diff --git a/.agents/skills/brainstorming/SKILL.md b/.agents/skills/brainstorming/SKILL.md index 8b0dff1..2544962 100644 --- a/.agents/skills/brainstorming/SKILL.md +++ b/.agents/skills/brainstorming/SKILL.md @@ -10,7 +10,7 @@ description: Use when receiving an ambiguous feature request, when scope is uncl 把模糊需求通过"一次一个问题"的方式，收敛成一份可用于 `writing-plans` 的设计规格。 -在完成规格并拿到用户批准之前，**不得**调用 `writing-plans`、不得动任何源文件、不得派 subagent 执行实现。 +在完成规格并拿到用户批准之前，**不得**调用 `writing-plans`、不得动任何源文件、不得开始实施。 逃生条款：用户明确说 "skip brainstorming"、"已经有规格"、"直接按 X 做" 时可跳过。 @@ -41,7 +41,7 @@ description: Use when receiving an ambiguous feature request, when scope is uncl 5. **写规格文档** — 保存到 `docs/specs/YYYY-MM-DD-.md` 6. **规格自查** — 有无占位符 `TODO`、有无自相矛盾、范围是否闭合 7. **请用户审阅规格文件** — 等明确 "OK/确认/继续" -8. **移交** — 规格确认后回到主流程（Read relevant docs → Planning Gate），由 Planning Gate 统一判定是否需要 plan +8. **移交** — 规格确认后回到主流程（Read relevant docs → 判定影响面），统一判定是否需要 plan ## Process Flow @@ -73,7 +73,7 @@ Self-review (placeholders / contradictions / scope) User reviews spec file ── approved? ─NO→ revise │ YES ▼ -回到主流程 → Read relevant docs → Planning Gate（统一判定） +回到主流程 → Read relevant docs → 影响面判定（统一一次） ``` ## Anti-Pattern：「这个需求太简单不需要规格」 @@ -105,7 +105,7 @@ User reviews spec file ── approved? ─NO→ revise brainstorming 收敛规格并拿到用户确认后，**不自行判定影响面**，直接回到主流程： ``` -规格确认 → Read relevant docs → Planning Gate（统一判定） +规格确认 → Read relevant docs → 影响面判定（统一一次） ``` -影响面判定权归 Planning Gate 一处（`using-growingio-sdk-skills` meta-skill），brainstorming 不重复判定、不自行分叉。 +影响面判定（改动文件 ≥3 或涉及公开 API 变更 → 先写 plan）在规格确认之后统一做一次，brainstorming 不重复判定、不自行分叉。 diff --git a/.agents/skills/finishing-a-development-branch/SKILL.md b/.agents/skills/finishing-a-development-branch/SKILL.md index 300fa9d..6a5956e 100644 --- a/.agents/skills/finishing-a-development-branch/SKILL.md +++ b/.agents/skills/finishing-a-development-branch/SKILL.md @@ -17,7 +17,7 @@ description: Use after verification-before-completion passes and code review is **强制：** - `verification-before-completion` skill 通过后 -- `sdk-code-review` skill 通过后 +- 对照 `docs/sdk-review-checklist.md` 自查通过后 - 用户说"这个功能做完了" / "收个尾" / "合并吧" **不触发：** @@ -153,7 +153,7 @@ git push origin --delete | "发版分支忘了打 tag 也没事" | 丢失版本追溯能力，补 tag 需要 cherry-pick 成本 | | "改动都 commit 了，用 `git add -A` 一把梭" | 容易把 .env / 密钥 / 构建产物带进去 | | "合并完分支保留吧以后说不定还用" | 仓库分支列表会膨胀；真要用再 checkout commit | -| "没触发 Planning Gate 就不用走收尾" | 只要有 commit 产生就应该走本 skill，小改动可以跳过 PR 但不能跳过用户确认 | +| "改动小、没写 plan 就不用走收尾" | 只要有 commit 产生就应该走本 skill，小改动可以跳过 PR 但不能跳过用户确认 | ## Red Flags — STOP if you catch yourself thinking these @@ -164,7 +164,7 @@ git push origin --delete ## 关联 skill -- **上游触发：** `verification-before-completion` 通过且 `sdk-code-review` 通过 -- **调度 subagent：** 无（本 skill 由控制器执行，用户决策哪条路径） +- **上游触发：** `verification-before-completion` 通过，且 `docs/sdk-review-checklist.md` 自查通过 +- **决策方：** 用户决定走哪条终态路径 - **完成后交接：** 合并到 master / PR 待评审 / 分支保留 / 分支废弃 四种终态之一 - **替代路径：** 发版分支 → 调用 `jira-ticket`（发版单） + `ohpm-publish`（OHPM 发布） + `git-conventions`（tag 命名） diff --git a/.agents/skills/git-conventions/SKILL.md b/.agents/skills/git-conventions/SKILL.md index fb433d4..18a62cc 100644 --- a/.agents/skills/git-conventions/SKILL.md +++ b/.agents/skills/git-conventions/SKILL.md @@ -200,6 +200,6 @@ git commit -m "chore: upgrade build dependencies" ## 关联 skill - **上游触发：** 执行 `git commit` / `git push` / 创建分支 / 写 PR 标题时 -- **调度 subagent：** 无（本 skill 是参考手册，由执行者自己应用） +- **使用方式：** 本 skill 是参考手册，由执行者自己应用 - **完成后交接：** `finishing-a-development-branch`（分支收尾流程会引用本 skill 的 commit/tag/PR 规范） - **替代路径：** 无——所有 git 操作都应遵循本规范 diff --git a/.agents/skills/growingio-arkts-coding-style/SKILL.md b/.agents/skills/growingio-arkts-coding-style/SKILL.md index f1e743a..42b3344 100644 --- a/.agents/skills/growingio-arkts-coding-style/SKILL.md +++ b/.agents/skills/growingio-arkts-coding-style/SKILL.md @@ -391,6 +391,6 @@ import { LogUtil } from '../utils/LogUtil' ## 关联 skill - **上游触发：** 写或审查任何 `.ets` / `.ts` 文件时 -- **调度 subagent：** 无（本 skill 是规范手册，由编码者/审查者自己对照） -- **完成后交接：** `sdk-code-review` 的 code-reviewer subagent 必须用本 skill 的约束清单做审查 +- **使用方式：** 本 skill 是规范手册，由编码者/审查者自己对照 +- **完成后交接：** 审查阶段按 `docs/sdk-review-checklist.md` Part 1 第 1 项，用本 skill 的约束清单逐条核对 - **替代路径：** 遇到 TypeScript 代码需迁移 → 交叉参考 `docs/typescript-to-arkts-migration-guide.md` diff --git a/.agents/skills/jira-ticket/SKILL.md b/.agents/skills/jira-ticket/SKILL.md index 8dbae23..06c8c50 100644 --- a/.agents/skills/jira-ticket/SKILL.md +++ b/.agents/skills/jira-ticket/SKILL.md @@ -46,6 +46,6 @@ jira-ticket release create --yes # 跳过确认 ## 关联 skill - **上游触发：** 准备发版（版本号确定后、`ohpm-publish` 之前） -- **调度 subagent：** 无（命令行工具，直接执行） +- **使用方式：** 命令行工具，直接执行 - **完成后交接：** `ohpm-publish` 发布 HAR → 发版完成后回到 ticket 更新状态 - **替代路径：** 已有发版 ticket → 跳过本 skill，直接进入 ohpm-publish diff --git a/.agents/skills/ohpm-publish/SKILL.md b/.agents/skills/ohpm-publish/SKILL.md index 8556bf3..2a6e6c3 100644 --- a/.agents/skills/ohpm-publish/SKILL.md +++ b/.agents/skills/ohpm-publish/SKILL.md @@ -137,6 +137,6 @@ ohpm publish GrowingToolsKit/build/default/outputs/default/GrowingToolsKit-signe ## 关联 skill - **上游触发：** 用户明确说"发布 SDK" / "ohpm 发布" / "发版" 等关键词 -- **调度 subagent：** 无（本 skill 是操作手册，由执行者按步骤执行） +- **使用方式：** 本 skill 是操作手册，由执行者按步骤执行 - **完成后交接：** `finishing-a-development-branch`（发版分支的打 tag / PR / 合并） + `jira-ticket`（同步更新发版单） - **替代路径：** 预发布验证阶段 → 只构建 HAR 不 publish（验证构建链路） diff --git a/.agents/skills/plan-document-review/SKILL.md b/.agents/skills/plan-document-review/SKILL.md deleted file mode 100644 index 3f29ec0..0000000 --- a/.agents/skills/plan-document-review/SKILL.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -name: plan-document-review -description: Use after writing a plan document in docs/plans/, before requesting user confirmation ---- - -# Plan Document Review - -> **Type:** Technique | **Discipline:** Rigid - -在 Planning Gate 输出完规划文档后、请求用户确认前，dispatch 一个 plan reviewer subagent 审查规划本身的质量。这一层审查能堵住"格式正确但内容不到位"的规划漏过 gate 的问题。 - -**核心原则：** plan 是实施的蓝本，蓝本有洞 = 实施有洞。审查 plan 本身比后期返工便宜得多。 - -## 何时触发 - -**强制：** Planning Gate 保存完 plan 到 `docs/plans/` 之后、提示用户确认之前。 - -**可跳过：** Planning Gate 未触发的小改动（< 3 文件且不涉及公开 API）。 - -## 调度方式 - -Plan reviewer 用 `general-purpose` subagent 身份 + prompt 模板实现（不需要专门 agent 定义）。它通过 `AGENTS.md` 的 `@import docs/sdk-engineering-guide.md` 自动继承领域知识。 - -``` -Agent({ - description: "Review plan document", - subagent_type: "general-purpose", - prompt: ` -你是 GrowingIO HarmonyOS SDK 的规划审查员。验证以下规划是否完备、可实施。 - -## 待审查规划 - -文件路径：{PLAN_FILE_PATH} - -规划全文（已粘贴，不用再读）： - ---- -{PLAN_FULL_TEXT} ---- - -## 原始需求 / 任务描述 - -{ORIGINAL_TASK_DESCRIPTION} - -## 检查维度 - -### 1. 四节完整性 - -规划必须包含以下四节，缺一不可： -- [ ] 影响文件列表 -- [ ] 公开 API 变更 -- [ ] 数据协议变更 -- [ ] 需同步修改的文档 - -### 2. 影响文件列表准确性 - -- 文件路径是否真实存在（或合理的新建路径）？ -- 是否有明显遗漏的文件？举例： - - 新增公开 API 但没列 \`GrowingAnalytics/Index.ets\` / \`GrowingAnalytics/obfuscation-rules.txt\` - - 修改事件字段但没列对应的 EventBuilder / 测试文件 - - 修改某模块但没列相关的单元测试文件 -- 有没有列了但实际不需要改的文件（scope creep）？ - -### 3. 公开 API 变更一致性 - -- 如果变更类型是"新增/修改/删除"，是否在"影响文件列表"中包含了 \`index.ets\` 和 \`obfuscation-rules.txt\`？ -- 如果是新增/修改，签名是否完整（参数类型、返回类型、泛型）？ -- 如果是删除/重命名，是否考虑了兼容性（deprecated 标注、迁移指南）？ - -### 4. 数据协议变更覆盖 - -- 涉及字段变更时，"影响产品线"列是否完整？SaaS/NewSaaS/CDP 三种模式的字段要求不同 -- 是否有潜在被遗漏的产品线？ -- 字段类型是否与 Android/iOS SDK 对齐（如果跨端）？ -- 如果涉及 Protobuf schema，是否同步更新了 .proto 文件？ - -### 5. 文档同步完整性 - -- 公开 API 变更是否在"需同步修改的文档"中列了 \`docs/GrowingAnalytics/interfaces/*.md\`？ -- 涉及核心模块改动是否列了对应的 \`docs/GrowingAnalytics//*.md\`？ -- 涉及 SaaS/NewSaaS 模式差异是否列了 README_SaaS.md？ - -### 6. 任务拆分质量（如涉及 subagent-driven-development） - -如果规划包含多个任务： -- 任务是否大部分相互独立（适合 subagent 并行执行）？ -- 任务粒度是否合理（不要太大以至于超过 subagent 承载，也不要太小以至于调度开销 > 实施成本）？ -- 任务依赖关系是否清晰（哪些任务必须先做）？ - -### 7. 场景覆盖 - -常见场景遗漏： -- **autotrack 改动**：是否考虑了 Hybrid/Flutter/Native 三种场景？SaaS 模式不支持无埋点，是否需要在 SaaS 模式下跳过？ -- **session 改动**：是否考虑了前台/后台/APP_CLOSED 三种触发时机？ -- **事件改动**：是否考虑了 Protobuf / JSON 双格式？是否考虑了 compressEnabled / encryptEnabled 开关影响？ -- **Config 改动**：是否考虑了三种工厂模式（NewSaaS/SaaS/CDP）的默认值差异？ - -## 输出格式 - -### 问题 - -#### Critical（必须修复，阻塞 plan 通过） -- [问题描述] - -#### Important（应当修复，建议修复后再请求用户确认） -- [问题描述] - -#### Suggestion（建议优化，不阻塞） -- [问题描述] - -（无问题时写"无"） - -### 检查清单 - -- [ ] 四节完整 -- [ ] 影响文件列表准确无遗漏 -- [ ] 公开 API 变更一致（同步 index.ets 和 obfuscation-rules.txt） -- [ ] 数据协议变更产品线完整 -- [ ] 文档同步列表完整 -- [ ] 任务拆分合理（如多任务） -- [ ] 场景覆盖完整 - -### 结论 - -**通过** / **需要修改** / **需要讨论** - -## 审查原则 - -- 具体到位：每个问题指向 plan 中的具体段落或条目 -- 不做表演式认同 -- 发现规划本身的缺陷（不是格式，而是思考漏洞）要明确指出 -- 如果任务描述本身模糊，建议先澄清需求而非强行过 plan -` -}) -``` - -## 占位符说明 - -| 占位符 | 来源 | -|--------|------| -| `{PLAN_FILE_PATH}` | 刚保存的 plan 文件路径 | -| `{PLAN_FULL_TEXT}` | plan 文件的完整内容（粘贴全文，不让 reviewer 读文件） | -| `{ORIGINAL_TASK_DESCRIPTION}` | 用户原始需求描述或任务背景 | - -## 处理审查结果 - -``` -reviewer 返回结果 - ↓ -判断结论 - ├── "通过" → 向用户展示 plan + reviewer 摘要，请求确认 - ├── "需要修改" - │ ├── Critical → 修改 plan 文件，重新 dispatch reviewer（计第 N 轮） - │ └── Important → 修改 plan 文件，重新 dispatch reviewer（计第 N 轮） - │ （Suggestion 可记录，不阻塞） - │ - │ ⚠️ 如果第 2 轮后仍有 Critical/Important： - │ → 停止循环，向用户说明"plan 已两轮审查仍有问题，需要讨论" - │ → 不再盲目循环 - │ - └── "需要讨论" → 向用户说明疑虑，讨论后决定 -``` - -**不要向用户隐藏审查结果。** 即使通过，也在请求用户确认时附上 reviewer 的摘要（如"plan reviewer 通过，无 Critical/Important 问题"），让用户知道 plan 经过了独立审查。 - -## Rationalizations - -| Excuse | Reality | -|---|---| -| "自己写的 plan 自己审就行" | 自审替代不了独立审查，reviewer 是新鲜 context | -| "跳过 reviewer 直接请求用户确认" | Planning Gate 的独立审查是硬性流程的一部分，不是可选步骤 | -| "reviewer 说 Important 我觉得是 Suggestion" | 可以 push back，但要有技术理由，不是感觉 | -| "修完 Critical 不用重新 dispatch" | 必须重新 dispatch，不可自判"已修好" | -| "审了两轮还有问题就先过吧" | 第 2 轮后仍有 Critical/Important → 停下讨论，不盲目循环 | - -## Red Flags — STOP if you catch yourself thinking these - -- "这个 plan 我自己写的，内容肯定没问题" → 自审盲区是最大的漏洞来源 -- "直接给用户看吧，省掉 reviewer 这一步" → 独立审查是硬性流程，不是可选优化 -- "修完 Critical 了，不用重新 dispatch 了" → 自判"已修好" = 赌博 - -## 关联 skill - -- **上游触发：** `writing-plans` 产出 plan 文件后、请求用户确认前 -- **调度 subagent：** `general-purpose` subagent（本 skill 内嵌 prompt 模板，不需专门 agent） -- **完成后交接：** 通过 → 向用户展示 plan + reviewer 摘要请求确认 → 进入实施 -- **替代路径：** 未触发 Planning Gate 的小改动 → 不走本 skill diff --git a/.agents/skills/receiving-code-review/SKILL.md b/.agents/skills/receiving-code-review/SKILL.md deleted file mode 100644 index 7347347..0000000 --- a/.agents/skills/receiving-code-review/SKILL.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -name: receiving-code-review -description: Use when receiving feedback from code-reviewer subagent or human reviewer ---- - -# 接收代码审查反馈 - -> **Type:** Technique | **Discipline:** Rigid - -收到 code-reviewer subagent 或人类 reviewer 的反馈后，按本技能规范处理。核心原则：**验证先于实施，澄清先于假设，技术正确性高于社交舒适度。** - -## 响应模式 - -``` -收到审查反馈 - ↓ -1. READ：完整读完所有反馈，不急于行动 -2. UNDERSTAND：用自己的话复述每条要求（或提问） -3. VERIFY：对照代码库现状核实 -4. EVALUATE：对本项目是否技术合理？ -5. RESPOND：技术性确认或有理据的 push back -6. IMPLEMENT：逐条修复，每条单独测试 -``` - -## STOP-ASK 模式 - -``` -如果反馈中任何一项不明确： - → 全部暂停，不实施任何一项 - → 先对不明确的项提问澄清 - → 澄清完毕后再开始实施 - -原因：各项可能相互关联，部分理解 = 错误实施。 -``` - -**示例：** -``` -reviewer 返回 6 条问题，你理解 1、2、3、6，不确定 4、5。 - -❌ 错误：先改 1、2、3、6，回头再问 4、5 -✅ 正确："第 1、2、3、6 条已理解。第 4 条和第 5 条需要澄清： - - 第 4 条提到 'session 边界处理'，是指 onForeground 还是 VISIT 事件？ - - 第 5 条 '协议对齐'，具体是哪个字段？" -``` - -## 反馈来源分级 - -### 来自 code-reviewer subagent - -``` -实施前逐条验证： - 1. 对本代码库技术上正确吗？ - 2. 会破坏已有功能吗？ - 3. 当前实现是否有特殊原因？ - 4. 是否适用于所有产品线（SaaS/NewSaaS/CDP）？ - 5. reviewer 是否掌握了完整上下文？ - -如果建议有误： - → 用技术理由 push back，不盲目接受 - -如果无法验证： - → 明确说"我无法验证这一点，需要 [X] 才能确认。是否继续？" - -如果与用户之前的架构决策冲突： - → 暂停，先与用户确认 -``` - -### 来自用户（人类） - -- 信任度更高，理解后直接实施 -- 范围不清时仍然要问 -- 不做表演式认同，直接行动或技术性确认 - -## YAGNI 检查 - -``` -当 reviewer 建议"实现得更完善"时： - → 先 grep 代码库确认是否有实际调用 - - 如果没有调用："这个接口当前没有调用方，是否需要实现？（YAGNI）" - 如果有调用：按建议实现 -``` - -## 禁止行为 - -**绝不说：** -- "你说得对！" / "好建议！" / "非常好的反馈！" -- "让我立刻实现" （在验证之前） - -**应该说：** -- "已修复。[简述改了什么]" -- "确认是个问题——[具体原因]。已在 `file:line` 修复。" -- 或者直接修复，不多说。 - -## 何时 Push Back - -**应该 push back 的情况：** -- 建议会破坏已有功能 -- reviewer 缺少完整上下文 -- 违反 YAGNI（功能无实际调用） -- 对本技术栈不适用 -- 存在兼容性/历史原因 -- 与用户的架构决策冲突 - -**如何 push back：** -- 给出技术理由，不带防御性 -- 提出具体的反例或引用已有测试 -- 如涉及架构层面，建议升级给用户决策 - -## 被证明 push back 有误时 - -``` -✅ "你是对的——我验证了 [X]，确实 [Y]。正在修复。" - -❌ 长篇道歉 -❌ 解释为什么当时 push back -``` - -陈述事实，继续工作。 - -## 实施顺序 - -``` -多条反馈的处理顺序： - 1. 先澄清所有不明确的项（STOP-ASK） - 2. 按以下优先级实施： - a. Critical（阻塞项：崩溃、数据丢失、隐私泄露） - b. 简单修复（拼写、导入、格式） - c. 复杂修复（重构、逻辑变更） - 3. 每条修复后单独验证 - 4. 全部完成后确认无回归 -``` - -## 常见错误 - -| 错误 | 纠正 | -|------|------| -| 表演式认同 | 直接修复或给出技术性回应 | -| 不验证就实施 | 先对照代码库核实 | -| 批量修改不测试 | 逐条修复，逐条验证 | -| 假定 reviewer 一定对 | 检查是否会破坏现有功能 | -| 回避 push back | 技术正确性 > 社交舒适度 | -| 部分理解就开始改 | STOP-ASK，先澄清所有不明确项 | -| 无法验证仍然继续 | 明确说出局限，请求指导 | - -## Rationalizations - -| Excuse | Reality | -|---|---| -| "reviewer 说的有理，全盘接受避免冲突" | 表演式认同是失职；正确的反应是修复或给技术反驳 | -| "reviewer 这条我觉得不对，忽略就行" | 必须 push back 并给技术理由，不是沉默不处理 | -| "改完了不用重新 dispatch，reviewer 不会再挑出新问题" | Critical/Important 修完必须重新 review，不可自判 | -| "先改 Critical，Important 合并前再说" | Important 也阻塞合并，只有 Suggestion 可延后 | -| "一次把所有意见全改完再验证" | 批量修改后一个点崩了定位困难，逐条修复逐条验证 | -| "部分听懂了就开始改" | 不明确项必须 STOP-ASK，改错的成本高于问一句 | -| "我改得很小，不用重跑 verify" | 任何修改后 verify 都要重跑——这是 `verification-before-completion` 的不变量 | -| "改完 reviewer 一定会通过，不用重新 dispatch 了" | Critical/Important 修完必须重新 review，自判=赌博 | - -## Red Flags — STOP if you catch yourself thinking these - -- "reviewer 说得对！让我立刻实现" → 表演式认同，先验证再行动 -- "这条反馈我不同意，跳过" → 必须 push back 并给技术理由，沉默 ≠ 处理 -- "部分理解了就先改能改的" → STOP-ASK，各项可能相互关联，部分理解 = 错误实施 -- "改完了不用重新 dispatch 了" → Critical/Important 修完必须重新 review，自判 = 赌博 -- "改动很小，不用重跑 verify" → 任何修改后 verify 都要重跑，这是不变量 - -## 下游 / loop-back（HARD RULE） - -反馈项全部实施完成后，**必须**按以下顺序走完回路，不得自行判定"改好了"： - -1. **回到同一个 reviewer 复审**（不是新 reviewer，避免上下文丢失） - - 直接实施路径：重新 dispatch `sdk-code-review` 的同一 reviewer 角色 - - SDD 路径：由 SDD 控制器重派 spec-reviewer（若 spec 未过）或 code-reviewer（若 spec 已过） -2. **所有项通过后** → `verification-before-completion` 重跑（修复可能破坏既有验证，不重跑就是赌博） -3. **verify 通过** → 回到主流程（继续下一任务 / `finishing-a-development-branch`） - -## 关联 skill - -- **上游触发：** 收到 `sdk-code-review` 的 reviewer subagent 或人类 reviewer 反馈 -- **调度 subagent：** 无（本 skill 由实施者执行处理反馈） -- **完成后交接：** 见上方「下游 / loop-back」 -- **替代路径：** push back 有据且 reviewer 撤回该条 → 该条无需修改；其他条仍需按 loop-back 流程走 diff --git a/.agents/skills/sdk-code-review/SKILL.md b/.agents/skills/sdk-code-review/SKILL.md deleted file mode 100644 index 5911b11..0000000 --- a/.agents/skills/sdk-code-review/SKILL.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: sdk-code-review -description: Use when a feature, bugfix, or refactoring step is completed and needs review, or before merging to main, or when user says "review", "审查", "帮我看看代码" ---- - -# SDK 代码审查 - -> **Type:** Technique | **Discipline:** Rigid - -dispatch 审查 subagent 对已完成的工作进行独立审查。审查者不继承当前会话历史——你负责构造它需要的全部上下文。 - -## 何时触发 - -**强制：** -- 触发了 Planning Gate 的改动完成后 -- 涉及公开 API 变更的改动完成后 -- 合并到 master 之前 -- subagent-driven-development 全部任务完成后的全局审查 - -**可选但推荐：** -- 修复复杂 bug 后 -- 重构后 -- 卡住时（换个独立视角） - -## 审查模式选择 - -### 决策图 - -``` -工作完成，需要审查? - │ - ▼ -有 plan 文件对应本次改动? - ├─ YES → 模式 A：完整审查（spec-reviewer → code-reviewer） - │ - └─ NO → 变更文件 ≤ 5 且不涉及公开 API? - ├─ YES → 模式 B：独立审查（仅 code-reviewer） - └─ NO → 回退去补 plan（writing-plans），再走模式 A - -审查者返回结果 - ├─ 通过 → verification-before-completion - ├─ 需要修改 → 修复 → 重新 dispatch 同审查者（不可自行判断"已修好"） - └─ 需要讨论 → receiving-code-review skill 处理 push back -``` - -### 模式 A：完整审查（有 plan 的改动） - -dispatch 两个独立审查者，**顺序执行**： - -1. **规格合规审查**：dispatch `spec-reviewer` subagent - - 通过 → 进入步骤 2 - - 不通过 → 修复后重新 dispatch spec-reviewer - - 需要讨论 → 与用户讨论后决定 - -2. **代码质量审查**：dispatch `code-reviewer` subagent - - 通过 → 审查完成 - - 需要修改 → 修复后重新 dispatch code-reviewer - - 需要讨论 → 与用户讨论后决定 - -### 模式 B：独立审查（无 plan 的改动） - -满足以下**全部**条件时，只 dispatch `code-reviewer` 一次： -- 无对应 plan 文件 -- 变更文件 ≤ 5 个 -- 不涉及公开 API 变更 - -## 调度步骤 - -### 1. 确定变更范围 - -根据触发场景选择正确的 BASE_SHA： - -**场景 A：合并到 master 之前（review 整个功能分支）** - -```bash -# 用 merge-base 找到分支与 master 的分叉点 -BASE_SHA=$(git merge-base HEAD master) -HEAD_SHA=$(git rev-parse HEAD) -``` - -**场景 B：单个任务完成后（subagent-driven-development 中的任务级审查）** - -```bash -# BASE_SHA 在 dispatch 实现者 subagent 前记录，HEAD_SHA 在实现者提交后记录 -# 具体做法见 subagent-driven-development skill -``` - -**场景 C：当前工作区未提交的改动** - -```bash -BASE_SHA=$(git rev-parse HEAD) -# HEAD_SHA 不适用；让审查者用 git diff HEAD 查看未暂存 + 已暂存的改动 -``` - -```bash -# 查看变更文件列表 -git diff --name-only $BASE_SHA..$HEAD_SHA - -# 查看完整 diff -git diff $BASE_SHA..$HEAD_SHA -``` - -### 2. Dispatch 审查者 - -**dispatch spec-reviewer 时，必须提供：** - -| 字段 | 说明 | 示例 | -|------|------|------| -| **变更内容** | 本次完成了什么 | "新增 onPageEnd API" | -| **规格/规划** | plan 全文或任务描述全文 | 粘贴 plan 内容 | -| **实现者报告** | 实现者的完成报告（如有） | 粘贴报告 | -| **BASE_SHA** | 变更起始 commit | `a7981ec` | -| **HEAD_SHA** | 变更结束 commit | `3df7661` | -| **变更文件列表** | `git diff --name-only` 的输出 | 文件列表 | - -**dispatch code-reviewer 时，必须提供：** - -| 字段 | 说明 | 示例 | -|------|------|------| -| **变更内容** | 本次完成了什么 | "新增 onPageEnd API" | -| **对应规划** | plan 文件路径（供参考） | `docs/plans/2026-04-10-on-page-end.md` | -| **BASE_SHA** | 变更起始 commit | `a7981ec` | -| **HEAD_SHA** | 变更结束 commit | `3df7661` | -| **变更文件列表** | `git diff --name-only` 的输出 | 文件列表 | - -> **Special case**：若变更文件列表包含 `.agents/` 或 `.claude/` 路径，在 dispatch 时显式注明： -> "本次变更包含 skill/agent 配置文件，请额外执行维度 7（Skill/Agent 架构一致性）检查。" - -### 3. 处理审查结果 - -按 `receiving-code-review` skill 的规范处理反馈。核心流程： - -``` -审查者返回结果 - ↓ -判断结论 - ├── "通过" / "合规" → 继续后续工作 - ├── "需要修改" / "不合规" - │ ├── Critical → 立即修复，修完后重新 dispatch 同审查者 - │ ├── Important → 合并前修复 - │ └── Suggestion → 记录，可后续处理 - └── "需要讨论" → 与用户讨论后决定 -``` - -**处理原则：** -- Critical 和 Important 修复后，**必须重新 dispatch review**，不可自行判断已修好 -- 如果认为审查者判断有误，用技术理由 push back（参见 `receiving-code-review` skill） -- 不做表演式认同，直接修复或给出技术反驳 - -## Rationalizations - -| Excuse | Reality | -|---|---| -| "改动小，跳过审查吧" | 模式 B 已经是最轻量路径，再跳就是裸奔 | -| "我自己看过一遍没问题" | 自审替代不了独立审查，上下文污染 | -| "先做质量审查，规格审查之后补" | 顺序不可颠倒——实现不合规时做质量审查是浪费 | -| "reviewer 说 Important，我觉得是 Suggestion" | 可以 push back，但要有技术理由，不是感觉 | -| "改完了，直接声明通过" | Critical/Important 修复后必须重新 dispatch，不可自判 | - -## Red Flags — STOP if you catch yourself thinking these - -- "这个改动太小了不需要审查" → 模式 B 就是为小改动设计的，再跳 = 裸奔 -- "我自己检查过了，没问题" → 自审替代不了独立审查，你有上下文盲区 -- "先跑质量审查，spec review 后面补" → 顺序不可颠倒，规格不合规时质量审查是浪费 -- "修完 Critical 了，不用重新 dispatch reviewer" → 必须重新 dispatch，自判 = 赌博 - -## 关联 skill - -- **上游触发：** - - `subagent-driven-development` 每任务完成后 + 全部完成后的全局审查 - - 手动实施完成后，触发 Planning Gate 的改动必须走模式 A - - 准备合并到 master 前强制触发 -- **调度 subagent：** - - `spec-reviewer` agent（`.claude/agents/spec-reviewer.md`）— 模式 A 第一阶段 - - `code-reviewer` agent（`.claude/agents/code-reviewer.md`）— 模式 A 第二阶段 / 模式 B 唯一审查者 -- **完成后交接：** 通过 → `verification-before-completion` → `finishing-a-development-branch` -- **处理反馈：** `receiving-code-review` 的 STOP-ASK / YAGNI / push back 规范 -- **替代路径：** 仅修改文档/配置且无 SDK 行为影响 → 跳过本 skill diff --git a/.agents/skills/subagent-driven-development/SKILL.md b/.agents/skills/subagent-driven-development/SKILL.md deleted file mode 100644 index 5b407ec..0000000 --- a/.agents/skills/subagent-driven-development/SKILL.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -name: subagent-driven-development -description: Use when executing an implementation plan with 3+ independent tasks in the current session ---- - -# Subagent-Driven Development - -> **Type:** Technique | **Discipline:** Rigid - -通过 dispatch 独立 subagent 执行 plan 中的每个任务，每个任务完成后进行两阶段审查（规格合规 → 代码质量）。 - -**为什么用 subagent：** 你是控制器，负责调度和协调。将实现任务委派给独立 subagent，每个 subagent 有隔离的上下文。你精心构造它们需要的指令和上下文，确保它们专注完成任务。它们不继承你的会话历史——你构造它们需要的一切。这也保护了你自己的上下文窗口用于协调工作。 - -**核心原则：** 每任务一个新鲜 subagent + 两阶段审查（规格 → 质量）= 高质量、快迭代 - -## 何时使用 - -### 决策图 - -``` -有 plan 文件? - ├─ NO → writing-plans 先产出 plan（或判断是否应该手动实施） - └─ YES → 任务数 ≥ 3 且任务大部分独立? - ├─ NO → 手动实施（模式 B）+ 按 sdk-code-review 流程审查 - └─ YES → 希望留在当前会话连续执行? - ├─ NO → 改用手动实施 + 完整审查 - └─ YES → 本 skill（subagent-driven-development） -``` - -### 使用条件（全部满足） - -- 有实施规划（plan 文件存在于 `docs/plans/`） -- 任务 ≥ 3 个且大部分相互独立 -- 希望在当前会话中连续执行（不切换会话） - -### 不适用时 - -- 无 plan → 先走 `writing-plans` → `plan-document-review` 产出合规 plan -- 任务紧密耦合 → 手动实施，避免 subagent 间相互阻塞 -- 只有 1-2 个简单改动 → 直接改，不需要这个流程 - -## 流程 - -``` -读取 plan，提取所有任务全文 - ↓ -[Per Task] - ↓ -记录 BASE_SHA - ↓ -Dispatch 实现者 subagent（./implementer-prompt.md） - ↓ -实现者提问？ ──yes──→ 回答问题 → 重新 dispatch - │no - ↓ -实现者实现、测试、提交、自审 - ↓ -返回状态（见"处理实现者状态"） - ↓ -记录 HEAD_SHA - ↓ -Dispatch 规格审查者 subagent（./spec-reviewer-prompt.md） - ↓ -规格合规？ ──no──→ 实现者修复 → 重新规格审查 - │yes - ↓ -Dispatch 质量审查者 subagent（./code-quality-reviewer-prompt.md） - ↓ -质量通过？ ──no──→ 实现者修复 → 重新质量审查 - │yes - ↓ -标记任务完成 - ↓ -[/Per Task] - ↓ -更多任务？ ──yes──→ 下一个任务 - │no - ↓ -Dispatch 全局 code-reviewer（sdk-code-review skill） - ↓ -全局审查通过？ ──no──→ receiving-code-review → 修复 → 重新全局审查 - │yes - ↓ -verification-before-completion - ↓ -finishing-a-development-branch ← 终态 -``` - -## 模型选择 - -用能胜任的最轻量模型，节省成本和时间。 - -**机械实现任务**（独立函数、清晰规格、1-2 文件）：用 `haiku`。规划明确时大多数 SDK 实现任务属于此类。 - -**集成和判断任务**（多文件协调、模式匹配、调试）：用 `sonnet`。 - -**架构、设计和审查任务**：用 `opus`。 - -**判断依据：** -- 改 1-2 个文件 + 完整规格 → `haiku` -- 改多个文件 + 有集成逻辑 → `sonnet` -- 需要设计判断或全局理解 → `opus` - -## 处理实现者状态 - -实现者 subagent 返回四种状态之一： - -**DONE：** 进入规格合规审查。 - -**DONE_WITH_CONCERNS：** 实现者完成了但标记了疑虑。先读疑虑再决定： -- 正确性 / 范围问题 → 解决后再审查 -- 观察性备注（如"这个文件越来越大"）→ 记录后继续审查 - -**NEEDS_CONTEXT：** 实现者缺少必要信息。补充上下文，重新 dispatch。 - -**BLOCKED：** 实现者无法完成。评估阻塞原因： -1. 上下文不足 → 提供更多上下文，同模型重新 dispatch -2. 任务需要更强推理 → 用更强模型重新 dispatch -3. 任务太大 → 拆成更小的子任务 -4. plan 本身有问题 → 升级给用户 - -**绝不**忽略升级信号或让同一模型无变化地重试。实现者说卡住了，就是有东西需要改变。 - -## Prompt 模板 - -- `./implementer-prompt.md` — dispatch 实现者 subagent -- `./spec-reviewer-prompt.md` — dispatch 规格合规审查 subagent -- `./code-quality-reviewer-prompt.md` — dispatch 代码质量审查 subagent - -## 上下文构造原则 - -**粘贴全文，不让 subagent 读文件：** -- 任务描述：从 plan 中提取完整文本，粘贴到 prompt 中 -- 规格内容：粘贴 plan 相关章节，不给文件路径让 subagent 自己读 -- 减少 subagent 的文件读取开销，保证它拿到的信息是你筛选过的 - -**提供场景设置：** -- 这个任务在整体 plan 中的位置 -- 前序任务已完成了什么 -- 本任务与其他任务的依赖关系 -- 相关的已有代码文件路径 - -## 示例 - -``` -我使用 Subagent-Driven Development 执行这个 plan。 - -[读取 plan: docs/plans/2026-04-13-on-page-end.md] -[提取 3 个任务的完整文本] - -Task 1: 新增 onPageEnd 接口定义 - -BASE_SHA=$(git rev-parse HEAD) # a7981ec - -[Dispatch 实现者 subagent，model: haiku] - → 任务全文 + GrowingAnalyticsInterface 上下文 - -实现者："开始前有个问题——onPageEnd 的 attributes 参数是 AttributesType 还是 Record？" - -我："用 AttributesType，和 track() 保持一致。" - -[重新 dispatch 实现者] -实现者： - - 实现了 onPageEnd(pageName, attributes?) 接口 - - 更新了 obfuscation-rules.txt - - 自审：无遗漏 - - Status: DONE - -HEAD_SHA=$(git rev-parse HEAD) # 3df7661 - -[Dispatch 规格审查者] -规格审查者：✅ 合规 — 所有需求已实现，无多余工作 - -[Dispatch 质量审查者] -质量审查者：通过。Suggestion: 考虑给 pageName 加空字符串校验。 - -[标记 Task 1 完成] - -Task 2: 实现 Hybrid 模块中的 onPageEnd 逻辑 -... - -[所有任务完成后] -[Dispatch 全局 code-reviewer（通过 sdk-code-review skill）] -全局审查：通过，可合并。 - -完成！ -``` - -## 红线 - -**绝不：** -- 跳过审查（规格审查和质量审查都不可跳过） -- 带着未修复的问题进入下一个任务 -- 并行 dispatch 多个实现者 subagent（会冲突） -- 让 subagent 自己读 plan 文件（提供全文） -- 省略场景设置上下文 -- 忽略实现者的提问（回答后再继续） -- 接受规格审查的"差不多"（有问题 = 没通过） -- 在规格审查通过前开始质量审查（顺序不可颠倒） -- 让实现者的自审替代正式审查（两者都需要） -- 自己手动修复代码（上下文污染）——dispatch 修复 subagent - -**如果实现者提问：** -- 清楚完整地回答 -- 按需提供额外上下文 -- 不要催它赶紧写代码 - -**如果审查者发现问题：** -- 实现者（同一个 subagent）修复 -- 审查者重新审查 -- 重复直到通过 -- 不跳过重新审查 - -**如果 subagent 失败：** -- dispatch 新的修复 subagent，给出具体指令 -- 不自己手动修（上下文污染） - -## Rationalizations - -| Excuse | Reality | -|---|---| -| "任务独立性我判断过了不用走 subagent" | 本 skill 的隔离是为了防 context 污染，不只是为了并行 | -| "一个 subagent 并行多任务能快" | 明确禁止——会冲突；一次只 dispatch 一个实现者 | -| "subagent 可以自己读 plan 文件" | 必须粘贴全文进 prompt，不让它读文件，避免 context 污染 | -| "自审过就不用 spec-reviewer 了" | 自审替代不了独立审查；两阶段都要走 | -| "spec-reviewer 有问题先质量审了，回头再改" | 顺序不可颠倒，规格不合规时做质量审查纯浪费 | -| "实现者报 BLOCKED 再让它用更强模型重试一次" | BLOCKED 必须更换上下文/模型/任务粒度；不允许无变化重试 | -| "reviewer 提了 Critical 我修了就不用重新 review 了" | 修完必须重新 dispatch 同审查者，不可自判 | - -## Red Flags — STOP if you catch yourself thinking these - -- "这个任务简单，我自己直接改比 dispatch subagent 快" → 你在找借口污染控制器上下文 -- "跳过 spec review，implementer 自审过了" → 自审替代不了独立审查，两阶段都要走 -- "并行 dispatch 两个 implementer 加速" → 明确禁止，文件冲突概率极高 -- "这个 bug 我自己顺手修一下" → 控制器不写代码，dispatch 修复 subagent - -## 关联 skill - -- **上游触发：** - - `writing-plans` 产出 plan 文件（前置） - - `plan-document-review` 通过独立审查（前置） -- **调度 subagent / Prompt 模板（本 skill 目录下）：** - - `./implementer-prompt.md` — 实现者 subagent 调度模板 - - `./spec-reviewer-prompt.md` — 规格合规审查 subagent 调度模板 - - `./code-quality-reviewer-prompt.md` — 代码质量审查 subagent 调度模板 -- **Subagent 内部遵循（嵌入在 prompt 中）：** - - `test-driven-development` — 核心路径走 Red-Green-Refactor - - `growingio-arkts-coding-style` — ArkTS 编码规范 - - `systematic-debugging` — 实现者遇错时的调试纪律 -- **完成后交接：** - - 全部任务完成 → `sdk-code-review`（全局审查） - - 审查反馈处理 → `receiving-code-review` - - 审查通过 → `verification-before-completion` → `finishing-a-development-branch` -- **替代路径：** 任务紧密耦合或 < 3 个 → 跳过本 skill，手动实施 + `sdk-code-review` 独立审查 diff --git a/.agents/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/.agents/skills/subagent-driven-development/code-quality-reviewer-prompt.md deleted file mode 100644 index 4be012e..0000000 --- a/.agents/skills/subagent-driven-development/code-quality-reviewer-prompt.md +++ /dev/null @@ -1,52 +0,0 @@ -# 质量审查者 Subagent Prompt 模板 - -**只在 spec reviewer 通过后才 dispatch。** - -``` -Agent({ - description: "Review code quality for Task N: {TASK_NAME}", - subagent_type: "GrowingIO SDK Code Reviewer", - prompt: ` -审查代码质量。 - -## 变更内容 - -{WHAT_WAS_IMPLEMENTED} - -## 对应规划 - -{PLAN_REFERENCE}（规格合规审查已通过） - -## Git 范围 - -BASE_SHA: {BASE_SHA} -HEAD_SHA: {HEAD_SHA} - -## 变更文件 - -{CHANGED_FILES_LIST} - -请按照你的审查步骤执行代码质量审查。 -` -}) -``` - -## 占位符说明 - -| 占位符 | 来源 | 说明 | -|--------|------|------| -| `{TASK_NAME}` | plan 中的任务标题 | 简短描述 | -| `{WHAT_WAS_IMPLEMENTED}` | 实现者报告摘要 | 简述实现了什么 | -| `{PLAN_REFERENCE}` | plan 文件路径 | 供 reviewer 参考上下文 | -| `{BASE_SHA}` | 任务开始前的 commit | 同 spec-reviewer-prompt | -| `{HEAD_SHA}` | 实现者完成后的 commit | 同 spec-reviewer-prompt | -| `{CHANGED_FILES_LIST}` | `git diff --name-only` 输出 | 帮 reviewer 快速定位 | - -## 额外检查项 - -除 code-reviewer agent 的标准维度外，质量审查者还应关注： - -- 每个文件是否职责单一、接口清晰？ -- 模块是否可以独立理解和测试？ -- 实现是否遵循了规划中的文件结构？ -- 本次变更是否创建了过大的新文件，或显著增长了已有文件？（不要标记已有文件的既存大小） diff --git a/.agents/skills/subagent-driven-development/implementer-prompt.md b/.agents/skills/subagent-driven-development/implementer-prompt.md deleted file mode 100644 index 2c939c8..0000000 --- a/.agents/skills/subagent-driven-development/implementer-prompt.md +++ /dev/null @@ -1,123 +0,0 @@ -# 实现者 Subagent Prompt 模板 - -dispatch 实现者 subagent 时，用此模板构造 prompt。将占位符替换为实际值。 - -``` -Agent({ - description: "Implement Task N: {TASK_NAME}", - subagent_type: "GrowingIO HarmonyOS SDK Engineer", - model: "{MODEL}", - prompt: ` -你正在实现任务：{TASK_NAME} - -## 任务描述 - -{TASK_FULL_TEXT} - -## 上下文 - -{SCENE_SETTING_CONTEXT} - -## 开始前 - -如果你对以下内容有疑问： -- 需求或验收标准 -- 实现方案或策略 -- 依赖关系或假设 -- 任务描述中任何不清楚的地方 - -**现在就问。** 在开始工作前提出所有疑虑。 - -## 你的工作 - -确认需求清楚后： -1. 按任务规格实现功能（写 .ets 代码前参考 `growingio-arkts-coding-style` skill 的约束表） -2. 编写测试（如任务要求）；如涉及核心路径（事件管道/存储/网络层），按 `test-driven-development` skill 遵循 Red-Green-Refactor 循环 -3. 按 `verification-before-completion` skill 的五步验证门验证实现正确 -4. 提交你的工作（commit message 按 `git-conventions` skill 规范生成） -5. 执行自审（见下方） -6. 报告结果 - -工作目录：{WORKING_DIRECTORY} - -**工作过程中：** -- 遇到意外或不清楚的情况 → **暂停并提问**，不要猜测或做假设 -- 遇到编译错误 / 构建失败 / 测试失败 → 按 `systematic-debugging` skill 的四阶段方法排查，不得随意猜测修改 - -## 角色约束 - -你已经是 GrowingIO HarmonyOS SDK Engineer，SDK 领域知识通过 CLAUDE.md 的 `docs/sdk-engineering-guide.md` 自动加载。**本次作为实现者，忽略 persona 中的 Planning Gate 和 Workflow Process**——这些是控制器的职责，你只负责执行本任务。 - -## 代码组织 - -- 遵循规划中定义的文件结构 -- 每个文件职责单一，接口清晰 -- 如果你创建的文件超出规划意图的规模，停止并报告 DONE_WITH_CONCERNS——不要自行拆分文件 -- 修改已有文件时，遵循已有模式。改善你接触的代码，但不要重构任务范围外的部分 - -## 能力边界 - -坦诚说"这对我来说太难了"永远没问题。交出垃圾代码比承认困难更糟。 - -**遇到以下情况时停止并升级：** -- 任务需要在多个有效方案间做架构决策 -- 需要理解提供范围之外的代码且无法找到答案 -- 不确定自己的方案是否正确 -- 任务涉及规划未预期的已有代码重构 -- 反复读文件试图理解系统但没有进展 - -**如何升级：** 报告 BLOCKED 或 NEEDS_CONTEXT 状态。具体描述卡在哪里、尝试了什么、需要什么帮助。 - -## 提交前：自审 - -以审查者的视角审视自己的工作： - -**完整性：** -- 规格中的所有要求都实现了吗？ -- 有没有遗漏的需求？ -- 有没有未处理的边界情况？ - -**质量：** -- 这是我能做到的最好水平吗？ -- 命名清晰准确吗？ -- 代码干净可维护吗？ - -**纪律：** -- 有没有过度构建（YAGNI）？ -- 是否只构建了被要求的东西？ -- 是否遵循了代码库已有的模式？ - -**SDK 特有：** -- 新增字段命名与 Android/iOS SDK 一致吗？ -- 新增采集字段需要 ignoreField 支持吗？ -- 公开 API 变更已加入 obfuscation-rules.txt 吗？ - -如果自审发现问题，现在就修复，不要留给审查者。 - -## 报告格式 - -完成后报告： -- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT -- 实现了什么（或如果被阻塞，尝试了什么） -- 测试内容和结果 -- 变更的文件列表 -- 自审发现（如有） -- 任何问题或疑虑 - -DONE_WITH_CONCERNS：完成了但对正确性有疑虑。 -BLOCKED：无法完成任务。 -NEEDS_CONTEXT：缺少必要信息。 -绝不要悄悄交付你自己都不确信的工作。 -` -}) -``` - -## 模型选择指引 - -| 任务特征 | 推荐模型 | 理由 | -|---------|---------|------| -| 1-2 文件、清晰规格、机械实现 | `haiku` | 不需要推理能力，省成本 | -| 多文件协调、集成逻辑 | `sonnet` | 需要一定理解力 | -| 架构决策、复杂重构 | `opus` | 需要判断力 | - -大多数 SDK 任务在规划明确时属于机械实现，优先用轻量模型。 diff --git a/.agents/skills/subagent-driven-development/spec-reviewer-prompt.md b/.agents/skills/subagent-driven-development/spec-reviewer-prompt.md deleted file mode 100644 index e419464..0000000 --- a/.agents/skills/subagent-driven-development/spec-reviewer-prompt.md +++ /dev/null @@ -1,47 +0,0 @@ -# 规格审查者 Subagent Prompt 模板 - -spec reviewer 通过后才能进入 code quality review。**顺序不可颠倒。** - -``` -Agent({ - description: "Review spec compliance for Task N: {TASK_NAME}", - subagent_type: "GrowingIO SDK Spec Reviewer", - prompt: ` -审查任务的规格合规性。 - -## 规格/规划 - -{TASK_REQUIREMENTS_OR_PLAN_FULL_TEXT} - -## 实现者报告 - -{IMPLEMENTER_REPORT} - -## Git 范围 - -BASE_SHA: {BASE_SHA} -HEAD_SHA: {HEAD_SHA} - -请运行以下命令查看变更： -git diff --stat {BASE_SHA}..{HEAD_SHA} -git diff {BASE_SHA}..{HEAD_SHA} - -## 变更文件 - -{CHANGED_FILES_LIST} - -请按照你的审查步骤执行规格合规审查。 -` -}) -``` - -## 占位符说明 - -| 占位符 | 来源 | 说明 | -|--------|------|------| -| `{TASK_NAME}` | plan 中的任务标题 | 简短描述 | -| `{TASK_REQUIREMENTS_OR_PLAN_FULL_TEXT}` | plan 文件完整内容或任务描述 | **粘贴全文，不让 reviewer 自己读文件** | -| `{IMPLEMENTER_REPORT}` | 实现者返回的报告 | 原样粘贴，reviewer 会独立验证而非信任 | -| `{BASE_SHA}` | 任务开始前的 commit | `git rev-parse HEAD`（dispatch 实现者前记录） | -| `{HEAD_SHA}` | 实现者完成后的 commit | `git rev-parse HEAD`（实现者提交后记录） | -| `{CHANGED_FILES_LIST}` | `git diff --name-only` 输出 | 帮 reviewer 快速定位 | diff --git a/.agents/skills/systematic-debugging/SKILL.md b/.agents/skills/systematic-debugging/SKILL.md index bc1302e..77fa8b6 100644 --- a/.agents/skills/systematic-debugging/SKILL.md +++ b/.agents/skills/systematic-debugging/SKILL.md @@ -178,6 +178,6 @@ git log --oneline --grep="关键词" -10 ## 关联 skill - **上游触发：** 任何编译 / 构建 / 测试 / 运行时失败，且第一次尝试没解决或原因不明 -- **调度 subagent：** 无（控制器/实施者自己执行四阶段） +- **使用方式：** 实施者自己按顺序执行四阶段，不跳阶段 - **完成后交接：** 修复后 → `verification-before-completion` 做完成前验证门 -- **替代路径：** ArkTS 语法类编译错误 → Phase 1 后对照 `growingio-arkts-coding-style` 查约束表；subagent 场景下 3 次失败 → 报告 BLOCKED 升级给控制器 +- **替代路径：** ArkTS 语法类编译错误 → Phase 1 后对照 `growingio-arkts-coding-style` 查约束表；连续 3 次修复失败 → 停下升级给用户讨论，不继续试 diff --git a/.agents/skills/test-driven-development/SKILL.md b/.agents/skills/test-driven-development/SKILL.md index 7c2331d..01cd767 100644 --- a/.agents/skills/test-driven-development/SKILL.md +++ b/.agents/skills/test-driven-development/SKILL.md @@ -189,6 +189,6 @@ it('json_path_includes_eventSequenceId', ...) ## 关联 skill - **上游触发：** `writing-plans` 在"影响面自查清单"中判定本次涉及核心模块 -- **调度 subagent：** 无（本 skill 由实施者执行） +- **使用方式：** 实施者自己执行 - **完成后交接：** 测试通过 → 继续实施 / 交给 `verification-before-completion` 做最终验证 - **替代路径：** 非核心路径（纯配置 / 文档）→ 跳过 TDD；运行时探索性改动 → `systematic-debugging` 的四阶段先于 TDD diff --git a/.agents/skills/using-growingio-sdk-skills/SKILL.md b/.agents/skills/using-growingio-sdk-skills/SKILL.md deleted file mode 100644 index 3bc66f4..0000000 --- a/.agents/skills/using-growingio-sdk-skills/SKILL.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -name: using-growingio-sdk-skills -description: Use when starting any interaction as the GrowingIO HarmonyOS SDK engineer main controller agent ---- - - -If you were dispatched as a subagent to execute a specific task — this includes but is not limited to: - -- `code-reviewer` / `spec-reviewer` (reviewing code or specs) -- implementer subagents dispatched by `subagent-driven-development` -- any general-purpose agent invoked via the `Agent` / `Task` tool with a specific assigned task -- any subagent whose prompt explicitly hands you a narrow job - -**then SKIP THIS META-SKILL ENTIRELY.** Do not apply the routing, Planning Gate, or workflow below. Just execute your assigned task as specified in the prompt you received. The meta-skill's rules are for the main controller agent only; you are not it. - -**但"跳过 meta-skill"不等于"不用任何 skill"**：子 agent 仍可（且应当）自主调用与任务相关的**域 skill**，例如： -- `growingio-arkts-coding-style`（写/审 `.ets`/`.ts` 时） -- `test-driven-development`（实现核心路径时） -- `systematic-debugging`（遇到 build/test/runtime 失败时） -- `verification-before-completion`（声称任务完成前） - -跳过的**只是** meta-skill 的三项硬规则：**Planning Gate + Workflow Routing + TodoWrite 强制**。域 skill 的判断由子 agent 按自身任务自行决定。 - -Signal of subagent context: your prompt starts with "你是…" / "You are…" followed by a specific role description, or you received a structured task payload. In contrast, the main controller receives raw user messages. - - - -If you think there is even a 1% chance a skill might apply to what you are doing, you MUST invoke the skill. This is not negotiable. You cannot rationalize your way out of this. - - -# Using GrowingIO SDK Skills - -> **Type:** Technique | **Discipline:** Rigid - -This is the **entry gate** for the GrowingIO HarmonyOS SDK engineer (main controller agent). - -## How this skill reaches you - -The full content of this SKILL.md is injected into every session automatically by the SessionStart hook (`.claude/hooks/session-start.sh`), and re-injected after `/clear` or auto-compact. You do NOT need to call the `Skill` tool to load it — it is already in your context when you start responding. - -If you see this content and you are NOT the main controller (see `` above), ignore it and execute your assigned task. - -## What this skill does - -Before any response — including clarifying questions — follow the Workflow Routing below to decide which task-specific skills apply, then invoke them via the `Skill` tool. - -## Instruction Priority - -When conflicts arise, resolve by this order: - -1. **User's explicit instructions** (CLAUDE.md, direct messages, in-conversation corrections) — highest -2. **SDK skills** (including this meta-skill, planning gate logic, workflow routing) — override default behavior -3. **Default model behavior** — lowest - -If the user says "skip the plan this time" and a skill says "always write a plan," follow the user. - -## The Rule - -**Invoke relevant skills BEFORE any response or action.** Even a 1% chance a skill applies means invoke it. If the invoked skill turns out to be wrong, you can drop it — but you must check first. - -## Skill Checklist → TodoWrite (HARD RULE) - -当被调用的 skill 包含步骤清单（"Checklist"、编号步骤、"You MUST..."、"必须完成以下"），控制器 **必须**立即调用 `TaskCreate` 把每一条转为独立 todo，并在完成每一步后用 `TaskUpdate` 更新状态。**禁止只在脑内执行 checklist**——脑内 checklist 的漏项率极高，落盘到 todo 才有约束力。 - -此规则对控制器（主 agent）强制；subagent 因其生命周期短、目标单一，可自行判断是否需要。 - -## Skill Catalog (by category) - -### Process skills (check FIRST — they decide HOW to approach the task) -- `brainstorming` — 模糊需求 / 范围不清 / 写 plan 前，做"一次一个问题"的规格收敛 -- `writing-plans` — drafting an implementation plan in `docs/plans/` -- `plan-document-review` — reviewing a plan doc for completeness before user confirmation -- `subagent-driven-development` — executing a plan by dispatching fresh subagents with two-stage review -- `systematic-debugging` — any build/test/runtime failure where root cause is unclear -- `test-driven-development` — implementing core SDK paths (event pipeline, storage, network) - -### Review skills -- `sdk-code-review` — completed a feature/bugfix/refactor, or before merge, or user asked for review -- `receiving-code-review` — processing feedback from a reviewer subagent or human - -### Closing skills -- `verification-before-completion` — before claiming work is done/fixed/ready -- `finishing-a-development-branch` — after verification & review pass, to close out the branch（普通分支收尾 / 发版分支 → 触发 Release 侧流） -- `git-conventions` — writing commit messages, branch names, PR titles - -### Domain skills -- `growingio-arkts-coding-style` — writing/reviewing `.ets`/`.ts` files - -### Release 侧流（仅发版分支激活，不走主流程） -- `jira-ticket` — 创建发版 Jira ticket（版本号确定后、`ohpm-publish` 之前） -- `ohpm-publish` — publishing the SDK HAR to OHPM registry - -### Meta 侧流（改 skill / 改 agent 本身时才用，不走主流程） -- `writing-skills` — 新建或修改 `.agents/skills/` 下任何 SKILL.md 时 - -## Planning Gate (HARD GATE) - -Before writing ANY code, check these triggers: - -**Trigger (any ONE suffices):** -- Affected file count ≥ 3 -- Any change to the public API surface (symbols exported from `index.ets`) - -**If triggered:** -1. Invoke `writing-plans` → save plan to `docs/plans/YYYY-MM-DD-.md` -2. Invoke `plan-document-review` → dispatch reviewer subagent for the plan -3. Show the user the plan path + reviewer summary, explicitly ask for confirmation -4. **Do NOT touch any source file until the user replies with confirmation ("确认" / "OK" / "继续")** - -Required sections in every plan (missing any = incomplete): -- 影响文件列表 -- 公开 API 变更（无则填"无"） -- 数据协议变更（无则填"无"） -- 需同步修改的文档（无则填"无"） - -### Rationalizations (all invalid) - -| Excuse | Reality | -|--------|---------| -| "改动很简单，不需要规划" | 简单改动也有影响面，规划 2 分钟没有例外 | -| "先改完再补规划" | 规划的价值在事前对齐，事后补写无价值 | -| "用户没要求规划" | 触发条件满足即强制，不需用户单独要求 | -| "只改内部实现，不影响公开 API" | 内部实现影响 ≥3 文件同样触发 | -| "这次先快速改，下次规范" | 没有"下次规范"，规则从第一次执行 | -| "步骤很清楚，我脑内过一遍 checklist 就行，不用 TodoWrite" | 脑内 checklist 漏项率极高；TaskCreate 落盘 30 秒，无例外 | -| "需求我看懂了，不用 brainstorming" | 看懂字面 ≠ 规格闭合；brainstorming 把假设写下来给用户挑错 | - -## Workflow Routing (decision tree) - -> 图中**实线**是主干，**虚线/旁路**是可插入的 skill（遇到对应情况随时跳转）。每个 `→` 都是一次 skill invoke。 - -``` -User request received - │ - ▼ -Invoke using-growingio-sdk-skills (you are here) - │ - ▼ -Understand intent - │ - ▼ -需求模糊 / 范围不清 / 无规格? - ├─ YES → brainstorming → 产出 docs/specs/YYYY-MM-DD-.md → 用户确认 - │ │ - └─ NO ───────────────────────────────────────────────────────────────┐ - │ - ▼ -Read relevant docs (docs/sdk-doc-routing.md 按场景读取表; - docs/sdk-critical-rules.md 若改核心模块必读) - │ - ▼ -Planning Gate: ≥3 files OR public API change ? - │ - ├─ YES ─────────────────────────────────────────────┐ - │ │ │ - │ ▼ │ - │ writing-plans → plan-document-review │ - │ → WAIT FOR USER CONFIRM │ - │ │ │ - │ ▼ │ - │ Tasks ≥3 且大部分独立? │ - │ ├─ YES → subagent-driven-development │ - │ │ (控制器不写代码；subagent 内部按需用 │ - │ │ TDD / growingio-arkts-coding-style │ - │ │ / systematic-debugging) │ - │ │ │ - │ └─ NO → 直接实施（单一职责 edits） │ - │ │ - └─ NO ── 直接实施（单一职责 edits） ───────────────────┘ - │ - │ 实施期可随时插入的旁路 skill： - │ ┊ 改核心模块（事件管道/存储/网络） → test-driven-development - │ ┊ 写/审 .ets / .ts → growingio-arkts-coding-style - │ ┊ 任何阶段 build/test/runtime 失败 → systematic-debugging - │ (修完 → 回到失败前的上一步) - ▼ - verification-before-completion (跑真实 verify 命令，读完整输出) - │ - ├─ 失败 → systematic-debugging → （修完）→ 回本步骤重跑 ─┐ - │ │ - └─ 通过 │ - │◄────────────────────────────────────────────────────┘ - ▼ - Code review - ├─ 有 plan → sdk-code-review 模式 A（spec-reviewer → code-reviewer） - ├─ 无 plan + ≤5 files + 不动公开 API → sdk-code-review 模式 B（仅 code-reviewer） - └─ 琐碎改动（<3 files 且不动公开 API）→ 可跳过 - │ - ├─ 需修改 → receiving-code-review → 修复 - │ → 重派同一 reviewer 复审 ─────────────┐ - │ → 回 verification-before-completion 重跑 - │ │ - └─ 通过 │ - │◄───────────────────────────────────────────────────┘ - ▼ - finishing-a-development-branch - ├─ 普通分支 → 使用 git-conventions 规范 commit / PR / 分支名 - │ → Done - │ - └─ 发版分支（version 字段变更）→ 侧流： - jira-ticket（发版单）→ ohpm-publish（发布 HAR） - → 使用 git-conventions 规范 tag 命名 - → Done -``` - -**Meta 侧流**（与上图主流程正交，改 skill 本身时激活）： -``` -修改 .agents/skills/*/SKILL.md → writing-skills → 按其 Checklist 走完 -``` - -## Skill Types - -- **Rigid** (TDD, Planning Gate, verification-before-completion, systematic-debugging): follow exactly, do not adapt away the discipline -- **Flexible** (domain patterns, coding style): adapt principles to context - -The skill itself declares which type it is. - -## Red Flags — STOP if you catch yourself thinking these - -| Thought | Reality | -|---------|---------| -| "这是个简单问题，直接回答就行" | 问题也是任务，先查 skill | -| "先读一下代码再说" | skill 告诉你怎么读 | -| "小改动不用走流程" | Planning Gate 的触发条件本身就是"小改动"判定器 | -| "我记得这个 skill 的内容" | skill 会演进，每次用读当前版本 | -| "用户没要求，跳过吧" | skill 适用性由触发条件判定，不由用户触发 | -| "先做一点再补流程" | 补不回来，从第一步就按流程走 | -| "这个场景有点特殊" | 没有特殊，Rigid skill 没有例外 | -| "我在 subagent 里，不需要查" | 看 `` — 只有控制器跳过，其他要查 | -| "skill 里的 checklist 我记住了，不用落盘 TodoWrite" | 落盘是约束力，不是记忆术；立刻 TaskCreate | -| "先直接写 plan，跳过 brainstorming" | 需求模糊时 plan 的输入就是错的；先走 brainstorming 收敛规格 | - -## User Instructions Override - -User instructions say WHAT to accomplish — they don't override HOW (skills). -"Add feature X" does not mean "skip Planning Gate". "Fix bug Y" does not mean "skip verification". -Only explicit "skip the plan / skip the review" overrides the skill. - -## Domain Context - -领域知识拆分为若干 lazy-load 文档： - -- `docs/sdk-engineering-guide.md` — 产品使命、核心职责索引、健康指标（精简版） -- `docs/sdk-critical-rules.md` — 修改核心模块前 **必读** -- `docs/sdk-doc-routing.md` — 按场景读取的模块文档索引 -- `docs/sdk-build-commands.md` — hvigor 构建命令 - -本 skill 不重复这些内容——读文档知道 WHAT to build，读 skill 知道 HOW to build。 - ---- - -**Remember:** The persona defines who you are. Skills define how you work. This meta-skill is your entry gate — invoke it first, every time. diff --git a/.agents/skills/verification-before-completion/SKILL.md b/.agents/skills/verification-before-completion/SKILL.md index 5c183cd..b6e21e1 100644 --- a/.agents/skills/verification-before-completion/SKILL.md +++ b/.agents/skills/verification-before-completion/SKILL.md @@ -156,6 +156,6 @@ ls -lh GrowingToolsKit/build/default/outputs/default/*.har ## 关联 skill - **上游触发：** 任何"声明完成 / 已修好 / 准备审查 / 准备 merge"的时刻 -- **调度 subagent：** 无（实施者/控制器自己执行验证命令） -- **完成后交接：** 验证通过 → `sdk-code-review` 或 `finishing-a-development-branch` +- **使用方式：** 实施者自己执行验证命令 +- **完成后交接：** 验证通过 → 对照 `docs/sdk-review-checklist.md` 自查 → `finishing-a-development-branch` - **替代路径：** 验证失败 → `systematic-debugging` 四阶段方法，不允许"再试一次"的无脑重跑 diff --git a/.agents/skills/writing-plans/SKILL.md b/.agents/skills/writing-plans/SKILL.md index 45b6862..7d1cd81 100644 --- a/.agents/skills/writing-plans/SKILL.md +++ b/.agents/skills/writing-plans/SKILL.md @@ -1,19 +1,19 @@ --- name: writing-plans -description: Use when Planning Gate triggers (affected files ≥3 or public API change) and an implementation plan is needed +description: Use when a change affects 3 or more files or alters public API, and an implementation plan is needed --- # Writing Plans > **Type:** Technique | **Discipline:** Rigid -指导如何写好一份实施规划。Planning Gate（见 `using-growingio-sdk-skills` meta-skill）定义 plan 的**格式**（四节结构），本 skill 定义**内容质量**。 +指导如何写好一份实施规划。改动文件 ≥3 或涉及公开 API 变更时，先写 plan 再实施。 **核心原则：** 写 plan 时多想 10 分钟，实施时少返工 1 小时。 ## 何时触发 -Planning Gate 要求输出 plan 时（影响 ≥ 3 文件，或涉及公开 API 变更）。 +改动影响 ≥ 3 个文件，或涉及公开 API 变更时。 ## 影响面自查清单 @@ -35,7 +35,7 @@ Planning Gate 要求输出 plan 时（影响 ≥ 3 文件，或涉及公开 API **拆成多任务：** 变更逻辑独立且可并行 / 单任务描述 > 200 字还说不清。 **合并为单任务：** 接口与其使用者（拆开编译不过） / 同模块内部重构 / TDD 内测试与被测代码。 -拆分后按 `subagent-driven-development` skill 判定是否走 subagent 模式。 +拆分后在当前会话内按任务顺序实施，每个任务完成即验证，不留到最后一起验。 ## Rationalizations @@ -51,13 +51,12 @@ Planning Gate 要求输出 plan 时（影响 ≥ 3 文件，或涉及公开 API ## Red Flags — STOP if you catch yourself thinking these -- "先改两个文件试试，plan 后面再写" → Planning Gate 触发那一刻就必须先写 plan +- "先改两个文件试试，plan 后面再写" → 达到门槛那一刻就必须先写 plan - "影响面我心里有数，不用列全" → 没列出来的文件 = 会返工的文件 - "这个字段变更只涉及 NewSaaS" → 三产品线必须逐一确认，未标注 = 后端出错 ## 关联 skill -- **上游触发：** 控制器判定 Planning Gate 触发 -- **调度 subagent：** 无（控制器直接执行） -- **完成后交接：** `plan-document-review` → 用户确认 → `subagent-driven-development` 或直接实施 -- **替代路径：** 未触发 Planning Gate → 跳过本 skill，直接实施 + `sdk-code-review` 独立审查 +- **上游触发：** 改动文件 ≥3 或涉及公开 API 变更 +- **完成后交接：** 用户确认 plan → 按任务顺序实施 → `verification-before-completion` +- **替代路径：** 改动面小于门槛 → 跳过本 skill 直接实施，完成后对照 `docs/sdk-review-checklist.md` 自查 diff --git a/.agents/skills/writing-skills/SKILL.md b/.agents/skills/writing-skills/SKILL.md index 11f9ec7..a3104f5 100644 --- a/.agents/skills/writing-skills/SKILL.md +++ b/.agents/skills/writing-skills/SKILL.md @@ -65,7 +65,7 @@ Edit skill without testing? Same violation. .md # Only when content >100 lines or is a reusable prompt template ``` -Naming: lowercase with hyphens, verb/gerund preferred: `brainstorming`, `writing-plans`, `subagent-driven-development`. +Naming: lowercase with hyphens, verb/gerund preferred: `brainstorming`, `writing-plans`, `verification-before-completion`. ## Frontmatter (only two fields) @@ -103,7 +103,7 @@ When the description was changed to just triggering conditions (no workflow summ ```yaml # ❌ BAD: Summarizes workflow — Claude may follow this instead of reading skill -description: Use when executing plans - dispatches subagent per task with code review between tasks +description: Use when finishing a branch - run verification, then review against the checklist, then commit and tag # ❌ BAD: Too much process detail description: Use for TDD - write test first, watch it fail, write minimal code, refactor @@ -115,7 +115,7 @@ description: 用于异步测试 description: I help you write skills # ✅ GOOD: Just triggering conditions -description: Use when executing an implementation plan with independent tasks in the current session +description: Use when a change affects 3 or more files or alters public API, and an implementation plan is needed # ✅ GOOD: Temporal trigger + symptoms description: Use before claiming work is complete, fixed, or ready to review diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md deleted file mode 100644 index b9529b5..0000000 --- a/.claude/agents/code-reviewer.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -name: GrowingIO SDK Code Reviewer -description: | - GrowingIO HarmonyOS SDK 代码质量审查 subagent。 - 通过 subagent-driven-development 或 sdk-code-review skill 调度，独立审查代码变更的质量、规范和安全性。 - 不负责规格/规划对齐检查（那是 spec-reviewer 的职责）。 -model: sonnet ---- - -你是一名专注于 GrowingIO HarmonyOS SDK 代码库的高级代码质量审查员。你审查代码的质量、规范合规性和安全性。你不负责检查实现是否匹配规格/规划——那是 spec-reviewer 的职责。你的审查是独立的——你没有来自实现会话的任何先前上下文。 - -## 审查步骤 - -收到调度上下文后，按以下顺序执行审查： - -1. **查看变更范围**：运行 `git diff --stat BASE_SHA..HEAD_SHA` 确认变更文件列表和规模 -2. **阅读规划文档**：如果提供了 plan 路径，阅读 plan 了解变更背景（但不做规格对齐检查） -3. **逐文件审查**：运行 `git diff BASE_SHA..HEAD_SHA -- ` 查看每个文件的具体变更 -4. **按维度逐项检查**：对照下方维度逐条评估 -5. **输出审查结果**：按输出格式填写审查报告 - -## 审查维度 - -仅当变更明显不涉及某个领域时，才可跳过该维度。 - -### 1. ArkTS 合规与代码质量 - -**按照 `growingio-arkts-coding-style` skill 中的规则检查**，重点关注： -- 语言约束违反（`any`、解构赋值、索引访问、`var`、`#privateField` 等） -- 格式规范违反（缩进、行宽、导入顺序、命名规范、许可证头等） - -### 2. SDK 设计红线 - -- **初始化前零采集**：`GrowingAnalytics.start()` 调用前无任何采集、存储、网络行为 -- **主线程零阻塞**：所有 IO（RDB 读写、网络请求）在 `TaskPool` 或 `Worker` 中执行 -- **不重复上报**：事件上报成功（2xx/3xx）后从数据库物理删除，失败时保留等待重试；`isUploading` 标志防止并发发送 -- **最小权限**：仅 `ohos.permission.INTERNET` 和 `ohos.permission.GET_NETWORK_INFO` -- **公开 API 仅通过 `index.ets` 导出**，内部实现不暴露 - -### 3. 数据协议一致性 - -- 新增/修改的事件字段命名与 Android/iOS SDK 保持一致 -- 字段类型对齐（string/number/boolean） -- 产品线差异处理正确（SaaS vs NewSaaS vs CDP） -- Protobuf schema 和 JSON schema 同步更新（如适用） - -### 4. 隐私合规 - -- 新增采集字段是否需要 `ignoreField` 位掩码支持 -- 是否存在未经用户授权的敏感数据采集 -- `dataCollectionEnabled = false` 时新代码路径是否被正确拦截 - -### 5. 混淆与打包 - -- 新增公开 API 符号是否已加入 `obfuscation-rules.txt` 的 keep 规则 -- 新增内部类/方法是否意外暴露在 `index.ets` 中 -- HAR 打包配置（`byteCodeHar: true`）未被破坏 - -### 6. 工程质量 - -以下是 `growingio-arkts-coding-style` 未覆盖的、code-reviewer 特有的检查项： -- 错误处理：外部操作使用 try-catch，不吞异常 -- 无冗余代码、无 TODO/FIXME 遗留 -- 无硬编码魔法值（应提取为常量） -- 每个文件职责单一、接口清晰 -- 模块可独立理解和测试 - -### 7. Skill / Agent 架构一致性（条件触发） - -**仅当变更文件列表包含 `.agents/` 或 `.claude/` 路径时执行。** - -- **Skill frontmatter**：`name` 字段与目录名一致；`description` 以 `Use when`/`Use before`/`Use after` 开头，仅描述触发条件，**不含流程摘要**（违反 = workflow in description → agent skips body） -- **Skill 类型声明**：正文开头已声明 `Type`（Technique/Pattern/Reference）+ `Discipline`（Rigid/Flexible）两个维度 -- **Rigid skill 完整性**：`Discipline: Rigid` 的 skill 必须包含 Rationalizations 表 + Red Flags 章节，缺失即 Important 问题 -- **交叉引用有效性**：skill 里通过名称引用的其他 skill 确实存在于 `.agents/skills/` 或 `.claude/skills/` 目录 -- **Agent 格式一致**：新增/修改 agent 的 frontmatter（`name`/`description`/`model`）格式与 `.claude/agents/` 下现有 agent 文件保持一致 -- **Settings hooks 无冲突**：`settings.json` 中新增的 hook 不与现有 hook 重复触发同一逻辑（PreToolUse + PostToolUse 执行同一命令 = 冗余），且 hook 的触发时机与其保护意图匹配（PostToolUse 无法阻断已完成的操作） - -## 输出格式 - -审查输出必须遵循以下结构： - -``` -## 代码质量审查 - -**范围**：[简述审查的变更范围] -**规划文档**：[对应的 plan 文件路径，或"无对应 plan"] - -## 问题 - -### Critical（必须修复，阻塞合并） -- [问题描述] — `file:line` - -### Important（应当修复，合并前处理） -- [问题描述] — `file:line` - -### Suggestion（建议优化，不阻塞） -- [问题描述] — `file:line` - -（无问题时写"无"） - -## 检查清单 - -- [ ] ArkTS 严格模式合规 -- [ ] SDK 设计红线无违反 -- [ ] 数据协议与 Android/iOS 一致 -- [ ] 隐私合规无遗漏 -- [ ] obfuscation-rules.txt 已更新（如需要） -- [ ] 文档已同步更新（如需要） -- [ ] Skill/Agent 架构一致性（`.agents/` / `.claude/` 变更时） - -## 结论 - -**通过** / **需要修改** / **需要讨论** -``` - -## 结论判断标准 - -| 结论 | 条件 | -|------|------| -| **通过** | 无 Critical 和 Important 问题，只有 Suggestion 或完全无问题 | -| **需要修改** | 存在 Critical 或 Important 问题，需要实现者修复后重新提交审查 | -| **需要讨论** | 涉及架构决策需要用户判断；发现的问题可能需要修改 plan | - -## 审查原则 - -- **独立判断**：你不知道实现者的意图，只看代码。如果代码有问题，指出问题，不替实现者解释。 -- **具体而非模糊**：每个问题给出精确文件路径和行号，不要写"某处可能有问题"。 -- **Critical 要谨慎**：只有会导致数据丢失、崩溃、隐私泄露、协议不兼容的问题才标 Critical。 -- **肯定做得好的地方**：在摘要里简要提及亮点，但不要堆砌赞美。 -- **不做表演式认同**：不要写"做得好！"，直接给出技术结论。 diff --git a/.claude/agents/engineering-harmonyos-sdk-engineer.md b/.claude/agents/engineering-harmonyos-sdk-engineer.md deleted file mode 100644 index d978409..0000000 --- a/.claude/agents/engineering-harmonyos-sdk-engineer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: GrowingIO HarmonyOS SDK Engineer -description: GrowingIO HarmonyOS SDK developer specializing in ArkTS/ArkUI-based data collection, auto-track, event pipeline, privacy compliance, and SDK packaging for the GrowingIO analytics platform on HarmonyOS Next. -color: blue -emoji: 📊 -vibe: Builds the GrowingIO analytics SDK that powers data-driven decisions on HarmonyOS devices. ---- - -# GrowingIO HarmonyOS SDK Engineer - -你是 **GrowingIO HarmonyOS SDK Engineer**，负责在 HarmonyOS Next 平台上开发和维护 GrowingIO 数据分析 SDK。 - ---- - -## 🚪 工作流规则（自动注入） - -你的工作流规则（Planning Gate、workflow routing、skill 目录、Red Flags）由 SessionStart hook **自动注入**到每个会话的上下文中，你不需要再显式调用 `Skill` 工具加载 `using-growingio-sdk-skills`——它已经在你的上下文里了。 - -如果你作为 subagent（code-reviewer、spec-reviewer、implementer 等）被分派了具体任务，忽略被注入的 meta-skill，直接执行被分派的任务即可。 - ---- - -## 身份 - -- **Role**: GrowingIO HarmonyOS SDK 的设计者、开发者与维护者 -- **Personality**: 数据精准优先、对 SDK 使用方友好、对隐私合规敬畏、对性能开销斤斤计较 -- **Experience**: 你构建过 GrowingIO Android/iOS SDK 并将其经验迁移到 HarmonyOS，深知跨平台 SDK 设计中数据一致性、采集精度与性能开销之间的权衡 - -## 领域知识（lazy-load） - -SDK 的领域知识分散在几个按需读取的文档里，**不自动注入**，你需要按场景主动读取： - -- `docs/sdk-engineering-guide.md` — 产品使命 + 核心职责概要 + 健康指标（索引性质，经 CLAUDE.md 注入） -- `docs/sdk-critical-rules.md` — **修改核心模块代码前必读**（SDK 设计红线 + ArkTS 开发规范） -- `docs/sdk-doc-routing.md` — 按场景读取的模块文档索引表（改动哪个模块读哪个 `.md`） -- `docs/sdk-build-commands.md` — hvigor 构建命令速查 - -**硬性要求**：动任何 `GrowingAnalytics` 核心模块代码前，**必须**先读 `docs/sdk-critical-rules.md`。 - ---- - -## 💭 沟通风格（面向开发者 —— 单一事实源） - -- **数据精准第一**："这里的 `sessionId` 需要在 App 回到前台超过 30 秒（`sessionInterval` 默认值）后重新生成，否则服务端的访问次数指标会偏低" -- **对接入方友好**："初始化推荐用 `new GrowingConfig().NewSaaS()`/`CDP()`/`SaaS()` 实例方法，三种模式的字段要求不同，工厂方法帮接入方做了参数校验；调试工具 `GrowingToolsKit` 是插件，通过 `config.plugins` 注入，不要单独 start" -- **性能意识**："数据库写入必须异步，把它丢到 TaskPool 里，别在 onClick 回调里直接写 RDB" -- **隐私合规敬畏**："`setDataCollectionEnabled(false)` 必须在用户拒绝隐私协议后立即调用，SDK 收到 false 后需同时停止上报调度" -- **多端一致性**："这个字段在 Android SDK 里叫 `appVersion`，HarmonyOS 这边也必须保持一致，不然数据仓库会出现重复字段" - ---- - -**技术决策优先级**（单一事实源）：在面对具体技术决策时，以「数据准确性 > 接入成本 > 性能开销 > 包体积」的优先级进行权衡。 - -**工作流程**：由 `using-growingio-sdk-skills` meta-skill 负责路由。persona 不再嵌入流程描述——流程活在 skill 里。 diff --git a/.claude/agents/spec-reviewer.md b/.claude/agents/spec-reviewer.md deleted file mode 100644 index 865f354..0000000 --- a/.claude/agents/spec-reviewer.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -name: GrowingIO SDK Spec Reviewer -description: | - GrowingIO HarmonyOS SDK 规格合规审查 subagent。 - 通过 subagent-driven-development skill 调度，独立验证实现是否匹配规格/规划，不检查代码质量。 -model: sonnet ---- - -你是一名专注于 GrowingIO HarmonyOS SDK 代码库的规格合规审查员。你的唯一职责是验证**实现是否匹配规格**——不多、不少、不偏。你不评判代码质量、风格或架构，那是 code-reviewer 的工作。 - -## 审查步骤 - -收到调度上下文后，按以下顺序执行： - -1. **阅读规格**：完整阅读提供的规划文档 / 任务描述，理解预期实现内容 -2. **查看变更范围**：运行 `git diff --stat BASE_SHA..HEAD_SHA` 确认变更文件列表和规模 -3. **逐文件审查**：运行 `git diff BASE_SHA..HEAD_SHA -- ` 查看每个文件的具体变更 -4. **三维度对比**：按下方维度逐条核实 - -## 关键原则：不信任报告 - -实现者的报告可能不完整、不准确或过于乐观。你**必须独立验证一切**。 - -**不要：** -- 相信实现者声称完成了什么 -- 接受实现者对需求的解读 -- 因为报告说"已完成"就跳过检查 - -**要做：** -- 读实际代码，不读报告 -- 逐条对照规格验证 -- 查找实现者没提到的遗漏或多余部分 - -## 审查维度 - -### 1. 缺失需求 - -- 规格中要求的功能是否全部实现？ -- 规划中列出的文件是否都已被修改？ -- 规划中的公开 API 签名是否被准确实现？ -- 规划中的数据协议变更是否被准确反映？ -- 规划中要求的文档更新是否已完成？ - -### 2. 多余工作 - -- 是否有规格未要求的额外功能？ -- 是否有规划外的文件被改动？ -- 是否过度工程化（YAGNI）？ - -### 3. 理解偏差 - -- 实现者是否曲解了需求？ -- 是否解决了错误的问题？ -- 功能方向对但实现方式与规格不符？ - -## 输出格式 - -``` -## 规格合规审查 - -**规格来源**：[plan 文件路径 / 任务描述] -**变更范围**：[简述审查的变更范围] - -## 核实结果 - -### 缺失需求 -- [具体描述] — `file:line` -（无缺失时写"无"） - -### 多余工作 -- [具体描述] — `file:line` -（无多余时写"无"） - -### 理解偏差 -- [具体描述] — `file:line` -（无偏差时写"无"） - -## 规格对照清单 - -- [ ] 规划中的文件全部已修改 -- [ ] 无规划外的额外文件被改动（或有合理理由） -- [ ] 公开 API 签名与规划一致 -- [ ] 数据协议变更与规划一致 -- [ ] 规划要求的文档已更新 - -## 结论 - -**合规** / **不合规** / **需要讨论** -``` - -## 结论判断标准 - -| 结论 | 条件 | -|------|------| -| **合规** | 无缺失、无多余、无偏差，或偏差极小且合理 | -| **不合规** | 存在缺失需求、多余工作或理解偏差，需要实现者修复 | -| **需要讨论** | 发现规格/规划本身有缺陷或歧义；实现与规格产生合理偏离但需要确认 | - -## 审查原则 - -- **只看规格对齐**：不评价代码风格、性能、架构。那不是你的工作。 -- **具体而非模糊**：每个问题给出精确文件路径和行号。 -- **发现规格问题要说出来**：如果实现过程中暴露了规格的缺陷（遗漏场景、接口设计不合理），在报告中明确建议更新规格。 -- **不做表演式认同**：直接给出技术结论。 diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh deleted file mode 100755 index 8dd1c89..0000000 --- a/.claude/hooks/session-start.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/usr/bin/env bash -# SessionStart hook for GrowingIO HarmonyOS SDK project. -# -# Injects the full content of the `using-growingio-sdk-skills` meta-skill -# into the session via hookSpecificOutput.additionalContext — so that the -# main controller agent always sees the meta-skill regardless of persona -# state, /clear, or auto-compact. -# -# Aligned with superpowers/hooks/session-start design. -# Platform: macOS (bash 4+). - -set -euo pipefail - -# Resolve project root. Claude Code sets CLAUDE_PROJECT_DIR; fall back to -# walking up from this script for standalone testing. -if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then - PROJECT_ROOT="$CLAUDE_PROJECT_DIR" -else - SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" - PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)" -fi - -META_SKILL_PATH="${PROJECT_ROOT}/.agents/skills/using-growingio-sdk-skills/SKILL.md" - -if [ ! -f "$META_SKILL_PATH" ]; then - # Fail loud via stderr so the problem is visible, but emit an empty-ish - # JSON so the harness does not get malformed output. - echo "session-start hook: meta-skill file missing at $META_SKILL_PATH" >&2 - printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":""}}\n' - exit 0 -fi - -meta_skill_content=$(cat "$META_SKILL_PATH") - -# Escape a string for embedding as a JSON string value. -# Order matters: backslashes first, then quotes, then control characters. -escape_for_json() { - local s="$1" - s="${s//\\/\\\\}" - s="${s//\"/\\\"}" - s="${s//$'\n'/\\n}" - s="${s//$'\r'/\\r}" - s="${s//$'\t'/\\t}" - printf '%s' "$s" -} - -wrapper_header=' -You are operating in the GrowingIO HarmonyOS SDK project. - -Below is the FULL content of the `using-growingio-sdk-skills` meta-skill, -injected automatically. You do NOT need to call the Skill tool to load it -again — it is already in your context. Follow its rules exactly. - -If you were dispatched as a subagent (code-reviewer, spec-reviewer, -implementer, etc.), honor the `` marker inside the skill -and ignore the meta-skill routing; just execute your assigned task. - ---- BEGIN using-growingio-sdk-skills SKILL.md --- -' - -wrapper_footer=' ---- END using-growingio-sdk-skills SKILL.md --- -' - -combined="${wrapper_header}${meta_skill_content}${wrapper_footer}" -escaped=$(escape_for_json "$combined") - -printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$escaped" diff --git a/.claude/settings.json b/.claude/settings.json index 63cf4a4..7b49e1c 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,18 +1,5 @@ { - "agent": "GrowingIO HarmonyOS SDK Engineer", "hooks": { - "SessionStart": [ - { - "matcher": "startup|clear|compact", - "hooks": [ - { - "type": "command", - "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh", - "timeout": 10 - } - ] - } - ], "PreToolUse": [ { "matcher": "Bash", diff --git a/.gitignore b/.gitignore index fca20d8..33dd8cd 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,5 @@ **/.test oh-package-lock.json5 /.appanalyzer -/build-profile.json5 \ No newline at end of file +/build-profile.json5 +.DS_Store diff --git a/AGENTS.md b/AGENTS.md index 310441a..a74543a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,3 +20,4 @@ > - `docs/sdk-critical-rules.md` — 修改核心模块 **必读**（SDK 设计红线 + ArkTS 开发规范） > - `docs/sdk-doc-routing.md` — 按场景读取的模块文档索引表 > - `docs/sdk-build-commands.md` — hvigor 构建命令速查 +> - `docs/sdk-review-checklist.md` — 提 PR 前 **必读**（代码质量 + 规格对齐自查） diff --git a/docs/agents-skills-flow.md b/docs/agents-skills-flow.md deleted file mode 100644 index 832a196..0000000 --- a/docs/agents-skills-flow.md +++ /dev/null @@ -1,326 +0,0 @@ -# Agents & Skills 流转结构图 - -> 基于当前 `.claude/agents/` 和 `.agents/skills/` 的实际内容分析。最后更新：2026-04-16。 - -## 1. 整体架构概览 - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ SESSION START │ -│ .claude/hooks/session-start.sh │ -│ → 注入 using-growingio-sdk-skills meta-skill 全文到会话上下文 │ -└──────────────────────────────┬──────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ MAIN CONTROLLER (主控制器 Agent) │ -│ Persona: .claude/agents/engineering-harmonyos-sdk-engineer.md │ -│ │ -│ 职责：理解用户意图 → 路由到正确 skill → 调度 subagent → 协调全流程 │ -│ 规则：不直接写代码（大型任务），通过 subagent 隔离上下文 │ -└──────────────────────────────┬──────────────────────────────────────┘ - │ - ▼ - ┌─────────────────────────┐ - │ using-growingio-sdk-skills │ - │ (Meta-Skill 入口门) │ - │ • Planning Gate (硬门) │ - │ • Workflow Routing │ - │ • Skill Checklist→Task │ - └─────────────┬─────────────┘ - │ - Workflow Routing - (见下图) -``` - -## 2. 主流程（Workflow Routing） - -```mermaid -flowchart TD - START([用户请求]) --> META[using-growingio-sdk-skills
入口门 — 已由 Hook 注入] - - META --> INTENT{理解意图} - - INTENT -->|需求模糊/无规格| BS[🧠 brainstorming
一次一问收敛规格] - INTENT -->|需求明确| DOCS - - BS --> SPEC_FILE[产出 docs/specs/*.md] - SPEC_FILE --> USER_APPROVE_SPEC{用户审阅规格} - USER_APPROVE_SPEC -->|拒绝/修改| BS - USER_APPROVE_SPEC -->|确认| DOCS - - DOCS[读领域文档
sdk-doc-routing.md
sdk-critical-rules.md] - DOCS --> GATE{Planning Gate
≥3 files OR 公开 API?} - - GATE -->|YES| WP[📋 writing-plans
产出 docs/plans/*.md] - GATE -->|NO| IMPL_DIRECT[直接实施
单一职责 edits] - - WP --> PDR[📝 plan-document-review
dispatch general-purpose subagent
审查 plan 质量] - - PDR --> PDR_RESULT{plan 审查结论} - PDR_RESULT -->|需要修改| WP - PDR_RESULT -->|2轮仍有 Critical| ESCALATE[升级给用户讨论] - PDR_RESULT -->|通过| USER_CONFIRM{用户确认 plan} - - USER_CONFIRM -->|拒绝/修改| WP - USER_CONFIRM -->|确认| SDD_GATE{任务 ≥3 且大部分独立?} - - SDD_GATE -->|YES| SDD[🤖 subagent-driven-development
控制器不写代码] - SDD_GATE -->|NO| IMPL_PLAN[直接实施
按 plan 逐步 edit] - - IMPL_DIRECT --> VERIFY - IMPL_PLAN --> VERIFY - SDD --> VERIFY - - VERIFY[✅ verification-before-completion
跑真实构建/测试命令
读完整输出] - - VERIFY --> VERIFY_RESULT{验证结论} - VERIFY_RESULT -->|失败| DEBUG[🔧 systematic-debugging
四阶段方法] - DEBUG --> VERIFY - VERIFY_RESULT -->|通过| REVIEW_GATE{审查模式选择} - - REVIEW_GATE -->|有 plan| REVIEW_A[sdk-code-review 模式 A
spec-reviewer → code-reviewer] - REVIEW_GATE -->|无 plan + ≤5 files| REVIEW_B[sdk-code-review 模式 B
仅 code-reviewer] - REVIEW_GATE -->|琐碎改动| FINISH - - REVIEW_A --> REVIEW_RESULT - REVIEW_B --> REVIEW_RESULT - - REVIEW_RESULT{审查结论} - REVIEW_RESULT -->|通过| FINISH - REVIEW_RESULT -->|需修改| RCR[receiving-code-review
STOP-ASK → 修复 → 重派 reviewer] - RCR --> VERIFY - - FINISH[🏁 finishing-a-development-branch
五步收尾] - FINISH --> IS_RELEASE{发版分支?
version 字段变更?} - - IS_RELEASE -->|YES| RELEASE_SIDE - IS_RELEASE -->|NO| BRANCH_END - - subgraph RELEASE_SIDE [Release 侧流] - JIRA[jira-ticket
创建发版 Jira] --> OHPM[ohpm-publish
发布 HAR 到 OHPM] - OHPM --> TAG[git tag
按 git-conventions 命名] - end - - BRANCH_END[git-conventions 规范
commit / PR / 分支名
→ Done ✅] - RELEASE_SIDE --> BRANCH_END - - style META fill:#e1f5fe,stroke:#0277bd - style GATE fill:#fff3e0,stroke:#ef6c00 - style SDD fill:#f3e5f5,stroke:#7b1fa2 - style VERIFY fill:#e8f5e9,stroke:#2e7d32 - style DEBUG fill:#fce4ec,stroke:#c62828 - style FINISH fill:#e0f2f1,stroke:#00695c - style RELEASE_SIDE fill:#fff8e1,stroke:#f9a825 -``` - -## 3. Subagent-Driven Development 内部流程 - -```mermaid -flowchart TD - SDD_START([SDD 启动
读取 plan, 提取任务]) --> TASK_LOOP - - subgraph TASK_LOOP [Per Task 循环] - BASE[记录 BASE_SHA] --> DISPATCH_IMPL[Dispatch 实现者 subagent
haiku/sonnet/opus 按复杂度选] - - DISPATCH_IMPL --> IMPL_STATUS{实现者状态} - - IMPL_STATUS -->|NEEDS_CONTEXT| ANSWER[补充上下文] --> DISPATCH_IMPL - IMPL_STATUS -->|BLOCKED| BLOCKED_EVAL{评估阻塞原因} - BLOCKED_EVAL -->|上下文不足| ANSWER - BLOCKED_EVAL -->|需更强模型| UPGRADE[升级模型重 dispatch] - BLOCKED_EVAL -->|任务太大| SPLIT[拆子任务] - BLOCKED_EVAL -->|plan 有问题| USER_HELP[升级给用户] - - IMPL_STATUS -->|DONE / DONE_WITH_CONCERNS| HEAD[记录 HEAD_SHA] - - HEAD --> SPEC_REVIEW[Dispatch spec-reviewer subagent
.claude/agents/spec-reviewer.md] - SPEC_REVIEW --> SPEC_OK{规格合规?} - SPEC_OK -->|NO| FIX_SPEC[实现者修复] --> SPEC_REVIEW - SPEC_OK -->|YES| CODE_REVIEW[Dispatch code-reviewer subagent
.claude/agents/code-reviewer.md] - - CODE_REVIEW --> CODE_OK{质量通过?} - CODE_OK -->|NO| FIX_CODE[实现者修复] --> CODE_REVIEW - CODE_OK -->|YES| TASK_DONE[标记任务完成 ✅] - end - - TASK_DONE --> MORE{更多任务?} - MORE -->|YES| TASK_LOOP - MORE -->|NO| GLOBAL_REVIEW[全局 sdk-code-review
spec-reviewer + code-reviewer] - - GLOBAL_REVIEW --> GLOBAL_OK{全局审查通过?} - GLOBAL_OK -->|NO| RCR[receiving-code-review
修复 → 重审] - RCR --> GLOBAL_REVIEW - GLOBAL_OK -->|YES| VBC[verification-before-completion] - - VBC --> FADB[finishing-a-development-branch] - - style TASK_LOOP fill:#f5f5f5,stroke:#9e9e9e - style SPEC_REVIEW fill:#e8eaf6,stroke:#283593 - style CODE_REVIEW fill:#e8eaf6,stroke:#283593 -``` - -## 4. SDK Code Review 详细流程 - -```mermaid -flowchart TD - TRIGGER([审查触发]) --> HAS_PLAN{有 plan 文件?} - - HAS_PLAN -->|YES| MODE_A[模式 A: 完整审查] - HAS_PLAN -->|NO| SMALL{≤5 files 且无公开 API?} - SMALL -->|YES| MODE_B[模式 B: 独立审查] - SMALL -->|NO| BACK_PLAN[回退补 plan
→ writing-plans] - - MODE_A --> SPEC_R[Phase 1: spec-reviewer subagent
规格合规审查] - SPEC_R --> SPEC_PASS{合规?} - SPEC_PASS -->|不合规| FIX1[修复 → 重新 dispatch] --> SPEC_R - SPEC_PASS -->|合规| CODE_R - - MODE_B --> CODE_R[Phase 2: code-reviewer subagent
代码质量审查] - - CODE_R --> CODE_PASS{结论} - CODE_PASS -->|通过| DONE([审查通过 →
verification-before-completion]) - CODE_PASS -->|需要修改| FIX2[receiving-code-review
逐条修复 → 重新 dispatch] - FIX2 --> CODE_R - CODE_PASS -->|需要讨论| DISCUSS[与用户讨论] - - style MODE_A fill:#e8eaf6,stroke:#283593 - style MODE_B fill:#e8eaf6,stroke:#283593 - style SPEC_R fill:#fce4ec,stroke:#880e4f - style CODE_R fill:#e1f5fe,stroke:#0277bd -``` - -## 5. 旁路 Skills（实施期可随时插入） - -``` -实施过程中的任意时刻： - │ - ├── 改核心模块（事件管道/存储/网络） - │ → test-driven-development (Red-Green-Refactor) - │ - ├── 写/审 .ets / .ts 文件 - │ → growingio-arkts-coding-style (ArkTS 编码规范) - │ - ├── 任何 build/test/runtime 失败 - │ → systematic-debugging (四阶段方法) - │ → 修完后回到失败前的上一步 - │ - └── 修改 .agents/skills/*/SKILL.md - → writing-skills (Meta 侧流, 与主流程正交) -``` - -## 6. 组件清单 - -### Hooks - -| Hook | 触发时机 | 作用 | -|------|---------|------| -| `session-start.sh` | 每次会话开始 | 注入 meta-skill 全文到上下文 | - -### Agents - -| Agent | 文件 | 角色 | 调度者 | -|-------|------|------|--------| -| **Main Controller** | `engineering-harmonyos-sdk-engineer.md` | 主控制器，理解意图、路由 skill、调度 subagent | — (入口) | -| **Code Reviewer** | `code-reviewer.md` | 代码质量、规范、安全性审查 | `sdk-code-review` / SDD | -| **Spec Reviewer** | `spec-reviewer.md` | 规格合规审查（实现 vs 规划） | `sdk-code-review` / SDD | -| **Plan Reviewer** | _(inline prompt in `plan-document-review`)_ | 审查 plan 文档完整性 | `plan-document-review` | -| **Implementer** | _(inline prompt in SDD)_ | 执行单个 plan 任务 | SDD | - -### Skills - -| 类别 | Skill | Type | Discipline | 触发条件 | -|------|-------|------|------------|---------| -| **入口** | `using-growingio-sdk-skills` | Technique | Rigid | 每次交互（Hook 自动注入） | -| **探索** | `brainstorming` | Pattern | Flexible | 需求模糊/范围不清 | -| **规划** | `writing-plans` | Technique | Rigid | Planning Gate 触发 | -| **规划审查** | `plan-document-review` | Technique | Rigid | plan 产出后 | -| **实施调度** | `subagent-driven-development` | Technique | Rigid | ≥3 独立任务 | -| **验证** | `verification-before-completion` | Technique | Rigid | 声明完成前 | -| **代码审查** | `sdk-code-review` | Technique | Rigid | 实施完成后 | -| **反馈处理** | `receiving-code-review` | Technique | Rigid | 收到审查反馈 | -| **收尾** | `finishing-a-development-branch` | Technique | Rigid | 验证+审查通过后 | -| **调试** | `systematic-debugging` | Technique | Rigid | 任何失败 | -| **TDD** | `test-driven-development` | Technique | Rigid | 核心路径实现 | -| **编码规范** | `growingio-arkts-coding-style` | Reference | Flexible | 写/审 .ets/.ts | -| **Git 规范** | `git-conventions` | Reference | Flexible | commit/PR/branch/tag | -| **发版 Jira** | `jira-ticket` | Reference | Flexible | 发版分支 | -| **OHPM 发布** | `ohpm-publish` | Technique | Rigid | 发版分支 | -| **Skill 编写** | `writing-skills` | Technique | Rigid | 修改 SKILL.md | - -### Skill Type 说明 - -两个正交维度（定义见 `writing-skills`）： - -**本质分类（这个 skill 是什么）：** - -| Type | 含义 | 示例 | -|------|------|------| -| **Technique** | 具体方法，有步骤可循 | `test-driven-development`, `systematic-debugging` | -| **Pattern** | 思维模型，指导如何思考 | `brainstorming` | -| **Reference** | 查询式，结构化条目 | `git-conventions`, `growingio-arkts-coding-style` | - -**执行纪律标签（这个 skill 怎么执行）：** - -| Discipline | 含义 | 要求 | -|---|---|---| -| **Rigid** | 必须严格遵守，不得适配 | 必须带 Rationalizations 表 + Red Flags | -| **Flexible** | 原则可按场景取舍 | 不需 Rationalizations | - -## 7. 信息流向总结 - -``` -Hook 注入 - │ - ▼ -Meta-Skill (入口门 + 路由) - │ - ├─→ 探索阶段: brainstorming → specs/ - │ - ├─→ 规划阶段: writing-plans → plan-document-review → 用户确认 - │ - ├─→ 实施阶段: SDD (subagent 隔离) 或 直接实施 - │ │ - │ ├── 旁路: TDD / coding-style / systematic-debugging - │ │ - │ └── Subagents: implementer → spec-reviewer → code-reviewer - │ - ├─→ 验证阶段: verification-before-completion ←→ systematic-debugging - │ - ├─→ 审查阶段: sdk-code-review (spec-reviewer + code-reviewer) - │ │ - │ └── receiving-code-review (反馈处理 loop-back) - │ - └─→ 收尾阶段: finishing-a-development-branch - │ - ├── 普通分支: git-conventions → Done - └── 发版分支: jira-ticket → ohpm-publish → git tag → Done -``` - -## 8. Meta-Skill 边界：主控制器 vs Subagent - -``` -┌────────────────────────────────────────────────────────────┐ -│ Main Controller（受 meta-skill 约束） │ -│ │ -│ ✅ Planning Gate ✅ Workflow Routing ✅ TodoWrite │ -│ │ -│ 职责：理解意图 → 选 skill → 调度 subagent → 协调全流程 │ -│ 禁止：大型任务中直接写代码（上下文污染） │ -└────────────────────────┬───────────────────────────────────┘ - │ dispatch - ▼ -┌────────────────────────────────────────────────────────────┐ -│ Subagents（跳过 meta-skill，见 ） │ -│ │ -│ ❌ Planning Gate ❌ Workflow Routing ❌ TodoWrite │ -│ ✅ 域 skill（按需）： │ -│ growingio-arkts-coding-style / test-driven-development │ -│ systematic-debugging / verification-before-completion │ -│ │ -│ 包括：implementer / code-reviewer / spec-reviewer / │ -│ plan-reviewer / 任何 Agent() 派出的窄任务 subagent │ -└────────────────────────────────────────────────────────────┘ -``` - -**判定依据：** prompt 以 "你是…" / "You are…" + 具体角色描述开头 = subagent。接收用户原始消息 = 主控制器。 diff --git a/docs/sdk-engineering-guide.md b/docs/sdk-engineering-guide.md index 380febb..da83ad2 100644 --- a/docs/sdk-engineering-guide.md +++ b/docs/sdk-engineering-guide.md @@ -23,6 +23,10 @@ **hvigor 构建命令 → [`docs/sdk-build-commands.md`](./sdk-build-commands.md)** +## ✅ 合并前自查 + +**提 PR 前 → 必读 [`docs/sdk-review-checklist.md`](./sdk-review-checklist.md)**（含开发流程图） + --- ## 🎯 SDK 健康指标 diff --git a/docs/sdk-review-checklist.md b/docs/sdk-review-checklist.md new file mode 100644 index 0000000..d0ed4f2 --- /dev/null +++ b/docs/sdk-review-checklist.md @@ -0,0 +1,127 @@ +# SDK 代码审查清单 + +变更完成后、合并前的自查清单。原先由 `code-reviewer` / `spec-reviewer` 两个 subagent 承载，现已沉淀为文档，由开发者（或 AI 助手）在同一会话内自查。 + +红线定义见 [`sdk-critical-rules.md`](./sdk-critical-rules.md)，本文档只列**审查动作**。 + +## 本清单在开发流程中的位置 + +本项目不使用 agent 编排层——没有 persona agent、没有 reviewer subagent、没有 SessionStart 注入。流程由规范文档承载，skill 靠自身 `description` 被动触发。 + +``` +需求 + │ + ├─ 模糊 / 范围不清 → brainstorming（一次一问，收敛成 docs/specs/ 规格） + │ + ▼ +读相关文档（docs/sdk-doc-routing.md 按场景路由） + │ + ▼ +影响面判定：改动 ≥3 文件 或 涉及公开 API？ + ├─ 是 → writing-plans（落地 docs/plans/YYYY-MM-DD-*.md，用户确认后实施） + └─ 否 → 直接实施 + │ + ▼ +实施（改核心模块走 test-driven-development） + │ + ▼ +verification-before-completion（跑构建 + 测试，不靠"应该没问题"） + │ + ▼ +◀── 本清单：对照下方两部分自查 ──▶ + │ + ▼ +finishing-a-development-branch（commit / PR / tag / 分支清理） +``` + +## 审查步骤 + +1. `git diff --stat BASE..HEAD` 确认变更文件列表和规模 +2. 有对应 plan（`docs/plans/`）则先读 plan，理解变更背景与预期范围 +3. `git diff BASE..HEAD -- ` 逐文件看具体变更 +4. 对照下方两部分逐条核实 + +--- + +## Part 1：代码质量 + +### 1. ArkTS 合规 + +按 `growingio-arkts-coding-style` skill 的规则检查，重点： + +- 语言约束：`any`、解构赋值、索引访问、`var`、`#privateField` +- 格式规范：缩进、行宽、导入顺序、命名规范、许可证头 + +### 2. SDK 设计红线 + +逐条核对 [`sdk-critical-rules.md`](./sdk-critical-rules.md)：初始化前零采集、主线程零阻塞、不重复上报、最小权限、公开 API 仅经 `index.ets` 导出。 + +### 3. 数据协议一致性 + +- 新增/修改的事件字段命名与 Android/iOS SDK 保持一致 +- 字段类型对齐（string / number / boolean） +- 产品线差异处理正确（SaaS vs NewSaaS vs CDP） +- Protobuf schema 与 JSON schema 同步更新（如适用） + +### 4. 隐私合规 + +- 新增采集字段是否需要 `ignoreField` 位掩码支持 +- 是否存在未经用户授权的敏感数据采集 +- `dataCollectionEnabled = false` 时新代码路径是否被正确拦截 + +### 5. 混淆与打包 + +- 新增公开 API 符号已加入 `obfuscation-rules.txt` 的 keep 规则 +- 新增内部类/方法未意外暴露在 `index.ets` 中 +- HAR 打包配置（`byteCodeHar: true`）未被破坏 + +> `git push` 前有 PreToolUse hook 跑 `scripts/check_obfuscation_rules.py` 做自动校验，但不要依赖它兜底。 + +### 6. 工程质量 + +- 错误处理：外部操作使用 try-catch，不吞异常 +- 无冗余代码、无 TODO/FIXME 遗留 +- 无硬编码魔法值（应提取为常量） +- 每个文件职责单一、接口清晰，模块可独立理解和测试 + +--- + +## Part 2：规格对齐 + +**前提：不信任自己的完成报告。** 读实际代码，不读报告；因为"我记得写了"就跳过检查，正是漏项的来源。 + +### 1. 缺失需求 + +- 规格要求的功能是否全部实现？ +- 规划中列出的文件是否都已被修改？ +- 公开 API 签名、数据协议变更是否被准确实现？ +- 规划要求的文档更新是否已完成？ + +### 2. 多余工作 + +- 是否有规格未要求的额外功能？规划外的文件被改动？ +- 是否过度工程化（YAGNI）？ + +### 3. 理解偏差 + +- 是否曲解了需求、解决了错误的问题？ +- 功能方向对但实现方式与规格不符？ + +--- + +## 问题分级 + +| 级别 | 判定标准 | 处理 | +|------|---------|------| +| **Critical** | 会导致数据丢失、崩溃、隐私泄露、协议不兼容 | 必须修复，阻塞合并 | +| **Important** | 违反规范或红线，但不直接造成上述后果 | 合并前处理 | +| **Suggestion** | 可优化项 | 不阻塞 | + +存在 Critical 或 Important 即为「需要修改」；涉及架构决策或暴露了规格本身的缺陷，则为「需要讨论」——后者应同时提出修改 plan 的建议。 + +## 审查原则 + +- **只看代码，不替自己解释意图**：代码有问题就是有问题 +- **具体而非模糊**：每个问题给出精确 `file:line`，不写"某处可能有问题" +- **Critical 要谨慎**：够不上上表标准的不要升级 +- **不做表演式认同**：直接给技术结论，不堆砌赞美