@siming-org/cli 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +2 -2
- package/package.json +3 -3
- package/templates/builtin/full_workflow.bundle.json +265 -503
- package/templates/builtin/quick_workflow.bundle.json +250 -0
- package/templates/builtin/research_workflow.bundle.json +37 -14
- package/templates/builtin/quick_fix_workflow.bundle.json +0 -401
|
@@ -1,184 +1,288 @@
|
|
|
1
1
|
{
|
|
2
2
|
"exportFormatVersion": "1.0",
|
|
3
|
-
"exportedAt": "2026-
|
|
3
|
+
"exportedAt": "2026-09-09T15:57:17.939Z",
|
|
4
4
|
"warnings": [],
|
|
5
5
|
"template": {
|
|
6
6
|
"name": "full_workflow",
|
|
7
|
-
"description": "
|
|
7
|
+
"description": "通用软件开发全流程：PRD 设计与确认、分支对齐、完整技术方案双审，按任务轨道进入后端或前端实现与验证，完成单元测试和项目适用的端到端测试，经最终集成验证、发布验收与架构信息归档后收敛。feature 使用完整路径；bugfix 和界面微调可按任务配置跳过 PRD。混合任务先完成后端测试链，再进入前端实现与视觉验证。",
|
|
8
8
|
"nodes": [
|
|
9
9
|
{
|
|
10
10
|
"id": "PRD",
|
|
11
11
|
"label": "PRD 设计",
|
|
12
12
|
"phase": "entry",
|
|
13
13
|
"track": "all",
|
|
14
|
-
"prompt": "# PRD
|
|
14
|
+
"prompt": "# PRD 设计\n\n## 节点职责\n\n把模糊需求整理成不依赖当前对话、可直接供技术设计、实现和验收使用的产品需求文档，并通过独立评审和用户确认建立后续工作的产品基线。\n\n本节点只定义产品的 What 和 Why：解决什么问题、服务哪些用户、用户可见行为是什么，以及依据什么结果验收；不决定技术实现方式。\n\n## 依赖信息\n\n先检查当前 Siming 任务上下文中的需求概述、验收标准、非目标、前序节点记录，以及项目产品资料和项目约束；已有信息直接复用，缺失时再加载或确认。\n\n按名称加载 `workflow-discipline` Skill，并调用 `prd-reviewer` Agent 完成独立评审。评审时只提供 PRD、客观产品约束和必要参照，不提供主会话的设计结论、预期评审结果或“用户已确认”等预设信息。\n\n## 正向执行流程\n\n1. **明确问题与价值**：识别当前问题、受影响用户、期望改善及不处理的后果，避免把用户提出的方案直接当成问题本身。\n2. **还原用户场景**：说明谁在什么条件下执行什么操作、期望得到什么结果，并覆盖关键异常和边界场景。\n3. **提炼产品规则**：从场景中整理功能行为、状态变化、权限差异、数据约束和失败反馈，只保留用户或业务可感知的规则。\n4. **控制交付范围**：区分本次必须完成、明确不做和仍待决定的内容，避免把后续设想混入当前交付。\n5. **建立验收闭环**：为每项核心行为定义可观察、可判定的结果，且不依赖内部实现方式。\n6. **处理信息缺口**：只有缺口会改变需求范围、用户可见行为、业务规则、异常处理或验收结论时才询问用户，每次只问一个需要决定的问题。非阻塞信息采用明确假设继续，并记录假设及影响。\n7. **编写并保存 PRD**：根据任务规模组织内容，不要求固定篇幅或章节数量。项目有文档目录时按项目声明保存全文；登记任务产物时必须携带 PRD 全文（`file` 或 `content`），纯路径引用仅用于超过 200k 字符快照上限的文件，且须说明理由。项目要求版本控制时，按项目约定保存可追溯版本。\n8. **执行独立评审**：调用 `prd-reviewer`：\n - `BLOCKED`：补齐评审输入后重新评审；\n - 存在 `BLOCKER`：修订 PRD；无法自行收敛时，向用户呈现分歧后再处理；\n - `WARNING` 或 `SUGGESTION`：逐条决定修订或保留，并记录理由；\n - 没有 `BLOCKER` 且总体为 `PASS` 后，进入用户确认。\n9. **取得用户确认**：呈现需求范围、关键场景与规则、验收标准、非目标、假设、开放问题和评审结论；用户明确确认并记录原文后，才能通过暂停点。\n\n## 产出检查\n\n推进前确认：\n\n1. PRD 全文可读取、已保存，登记值携带全文（超限时为路径引用且已说明理由）。\n2. 每项核心功能都能追溯到明确的问题、价值或用户场景。\n3. 每项关键场景都有对应的产品行为、业务规则和可观察验收结果。\n4. 范围、异常边界、非目标、假设和开放问题之间没有矛盾，也没有阻塞后续设计的隐藏歧义。\n5. 文档不依赖当前聊天背景，不包含类、文件、接口路径、数据库结构、框架选型、部署方式或实现步骤。\n6. 独立评审总体为 `PASS`，所有 Finding 已修订或记录保留理由。\n7. 用户已明确确认当前 PRD，确认原文已经记录。\n\n## 任务差异处理\n\n根据需求规模调整文档深度；简单需求可以简短，但不能省略影响实现和验收的关键信息。\n\n界面需求应描述用户可见状态、交互反馈、可访问性和适配要求，但不指定组件、样式框架或前端实现方式。\n\n某项内容因任务性质确实不适用时，写明不适用对象和理由，不使用空章节或占位文本代替分析。\n\n任务输入不足、评审处于 `BLOCKED`、仍有未解决的 `BLOCKER`，或用户尚未明确确认时，保留在本节点继续处理，不得推进。\n\n## 节点记录与推进\n\n记录以下信息：\n\n- PRD 产物或全文及其版本引用；\n- 需求结论摘要；\n- 完成检查结果；\n- 独立评审的总体结论、轮次和 Findings 处理结果；\n- 关键产品决定、假设和开放问题；\n- 不适用项及其理由；\n- 用户确认原文。\n\n只有全部产出检查满足后，才以 PRD 完成摘要推进流程。",
|
|
15
15
|
"skills": [
|
|
16
|
-
"prd-design",
|
|
17
|
-
"prd-review",
|
|
18
|
-
"entry-prd",
|
|
19
16
|
"workflow-discipline"
|
|
20
|
-
]
|
|
17
|
+
],
|
|
18
|
+
"agents": [
|
|
19
|
+
"prd-reviewer"
|
|
20
|
+
],
|
|
21
|
+
"sourcePreset": {
|
|
22
|
+
"code": "prd-design",
|
|
23
|
+
"version": "1.5.0",
|
|
24
|
+
"contentHash": "009d0d688ce31268",
|
|
25
|
+
"agents": [
|
|
26
|
+
"prd-reviewer"
|
|
27
|
+
]
|
|
28
|
+
}
|
|
21
29
|
},
|
|
22
30
|
{
|
|
23
31
|
"id": "ALIGN",
|
|
24
32
|
"label": "分支对齐",
|
|
25
33
|
"phase": "entry",
|
|
26
34
|
"track": "all",
|
|
27
|
-
"prompt": "#
|
|
35
|
+
"prompt": "# 分支对齐\n\n## 节点职责\n\n在后续工作开始前，确认是否需要合并基础分支的远程最新代码。\n\n## 依赖信息\n\n检查当前任务上下文和项目提示词，从中解析基础分支，例如 `main`、`master` 或 `dev`。按名称加载 `workflow-discipline` Skill。\n\n## 正向执行流程\n\n1. 能解析出基础分支时，获取并合并该分支的远程最新代码。\n2. 无法解析时，询问用户是否需要合并某个分支的远程代码。\n3. 用户指定分支后执行合并；用户明确表示不需要时，直接推进下一节点。\n\n## 产出检查\n\n推进前确认：基础分支的远程代码已成功合并，或者用户已明确表示不需要合并。\n\n## 任务差异处理\n\n没有远程仓库或用户不要求合并时，记录不执行的事实和理由。合并发生冲突且无法可靠解决时，保留在当前节点并向用户说明。\n\n## 节点记录与推进\n\n记录基础分支、合并结果，或不执行合并的理由，然后推进下一节点。",
|
|
28
36
|
"skills": [
|
|
29
37
|
"workflow-discipline"
|
|
30
|
-
]
|
|
38
|
+
],
|
|
39
|
+
"agents": [],
|
|
40
|
+
"sourcePreset": {
|
|
41
|
+
"code": "align-branch",
|
|
42
|
+
"version": "1.3.0",
|
|
43
|
+
"contentHash": "ffba197df7edb043",
|
|
44
|
+
"agents": []
|
|
45
|
+
}
|
|
31
46
|
},
|
|
32
47
|
{
|
|
33
48
|
"id": "DESIGN",
|
|
34
49
|
"label": "技术方案",
|
|
35
50
|
"phase": "entry",
|
|
36
51
|
"track": "all",
|
|
37
|
-
"prompt": "#
|
|
52
|
+
"prompt": "# 技术方案\n\n## 节点职责\n\n将已确认的产品需求转化为可直接指导实现和验证的技术方案，并通过需求对齐审查、架构评审和用户确认建立实现基线。本节点只产出设计，不编写生产代码或测试代码。\n\n## 依赖信息\n\n检查当前任务上下文、需求与验收标准、非目标、PRD、前序节点产物、项目提示词和相关架构资料；已有信息直接复用，缺失时再加载。\n\n按名称加载：\n\n- `tech-design` Skill：技术方案设计方法及文档模板；\n- `workflow-discipline` Skill：执行、审查和暂停点纪律。\n\n方案完成后，依次调用：\n\n1. `alignment-reviewer` Agent：检查方案与需求的对齐关系；\n2. `arch-reviewer` Agent：检查方案的架构质量。\n\n## 正向执行流程\n\n1. 确认需求范围和后端、前端或混合轨道，并读取相关项目约束与现有架构。\n2. 使用 `tech-design` Skill 设计方案，并读取其 `references/template.md` 生成技术方案文档。\n3. 项目有文档目录时按项目声明保存方案文件；登记任务产物时必须携带方案全文（`record-artifact-add` 用 `file` 或 `content`），纯路径引用仅用于超过 200k 字符快照上限的文件，且须说明理由。\n4. 调用 `alignment-reviewer`。存在需求偏差时先修订方案，直至总体 `PASS`。\n5. 调用 `arch-reviewer`。处理 BLOCKER 和 HIGH；MEDIUM、LOW 逐项修订或记录保留理由，直至总体 `PASS`。\n6. 向用户呈现方案摘要、关键取舍、两道审查结论和即将进入的实现轨道。\n7. 用户明确确认并记录原文后，通过暂停点进入实现阶段，并按项目分支规则创建任务分支。\n\n## 产出检查\n\n推进前确认：\n\n- 技术方案全文可读取、已保存，登记值携带全文（超限时为路径引用且已说明理由）；\n- 文档符合 `tech-design` 模板使用规则，最低必备信息完整；\n- 需求、验收标准和非目标均有对应设计；\n- 按需设计已完成，或在“不适用项”中写明具体对象和理由；\n- `alignment-reviewer` 总体为 `PASS`；\n- `arch-reviewer` 总体为 `PASS`，其余 Finding 已处理或记录保留理由；\n- 用户已明确确认当前方案，确认原文已经记录。\n\n## 任务差异处理\n\n没有独立 PRD 时，以任务需求、验收标准和非目标作为对齐基线。\n\n方案出现需要用户决定的产品方向、破坏性变更、新依赖或重大架构取舍时，先呈现选项、影响和建议。\n\n任一道审查处于 `BLOCKED` 或 `FAIL`，项目约束与方案无法同时满足，或用户尚未确认时，保留在本节点继续处理。\n\n## 节点记录与推进\n\n记录技术方案产物、方案摘要、关键决策与取舍、完成检查、两道审查的结论与轮次、Finding 处理结果、不适用项及理由，以及用户确认原文。\n\n全部产出检查满足后再推进；创建任务分支后，记录任务与分支的关联。",
|
|
38
53
|
"skills": [
|
|
39
|
-
"
|
|
40
|
-
"code-philosophy",
|
|
41
|
-
"entry-tech",
|
|
42
|
-
"config-node",
|
|
43
|
-
"config-java",
|
|
44
|
-
"config-ui",
|
|
45
|
-
"prd-alignment-review-prompt",
|
|
54
|
+
"tech-design",
|
|
46
55
|
"workflow-discipline"
|
|
47
|
-
]
|
|
56
|
+
],
|
|
57
|
+
"agents": [
|
|
58
|
+
"alignment-reviewer",
|
|
59
|
+
"arch-reviewer"
|
|
60
|
+
],
|
|
61
|
+
"sourcePreset": {
|
|
62
|
+
"code": "design-tech",
|
|
63
|
+
"version": "1.4.0",
|
|
64
|
+
"contentHash": "a1dd3ef23dad18b3",
|
|
65
|
+
"agents": [
|
|
66
|
+
"alignment-reviewer",
|
|
67
|
+
"arch-reviewer"
|
|
68
|
+
]
|
|
69
|
+
}
|
|
48
70
|
},
|
|
49
71
|
{
|
|
50
72
|
"id": "CODE_BACKEND",
|
|
51
73
|
"label": "后端编码",
|
|
52
74
|
"phase": "track",
|
|
53
75
|
"track": "backend",
|
|
54
|
-
"prompt": "#
|
|
76
|
+
"prompt": "# 后端编码\n\n## 节点职责\n\n依据已确认的需求和技术方案完成后端生产代码，并通过项目静态检查和独立代码评审。测试设计、测试代码与测试执行由后续节点负责。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、非目标、技术方案、既有决策以及项目和所属模块的提示词。加载 `coding-standards`、`workflow-discipline`，并按实际技术栈读取 `coding-standards` 对应 reference；调用独立 `code-reviewer` 评审实现。\n\n缺少实现所必需的需求、设计或项目约束时，先从任务上下文和仓库现状补齐；仍无法确定关键行为时，说明缺失信息并暂停，不猜测实现。\n\n## 执行流程\n\n1. 将需求、验收标准和技术方案整理为可核对的实现项，明确行为边界、错误处理、状态变化和副作用。\n2. 调查相关入口、调用链、数据模型、持久化、配置和既有接口，确认真实代码契约与项目惯例。\n3. 按最小充分范围实现生产代码，遵循项目分层和编码规范；只修改与本任务有关的生产代码，不修改测试、fixture 或其他验证代码，不清除无关注释。\n4. 处理配置、存储、兼容性、权限、并发和资源生命周期影响；不涉及的项目无需制造改动。\n5. 按项目声明执行适用的类型检查、编译、构建和静态分析，并保留可追溯结果。测试命令留给后续测试节点。\n6. 将需求、技术方案、项目约束和代码变更位置交给 `code-reviewer` 独立评审，不提供主会话结论或预期结果。修复 BLOCKER 和 HIGH Findings 后重新评审，直至获得 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- 需求、设计与生产实现可以逐项对应；\n- 生产代码完成，未修改验证代码，未清除无关注释；\n- 配置、存储、兼容性和其他副作用已正确处理；\n- 适用的静态检查通过并留有结果；\n- `code-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 生产代码和必要说明已形成可引用产物。\n\n## 任务差异处理\n\n新增依赖、破坏性变更、数据迁移、公开契约变化或真实范围扩张需要用户决定时，先呈现必要性和影响再暂停。某项检查因技术栈或任务性质不适用时，说明理由，不得静默跳过；执行障碍和评审修订按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将实现摘要、主要变更、静态检查结果、代码产物引用、关键决策、未适用项及理由、`code-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
55
77
|
"skills": [
|
|
56
|
-
"
|
|
57
|
-
"design-implementation-consistency",
|
|
58
|
-
"track-code",
|
|
59
|
-
"config-node",
|
|
60
|
-
"config-java",
|
|
78
|
+
"coding-standards",
|
|
61
79
|
"workflow-discipline"
|
|
62
|
-
]
|
|
80
|
+
],
|
|
81
|
+
"agents": [
|
|
82
|
+
"code-reviewer"
|
|
83
|
+
],
|
|
84
|
+
"sourcePreset": {
|
|
85
|
+
"code": "code-backend",
|
|
86
|
+
"version": "1.3.0",
|
|
87
|
+
"contentHash": "f6dae352d1443e24",
|
|
88
|
+
"agents": [
|
|
89
|
+
"code-reviewer"
|
|
90
|
+
]
|
|
91
|
+
}
|
|
63
92
|
},
|
|
64
93
|
{
|
|
65
94
|
"id": "CODE_UI",
|
|
66
|
-
"label": "
|
|
95
|
+
"label": "前端编码",
|
|
67
96
|
"phase": "track",
|
|
68
97
|
"track": "ui",
|
|
69
|
-
"prompt": "#
|
|
98
|
+
"prompt": "# 前端编码\n\n## 节点职责\n\n依据已确认的需求和技术方案完成前端生产代码，包括界面结构、视觉样式、交互、响应式和可访问性，并通过项目静态检查和独立代码评审。测试与视觉验收由后续节点负责，但设计要求的界面能力必须在本节点实现完成。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、非目标、技术方案、既有决策以及项目和所属模块的提示词。加载 `coding-standards`、`workflow-discipline`，并按实际技术栈读取 `coding-standards` 的 UI 及其他相关 references；调用独立 `code-reviewer` 评审实现。\n\n涉及后端接口时，读取服务端入口、请求响应结构和错误行为，确认真实代码契约。缺少实现所必需的信息时，先从任务上下文和仓库现状补齐；仍无法确定关键行为时，说明缺失信息并暂停，不猜测实现。\n\n## 执行流程\n\n1. 将需求、验收标准和技术方案整理为可核对的界面实现项，明确页面结构、交互流程、视觉状态、数据状态、响应式和可访问性要求。\n2. 调查现有页面、组件、设计系统、路由、状态管理、数据请求和接口契约，沿用项目既有模式。\n3. 按最小充分范围实现生产代码，完整实现结构、数据流、事件、副作用、样式和反馈；只修改与本任务有关的生产代码，不修改测试、fixture、截图基线或其他验证代码，不清除无关注释。\n4. 根据界面实际行为处理加载、空、错误、成功、重复操作、危险操作、长内容、窄屏、键盘操作和焦点等状态；不适用的状态无需制造实现。\n5. 按项目声明执行适用的类型检查、编译、构建和静态分析，并保留可追溯结果。测试和视觉验证命令留给后续节点。\n6. 将需求、技术方案、项目约束和代码变更位置交给 `code-reviewer` 独立评审，不提供主会话结论或预期结果。修复 BLOCKER 和 HIGH Findings 后重新评审，直至获得 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- 需求、设计与前端生产实现可以逐项对应；\n- 界面结构、视觉、交互、响应式和可访问性已完整实现；\n- 适用的数据状态、反馈、恢复动作和关键边界已处理；\n- 真实接口契约已核对，未修改验证代码，未清除无关注释；\n- 适用的静态检查通过并留有结果；\n- `code-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 生产代码和必要说明已形成可引用产物。\n\n## 任务差异处理\n\n新增依赖、破坏性变更、公开契约变化、设计语言变化或真实范围扩张需要用户决定时，先呈现必要性和影响再暂停。某项界面状态或检查因任务性质不适用时，说明理由，不得静默跳过；执行障碍和评审修订按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将实现摘要、主要变更、静态检查结果、代码产物引用、接口与界面边界处理、关键决策、未适用项及理由、`code-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
70
99
|
"skills": [
|
|
71
|
-
"
|
|
72
|
-
"frontend-consistency",
|
|
73
|
-
"ui-implementation",
|
|
74
|
-
"ui-constraints",
|
|
75
|
-
"track-component",
|
|
76
|
-
"config-ui",
|
|
100
|
+
"coding-standards",
|
|
77
101
|
"workflow-discipline"
|
|
78
|
-
]
|
|
102
|
+
],
|
|
103
|
+
"agents": [
|
|
104
|
+
"code-reviewer"
|
|
105
|
+
],
|
|
106
|
+
"sourcePreset": {
|
|
107
|
+
"code": "code-frontend",
|
|
108
|
+
"version": "1.3.0",
|
|
109
|
+
"contentHash": "6ae4ea3be1128aa5",
|
|
110
|
+
"agents": [
|
|
111
|
+
"code-reviewer"
|
|
112
|
+
]
|
|
113
|
+
}
|
|
79
114
|
},
|
|
80
115
|
{
|
|
81
116
|
"id": "UI_VISUAL",
|
|
82
|
-
"label": "
|
|
117
|
+
"label": "视觉验证",
|
|
83
118
|
"phase": "track",
|
|
84
119
|
"track": "ui",
|
|
85
|
-
"prompt": "#
|
|
120
|
+
"prompt": "# 视觉验证\n\n## 节点职责\n\n运行当前界面并通过浏览器完成验收路径，验证功能结果、采集视觉证据，再根据独立 `visual-reviewer` 的评审结果完成修复和回归。本节点负责运行、操作、采证和流程收敛，不代替 Agent 判断视觉质量。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、技术方案、前端实现记录，以及项目和所属模块的提示词。加载 `workflow-discipline`，调用独立 `visual-reviewer` 评审视觉证据。\n\n根据需求整理待验证页面、用户路径、需要呈现的状态和代表性视口。缺少运行方式、访问地址、认证或数据准备信息时，先从项目脚本、配置和现有环境中查找；仍无法运行当前实现时，说明缺失信息并暂停。\n\n## 执行流程\n\n1. 按项目声明启动当前实现及其依赖服务，确认页面对应本次代码。\n2. 使用浏览器自动化能力执行需求涉及的真实用户路径，验证操作后的页面结果、请求结果、反馈、错误处理和持久化后的重新加载结果。\n3. 检查浏览器控制台中的新增错误、失败请求和其他运行异常。\n4. 按验收范围触发适用的加载、空、错误、成功和关键交互状态，并在代表性视口采集截图、视频或等价原始证据；不在本节点预判视觉结论。\n5. 将需求、设计规范、场景说明、视口信息和原始证据交给 `visual-reviewer`，不提供实现者结论或预期缺陷。\n6. 修复功能验证失败项以及 `visual-reviewer` 报告的 BLOCKER、HIGH Findings，然后重新执行受影响路径、采集同场景证据并再次评审，直至功能验证通过且视觉评审为 PASS。MEDIUM、LOW 逐项处理或记录保留理由。\n7. 清理本次创建的临时数据和运行资源，不删除非本次创建的数据。\n\n## 产出与检查\n\n推进前确认：\n\n- 需求涉及的用户路径已通过真实浏览器操作验证，并观察到最终结果；\n- 页面结果、请求、反馈、错误处理、持久化和控制台均无未解决的严重问题；\n- 验收所需状态与视口已呈现，原始证据对应当前实现且可追溯；\n- `visual-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 修复后的受影响路径已重新验证并重新采证；\n- 临时数据和运行资源已按项目规则清理。\n\n## 任务差异处理\n\n根据需求和页面能力选择用户路径、状态、视口与证据，不套用固定 CRUD 或截图数量。某项不适用时说明理由，不得静默跳过。完全无法运行当前实现，或修复需要改变已确认需求、设计方向、公开契约或引入新依赖时，说明影响并暂停；验证与修订轮次按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将功能验证结论、已覆盖的用户路径、状态与视口、请求和控制台结果、原始证据引用、缺陷修复、未适用项及理由、`visual-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
86
121
|
"skills": [
|
|
87
|
-
"ui-verify",
|
|
88
|
-
"multimodal-vision",
|
|
89
|
-
"track-visual",
|
|
90
|
-
"config-ui",
|
|
91
122
|
"workflow-discipline"
|
|
92
|
-
]
|
|
123
|
+
],
|
|
124
|
+
"agents": [
|
|
125
|
+
"visual-reviewer"
|
|
126
|
+
],
|
|
127
|
+
"sourcePreset": {
|
|
128
|
+
"code": "verify-visual",
|
|
129
|
+
"version": "1.3.0",
|
|
130
|
+
"contentHash": "d9c7d39fcaf592cd",
|
|
131
|
+
"agents": [
|
|
132
|
+
"visual-reviewer"
|
|
133
|
+
]
|
|
134
|
+
}
|
|
93
135
|
},
|
|
94
136
|
{
|
|
95
137
|
"id": "UT_DESIGN",
|
|
96
|
-
"label": "
|
|
138
|
+
"label": "单元测试设计",
|
|
97
139
|
"phase": "test",
|
|
98
140
|
"track": "backend",
|
|
99
|
-
"prompt": "#
|
|
141
|
+
"prompt": "# 单元测试设计\n\n## 节点职责\n\n为本次生产代码设计可执行的单元测试计划，明确测什么、为什么测以及预期什么。本节点只产出测试设计，不编写或执行测试代码，并通过独立 `test-reviewer` 评审设计质量。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、非目标、技术方案、生产代码变更、编码决策，以及项目和所属模块的测试约束。加载 `workflow-discipline`，调用独立 `test-reviewer` 评审测试设计。\n\n读取现有测试目录、配置和相关用例，确认测试框架、命名、替身边界、覆盖要求及与其他测试层级的分工。信息缺失时先从仓库现状推导；仍无法确定关键行为或测试边界时，说明缺失信息并暂停。\n\n## 执行流程\n\n1. 从需求、技术方案和生产代码整理本次需要验证的行为单元，明确输入、输出、状态变化、错误和副作用。\n2. 为每个行为单元设计正常、边界和失败场景，并按实际行为补充状态恢复、幂等、重试、权限、并发或资源生命周期场景；不适用项无需制造用例。\n3. 为每个用例写明优先级、前置条件、输入、替身或数据准备、操作、观察点、预期结果及覆盖的行为或分支，使后续实现者无需猜测测试意图。\n4. 明确哪些依赖使用真实实现、替身或受控环境，避免过度 Mock 掩盖业务行为，也避免把跨系统路径误当单元测试。\n5. 逐项核对现有测试。标记为复用时，指出具体用例及其已覆盖的本次行为；需要调整或新增时明确差异，不用“已有覆盖”笼统跳过。\n6. 形成最终测试设计，包含范围与策略、行为单元、逐项用例、覆盖目标、测试层级边界、风险和不适用说明；不得包含可执行测试函数、断言代码或完整 fixture。\n7. 将需求、生产代码、项目测试约束、现有测试位置和测试设计交给 `test-reviewer`，不提供设计者结论或预期结果。修复 BLOCKER、HIGH Findings 后重新评审，直至获得 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- 生产变更与被测行为已逐项对应；\n- 每个行为单元都有明确场景、观察点和预期结果；\n- 关键边界、失败路径和副作用已覆盖，不适用项已有理由；\n- 替身、数据准备和测试层级边界合理；\n- 现有测试的复用、调整与新增判断均有具体依据；\n- 最终设计不包含可执行测试代码；\n- `test-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 测试设计已形成完整产物，登记值携带全文（超限时为路径引用且已说明理由）。\n\n## 任务差异处理\n\n根据被测行为选择覆盖维度，不机械套用固定方法或为不适用场景制造用例。纯文档、配置或其他不存在可单元验证行为的变更，应说明判断依据和后续适用的验证层级，不得静默产出空设计。评审修订与执行障碍按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将测试设计结论、范围、覆盖维度、现有测试复用判断、测试层级边界、风险与不适用项、设计产物（登记携带全文，超限时路径引用并说明理由）、`test-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
100
142
|
"skills": [
|
|
101
|
-
"code-philosophy",
|
|
102
|
-
"arch-review",
|
|
103
|
-
"track-ut-design",
|
|
104
|
-
"config-node",
|
|
105
143
|
"workflow-discipline"
|
|
106
|
-
]
|
|
144
|
+
],
|
|
145
|
+
"agents": [
|
|
146
|
+
"test-reviewer"
|
|
147
|
+
],
|
|
148
|
+
"sourcePreset": {
|
|
149
|
+
"code": "test-unit-design",
|
|
150
|
+
"version": "1.4.0",
|
|
151
|
+
"contentHash": "552a6b5c5c8a948c",
|
|
152
|
+
"agents": [
|
|
153
|
+
"test-reviewer"
|
|
154
|
+
]
|
|
155
|
+
}
|
|
107
156
|
},
|
|
108
157
|
{
|
|
109
158
|
"id": "UT_DEV",
|
|
110
|
-
"label": "
|
|
159
|
+
"label": "单元测试开发",
|
|
111
160
|
"phase": "test",
|
|
112
161
|
"track": "backend",
|
|
113
|
-
"prompt": "#
|
|
162
|
+
"prompt": "# 单元测试开发\n\n## 节点职责\n\n依据已确认的单元测试设计编写或调整测试代码，验证生产行为与需求一致。测试代码和必要的生产代码修复由当前执行者完成；测试命令交给独立 `test-executor` 执行，最终代码交给独立 `code-reviewer` 评审。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、技术方案、生产代码、单元测试设计、前序决策，以及项目和所属模块的测试约束。加载 `coding-standards`、`workflow-discipline`；出现测试失败且根因不明确时加载 `bugfix-root-cause-verification`。调用 `test-executor` 执行测试，调用 `code-reviewer` 审查代码变更。\n\n读取现有测试、配置和项目命令，确认框架、命名、替身、数据准备、覆盖目标和日志规则。缺少关键信息时先从仓库现状补齐；仍无法确定测试语义时说明缺失信息并暂停。\n\n## 执行流程\n\n1. 建立“测试设计用例 → 测试实现或已有用例”的逐项映射，明确新增、调整和复用范围。\n2. 按项目惯例实现测试，验证业务结果、状态变化、错误传播和必要副作用；替身只隔离单元边界，不掩盖被测行为。\n3. 完成一个测试文件或紧密相关的一组用例后，将明确的命令、范围和通过标准交给 `test-executor` 执行，并依据事实报告判断结果。\n4. 测试失败时读取完整证据。根因明确则做最小正确修复；根因不明确则按 `bugfix-root-cause-verification` 复现、提出并验证假设，确认根因后再修改测试、生产代码或环境。\n5. 修复后重新执行原失败范围及受影响回归。不得通过删除有效测试、skip/only、缩小应执行范围、放宽正确断言、吞异常、修改数据避开问题或硬编码结果制造通过。\n6. 所有设计用例实现后，先根据生产代码改动和依赖关系判定回归范围，无法可靠判断时扩大范围；范围判定完成后必须调用 `test-executor` 执行该回归范围。\n7. 检查设计映射、测试删除、skip/only、无效观察点、隔离性和覆盖统计，确认测试变更完整。\n8. 将需求、测试设计、项目约束和全部代码变更位置交给 `code-reviewer`，不提供实现者结论或预期结果。修复 BLOCKER、HIGH Findings 后重新执行受影响测试并复审，直至测试通过且评审为 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- 每个适用的测试设计用例都有对应实现或明确的已有测试；\n- 测试具有有效观察点，替身、数据和隔离方式符合项目约束；\n- 所有测试失败均在根因明确后修复，没有制造假绿；\n- `test-executor` 报告适用范围全部通过，失败为 0，未授权跳过为 0，日志可追溯；\n- 完整性检查通过，没有删除有效测试或遗漏设计用例；\n- `code-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 测试代码、必要的生产修复和执行报告已形成可引用产物。\n\n## 任务差异处理\n\n根据项目测试框架和变更范围选择实现与回归方式，不套用固定命令或覆盖率指标。测试设计中的用例确实不适用或已被等价测试覆盖时，说明具体依据。失败修复涉及破坏性契约、新依赖或真实范围扩张时先说明影响并暂停；同一问题多轮仍不收敛时按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将设计到实现的映射、测试代码变更、实际执行命令与范围、通过/失败/跳过统计、日志与报告引用、根因和修复、完整性结论、未适用项及理由、`code-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
114
163
|
"skills": [
|
|
115
|
-
"
|
|
116
|
-
"test-fix-loop",
|
|
117
|
-
"bugfix-root-cause-verification",
|
|
118
|
-
"track-ut-dev",
|
|
119
|
-
"config-node",
|
|
164
|
+
"coding-standards",
|
|
120
165
|
"workflow-discipline"
|
|
121
|
-
]
|
|
166
|
+
],
|
|
167
|
+
"agents": [
|
|
168
|
+
"test-executor",
|
|
169
|
+
"code-reviewer"
|
|
170
|
+
],
|
|
171
|
+
"sourcePreset": {
|
|
172
|
+
"code": "test-unit-implement",
|
|
173
|
+
"version": "1.3.1",
|
|
174
|
+
"contentHash": "34c3ea09310475d5",
|
|
175
|
+
"agents": [
|
|
176
|
+
"test-executor",
|
|
177
|
+
"code-reviewer"
|
|
178
|
+
]
|
|
179
|
+
}
|
|
122
180
|
},
|
|
123
181
|
{
|
|
124
182
|
"id": "E2E_DESIGN",
|
|
125
|
-
"label": "
|
|
183
|
+
"label": "端到端测试设计",
|
|
126
184
|
"phase": "test",
|
|
127
185
|
"track": "backend",
|
|
128
|
-
"prompt": "#
|
|
186
|
+
"prompt": "# 端到端测试设计\n\n## 节点职责\n\n判断项目是否存在适用的端到端测试体系；适用时为本次变更设计跨真实系统边界的可执行场景，不适用时记录依据。本节点只产出测试设计，不编写或执行测试代码，并通过独立 `test-reviewer` 评审设计质量。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、非目标、技术方案、生产代码与单元测试变更、前序决策，以及项目和所属模块的测试约束。加载 `workflow-discipline`，调用独立 `test-reviewer` 评审测试设计或不适用判断。\n\n读取项目提示词、测试说明、E2E 目录、配置、执行入口和现有用例，确认项目是否定义了 E2E 对象、边界、框架、环境和数据规则。缺少信息时先从仓库现状补齐，不凭通用惯例新建测试体系。\n\n## 执行流程\n\n1. 记录已检索的项目声明、目录、配置和现有用例，判断项目是否存在可用的 E2E 体系。\n2. 项目未定义 E2E 时，说明检索范围、判断依据及不引入新体系的结论，形成 N/A 产物后进入独立评审。\n3. 项目已定义 E2E 时，从需求和变更中识别必须跨真实边界验证的用户或系统路径，结合风险、现有覆盖和低层测试确定纳入与排除范围。\n4. 为每个场景写明标识、目标、优先级、前置条件、步骤、观察点、预期结果、数据准备、隔离和清理要求。场景应验证最终可观察结果，不只验证请求成功或调用发生。\n5. 覆盖正常、失败、权限、恢复、状态或兼容场景中的适用部分，并说明哪些行为已由单元或其他测试层级可靠覆盖，避免重复和遗漏。\n6. 形成最终设计，不包含测试函数、可执行 fixture、请求代码或浏览器操作代码。\n7. 将需求、生产变更、项目 E2E 约束、现有用例位置和测试设计交给 `test-reviewer`，不提供设计者结论或预期结果。N/A 时由 reviewer 核对判断依据；适用时修复 BLOCKER、HIGH Findings 后重新评审，直至获得 PASS。MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- 项目 E2E 体系的适用性已有仓库证据；\n- N/A 时已记录检索范围和判断依据，未擅自新建框架、目录或入口；\n- 适用时，覆盖范围与本次跨边界行为逐项对应，纳入和排除均有理由；\n- 每个场景的前置条件、步骤、观察点、预期结果和数据清理可供后续实现；\n- 与其他测试层级的边界明确，设计不含可执行测试代码；\n- `test-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- E2E 设计或 N/A 结论已形成完整产物，登记值携带全文（超限时为路径引用且已说明理由）。\n\n## 任务差异处理\n\n不默认逐接口覆盖，也不默认只测关键旅程；根据项目现有 E2E 体系、需求风险和低层覆盖确定范围。项目未定义 E2E 时不把本节点变成测试基础设施建设；若任务明确要求新建 E2E 体系，应将其作为范围与技术决策单独确认。执行障碍和评审修订按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将 E2E 适用性、检索范围与依据、覆盖范围、场景设计、测试层级边界、数据与清理策略、不适用项及理由、设计产物（登记携带全文，超限时路径引用并说明理由）、`test-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
129
187
|
"skills": [
|
|
130
|
-
"arch-review",
|
|
131
|
-
"track-e2e-design",
|
|
132
|
-
"config-node",
|
|
133
188
|
"workflow-discipline"
|
|
134
|
-
]
|
|
189
|
+
],
|
|
190
|
+
"agents": [
|
|
191
|
+
"test-reviewer"
|
|
192
|
+
],
|
|
193
|
+
"sourcePreset": {
|
|
194
|
+
"code": "test-e2e-design",
|
|
195
|
+
"version": "1.4.0",
|
|
196
|
+
"contentHash": "f35e7b66b9f55253",
|
|
197
|
+
"agents": [
|
|
198
|
+
"test-reviewer"
|
|
199
|
+
]
|
|
200
|
+
}
|
|
135
201
|
},
|
|
136
202
|
{
|
|
137
203
|
"id": "E2E_DEV",
|
|
138
|
-
"label": "
|
|
204
|
+
"label": "端到端测试开发",
|
|
139
205
|
"phase": "test",
|
|
140
206
|
"track": "backend",
|
|
141
|
-
"prompt": "#
|
|
207
|
+
"prompt": "# 端到端测试开发\n\n## 节点职责\n\n依据已确认的 E2E 设计实现并验证跨真实系统边界的测试场景；设计结论为 N/A 时复核依据并记录结果。测试代码和必要的生产代码修复由当前执行者完成；测试命令交给独立 `test-executor` 执行，最终代码交给独立 `code-reviewer` 评审。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、技术方案、生产代码、E2E 设计、单元测试结果、前序决策，以及项目和所属模块的测试约束。加载 `coding-standards`、`workflow-discipline`；测试失败且根因不明确时，再加载 `bugfix-root-cause-verification`。调用 `test-executor` 执行测试，调用 `code-reviewer` 审查代码变更。\n\n读取项目的 E2E 目录、配置、执行入口、邻近用例和环境规则。缺少关键信息时先从仓库现状补齐，不擅自引入项目未定义的测试体系。\n\n## 执行流程\n\n1. 读取 E2E 适用性结论并建立“设计场景 → 测试实现或已有用例”的逐项映射。\n2. 设计结论为 N/A 时，复核项目仍未定义适用的 E2E 体系；依据成立则记录 N/A，发现依据不成立则返回设计范围判断，不直接越过设计补写测试。\n3. 适用时，按项目现有框架和唯一执行入口实现测试，落实前置条件、操作步骤、观察点、预期结果、数据隔离和清理。测试必须经过项目定义的真实边界，并验证最终可观察结果。\n4. 完成一个场景或紧密相关的一组场景后，将明确的命令、范围和通过标准交给 `test-executor` 执行。\n5. 测试失败时读取完整证据。根因明确则做最小正确修复；根因不明确则按需加载 `bugfix-root-cause-verification`，确认根因后再修改测试、生产代码或环境。\n6. 修复后重新执行原失败场景及受影响回归。不得通过删除有效测试、skip/only、绕开真实边界、缩小应执行范围、放宽正确断言、吞异常或硬编码结果制造通过。\n7. 全部场景实现后，根据测试和生产代码改动确定 E2E 回归范围；无法可靠判断时扩大到项目 E2E 全量。生产代码发生修复时，同时确定并执行受影响的低层测试。\n8. 检查设计映射、测试删除、skip/only、断言有效性、真实边界、数据隔离、清理和环境可重复性。\n9. 将需求、E2E 设计、项目约束和全部代码变更位置交给 `code-reviewer`，不提供实现者结论或预期结果。修复 BLOCKER、HIGH Findings 后重新执行受影响测试并复审，直至测试通过且评审为 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n\n## 产出与检查\n\n推进前确认：\n\n- N/A 结论已有复核证据，或每个适用设计场景都有对应实现或明确的已有测试；\n- 测试遵循项目现有 E2E 体系并经过真实系统边界；\n- 观察点、数据隔离、清理和环境准备符合项目约束；\n- 所有失败均在根因明确后修复，没有制造假绿；\n- `test-executor` 报告适用 E2E 和必要的低层回归全部通过，失败为 0，未授权跳过为 0；\n- 完整性检查通过，日志和报告可追溯；\n- `code-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 测试代码、必要的生产修复和执行报告已形成可引用产物。\n\n## 任务差异处理\n\n项目没有适用的 E2E 体系时不新建框架、目录或执行入口。根据项目能力和设计范围选择测试、环境和回归方式，不套用固定浏览器、协议、命令或覆盖指标。失败修复涉及破坏性契约、新依赖或真实范围扩张时先说明影响并暂停；同一问题多轮仍不收敛时按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将 E2E 适用性复核、设计到实现的映射、测试代码变更、真实边界、数据与清理、实际执行命令和范围、通过/失败/跳过统计、低层回归、日志与报告引用、根因和修复、完整性结论、`code-reviewer` 结论与 Findings 处理情况写入当前节点记录。完成上述检查后推进下一节点。",
|
|
142
208
|
"skills": [
|
|
143
|
-
"
|
|
144
|
-
"track-e2e-dev",
|
|
145
|
-
"config-node",
|
|
209
|
+
"coding-standards",
|
|
146
210
|
"workflow-discipline"
|
|
147
|
-
]
|
|
211
|
+
],
|
|
212
|
+
"agents": [
|
|
213
|
+
"test-executor",
|
|
214
|
+
"code-reviewer"
|
|
215
|
+
],
|
|
216
|
+
"sourcePreset": {
|
|
217
|
+
"code": "test-e2e-implement",
|
|
218
|
+
"version": "1.3.0",
|
|
219
|
+
"contentHash": "55d0e8c282c8eb61",
|
|
220
|
+
"agents": [
|
|
221
|
+
"test-executor",
|
|
222
|
+
"code-reviewer"
|
|
223
|
+
]
|
|
224
|
+
}
|
|
148
225
|
},
|
|
149
226
|
{
|
|
150
227
|
"id": "INTEGRATE",
|
|
151
228
|
"label": "集成验证",
|
|
152
229
|
"phase": "test",
|
|
153
230
|
"track": "all",
|
|
154
|
-
"prompt": "#
|
|
231
|
+
"prompt": "# 集成验证\n\n## 节点职责\n\n将远程主线最新状态整合到任务分支，并在最终集成态执行适用回归，形成绑定明确版本的验证结论。版本控制与范围判断由当前执行者负责，测试命令交给独立 `test-executor` 执行；若产生代码修复，再交给独立 `code-reviewer` 评审。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、技术方案、实现与测试记录、`align-branch` 的基础分支与合并记录，以及项目的分支策略、测试体系和所属模块提示词。加载 `workflow-discipline`，调用 `test-executor` 执行回归；发生代码修复时调用 `code-reviewer`。测试失败且根因不明确时，再加载 `bugfix-root-cause-verification`。\n\n优先使用 `align-branch` 已记录的基础分支；记录缺失时，按与该节点相同的规则从任务上下文或项目提示词解析，例如 `main`、`master` 或 `dev`。仍无法解析时询问用户是否需要合并某个分支的远程代码，不根据版本历史猜测基础分支。\n\n## 执行流程\n\n1. 获取远程状态，优先读取 `align-branch` 记录的基础分支；记录缺失时从任务上下文或项目提示词解析，仍无法解析则询问用户。记录当前任务版本、基础分支、远程版本及判断依据。\n2. 用户明确表示无需合并时记录该决定；否则按项目策略整合基础分支的远程最新代码。发生冲突时理解双方意图后逐项融合并验证结果，不盲目选择任一侧；无法可靠解决时说明冲突与缺失决策并暂停。\n3. 汇总任务改动和主线整合改动，读取项目测试目录、配置、脚本与现有用例，列出适用的测试层级和执行入口；项目未定义的层级记录 N/A。\n4. 根据代码差异、模块依赖和测试映射确定回归范围。无法可靠判断某一层级的受影响范围时，将该层级扩大到全量。\n5. 将明确的命令、顺序、范围和通过标准交给 `test-executor` 执行，依据事实报告核对各层级统计、失败、跳过和日志。\n6. 测试失败时读取完整证据。根因明确则做最小正确修复；根因不明确则按需加载 `bugfix-root-cause-verification`，确认根因后再修改代码、测试或环境。\n7. 每次修复后重新执行原失败范围和受影响回归。不得通过删除有效测试、skip/only、缩小应执行范围、放宽正确断言、吞异常或硬编码结果制造通过。\n8. 检查新增 skip/only、测试删除、未执行的适用层级、范围遗漏和统计对账。发生代码修复时，将客观约束与变更位置交给 `code-reviewer`；修复 BLOCKER、HIGH Findings 后重跑受影响测试并复审，直至测试通过且评审为 PASS。\n9. 记录最终同步状态、实际回归范围、测试结果和已验证的提交或等价版本标识，确保后续能够判断证据是否仍有效。\n\n## 产出与检查\n\n推进前确认：\n\n- 基础分支沿用 `align-branch` 记录，或已按相同规则重新解析并留痕；\n- 基础分支的远程状态已获取并完成整合，或用户已明确表示无需合并；\n- 所有冲突均已理解并正确融合；\n- 项目适用测试层级与执行入口已识别，N/A 有具体依据；\n- 回归范围有代码差异、依赖或测试映射依据，无法判断的层级已扩大到全量；\n- `test-executor` 报告所有适用回归通过，失败为 0，未授权跳过为 0；\n- 所有失败均在根因明确后修复，没有制造假绿；\n- 发生代码修复时，`code-reviewer` 最终结论为 PASS；\n- 集成结论绑定明确版本，日志和报告可追溯。\n\n## 任务差异处理\n\n基础分支没有新提交时无需制造合并提交，但回归验证仍须执行。用户明确表示无需合并时保留决定并继续验证当前版本。根据项目实际体系选择测试层级和命令，不擅自引入未定义的测试类型。远程状态不可获取、冲突无法可靠解决，或修复涉及破坏性契约、新依赖和真实范围扩张时，说明证据与影响并暂停；同一问题多轮不收敛时按 `workflow-discipline` 处理。\n\n## 节点记录与推进\n\n将基础分支来源、同步策略与结果、任务和远程版本、冲突处理、适用测试层级、回归范围及依据、实际命令与统计、失败根因和修复、完整性检查、代码评审结果、日志与报告引用、最终已验证版本写入当前节点记录。完成上述检查后推进下一节点。",
|
|
155
232
|
"skills": [
|
|
156
|
-
"workflow-discipline"
|
|
157
|
-
|
|
158
|
-
|
|
233
|
+
"workflow-discipline"
|
|
234
|
+
],
|
|
235
|
+
"agents": [
|
|
236
|
+
"test-executor",
|
|
237
|
+
"code-reviewer"
|
|
238
|
+
],
|
|
239
|
+
"sourcePreset": {
|
|
240
|
+
"code": "test-integrate",
|
|
241
|
+
"version": "1.3.0",
|
|
242
|
+
"contentHash": "a29435e9ed9bbc68",
|
|
243
|
+
"agents": [
|
|
244
|
+
"test-executor",
|
|
245
|
+
"code-reviewer"
|
|
246
|
+
]
|
|
247
|
+
}
|
|
159
248
|
},
|
|
160
249
|
{
|
|
161
250
|
"id": "ACCEPT",
|
|
162
|
-
"label": "
|
|
251
|
+
"label": "发布验收",
|
|
163
252
|
"phase": "exit",
|
|
164
253
|
"track": "all",
|
|
165
|
-
"prompt": "#
|
|
254
|
+
"prompt": "# 发布验收\n\n## 节点职责\n\n核对最终集成验证证据与当前版本是否一致，向用户呈现可独立理解的验收摘要，并在用户明确确认后按项目策略归档代码。本节点不重复执行测试、代码评审或回归分析。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、验收标准、非目标、已激活节点的完成记录、`test-integrate` 的测试范围与结果、日志以及已验证版本标识，并读取项目分支与归档策略。加载 `workflow-discipline`。\n\n缺少集成验证证据、版本标识或前序完成记录时，先从任务上下文补齐；证据仍不完整或无法对应当前版本时停止验收，不推断通过。\n\n## 执行流程\n\n1. 确认所有已激活的前序节点均已完成，不写死某一模板路径下的节点清单。\n2. 比较当前生产代码与 `test-integrate` 绑定的已验证版本。存在新的生产代码变化时，退回集成验证重新判断范围并回归；纯文档或记录变化说明为何不影响证据。\n3. 逐条核对验收标准对应的实现位置和前序验证证据，并确认非目标未被误实现、范围变化已说明、所有 reviewer 的阻塞问题已解决。\n4. 汇总集成测试范围与统计、未授权跳过、实现与验收标准对应关系、范围变化、已知问题和风险，形成简洁且不依赖任务内部术语的验收摘要。\n5. 向用户呈现验收摘要并等待明确决定。只有明确的通过、确认归档或等价肯定表达构成确认；提问、条件句、部分认同、沉默或模糊表态不构成确认。\n6. 用户明确确认后，逐字记录确认原文，并按项目声明完成提交、合并、推送或其他代码归档动作。无项目策略时采用保留历史且可回退的常规方式，并记录采用的默认。\n7. 归档过程中遇到冲突或失败时先检查实际版本控制状态并自主诊断；无法可靠解决时说明当前状态和卡点，不猜测操作结果。\n\n## 产出与检查\n\n推进前确认：\n\n- 所有已激活前序节点已完成；\n- 集成验证证据完整，所有适用测试通过，失败为 0，未授权跳过为 0；\n- 当前生产代码与已验证版本一致；\n- 每条验收标准都有实现和验证证据，非目标、范围变化与已知问题已说明；\n- 没有未解决的 BLOCKER、HIGH 或其他流程定义的阻塞问题；\n- 用户已明确确认，确认原文已逐字记录；\n- 代码已按项目策略归档，最终提交、分支和远程状态可追溯。\n\n## 任务差异处理\n\n任务没有代码或项目没有分支归档流程时，执行适用的验收确认并说明不适用项。用户要求附条件通过或接受具体风险时，记录条件、风险和确认原文；未被明确接受的阻塞问题不得归档。证据过期、验收标准缺失或代码归档失败时，按实际问题返回相应节点处理，不在本节点重新执行其职责。\n\n## 节点记录与推进\n\n在用户确认前，将验收摘要、证据时效、验收标准对照、范围变化和已知问题写入当前节点记录并保持暂停。用户确认后，追加确认原文、归档策略与结果、最终提交和远程状态。完成上述检查后推进下一节点。",
|
|
166
255
|
"skills": [
|
|
167
|
-
"exit",
|
|
168
|
-
"config-node",
|
|
169
256
|
"workflow-discipline"
|
|
170
|
-
]
|
|
257
|
+
],
|
|
258
|
+
"agents": [],
|
|
259
|
+
"sourcePreset": {
|
|
260
|
+
"code": "release-accept",
|
|
261
|
+
"version": "1.3.0",
|
|
262
|
+
"contentHash": "d661172440a87940",
|
|
263
|
+
"agents": []
|
|
264
|
+
}
|
|
171
265
|
},
|
|
172
266
|
{
|
|
173
267
|
"id": "ARCHIVE",
|
|
174
268
|
"label": "架构信息归档",
|
|
175
269
|
"phase": "exit",
|
|
176
270
|
"track": "all",
|
|
177
|
-
"prompt": "#
|
|
271
|
+
"prompt": "# 架构信息归档\n\n## 节点职责\n\n从任务决策中筛选对未来设计持续有帮助的项目重大信息，形成架构信息修改计划，经独立 `arch-info-reviewer` 评审和用户明确确认后写入项目架构文档。没有合格条目是正常结果，本节点完成后任务正式收敛。\n\n## 依赖信息\n\n先检查当前任务上下文，读取需求、关键决策、技术方案、各节点记录、架构候选素材和发布验收结果，并读取项目及架构文档目录的提示词、记录标准、索引和相关现有条目。加载 `workflow-discipline`，调用独立 `arch-info-reviewer` 评审修改计划。\n\n项目已有架构文档体系时遵循其分类、命名、索引和写入规则。没有体系时先判断是否确有合格条目，不为“无新增”创建空目录或空文档。\n\n## 执行流程\n\n1. 汇总任务中的候选决策，逐条判断它是否会约束未来多个设计或实现，是否属于项目特有的重要业务规则、模块边界、技术选型、兼容策略或跨任务约束。\n2. 排除常规功能演进、局部实现、缺陷修复过程、工作流水和通用工程常识；说明不收录理由及更合适的载体，没有其他载体时保留在任务记录。\n3. 检索架构索引和相关正文，判断候选是新增主题、现有主题演进、替代或退役，避免创建重复或冲突条目。\n4. 形成修改计划：建议项写明主题、决策、未来约束、适用范围、目标文档及新增或演进方式；不收录项写明门槛结论。允许建议项为零。\n5. 将项目记录标准、现有相关文档、客观决策素材和修改计划交给 `arch-info-reviewer`，不提供撰写者结论或预期结果。修复 BLOCKER、HIGH Findings 后重新评审，直至获得 PASS；MEDIUM、LOW 逐项处理或记录保留理由。\n6. 向用户同时呈现修改计划和独立评审结论。只有明确批准、调整后批准、放弃或确认无新增构成决定；逐字记录用户原文。\n7. 仅写入用户批准的条目：按项目组织更新正文和索引，同主题优先演进；无批准条目时不创建或修改架构文档。\n8. 核对批准条目与实际写入、正文与索引、演进与替代关系。有文档变化时按项目策略提交并推送；无变化时记录跳过。\n\n## 产出与检查\n\n推进前确认：\n\n- 任务决策和候选素材已完整读取；\n- 所有候选均经过记录门槛判断，修改计划包含建议项和不收录理由；\n- 相关现有条目已检索，新增、演进、替代和退役关系明确；\n- `arch-info-reviewer` 最终结论为 PASS，所有 Findings 均已处理或说明；\n- 修改计划和评审结论已呈现用户，确认原文已逐字记录；\n- 仅有用户批准的条目被写入，正文与索引一致；\n- 无新增时未创建空文档，有变化时提交与远程状态可追溯；\n- 当前节点记录完整，任务可以正式收敛。\n\n## 任务差异处理\n\n项目没有架构体系但有获批的重大决策时，优先使用项目声明的文档根建立最小结构；无文档根声明时使用 `docs/architecture/`，只创建承载获批内容所需的文件。用户未批准修改计划时保持暂停，不提前写入。候选全部不达门槛时，呈现“无新增”及主要理由，经用户确认后正常完成。\n\n## 节点记录与推进\n\n将架构归档结论、候选过滤、修改计划、独立评审结论、用户确认原文、写入或不收录决定、架构文档与索引引用、提交和远程状态写入当前节点记录。完成上述检查后推进终态，使任务完成；在任务完成前不开始其他任务。",
|
|
178
272
|
"skills": [
|
|
179
|
-
"workflow-discipline"
|
|
180
|
-
|
|
181
|
-
|
|
273
|
+
"workflow-discipline"
|
|
274
|
+
],
|
|
275
|
+
"agents": [
|
|
276
|
+
"arch-info-reviewer"
|
|
277
|
+
],
|
|
278
|
+
"sourcePreset": {
|
|
279
|
+
"code": "archive-architecture",
|
|
280
|
+
"version": "1.3.0",
|
|
281
|
+
"contentHash": "67a6c3369ed12d82",
|
|
282
|
+
"agents": [
|
|
283
|
+
"arch-info-reviewer"
|
|
284
|
+
]
|
|
285
|
+
}
|
|
182
286
|
}
|
|
183
287
|
],
|
|
184
288
|
"edges": [
|
|
@@ -266,484 +370,142 @@
|
|
|
266
370
|
],
|
|
267
371
|
"layout": {
|
|
268
372
|
"PRD": {
|
|
269
|
-
"x":
|
|
270
|
-
"y":
|
|
373
|
+
"x": 252,
|
|
374
|
+
"y": 24
|
|
271
375
|
},
|
|
272
376
|
"ALIGN": {
|
|
273
|
-
"x":
|
|
274
|
-
"y":
|
|
377
|
+
"x": 244,
|
|
378
|
+
"y": 166
|
|
275
379
|
},
|
|
276
380
|
"DESIGN": {
|
|
277
|
-
"x":
|
|
278
|
-
"y":
|
|
381
|
+
"x": 242,
|
|
382
|
+
"y": 296
|
|
279
383
|
},
|
|
280
384
|
"CODE_BACKEND": {
|
|
281
|
-
"x":
|
|
385
|
+
"x": 180,
|
|
282
386
|
"y": 472
|
|
283
387
|
},
|
|
284
388
|
"CODE_UI": {
|
|
285
|
-
"x":
|
|
286
|
-
"y":
|
|
389
|
+
"x": 479.0010563085667,
|
|
390
|
+
"y": 511.4700938011274
|
|
287
391
|
},
|
|
288
392
|
"UI_VISUAL": {
|
|
289
|
-
"x":
|
|
290
|
-
"y":
|
|
393
|
+
"x": 480.00000000000006,
|
|
394
|
+
"y": 664
|
|
291
395
|
},
|
|
292
396
|
"UT_DESIGN": {
|
|
293
|
-
"x":
|
|
397
|
+
"x": 180,
|
|
294
398
|
"y": 616
|
|
295
399
|
},
|
|
296
400
|
"UT_DEV": {
|
|
297
|
-
"x":
|
|
401
|
+
"x": 180,
|
|
298
402
|
"y": 760
|
|
299
403
|
},
|
|
300
404
|
"E2E_DESIGN": {
|
|
301
|
-
"x":
|
|
405
|
+
"x": 180,
|
|
302
406
|
"y": 904
|
|
303
407
|
},
|
|
304
408
|
"E2E_DEV": {
|
|
305
|
-
"x":
|
|
409
|
+
"x": 180,
|
|
306
410
|
"y": 1048
|
|
307
411
|
},
|
|
308
412
|
"INTEGRATE": {
|
|
309
|
-
"x":
|
|
310
|
-
"y":
|
|
413
|
+
"x": 481.12871904380694,
|
|
414
|
+
"y": 1207.6653460717146
|
|
311
415
|
},
|
|
312
416
|
"ACCEPT": {
|
|
313
|
-
"x":
|
|
314
|
-
"y":
|
|
417
|
+
"x": 483.63604444938846,
|
|
418
|
+
"y": 1333.43167869324
|
|
315
419
|
},
|
|
316
420
|
"ARCHIVE": {
|
|
317
|
-
"x":
|
|
318
|
-
"y":
|
|
421
|
+
"x": 490.9029752350456,
|
|
422
|
+
"y": 1452.6083119553925
|
|
319
423
|
}
|
|
320
424
|
},
|
|
321
425
|
"isDefault": false,
|
|
322
|
-
"version": "3.
|
|
426
|
+
"version": "3.4.2"
|
|
323
427
|
},
|
|
324
428
|
"dependencies": {
|
|
325
429
|
"skills": [
|
|
326
430
|
{
|
|
327
|
-
"name": "
|
|
328
|
-
"description": "
|
|
329
|
-
"content": "#
|
|
330
|
-
"category": "domain",
|
|
331
|
-
"version": "1.1.0",
|
|
332
|
-
"references": [],
|
|
333
|
-
"scope": "project"
|
|
334
|
-
},
|
|
335
|
-
{
|
|
336
|
-
"name": "bugfix-root-cause-verification",
|
|
337
|
-
"description": "Use when 修复问题前需要根因验证——任何来源的 bug / 缺陷（测试失败、用户报告、线上 bug、代码审查发现等），原因不明或需系统化排查时。",
|
|
338
|
-
"content": "# Bugfix 根因验证子流程\n\n> **定位**：本 skill 是 系统化根因排查流程（复现→隔离→假设→验证）（通用调试方法论）在 dev-workflow DAG 任务上下文的特化版本。增加两个项目特定约束：**测试理解卡**（强制 8 字段）+ **决策分支**（对接 dev-workflow 节点流转）。\n>\n> **加载顺序**：先加载 系统化根因排查流程（复现→隔离→假设→验证） 形成假设并并行调查，进入\"定位根因\"阶段时加载本 skill 应用项目特定约束。\n\n## 触发条件\n\n满足以下任一条件即加载本 skill：\n\n1. **bugfix 类任务**进入需求录入前（task-create skill「PRD 跳过判定（bugfix 快速通道）」）\n2. **测试失败无法立即定位**（不属于\"显式断言失败\"或\"明显代码错误\"）\n3. 系统化根因排查流程（复现→隔离→假设→验证） 进入\"定位根因\"阶段\n4. 项目 AGENTS 纪律文件「测试 Iron Law」（测试 Iron Law）触发：未完成根因调查禁止提修复方案\n\n## 7 步子流程\n\n### 步骤 1 — 标注假设\n\n列出所有可能的根因假设，编号 H1/H2/H3...。\n\n要求：\n- 至少 3 个假设（对接 systematic-debugging 的 ≥3 假设原则）\n- 每个假设必须有**可证伪的判定条件**（如何证明/证伪这个假设）\n- 禁止\"猜测性\"假设（如\"可能是缓存问题\"），必须有依据（日志 / 栈 / 行为差异）\n\n### 步骤 2 — 收集失败事实\n\n复述可观测事实，**不臆测原因**：\n- 错误信息（异常类型 + message + 完整栈）\n- log 行（失败前后 20 行上下文）\n- FAIL 方法名（测试 class + method）\n- 失败时间点（哪个测试步骤 / 哪个 API 调用）\n- 数据状态（数据库 / 缓存 / 队列的当前值）\n\n**禁止**：\n- 用\"应该是\"/\"可能是\"开头描述事实\n- 跳过栈顶直接归因\n- 用历史经验替代当前证据\n\n### 步骤 3 — 复现\n\n用最小步骤**稳定复现**失败。\n\n| 情况 | 处理 |\n|---|---|\n| 可稳定复现 | 进入步骤 4 |\n| 偶发复现（<50% 概率）| 排查并发/时序/数据竞争，无法稳定 → 进入决策分支 7.4 |\n| 完全无法复现 | 进入决策分支 7.4（环境/数据问题，暂停上升） |\n\n**复现要求**：\n- 记录完整复现步骤（命令 / 数据 / 顺序）\n- 复现成功后立即保存现场（log + 截图 + 数据快照）\n- 禁止\"改了点代码再试\"绕过复现\n\n### 步骤 4 — 测试理解卡（8 字段强制填写）\n\n**HARD GATE**：未填写测试理解卡禁止进入步骤 5。\n\n逐字段填写（缺一不可，缺字段等同于未填）：\n\n| 字段 | 内容 | 示例 |\n|---|---|---|\n| 1. 失败 case 名 | 完整 class.method | `UserControllerTest.create_user_with_valid_data` |\n| 2. 业务能力 | 测试覆盖的业务场景 | \"创建用户（合法输入）\" |\n| 3. 前置数据 | 测试 setup 的数据 | \"已存在 user(id=1, email=test@a.com)；新建 user(id=2, ...)\" |\n| 4. 执行动作 | 测试触发的主操作 | \"POST /api/users，body={email: test@b.com, name: 'B'}\" |\n| 5. 断言目标 | 测试验证什么 | \"返回 201；DB user 表新增 1 行；email 字段值符合\" |\n| 6. 架构层级 | 测试穿透的架构层 | \"Controller → Service → Repository → DB\" |\n| 7. 数据隔离方式 | 测试如何避免互相污染 | \"@Transactional + @Rollback；每个 case 独立事务回滚\" |\n| 8. 初判假设 | 基于步骤 1-3 的初判 | \"H2 可能性最高：email 唯一约束未生效（事务回滚机制异常）\" |\n\n### 步骤 5 — 定位根因\n\n按以下 4 个手段**逐个**验证假设（对接 systematic-debugging 的并行调查用于初始假设筛选，本步骤是单一假设验证）：\n\n#### 5.1 链路追踪\n- 日志：失败前后的 log（按 项目 AGENTS 纪律文件「命令日志」HARD GATE 落盘的日志，从 `logs/` 读取）\n- 调用栈：完整的异常栈（不只是栈顶）\n- 数据流：从入口到失败点的数据传递路径\n\n#### 5.2 同类对比\n- 同一 case 在其他场景能通过 → 找差异点（数据 / 配置 / 环境 / 时序）\n- 同类 case（同 module 的其他 test）是否也失败 → 共同根因\n\n#### 5.3 单一假设验证（HARD GATE）\n- **一次验证一个 H**（禁止并发验证多个假设）\n- 验证手段必须**可观测**（添加 log / 断点 / 测试断言）\n- 验证结果记录：`H{N} → 验证方法 → 结果（confirmed / rejected / inconclusive）`\n\n#### 5.4 技术机制查源码优先\n- 涉及框架/库的行为，**先查源码**（参照 项目 AGENTS 纪律文件「信息推断权威」）\n- 禁止凭\"经验\"判断框架行为\n- 源码路径：`~/.m2/repository/`（maven）/ `node_modules/`（npm）\n\n### 步骤 6 — 产出结论\n\n输出根因结论，必须包含：\n- **根因陈述**：明确技术原因（不是症状描述）\n- **关联假设编号**：H{N} confirmed，其他 H{M} rejected 的理由\n- **证据链**：每条结论引用代码行号 / log 行 / 数据快照\n- **影响范围**：根因是否影响其他 case / 其他模块\n\n**反幻觉 HARD GATE**（对接 项目 AGENTS 纪律文件「信息推断权威」）：\n- 无源标注的结论标 `UNDOCUMENTED`，需补充证据\n- 推论性结论标 `INFERRED`，需说明推理链\n- 禁止 `AMBIGUOUS` 占位（必须二选一定性）\n\n### 步骤 7 — 决策分支（对接 dev-workflow）\n\n根据根因结论，按以下分支决策：\n\n| 分支 | 条件 | 动作 |\n|---|---|---|\n| **7.1 继续** | 根因匹配任务文件描述（属于当前任务范围） | 继续 dev-workflow 流程，按 systematic-debugging 修复 |\n| **7.2 暂停 — 任务范围漂移** | 根因不匹配任务文件（属于其他任务/其他模块） | 暂停，重新评估任务范围（可能需要拆分新任务） |\n| **7.3 暂停 — 升级 reviewer/用户** | 2 轮仍无法确定根因 | 按「自主优先方法论」暂停上升；先升级对应场景 reviewer 咨询，仍无果再上升用户 |\n| **7.4 暂停 — 环境/数据问题** | 现象无法稳定复现 | 暂停，排查环境/数据问题（并发 / 时序 / 外部依赖） |\n\n**升级格式**（暂停上升时）：\n- 现象（步骤 2 的失败事实）\n- 已尝试路径（步骤 5 验证过的假设清单 + 结果）\n- 卡点结论（当前最可能的根因 + 缺什么证据）\n- 候选方向（2-3 个可能的突破点）\n- 需用户/对应场景 reviewer 决策的具体问题\n\n## 与 系统化根因排查流程 的关系\n\n| 维度 | systematic-debugging（通用） | 本 skill（项目特定） |\n|---|---|---|\n| 假设数量 | ≥3 假设，并行调查 | 单一假设验证（步骤 5.3） |\n| 调查手段 | 形成假设 → 并行调查 → reviewer 升级 | 链路追踪 / 同类对比 / 单一验证 / 源码优先 |\n| 升级机制 | 2 轮失败 → 对应场景 reviewer → 用户 | 同 + 决策分支对接 task-create 流程入口 |\n| 强制约束 | 形成假设前禁止修 | **+ 测试理解卡 8 字段**（步骤 4） |\n| 输出 | 根因 + 修复方案 | 根因 + 决策分支（继续/暂停/升级） |\n\n**加载顺序**：\n1. 测试失败 → 加载 `systematic-debugging`\n2. 形成假设并并行调查\n3. 进入\"定位根因\"阶段 → 加载本 skill\n4. 填写测试理解卡 + 单一假设验证 + 决策分支\n5. 决策分支 7.1 → 回到 systematic-debugging 完成修复\n\n## 集成点\n\n- **task-create skill「PRD 跳过判定（bugfix 快速通道）」**：bugfix 类任务进入需求录入前必须先按本 skill 完成根因验证\n- **项目 AGENTS 纪律文件「测试 Iron Law」**：未完成根因调查禁止提修复方案 → 加载本 skill 完成根因验证\n- **test-fix-loop skill**：测试失败修复循环的根因分析阶段由本 skill 承担",
|
|
339
|
-
"category": "process",
|
|
340
|
-
"version": "4.2.2",
|
|
341
|
-
"references": [],
|
|
342
|
-
"scope": "global"
|
|
343
|
-
},
|
|
344
|
-
{
|
|
345
|
-
"name": "prd-design",
|
|
346
|
-
"description": "产品需求文档（PRD）撰写代理。通过对话明确需求后，按照产品思维方法论输出结构化 PRD。\n适用于独立开发者、全流程 AI 开发场景，PRD 的读者是 AI 编码代理。",
|
|
347
|
-
"content": "# PRD Writer\n\n你是一位资深产品经理，帮助团队撰写产品需求文档（PRD）。\n\nPRD 的读者是 AI 编码代理。你的目标是产出一份清晰、完整、有边界的文档，让编码代理可以直接基于它开始开发。\n\n## 核心思想\n\n### 内容公理：PRD = What + Why\n\n**PRD 回答两个问题：做什么（What）、为什么做（Why）。不回答怎么做（How）。**\n\n「怎么做」——技术选型、系统架构、API 设计、数据库 schema、代码逻辑、类结构——属于**技术方案**的范畴，不在这里讨论。\n\n写作时每句话都问自己：\n\n> 这句话帮助读者理解\"做什么\"或\"为什么做\"吗？\n> - 是 → 保留\n> - 它在描述具体怎么实现 → 不属于 PRD，删掉\n\n这个判断贯穿 PRD 写作的全过程。每个段落、每个章节、每个验收标准都适用。\n\n#### 如何用产品语言描述「做什么」\n\n描述系统行为时，只用产品语言：输入是什么、产出是什么、用户/系统看到什么结果。\n\n**有用户交互的功能**：用\"用户操作 → 系统响应\"交替模式。\n```\n1. 用户 {操作}\n2. 系统 {响应}\n3. 用户 {操作}\n4. 系统 {响应}\n```\n\n**无用户交互的后端功能**：用\"触发条件 → 行为结果\"模式，只写输入和产出。\n```\n1. {触发条件} → 系统 {产出/结果}\n2. {边界条件} → 系统 {处理方式}\n```\n\n❌ 泄漏实现的写法：\n- \"系统异步采集事件，写入内存缓冲区，定时批量刷入持久化存储\"\n- \"通过 Kafka 消息队列投递告警，Consumer 消费后调用告警平台 API\"\n\n✅ 用产品语言的写法：\n- \"限流触发后，系统记录限流事件（实体标识、限流类型、触发时间），同一分钟内相同维度的事件合并计数\"\n- \"告警触发后，系统向配置的接收人发送通知，内容包含实体名称、限流类型、触发次数\"\n\n**判断标准**：删掉某个技术名词后，产品行为的描述仍然完整准确 → 这个技术名词不该出现。\n\n### 问题空间与解决方案空间分离\n\n最好的产品团队（Intercom、Airbnb、Asana、Miro、Basecamp）都遵循这个实践。\n\n**问题空间**回答\"为什么做\"：用户面临什么痛点？市场有什么机会？不做会怎样？\n**解决方案空间**回答\"做什么\"：核心功能是什么？用户怎么使用？怎么算做成了？\n\n先彻底搞清楚问题，再开始设计解决方案。如果对问题的理解还有模糊的地方，不要急着写方案。\n\n### PRD 是\"just enough\"，不是越多越好\n\n参考 Atlassian 的 Agile PRD 理念：PRD 提供的是\"刚刚好\"的上下文，让开发者和产品经理对产品有共享理解。\n\n- 一份好的 PRD 让读者读完就能开始干活\n- 一份坏的 PRD 是什么都写了但读者不知道从哪下手\n- 删掉不影响理解的文字，就是好文字\n\n### 每个需求都要可验证\n\n参考 Google 和 Atlassian 的实践：每个功能都必须有明确的验收标准。如果无法定义\"怎么算做完了\"，说明这个功能还没想清楚。\n\n## PRD 各章节的内容归属\n\n每个章节有明确的内容目标。写作时对照此表，确保只写该写的内容。\n\n| 章节 | 回答什么问题 | 应该写 | 不属于这里 |\n| ---- | ------------ | ------ | ---------- |\n| 产品概述 | Why：为什么做 | 产品定位、解决什么问题、覆盖范围 | 技术栈、部署方式 |\n| 问题与用户 | Why：为谁解决什么 | 用户痛点、用户画像、使用场景、成功指标 | 系统架构、数据流向 |\n| 解决方案 | What：用户怎么用 | 用户旅程、交互流程、关键步骤 | 代码逻辑、算法描述 |\n| 功能需求 | What：具体做什么 | 行为描述、触发条件、异常分支、验收标准 | API 设计、数据库字段、类结构 |\n| 范围边界 | What：不做什么 | 明确排除的功能及原因 | 技术约束、框架限制 |\n| 补充信息（按需） | 依子章节而定 | 用户角色权限、数据实体(自然语言)、非功能要求 | 数据库 schema、系统架构设计 |\n| 开放问题 | 待澄清的事项 | 未决决策点及其影响 | — |\n\n**不属于的项不是\"被禁止\"——它们属于另一个文档（技术方案），只是不应该出现在 PRD 里。**\n\n## 工作流程\n\n### 阶段一：需求访谈\n\n不要直接写文档。先通过对话充分理解需求。每次只问一个问题，根据回答调整下一个。\n\n**第一步：确定范围**\n\n1. 这是新功能、功能增强、还是改动？改动不需要 PRD\n2. 预期开发周期？< 1 天 → 简化 PRD 或跳过；1-3 天 → 标准 PRD；> 3 天 → 完整 PRD\n3. 有参考产品或竞品吗？\n\n**第二步：逐层深入**\n\n从以下维度依次提问。一次一个维度，用户回答后再进入下一个：\n\n1. **产品定位** — 这是什么？一句话说清楚。属于什么类型？\n2. **问题** — 解决什么问题？谁受影响？有多痛？\n3. **用户** — 目标用户是谁？他们现在怎么解决的？\n4. **场景** — 用户从\"发现\"到\"完成\"的完整路径是什么？\n5. **核心功能** — 3-5 个必须有的功能是什么？按优先级排序（P0/P1/P2）\n6. **范围边界** — 第一版明确不做什么？为什么？\n7. **成功标准** — 怎么判断做对了？有哪些可衡量的指标？\n8. **约束** — 时间、性能、兼容性、平台上有哪些限制？\n\n如果用户提供的信息不足，主动追问。不要基于猜测补全信息。\n\n### 阶段二：确认理解\n\n用以下结构化模板向用户确认理解是否正确：\n\n```\n确认一下我的理解：\n\n**产品：** [名称] — [一句话描述]\n**目标用户：** [主要用户类型]\n**核心问题：** [要解决的用户痛点]\n**MVP 功能清单：**\n 1. [P0 功能 1]\n 2. [P0 功能 2]\n 3. [P0 功能 3]\n**成功标准：** [关键指标与目标值]\n**范围边界：** [明确不做的事]\n**约束：** [关键限制条件]\n\n以上理解准确吗？需要调整什么？\n```\n\n用户确认后方可进入下一阶段。\n\n### 阶段三：撰写 PRD\n\n按照 [references/template.md](references/template.md) 中的文档结构和写作规范输出 PRD。\n\n**写作自检**：每写完一个章节，对照「PRD 各章节的内容归属」表逐条检查：\n- 这段描述的是 What 或 Why？→ 保留\n- 这段描述的是具体怎么实现（How）？→ 删掉，记到技术方案的备忘录里\n\n写完 PRD 全文后，按照 [references/quality-checklist.md](references/quality-checklist.md) 进行整体自检（6 维度：完整性、一致性、清晰度、简洁性、逻辑合理性、内容公理符合度）。自检通过即可交付。正式 PRD 评审由开发流程 step-01 通过 `prd-review` skill 执行，不在此处进行。\n\n- 用户提供的原始需求如存在矛盾，在 PRD 中明确标注并给出 AI 的理解/建议，而非静默忽略",
|
|
431
|
+
"name": "workflow-discipline",
|
|
432
|
+
"description": "DAG 节点执行、角色分离、授权、暂停点与任务边界纪律",
|
|
433
|
+
"content": "# workflow-discipline\n\n保证所有 DAG 节点以一致方式确定工作边界、分离执行与验证、处理授权与暂停点，并在完成判定满足后安全推进。\n\n## 适用边界\n\n- 所有节点执行者都应用本 Skill；任务简单、用户催促或改动很小，不改变节点步骤、质量门和完成标准。\n- 本 Skill规定跨节点通用纪律，不替代当前节点提示词中的职责、产出、检查项和具体执行方法。\n- 当前节点提示词与本 Skill共同生效；发现冲突时不得自行忽略任一约束，应先按权限和任务边界判断，无法收敛再向用户呈现冲突。\n\n## 节点执行流程\n\n1. **确认当前边界**：读取任务上下文、当前节点职责、所需产出、完成判定、暂停点和项目约束。执行 git 操作前确认当前分支及项目声明的分支模型。\n2. **确定执行角色**：设计文档和编码由主会话完成；测试命令由 `test-executor` 执行；节点要求独立审查时，由不同 session 的只读 Verifier 执行。\n3. **完成节点工作**：只实施当前节点和已确认任务范围内的工作。发现死代码删留、顺手重构、范围扩张或其他范围外动作时，将其作为独立决策呈现给用户，不自行纳入。\n4. **执行独立验证**：Worker 与 Verifier 必须分离。Verifier 只接收评审对象路径、客观约束和参照位置，不接收设计结论、决策理由或“用户已确认”等预设结论。\n5. **处理审查结果**：审查是否通过，以 Verifier 本次输出为准。逐条修复 finding，或记录不修复理由；修复阻塞问题后重新审查。交互式审查最多 3 轮，连续 3 轮仍未通过时，保留在当前节点并请用户决定。\n6. **检查并记录**：逐项核对当前节点的完成判定，记录实际产出、检查结果、评审结论与轮次、关键决定、不适用项及其理由。\n7. **提交节点成果**：完成判定全部满足后、推进节点前，检查工作树和 diff。存在本节点产生的应提交改动时，只纳入当前任务与当前节点范围内的代码、测试、文档等成果并创建 git commit；不得混入无关改动，也不得用空提交代替成果提交。提交失败或本节点应提交改动仍有遗漏时，留在当前节点处理。\n8. **推进节点**：确认完成判定全部满足，且本节点应提交成果已经提交后，才按节点规定推进或进入暂停点。没有应提交改动的纯审查、纯审批节点直接推进，不制造空提交。\n\n## 执行与质量边界\n\n- Track 编码节点只修改生产代码，不修改测试或其他验证代码；测试节点不得以“现有测试已经覆盖”代替逐项验证。\n- 本任务改动导致的测试失败必须完成根因调查并处理，不得标记为“既有问题”后拒绝处理，也不得通过删除测试、放宽断言或添加 skip 制造通过。\n- 预算或时间不足是暂停并上升决策的理由，不是降低质量门的理由。\n- 已知问题必须逐条判断是否影响功能完整性；影响验收的，在任务结束前处理。只有用户明确接受风险并留下原文记录，才可作为例外。\n- 增量测试或增量评审只能缩小经过证据证明的受影响范围，不得降低原有测试、审查和通过标准。\n\n## 审查与委派规则\n\n- Worker 与 Verifier 使用不同 session；Verifier 只读，不修改代码或文档，不接管主会话协调。\n- 增量复审聚焦本轮改动及其影响面，但沿用完整审查标准。\n- 委派 prompt 使用七段结构：`IDENTITY → TASK → EXPECTED → CONTEXT → CONSTRAINTS → MUST DO / MUST NOT DO → VERIFICATION`。\n- `IDENTITY` 必须说明 agent 类型、读写边界、所需 Skill 和禁止再次委派；借用其他 Skill 时说明是执行该 Skill，还是仅借用其输出格式。\n- subagent 完成指定产出后立即结束；审查修订、重新委派和多轮协调由主会话负责。\n\n## 授权与暂停点\n\n- **决策授权**只覆盖具体方案或风险选择，不自动跳过审查、复审、测试或其他流程步骤。\n- **流程授权**只覆盖用户明确指名跳过的步骤，不得扩展到其他质量门。\n- “跳过人工审批”只跳过对应的用户暂停点，不等于跳过自动审查或验证。\n- 暂停点只有用户明确肯定当前待确认内容时才算通过，并记录用户原文。用户的提问、评估、条件句或新诉求不是确认；应先回应并继续等待明确结论。\n\n## 任务完成边界\n\n- 当前节点全部完成判定满足，且本节点产生的应提交成果已经提交后，才能推进到下一节点；单项测试通过、核心代码完成、存在未提交成果或分支合并，都不能代替节点完成。没有应提交改动的节点不制造空提交。\n- 节点完成不等于任务完成。架构信息归档完成，或该步骤经用户明确授权跳过并留下记录后，任务才进入终态。\n- 任务终止前，不推荐、不询问、不切换到下一个任务；终止后再输出完整任务总结。",
|
|
348
434
|
"category": "process",
|
|
349
|
-
"version": "
|
|
435
|
+
"version": "1.1.1",
|
|
350
436
|
"references": [],
|
|
351
437
|
"scope": "global"
|
|
352
438
|
},
|
|
353
439
|
{
|
|
354
|
-
"name": "
|
|
355
|
-
"description": "
|
|
356
|
-
"content": "#
|
|
440
|
+
"name": "tech-design",
|
|
441
|
+
"description": "将产品需求转化为可实现、可验证的技术设计",
|
|
442
|
+
"content": "# 技术方案设计\n\n将已确认的产品需求转化为可以直接指导实现和验证的技术设计。\n\n## 工作原则\n\n- 先理解需求、项目约束和现有架构，再选择技术方案。\n- 设计必须覆盖需求，但不扩张产品范围。\n- 关键决策说明备选方案、最终选择及取舍理由。\n- 设计到足以消除实现歧义为止，不编写生产代码或完整测试代码。\n- 根据任务范围调整设计深度，避免为简单任务堆叠无关内容。\n\n## 执行方法\n\n1. 建立需求、验收标准与设计内容的对应关系。\n2. 识别模块边界、核心流程及适用的数据和接口契约。\n3. 根据实际影响设计异常处理、安全、兼容迁移、发布回退和验证方式。\n4. 检查设计是否足以支持实现、测试和验收。\n5. 读取 `references/template.md` 形成技术方案；可以增加任务特有章节，但必须保留最低必备信息。\n\n## 模板使用规则\n\n所有技术方案必须包含：\n\n- 目标与范围；\n- 现状与约束；\n- 方案总览；\n- 需求与设计对应；\n- 关键决策；\n- 详细设计；\n- 验证方案；\n- 风险与开放问题。\n\n以下内容按任务实际影响填写：\n\n- 数据设计；\n- 接口与交互契约；\n- 安全与可靠性；\n- 发布、迁移与回退。\n\n按需章节不适用时，可以省略正文，但必须在“不适用项”中记录具体对象和理由。不得保留空章节，也不得只写“无影响”而不说明判断依据。\n\n## 设计边界\n\n允许使用字段表、接口 schema、状态机、时序图、决策表和测试矩阵表达设计。\n\n不写完整方法体、可直接执行的生产代码、完整测试代码或完整配置文件；这些内容属于后续实现节点。",
|
|
357
443
|
"category": "process",
|
|
358
|
-
"version": "
|
|
359
|
-
"references": [
|
|
444
|
+
"version": "1.0.0",
|
|
445
|
+
"references": [
|
|
446
|
+
{
|
|
447
|
+
"path": "references/template.md",
|
|
448
|
+
"content": "# <任务标题>技术方案\n\n> 输入需求：<PRD 或任务需求引用>\n> 状态：<草稿/已确认>\n> 版本：<版本>\n\n## 1. 目标与范围【必备】\n\n- 解决的问题：\n- 本次覆盖：\n- 明确不做：\n- 成功判定：\n\n## 2. 现状与约束【必备】\n\n说明现有架构、相关模块、项目规则、兼容要求和已知限制。\n\n## 3. 方案总览【必备】\n\n### 3.1 整体设计\n\n使用文字或图表说明模块关系、核心流程和数据流。\n\n### 3.2 需求与设计对应【必备】\n\n| 需求或验收项 | 对应设计章节 | 覆盖说明 |\n|---|---|---|\n\n### 3.3 关键决策【必备】\n\n| 决策点 | 备选方案 | 最终选择 | 取舍理由 |\n|---|---|---|---|\n\n## 4. 详细设计【必备】\n\n按功能或模块组织；每项说明：\n\n- 职责与边界；\n- 输入、输出和依赖；\n- 正常流程；\n- 异常与边界流程；\n- 数据或状态变化；\n- 与其他模块的交互；\n- 兼容与迁移影响。\n\n## 5. 数据设计【按需】\n\n说明数据结构、字段、约束、关系、索引、生命周期和存量数据处理。\n\n## 6. 接口与交互契约【按需】\n\n说明调用方、输入输出、错误响应、权限、幂等和兼容策略。\n\n## 7. 安全与可靠性【按需】\n\n说明权限边界、输入安全、敏感信息、一致性、部分失败、重试、恢复和回滚。\n\n## 8. 验证方案【必备】\n\n| 验证对象 | 验证层级 | 场景 | 预期结果 |\n|---|---|---|---|\n\n说明单元测试、集成测试、端到端测试和人工验证的边界。\n\n## 9. 发布、迁移与回退【按需】\n\n说明部署顺序、配置变化、数据迁移、兼容窗口、可观测信号、回退条件和回退步骤。\n\n## 10. 风险与开放问题【必备】\n\n| 风险或问题 | 影响 | 应对方式 | 状态 |\n|---|---|---|---|\n\n## 11. 不适用项【必备】\n\n列出模板中不适用于当前任务的内容及理由；没有时写“无”。"
|
|
449
|
+
}
|
|
450
|
+
],
|
|
360
451
|
"scope": "global"
|
|
361
452
|
},
|
|
362
453
|
{
|
|
363
|
-
"name": "
|
|
364
|
-
"description": "
|
|
365
|
-
"content": "#
|
|
454
|
+
"name": "coding-standards",
|
|
455
|
+
"description": "通用编码规范与多技术栈实现约束",
|
|
456
|
+
"content": "# 通用编码规范\n\n指导 AI 根据项目技术栈编写正确、清晰、可维护且可验证的代码。\n\n## 规则优先级\n\n依次遵循：\n\n1. 当前任务需求和已确认的技术方案；\n2. 项目及所属模块的提示词、技术栈和既有代码约定；\n3. 本 Skill 中与当前技术栈匹配的 reference；\n4. 本文的跨技术栈通用规则。\n\n技术栈 reference 用于补充语言和运行时特有约束，不覆盖项目已经明确的版本、框架、目录、接口和工具配置。\n\n## Reference 加载\n\n编码前识别当前改动实际涉及的技术栈，并读取所有匹配的 reference。\n\n常见组合：\n\n- TypeScript 后端：`typescript.md` + `node.md`\n- TypeScript 前端：`typescript.md` + `ui.md`\n- JavaScript 后端：`javascript.md` + `node.md`\n- JavaScript 前端：`javascript.md` + `ui.md`\n- 应用代码涉及关系数据库：对应语言 reference + `sql.md`\n- 构建或运维脚本：`shell.md`\n\n同一任务可以同时加载多个 reference。未来新增技术栈时，追加 reference 和本节路由即可，不重写通用规则。\n\n## 通用规则\n\n### 1. 先理解再修改\n\n先读取任务范围、技术方案、项目约束和相关现有代码。新增实现应沿用项目已经采用的架构、错误模型、命名、测试方式和工具链；不要仅因存在另一种惯用写法就替换既有设计。\n\n### 2. 在边界建立可信数据\n\n外部输入、配置、网络响应、持久化数据和跨模块数据进入内部逻辑前，应完成必要的解析、校验和归一化。进入内部后使用能够表达业务约束的类型或数据结构，不在每一层重复猜测和修补无效数据。\n\n### 3. 让状态与职责清楚\n\n优先用类型、枚举、状态机、约束和封装排除非法状态。互斥状态不要拆成可能相互矛盾的布尔值。每个模块、对象和函数保持单一、可说明的职责；没有实际复用或替换需求时，不提前增加抽象层。\n\n### 4. 让状态变化显式\n\n尽量减少共享可变状态和隐藏副作用。纯计算优先写成输入到输出的可预测函数；确实需要修改状态、执行 I/O 或操作外部系统时，把副作用集中在清楚的边界，并明确所有权、生命周期和执行顺序。\n\n这不是全面函数式要求。实体、缓存、缓冲区和框架管理对象可以按其职责保持可变。\n\n### 5. 正确表达失败\n\n区分预期失败、调用方错误、系统故障和内部不变量破坏，并使用当前技术栈惯用的错误机制表达。错误不得静默丢失；包装错误时保留原始原因和必要上下文。只有能够处理或转换错误的层才捕获错误。\n\n不要把所有失败都机械地转成异常、panic 或进程退出；具体边界以对应技术栈 reference 为准。\n\n### 6. 成对管理资源与并发生命周期\n\n文件、连接、锁、事务、流、线程、任务、订阅和临时资源必须有明确的创建、释放、取消和失败路径。优先使用语言或标准库提供的结构化资源管理方式。\n\n启动并发工作时，应能说明：\n\n- 谁拥有它；\n- 何时结束；\n- 如何取消；\n- 错误由谁接收；\n- 是否需要背压、限流或同步。\n\n### 7. 接口保持最小且稳定\n\n公开接口只暴露调用方需要的能力，优先使用能够表达语义的类型，不用无结构字符串、布尔开关或通用对象代替领域概念。兼容性、错误契约和副作用属于接口的一部分。\n\n抽象应来自已经出现的变化或复用需求，不为测试替身、未来设想或形式上的“解耦”提前创建接口。\n\n### 8. 可读性来自结构和命名\n\n控制流保持线性，优先处理边界和失败路径，避免不必要的深层嵌套。命名表达业务含义和单位，让调用处能够读懂意图。\n\n注释只说明代码本身无法表达的约束、业务原因、不变量、兼容考虑和安全前提，不复述代码行为。公开 API 是否需要文档注释，以及文档格式，按技术栈 reference 和项目约定执行。\n\n### 9. 让代码可验证\n\n核心逻辑应能在不依赖真实网络、文件、数据库、时钟或全局状态的情况下验证。外部系统集中在边界，并通过项目既有方式提供可替换入口。\n\n测试验证可观察行为、边界和失败路径，保持确定性与相互独立；不要为了方便测试而扭曲生产接口或增加没有业务价值的抽象。\n\n### 10. 工具负责机械规则\n\n缩进、换行、导入排序和其他机械格式服从项目已有 formatter、lint、编译器和静态分析配置。本 Skill 不重复这些工具能够可靠执行的规则。\n\n没有测量证据时不做性能微优化；先保证正确性和清晰度，再依据 profiling、运行指标或容量目标优化。\n\n## 完成检查\n\n编码完成前确认：\n\n- 已读取所有匹配的技术栈 reference；\n- 外部输入在边界得到处理，内部状态没有依赖隐含猜测；\n- 错误、资源和并发生命周期均有明确归属；\n- 新增抽象具有实际需求，未重复已有能力；\n- 注释只保留有长期价值的信息；\n- 代码符合项目现有 formatter、lint、编译和静态分析要求；\n- 受影响行为具有可验证路径。",
|
|
366
457
|
"category": "process",
|
|
367
|
-
"version": "
|
|
458
|
+
"version": "1.0.0",
|
|
368
459
|
"references": [
|
|
369
460
|
{
|
|
370
|
-
"path": "references/
|
|
371
|
-
"content": "#
|
|
461
|
+
"path": "references/dotnet.md",
|
|
462
|
+
"content": "# C# 与 .NET 编码规范\n\n- 开启 nullable reference types；可空值用 `?` 表达，`!` 只用于编译器无法证明但代码已有可靠不变量的场景。\n- 异常只用于异常情况；常见可预期失败优先 `Try*` 模式。捕获后使用裸 `throw` 保留堆栈，不主动抛出运行时保留异常类型。\n- I/O 使用 async 全链路；不得用 `.Result`、`.Wait()` 或同步阻塞方式等待 Task。`async void` 仅限事件处理器。\n- 独立库代码按项目分析规则决定是否使用 `ConfigureAwait(false)`；应用层不机械添加。\n- 长时间或异步公开操作接收并向下传递 `CancellationToken`；协作取消不是普通失败。\n- 拥有 `IDisposable` 或 `IAsyncDisposable` 资源的对象负责释放；优先使用 `using`、`await using`，Dispose 应幂等。\n- 异步路径不跨 `await` 持有 `lock`；使用适合异步的同步原语。简单原子状态优先使用 `Interlocked`。\n- 纯数据和值语义模型可以使用 record；实体、可变状态和依赖引用相等的模型使用 class。注意 `with` 是浅拷贝。\n- 公开 API 遵循 Framework Design Guidelines；内部实现不为形式一致性过度暴露。\n- LINQ 查询存在延迟执行；避免无意的重复枚举，需要复用结果时明确物化。\n- ASP.NET Core 请求路径不执行同步阻塞或 `Task.Run` 伪异步；HttpClient 和依赖生命周期交给项目既有宿主管理方式。\n- 测试保持快速、隔离、可重复和自检；时钟、文件、网络、数据库等外部依赖通过明确边界替换。\n\n依据：dotnet/docs、dotnet/runtime、dotnet/csharplang、dotnet/AspNetCore.Docs 官方仓库。"
|
|
463
|
+
},
|
|
464
|
+
{
|
|
465
|
+
"path": "references/go.md",
|
|
466
|
+
"content": "# Go 编码规范\n\n- 错误是普通返回值，必须显式检查；不得用 `_` 静默丢弃可能影响结果的错误。\n- 错误消息以小写开始且不以句号结束。调用方需要判断错误时，使用稳定哨兵或自定义类型配合 `errors.Is`、`errors.As`。\n- 增加上下文时使用 `%w` 保留错误链；公开函数返回 `error` 接口，不返回可能形成“非空接口包裹空指针”的具体错误指针。\n- 接口由消费方按需要定义，并保持最小；实现方通常返回具体类型，不为测试替身或未来设想提前创建接口。\n- 修改接收者、包含锁或复制成本较大的类型使用指针 receiver；同一类型的方法保持 receiver 选择一致。\n- `context.Context` 作为第一个参数传递，不存入结构体，不自定义替代类型。\n- 每个 goroutine 都必须有明确退出、取消和错误接收路径；阻塞 goroutine 不会由垃圾回收器自动清理。\n- 默认提供同步 API，由调用方决定是否并发。共享状态可使用 channel 或锁，按语义选择，不机械套用口号。\n- 资源获取后立即安排 `defer` 清理；理解 defer 参数立即求值和后进先出语义。\n- 类型尽量让零值可用；不要仅为微小复制成本把所有参数改成指针。\n- 包名、接收者和导出名称遵循 Go 惯例；导出声明的 doc 注释以声明名称开头。\n- 格式完全交给 `gofmt`/`goimports`；测试失败信息包含输入、got 和 want，重复场景使用表驱动测试。\n\n依据：golang/website、golang/wiki、golang/go 官方仓库。"
|
|
372
467
|
},
|
|
373
468
|
{
|
|
374
|
-
"path": "references/
|
|
375
|
-
"content": "#
|
|
469
|
+
"path": "references/java.md",
|
|
470
|
+
"content": "# Java 编码规范\n\n适用于现代 Java 应用和库。项目使用 Spring、JPA 等框架时，再叠加项目自身框架约束。\n\n- 公开接口默认非空；可空参数或返回值应显式标注。集合和数组无结果时返回空值对象，不返回 `null`。\n- `Optional` 主要用于表达“单个返回值可能不存在”，不作为字段、参数或集合元素使用。\n- 优先基本类型；金额和精确十进制计算使用 `BigDecimal`，不用浮点数代替。\n- 异常只表达异常路径，不用于普通控制流。优先标准异常；跨层传播时转换为当前层语义并保留原因。\n- `catch` 不得静默吞错。确实无需处理时，注释说明为什么可以安全忽略。\n- `AutoCloseable` 资源使用 try-with-resources；跨对象生命周期资源由明确的拥有者释放。\n- 共享可变状态使用同步或并发工具；优先不可变对象，但不强制实体、DTO 和内部缓冲区不可变。\n- 面向接口声明集合等依赖；重写 `equals` 时同时重写 `hashCode`。\n- 公开 API 保持最小暴露，并以 Javadoc 说明契约、异常、副作用和线程安全要求；自解释的内部成员不强制注释。\n- Spring 单例组件默认跨请求共享，组件字段应为依赖或不可变配置；JPA 实体的相等性不得依赖会在持久化过程中变化的值。\n\n依据：OpenJDK、Google Java Style Guide、Spring Framework 官方仓库文档。"
|
|
376
471
|
},
|
|
377
472
|
{
|
|
378
|
-
"path": "references/
|
|
379
|
-
"content": "#
|
|
473
|
+
"path": "references/javascript.md",
|
|
474
|
+
"content": "# JavaScript 编码规范\n\n适用于未由 TypeScript 类型系统约束的现代 JavaScript。Node.js 和 UI 规则分别叠加对应 reference。\n\n- 默认 `const`，需要重新赋值时使用 `let`，不使用 `var`。\n- 使用 `===` 和 `!==`；仅在明确需要同时匹配 `null` 与 `undefined` 时使用 `value == null`。\n- 默认值只针对空值时使用 `??`，不要用 `||` 意外覆盖 `0`、空字符串或 `false`。\n- 可选链只保护其直接访问链；后续调用或运算仍需处理 `undefined`。\n- 使用 `Number.isNaN` 判断 `NaN`，不用 `value === NaN` 或带隐式转换的全局 `isNaN`。\n- 只抛出 `Error` 或其子类；包装错误使用 `cause` 保留原始原因。\n- Promise 链保持平坦并返回内部 Promise；错误在链尾或明确的局部恢复点处理。\n- 根据业务语义选择 `Promise.all`、`allSettled`、`any` 或 `race`，不要把它们视为可互换工具。\n- 数组和可迭代对象使用 `for...of` 或数组方法；对象键使用 `Object.keys`、`Object.entries` 和 `Object.hasOwn`。\n- ESM 和 class 自动处于严格模式；遗留脚本是否声明严格模式按项目环境决定。\n- 注释说明业务原因和约束，不复述代码。\n\n依据：eslint/eslint、mdn/content；Google JavaScript Guide 已冻结，仅用于命名和注释的一般原则。"
|
|
475
|
+
},
|
|
476
|
+
{
|
|
477
|
+
"path": "references/node.md",
|
|
478
|
+
"content": "# Node.js 运行时与服务端规范\n\n与 TypeScript 或 JavaScript reference 共同使用。\n\n- 请求处理路径不使用同步文件、进程、压缩和加密 API。CPU 密集工作移出事件循环，并使用有界 worker 或进程池。\n- 明确处理四类错误通道：同步异常、Promise rejection、EventEmitter `error` 事件和 Stream 错误；一种通道的处理方式不能替代另一种。\n- Promise 必须被 `await`、返回或显式捕获；异步事件监听器必须自行处理 rejection。\n- 包装错误使用 `cause`；程序分支依据稳定错误类型或错误码，不匹配 message 文本。\n- 会发出 `error` 的 EventEmitter 必须有错误处理；监听器数量异常先调查泄漏，不直接提高限制。\n- 流式处理尊重 `write`、`push` 的背压信号；多流串联优先 `pipeline`，并处理其销毁底层资源的语义。\n- `uncaughtException` 只用于同步清理和退出，不用于恢复运行。进程重启交给外部监督者。\n- 避免用 `process.exit()` 截断异步输出和清理；优先设置退出码并让事件循环自然结束。\n- 请求体、JSON 结构、正则、路径和命令参数都视为不可信输入；执行子进程优先参数数组，不拼接 shell 命令。\n- 请求上下文使用 `AsyncLocalStorage` 等明确机制，不用模块级可变变量在并发请求间传递上下文。\n- 定时器、连接、流、worker 和订阅必须具备关闭或取消路径；测试结束前清理所有活动句柄。\n\n依据：nodejs/node、nodejs/learn、OWASP CheatSheetSeries 官方仓库。"
|
|
479
|
+
},
|
|
480
|
+
{
|
|
481
|
+
"path": "references/python.md",
|
|
482
|
+
"content": "# Python 编码规范\n\n- 公共接口提供类型标注，但不得把类型注解当成运行时校验；需要运行时约束时在边界显式解析。\n- 需要“任意但仍受类型保护”的值时优先 `object`，慎用会关闭检查链的 `Any`。\n- 数据容器优先考虑 `dataclass`；可变对象不要强行实现哈希，值对象可使用 `frozen=True`。\n- Python 惯用 EAFP：可恢复的异常情况先执行再捕获；普通业务分支仍使用清楚的条件判断。\n- 只捕获能够处理的具体异常。裸 `except` 禁止；最外层 `except Exception` 仅用于记录、转换或重新抛出。\n- 自定义异常继承 `Exception` 并以 `Error` 结尾；跨层转换使用 `raise ... from ...` 保留原因链。\n- 文件、锁、连接和临时资源使用 `with`；没有现成上下文管理器时用 `contextlib` 封装。\n- 禁止可变默认参数；使用 `None` 或独立哨兵，并在函数体内创建新对象。\n- 不在迭代期间修改当前集合；一次性迭代器需要多次使用时先明确物化。\n- 公共 API 编写 docstring；实现注释说明原因，不重复签名或类型信息。\n- 不吞掉 `asyncio.CancelledError`；清理完成后继续传播，并优先使用结构化并发原语。\n- FastAPI、Django、pandas 等规则仅在项目确实采用对应框架时叠加，不作为 Python 语言硬规则。\n\n依据：python/peps、python/cpython、FastAPI、Django 和 pandas 官方仓库文档。"
|
|
483
|
+
},
|
|
484
|
+
{
|
|
485
|
+
"path": "references/rust.md",
|
|
486
|
+
"content": "# Rust 编码规范\n\n- 使用 `Option`、`Result`、enum、新类型和私有字段表达值域与状态；能够由类型排除的非法状态不留到运行时猜测。\n- 可恢复或预期失败返回 `Result` 并用 `?` 传播；错误类型提供可读上下文和原因链，不使用 `()` 作为公开错误类型。\n- `panic` 只用于调用方违反契约、内部不变量破坏或继续执行不安全的情况；解析、I/O、网络和业务校验失败返回 `Result`。\n- `unwrap`、`expect` 仅用于测试、原型或已有不变量能够证明成功的场景；后者使用 `expect` 说明为什么不可能失败。\n- 只读时借用，修改时使用可变借用，转移所有权时按值传递；不要用无意义的 `clone` 或 `unsafe` 绕开所有权设计问题。\n- 默认不写 `unsafe`。确需使用时将块保持最小，封装在安全 API 内，并以 `SAFETY` 注释或 `# Safety` 文档说明必须维持的不变量。\n- `Send`、`Sync` 依赖编译器自动推导；手写 `unsafe impl` 前必须证明任意安全调用方都无法触发数据竞争或未定义行为。\n- 公开 API 按语义实现适用的通用 trait；转换优先实现 `From`、`TryFrom`，不直接实现已有 blanket implementation 的反向 trait。\n- 公开函数可能失败、panic 或要求 unsafe 前提时，分别编写 `# Errors`、`# Panics`、`# Safety`。\n- 文档示例使用 `?` 处理错误，并作为 doctest 保持可执行。unsafe 相关代码除常规测试外使用 Miri 等工具增强验证。\n- 格式交给 rustfmt，静态问题交给 Clippy；不要把 Clippy 的所有 restriction 规则无差别提升为项目硬门。\n\n依据：Rust Book、Rust Reference、Rust API Guidelines、rust-lang 官方仓库。"
|
|
487
|
+
},
|
|
488
|
+
{
|
|
489
|
+
"path": "references/shell.md",
|
|
490
|
+
"content": "# Shell 与 Bash 编码规范\n\nShell 适合构建、发布、运维和简单胶水任务。脚本过长或控制流复杂时，改用结构化语言。\n\n- 默认使用 Bash 时明确 shebang 和最低版本；只有交付环境要求 `/bin/sh` 时才采用 POSIX sh，两种语法边界不混写。\n- 变量、命令替换和路径展开默认加双引号。参数列表使用数组并以 `\"${array[@]}\"` 展开。\n- 文件列表不解析 `ls` 输出；使用 glob、`find -print0`、`readarray` 等能够保留文件名边界的方式。\n- `set -euo pipefail` 不是完整错误处理方案：`-e` 在条件、管道、函数和命令替换中的行为有例外，`pipefail` 也可能把预期 SIGPIPE 判为失败。\n- 必须成功的步骤显式写出失败处理，如 `command || return` 或 `command || exit`；预期可能失败的命令在条件表达式中判断。\n- 使用 `if command` 或 `if ! command` 检查结果，不通过稍后的 `$?` 判断；错误消息写入 stderr。\n- `read` 使用 `-r`；需要原样读取行时同时设置 `IFS=`。\n- 临时文件和目录使用 `mktemp`，并用 `trap ... EXIT` 清理；不用 PID 拼接可预测临时路径。\n- 不使用 `eval`，不把外部输入拼成命令字符串；命令及参数通过数组或正常参数边界传递。\n- 外部依赖使用 `command -v` 检查；函数内变量使用 `local`，需要保留命令退出码时将声明与命令替换分开。\n- 静态检查使用 ShellCheck；脚本验收同时检查退出码和关键输出或实际结果，不能只信退出码。\n- 格式和低价值样式差异服从项目已有工具与脚本约定。\n\n依据：Google Shell Style Guide、ShellCheck、GNU Bash 与 GNU Coreutils。Bash GitHub 镜像使用 `gnu-mirror-unofficial/bash`，不引用不存在的 `bminor/bash`。"
|
|
491
|
+
},
|
|
492
|
+
{
|
|
493
|
+
"path": "references/sql.md",
|
|
494
|
+
"content": "# SQL 与关系数据库规范\n\n本文件只规定跨关系数据库的共同原则。隔离级别、NULL、索引、在线 DDL 和错误码的具体语义必须再核对当前数据库与版本。\n\n- 所有外部值使用参数化查询或驱动提供的绑定参数；不得用字符串拼接、转义替代参数化。\n- 关键业务约束同时落入数据库约束，如主键、外键、唯一性、非空和检查约束；应用校验不能替代数据库最终保护。\n- 事务边界保持明确且尽量短，只覆盖必须原子完成的操作；网络调用和长时间计算通常不放在事务内部。\n- 根据业务一致性要求选择隔离级别，不依赖数据库默认值。明确评估丢失更新、不可重复读、幻读和写偏差。\n- 序列化失败和死锁只能在操作可安全重试时重试，并设置次数、退避和最终失败处理。\n- 查询显式列出所需字段，不使用 `SELECT *` 作为稳定接口；批量操作使用数据库或驱动的批处理能力，避免逐行往返。\n- 索引来自实际查询、排序和约束需要；使用执行计划和运行指标验证，不为每个字段机械建索引。\n- NULL 使用数据库三值逻辑处理；唯一约束、聚合和排序中的 NULL 行为按当前数据库版本核对。\n- Schema 变更优先采用兼容性演进：先扩展、再迁移、再切换读取、最后收缩；大表变更先确认锁和在线能力。\n- 已部署的版本化迁移不修改其语义内容；修复通过新迁移完成。回滚能力需要单独设计，不能假设迁移工具自动提供。\n- 动态表名、列名和排序字段不能通过普通参数绑定，必须由受控白名单映射。\n- 性能结论以真实执行计划、数据规模和运行指标为依据，不凭 SQL 文本外观判断。\n\n依据：postgres/postgres、MicrosoftDocs/sql-docs、OWASP CheatSheetSeries、Flyway 与 Liquibase 官方仓库。MySQL 方言资料只有官网正文，不作为跨数据库硬规则。"
|
|
495
|
+
},
|
|
496
|
+
{
|
|
497
|
+
"path": "references/typescript.md",
|
|
498
|
+
"content": "# TypeScript 编码规范\n\n- 项目默认开启 `strict`。新项目推荐同时启用 `noImplicitOverride`、`noImplicitReturns`、`noFallthroughCasesInSwitch`；其他严格选项按存量迁移情况逐步开启。\n- 禁止让 `any` 进入内部逻辑；未知输入使用 `unknown`，完成收窄或边界解析后再使用。\n- 类型断言和非空断言没有运行时保护，只作为最后手段。优先使用 `typeof`、`instanceof`、判别字段和类型守卫。\n- 外部数据在边界执行运行时解析；TypeScript 类型声明本身不能证明网络、配置或持久化数据有效。\n- 互斥状态使用可辨识联合，并用 `never` 检查穷尽性；不要用多个可能矛盾的可选字段或布尔值表达同一状态机。\n- 对象形状优先 `interface`，联合、映射和条件类型使用 `type`。对象字面量使用类型注解或 `satisfies`，不要用 `as` 掩盖字段错误。\n- Promise 不得悬空；只抛出或拒绝 `Error` 实例。捕获值按 `unknown` 处理，包装时保留 `cause`。\n- 默认 `const`；只读参数和属性用于表达不修改意图，但不把浅层 `readonly` 误认为运行时深不可变。\n- 使用 ESM 与 `import type`；是否允许其他模块形态，以项目运行时和构建配置为准。\n- 使用 `===` 和 `!==`；只有项目明确采用 `value == null` 同时判断 `null`/`undefined` 时例外。\n- JSDoc 不重复 TypeScript 已表达的类型；实现注释只说明原因、约束和不变量。\n- formatter、lint 和 tsconfig 的项目现值优先，不在业务代码中手工创造另一套风格。\n\n依据：microsoft/TypeScript-Website、typescript-eslint、Google TypeScript Style Guide。"
|
|
499
|
+
},
|
|
500
|
+
{
|
|
501
|
+
"path": "references/ui.md",
|
|
502
|
+
"content": "# UI 与 React 编码规范\n\n与 TypeScript 或 JavaScript reference 共同使用。具体组件库、样式框架和数据层服从项目配置。\n\n- 原生语义元素优先于 ARIA 和自绘控件；必须自定义时，同时实现可访问名称、键盘行为和焦点管理。\n- React 组件渲染保持幂等，不在渲染期修改 props、state、全局对象或既有数据。\n- 状态保持最小：能从 props 或现有 state 推导的值在渲染期计算，不重复存储。\n- 互斥界面状态用单一状态机表达，不用可能同时为真的多个布尔值。\n- Effect 只用于同步外部系统；用户事件在事件处理器中执行，渲染数据直接计算。\n- Effect 中的订阅和异步操作必须清理，并防止过期响应覆盖新状态。已有数据层时优先使用其缓存、取消和竞态能力。\n- 列表 key 必须稳定、唯一且来自数据；动态列表不使用数组下标或渲染时随机值。\n- 数据区域显式处理加载、空、错误、成功和边界状态，并为用户提供可执行的下一步。\n- 表单优先使用原生约束；客户端校验用于反馈，服务端仍须验证。错误信息与字段建立可访问关联。\n- 对话框打开时焦点进入，Tab 保持在内部，Escape 可关闭，关闭后焦点返回触发点。\n- `memo`、`useMemo`、`useCallback` 只用于经过测量的性能问题，不作为默认编码模板。\n- 测试用户可见行为，优先通过 role、label 和可见文本定位；只有无法表达用户语义时使用 test id。\n\n依据：reactjs/react.dev、w3c/aria-practices、mdn/content、Testing Library、Playwright 官方仓库。"
|
|
380
503
|
}
|
|
381
504
|
],
|
|
382
505
|
"scope": "global"
|
|
383
|
-
},
|
|
384
|
-
{
|
|
385
|
-
"name": "code-philosophy",
|
|
386
|
-
"description": "Internal logic & data flow philosophy (5 Laws of Elegant Defense). 由 dev-workflow 编排调用。",
|
|
387
|
-
"content": "# Internal Logic Philosophy: The 5 Laws of Elegant Defense\n\n**Role:** Principal Engineer for all **Internal Logic & Data Flow** — applies to backend, React components, hooks, state management, and any code where functionality matters.\n\n**Philosophy:** Elegant Simplicity — code should guide data so naturally that errors become impossible, keeping core logic flat, readable, and pristine.\n\n## The 5 Laws\n\n### 1. The Law of the Early Exit (Guard Clauses)\n- **Concept:** Indentation is the enemy of simplicity. Deep nesting hides bugs.\n- **Rule:** Handle edge cases, nulls, and errors at the very top of functions.\n- **Practice:** Use `if (!valid) return; doWork();` instead of `if (valid) { doWork(); }`.\n\n### 2. Make Illegal States Unrepresentable (Parse, Don't Validate)\n- **Concept:** Don't check data repeatedly; structure it so it can't be wrong.\n- **Rule:** Parse inputs at the boundary. Once data enters internal logic, it must be in trusted, typed state.\n- **Why:** Removes defensive checks deep in algorithmic code, keeping core logic pristine.\n\n### 3. The Law of Atomic Predictability\n- **Concept:** A function must never surprise the caller.\n- **Rule:** Functions should be \"Pure\" where possible. Same Input = Same Output. No hidden mutations.\n- **Defense:** Avoid `void` functions that mutate global state. Return new data structures instead.\n\n### 4. The Law of \"Fail Fast, Fail Loud\"\n- **Concept:** Silent failures cause complexity later.\n- **Rule:** If a state is invalid, halt immediately with a descriptive error. Do not try to \"patch\" bad data.\n- **Result:** Keeps logic simple by never accounting for \"half-broken\" states.\n\n### 5. The Law of Intentional Naming & Purposeful Comments\n- **Concept:** Good naming reduces the need for trivial comments, but meaningful comments are essential for understanding.\n- **Rule:** Variables and functions must be named so clearly that logic reads like an English sentence. Comments should explain WHY and business context, not restate WHAT the code does.\n- **Defense:** `isUserEligible` is better than `check()`. But a complex business rule still needs a comment explaining the reasoning.\n- **Comment Requirements (MANDATORY):**\n - **Classes:** Every class must have a concise comment describing its purpose and responsibility.\n - **Complex methods:** Methods with non-trivial business logic must have a brief comment explaining the business intent.\n - **Complex flows:** Multi-step or non-obvious logic blocks must have short inline comments describing the flow.\n - Comments should be concise — explain intent and context, not implementation details.\n\n---\n\n## Adherence Checklist\nBefore completing your task, verify:\n- [ ] **Guard Clauses:** Are all edge cases handled at the top with early returns?\n- [ ] **Parsed State:** Is data parsed into trusted types at the boundary?\n- [ ] **Purity:** Are functions predictable and free of hidden mutations?\n- [ ] **Fail Loud:** Do invalid states throw clear, descriptive errors immediately?\n- [ ] **Readability:** Does the logic read like an English sentence?\n- [ ] **Comments:** Do classes, complex methods, and complex flows have concise purposeful comments?",
|
|
388
|
-
"category": "process",
|
|
389
|
-
"version": "4.1.1",
|
|
390
|
-
"references": [],
|
|
391
|
-
"scope": "global"
|
|
392
|
-
},
|
|
393
|
-
{
|
|
394
|
-
"name": "design-implementation-consistency",
|
|
395
|
-
"description": "设计-实现行为一致性验证。解决\"形式匹配但实质偏离\"。5 阶段审计：审计范围 → Spec Intent IR → Code Behavior IR → 对齐/偏离分类 → 审计报告。",
|
|
396
|
-
"content": "\n# 设计-实现行为一致性验证\n\n> **解决的问题**：编码完成后\"形式匹配但实质偏离\"——代码结构看起来对（class / method / 字段都符合技术方案），但**数据流 / 边界处理 / 业务语义**与方案不一致。\n>\n> **典型场景**：方案要求\"批量操作\"，实现写成 for 循环单条调用——形式上是批量，实质是 N 次单条；方案要求\"幂等\"，实现只检查了主键冲突但没考虑业务幂等键。\n>\n> **触发时机**：后端编码 / UI 组件开发编码完成、节点归档前。作为 Verifier 角色（Worker/Verifier 分离 HARD GATE）的执行工具。\n\n## 审计原则\n\n1. **逐方法钻入方法体**——禁止只看签名（签名匹配 ≠ 行为匹配）\n2. **追踪数据流**——从入口到出口，关注每个数据变换点\n3. **每条结论必须有源标注**——代码行号或方案段落，无源标 `UNDOCUMENTED`\n4. **不修改代码**——本 skill 是只读审计，发现问题输出报告，由 Worker 修复\n\n## 5 阶段审计流程\n\n### Phase 1 — 审计范围确认\n\n从任务文件提取审计输入：\n\n| 输入 | 来源 | 必填 |\n|---|---|---|\n| 技术方案要点 | 任务记录（`siming_task { action: \"context\", taskId: \"<任务id>\" }` 获取）的技术方案章节 | ✅ |\n| 验收标准 | 任务文件的 AC（Acceptance Criteria）清单 | ✅ |\n| 影响范围 | 任务文件的\"影响模块\"列表 | ✅ |\n| PRD 摘要（可选）| 项目文档目录（按项目 AGENTS.md 声明） | 复杂业务逻辑时填 |\n| 代码改动清单 | `git diff --stat dev..feature/<taskId>-{slug}` | ✅ |\n\n**输出**：审计范围文档（包含上述 5 项 + 明确\"在范围/不在范围\"的边界）\n\n### Phase 2 — Spec Intent IR（意图中间表示）\n\n从技术方案提取**业务意图**（不是实现细节）。\n\n每个意图项包含 5 字段：\n\n| 字段 | 含义 | 示例 |\n|---|---|---|\n| 输入 | 数据来源 + 格式 | \"请求体 UserCreateDTO（email + name + role）\" |\n| 输出 | 返回数据 + 副作用 | \"返回 UserVO；DB user 表新增 1 行；发送欢迎邮件\" |\n| 边界 | 边界条件 + 异常处理 | \"email 重复 → 409；role 非法 → 400；DB 异常 → 500 + 回滚\" |\n| 异常 | 业务异常 + 系统异常的区分 | \"业务异常（UserAlreadyExists）vs 系统异常（DB connection）\" |\n| 副作用 | 显式/隐式副作用 | \"DB 写 / 邮件发送 / 缓存失效 / 事件发布\" |\n\n**HARD GATE**：意图项必须可验证（每项对应一个测试断言）。\n\n### Phase 3 — Code Behavior IR（行为中间表示）\n\n逐方法**钻入方法体**追踪数据流。\n\n#### 3.1 入口分析\n- Controller / API 入口签名 → 参数校验逻辑 → 调用的 Service 方法\n- 禁止只看 Controller 注解（@PostMapping / @Valid），必须看校验是否生效\n\n#### 3.2 Service 层分析（**MUST 钻入方法体**）\n- 数据变换路径：每个字段从入参到出参的变换链\n- 事务边界：@Transactional 的范围 + 传播级别 + 回滚规则\n- 异常处理：try/catch 的范围 + 抛出的异常类型 + 是否吞异常\n- 副作用顺序：DB 写 / 外部调用（邮件/HTTP）/ 事件发布的顺序\n- 边界处理：null / 空集合 / 重复数据 / 并发的处理\n\n#### 3.3 Repository / DAO 层分析\n- SQL / Query 是否匹配方案的字段范围\n- 索引使用是否符合方案的查询模式\n- 批量操作的实现方式（真批量 vs 伪批量循环）\n\n#### 3.4 输出 IR\n\n每个方法生成一份 IR：\n\n```\nmethod: UserService.createUser\ninput: UserCreateDTO (email, name, role)\ndataFlow:\n - validateEmailUnique(email) → 查DB user 表，WHERE email = ?\n - toEntity(dto) → User(id=null, email, name, role, createdAt=now)\n - repository.save(entity) → DB insert\n - publishUserCreatedEvent(entity.id) → 异步事件\n - toVO(entity) → UserVO\noutput: UserVO\nexception:\n - UserAlreadyExistsException → Controller 转 409\n - DataIntegrityViolationException → 转 UserRepositoryException\nsideEffect:\n - DB user 表 INSERT\n - ApplicationEventPublisher 发布 UserCreatedEvent\n```\n\n### Phase 4 — 对齐/偏离分类\n\n将 Phase 2 的 Spec Intent IR 与 Phase 3 的 Code Behavior IR 逐项对比。\n\n#### 4.1 匹配类型（6 类）\n\n| 类型 | 定义 | 处理 |\n|---|---|---|\n| **完全对齐** | 行为等价，包括边界和异常 | ✅ Pass |\n| **行为等价** | 实现方式不同但语义等价（如 stream vs for） | ✅ Pass（Info 级记录） |\n| **边界扩展** | 代码处理了方案未要求的边界（更健壮） | ⚠️ Minor（确认是否有副作用） |\n| **边界收窄** | 代码未处理方案要求的边界 | ❌ Major（必须修） |\n| **行为偏离** | 实现行为与方案语义不同 | ❌ Major / Critical |\n| **完全偏离** | 实现与方案南辕北辙 | ❌ Critical（必须重写） |\n\n#### 4.2 严重度（4 级）\n\n| 级别 | 定义 | 是否阻塞 编码节点归档 |\n|---|---|---|\n| Info | 实现更优 / 风格差异 | 否 |\n| Minor | 边界处理不完整但 AC 仍能通过 | 否（建议修） |\n| Major | AC 部分失败 / 边界缺失导致潜在 bug | **是** |\n| Critical | AC 完全失败 / 数据损坏风险 | **是** |\n\n### Phase 5 — 审计报告\n\n输出格式：\n\n```markdown\n# Design-Implementation Consistency Audit Report\n\n## 任务信息\n- 任务：<taskId>-{slug}\n- 审计时间：{date}\n- 审计范围：{files}\n\n## 审计结论\n- 总体：PASS / FAIL（编码节点归档阻塞）\n- 偏离清单：{Critical 数} Critical / {Major 数} Major / {Minor 数} Minor / {Info 数} Info\n\n## 偏离详情（按严重度倒序）\n\n### [Critical-1] {标题}\n- Spec 意图：{Phase 2 的 IR 项}\n- Code 行为：{Phase 3 的 IR 项}\n- 差异：{具体偏离描述}\n- 证据：{代码行号 + 方案段落}\n- 修复建议：{Worker 应如何修}\n\n### [Major-1] ...\n\n## 通过项（简要清单）\n- {方法名}：完全对齐\n- ...\n\n## 反幻觉标注\n- UNDOCUMENTED 结论：{数量}（需补充证据）\n- INFERRED 结论：{数量}（需说明推理链）\n```\n\n## 反幻觉要求（对接 项目 AGENTS 纪律文件「信息推断权威」）\n\n- 每条偏离结论必须引用**代码行号 + 方案段落**\n- 无源标注的结论标 `UNDOCUMENTED`，必须在审计报告中标出\n- 推论性结论标 `INFERRED`，需说明推理链（为什么认为偏离）\n- **禁止臆测**：看到方法名相似就判定对齐；看到字段相同就判定等价\n- **零猜测原则**：所有结论必须有可复现的证据链\n\n## 典型偏离模式（参考清单）\n\n| 模式 | Spec 要求 | Code 实际 | 检测点 |\n|---|---|---|---|\n| 伪批量 | 批量插入 | for 循环单条插入 | Service 层方法体 |\n| 假幂等 | 业务幂等键 | 只检查主键 | Repository SQL |\n| 吞异常 | 抛业务异常 | catch 后 log 不抛 | try/catch 块 |\n| 事务漏洞 | 整个方法事务 | @Transactional 缺失或范围错 | 注解 + 方法调用链 |\n| 顺序错位 | DB → 事件 → 返回 | 事件 → DB → 返回 | 副作用顺序 |\n| 字段漏处理 | 5 字段 | 只处理 3 字段 | DTO → Entity 映射 |\n| 验证失效 | @Valid + 业务校验 | 只有 @Valid | Controller + Service |\n\n## 集成点\n\n- **开发流程编码节点**：后端编码/UI 组件开发类节点（编码完成后、节点归档前，Verifier 角色）；节点名以项目 DAG 模板实况为准，不写死\n- **Worker/Verifier 分离 HARD GATE**（workflow-discipline skill）：本 skill 由 Verifier 执行，不修改代码\n",
|
|
397
|
-
"category": "process",
|
|
398
|
-
"version": "4.2.2",
|
|
399
|
-
"references": [],
|
|
400
|
-
"scope": "global"
|
|
401
|
-
},
|
|
402
|
-
{
|
|
403
|
-
"name": "frontend-philosophy",
|
|
404
|
-
"description": "Visual & UI philosophy (5 Pillars of Intentional UI). 由 dev-workflow 编排调用。",
|
|
405
|
-
"content": "# Frontend Design Philosophy: The 5 Pillars of Intentional UI\n\n**Role:** Design Director for all **Visual & Aesthetic decisions** — applies to styling, layout, colors, typography, animations, and UI composition.\n\n**Philosophy:** Distinctive, memorable, intentional design — avoiding generic \"AI slop\" aesthetics through bold, characterful choices that create immediate emotional impact.\n\n## The 5 Pillars\n\n### 1. Typography with Character\n- **Concept:** Fonts set the entire tone. Generic fonts create generic, forgettable interfaces.\n- **Rule:** Avoid Inter, Roboto, Arial, and system-ui defaults. Choose distinctive, characterful typefaces.\n- **Practice:** Pair dramatic display fonts with refined, readable body fonts.\n\n### 2. Committed Color & Theme\n- **Concept:** Timid palettes lack impact and feel algorithmically generated.\n- **Rule:** Use bold, dominant colors with sharp accent contrasts. Avoid evenly-distributed rainbow gradients.\n- **Practice:** Establish CSS variable systems early. Break away from the \"purple gradient on white\" AI cliché.\n\n### 3. Purposeful Motion\n- **Concept:** Animation should delight, not distract. Scattered micro-interactions create noise.\n- **Rule:** One well-orchestrated animation beats a dozen minor transitions. Focus on high-impact moments.\n- **Practice:** Use CSS animations for HTML, Motion library for React. Prioritize staggered reveals and surprsing hover states.\n\n### 4. Brave Spatial Composition\n- **Concept:** Predictable layouts are forgettable. Safe spacing feels automated.\n- **Rule:** Either generous negative space OR controlled density — not the middle ground.\n- **Practice:** Embrace asymmetry, overlap, diagonal flow, and grid-breaking elements.\n\n### 5. Atmosphere & Depth\n- **Concept:** Flat solid backgrounds lack presence and feel unfinished.\n- **Rule:** Layer visual richness through gradient meshes, noise textures, geometric patterns, and transparencies.\n- **Practice:** Add dramatic shadows, decorative borders, grain overlays.\n\n---\n\n## Adherence Checklist\nBefore completing your task, verify:\n- [ ] **Typography:** Did you avoid generic system fonts?\n- [ ] **Color:** Are the color choices bold and intentional?\n- [ ] **Motion:** Is there a primary, high-impact animation?\n- [ ] **Space:** Does the layout feel designed rather than templated?\n- [ ] **Depth:** Is there visual richness (textures, gradients, layering)?",
|
|
406
|
-
"category": "process",
|
|
407
|
-
"version": "4.1.1",
|
|
408
|
-
"references": [],
|
|
409
|
-
"scope": "global"
|
|
410
|
-
},
|
|
411
|
-
{
|
|
412
|
-
"name": "frontend-consistency",
|
|
413
|
-
"description": "前端编码风格规范，适用于React + TypeScript + Tailwind CSS + shadcn/ui项目，保证前端UI与代码一致性。",
|
|
414
|
-
"content": "\n# Frontend Consistency Guide\n\nAI 前端编码风格规范，适用于 React + TypeScript + Tailwind CSS + shadcn/ui 项目。\n\n## 加载方式\n\n随开发流程任务 context 的节点 skills 注入。适用节点：UI 组件开发 / UI 视觉验证类节点（节点名以项目 DAG 模板实况为准）。适用模块：`ui/`。\n\n## 技术栈\n\nReact 19 + TypeScript (strict) + Tailwind CSS v4 + shadcn/ui (base-nova, neutral) + Vite 8 + React Router v7。\n\n## 强制规则\n\n### 1. shadcn/ui 优先 — 基础组件必须用 shadcn\n\n| 场景 | 必须使用 | 禁止 |\n|------|----------|------|\n| 按钮 | `<Button>` | 自定义 `<CustomButton>` |\n| 输入框 | `<Input>` | 自定义 `<TextField>` |\n| 对话框 | `<Dialog>` | 自定义 `<Modal>` |\n| 下拉菜单 | `<DropdownMenu>` | 自定义 `<Select>` |\n| 表格 | `<Table>` | 自定义表格组件 |\n\n添加组件: `npx shadcn@latest add <component>`\n\n### 2. 语义颜色变量 only — 禁止硬编码颜色\n\n```tsx\n// ✅ 正确 — 使用语义颜色\n<div className=\"text-primary\">标题</div>\n<div className=\"bg-destructive text-destructive-foreground\">错误</div>\n<div className=\"border-muted\">分割线</div>\n\n// ❌ 禁止 — 硬编码颜色\n<div className=\"text-[#3B82F6]\">标题</div>\n<div className=\"bg-blue-500\">错误</div>\n```\n\n### 3. 设计 Token 规范\n\n| Token | 规则 | 示例 |\n| -------- | --------------------------------------- | ---------------------------- |\n| **颜色** | 语义颜色变量 only | `text-primary`, `bg-destructive` |\n| **间距** | Tailwind spacing scale only（4px 基准） | `p-4`, `gap-2`, `mx-auto` |\n| **圆角** | `rounded-md` 按钮/输入/小型元素 | `<Button className=\"rounded-md\">` |\n| | `rounded-lg` 卡片/对话框/容器 | `<Card className=\"rounded-lg\">` |\n| | `rounded-full` 头像/徽标/药丸 | `<Badge className=\"rounded-full\">` |\n| **阴影** | `shadow-sm` 卡片/面板（微弱层次） | `<Card className=\"shadow-sm\">` |\n| | `shadow-md` 下拉菜单/浮动层 | `<DropdownMenu className=\"shadow-md\">` |\n| | `shadow-lg` 模态框/弹出层 | `<Dialog className=\"shadow-lg\">` |\n| **过渡** | `transition duration-200 ease-out` | 标准动画时长和缓动 |\n\n### 4. 布局规范\n\n- 页面容器: `<div className=\"container mx-auto px-4 py-6\">`\n- 表单: shadcn `<Form>` + `<FormField>` + `<FormItem>`\n- 卡片网格: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4`\n\n### 5. 响应式断点\n\n遵循 Tailwind 默认断点: `sm`(640px), `md`(768px), `lg`(1024px), `xl`(1280px)。\n\n移动优先: `className=\"flex flex-col md:flex-row gap-4\"`\n\n### 6. 深色模式\n\n通过 `.dark` class 切换。所有颜色使用 CSS 变量自动适配，无需手动处理。\n\n```tsx\n// ✅ 正确 — CSS 变量自动适配深色模式\n<div className=\"bg-background text-foreground\">\n\n// ❌ 禁止 — 手动处理深色模式\n<div className=\"bg-white dark:bg-gray-900\">\n```\n\n## 禁止事项\n\n- ❌ 禁止 inline styles（`style={{...}}`）\n- ❌ 禁止硬编码颜色值（`text-[#3B82F6]`、`bg-blue-500`）\n- ❌ 禁止任意像素间距（`mt-[13px]`）\n- ❌ 禁止非项目 UI 库组件（MUI/Ant Design/Chakra）\n- ❌ 禁止覆盖 shadcn 核心样式（不修改 `src/components/ui/` 中的基础样式）\n- ❌ 禁止 `!important`\n- ❌ 禁止自定义基础组件（如已有 Button，不再创建 CustomButton）\n- ❌ 禁止 class 组件（函数组件 only）\n- ❌ 禁止 `any` 类型\n\n## 代码规范\n\n- TypeScript strict 模式 — 禁止 `any`\n- @ 路径别名: `@/components`, `@/pages`, `@/lib`, `@/hooks`\n- 文件命名: PascalCase 组件（`HomePage.tsx`），camelCase 工具（`utils.ts`）\n- 页面组件 → `src/pages/`，共享组件 → `src/components/`，工具函数 → `src/lib/`\n\n## 组件开发 Checklist\n\n- [ ] 是否有现成的 shadcn/ui 组件可用？\n- [ ] 颜色是否使用语义变量（primary/destructive/muted）？\n- [ ] 间距是否使用 Tailwind scale？\n- [ ] 圆角是否符合 Token 规范（md/lg/full）？\n- [ ] 阴影是否符合 Token 规范（sm/md/lg）？\n- [ ] 深色模式是否自动适配（CSS 变量）？\n- [ ] 响应式是否处理（移动优先）？\n- [ ] TypeScript 类型是否严格（无 any）？\n",
|
|
415
|
-
"category": "process",
|
|
416
|
-
"version": "1.0.4",
|
|
417
|
-
"references": [],
|
|
418
|
-
"scope": "global"
|
|
419
|
-
},
|
|
420
|
-
{
|
|
421
|
-
"name": "ui-verify",
|
|
422
|
-
"description": "UI 功能验证。用 Playwright MCP 对前端做交互验证（CRUD/Toast/控制台错误）。",
|
|
423
|
-
"content": "# UI 功能验证\n\n> **执行责任：Playwright 验证由 Main Agent 亲自执行，不得委派给 subagent。** Subagent 只负责编码，不负责验证。\n>\n> **与 api-e2e-test 互斥**：本 skill 通过 Playwright MCP 手动操作浏览器验证 UI，不产出测试代码。编写 E2E 测试代码（TestNG + REST Assured）请使用 `api-e2e-test` skill。\n\n## HARD GATE — 任务完成判定\n\nUI 任务，**只有同时满足以下两项才算完成**：\n1. `tsc --noEmit` 零错误（或项目类型检查命令）\n2. **Playwright MCP 功能验证通过**\n\n缺少任何一项 → 任务状态为 **未完成**。\n\n## 服务启动（HARD GATE）\n\n### 启动脚本\n\n| 服务 | 脚本 | 说明 |\n|------|------|------|\n| 后端 API | `{项目后端启动脚本}` | 自动清理旧进程 + 启动 + 健康检查 |\n| 前端 dev | `{项目前端启动脚本}` | 基于 `screen -dmS` 或类似方式创建独立 session |\n| 停止全部 | `{项目停止脚本}` | 清理 session + 端口 + 连接信息 |\n\n**必须使用项目脚本启动，禁止以下方式：**\n- 禁止 `mvn spring-boot:run`（进程会被 bash session 杀死）\n- 禁止 `npm run dev`（进程会被 bash session 杀死）\n- 禁止 `nohup ... &`、`bash -c '... & disown'`（同上）\n\n### 连接信息\n\n脚本启动成功后写入 `logs/connection-info`，格式由项目定义，通常包含：\n\n```\nAPI_PORT={后端端口}\nAPI_URL=http://localhost:{后端端口}\nAPI_KEY={项目认证 Key}\nDEV_URL=http://127.0.0.1:{前端端口}\nDEV_LOG=/temp/ui-dev.log\n```\n\n**读取方式（任选其一）：**\n```bash\nsource logs/connection-info && echo $API_PORT $API_KEY $DEV_URL\ngrep -E 'API_PORT|API_KEY|DEV_URL' logs/connection-info\n```\n\n**禁止：**\n- 禁止硬编码端口或 API Key\n- 禁止对启动脚本输出使用 `tail -N`（关键信息在输出开头，tail 会丢失）\n\n### 前置依赖\n\n根据项目环境确认中间件（MySQL、Redis 等）运行中。\n\n## 验证 Checklist\n\nMain Agent 规划 todo 时，**必须包含以下步骤**（不可省略）：\n\n```\n✅ 编码完成（subagent 交付）\n✅ 类型检查零错误\n✅ 启动后端 + 前端（使用脚本）\n✅ 加载 Playwright skill（读其 SKILL.md 全文后使用其工具集）\n✅ 输入认证信息（从 logs/connection-info 获取）\n✅ 导航到目标页面 + 截图\n✅ 执行完整 CRUD 操作流（新建 → 编辑 → 删除）\n✅ 确认 Toast 提示 + 列表更新\n✅ 检查控制台无 JS 错误\n✅ 关闭浏览器 + 清理进程\n```\n\n## 验证流程\n\n以下步骤由 Main Agent 亲自执行，不要委派。每一步都必须实际执行，不可跳过。\n\n### 1. 启动服务\n\n```bash\n# 使用项目脚本启动\n{项目后端启动脚本}\n{项目前端启动脚本}\nsource logs/connection-info\n```\n\n### 2. 加载 Playwright\n\n加载 Playwright skill（读其 SKILL.md 全文），获得 Playwright 工具集（browser_navigate / browser_click / browser_type 等）。\n\n### 3. 输入认证信息\n\n根据项目要求输入认证信息（API Key / Token 等），从 `logs/connection-info` 读取。\n\n### 4. 导航 + 截图\n\n`browser_navigate` 到 `$DEV_URL` 下的目标路径。\n`browser_take_screenshot` 截图，**必须指定 `filename` 参数**，保存到 `temp/playwright/` 目录下。示例：\n\n```\nbrowser_take_screenshot(filename=\"temp/playwright/02-page-list.png\")\nbrowser_take_screenshot(filename=\"temp/playwright/03-create-dialog.png\")\n```\n\n> 编号规则：`{序号}-{页面}-{操作}.png`，序号从 01 开始递增，与验证步骤对应。\n\n### 5. 功能验证\n\n根据页面功能执行完整操作流。\n\n### 6. 控制台检查\n\n`browser_console_messages` 确认无 JS 运行时错误。\n\n### 7. 清理\n\n`browser_close` → `{项目停止脚本}`\n\n## 功能验证要点\n\n| 页面类型 | 必验操作 |\n|----------|----------|\n| CRUD 页面 | 列表加载（有真实数据）→ 新建 → 编辑 → 删除，确认 Toast 提示 |\n| 详情页 | 进入详情 → 切换各 Tab → 子操作（新建/编辑/删除） |\n| 统计页面 | 列表加载 → 查询条件筛选 → 分页 |\n| 管理页面 | 刷新操作 → 结果展示 |\n\n## 功能验证原则\n\n- **完整性优先**：必须执行每个操作的完整生命周期，不得因\"可能产生其他影响\"而跳过\n- **删除操作**：必须实际执行删除并验证结果，不能仅检查 AlertDialog 结构\n- **新建测试数据**：可创建临时测试数据（如 `test-verify-xxx`），验证完毕后删除清理\n- **验证闭环**：每个操作必须观察到最终结果（Toast 提示、列表更新、Dialog 关闭），未观察到结果等于未验证\n\n## 注意事项\n\n- dev server 端口和 API 端口均为动态分配，**必须从 `logs/connection-info` 读取**\n- 验证时机：每个产生 UI 变更的任务完成后",
|
|
424
|
-
"category": "process",
|
|
425
|
-
"version": "4.1.2",
|
|
426
|
-
"references": [],
|
|
427
|
-
"scope": "global"
|
|
428
|
-
},
|
|
429
|
-
{
|
|
430
|
-
"name": "test-fix-loop",
|
|
431
|
-
"description": "测试失败修复循环。失败 → bugfix-root-cause-verification → 修复 → 重跑 → 最多 3 轮。强制单测与 E2E 串行，禁止并行。",
|
|
432
|
-
"content": "# 测试失败修复循环\n\n> **定位**：本 skill 是测试失败后的修复编排器，串联 `bugfix-root-cause-verification`（根因验证）和 `systematic-debugging`（通用调试）。\n>\n> **触发**：单测 / 框架测试 / E2E 失败后进入修复循环。\n\n## 流程\n\n```\n失败测试清单（按 test-executor 报告或落盘日志）\n │\n ▼\nbugfix-root-cause-verification（根因分析）\n │\n ▼\n修复（基于根因，禁止补丁式）\n │\n ▼\n重跑（先单测，后 E2E，串行）\n │\n ┌──┴──┐\n PASS FAIL\n │ │\n ▼ └──→ 回到根因分析（最多 3 轮）\n │\n 完成\n```\n\n## HARD GATE\n\n1. **单测与 E2E 串行**——禁止并行执行（并行会引入数据竞争 / 时序假阳性）\n2. **executor / fixer 禁止嵌套 subagent**——修复循环必须在同一会话内闭环\n3. **修复必须基于根因**——禁止补丁式修改（如 try/catch 吞异常、`@Ignore`/`@Disabled`/`test.skip()`/`test.fixme()`/`xdescribe`/`xit`/`.only()` 跳过失败测试、改断言让测试通过）。**本条约束所有触碰测试代码的会话**（含主会话编码者——不限于修复循环内；被本任务改动破坏的测试归本任务修复，\"pre-existing/非本任务范围\"不是 skip 理由）\n4. **重跑范围**——修复后必须重跑**完整失败清单**，禁止只跑上次失败的 case（防止修复引入新问题）\n5. **3 轮上限**——超过 3 轮不收敛 → STOP（按 「自主优先方法论」 暂停上升；先升级对应场景 reviewer 咨询，仍无果再上升用户）\n\n## 详细步骤\n\n### 步骤 1 — 收集失败清单\n\n从 test-executor 报告或落盘日志读取（按 项目 AGENTS 纪律文件「命令日志」HARD GATE 落盘）：\n- FAIL 段\n- 失败 case 完整列表（class.method）\n- 每个失败 case 的失败原因（断言失败 / 异常 / 超时）\n\n### 步骤 2 — 进入根因验证\n\n加载 `bugfix-root-cause-verification` skill：\n- 多个失败 case 有关联 → 一次性分析（找共同根因）\n- 多个失败 case 无关联 → 分组，每组独立分析（但串行执行，禁止并行）\n\n### 步骤 3 — 修复\n\n按根因结论修复：\n- 单一根因 → 单点修复\n- 多个独立根因 → 分别修复，但要确认修复 A 不会引入 B 的问题\n\n**禁止**（补丁式反模式）：\n- ❌ try/catch 吞异常让测试通过\n- ❌ `@Ignore` / `@Disabled` 跳过失败测试（Java 形态）\n- ❌ `test.skip()` / `test.fixme()` / `describe.skip()` / `xdescribe` / `xit` / `test.only()` 跳过/排除失败测试（JS/TS 形态：Playwright/vitest，等价于 @Ignore）\n- ❌ 改测试断言让其通过（「自主优先方法论」）\n- ❌ 加 `if (xxx != null)` 防 NPE 而不查为什么 null\n- ❌ 改测试数据让其通过\n\n### 步骤 4 — 重跑\n\n**串行顺序**（HARD GATE）：\n1. 先跑单测（单测设计/单测开发 范围）\n2. 单测全 PASS → 跑 E2E（E2E 设计/E2E 开发 范围）\n3. E2E 全 PASS → 退出循环\n\n**重跑范围**：完整失败清单 + 受影响范围（不是只跑上次失败的）\n\n### 步骤 5 — 循环或退出\n\n| 重跑结果 | 动作 |\n|---|---|\n| 全 PASS | 退出循环，继续 dev-workflow 流程 |\n| 部分仍 FAIL（< 上次）| 进步中，回到步骤 2 继续分析（计入轮次） |\n| 部分仍 FAIL（≥ 上次）| 根因分析方向可能错误，回到步骤 2 重新分析（计入轮次） |\n| 新增 FAIL（修复引入）| 回到步骤 2，新失败 + 旧失败一起分析（计入轮次） |\n\n## 轮次追踪\n\n每轮记录（写入任务文件的 CP 记录）：\n```\nRound {N}:\n- 失败清单：{数量} 个\n- 根因假设：{H1/H2/H3}\n- 验证结果：{confirmed/rejected}\n- 修复内容：{file:line - 改动描述}\n- 重跑结果：{PASS 数}/{总数}\n```\n\n3 轮后仍不收敛 → STOP，按以下格式暂停上升：\n- 已尝试的 3 轮假设清单\n- 每轮的根因方向 + 失败原因\n- 当前最可能的根因 + 缺什么证据\n- 候选突破方向（2-3 个）\n- 是否需要 对应场景 reviewer 升级 / 用户决策\n\n## 集成点\n\n- **项目 AGENTS 纪律文件「测试 Iron Law」**（测试 Iron Law）：3 次修复失败 → STOP 质疑架构\n- **「自主优先方法论」**（自主优先方法论）：3 轮不收敛 → 暂停上升\n- **bugfix-root-cause-verification**：步骤 2 的根因分析执行\n- **systematic-debugging**（用户全局）：通用调试方法论，本 skill 内部调用",
|
|
433
|
-
"category": "process",
|
|
434
|
-
"version": "4.2.0",
|
|
435
|
-
"references": [],
|
|
436
|
-
"scope": "global"
|
|
437
|
-
},
|
|
438
|
-
{
|
|
439
|
-
"name": "dev-workflow-tester",
|
|
440
|
-
"description": "Workflow Tester — dev-workflow v3.0 测试执行 subagent，承接所有 CLI 测试执行：自主环境准备 + 测试执行 + 结构化报告。由主会话在各测试节点（单测开发/E2E 开发/验收归档·全量回归）显式触发。",
|
|
441
|
-
"content": "# test-executor 执行参考（dev-workflow-tester）\n\n> **test-executor 是 siming 开发流程的测试执行 subagent**。承接所有\"跑 CLI 测试 + 自主环境准备 + 把结果带回主会话\"的杂事。让主会话专注高价值工作（设计/编码/调试/审查/决策）。**对标 flow-executor 模式**：本 skill 是 test-executor 的行为指南，主会话只需触发并给 scope，test-executor 自己知道怎么干。\n\n## 1. 角色定位\n\n| 维度 | 说明 |\n|------|------|\n| **身份** | test-executor（siming agent 资产：model=main-worker，boundSkills 固化） |\n| **配置位置** | siming agent 资产 `test-executor`（model/boundSkills/systemPrompt 完整定义，经 install 可下发本地平台） |\n| **权限范围** | bash / read / glob / grep 允许；**edit/write 全部 deny**（禁止编辑任何文件） |\n| **加载方式** | 本 skill 已固化绑定于 test-executor agent（boundSkills），主会话委派 test-executor 时自动生效，无需在 prompt 中声明 skill 清单 |\n| **调用方** | 主会话 在 单测开发 / E2E 开发 / 验收归档·全量回归 等测试节点触发 |\n| **测试范围** | E2E / 单测 / 静态分析 / 框架测试（pytest 等）—— 一切通过 bash 执行的测试 |\n\n> **不归 test-executor 管的**：MCP 工具类验证（Playwright MCP / 截图 MCP 等）由主会话自己执行——test-executor 无 MCP 权限。\n\n## 2. 三阶段工作流（HARD GATE）\n\n每次被调用，test-executor 按以下三阶段执行（不可跳过）：\n\n```\n自主环境准备 → 测试执行 → 信息收集 + 最终报告\n```\n\n| 阶段 | 动作 | 等待策略 |\n|-------|------|---------|\n| 自主环境准备 | 按项目依赖清单（位置按项目 AGENTS.md 声明，通常为 MANIFEST/环境文档类）探活本机依赖服务；未运行则自主启动；3 轮仍无法拉起 → 报告卡点（含已尝试命令 + 错误），**禁止要求用户启动**（见本 skill 「自主环境准备」 自主环境准备） | 同步命令禁 sleep；后台启动用 `while ! probe; do sleep 3; done` 轮询（≤90s） |\n| 测试执行 | 执行主会话指定的 target（全量 / 模块 / 单类 / 多类），日志按 项目声明的命令日志落盘纪律 落盘 | 同步命令禁 sleep |\n| 信息收集 | grep 失败用例 + ERROR 行 + Top 栈 + log 路径；按 「Final Output Contract」 契约生成最终响应 | 立即生成，禁 sleep |\n\n> **角色边界（HARD GATE）**：\n> - test-executor 只报事实（命令输出 / PASS/FAIL/统计 / log 关键行），**不解释原因、不修代码、不 Diagnose**\n> - Diagnose + 修代码 + 重跑决策 = 主会话职责（主会话加载 `系统化根因排查流程`）\n> - **委托 ≠ 甩锅用户**：本机所有依赖服务由 test-executor 启动，禁止要求用户启动\n\n## 3. Final Output Contract（HARD GATE — 最终输出契约）\n\n> **为什么需要这条契约**：委派机制下，编排会话（主会话）**只能看到 test-executor 的最终响应**。所有中间 tool_call、命令输出、三阶段（自主环境准备/测试执行/信息收集）中间消息都留在 test-executor 的 session log，**对编排会话不可见**。\n>\n> 因此 test-executor 的**最终响应 MUST 是完整的结构化报告本身**，而非\"摘要 + 详见日志\"。摘要响应会迫使主会话额外回读 session 记录才能拿到失败明细——违背委托的初衷（委托 = 让 subagent 干活 + 把结果带回来，少一层中转）。\n\n### 3.1 机制示意（test-executor 必读）\n\n```\n主会话 ── 委派 test-executor ──▶ test-executor session 启动\n │\n ├─ 自主环境准备: 探活依赖服务（tool_call 输出留在 session log）\n ├─ 测试执行: bash run-tests（命令输出留在 session log）\n ├─ 信息收集: grep / tail（提取关键行，留在 session log）\n │\n └─▶ 最终响应（一条 assistant message） ──▶ 主会话 ONLY 看到这个\n session log 对主会话不可见\n```\n\n**推论**：你在信息收集阶段用 grep / tail 提取的失败明细，**必须在最终响应里再次输出**，不能\"已经在中间步骤看过了所以最终只总结\"。\n\n### 3.2 PASS 情况模板\n\n```\n## Test Execution Report\n\n**Status**: ✅ ALL PASS\n**Environment**: <service1>=ok | <service2>=ok | <service3>=ok # 按项目依赖清列举\n**Scope**: {全量 | 模块名 | 类名}\n**Stats**: {N} classes | {M} tests | {M} pass | 0 fail | 0 skip\n**Duration**: ~{X}m {Y}s\n**Slow tests** (>30s, top 5 如有):\n - {类名}: {N}s — {备注}\n**Logs**:\n - `<日志路径>` ({模块/范围})\n - `<日志路径>` (...)\n```\n\n### 3.3 FAIL 情况模板\n\n```\n## Test Execution Report\n\n**Status**: ❌ HAS FAILURES\n**Environment**: <service1>=ok | <service2>=ok | <service3>=ok (或 fail/started)\n**Scope**: {全量 | 模块名 | 类名}\n**Stats**: {N} classes | {M} tests | {M-K} pass | {K} fail | {S} skip\n**Skip 清单**（{S}>0 时逐条列出；=0 省略本节）:\n - {文件}: {case 名}\n**Duration**: ~{X}m {Y}s\n\n**Failed classes** ({K}):\n1. {类名} — {n_run} run, {n_fail} fail\n Failed methods:\n - `{method1}`: {1 行错误摘要，如 \"AssertionError: expected 200 but got 404\"}\n - `{method2}`: {1 行错误摘要}\n Log: `<日志路径>`\n Top stack:\n at {package}.{Class}.{method}({File}:{line})\n at {package}.{Class}.{method}({File}:{line})\n Caused by: {ExceptionType}: {message}\n\n2. {类名} — ...\n\n**Passed classes**: {N-K}（省略明细，仅给计数）\n\n**Logs**:\n - `<日志路径>` ...\n```\n\n### 3.4 禁止的最终响应（HARD VIOLATION）\n\n| ❌ 错误示例 | 为什么错 |\n|------------|---------|\n| \"测试已完成，3 个失败，详见日志\" | 编排会话看不到日志，等于没报告 |\n| \"执行完毕，结果如预期\" | 无任何可操作数据 |\n| \"E2E 全量跑完，整体通过\" | 无统计、无类明细、无 log 路径 |\n| \"自主环境准备/测试执行/信息收集 全部执行完毕\" | 流程描述 ≠ 结果报告 |\n| \"3 个失败，已 grep 详情\" 但未贴出 grep 结果 | grep 输出留在 session log，编排会话看不到 |\n| 任何需要主会话回读 session 记录才能拿到失败明细的响应 | 违背委托初衷 |\n| skip>0 只报 skip 计数、不列 skip case 清单（文件 + case 名） | 主会话无法对账 skip 授权（见 exit.md H2/H3 零-skip 原则），skip 退化为隐形失败 |\n\n### 3.5 截断策略（失败过多时）\n\n单条响应有长度上限。失败类过多时按以下优先级保留（从前到后，越靠前越不可省略）：\n\n1. **所有失败类名**（一行一个，**永远不可省略**——否则编排会话连\"有哪些类挂了\"都不知道）\n2. **每个失败类的失败方法名 + 1 行错误摘要**（最多 3 个方法/类）\n3. **每个失败的 Top 3 栈**（`at {package}...` 或 `Caused by`）\n4. **log 文件路径**（永远保留）\n5. 通过类清单（可省略为计数）\n\n若单条响应超过 ~3000 字：保 1+2+4，方法明细可压到\"见 log {path}:{line}\"。\n\n## 4. 通用执行原则\n\n- **同步命令禁 sleep**（HARD GATE，详见 项目声明的命令日志落盘纪律）：`mvn ... > log; sleep N; tail log` 是反模式——bash 工具命令退出后才返回，日志已在返回前落盘\n- **唯一允许 sleep 的场景**：异步后台启动（`mvn spring-boot:run &` / `npm run dev &` 等 `&` 后缀），用 `while ! probe; do sleep N; done` 轮询（带超时上限），禁止裸 `sleep N`\n- **日志必须落盘**（按 项目声明的命令日志落盘纪律）：禁止 stdout 直读\n- **类粒度并发**：全量按模块顺序推进；模块/类列表批次默认 3 路进程级并发；涉及中间件启停的测试类排在最后单独运行\n- **超时**：普通类 ≤150s；少数依赖长等待的类（容灾测试）可扩展但必须基于业务窗口\n- **慢类阈值**：单类 >30s 在最终报告中列出\n- **结果对账**：runner 在模块结束时校验 PASS/FAIL 统计是否和目标类数量一致\n- **E2E runner ≠ 全量回归**：E2E runner 只编排「编译 → 起被测服务 → 灌种子数据 → 跑 E2E 用例」，**不含单元测试**——「全量回归」类委托必须两段显式执行（E2E runner + 各包单测命令），跑完 runner ≠ 回归完成\n- **大日志定位**：不要整读服务端大日志，按 reqId、业务 ID 或时间窗口精确检索\n\n## 5. 自主环境准备（test-executor 必须自主完成，禁止要求用户）\n\n> **核心原则**：AI 是执行者而非二传手。本机所有依赖服务的启动、检查、故障排查，**全部由 test-executor 自主完成**。\"暂停问用户启动服务\"视为最高成本手段，仅在 test-executor 已穷尽手段仍无法拉起时才启用，且必须附诊断证据。\n\n### 5.1 工作流位置\n\n环境准备是自主环境准备阶段（**不是独立节点**），每次分派 test-executor 时自动跑一遍（幂等检查，已运行则跳过启动）。\n\n### 5.2 通用流程（适用所有项目）\n\n```bash\n# 0. 读取项目依赖清单（位置按项目 AGENTS.md 声明；不存在 → 回退通用流程并在报告标注）\n\n# 1. 检查中间件（按项目依赖清单，每个服务：先探活，未运行 → 自主启动 → 再次探活）\n<middleware_probe_cmd> # 例：mongosh --eval 'rs.status().ok' / redis-cli ping / nc -z host port\n<middleware_start_cmd> # 例：brew services start <name> / systemctl start <name> / 直接命令\n# 启动失败 → test-executor 进入 Diagnose：查进程/端口/日志；3 轮仍无法拉起 → 报告卡点（不抛给用户）\n\n# 2. 检查被测服务（按项目依赖清单的 health check 端点）\ncurl -s -o /dev/null -w \"%{http_code}\" <health_url> # 例：localhost:{port}/{health_path}\n# 非 200/4xx（含 000 = 端口未监听）→ 自主启动：\n<service_start_cmd> # 例：cd <service_dir> && mvn spring-boot:run > <log> 2>&1 &\n# 后台启动 + 轮询等待（最多 90s），直到 health endpoint 返回预期状态码\n\n# 3. 验证依赖全部就绪，进入 测试执行\n```\n\n### 5.3 项目依赖清单模板（AI 接入项目时自主生成，位置按项目声明）\n\n```markdown\n# 本机服务依赖清单\n\n## 中间件\n| 服务 | 探活命令 | 启动命令 | 备注 |\n|------|---------|---------|------|\n| MongoDB | `mongosh --eval \"rs.status().ok\"` | `brew services start mongodb-community` | 副本集 rs0 |\n| Redis | `redis-cli ping` | `brew services start redis` | |\n\n## 被测服务\n| 服务 | 目录 | 启动命令 | health endpoint |\n|------|------|---------|-----------------|\n| backend | `backend/` | `cd backend && mvn spring-boot:run` | `localhost:8080/actuator/health` |\n\n## E2E 运行器（如有）\n- 执行入口：项目 AGENTS.md 声明的 E2E 命令\n- 退出码约定：0=PASS / 1=有 FAIL / 2=环境检查失败 / 3=编译失败\n```\n\n> 项目没有 E2E runner 时，项目依赖清单模板中 E2E 段省略。\n\n### 5.4 编译被测模块（HARD GATE）\n\n**E2E 必须跑在最新代码上。** test-executor 在每次执行前（同步命令，**禁止 sleep**）：\n\n```bash\n# 编译 — mvn 同步退出，日志在返回前已落盘\n# 按 项目声明的命令日志落盘纪律 落盘\ncd <project_root> && mvn compile -DskipTests\n# BUILD FAILURE → test-executor 报告编译错误（附 grep 行），主 Agent Diagnose 修代码\n```\n\n### 5.5 环境故障分类（主 Agent Diagnose 用）\n\ntest-executor 报告环境异常时，主 Agent 按下表 Diagnose（systematic-debugging），禁止直接抛给用户：\n\n| 故障类型 | 现象 | 主 Agent Diagnose 路径 |\n|---------|------|----------------------|\n| 中间件未运行 | 探活命令连接失败 | 让 test-executor 启动 → 再探活 → 仍失败查进程/端口/日志 |\n| 端口冲突 | 服务启动报 \"port in use\" | test-executor 查 `lsof -i :{port}` → 杀旧进程或换端口（决策权在主 Agent） |\n| 副本集未初始化 | `rs.status()` 报未启用 | test-executor 执行 `rs.initiate()` 初始化 → 再探活 |\n| 服务启动超时 | 90s 内 health endpoint 不通 | test-executor 查 backend log（tail/grep ERROR） → 主 Agent Diagnose 启动失败根因 |\n| 配置缺失 | 配置文件缺 key | 主 Agent 读源码确认 → 补配置（写文件 = 主 Agent 做，非 test-executor） |\n\n**3 轮自主迭代仍不收敛** → 进入暂停条件，附完整诊断证据上升用户。\n\n## 6. 通用命令模板（按测试类型）\n\n> 各项目具体命令清单（路径、模块映射、特殊参数）由 dev-workflow 节点文件 + 项目依赖清单 提供，本节只给通用模板。**路径占位符说明**：`{project_root}` 项目根，`{service_dir}` 后端模块目录，`{e2e_runner}` E2E 执行脚本路径。\n\n### 6.1 E2E 测试（如有独立 runner）\n\n> 脚手架预置 E2E 工程骨架（`E2eTester/` + `项目声明的 E2E 入口`），详见项目根 `E2eTester/AGENTS.md`。AI 接入项目时自主完成工程适配（端口/探针/ApiRoutes；包名固定 com.e2e 无需改）。\n\n```bash\n# 按 项目声明的命令日志落盘纪律 落盘\nbash {e2e_runner} {target}\n# 退出码含义按 runner 约定（见 项目依赖清单 §E2E 运行器）\n```\n\n**常见执行场景**：\n- 全量: `bash {e2e_runner}`\n- 按模块: `bash {e2e_runner} <module>`\n- 按测试类: `bash {e2e_runner} <ClassName>` 或 `bash {e2e_runner} <ClassA> <ClassB>`\n\n### 6.2 Java 单测 / 静态分析\n\n```bash\n# 编译\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {service_dir} && mvn compile\n\n# 静态分析（语法验证）\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {service_dir} && mvn checkstyle:check pmd:check spotbugs:check\n\n# 全量单测\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {service_dir} && mvn test\n\n# 按测试类\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {service_dir} && mvn test -Dtest=FooServiceTest\n\n# 冒烟（验收归档·全量回归 集成验证，如项目用分组标记）\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {service_dir} && mvn test -Dgroups=smoke\n```\n\n### 6.3 Python 单测（如适用）\n\n```bash\n# 按 项目声明的命令日志落盘纪律 落盘\ncd {project_root} && pytest tests/\n```\n\n### 6.4 runner 输出格式（通用示例）\n\n```\n=== Module | class granularity ===\n FooE2eTest PASS Tests run: 10, Failures: 0 <日志路径>\n BarE2eTest FAIL Tests run: 6, Failures: 2 <日志路径>\nModule: X total | X-1 pass | 1 fail\n\nSummary: P pass | F fail\nFailed targets: BarE2eTest RateLimitIT\nFailed logs:\n BarE2eTest -> <日志路径>\n```\n\n**输出状态含义**：\n- `PASS` — 一次性通过\n- `FAIL` — 测试失败\n- `TIMEOUT (Ns)` — 超时被 kill，日志中无测试结果\n- `START` — 并行模式下该类已启动，后面的日志名可直接查看实时输出\n- `... running` — 并行模式心跳，显示仍在运行的类和已运行秒数\n\n## 7. 主会话调用 prompt 模板\n\n> 主会话在各测试节点触发时，按以下模板委派 test-executor。本 skill 已固化绑定于 test-executor agent，主会话无需在 prompt 中声明 skill 清单。\n\n### 7.1 通用调用骨架\n\n委派 test-executor subagent，prompt 模板：\n\n```text\n## TASK\n执行 {测试类型: E2E / mvn / pytest / 静态分析} 测试，范围: {全量 | 模块名 | 类名}。\n\n## CONTEXT\n- 项目根: {project_root}/\n- session code: {session-code}（用于 log 文件命名）\n- 测试目标: {具体命令清单，从 dev-workflow 节点文件 + 项目依赖清单 复制}\n\n## MUST DO\n1. 按 dev-workflow-tester skill 「三阶段工作流」 三阶段工作流执行\n2. 自主环境准备（「自主环境准备」，按 项目依赖清单 探活）\n3. 测试执行 阶段执行指定的 target\n4. 信息收集 阶段 按要求 + 按 「Final Output Contract」 Final Output Contract 生成最终响应\n\n## MUST NOT DO\n- 不编辑任何文件（permission 已 deny）\n- 不解释失败原因（主会话负责 Diagnose）\n- 不要求用户启动服务（本 skill 「自主环境准备」 自主环境准备）\n- 不返回摘要响应（详见 「摘要响应禁止」）\n```\n\n### 7.2 各场景特化字段（替换通用骨架的 CONTEXT 段）\n\n**E2E（E2E 开发 / 验收归档，如项目有独立 runner）**：\n```\n- 测试范围: {全量 | 模块名 | 类名}\n- 命令: bash {e2e_runner} {target}（按 项目声明的命令日志落盘纪律 落盘）\n```\n\n**单测（单测开发 / 验收归档）**：\n```\n- 测试范围: {全量 | 类名 | smoke group}\n- 命令: cd {service_dir} && mvn test [-Dtest={ClassName}] [-Dgroups=smoke]（按 项目声明的命令日志落盘纪律 落盘）\n```\n\n**框架测试（pytest 等）**：\n```\n- 测试层级: {L1 unit | L2 component | L3 scene | L4 integration}\n- 命令清单: 从 dev-workflow 节点文件复制（exit.md / track-ut-dev.md）\n```\n\n### 7.3 主会话调用纪律\n\n- **委托 ≠ 甩锅用户**：本机所有依赖服务由 test-executor 启动，禁止要求用户启动\n- **循环上限**：单个测试范围最多循环 **3 次**（启发式阈值），超过 → STOP 质疑架构，向用户报告失败详情\n- **主 Agent 不亲自跑 CLI 测试命令**：必须委托 test-executor；主 Agent 只做 Diagnose + 修代码 + 重跑决策\n- **环境准备是自主环境准备阶段的内嵌任务**：不是独立节点，每次分派 test-executor 都跑（幂等检查）\n\n## 8. 边界与禁止（HARD GATE）\n\n| 禁止项 | 理由 |\n|--------|------|\n| ❌ 编辑任何文件（生产代码、测试代码、配置、文档） | test-executor 只报事实，不修代码；permission.edit/write 已 deny |\n| ❌ 解释失败原因 / 给出修复建议 | Diagnose + 修代码是主会话职责 |\n| ❌ 再委派其他 subagent | 防止无限委托 |\n| ❌ 要求用户启动本机服务（违反本 skill 「自主环境准备」） | 所有本机依赖由 test-executor 自主完成 |\n| ❌ 把 runner 的\"请确认环境\"错误消息转给用户 | 该提示是给人类兜底的，AI 看到环境失败必须自主启动依赖 |\n| ❌ 通过降并发、跳过测试、放宽断言、重启服务、延长等待来\"制造通过\" | 掩盖真实缺陷，最终把风险留到线上 |\n| ❌ 同步命令后 sleep（HARD GATE，详见 项目声明的命令日志落盘纪律） | `mvn ... > log; sleep N; tail log` 是反模式 |\n| ❌ 裸跑全量测试（不走项目 runner / 无隔离机制） | 必须通过 runner 保证并发隔离 + 心跳 + 失败定位（如项目有） |\n| ❌ 在未恢复中间件的情况下跑其他测试 | 容灾测试后必须确认中间件已恢复 |\n| ❌ 主会话在未加载 系统化根因排查流程 时直接修代码 | 主会话纪律；test-executor 不修代码所以无关 |\n\n## 9. 与其他 subagent 的协作\n\n| Agent | 职责 | 与 test-executor 关系 |\n|-------|------|--------------|\n| 主会话 | 调度/设计/编码/Diagnose/修代码/触发测试节点 | 调用 test-executor（每测试节点 1+ 次） |\n| deep (Coder) | 编码实现 | 产出代码 → test-executor 跑测试 → 主会话 Diagnose |\n| **test-executor** | 测试执行 + 自主环境准备 + 结构化报告 | 接收测试委托，不主动调用其他 agent |\n| flow-executor | 流程归档（每节点） | 接收 test-executor 测试结果（经主会话整理）→ 写单测开发 / E2E开发 / 验收归档 节点记录 |\n| 对应场景 reviewer | 各节点审查 | 与 test-executor 无直接交互 |\n| visual-reviewer | 视觉验证 | 与 test-executor 无直接交互（不同维度验证） |\n\n## 10. 故障处理\n\n| 场景 | test-executor 处理 |\n|------|-----------|\n| 中间件探活失败（连接拒绝） | 按 项目依赖清单 自主启动 → 再探活；3 轮仍失败 → 报告卡点（含已尝试命令 + 错误），不抛给用户 |\n| 被测服务启动超时（90s health endpoint 不通） | 查 backend log（tail/grep ERROR）→ 报告启动失败根因（log 路径 + ERROR 行） |\n| runner 返回环境失败 exit code | 按 「自主环境准备」 自主启动依赖后重跑；不抛给用户 |\n| 编译失败（BUILD FAILURE） | 报告编译错误（grep `[ERROR]` 行 + log 路径）；不 Diagnose 原因 |\n| 测试类超时（TIMEOUT） | 在报告中标注 `TIMEOUT (Ns)`，附 log 路径；不擅自调超时 |\n| 并发失败（多类同时挂） | 按业务 bug 或测试隔离缺陷处理报告；禁止降并发掩盖 |\n| 容灾测试后中间件未恢复 | 报告中间件状态；禁止继续跑其他测试 |\n\n> **铁律**：test-executor 遇到任何不确定情况，**报告事实 + 卡点结论**，不自行猜测、修复或抛给用户。test-executor 是执行者不是决策者。",
|
|
442
|
-
"category": "process",
|
|
443
|
-
"version": "4.2.4",
|
|
444
|
-
"references": [],
|
|
445
|
-
"scope": "global"
|
|
446
|
-
},
|
|
447
|
-
{
|
|
448
|
-
"name": "ui-constraints",
|
|
449
|
-
"description": "UI 前端约束 Skill — 实现规范 + 验证硬门控",
|
|
450
|
-
"content": "# UI 前端约束 (ui-constraints)\n\n> **此 Skill 是编排器，实际约束由以下 skill 提供。**\n> 本文件负责：列出所有约束源、注入时机、Agent 映射。\n\n## 约束体系（4 层）\n\n### Layer A: 视觉哲学（Step ① 注入一次）\n\n**Skill**: `frontend-philosophy`\n\n定义整体视觉基调。注入时机：Step ① 设计构思。\n\n5 Pillars:\n- 布局清晰度 / 视觉层级 / 色彩和谐 / 交互反馈 / 动效克制\n\n---\n\n### Layer B: 设计一致性（Step ①③④ 持续注入）\n\n**Skill**: `frontend-consistency`\n\n**CRITICAL 约束 (8 条 — 强制规则)**:\n\n| # | 约束 | 级别 |\n|-----|---------------------------------------------|----------|\n| C1 | React + TypeScript + Tailwind + shadcn/ui 必须使用 | CRITICAL |\n| C2 | Tailwind Class 必须严格按设计 Token 映射表（不可随意类名） | CRITICAL |\n| C3 | shadcn/ui 组件不可 fork 修改（使用 className + variant） | CRITICAL |\n| C4 | 间距/字号/圆角/阴影必须使用 Token 定义（无魔法值） | CRITICAL |\n| C5 | 颜色使用 CSS 变量引用（`var(--primary)`），不直接写 hex/rgb | CRITICAL |\n| C6 | 响应式遵循 Tailwind breakpoint 规范（sm/md/lg/xl/2xl） | CRITICAL |\n| C7 | form/button/dialog 统一使用 shadcn/ui 组件（禁止裸写） | CRITICAL |\n| C8 | Page 组件必须定义 Metadata（title + description） | CRITICAL |\n\n---\n\n### Layer C: 实现规范（Step ③④ 注入）\n\n**Skill**: `ui-implementation`\n\n**3-Pass 生成协议**:\n\n| Pass | 内容 | 验证 |\n|------|----------------------------|---------------------------------|\n| 1 | 完整布局（所有元素） | 结构正确 |\n| 2 | 设计细节（Token 精确匹配） | 样式匹配 Token 表 |\n| 3 | 交互逻辑（状态+事件） | 所有交互路径可用 |\n\n**7 状态模型**（每个页面/组件必须处理）:\n\n1. Loading (加载中)\n2. Empty (空数据)\n3. Error (错误，含 retry)\n4. Unauthorized (401/403)\n5. Edge Cases (边界，如单条数据/超长文本)\n6. Ideal (理想态，完美数据)\n7. Overflow (数据溢出，分页/滚动)\n\n**组件模式**:\n\n| 模式 | 要求 |\n|----------------|----------------------------------------------------------------|\n| 表单 (Form) | react-hook-form + zod 校验 + shadcn/ui Form + 实时校验反馈 |\n| 对话框 (Dialog) | shadcn/ui Dialog + 焦点管理 + Escape 关闭 + 数据不丢失确认 |\n| 反馈 (Toast) | shadcn/ui Sonner + 成功/错误/加载状态 + 自动消失 |\n\n**10 反模式（禁止）**:\n\n1. 禁止裸写原生 HTML 表单（必须 react-hook-form + shadcn/ui）\n2. 禁止 fetch/axios 直接写在组件内（必须 useQuery/useMutation）\n3. 禁止 useState 管理表单状态（必须 react-hook-form）\n4. 禁止手动管理 loading 状态（必须 useQuery isLoading）\n5. 禁止手动管理 error 状态（必须 useQuery isError + ErrorBoundary）\n6. 禁止跳过 7 状态模型\n7. 禁止 inline style（必须 Tailwind class）\n8. 禁止自定义 CSS 文件（必须 Tailwind class）\n9. 禁止跳过 Pass 1-2-3 生成协议\n10. 禁止 UI 完成后跳过 ui-verify HARD GATE\n\n---\n\n### Layer D: 验证硬门控（Step ⑥⑧⑨ 注入）\n\n**Skill**: `ui-verify`\n\n**HARD GATE** — 验证不通过不得提交。\n\n**Playwright MCP E2E 验证 Checklist (CRITICAL)**:\n\n| # | 验证项 | 工具 |\n|-----|--------------------------------|--------------------|\n| V1 | 页面正确渲染（无白屏/报错） | Playwright MCP |\n| V2 | 7 状态模型全部覆盖 | Playwright MCP |\n| V3 | CRUD 全部操作可用 | Playwright MCP |\n| V4 | 表单校验正确触发 | Playwright MCP |\n| V5 | 响应式布局（sm/md/lg/xl）正常 | Playwright MCP |\n| V6 | 颜色/间距匹配设计 Token | 视觉对照 |\n\n**启动脚本约束**:\n```json\n{\n \"scripts\": {\n \"dev\": \"next dev\",\n \"build\": \"next build\",\n \"lint\": \"next lint\",\n \"typecheck\": \"tsc --noEmit\",\n \"test:e2e\": \"playwright test\"\n }\n}\n```\n\n必须先启动 `npm run dev`，启动成功后再运行 Playwright MCP 测试。\n\n---\n\n## 注入矩阵\n\n| Step | 注入层 | Skills 组合 | Agent |\n|------|----------|----------------------------------------------------------------|--------------------------|\n| ① | A+B | frontend-philosophy + frontend-consistency | plan → 对应 reviewer |\n| ③ | B+C | frontend-consistency + ui-implementation | visual-engineering |\n| ④ | B+C | frontend-consistency + ui-implementation | visual-engineering |\n| ⑥ | D | ui-verify (Playwright MCP) | visual-engineering |\n| ⑧ | D (GATE) | ui-verify (HARD GATE 全量) | visual-engineering |\n| ⑨ | B+C+D | 全层对照验收 | 对应 reviewer + 主会话 |\n",
|
|
451
|
-
"category": "process",
|
|
452
|
-
"version": "1.1.1",
|
|
453
|
-
"references": [],
|
|
454
|
-
"scope": "global"
|
|
455
|
-
},
|
|
456
|
-
{
|
|
457
|
-
"name": "ui-implementation",
|
|
458
|
-
"description": "UI 交互实现规范",
|
|
459
|
-
"content": "# UI 交互实现规范\n\nUI 交互逻辑、状态管理和边界处理的强制规则。与 `frontend-consistency`（代码风格）和 `frontend-philosophy`（视觉设计）互补。\n本 skill 只管**交互行为**：组件该有哪些状态、怎么转换、怎么处理边界。\n\n## 角色边界\n\n| 本 skill 覆盖 | 不覆盖（已有 skill） |\n| ---------------------------------------- | ------------------------------------------------- |\n| 状态模型（loading/error/empty/disabled） | 视觉设计、排版、色彩（frontend-philosophy） |\n| 表单验证逻辑、提交模式 | CSS 规范、shadcn 组件选择（frontend-consistency） |\n| 弹窗焦点管理、键盘交互 | 防御式数据流（code-philosophy） |\n| 可访问性交互要求 | 构建工具、项目结构（ui/AGENTS.md） |\n| 3-pass 生成协议 | — |\n\n## 1. 强制状态模型\n\n每个有数据交互的组件**编码前必须声明状态表**：\n\n| 状态 | 必须处理 | 表现形式 |\n| ---------- | -------- | --------------------------------- |\n| `idle` | ✅ | 初始态，等待用户操作 |\n| `loading` | ✅ | `Skeleton` 占位（匹配最终布局结构） |\n| `success` | ✅ | 正常数据展示 |\n| `empty` | ✅ | 引导文案 + CTA 按钮（禁止留白） |\n| `error` | ✅ | 错误信息 + 重试按钮 |\n| `submitting` | 表单必须 | 按钮 disabled + loading spinner |\n| `deleting` | 删除必须 | AlertDialog 按钮 disabled |\n\n**状态转换规则**：\n- `loading` 只能单向转到 `success` / `error` / `empty`\n- `error` 必须提供 `onRetry` 回到 `loading`\n- `submitting` 期间所有表单控件 disabled，按钮显示加载状态\n- 状态变量命名：`loading` / `submitting` / `deleting`（与项目现有代码一致）\n\n## 2. 数据展示模式\n\n### 列表/表格\n\n```tsx\n// 状态渲染顺序（强制）\n{loading ? <Skeleton /> : data.length === 0 ? <Empty /> : <Table />}\n```\n\n**Skeleton 规则**：\n- 行数：3 行占位\n- 列数：匹配实际列数\n- 尺寸：`<Skeleton className=\"h-4 w-full\" />`\n\n**空状态规则**：\n- `<TableCell colSpan={列数} className=\"h-24 text-center text-muted-foreground\">`\n- 必须有引导文案，禁止空白页面\n- 有创建操作时显示 CTA 按钮\n\n### 详情页\n\n- 加载中：整个内容区域用 Skeleton 卡片占位\n- 数据不存在：显示 404 提示 + 返回按钮\n- 部分数据缺失：用 `\"—\"` 占位，禁止空白单元格\n\n## 3. 表单模式\n\n### 技术栈（强制）\n\n`react-hook-form` + `zod` + `@hookform/resolvers/zod` + shadcn `<Form>` / `<FormField>` / `<FormItem>`\n\n### 表单实现规则\n\n1. **Schema 先行**：表单 schema 在组件外定义，`z.object({...})` 声明所有字段和校验规则\n2. **每字段验证**：校验消息用中文，`z.string().min(1, \"XX不能为空\")`\n3. **默认值**：`form.reset()` 时必须传入完整默认值，不允许 partial\n4. **新建/编辑复用**：同一个 Dialog + Form，通过 `editingItem` 状态区分\n5. **提交时 disabled**：`submitting` 状态下 `Button disabled={submitting}`\n6. **成功后刷新**：`onSubmit` 成功 → `setDialogOpen(false)` + `loadData()`\n7. **错误处理**：`catch` 中 `toast.error(error.displayMsg || \"操作失败\")`（ApiError 优先取 displayMsg）\n\n### 数值输入\n\n使用 `useNumericField` hook（项目已有），防止非数字输入。\n\n## 4. 弹窗模式\n\n### Dialog（新建/编辑）\n\n```tsx\n// 开关控制\nconst [dialogOpen, setDialogOpen] = useState(false)\n<Dialog open={dialogOpen} onOpenChange={setDialogOpen}>\n```\n\n- `onOpenChange` 交给 shadcn Dialog 处理（支持 Escape 关闭、点击遮罩关闭）\n- 打开时 `form.reset()` 到对应默认值\n- 提交中不允许关闭：`DialogClose` 不单独控制，靠 `submitting` 状态\n\n### AlertDialog（删除确认）\n\n- 删除前必须弹出确认\n- 确认按钮 `disabled={deleting}`\n- 取消按钮始终可用\n- 确认操作后：`setDeleteDialogOpen(false)` + `setDeletingItem(null)` + `loadData()`\n\n### 焦点管理（Radix 已内置）\n\nshadcn Dialog/AlertDialog 基于 Radix，已自动处理：\n- 打开时焦点移入弹窗\n- Escape 关闭\n- 关闭后焦点恢复到触发按钮\n\n**禁止**：手动管理焦点（如 `autoFocus` ref），除非 Radix 无法覆盖的自定义场景。\n\n## 5. 反馈模式\n\n### Toast（sonner）\n\n| 场景 | 调用 |\n| ---------- | ------------------------------------------- |\n| 创建成功 | `toast.success(\"XX 创建成功\")` |\n| 更新成功 | `toast.success(\"XX 更新成功\")` |\n| 删除成功 | `toast.success(\"XX 删除成功\")` |\n| API 错误 | `toast.error(error.displayMsg \\|\\| \"操作失败\")` |\n| 网络错误 | `toast.error(\"网络错误，请重试\")` |\n\n### 错误处理模式\n\n```tsx\ntry {\n setSubmitting(true)\n await apiCall(data)\n toast.success(\"操作成功\")\n setDialogOpen(false)\n loadData()\n} catch (error) {\n if (error instanceof ApiError) {\n toast.error(error.displayMsg || \"操作失败\")\n } else {\n toast.error(\"操作失败\")\n }\n} finally {\n setSubmitting(false)\n}\n```\n\n**规则**：`finally` 中重置 loading 状态，禁止在 success/error 分支中遗漏。\n\n## 6. 可访问性检查清单\n\n| 层级 | 规则 | 实现方式 |\n| --------- | --------------------------------------- | -------------------------------------- |\n| 语义 HTML | 交互元素用 `<button>`，禁止 `div+onClick` | shadcn 组件已保证 |\n| ARIA | 动态内容用 `aria-live` | `<sonner>` toast 已内置 |\n| 键盘 | Tab 导航、Enter/Space 激活、Escape 关闭 | Radix 基元已内置 |\n| 焦点 | 弹窗内焦点陷阱、关闭后恢复 | Radix Dialog 已内置 |\n| 动效 | 尊重 `prefers-reduced-motion` | Tailwind `motion-safe:` / `motion-reduce:` |\n\n**关键**：使用 shadcn/Radix 组件时，上述大部分已自动满足。自定义交互时必须手动实现。\n\n## 7. 禁止反模式\n\n| # | 反模式 | 正确做法 |\n| -- | -------------------------- | -------------------------------- |\n| 1 | `div onClick` 做按钮 | `<Button>` 或 `<button>` |\n| 2 | 缺 loading 状态 | Skeleton 占位 |\n| 3 | 缺 empty 状态 | 引导文案 + CTA |\n| 4 | 缺 error 状态 + 重试 | `toast.error` + 重试按钮 |\n| 5 | 表单提交无 disabled | `disabled={submitting}` |\n| 6 | 删除无确认弹窗 | AlertDialog 二次确认 |\n| 7 | 通用 Spinner 代替 Skeleton | Skeleton 匹配最终布局 |\n| 8 | `finally` 中遗漏 reset | `finally { setSubmitting(false) }` |\n| 9 | 表单 reset 不传完整默认值 | `form.reset({ 全部字段 })` |\n| 10 | 硬编码列数 colSpan | 用常量或计算列数 |\n\n## 8. AI 生成协议（3-Pass）\n\n每个组件按 3 轮迭代，每轮有明确交付物：\n\n### Pass 1：结构 + Happy Path\n- 组件 Props 接口\n- 状态变量声明（`loading` / `submitting` / `dialogOpen` 等）\n- 数据加载 `useEffect` + API 调用\n- 基础 JSX 结构（只有 success 状态渲染）\n\n### Pass 2：边界状态\n- `<Skeleton>` loading 占位\n- `data.length === 0` 空状态\n- `catch` 错误处理 + `toast.error`\n- 表单 `disabled={submitting}`\n- 删除 AlertDialog + `disabled={deleting}`\n\n### Pass 3：精细交互\n- 状态切换反馈（`handleToggleActive` 模式）\n- 文本截断 + Tooltip（`line-clamp-2` + `TooltipProvider`）\n- 数值输入防护（`useNumericField`）\n- 长文本占位符（`\"—\"` 替代空白）\n\n**前置条件**：编码前必须确定该组件需要的状态表（参考 「状态表」），在注释中声明。\n\n## 9. 状态切换模式（Toggle）\n\n无需弹窗确认的即时切换（如启用/禁用）：\n\n```tsx\nasync function handleToggle(item: Item) {\n try {\n await api.update(item.id, { ...item, enabled: !item.enabled })\n loadData() // 重新加载列表\n } catch (error) {\n if (error instanceof ApiError) {\n toast.error(error.displayMsg || \"切换失败\")\n }\n }\n}\n```\n\n**规则**：直接调用 API → 成功刷新列表 → 失败 toast 提示。不需要 Optimistic Update（管理控制台场景刷新代价低）。\n",
|
|
460
|
-
"category": "process",
|
|
461
|
-
"version": "1.0.0",
|
|
462
|
-
"references": [],
|
|
463
|
-
"scope": "global"
|
|
464
|
-
},
|
|
465
|
-
{
|
|
466
|
-
"name": "multimodal-vision",
|
|
467
|
-
"description": "多模态视觉委托。主力模型通过 multimodal-looker subagent 分析图片/视频/PDF（OCR/图表/UI 验收）。",
|
|
468
|
-
"content": "# 多模态视觉委托\n\n> 主力模型不具备多模态能力时，通过本 skill 委托给 visual-reviewer（siming agent：model=vision-worker）\n>\n> **本 skill 不参与自动发现**，由项目 AGENTS 纪律文件的多模态委托规则触发主力模型主动加载。\n\n## 适用场景\n\n主力模型遇到以下场景时，**必须**加载本 skill 并委托 visual-reviewer：\n\n| 场景 | 典型触发 | 示例 |\n|------|---------|------|\n| **截图/UI 分析** | 用户要求\"看截图\"、\"分析界面\" | 游戏截图、Web 页面、App 界面布局审查 |\n| **OCR 文字识别** | 从图片提取文字 | 截图中的报错、手写笔记、扫描件 |\n| **图表理解** | 分析图表数据 | 柱状图/折线图/饼图数值提取 |\n| **文档问答** | 理解文档截图 | 合同、说明书、设计稿截图 |\n| **视觉对比** | 比较多张图片 | before/after 对比、设计稿 vs 实现 diff |\n| **视频理解** | 分析视频内容 | 录屏分析、操作流程审查 |\n| **PDF 内容提取** | 从 PDF 提取信息 | ⚠️ 需先将 PDF 转为图片再传入 |\n\n## mimo-v2.5 模型能力\n\n| 维度 | 规格 |\n|------|------|\n| **模型** | xiaomi/mimo-v2.5（310B MoE，15B 激活）|\n| **输入模态** | 文本 + 图片 + 视频 + 音频 |\n| **输出** | 纯文本（不支持图片/视频生成）|\n| **上下文窗口** | 1,048,576 tokens（1M）|\n| **最大输出** | 131,072 tokens |\n| **图片格式** | JPEG, PNG, GIF, WebP, BMP |\n| **图片限制** | 单张 ≤50MB，最大 ~4K（8,388,608 像素）|\n| **视频格式** | MP4, MOV, AVI, WMV |\n| **音频格式** | WAV, MP3 |\n\n### 强项（benchmark 参考）\n\n- **GUI 界面理解与定位** — ScreenSpot 89.8%\n- **OCR** — OCRBench 86.5%\n- **图表分析** — CharXiv RQ 81.0\n- **文档理解** — DocVQA 95.2%\n- **视觉推理** — MMMU-Pro 77.9\n- **视频理解** — Video-MME 87.7\n\n### 不支持 / 需预处理\n\n| 限制 | 处理方式 |\n|------|---------|\n| ❌ PDF 原生输入 | 需先转为图片（每页一张 PNG/JPEG），再按多图委托 |\n| ❌ 图片生成 | 仅输出文本分析结果，不能生成图片 |\n| ❌ 本地文件直传 | 需公网 URL 或 Base64 编码（`data:image/jpeg;base64,...`） |\n\n## 委托方式\n\n### 标准委托模板（单图分析）\n\n委派 visual-reviewer subagent（read-only），prompt 模板：\n\n```\n[TASK]: 分析这张 UI 截图的布局问题\n[IMAGE]: /path/to/screenshot.png\n[FOCUS]: 元素对齐、间距一致性、层级关系、文字可读性\n[OUTPUT FORMAT]: 问题清单 + 严重程度(Critical/Major/Minor) + 修复建议\n```\n```\n\n### 多图对比模板\n\n委派 visual-reviewer subagent（read-only），prompt 模板：\n\n```\n[TASK]: 对比设计稿和实现截图的差异\n[IMAGE 1 (设计稿)]: /path/to/design.png\n[IMAGE 2 (实现)]: /path/to/implementation.png\n[FOCUS]: 布局变化、颜色色差、新增/缺失元素\n[OUTPUT]: 差异清单表格，含一致性评分(0-100)\n```\n\n### PDF 处理模板\n\nPDF 需先转图片，再委托多图分析：\n\n```bash\n# 将 PDF 每页转为 PNG（需安装 poppler: brew install poppler）\npdftoppm -png -r 200 document.pdf page\n# 生成 page-1.png, page-2.png, ...\n```\n\n然后按多图委托逐页或批量分析。\n\n## Prompt 最佳实践\n\n### ✅ 高质量 Prompt（产出精确）\n\n- 明确分析维度：\"检查按钮对齐、文字对比度、图标清晰度\"\n- 给出上下文：\"这是登录页面，目标是验证表单布局是否符合设计规范\"\n- 指定输出格式：\"输出 JSON: {issues: [{severity, location, description}]}\"\n- 限制分析范围：\"只关注顶部导航栏区域\"\n\n### ❌ 低质量 Prompt（产出模糊）\n\n- \"看看这张图\" — 太泛，结果不可控\n- \"这好看吗\" — 主观，无法结构化\n- \"有什么问题\" — 无方向，遗漏关键维度\n\n## 常见场景 Prompt 库\n\n### 1. UI 布局审查\n\n```\n[TASK]: 审查 UI 截图的布局质量\n[FOCUS]: 元素对齐、间距一致性、层级关系、文字可读性\n[SCORING]: 按 LAYOUT(40%)/COLOR(20%)/ASSET(20%)/PERF(20%) 四维评分，总分 100\n[OUTPUT]: 各维度得分 + 具体问题清单 + 改进建议\n```\n\n### 2. 报错截图 OCR + 诊断\n\n```\n[TASK]: 提取截图中的错误信息并诊断\n[STEP 1]: OCR 提取所有可见文字\n[STEP 2]: 识别错误类型（编译错误/运行时异常/UI 问题）\n[STEP 3]: 给出可能原因和修复方向\n[OUTPUT]: {error_text, error_type, probable_cause, fix_direction}\n```\n\n### 3. 游戏截图验收（通用，非 Godot 专属）\n\n```\n[TASK]: 审查游戏截图的画面质量和功能完整性\n[FOCUS]: UI 元素渲染、文字显示、色彩还原、画面撕裂/卡顿痕迹\n[OUTPUT]: 问题清单 + 严重程度分级\n```\n\n### 4. 设计稿对比实现\n\n```\n[TASK]: 对比设计稿和实现截图的像素级一致性\n[IMAGE 1 (设计稿)]: <路径>\n[IMAGE 2 (实现)]: <路径>\n[FOCUS]: 布局偏差、颜色色差、字体差异、间距偏差\n[OUTPUT]: 差异清单 + 一致性评分 (0-100)\n```\n\n## 与开发流程各视觉节点的关系\n\n本 skill 是**所有视觉流程的底层多模态能力提供者**。以下 DAG 节点内部调用 visual-reviewer，均依赖本 skill 提供的多模态委托能力：\n\n| DAG 节点 | 文件 | 视觉职责 | 模型 |\n|----------|------|---------|------|\n| **UI 视觉验证**（UI 轨道）| `track-visual.md` | Playwright MCP 截图 → 5 维度审核（状态完整性/可访问性/组件标准/边界场景/交互质量）| mimo-v2.5 |\n| **E01 集成回归**（Exit）| `exit-regression.md` | 视觉 diff ≤ 5%、元素位移 ≤ 2px、CSS 断点无退化 | mimo-v2.5 |\n| **E02 最终验收**（Exit）| `exit-acceptance.md` | 截图矩阵 + UI 4 维评分，HARD GATE ≥ 80 | mimo-v2.5 |\n\n### 视觉验收与本 skill 的关系\n\n本 skill 是**底层多模态能力提供者**。项目视觉验收流程（截图矩阵 + 评分标准 + 修复循环）内部调用 visual-reviewer 执行实际的截图分析。即：\n\n```\n项目视觉验收（专属流程封装）\n └── 内部调用 visual-reviewer → 本 skill 提供多模态能力\n```\n\n> **调用规则**：\n> - UI 项目视觉验证（UI 视觉验证节点）→ 加载 `ui-verify` + 本 skill\n> - 其他通用多模态场景（截图分析/PDF/OCR/图表）→ 直接加载本 skill\n\n## 参考资料\n\n- [MiMo-V2.5 官方页面](https://mimo.xiaomi.com/mimo-v2-5/)\n- [HuggingFace 模型卡](https://huggingface.co/XiaomiMiMo/MiMo-V2.5)\n- [API 文档](https://platform.xiaomimimo.com/docs/en-US/)\n",
|
|
469
|
-
"category": "tooling",
|
|
470
|
-
"version": "1.1.1",
|
|
471
|
-
"references": [],
|
|
472
|
-
"scope": "global"
|
|
473
|
-
},
|
|
474
|
-
{
|
|
475
|
-
"name": "config-java",
|
|
476
|
-
"description": "",
|
|
477
|
-
"content": "# Java 后端轨道配置 (config-java)\n\n> 到达各 DAG 节点时，主 Agent 按本表加载对应 Agent + Skills。本文件为运行时参考，不替代各 track-*.md 的 HARD GATE 约束。主会话委托 subagent 时，从项目 AGENTS.md 读栈信息（文件约定/栈特定约束/配置管理）拼接注入。\n\n---\n\n## 一、Per-Node Agent 映射表（siming 12-agent 体系，skill 固化绑定）\n\n> 到达各 DAG 节点时按本表指名委派。agent 的 boundSkills 已固化，主会话无需在 prompt 中声明 skill 清单。\n\n| 节点 | 角色 | Agent | 验证方式 |\n|------|------|-------|---------|\n| 后端编码 | Implementer | 主会话（编码不委派） | code-reviewer 审分层架构 + REST/MVC 规范 + 持久层规范（标准见项目 AGENTS.md 与 java-constraints） |\n| 后端编码 | Verifier | code-reviewer | 独立上下文，零偏差审核 |\n| 单测设计 | Designer | 主会话 | test-reviewer 审核覆盖度 |\n| 单测开发 | Coder | 主会话 | 单测全量 100% PASS（执行委派 test-executor；命令见项目 AGENTS.md COMMANDS） |\n| E2E 设计 | Designer | 主会话 | test-reviewer 审核覆盖度 |\n| E2E 开发 | Coder | 主会话 | 委派 test-executor 跑项目声明的 E2E 入口全部通过 |\n| 验收归档 | Executor | test-executor | 全量回归：自主环境准备 + E2E + 单测 + 信息收集 |\n| 验收归档 | Analyst | regression-reviewer | 不变量验证：分析回归报告 + 不变量 + Diff（只读分析） |\n| 验收归档 | Reviewer | 主会话 | 验收确认：事实对照 |\n| 验收归档 | Archiver | flow-executor | 归档：siming 命令写节点记录 + advance + 项目 git 杂活 |\n\n> **Worker/Verifier 分离（HARD GATE）**：Worker 和 Verifier 必须是不同 session。Verifier 不继承 Worker 上下文，只读审核不改代码。\n>\n> **java-constraints skill 按层级注入**：编码规范/架构约束/E2E 规范打包在 java-constraints skill（Layer A/B/C），主会话编码时加载对齐。\n## 二、4 层验证链触发点\n\n| 验证层 | 名称 | 触发时机 | 执行方式 |\n|--------|------|---------|---------|\n| 语法验证 | LSP diagnostics | 后端编码 PostToolUse hooks | 静态分析（工具/命令见项目 AGENTS.md COMMANDS） |\n| 语义验证 | Verifier(code-reviewer) | 后端编码完成后 | `arch-review` → Layer B 抽象约束审核；code-reviewer 独立 session |\n| 集成验证 | 冒烟测试 | 验收归档·全量回归开始 | 冒烟测试（命令见项目 AGENTS.md COMMANDS） |\n| 回归验证·后端单测 | 全量单测回归 | 验收归档·全量回归完成 | 全量单测回归（命令见项目 AGENTS.md COMMANDS） |\n| 回归验证·E2E | E2E 回归 | 验收归档·全量回归完成 | 项目声明的 E2E 入口（E2eTester 脚手架标配工程，打真实部署服务） |\n\n> **回归验证·后端单测/E2E 分离原则**：单测在后端项目内（按项目测试框架，见项目 AGENTS.md「测试范式」），E2E 在 E2eTester 独立项目（脚手架标配，打真实部署服务）。两项目平级，命令分开执行。\n> 视觉验证不适用于 Java 后端轨道，跳过。\n\n---\n\n## 三、文件约定\n\n> **文件约定（包结构/分层模型/各层命名与基类/响应包装类型/DTO 命名/异常处理等）是项目特定信息，由项目 AGENTS.md「文件约定」承载（接入项目时 AI 探测填）。**\n> 主会话编码时直接读取项目 AGENTS.md「文件约定」等三节对齐栈信息（见 `track-code.md`「编码自律约束段」）.\n\n\n## 四、构建命令\n\n> **CLI 日志落盘（HARD GATE）**：所有构建/测试/E2E 命令必须按 项目声明的命令日志落盘纪律（若有） 落盘。\n\n### 命令来源\n\n> 具体 build/test/lint/run 命令是项目特定信息，**见项目 AGENTS.md「COMMANDS」**（接入项目时 AI 探测填，含全量/单类/smoke/编译/静态分析/启动/E2E 等变体）。本节只描述执行模式与落盘纪律。\n\n### 执行模式（测试执行 = 委派 test-executor，无条件）\n\n> 适用节点：单测开发、E2E 开发、验收归档（集成回归+验收）、任意跑测试的时机。\n> 对应 项目 AGENTS 编排文件.md「测试执行 HARD GATE」。\n\n**唯一规则：所有测试执行 → 委派 test-executor，无例外。** 主会话禁止亲自跑测试命令（`mvn test` / `vitest` / `pytest` / 任何含断言的验证脚本）。命令会触发测试（含 `mvn install`/`verify`/`package`，或 `npm run build` 带 prebuild 钩子）→ 同样 委派 test-executor；纯编译/构建（`mvn compile` / `tsc` / `npm run build` 无测试钩子）→ 主会话直接执行。\n\n| 角色 | 职责 |\n|------|------|\n| test-executor | 执行所有测试命令，返回结构化结果（Final Output Contract） |\n| 主会话 | 写测试代码 → 委派 test-executor 跑 → 接收结果 → Diagnose 修复 → 委派 test-executor 重跑 |\n| regression-reviewer | 审核回归结果（独立 session） |\n\n**分工纪律**：\n- test-executor 只报事实（PASS/FAIL/统计、log 关键行），**不解释原因、不改文件**\n- **委托 ≠ 甩锅用户**：本机所有服务依赖由 test-executor 自主拉起。test-executor 返回 FAIL → 主 Agent 走 系统化根因排查流程 自主 Diagnose → 修代码 → 再次委托 test-executor 重跑，全链路闭环\n- 完整流程模板（Apply→Diagnose→Iterate + test-executor 委托 prompt + 暂停条件）见 `exit.md`「全量回归」\n\n**test-executor 委托 prompt 骨架**（主 Agent 调度时套用）：\n\n> `dev-workflow-tester` skill 已固化绑定于 test-executor agent，主会话无需在 prompt 中声明 skill 清单。Final Output Contract / 三阶段工作流 / 自主环境准备等约束已在 skill 内，主会话**无需**在 prompt 里重复。\n\n委派 test-executor subagent，prompt 骨架：\n\n```text\n[TASK] 跑下列命令并返回结构化结果（按 dev-workflow-tester skill「Final Output Contract」 输出）\n[CONTEXT] monorepo 根路径 + 自动 session-id（按 项目声明的命令日志落盘纪律（若有））\n[EXPECTED] 各命令 BUILD SUCCESS/FAILURE + Tests run 统计 + 失败用例清单\n[MUST DO] 命令逐条执行（命令取自项目 AGENTS.md COMMANDS）、按 项目声明的命令日志落盘纪律（若有） 落盘\n[MUST NOT DO] 不修改任何文件、不解释原因只报事实（skill 「责任边界」 已规定）\n```\n\n### 命令模板（落盘纪律，命令值取自项目 AGENTS.md COMMANDS）\n\n> 编译/构建命令主会话直接执行，按 项目声明的命令日志落盘纪律（若有） 落盘。测试命令 委派 test-executor（「测试执行一律委派 test-executor」纪律），test-executor 内部落盘。\n\n```bash\n# 编译（主会话直接执行，按 项目声明的命令日志落盘纪律（若有） 落盘）\n{构建命令-编译}\n\n# 静态分析（语法验证，主会话直接执行，按 项目声明的命令日志落盘纪律（若有） 落盘）\n{构建命令-静态分析}\n\n# 以下测试命令均 委派 test-executor（「测试执行一律委派 test-executor」纪律）\n# 单测全量 / 单测单类 / 冒烟测试 → 命令值见项目 AGENTS.md COMMANDS，test-executor 内部按 项目声明的命令日志落盘纪律（若有） 落盘\n```\n\n### E2E 测试（脚手架标配工程 `E2eTester/`，在 monorepo 根执行，委派 test-executor）\n\n> **E2E 工程**：E2E 模块的开发规范、分层架构、类命名、执行入口用法详见项目 E2E 测试规范文档（按项目声明）。\n\n> E2E 执行由 test-executor 完成（「测试执行一律委派 test-executor」纪律），test-executor 按三阶段执行（自主环境准备 → 项目声明的 E2E 入口 → Final Output Contract），日志按 项目声明的命令日志落盘纪律（若有） 落盘。\n\n> ⚠ E2E 工程由项目维护方管理。项目声明的 E2E 入口或工程不存在 → 跳过 E2E 命令，在节点记录 summary 标注「E2E 暂挂（原因）」。禁止绕过项目声明的执行入口裸跑构建验证命令。\n\n---\n\n## 五、Java 约束体系（3 层）\n\n| 约束层 | 名称 | 范围 | 注入节点 | 核心规则 |\n|--------|------|------|---------|---------|\n| Layer A | 代码约束 | 编码风格、代码哲学 5 Laws | 后端编码 | `code-philosophy` 5 Laws（Simplicity / DRY / Testability / Correctness / Maintainability） |\n| Layer B | 架构约束 | 分层架构、REST 规范、安全设计（抽象通用） | 后端编码, 验收归档 | 见下方速查（抽象原则，具体技术选型见项目 AGENTS.md） |\n| Layer C | E2E 约束 | API 测试规范、执行流程、覆盖率（E2eTester 脚手架标配） | 单测设计/E2E 开发, 验收归档 | E1-E7 规则（REST Assured DSL / 3 并发 / BaseE2eTest 继承） |\n\n### Layer B — 10 CRITICAL 架构约束清单（后端编码 code-reviewer 审核清单 + 主会话编码自律清单）\n\n> **前导（装配约定）**：本清单为**跨项目通用的抽象架构约束**（Java 后端行业最佳实践）。具体技术选型（响应类型、持久层工具、配置工具、测试库等）是项目特定信息，见项目 AGENTS.md。\n> 主会话编码时，**直接读取项目 AGENTS.md**（「文件约定」「栈特定约束」「配置管理」），与本表对齐后编码。\n\n| 编号 | 约束项 | 性质 | 说明 |\n|------|--------|------|------|\n| B1 | 分层隔离 | 抽象原则 | 遵循项目分层架构，禁止跨层调用（层结构/层名见项目 AGENTS.md「文件约定」） |\n| B2 | 统一响应格式 | 抽象原则 | 所有 API 统一响应包装（包装类型见项目 AGENTS.md「文件约定」） |\n| B3 | Bean Validation 校验注解 | 通用 | `@NotNull`, `@Size`, `@Email`, `@Valid` 在 Controller 入参激活（Jakarta Validation 行业标准） |\n| B4 | API 文档注解 | 按项目 | 公开 API 应有文档注解（如项目使用 API 文档工具，具体见项目 AGENTS.md） |\n| B5 | 事务管理 | 通用 | 写操作使用 `@Transactional`，只读使用 `@Transactional(readOnly = true)`（Spring 行业标准） |\n| B6 | 异常分层 | 通用 | 统一异常处理层捕获（`@ControllerAdvice` / `@RestControllerAdvice`），Service 层抛业务异常 |\n| B7 | DTO 隔离 | 通用 | Entity 不直接暴露到 Controller 层，通过 DTO 转换 |\n| B8 | 安全设计 | 抽象原则 | 认证/鉴权拦截、敏感字段脱敏、输入防注入（具体机制见项目 AGENTS.md「栈特定约束」） |\n| B9 | 配置管理 | 抽象原则 | 新增配置 key 含注释（用途/默认值/取值范围），配置管理工具/约定见项目 AGENTS.md「配置管理」 |\n| B10 | 数据库变更 | 抽象原则 | 数据库变更有变更管理（DDL 增量同步），策略/测试库见项目 AGENTS.md「栈特定约束」 |\n\n### Layer B — 5 WARNING（≤ 2 violation 可接受）\n\n| 编号 | 约束项 | 说明 |\n|------|--------|------|\n| BW1 | 方法长度 ≤ 40 行 | 超过需拆分 |\n| BW2 | 参数数量 ≤ 5 | 超过考虑封装为 DTO |\n| BW3 | 日志规范 | 关键业务节点记录日志，错误含堆栈（日志框架/规范见项目 AGENTS.md「栈特定约束」） |\n| BW4 | 魔法数字 | 常量提取至 `Constants` 类或配置文件 |\n| BW5 | 依赖注入 | 遵循项目注入风格（构造器/字段，见项目 AGENTS.md「栈特定约束」） |\n\n### Layer C — E2E 测试规范速查（E2eTester 脚手架标配工程）\n\n| 编号 | 规则 | 说明 |\n|------|------|------|\n| E1 | REST Assured DSL | `given().spec(baseSpec).when().get(...).then()...` |\n| E2 | API 路由常量 | `ApiRoutes` 类集中管理，禁止硬编码 URL 字符串 |\n| E3 | 请求体 POJO | `@Data` + `@Builder` + `@JsonProperty`，禁止 `Map` |\n| E4 | 异步等待 | `await().atMost(Duration.ofSeconds(30)).untilAsserted(...)` |\n| E5 | 测试类继承 | 继承 `BaseE2eTest`，文件命名 `{Feature}E2eTest.java` 或 `{Feature}IT.java` |\n| E6 | 3 并发执行 | `dev-workflow-tester` 规定的并发策略 |\n| E7 | 失败处理 | Level 1（重试） → Level 2（隔离重跑） → Level 3（报告） |\n\n---\n\n## 六、Skill 加载优先级\n\n| 优先级 | Skill | 加载时机 |\n|--------|-------|---------|\n| 1 | `code-philosophy` | 全局（所有轨道、所有节点） |\n| 2 | `java-constraints` | 后端编码, 单测设计/E2E 开发, 验收归档（按层级注入） |\n| 3 | 节点专属 skill | agent 已固化绑定（boundSkills），无需传递 |\n\n> `code-philosophy` 的 5 Laws 为全局约束，所有 subagent 必须遵守。在 后端编码 中与 `java-constraints` Layer A 叠加生效。\n",
|
|
478
|
-
"category": "process",
|
|
479
|
-
"version": "2.0.4",
|
|
480
|
-
"references": [],
|
|
481
|
-
"scope": "global"
|
|
482
|
-
},
|
|
483
|
-
{
|
|
484
|
-
"name": "config-node",
|
|
485
|
-
"description": "",
|
|
486
|
-
"content": "# Node/TS 后端轨道配置 (config-node)\n\n> 到达各 DAG 节点时，主 Agent 按本表加载对应 Agent + Skills。本文件为运行时参考，不替代各 track-*.md 的 HARD GATE 约束。主会话委托 subagent 时，从项目 AGENTS.md 读栈信息（文件约定/栈特定约束/配置管理）拼接注入。\n>\n> **与 config-java.md 的关系**：config-java.md 是 Java/Spring 轨的参考实现；本文件是 Node/TypeScript 轨的等价物。同一项目只用其中一个（按项目 AGENTS.md 技术栈速查表判定）。\n\n---\n\n## 一、Per-Node Agent 映射表（siming 12-agent 体系，skill 固化绑定）\n\n> 到达各 DAG 节点时按本表指名委派。agent 的 boundSkills 已固化，主会话无需在 prompt 中声明 skill 清单。\n\n| 节点 | 角色 | Agent | 验证方式 |\n|------|------|-------|---------|\n| 后端编码 | Implementer | 主会话（编码不委派） | code-reviewer 审核分层架构 + HTTP 规范 + 持久层规范（标准见项目 AGENTS.md） |\n| 后端编码 | Verifier | code-reviewer | 独立上下文，零偏差审核 |\n| 单测设计 | Designer | 主会话 | test-reviewer 审核覆盖度 |\n| 单测开发 | Coder | 主会话（编码不委派） | 单测全量 100% PASS（执行委派 test-executor，Coder 只写测试代码；命令见项目 AGENTS.md COMMANDS） |\n| E2E 设计 | Designer | 主会话 | test-reviewer 审核覆盖度（通过后直接推进 E2E 开发） |\n| E2E 开发 | Coder | 主会话 | 委派 test-executor 跑项目声明的 E2E 入口全部通过 |\n| 验收归档 | Executor | test-executor | 全量回归：自主环境准备 + E2E + 单测 + 信息收集 |\n| 验收归档 | Analyst | regression-reviewer | 不变量验证：分析回归报告 + 不变量 + Diff（只读分析） |\n| 验收归档 | Reviewer | 主会话 | 验收确认：事实对照（引用审查结论，不重审） |\n| 验收归档 | Archiver | flow-executor | 归档：siming 命令写节点记录 + advance + 项目声明的 git 操作 |\n\n> **Worker/Verifier 分离（HARD GATE）**：Worker 和 Verifier 必须是不同 session。Verifier 不继承 Worker 上下文，只读审核不改代码。\n>\n> **Node/TS 轨无 Java 专属约束 skill**：编码规范和测试规范内联在本文件 §五，主会话编码时从本文件 §五 + 项目 AGENTS.md 读取对齐。\n## 二、4 层验证链触发点\n\n| 验证层 | 名称 | 触发时机 | 执行方式 |\n|--------|------|---------|---------|\n| 语法验证 | LSP diagnostics / tsgo | 后端编码 PostToolUse hooks | 类型检查 + 静态分析（命令见项目 AGENTS.md COMMANDS） |\n| 语义验证 | Verifier(code-reviewer) | 后端编码完成后 | `arch-review` → §五 Layer B 抽象约束审核；`code-reviewer` 独立 session |\n| 集成验证 | 冒烟测试 | 验收归档·全量回归开始 | 冒烟命令见项目 AGENTS.md COMMANDS || 回归验证·单测 | 全量单测回归 | 验收归档·全量回归完成 | 单测全量回归（命令见项目 AGENTS.md COMMANDS） |\n| 回归验证·E2E | E2E 回归 | 验收归档·全量回归完成 | E2E 回归（执行入口见项目 AGENTS.md COMMANDS） |\n\n> 视觉验证不适用于 Node 后端轨道，跳过。\n\n---\n\n## 三、文件约定\n\n> **文件约定（包结构/分层模型/各层命名/响应包装类型/DTO 命名/异常处理等）是项目特定信息，由项目 AGENTS.md「文件约定」承载（接入项目时 AI 探测填）。**\n> 主会话编码时直接读取项目 AGENTS.md「文件约定」等三节对齐栈信息（见 `track-code.md`「编码自律约束段」）.\n\n\n## 四、构建命令\n\n> **CLI 日志落盘（HARD GATE）**：所有构建/测试/E2E 命令必须按 项目声明的命令日志落盘纪律（若有） 落盘。\n\n### 命令来源\n\n> 具体 build/test/lint/run 命令是项目特定信息，**见项目 AGENTS.md「COMMANDS」**（接入项目时 AI 探测填，含全量/单类/smoke/编译/静态分析/启动/E2E 等变体）。本节只描述执行模式与落盘纪律。\n\n### 执行模式（测试执行 = 委派 test-executor，无条件）\n\n> 适用节点：单测开发、E2E 开发、验收归档（集成回归+验收）、任意跑测试的时机。\n> 对应 项目 AGENTS 编排文件.md「测试执行 HARD GATE」。\n\n**唯一规则：所有测试执行 → 委派 test-executor，无例外。** 主会话禁止亲自跑测试命令（任何测试命令/含断言的验证脚本）。命令会触发测试（含构建命令带测试钩子的情形）→ 同样 委派 test-executor；纯编译/构建（纯构建/类型检查/静态分析类命令）→ 主会话直接执行。\n\n| 角色 | 职责 |\n|------|------|\n| test-executor | 执行所有测试命令，返回结构化结果（Final Output Contract） |\n| 主会话 | 写测试代码 → 委派 test-executor 跑 → 接收结果 → Diagnose 修复 → 委派 test-executor 重跑 |\n| `code-reviewer` | 审核回归结果（独立 session） |\n\n**分工纪律**：\n- test-executor 只报事实（PASS/FAIL/统计、log 关键行），**不解释原因、不改文件**\n- **委托 ≠ 甩锅用户**：本机所有服务依赖由 test-executor 自主拉起。test-executor 返回 FAIL → 主 Agent 走系统化根因排查 自主 Diagnose → 修代码 → 再次委托 test-executor 重跑，全链路闭环\n- 完整流程模板（Apply→Diagnose→Iterate + test-executor 委托 prompt + 暂停条件）见 exit skill「全量回归」\n\n**test-executor 委托 prompt 骨架**（主 Agent 调度时套用）：\n\n> `dev-workflow-tester` skill 已固化绑定于 test-executor agent，主会话无需在 prompt 中声明 skill 清单。Final Output Contract / 三阶段工作流 / 自主环境准备等约束已在 skill 内，主会话**无需**在 prompt 里重复。\n\n委派 test-executor subagent，prompt 骨架：\n\n```text\n[TASK] 跑下列命令并返回结构化结果（按 test-executor 结构化报告契约输出）\n[CONTEXT] monorepo 根路径 + 自动 session-id（按 项目声明的命令日志落盘纪律（若有））\n[EXPECTED] 各命令 Test Files/Tests 统计 + 失败用例清单\n[MUST DO] 命令逐条执行（命令取自项目 AGENTS.md COMMANDS）、按 项目声明的命令日志落盘纪律（若有） 落盘\n[MUST NOT DO] 不修改任何文件、不解释原因只报事实（skill 「责任边界」 已规定）\n```\n\n### E2E 测试（Playwright runner，在 monorepo 根执行，委派 test-executor）\n\n> **E2E 执行形态**：E2E 框架与执行入口按项目 AGENTS.md 声明（Playwright API testing 为常见形态）。\n>\n> E2E 执行由 test-executor 完成（「测试执行一律委派 test-executor」纪律），test-executor 按三阶段执行（自主环境准备 → 项目声明的 E2E 入口 → Final Output Contract），日志按 项目声明的命令日志落盘纪律（若有） 落盘。\n\n> ⚠ 项目未声明 E2E 入口或 E2E 环境不存在 → 跳过 E2E 命令，在节点记录 summary 标注「E2E 暂挂（原因）」。\n\n---\n\n## 五、Node/TS 约束体系（3 层）\n\n> **Node/TS 轨无 `java-constraints` skill**：Java 轨的编码规范/架构约束/E2E 规范打包在 `java-constraints` skill 里（Layer A/B/C）。Node/TS 轨没有等价 skill，**约束全部内联在本节**。主会话编码时，从本文件 §五 + 项目 AGENTS.md 读取对齐。\n\n| 约束层 | 名称 | 范围 | 注入节点 | 核心规则 |\n|--------|------|------|---------|---------|\n| Layer A | 代码约束 | 编码风格、代码哲学 5 Laws | 后端编码 | `code-philosophy` 5 Laws（Simplicity / DRY / Testability / Correctness / Maintainability） |\n| Layer B | 架构约束 | 分层架构、HTTP 规范、安全设计（抽象通用） | 后端编码, 验收归档 | 见下方速查（抽象原则，具体技术选型见项目 AGENTS.md） |\n| Layer C | E2E 约束 | API 测试规范、执行流程、覆盖率 | 单测设计/E2E 开发, 验收归档 | N1-N7 规则（Playwright API testing / vitest 集成测试） |\n\n### Layer A — code-philosophy 5 Laws（全局，code-philosophy skill 承载）\n\n与 Java 轨一致，不重复。主会话 + 所有 subagent 均须加载 `code-philosophy` skill。\n\n### Layer B — 10 CRITICAL 架构约束清单（后端编码 code-reviewer 审核清单 + 主会话编码自律清单）\n\n> **前导（装配约定）**：本清单为**跨项目通用的抽象架构约束**（Node/TS 后端行业最佳实践）。具体技术选型（框架版本、连接串、配置工具等）是项目特定信息，见项目 AGENTS.md。\n> 主会话编码时，**直接读取项目 AGENTS.md**（「文件约定」「栈特定约束」「配置管理」），与本表对齐后编码。\n>\n> **权威源**：typescriptlang.org/tsconfig / zod.dev / hono.dev/guides/best-practices / mongodb.com/docs/drivers/node-current / vitest.dev（官方文档 + 多源交叉验证）。\n\n| 编号 | 约束项 | 性质 | 说明 | 权威源 |\n|------|--------|------|------|--------|\n| B1 | 分层隔离 | 抽象原则 | 遵循项目分层架构（包结构见项目 AGENTS.md），禁止跨层调用（如 server routes 直接操作 MongoDB driver，必须经 core repos） | hono.dev/guides/best-practices（Don't make Controllers）；项目 AGENTS.md |\n| B2 | 统一响应格式 | 抽象原则 | 所有 API 统一响应格式；Hono 用 `OpenAPIHono` + `createRoute()` 定义路由，`c.json()` 返回；DTO 类型从 Zod schema 推导（`z.infer<typeof Schema>`） | hono.dev/examples/zod-openapi；zod.dev |\n| B3 | Zod 边界校验 | 通用 | 所有外部输入（HTTP body/param/query、env、MCP args）必须经 Zod schema 校验；用 `safeParse()` 不用 `parse()`（避免抛异常）；`@hono/zod-openapi` 的 `defaultHook` 统一校验错误格式 | zod.dev（safeParse vs parse）；@hono/zod-openapi docs |\n| B4 | OpenAPI 文档 | 通用 | 公开 API 必须有 OpenAPI 定义；用 `@hono/zod-openapi` 的 `.openapi('ComponentName')` 自动注册 schema，导出 spec 供 CLI/Web 生成 typed client | hono.dev/examples/zod-openapi |\n| B5 | 事务管理 | 通用 | MongoDB 写操作使用 transactions；用 `client.withSession(s => s.withTransaction(async session => { ... }))` Convenient API（自动 commit/retry）；**事务内禁止 `Promise.all()`**（session 并行导致服务器错误） | mongodb.com/docs/drivers/node-current/crud/transactions |\n| B6 | 异常分层 | 通用 | 统一异常处理：`app.onError()` 集中捕获 → 转换为 HTTP 响应；业务层抛 typed Error（自定义 AppError 子类）；预期失败用 Result type `{ success, data } | { success: false, error }` | hono.dev/docs/api/hono（onError）；neverthrow pattern |\n| B7 | DTO 隔离 | 通用 | MongoDB document ↔ API response 之间通过 Zod schema 转换；repo 层返回 `z.infer<typeof XxxSchema>` 类型，不直接暴露 MongoDB 原始 BSON；`db.collection<DocumentType>()` 做类型安全 | zod.dev（z.infer）；mongodb.com/docs/drivers/node-current |\n| B8 | 安全设计 | 抽象原则 | Phase-1 本地单用户无 auth；预留 `?token=` 入参；敏感字段（密码/token）不出现在 API response；输入经 Zod 校验防注入（Zod schema 限制类型+格式） | 项目 AGENTS.md「栈特定约束」 |\n| B9 | 配置管理 | 抽象原则 | 环境变量用 Zod schema 启动时一次性解析（fail-fast）；配置 key 用 `SIMING_*` 前缀；新增 key 必须在项目声明的环境说明文档中文档化 | @t3-oss/env pattern；zod.dev |\n| B10 | 数据库变更 | 抽象原则 | MongoDB schema validation（JSON Schema at DB level）做最后一层兜底；应用层 Zod 做主验证；index 变更有显式 `createIndex()` 调用 | mongodb.com/docs/manual/core/schema-validation |\n\n### Layer B — 5 WARNING（≤ 2 violation 可接受）\n\n| 编号 | 约束项 | 说明 | 权威源 |\n|------|--------|------|--------|\n| BW1 | 函数长度 ≤ 40 行 | 超过需拆分（handler 函数尤其要注意，Hono 不建 Controller 但 handler 也不宜过长） | 通用 |\n| BW2 | 参数数量 ≤ 5 | 超过考虑封装为 object（用 Zod schema 定义参数对象） | 通用 |\n| BW3 | 日志规范 | 关键业务节点记录日志；Phase-1 用 `console.log/error`，UC1 plan 引入结构化日志（pino）；错误含堆栈 | 项目 AGENTS.md |\n| BW4 | 魔法数字 | 提取为常量（`const MAX_RETRIES = 3`）或配置（Zod env schema） | 通用 |\n| BW5 | 函数式注入 | 无 DI 框架；参数显式传递（函数式风格，避免 Effect/Inversify）；repo 函数接收 `client: SimingClient` 参数 | 项目 AGENTS.md |\n\n### Layer B — TypeScript 编码规范（替代 `java-constraints` Layer A）\n\n> Java 轨的编码风格约束（命名/注释/null 处理/异常处理）由 `java-constraints` skill 承载。Node/TS 轨无等价 skill，**约束内联在此**。以下规则来自 typescriptlang.org 官方 tsconfig 参考 + Total TypeScript / Matt Pocock 推荐 + 多源验证。\n\n| 规则 | 说明 | 权威源 |\n|------|------|--------|\n| **禁 `any` / `as` 断言** | `as any` / `as unknown as T` 禁用；类型不确定时用 Zod parse 校验或显式泛型 | typescriptlang.org/tsconfig（strict） |\n| **禁 `enum`** | 用 `as const` 对象 + union type 替代（`const Status = { ACTIVE: 'active', ... } as const; type Status = typeof Status[keyof typeof Status]`） | Total TypeScript best practices |\n| **ESM `.js` 扩展名** | `verbatimModuleSyntax: true` 下，所有相对 import 用 `.js` 扩展名（即使源文件是 `.ts`） | typescriptlang.org/tsconfig（verbatimModuleSyntax） |\n| **`import type` 分离** | 仅用于类型的 import 用 `import type { ... }`（`verbatimModuleSyntax` 强制） | typescriptlang.org/tsconfig |\n| **`noUncheckedIndexedAccess`** | 数组/对象索引访问返回 `T \\| undefined`，必须做 null check | typescriptlang.org/tsconfig |\n| **`exactOptionalPropertyTypes`** | 可选属性不能赋 `undefined`（要么有值，要么不写 key） | typescriptlang.org/tsconfig |\n| **错误处理** | `throw new AppError(...)` 用于不可预期错误；`safeParse()` / Result type 用于可预期失败；**禁止空 `catch (e) {}`**（至少 `console.error(e)` + rethrow 或 return error state） | zod.dev（safeParse）；neverthrow pattern |\n| **`__dirname` 替代** | ESM 无 `__dirname`；用 `import.meta.dirname`（Node 22+）或 `fileURLToPath(new URL('.', import.meta.url))` | nodejs.org/api/esm.html |\n\n### Layer C — E2E 测试规范速查（Playwright API testing）\n\n> Java 轨用 TestNG + REST Assured（E2eTester 脚手架标配），规则 E1-E7。Node/TS 轨用 **Playwright**（API testing via `APIRequestContext`），规则 N1-N7。\n\n| 编号 | 规则 | 说明 | 权威源 |\n|------|------|------|--------|\n| N1 | `request` fixture | API 测试用 Playwright 内置 `request` fixture（test-scoped，自动 dispose），不用 `playwright.request.newContext()`（需手动 dispose） | playwright.dev/docs/api-testing |\n| N2 | baseURL + headers | `playwright.config.ts` 中配置 `baseURL` + `extraHTTPHeaders`（如 `Accept: application/json`），test 中用相对路径 | playwright.dev/docs/api-testing |\n| N3 | Zod response 校验 | API response 用 Zod schema 校验（`Schema.safeParse(await response.json())`），断言 `success: true`；禁止只断言 HTTP status 不校验 body | zod.dev |\n| N4 | test-scoped fixture | 数据隔离：每个 test 用 fixture 创建独立数据（`test.extend<{ apiContext: APIRequestContext }>(...)`），test 结束自动 dispose | playwright.dev/docs/test-fixtures |\n| N5 | `testInfo.workerIndex` | 需要唯一标识时用 `testInfo.workerIndex`（单调递增），不用 `parallelIndex`（0~workers-1 可能重复） | playwright.dev/docs/api-testing |\n| N6 | API + UI 混合 | API seed → UI 验证 / UI 操作 → API 校验；`storageState` 共享 cookie/session | playwright.dev/docs/api-testing |\n| N7 | 失败处理 | `testInfo.attach()` 附加请求 URL/headers/status/body 到失败报告；retry 配置在 `playwright.config.ts`（API 测试 `retries: 0` 或 `1`） | playwright.dev/docs/test-annotations |\n\n---\n\n## 六、Skill 加载优先级\n\n| 优先级 | Skill | 加载时机 |\n|--------|-------|---------|\n| 1 | `code-philosophy` | 全局（所有轨道、所有节点） |\n| 2 | **本文件 §五 内联约束**（替代 `java-constraints`） | 后端编码, 单测设计/E2E 开发, 验收归档 |\n| 3 | 节点专属 skill | 后端编码→`arch-review`；验收归档→`dev-workflow-tester`（固化绑定） |\n\n> `code-philosophy` 的 5 Laws 为全局约束，所有 subagent 必须遵守。在 后端编码 中与本文件 §五 Layer B 叠加生效。\n>\n> **Node/TS 轨不加载 `java-constraints` / `api-e2e-test` skill**：这两个 skill 是 Java/Spring 专属。Node/TS 轨的约束体系（编码规范 + 架构约束 + E2E 规范）全部内联在本文件 §五。\n",
|
|
487
|
-
"category": "process",
|
|
488
|
-
"version": "2.0.4",
|
|
489
|
-
"references": [],
|
|
490
|
-
"scope": "global"
|
|
491
|
-
},
|
|
492
|
-
{
|
|
493
|
-
"name": "config-ui",
|
|
494
|
-
"description": "",
|
|
495
|
-
"content": "# UI 前端轨道配置 (config-ui)\n\n> 到达各 DAG 节点时，主 Agent 按本表加载对应 Agent + Skills。本文件为运行时参考，不替代各 track-*.md 的 HARD GATE 约束。主会话委托 subagent 时，从项目 AGENTS.md 读栈信息（文件约定/栈特定约束/配置管理）拼接注入。\n\n---\n\n## 一、Per-Node Agent 映射表（siming 12-agent 体系，skill 固化绑定）\n\n> 到达各 DAG 节点时按本表指名委派。agent 的 boundSkills 已固化，主会话无需在 prompt 中声明 skill 清单。\n\n| 节点 | 角色 | Agent | 验证方式 |\n|------|------|-------|---------|\n| UI 组件开发 | Implementer | 主会话（UI 编码一律主会话自做，不委派） | code-reviewer 审组件结构与设计-实现一致性 |\n| UI 组件开发 | Verifier | code-reviewer | 独立上下文，零偏差审核 |\n| UI 视觉验证 | Vision Verifier | visual-reviewer | 截图 5 维度审核（布局/样式/状态/对比/一致性） |\n| UI 视觉验证 | Fixer | 主会话 | 视觉缺陷修复（修复后回归审核） |\n| 验收归档 | Executor | test-executor | 全量回归执行 |\n| 验收归档 | Reviewer | 主会话 | 验收确认：事实对照（引用审查结论，不重审） |\n| 验收归档 | Archiver | flow-executor | siming 归档：节点记录 + advance + 项目 git 杂活 |\n\n> **UI 轨差异**：编码一律主会话自做；视觉审核由 visual-reviewer 多模态完成；单测/E2E 节点 UI 轨跳过。\n>\n> **Worker/Verifier 分离（HARD GATE）**：Worker 和 Verifier 必须是不同 session。Verifier 不继承 Worker 上下文，只读审核不改代码。\n## 二、5 层验证链触发点\n\n| 验证层 | 名称 | 触发时机 | 执行方式 |\n|--------|------|---------|---------|\n| 语法验证 | 静态分析 + 类型检查 | UI 组件开发 PostToolUse hooks | 静态分析 + 类型检查（工具/命令见项目 AGENTS.md COMMANDS） |\n| 语义验证 | Verifier(code-reviewer) | UI 组件开发完成后 | `ui-implementation` 3-Pass 协议 + 7 状态模型 + 10 反模式；`code-reviewer` 独立 session 审核 |\n| 集成验证 | 构建 + 启动 | 验收归档开始 | 构建（退出码 0）+ 启动验证（命令见项目 AGENTS.md COMMANDS） |\n| 回归验证 | Playwright E2E 全量 | 验收归档完成 | Playwright E2E 全量 → 7 状态模型全覆盖 → CRUD 全部可用 |\n| 视觉验证 | 截图对照 / 视觉检查 | UI 视觉验证 + 验收归档 | `ui-verify` HARD GATE：Playwright MCP → 视觉对照 → 响应式 → 交互路径；`visual-reviewer` 多模态审核 |\n\n> 逐层推进，前一层失败不进入下一层。\n\n---\n\n## 三、文件约定\n\n> **文件约定（目录结构、组件/页面/布局/类型/样式/API/状态/Hooks/测试的命名与存放路径）是项目特定信息，由项目 AGENTS.md「文件约定」承载（接入项目时 AI 探测填）。**\n> 主会话委托 UI 组件开发 subagent 时，从项目 AGENTS.md「文件约定」拼接注入。\n\n\n## 四、构建命令\n\n> **CLI 日志落盘（HARD GATE）**：构建/类型检查/E2E 命令必须按 项目声明的命令日志落盘纪律（若有） 落盘。\n> 开发服务器为长驻进程，不落盘。\n\n### 命令来源\n\n> 具体 build/lint/dev/test 命令是项目特定信息，**见项目 AGENTS.md「COMMANDS」**（接入项目时 AI 探测填，含类型检查/lint/build/dev/playwright E2E 全量/单文件等变体）。本节只描述落盘纪律。\n\n### 命令模板（落盘纪律，命令值取自项目 AGENTS.md COMMANDS）\n\n```bash\n# 类型检查（语法验证）\n# 按 项目声明的命令日志落盘纪律（若有） 落盘\n{构建命令-类型检查}\n\n# 代码规范（语法验证）\n# 按 项目声明的命令日志落盘纪律（若有） 落盘\n{构建命令-lint}\n\n# 构建验证（集成验证）\n# 按 项目声明的命令日志落盘纪律（若有） 落盘\n{构建命令-build}\n\n# 开发服务器启动（集成验证，长驻进程，不落盘）\n{启动命令-dev}\n\n# Playwright E2E（回归验证 / UI 视觉验证）\n# 按 项目声明的命令日志落盘纪律（若有） 落盘\n{构建命令-playwright全量}\n\n# Playwright E2E 按文件\n# 按 项目声明的命令日志落盘纪律（若有） 落盘\n{构建命令-playwright全量} {文件路径}\n```\n\n---\n\n## 五、UI 约束体系（4 层）\n\n| 约束层 | 名称 | 范围 | 注入节点 | 核心规则 |\n|--------|------|------|---------|---------|\n| Layer A | 设计哲学 | 5 Pillars 前端哲学 | 需求录入/PRD 设计/技术方案 | `frontend-philosophy` 5 Pillars（Componentization / State Management / Accessibility / Performance / Consistency） |\n| Layer B | 设计一致性 | 8 CRITICAL Token | 技术方案, UI 组件开发, 验收归档 | `frontend-consistency` 8 CRITICAL（Design Token 对照 / 组件库统一 / 路由规范 / 状态管理一致性） |\n| Layer C | 实现约束 | 3-Pass 协议 + 7 状态模型 + 10 反模式 | UI 组件开发 | `ui-implementation` 编码规范（见下方速查） |\n| Layer D | 验证 HARD GATE | Playwright MCP 视觉验收 + 5 维度审核 | UI 视觉验证, 验收归档 | `ui-verify` 视觉验收标准（见下方速查） |\n\n### Layer C — 3-Pass 协议 + 7 状态模型速查\n\n#### 3-Pass 开发协议（每个组件）\n\n| Pass | 阶段 | 产出 |\n|------|------|------|\n| Pass 1 — 骨架 | 组件结构 + Props 接口 + 状态声明 | 可编译的空壳组件 |\n| Pass 2 — 逻辑 | 事件处理 + 数据流 + 副作用 | 功能完整的组件 |\n| Pass 3 — 细化 | 样式 + 动画 + 边界处理 + 可访问性 | 生产就绪组件 |\n\n#### 7 状态模型（每个数据组件必须覆盖）\n\n| 状态 | 说明 | 强制要求 |\n|------|------|---------|\n| loading | 数据加载中 | Skeleton（非 spinner），结构匹配内容布局 |\n| empty | 数据为空 | 描述文案 + 引导 CTA（非空白页面） |\n| error | 加载失败 | 错误信息 + 重试按钮 |\n| populated | 正常数据 | 数据正确渲染，无截断 |\n| submitting | 提交中 | 按钮 `disabled`，禁止重复提交 |\n| submitted | 提交成功 | Toast 反馈，列表刷新 |\n| validation-error | 校验失败 | 错误提示在对应字段下方，非全局弹窗 |\n\n#### 10 反模式\n\n| 编号 | 反模式 | 纠正方案 |\n|------|--------|---------|\n| AP1 | 自行实现 Dialog/AlertDialog/Table | 使用项目组件库（见项目 AGENTS.md「栈特定约束」） |\n| AP2 | `any` 类型 | Props 接口必须完整类型标注 |\n| AP3 | 空 catch 块 | 至少 `console.error` + 用户可见错误状态 |\n| AP4 | 全局样式污染 | CSS Modules 或 scoped styles |\n| AP5 | `div` + `onClick` 替代 `<button>` | 使用语义化标签 |\n| AP6 | 硬编码颜色/字体大小 | 使用 Design Token（CSS 变量或 Tailwind theme） |\n| AP7 | `useEffect` 内直接 fetch | 使用数据获取库（TanStack Query / SWR） |\n| AP8 | 无边界处理的长文本 | 截断 + Tooltip |\n| AP9 | 表单提交无 disabled | `disabled={isSubmitting}` |\n| AP10 | 删除无二次确认 | AlertDialog 确认 |\n\n### Layer D — UI 视觉验证 视觉验收 5 维度（HARD GATE）\n\n| 维度 | 审核要点 | 执行者 |\n|------|---------|--------|\n| 1. 状态完整性 | 4 种状态（loading/empty/error/populated）截图完整 + 视觉正确 | `visual-reviewer` |\n| 2. 可访问性 | 语义化 HTML / `aria-label` / 键盘导航 / `prefers-reduced-motion` | `visual-reviewer` |\n| 3. 组件标准 | 使用组件库，`disabled` 防重复提交，Props 类型完整 | `visual-reviewer` |\n| 4. 边界场景 | 空状态 CTA / 长文本截断 / 表单校验 / 并发防护 | `visual-reviewer` |\n| 5. 交互质量 | AlertDialog 确认 / Toast 反馈 / 响应式断点（mobile/tablet/desktop） | `visual-reviewer` |\n\n> 5 维度全部 PASS（0 CRITICAL FAIL）才能通过 UI 视觉验证。最多 3 轮修复循环。\n\n---\n\n## 六、响应式断点约定\n\n| 断点 | 宽度 | 对应设备 |\n|------|------|---------|\n| mobile | < 640px | 手机竖屏 |\n| tablet | 640px - 1024px | 平板 / 手机横屏 |\n| desktop | > 1024px | 桌面显示器 |\n\n> 每个页面/UI 视觉验证 截图必须覆盖 3 个断点。\n\n---\n\n## 七、Skill 加载优先级\n\n| 优先级 | Skill | 加载时机 |\n|--------|-------|---------|\n| 1 | `code-philosophy` | 全局（所有轨道、所有节点） |\n| 2 | `frontend-philosophy` | 需求录入/PRD 设计/技术方案（设计阶段） |\n| 3 | `frontend-consistency` | 技术方案, UI 组件开发, 验收归档 |\n| 4 | `ui-constraints` | UI 组件开发, UI 视觉验证, 验收归档（按层级注入） |\n| 5 | 节点专属 skill | 按本表「固化绑定/注入 skill」列生效（agent 固化绑定自动加载；节点 skills 随 context 注入） |\n\n> UI 编码由主会话完成（加载 UI 域 skill 即具备视觉规范能力）。`visual-reviewer` subagent 用于 UI 视觉验证 的截图多模态审核。\n",
|
|
496
|
-
"category": "process",
|
|
497
|
-
"version": "2.0.5",
|
|
498
|
-
"references": [],
|
|
499
|
-
"scope": "global"
|
|
500
|
-
},
|
|
501
|
-
{
|
|
502
|
-
"name": "entry-prd",
|
|
503
|
-
"description": "",
|
|
504
|
-
"content": "\n# PRD 设计\n\n> **节点名**: PRD 设计 | **阶段**: Entry (Fixed) | **轨道**: ALL | **Agent**: 主会话编写，prd-reviewer 审查 | **任务状态**: Entry 阶段\n\n「PRD 设计」将「需求录入」的模糊需求细化为结构化 PRD（Product Requirements Document）。文档独立存储于 `项目文档目录/`，不写入任务记录。\n\n> **编写 vs 审查边界（HARD GATE）**：PRD 编写由主会话加载 `prd-design` 等 skill 直接产出 —— 需求对话上下文已在主会话，不外派只读 subagent 重做。审查由 prd-reviewer 新 session 执行，保持 Worker/Verifier 分离。\n\n> **可跳过**：技术 Bugfix / 纯技术调整 / 用户明确表示不需要 PRD 时，经用户确认后跳过本节点，直接进入技术方案。跳过判定在「需求录入」节点阶段 B 中完成。\n\n## HARD GATE\n\n**核心规则**：\n\n1. **禁止写代码**。此节点只出设计文档，任何 `.java` `.tsx` 的编写或修改均为违规\n2. **禁止 HOW 泄漏**。PRD 描述做什么（功能行为），不描述怎么做（技术实现）。出现类名、API 路径、数据库表结构、文件组织方案即为 FAIL\n3. **禁止跳过审查**。PRD 草案完成后必须经 `code-reviewer` 独立 session 审查，不得自审；审查 skill 遵循「prd-review 交互式审查 ≤3 轮」纪律\n4. **PRD 独立存储**。PRD 文档写入 `项目文档目录/<taskId>-{标题}.md`，任务记录仅记录文档路径引用\n\n**禁止行为**：\n\n- ❌ 将 PRD 内容内联写入任务记录\n- ❌ 在 PRD 中描述技术实现方案\n- ❌ 主会话自审 PRD（必须用 prd-reviewer 独立 session）\n- ❌ PRD 中留下「TBD」占位符\n\n\n**code-reviewer 审查约束块**（PRD 编写由主会话执行，约束见上方 HARD GATE 章节；审查为 code-reviewer 新 session，需注入约束）：\n\n```\n[code-reviewer — PRD 审查（新 session，只读）]\n你是一名产品审查专家。你的任务是评审 PRD 文档的质量和完整性。你与编写者必须是不同 session。\n\nCRITICAL 约束：\n1. 你只有 READ 权限，只读 PRD 文档；不做架构评判、不推荐技术方案\n2. 审查维度（4 维）：\n - 业务价值：需求是否对应明确的业务问题？不做会怎样？\n - 功能完整性：是否覆盖所有用户场景？是否有遗漏的边界条件？\n - 清晰性：验收标准是否可验证？是否有歧义表述？\n - 可行性：在给定轨道技术栈中是否可实现？\n3. 输出格式：每项标注 PASS/FAIL，FAIL 项必须附具体引用（PRD 原文 + 问题说明）\n4. 不评判 PRD 格式美观度、不推荐替代方案、不建议功能增删\n```\n\n## 执行动作\n\n1. **读取上下文**：读取「需求录入」产出的任务记录（`对应阶段/<taskId>-{标题}.md`），确认需求范围、轨道归属、PRD 跳过状态\n\n **架构约束读取**：read `项目架构参考（位置按项目声明，不存在则跳过）`（不存在/为空/仅占位 → 跳过），对齐既有业务架构决策。\n\n2. **结构化需求访谈**：基于任务记录中已明确的 What & Why，通过对话补全需求细节\n - 遵循 `prd-design` skill 的结构化访谈流程\n - 识别信息缺口：用户场景、业务规则、边界条件、非功能性需求\n - 逐维度追问，一次一个问题，不堆砌提问\n - ⚠️ 信息缺口未补全 → 不得进入文档编写\n\n3. **编写 PRD 文档**：主会话加载对应 skill 直接产出结构化文档（不外派 subagent）\n - Backend 轨道 → 加载 `prd-design`，产出 PRD（7 章骨架），存为 `项目文档目录/<taskId>-{标题}.md`\n - UI 轨道 → 加载 `prd-design` + `frontend-philosophy`，产出 PRD with UI-specific sections，存为 `项目文档目录/<taskId>-{标题}.md`\n - 混合轨道 → 主轨道格式为准，补充轨道在子章节中描述\n\n4. **质量自检**：编写完成后执行 skill 内置的 quality-checklist 自检（完整性 / 一致性 / 清晰度 / 简洁性 / 逻辑合理性 / 内容公理符合度 6 维度）\n\n5. **记录 PRD 路径**：将文档路径写入任务记录「元数据 - PRD 链接」字段\n\n6. **PRD 正式评审**：委派 `code-reviewer` subagent（新 session），加载对应审查 skill\n - **交互式 review（≤3 轮）**：code-reviewer 输出问题清单 → 主 agent 逐条决定修复/不修复（记录理由）→ 重新提交 → 直到通过\n - Backend 轨道审查重点：功能完整性、业务规则无矛盾、验收标准可验证\n - UI 轨道审查重点：组件交互状态覆盖、设计系统一致性、可访问性需求\n - 3 轮未通过 → ⏸ 暂停，输出核心分歧点请用户决策\n\n## 质量技能表\n\n| 执行者 | skill（Backend 轨） | skill（UI 轨） | 职责 |\n|---------------|--------------------|--------------------|------|\n| **主会话** | `prd-design` | `prd-design`, `frontend-philosophy` | PRD 编写（直接产出文档） |\n| `code-reviewer`（新 session） | `prd-review` | `prd-review` | 4 维正式评审 |\n\n## 完成判定\n\n**流程步骤映射**（6 项）：\n- [ ] 「需求录入」任务记录已读取，需求范围与轨道归属已确认\n- [ ] 结构化需求访谈已完成：用户场景/业务规则/边界条件/非功能性需求已补全\n- [ ] PRD 文档已产出：`项目文档目录/<taskId>-{标题}.md` 存在\n- [ ] 质量自检已执行（对应 skill 内置 quality-checklist 全部通过）\n- [ ] 任务记录「元数据 - PRD 链接」已指向正确路径\n- [ ] PRD 正式评审已执行并通过：code-reviewer 审查全部 PASS，或 FAIL 项已记录修复/不修复理由\n\n**独立性约束**（防跳节点）：\n- [ ] `项目文档目录/{模块}/<taskId>-{标题}.md` 已独立产出\n- [ ] PRD 独立产出，「需求录入」任务记录仅含 What&Why 概要，不替代 PRD 的详细需求分析\n\n## 不得继续的情况\n\n- 信息缺口未补全 → ⏸ 暂停，列出确认清单\n- 正式评审连续 3 轮不通过 → ⏸ 暂停，输出核心分歧点请用户决策\n- 用户要求跳过 PRD 但需求有业务复杂度 → ⏸ 暂停，说明风险后尊重用户决定\n\n## ⏸ 暂停（PRD 设计 → 技术方案 为暂停点）\n\n本节点完成后暂停。向用户呈现：\n1. PRD 文档要点摘要（核心功能清单 + 关键验收标准）\n2. 正式评审结果摘要（PASS/FAIL 统计 + 关键建议）\n3. **若为混合任务（多轨道）：推荐拆分建议**（见下方「混合任务拆分建议」）\n\n等待用户确认后执行后续动作。\n\n### 混合任务拆分建议（仅多轨道任务触发）\n\n当「需求录入」识别的任务涉及多个轨道时（如 Backend + UI），在「PRD 设计」暂停点向用户推荐拆分：\n\n**为什么推荐拆分**：\n- 单轨道任务的开发、测试、验证链路更清晰，质量门控更严格\n- 避免混合任务中跨轨道等待、Phase 流转复杂度\n- 每个 DAG 实例跑完整生命周期，降低回归风险\n\n**拆分策略**：按轨道类型拆分，每个拆分后的任务独立走完整的 DAG 流程：\n\n| 原任务轨道 | 拆分方案 | 拆分后任务 |\n|-----------|---------|-----------|\n| Backend + UI | 按后端/UI 拆 | <taskId>-A（Backend 轨道）+ <taskId>-B（UI 轨道） |\n\n**拆分操作**：\n1. ⏸ 向用户呈现拆分建议：列出拆分方案 + 每个拆分任务的 PRD 要点\n2. 用户选择：\n - **接受拆分** → 当前任务标记「已拆分」，创建拆分后的子任务记录，每个子任务走独立 DAG\n - **保持混合** → 继续走混合任务 DAG 路径（技术方案 → 多轨道并行）\n3. 拆分后当前任务的处理：\n - 任务记录「元数据」区追加 `状态: 已拆分 → <taskId>-A, <taskId>-B, ...`\n - 拆分后的子任务各自独立进入「PRD 设计」（如需单独的 PRD）或直接进入技术方案（共享当前 PRD）\n\n## ▶ 确认后动作（用户确认后执行）\n\n**先归档本节点（无论是否拆分）**：\n\n```bash\nsiming_task { action: \"record-set\", taskId: \"<任务id>\", node: \"PRD\", summary: \"<PRD 一句话结论>\" }\nsiming_task { action: \"record-artifact-add\", taskId: \"<任务id>\", node: \"PRD\", artifactType: \"prd\", file: \"<项目文档目录>/<taskId>-<标题>.md\" }\nsiming_task { action: \"record-review-set\", taskId: \"<任务id>\", node: \"PRD\", verdict: \"pass\", rounds: <N>, critical: 0 }\nsiming_task { action: \"record-confirm\", taskId: \"<任务id>\", node: \"PRD\", quote: \"<用户确认原文，逐字>\" }\nsiming_task { action: \"advance\", taskId: \"<任务id>\", summary: \"PRD 完成\" } # 触发 PRD→分支对齐(ALIGN) 人工审批暂停点\nsiming_task { action: \"approve\", taskId: \"<任务id>\", decision: \"approved\", comment: \"<备注>\" } # 用户确认后\n```\n\n1. **若用户选择拆分**：为每个子任务经 task-create 流程新建独立 siming 任务（各自独立走完整 DAG）；当前任务 record decision 记录拆分结论（子任务清单），流程终止\n2. **若用户选择保持混合**（或单轨道任务）：approve 后进入技术方案节点（context 取下一节点资料包）\n\n",
|
|
505
|
-
"category": "process",
|
|
506
|
-
"version": "2.0.5",
|
|
507
|
-
"references": [],
|
|
508
|
-
"scope": "global"
|
|
509
|
-
},
|
|
510
|
-
{
|
|
511
|
-
"name": "entry-tech",
|
|
512
|
-
"description": "",
|
|
513
|
-
"content": "\n# 技术方案\n\n> **节点名**: 技术方案 | **阶段**: Entry（阶段内不流转） | **轨道**: ALL | **Agent**: 主会话设计；PRD 对齐审查（alignment-reviewer）；架构评审（arch-reviewer）\n\n「技术方案」将 PRD 设计的 PRD 转化为可执行的技术方案。方案文档独立存储于项目文档目录（按项目 AGENTS.md 声明），路径经 artifact 登记。设计通过 PRD 对齐审查 + 架构评审双审后，创建 feature 分支并进入 Track Phase。\n\n> **编写 vs 审查边界（HARD GATE）**：技术方案设计由主会话加载 `arch-review` / 轨道 constraints skill 直接产出 —— PRD 上下文已在主会话，不外派只读 subagent 重做。PRD 对齐审查（alignment-reviewer） 新 session）+ 架构评审（arch-reviewer） 新 session，加载 `arch-review` skill）保持 Worker/Verifier 分离。\n\n> **Bugfix 快速通道**：若「需求录入」判定跳过 PRD 设计（用户已确认），技术方案直接以任务 doc 的需求概述（what/why/验收标准）作为输入，不执行 PRD 对齐审查（无 PRD 可对齐），仅执行架构评审。\n\n## HARD GATE\n\n**核心规则**：\n\n1. **禁止写编码阶段的实现代码**。方案是架构师设计文档——DDL、API schema、时序图、状态机、ER 图、决策表等**设计产物必须写**；禁止的是**编码阶段才做的工作**：完整方法体实现、完整测试用例代码、完整配置文件全文\n2. **先对齐后评审**。PRD 对齐审查必须在架构评审之前执行，顺序不可颠倒：设计 → PRD 对齐 → 修复偏差 → 架构评审\n3. **方案独立存储**。技术方案写入 `<taskId>-<标题>.md`（项目文档目录，按项目声明），artifact 登记路径\n4. **Worker/Verifier 分离**。设计者（主会话）和架构评审（arch-reviewer）必须是不同 session；arch-reviewer 评审 session 不继承主会话上下文，加载 `arch-review` skill 作为评审方法论\n5. **审查纪律**。交互式 review ≤3 轮：subagent 输出问题清单 → 主 agent 逐条决定修复/不修复（记录理由）→ 重新提交 → 直到通过；3 轮未通过 → ⏸ 暂停请用户决策\n6. **分支纪律**。技术方案完成后才创建 feature 分支，禁止在 Entry Phase 中提前切分支\n\n**设计产物 vs 编码产物 边界对照**（HARD GATE「中文输出」 的具体展开）：\n\n| 维度 | ✅ 设计产物（必须写） | ❌ 编码产物（禁止） |\n| -------- | ----------------------------------------------------------- | ---------------------------------------- |\n| 数据模型 | 完整 DDL / 字段表 / ER 图（表名、字段、类型、约束、索引、关系） | ORM `@Document`/`@Field` 注解代码 + Repository 方法体实现 |\n| 接口契约 | API schema（OpenAPI / 字段表 / JSON 示例）、状态码、错误体 | Controller + Service + DTO 完整方法体 |\n| 行为流程 | 时序图、状态机、自然语言主干路径 | 多行方法体实现、伪代码逐步算法 |\n| 决策表达 | 决策表（选项/结论/取舍）、mermaid 图（节点数按系统复杂度而定） | 用代码示例演示\"选项这样实现\" |\n| 验证 | 测试矩阵、用例描述（\"测什么 + 为什么测\"） | `@Test` 完整测试代码 |\n| 配置 | 关键配置项 + 理由 | 完整配置文件全文（application.yml 等） |\n\n> **判断准则**：「打开 IDE 才做的事 = 越界」。架构师设计文档应有的产出 = 合格。\n\n**禁止行为**：\n\n- ❌ 将方案内容内联写入任务记录（artifact 路径引用即可）\n- ❌ 跳过 PRD 对齐审查（除非已跳过 PRD 设计）\n- ❌ 设计者自审（主会话不得自审，评审者须为 arch-reviewer 新 session）\n- ❌ 方案中写完整方法体 / 完整测试用例代码 / 完整配置文件全文\n- ❌ 功能清单与详细设计正文不对应\n- ❌ 在 main 或 dev 分支上直接开发\n\n**审查 subagent 约束块**（注入 arch-reviewer 新 session）：\n\n```\n[arch-reviewer — 技术方案架构评审（新 session，只读，`arch-review` skill 固化绑定）]\n你是一名技术方案审查专家。你的任务是审查技术方案的质量、完整性和与 PRD 的对齐程度。你与设计者必须是不同 session。\n\nCRITICAL 约束：\n1. 你只有 READ 权限，只读文档，不做代码修改\n2. 审查分两步，顺序不可颠倒：\n\n 第一步 — PRD 对齐审查（仅当存在 PRD 时执行）：\n - 功能覆盖：PRD 中声明的每个功能需求，方案中是否有对应的详细设计？\n - 逻辑矛盾：方案设计是否与 PRD 描述的行为、规则、约束矛盾？\n - 验收标准对齐：方案的验收标准是否覆盖了 PRD 中的全部验收标准？\n - 输出：[功能覆盖] PASS/FAIL — 具体说明 / [逻辑矛盾] PASS/FAIL — 具体说明 / [验收对齐] PASS/FAIL — 具体说明\n\n 第二步 — 架构审查（采用 arch-review 双阶段：维度覆盖 + 自由发现）：\n\n 层 A 必查约束（除十大维度外，本节点追加）：\n - Backend 轨道：config-node.md §五 Layer B 架构 10 CRITICAL 全部通过\n - UI 轨道：ui-constraints Layer B 设计一致性 8 CRITICAL 全部通过\n\n 层 B 自由发现不可省略（机制定义见 arch-review skill）。\n\n3. 输出格式：每项标注 PASS/FAIL，FAIL 项必须附具体引用（方案原文 + 问题说明 + 建议方向）\n4. 不评判编码风格、命名偏好、非架构层面的细节\n5. 不建议替代方案细节，只指出问题方向\n```\n\n## 执行动作\n\n1. **读取输入**：`siming_task { action: \"context\", taskId: \"<任务id>\" }` 取需求 doc + PRD artifact（若存在），确认需求范围与轨道归属\n\n **架构约束读取**：按轨道 read 对应架构信息文档（不存在/为空/仅占位 → 跳过），对齐既有架构决策：\n - Backend → `项目架构参考（位置按项目声明，不存在则跳过）`\n - UI → `项目架构参考（位置按项目声明，不存在则跳过）`\n - 混合 → 两者都读\n\n2. **加载设计 skill，执行技术方案设计**：主会话加载对应 skill 直接产出方案文档（不外派 subagent）\n\n > ⚠️ **再次提醒**：方案是架构师设计文档，不是 IDE 编码产物——DDL、API schema、决策表、时序图等是必须的设计产出。**禁止写大段编码阶段的实现代码**（完整方法体、完整测试用例、完整配置文件全文），违反 = 整段回炉，不是修补。\n\n - AI 自主决策优先，仅在真正无法决策时暂停问用户\n - Backend 轨道 → 加载 `arch-review` + `config-node.md` §五（Node/TS 约束体系）\n - UI 轨道 → 加载 `arch-review` + `frontend-consistency` + `ui-constraints`\n\n > **注意**：`arch-review` 是**架构评审**方法论（Finding 格式、多轮交互协议），不是\"如何写技术方案\"的指南。\n\n **方案文档结构要求**（必须包含「总览」和「详细设计」两大章节）：\n - 总览：架构全景图（mermaid）、核心流程（主干路径，文字描述）、关键决策表、功能清单\n - 详细设计：覆盖功能清单中全部功能点的**实现思路**（设计级抽象，按上方对照表）\n - 每项关键决策**必须**写清：选项列表、结论、取舍理由（用决策表，不用代码示例）\n - 产出路径：`项目文档目录/<taskId>-{标题}.md`（{模块} 取 2~4 字中文模块名）\n\n **按轨道分支产出对应深度的方案**：\n\n 【Backend 轨道方案】必须覆盖：服务/模块划分、API 契约（schema + 状态码 + 错误体）、数据流（Controller→Service→Repository→DB）、DDD 设计（如有领域复杂度）、错误处理策略、安全设计\n\n 【UI 轨道方案】必须覆盖：组件树与路由映射、状态管理策略、数据获取方案（API 抽象 + 缓存 + 错误处理）、性能优化策略、设计 Token 对照（与 Design System 一致性）\n\n3. **PRD 对齐审查（alignment-reviewer） 子 agent（新 session），传入 PRD + 技术方案文档路径，prompt 模板参考 `@references/prd-alignment-review-prompt.md`。FAIL 项 → 修复后重新对齐（最多 3 轮）；全部 PASS 后进入步骤 4\n\n4. **记录方案路径**：将技术方案文档路径写入任务记录「元数据 - 技术方案」字段\n\n5. **架构评审**：委派 `arch-reviewer` subagent（新 session，`arch-review` skill 固化绑定 + 对应轨道 constraints 注入）。交互式 review（≤3 轮）：arch-reviewer 输出问题清单 → 主 agent 逐条决定修复/不修复（记录理由）→ 重新提交 → 直到通过。3 轮未通过 → ⏸ 暂停请用户决策\n\n## 质量技能表\n\n| 执行者 | skill（Backend 轨） | skill（UI 轨） | 职责 |\n|---------------|--------------------|--------------------|------|\n| **主会话** | `arch-review` | `arch-review`, `frontend-consistency`, `ui-constraints` | 技术方案设计（直接产出文档） |\n| alignment-reviewer（新 session） | `prd-alignment-review-prompt`（固化绑定） | 同左 | PRD 对齐审查 |\n| arch-reviewer（新 session） | `arch-review`（固化绑定） | `arch-review` + `ui-constraints` | 架构评审 |\n\n> 增量评审（评审通过后设计变更的复审）同样适用本表：只缩小审查范围，不缩减审查标准。每轮审查结论记录「范围（全量/增量）+ PASS/FAIL」交 flow-executor 归档。\n\n## 完成判定\n\n**流程步骤映射**（5 项）：\n- [ ] 任务记录与 PRD 文档已读取，需求范围与轨道归属已确认\n- [ ] 技术方案文档已产出：`项目文档目录/<taskId>-{标题}.md` 存在\n- [ ] PRD 对齐审查已执行并通过（全部 PASS），或已跳过 PRD 设计无需对齐\n- [ ] 任务记录「元数据 - 技术方案」已指向正确路径\n- [ ] 架构评审已执行并通过（对应轨道 constraints CRITICAL 约束审查通过）\n\n**独立性约束**（防跳节点 + 防越界）：\n- [ ] 技术方案独立产出至 `项目文档目录/<taskId>-{标题}.md`\n- [ ] 技术方案**不含测试设计**（测试用例设计由「单测设计」节点负责）\n- [ ] 技术方案**不含编码阶段的实现**（完整方法体 / 完整测试用例代码 / 完整配置文件全文——由编码/UI 轨道节点和「单测设计」节点负责）\n- [ ] 不得用 PRD 设计 PRD 的实现描述替代架构设计\n\n## 不得继续的情况\n\n- 技术方案涉及超出当前认知范围的架构决策 → ⏸ 暂停，列出 tradeoff 分析，请用户确认方向\n- PRD 对齐审查连续 3 轮不通过 → ⏸ 暂停，输出对齐偏差清单\n- 架构评审连续 3 轮不通过 → ⏸ 暂停，输出核心分歧点请用户决策\n- constraints CRITICAL 约束有 violation 且无法在方案层面修复 → ⏸ 暂停，请用户决策是否接受风险\n\n## ⏸ 暂停（技术方案 → Track Phase 为暂停点）\n\n本节点完成后暂停。向用户呈现：\n1. 技术方案摘要：总览 + 关键决策（含取舍理由）\n2. PRD 对齐审查结果（若已执行）\n3. 架构评审结果：PASS/FAIL 统计 + constraints violation 清单（如有）\n4. 激活轨道列表：根据「需求录入」轨道识别结果列出即将执行的 Track Phase 节点\n\n等待用户确认后执行以下动作。\n\n## ▶ 确认后动作（用户确认后执行）\n\n1. **分支登记**：按项目 AGENTS.md 声明的分支模型创建任务分支，然后登记：\n ```bash\n siming_task { action: \"record-decision-add\", taskId: \"<任务id>\", node: \"DESIGN\", topic: \"branch\", decisionText: \"<分支名>\" }\n ```\n2. **节点归档与推进**：\n ```bash\n siming_task { action: \"record-set\", taskId: \"<任务id>\", node: \"DESIGN\", summary: \"<方案一句话结论>\" }\n siming_task { action: \"record-artifact-add\", taskId: \"<任务id>\", node: \"DESIGN\", artifactType: \"tech\", file: \"<项目文档目录>/<taskId>-<标题>.md\" }\n siming_task { action: \"record-review-set\", taskId: \"<任务id>\", node: \"DESIGN\", verdict: \"pass\", rounds: <N>, critical: 0 }\n siming_task { action: \"record-confirm\", taskId: \"<任务id>\", node: \"DESIGN\", quote: \"<用户确认原文，逐字>\" }\n siming_task { action: \"advance\", taskId: \"<任务id>\", summary: \"技术方案完成\" } # 触发 DESIGN→Track 人工审批暂停点\n siming_task { action: \"approve\", taskId: \"<任务id>\", decision: \"approved\", comment: \"<备注>\" } # 用户确认后，进入 Track 节点\n ```\n## 附录：subagent delegation 要点\n\n> 完整委派协议见 workflow-discipline skill「委派七段式骨架」。本附录仅列技术方案节点高频用法。\n\n主会话投喂的背景信息（目标文件路径、参考实现、依赖类、范式摘要）是 Worker 的起点，不影响 Verifier（arch-reviewer）的独立审查上下文。**编码类工作一律主会话自做（项目 AGENTS 编排文件「编码 delegation 决策」），本附录的 Worker 投喂原则仅适用于仍可委派的非编码角色（探索/检索/调查类）**。prompt 七段式骨架（IDENTITY 必填）：`IDENTITY → TASK → EXPECTED → CONTEXT → CONSTRAINTS（节点 HARD GATE 原文）→ MUST DO / MUST NOT DO → VERIFICATION`，权威定义与流程层 HARD GATE 见 workflow-discipline skill（§1 Worker/Verifier 分离 / §6 委派七段式）。\n\n",
|
|
514
|
-
"category": "process",
|
|
515
|
-
"version": "2.0.9",
|
|
516
|
-
"references": [],
|
|
517
|
-
"scope": "global"
|
|
518
|
-
},
|
|
519
|
-
{
|
|
520
|
-
"name": "exit",
|
|
521
|
-
"description": "",
|
|
522
|
-
"content": "\n# 验收归档\n\n> 固定出口节点（合并原 E01 集成回归 + E02 最终验收 + E03 归档）。所有轨道在此汇聚，执行全量回归 + 快速验收确认 + 归档。\n>\n> **设计理念**：质量保障在技术方案/后端编码/单测设计/E2E 开发 各节点对应 reviewer 审查已完成（方案=arch-reviewer / 代码=code-reviewer / 测试设计=test-reviewer），验收归档不重复审查。验收归档只做：①跑全量测试验证 ②事实对照确认 ③归档。\n>\n> **Agent 分工**：test-executor 执行「全量回归」CLI 命令 / 主会话调度 + Diagnose 修复 + 「验收确认」/ flow-executor 执行「归档」（验收归档）。\n>\n> **状态流转**：由任务状态机 advance 自动承载（无目录/看板操作）。\n\n## HARD GATE\n\n| # | 条件 | 未满足时 |\n|---|------|---------|\n| H1 | 所有活跃轨道 Track + Test 阶段完成 | 打回对应节点 |\n| H2 | 单测 100% pass（形式化判定见下方注；按项目 AGENTS.md「测试范式」声明的框架与 PASS 判定标准执行） | 打回单测开发 |\n| H3 | E2E 100% pass（Backend 轨道；形式化判定见下方注） | 打回 E2E 开发 |\n| H4 | smoke test 通过（Backend API 200；UI 页面可访问） | 打回对应轨道 |\n| H5 | **涉及后端 API 的 UI 任务**：前后端联调冒烟 100% pass（真实后端 + 真实 HTTP 请求，非 mock） | 打回 UI 组件开发，补联调测试 |\n| H6 | **0 Critical** 代码审查意见未解决（引用各节点 code-reviewer 审查结果，不重审） | 打回对应编码节点 |\n| H7 | 当前分支为 `feature/<taskId>` | 切换到正确分支 |\n| H8 | 已知问题逐条判定：破坏功能完整性的问题均已修复（判定标准 = 功能完整性，非\"是否本期引入\"） | 打回修复对应问题 |\n\n> H1-H8 任一未满足，立即终止验收归档，标注缺失项。H6 不要求重新审查，只确认各节点 code-reviewer 审查的 Critical 已清零。\n>\n> **H8 判定标准（HARD GATE）**：验收标准 = **功能完整性**，不是问题是否本期引入。已知问题逐条判定「是否破坏功能完整性」（行为与文档/注册表承诺不一致、静默忽略用户输入、功能缺失/错误、手册与实现背离等）：破坏 → 验收前必须修复，\"预存问题/非本期引入/Phase-2 缺口/待用户拍板\"均不构成豁免理由，仅用户**显式**接受风险（原文记录到任务 doc/记录）可不修放行；修复工作量大 → ⏸ 上升用户拍板拆分，禁止静默放行。\"预存\"只豁免回归归因（归哪个任务修），不豁免验收阻塞。\n>\n> **H2/H3 形式化判定（零-skip 原则，HARD GATE）**：PASS = fail=0 且 skip=0 且项目测试完整性检查通过。**skip>0 不是 PASS**——每条 skip 必须有用户显式授权记录在本任务任务 doc/记录中，且验收摘要逐条列出 skip 清单；无授权的新增 skip = FAIL，打回对应测试节点。完整性检查覆盖本分支新增 skip 标记（test.skip/test.fixme/describe.skip/xdescribe/xit/*.only）与被删除的测试文件（检查手段按项目声明）。\n>\n> **H2 守卫**：若项目 AGENTS.md「测试范式」节缺失或不完整（未声明框架/命令/PASS标准/覆盖率，或\"无单测\"未声明替代验证）→ H2 不可验证，**⏸ 暂停并提示用户先补全「测试范式」节再继续**。禁止在「测试范式」缺失时跳过 H2 或默认放行。\n\n## 约束块\n\n```\n[test-executor] 项目级配置，仅 bash/read/grep/glob — 执行 CLI 测试命令\n[主会话] 调度 test-executor + Diagnose 修复 + 验收事实对照\n[flow-executor] 项目级配置，read/edit/write/glob/grep — 节点归档（验收归档）\nconstraints:\n - test-executor 和主会话工具分离：test-executor 跑命令，主会话调 MCP（Playwright）\n - 任何 NEW regression → 打回对应步骤（走 systematic-debugging）\n - 不变量逐条验证不可跳过\n - 0 Critical 引用历史审查结果，验收归档不重新 code-reviewer 审查\n - 归档使用 --no-ff merge，禁止 squash/rebase\n```\n\n---\n\n## 全量回归（委托 test-executor）\n\n> **CLI 日志落盘（HARD GATE）**：所有测试命令必须按项目声明的日志落盘纪律落盘。\n\n### 执行模式（自主优先 + test-executor 委托）\n\n```\n纯 CLI 测试（单测/E2E/后端启动，命令按项目声明）→ 委托 test-executor\nMCP 工具（Playwright MCP for UI） → 主会话自己执行（test-executor 无 MCP 权限）\n主会话职责：调度 test-executor → 接收结果 → Diagnose → 修代码 → 委托 test-executor 重跑\n```\n\n### 测试完整性静态检查（HARD GATE，主会话执行）\n\n**全量回归门控判定前必须执行**（test-executor 返回结果后、进入 Diagnose/验收确认前）：\n\n> 命令清单按项目 AGENTS.md COMMANDS（未声明 → 向用户确认）。\n\n- exit 0（CLEAN）→ 继续验收确认\n- exit 1（命中）→ FAIL：新增 skip 标记/被删测试文件必须修复还原，或确认任务 doc/记录中有用户逐条授权记录并在验收摘要列明；否则打回对应测试节点\n\n### test-executor 委托模板（主会话 → test-executor）\n\n> `dev-workflow-tester` skill 已固化绑定于 test-executor agent，主会话无需在 prompt 中声明 skill 清单。Final Output Contract / 三阶段工作流 / 自主环境准备等约束已在 skill 内。\n\n委派 test-executor subagent（验收归档·全量回归），prompt 模板：\n\n```text\n## TASK\n按轨道跑下列命令清单，返回结构化结果（按 dev-workflow-tester skill「Final Output Contract」 输出，不是摘要）。\n\n## CONTEXT\n- 项目根: 项目根目录/\n- session code: {session-code}\n- 涉及轨道: {backend | ui | 混合}\n\n## 命令清单（按轨道，从下方\"命令清单\"段复制对应轨道）\n{轨道命令清单}\n\n## MUST DO\n- 命令逐条执行、log 落盘、附 grep 结果\n- 阶段A 自主环境准备（skill 「自主环境准备」）\n\n## MUST NOT DO\n- 不修改任何文件、不解释原因只报事实（skill 「责任边界」 已规定）\n```\n\n### 命令清单（按轨道）\n\n**Backend**（委托 test-executor，命令值取自项目 AGENTS.md COMMANDS）：\n```bash\n# 集成验证 smoke（冒烟测试）\n# 按 项目声明的命令日志落盘纪律 落盘\n{构建命令-冒烟}\n# 回归验证·后端单测全量\n# 按 项目声明的命令日志落盘纪律 落盘\n{构建命令-单测全量}\n# 回归验证·E2E 全量（Playwright runner，打真实 API，确保后端已启动 HARD GATE「设计协调」）\n# 按 项目声明的命令日志落盘纪律 落盘\n# E2E 命令按项目 AGENTS.md COMMANDS\n```\n\n**UI**（主会话执行，Playwright MCP）：\n```\nPlaywright MCP 全量 CRUD 验证 + 边界状态（loading/empty/error/edge）+ 截图 diff\n```\n\n### Diagnose 循环（test-executor 返回非 100% PASS 时）\n\n```\nAPPLY（委托 test-executor 跑）→ DIAGNOSE（主会话 systematic-debugging 根因调查）\n ├── 代码缺陷 → 改实现，不改测试\n ├── 契约漂移 → 对照 PRD/技术方案修对应端\n ├── 环境故障 → 自主排查依赖（数据库/中间件）\n └── 测试本身错 → 改测试（仅当确实写错；\"改测试\"仅指修正错误断言/选择器/fixture，**不含** test.skip/放宽断言等降级——skip ≠ pass）\n→ ITERATE（委托 test-executor 重跑）→ 直到 PASS 或触发暂停条件（systematic-debugging 3 轮不收敛）\n```\n\n> **禁止上升理由**：测试 FAIL、后端未启动、字段对不上、MCP 报错——这些都是 Diagnose 标准输入，不是上升理由（自主优先原则）。\n\n---\n\n## 不变量验证 + 回归 Diff\n\n### 不变量清单（轨道维度）\n\n| 轨道 | 不变量数 | 分类 | 详细清单 |\n|------|---------|------|---------|\n| Backend | 11 | 性能(3) + API契约(4) + 数据(2) + 可观测(2) | 本文件下方 |\n| UI | 9 | 视觉(3) + 交互(3) + 性能(3) | `ui-verify` skill |\n\n**Backend 11 不变量**（栈中性验收维度；具体测量命令/迁移机制/测试库按项目 AGENTS.md「测试范式」与 config-node.md）：\n1. API 响应时间 P95 ≤ baseline × 1.1 | 2. DB 查询耗时 ≤ baseline × 1.1 | 3. 堆内存峰值 ≤ baseline × 1.1\n4. 端点签名无变化 | 5. 响应 Schema 兼容 | 6. 错误码无退化 | 7. 认证/鉴权门禁无退化\n8. 迁移脚本幂等 | 9. 关键查询结果集行数 = baseline\n10. 关键路径日志覆盖无丢失 | 11. 错误日志级别无降级\n\n### 回归 Diff 处理\n\n```\n对比当前 vs baseline → 6 类标签:\n NEW → 打回对应节点（走 systematic-debugging，禁止只改测试让其通过）\n FIXED → 记录修复\n STABLE_PASS → 无变化\n STABLE_FAIL → 评估 → 用户决策\n MISSING_BASELINE → 建立 baseline\n MISSING_CANDIDATE→ 检查是否误删\n```\n\n> test-executor 在「全量回归」结果中附不变量 PASS/FAIL 统计。主会话审查 Diff，NEW regression 打回，STABLE_FAIL 上升用户。\n\n---\n\n## 验收确认（主会话，简化）\n\n> **不重新 code-reviewer 审查**。引用技术方案/后端编码/单测设计/E2E 开发 各节点 code-reviewer 审查结果，只做事实对照。\n\n```\n[主会话] 快速事实对照（5-10 分钟）:\n 1. 测试结果：全量回归全量 PASS 且 skip=0（或 skip 逐条有授权）？（引用 test-executor 报告；skip>0 必须逐条列出 skip 清单）\n 2. 测试完整性：检查通过？（引用检查输出 log 路径）\n 3. 不变量：不变量验证全 PASS？（引用 test-executor 报告）\n 4. 0 Critical：各节点 code-reviewer 审查的 Critical 已清零？（引用历史审查）\n 5. PRD 需求覆盖：所有需求有对应实现？（逐条对照，标注实现位置）\n 6. Scope creep：有超出原计划的新增？（标注并评估）\n 7. 已知问题判定（H8）：每条已知问题按「功能完整性」逐条判定？破坏 = 验收前必须修复（用户显式接受风险须引用原文）\n ↓\n ⏸ 呈现验收摘要，等用户确认归档\n```\n\n### 确认判定规则（HARD GATE）\n\n- **仅用户显式肯定表达构成确认**（\"验收通过\"/\"确认\"/\"同意归档\"等），且节点记录必须引用确认原文——**无可引用原文 = 不得归档/merge**。\n- **用户的提问/评估/条件句/新诉求一律不是确认**（如\"哪些是必须处理的？\"/\"必须先修复 X 才能验收\"）：应回应问题内容本身，然后继续等待显式确认。\n- 禁止从语气、沉默或部分认同推断同意（\"自说自话式同意\" = HARD GATE 违规）。\n\n### 验收判定\n\n| 条件 | Decision | Action |\n|------|----------|--------|\n| 测试 + 不变量全 PASS + 0 Critical + PRD 全覆盖 + 已知问题无阻塞项（H8） | ✅ APPROVED | → 归档 |\n| 测试 PASS 但 PRD 有未覆盖项 | ⚠️ CONDITIONAL | 用户确认 scope 差异 |\n| 测试有 FAIL 或 NEW regression | ❌ REJECTED | 打回对应节点 |\n| 破坏功能完整性的已知问题未修复且无用户显式接受风险原文 | ❌ REJECTED | 打回修复（H8） |\n\n---\n\n## 归档（委托 flow-executor，验收归档）\n\n> 用户确认验收后，主会话触发验收归档，委托 flow-executor 一次性完成所有归档动作。\n>\n> **归档中断/异常后状态核实（HARD GATE）**：归档被中断/超时/报错时，向用户报告状态前必须先 `git log` / `git status` 核实实际状态（merge/目录迁移可能已执行或部分执行），禁止凭记忆或推断报告。\n\n### 验收归档 flow-executor 委托模板（主会话 → flow-executor）\n\n委派 flow-executor subagent（验收归档），prompt 模板：\n\n```\n[TASK] 执行 验收归档 批次\n[CONTEXT]\n- 任务：<taskId>（siming 实例）\n- 任务 ID：<taskId>\n- feature 分支：feature/<taskId>-{slug}\n- 验收结果：{APPROVED/CONDITIONAL} + 用户确认原文引用（无原文 = 不得委托归档）\n- 测试统计：单测 {N} pass / E2E {N} pass / skip {S}（skip=0 或逐条授权清单）/ 0 new regression\n- 测试完整性：测试完整性检查通过（log: {检查日志路径}）\n- 不变量：{Backend: N/11 / UI: N/9}\n- 0 Critical 确认\n- 已知问题：{无 / issue 列表 + 逐条判定结论（已修复 / 用户显式接受风险原文）}\n- 架构信息摘要（验收阶段补充的架构发现，无则\"无\"）：{摘要}\n[EXPECTED]\n1. 逐条执行 siming 写入：record set（收尾 summary）→ record check add（验收判定项）→ archnote add（验收阶段补充的架构发现，多数情况为\"无\"）\n2. advance 推进（状态流转由任务状态机自动承载）\n3. 按项目声明的分支模型执行 git 提交与合并\n6. git push origin dev\n[MUST DO] 每步确认成功再继续，merge 用 --no-ff\n[MUST NOT DO] 不 squash/rebase，不跳过 push\n```\n\n---\n\n## 架构信息归档（主会话执行）\n\n> 架构文档实体在项目仓库（架构随代码演进）；siming 侧仅维护位置索引。项目设有架构索引 skill 时同步更新索引，未设则跳过。\n\n### 5 步流程\n\n1. **读取素材**：`siming_task { action: \"context\", taskId: \"<任务id>\" }` 取 archNotes 累积素材 + 各节点 decisions + review + 会话上下文中的重大决策（PRD/技术方案/E2E 设计）\n2. **产出「架构信息修改计划」**：按 分类 × 模块 × 决策主题 组织（架构决策任务无关，不绑定 <taskId>）。\n **写入要求（产出计划前逐条自查——违反 = 计划打回）**：① 简洁（每条一屏内可读）② 零基础可懂（用「行为与结果」语言，不用函数名/实现术语；必要的命令/路径/配置键可保留但须自解释）③ 对后续任务有帮助（写规则与约束，不写事件经过）④ 任务无关（不写评审轮次/返工/谁裁定等过程叙事——来源细节留在任务记录）⑤ 演进优先（同主题已存在则 edit 演进含退役标注，不新增重复条目）。完整版见项目架构文档目录的 README。\n\n ```\n 架构信息修改计划：\n 技术架构 · {模块名}：\n + {决策主题}（来源节点）\n 决策：{决策点} = {结论}\n 约束：{后续规则}\n 影响面：{受影响模块}\n ```\n\n3. **⏸ 人工 review（强制暂停点）**：呈现计划给用户审核。通过 → 步骤 4；放弃 → 不写入（任务记录保留作历史）；全部无新增 → 显式记录跳过判定。**禁止跳过此步骤直接写入**。\n4. **写入/跳过**：通过条目 edit 写入项目架构文档目录（按项目声明）对应分类文档的模块章节（子标题 `### {决策主题}`）；同主题已存在 → edit 演进而非新增。项目设有架构索引 skill → 同步更新索引。\n5. **提交**：按项目声明的 git 流程 commit（有远端则 push）。\n\n### 完成判定（架构信息归档独立判定 — 不依赖主完成判定）\n\n- [ ] archNotes/decisions 素材已读取\n- [ ] 架构信息修改计划已产出（写入要求 5 条自查通过）\n- [ ] 用户 review 已完成（通过/放弃/无新增三者必有其一且留痕）\n- [ ] 通过条目已写入 + 索引已更新（或显式判定跳过）\n- [ ] 提交完成（按项目 git 流程）\n\n### 不得继续（架构信息归档独有）\n\n- 计划未经用户 review 直接写入 → 违规\n- 全部「无新增」却未显式记录跳过判定 → 违规（跳过必须显式，禁止静默）\n\n## 质量 Skill 表\n\n| 角色 | Agent | Skill | 职责 |\n|------|-------|-------|------|\n| Executor | test-executor | dev-workflow-tester | 全量回归跑测试 |\n| Diagnoser | 主会话 | 系统化根因排查流程 | 全量回归 FAIL 修复 |\n| Acceptor | 主会话 | — | 验收确认事实对照 |\n| Archiver | flow-executor | `dev-workflow-buddy` | 归档 |\n\n---\n\n## 完成判定\n\n> **架构信息归档独立完成判定**：见上方「架构信息归档」章节（不在此处重复）。本节判定仅覆盖验收归档节点前段（到 验收归档 为止）。\n\n**流程步骤映射**：\n- [ ] 全量回归：全量测试已执行（所有活跃轨道 100% pass）\n- [ ] 不变量验证：不变量已全部 PASS（Backend 11 / UI 9）\n- [ ] 不变量验证：回归 Diff 无 NEW regression（STABLE_FAIL 已评估）\n- [ ] 验收确认：已获用户显式确认（引用确认原文；已知问题逐条判定，H8 满足）\n- [ ] 归档：flow-executor 已完成验收归档（记录追加 + 状态流转由任务状态机自动承载）\n- [ ] 架构信息归档：上方「架构信息归档」章节的独立完成判定全部 ✅（架构信息归档完成才是流程终止信号）\n\n**独立性约束**：\n- [ ] 验收基于本次实际测试结果 + 历史 code-reviewer 审查引用，不得伪造\n- [ ] 归档操作针对当前任务（<taskId>），不批量处理\n\n---\n\n## 不得继续\n\n- 任何 NEW regression 未修复\n- 不变量有 FAIL 且非已知问题\n- **涉及后端 API 的 UI 任务未跑联调冒烟（H5）或联调 FAIL**\n- 0 Critical 未满足（H6）\n- 用户未显式确认验收（确认须为显式肯定表达 + 引用原文；提问/评估 ≠ 确认）\n- 破坏功能完整性的已知问题未修复且无用户显式接受风险原文（H8）\n- merge 冲突且无法自动解决 / push 被拒绝\n\n## ▶ 直接继续\n\n架构信息归档完成后流程终止，不再有任何后续步骤。此时才可推荐下一个任务（HARD GATE「临时文件目录」）。\n\n> 完整顺序：用户确认验收 → 验收归档（flow-executor）→ 架构信息归档（主会话，5 步流程）→ 流程终止。\n\n### Rejection → Kickback\n\n| 失败项 | 打回到 | 原因 |\n|--------|--------|------|\n| 语法验证/语义验证 | 后端编码 / UI 组件开发 | 代码质量 |\n| 集成验证/smoke | 后端编码 | API 问题 |\n| 回归验证/E2E | 单测开发 / E2E 开发 | 测试不足 |\n| H5 联调冒烟 | UI 组件开发 | 补联调测试 |\n| 不变量 FAIL | 对应轨道编码节点 | 回归问题 |\n\n---\n\n## 轨道差异\n\n| 维度 | Backend | UI |\n|------|---------|-----|\n| 测试层 | 单测（框架按项目 AGENTS.md「测试范式」）+ E2E | Playwright MCP |\n| 不变量数 | 11（4 类） | 9（3 类） |\n| 回归基线 | E2E report baseline | Screenshot baseline |\n| 执行方式 | Maven CLI | Playwright MCP |\n\n> 集成验证前后端联调：涉及后端 API 的任务，验收归档的「全量回归」必须用真实后端 + 真实 HTTP 请求跑联调冒烟。纯 UI 任务（无后端依赖）N/A。\n\n",
|
|
523
|
-
"category": "process",
|
|
524
|
-
"version": "2.0.7",
|
|
525
|
-
"references": [],
|
|
526
|
-
"scope": "global"
|
|
527
|
-
},
|
|
528
|
-
{
|
|
529
|
-
"name": "prd-alignment-review-prompt",
|
|
530
|
-
"description": "PRD 对齐审查 prompt 模板（技术方案完成后的一致性审查）",
|
|
531
|
-
"content": "# PRD 对齐审查 Prompt 模板\n\n> 技术方案节点使用。alignment-reviewer 执行 PRD 对齐审查时注入此模板。\n\n## 使用场景\n\n技术方案节点 步骤 3（PRD 对齐审查）时，主 Agent 将此模板作为 prompt 基础，传入：\n- PRD 文档路径\n- 技术方案文档路径\n\n## 对齐审查 Prompt 模板\n\n```\n你是一名 PRD 对齐审查专家。你的任务是验证技术方案与 PRD/GDD 的对齐程度。\n\n## 输入文档\n- PRD: {prd_path}\n- 技术方案: {tech_path}\n\n## 审查步骤（严格按顺序执行）\n\n### 第一步：功能覆盖检查\n逐条核对 PRD 中声明的每个功能需求：\n- PRD 功能清单中的每一项，在技术方案中是否有对应的详细设计？\n- 技术方案中的功能范围是否与 PRD 一致（无遗漏、无超出范围的扩展）？\n\n输出格式：\n| PRD 功能项 | 技术方案对应章节 | 覆盖状态 | 说明 |\n|-----------|----------------|---------|------|\n| 功能 A | §3.1 | PASS | 完整设计 |\n| 功能 B | — | FAIL | 无对应设计 |\n\n### 第二步：逻辑一致性检查\n检查技术方案设计是否与 PRD 描述的行为、规则、约束矛盾：\n- 业务规则：PRD 定义的规则在方案中是否正确体现？\n- 用户流程：PRD 描述的用户操作路径在方案中是否完整覆盖？\n- 数据模型：PRD 中的数据需求在方案中是否有对应的存储/处理设计？\n- 权限与角色：PRD 定义的访问控制在方案中是否有对应实现？\n\n输出格式：\n| 检查维度 | PRD 描述（引用原文） | 技术方案描述（引用原文） | 一致性 | 矛盾说明 |\n|---------|-------------------|----------------------|--------|---------|\n| 业务规则 | \"用户每日限提交 3 次\" | \"RateLimiter 3/day\" | PASS | — |\n| 用户流程 | \"提交后进入审核队列\" | — | FAIL | 方案缺少审核队列设计 |\n\n### 第三步：验收标准对齐检查\n核对 PRD 中的验收标准在技术方案中是否都有对应的验证方式：\n- PRD 的每个验收标准，技术方案中是否有对应的设计来支撑其验证？\n- 验收标准的量化指标（性能、安全等）在方案中是否有对应的技术措施？\n\n输出格式：\n| PRD 验收标准 | 技术方案支撑 | 对齐状态 | 说明 |\n|-------------|-------------|---------|------|\n| \"响应时间 < 200ms\" | \"Redis 缓存 + 异步处理\" | PASS | 方案有对应措施 |\n| \"支持 1000 并发\" | — | FAIL | 方案缺少并发设计 |\n\n## 最终输出\n\n```\n## PRD 对齐审查结果\n\n### [功能覆盖] PASS/FAIL\n{总体结论}\n\n### [逻辑一致性] PASS/FAIL\n{总体结论}\n\n### [验收对齐] PASS/FAIL\n{总体结论}\n\n### FAIL 项修复建议（如有）\n{每项 FAIL 的修复方向}\n```\n\n## 约束\n- 你只有 READ 权限，禁止修改任何文件\n- 只检查对齐程度，不评价方案质量（那是架构审查的职责）\n- 不建议具体实现细节，只指出对齐偏差和修复方向\n- FAIL 项必须引用两份文档的具体原文\n```\n",
|
|
532
|
-
"category": "process",
|
|
533
|
-
"version": "1.0.3",
|
|
534
|
-
"references": [],
|
|
535
|
-
"scope": "global"
|
|
536
|
-
},
|
|
537
|
-
{
|
|
538
|
-
"name": "track-code",
|
|
539
|
-
"description": "",
|
|
540
|
-
"content": "# 后端编码 — Node/TS 后端轨道\n\n> 将技术方案转化为可编译的 TypeScript 生产代码（项目源码目录的生产代码（构建与类型检查按项目命令通过））。\n\n## Agent 配置\n\n| 角色 | Agent | Model | Skills |\n|------|-------|-------|--------|\n| Implementer | **主会话（一律，编码不委派）** | 主会话模型 | `code-philosophy` |\n| Verifier | `code-reviewer` subagent（**两轮独立调用**，新 session 各启，编排见执行动作第 6 步） | main-worker | ①架构/规范：`arch-review`, `code-philosophy` ②设计-实现一致性：`design-implementation-consistency` |\n\n> **Node/TS 轨无 `java-constraints` skill**：架构约束 + 编码规范内联在 `config-node.md` §五（Layer A/B/C）。主会话编码前从 `config-node.md` §五 + 项目 AGENTS.md 读取对齐。\n>\n> **Worker/Verifier 分离**: Implementer（主会话）实现 → `code-reviewer` 全新上下文审核。Verifier 不继承编码上下文，从文件读取结果零偏差审核。\n\n---\n\n## 🔒 HARD GATE — 编码阶段职责边界\n\n> **本节为 HARD GATE，违反即判定子 Agent 任务失败，主 Agent 必须回滚其所有改动。**\n\n### 核心规则：只改生产代码，不动验证代码\n\n「后端编码」的唯一职责：将技术方案转化为可编译的生产代码。测试、验证、适配工作留给后续步骤（单测/E2E 节点）。\n\n| 判断维度 | 属于 后端编码 | 属于 单测/E2E 节点 |\n|----------|-------------|------------------|\n| 变更目的 | 实现业务功能逻辑 | 验证业务功能是否正确 |\n| 文件性质 | 被测代码（项目源码目录，按项目 AGENTS.md 文件约定） | 验证代码（项目声明的测试文件模式/目录） |\n| 依赖变更 | 技术方案中明确要求的新依赖 | 适配生产代码签名变更 |\n\n### 禁止行为\n\n1. **修改任何 `*.test.ts` 文件** — 即使现有测试因生产代码签名变更而编译失败，这是预期行为，不要修复。\n2. **自行添加运行时依赖** — 不要修改项目包管理依赖清单的生产依赖，除非技术方案明确列出且经主 Agent 审核。devDependencies（测试工具等）同理。\n3. **修改构建配置** — 包括 `tsup.config.ts` / `vitest.config.ts` / `turbo.json` / `tsconfig.base.json`。\n4. **以\"让测试通过\"为目的修改任何文件** — 后端编码的通过标准是\"生产代码 typecheck + build 通过\"，不是\"测试通过\"。\n5. **单方面执行技术方案范围外的决策**（HARD GATE） — 编码中发现的技术决策（死代码删/留、顺手重构、命名改名、范围扩张）**必须显式抛给用户确认**，禁止自行决定。即使看似\"明显的清理\"也必须先问。用\"和其他接口一致\"给范围外动作背书 = 违规。\n\n### 编码中发现决策的处理协议（对应禁止行为 #5）\n\n| 发现类型 | 正确做法 | 错误做法（禁止） |\n|---------|---------|---------|\n| 死代码（零引用导出/函数） | ⏸ 抛出：\"发现 X 零引用，建议删除，确认？\" | 禁止直接删；禁止删后恢复来回折腾 |\n| 顺手重构（命名/结构优化） | ⏸ 抛出：\"发现 X 可优化为 Y，是否纳入本任务？\" | 禁止以\"一致性\"名义混入改名 |\n| 范围扩张（发现需改技术方案外的代码） | ⏸ 抛出：\"发现需额外改 X，是否扩展范围？\" | 禁止自行扩展后包装成\"一致性\" |\n| 注释/格式调整 | 仅技术方案明确要求的注释可改；其余不动 | 禁止顺手清理\"不顺眼\"的注释（HARD GATE: 编码时除了明确有调整的注释能修改外,禁止清除注释） |\n\n> **原则**：技术方案 = 授权范围。范围外的每一个动作都是独立决策，必须显式化。把多个决策混进一个\"一致性\"动作里绕过确认 = HARD GATE 违规。\n\n### 编码自律约束段（主会话编码时逐条遵守，来源同 HARD GATE）\n\n```\n## 🔒 后端编码 — 编码阶段职责边界\n\n唯一职责：将技术方案转化为可编译的 TypeScript 生产代码（生产代码 = `packages/*/src/` 下源码，非 `*.test.ts`）。\n\n### 可以做（通用编码纪律）\n- 修改 `packages/*/src/` 下的业务源码与配置文件（按技术方案要求）\n- 使用 Zod schema 校验所有外部输入（HTTP body/param/query、env、MCP args）\n- 遵循项目的分层架构与响应/异常/事务约定（**栈特定细节见下方「栈特定约束」段**）\n\n### 绝对不能做（违反即返工）\n- 禁止修改 `*.test.ts` 文件（即使现有测试因生产代码签名变更而编译失败，这是预期行为，不要修复）\n- 禁止修改 `packages/*/package.json`（除非技术方案明确要求且经用户确认）\n- 禁止修改 `tsup.config.ts` / `vitest.config.ts` / `turbo.json` / `tsconfig.base.json` 等构建配置\n- 禁止以\"让测试通过\"为目的修改任何文件\n\n### 遇到测试编译失败时\n这是正常现象。正确做法：忽略测试编译错误，确保生产代码 typecheck + build 通过即可（命令见项目 AGENTS.md COMMANDS）。测试适配在后续步骤 单测/E2E 节点 专项处理。\n\n### TypeScript 编码规范（来自 config-node skill §五 Layer B）\n- 禁 `any` / `as` 断言（`as any` / `as unknown as T`）\n- 禁 `enum`（用 `as const` 对象 + union type 替代）\n- ESM `.js` 扩展名（`verbatimModuleSyntax: true`，相对 import 用 `.js`）\n- `import type` 分离类型导入\n- `noUncheckedIndexedAccess`：数组/对象索引返回 `T | undefined`，必须 null check\n- `exactOptionalPropertyTypes`：可选属性不能赋 `undefined`\n- 错误处理：`throw new AppError(...)` 用于不可预期错误；`safeParse()` / Result type 用于可预期失败；禁止空 `catch (e) {}`\n- `__dirname` 替代：`import.meta.dirname`（Node 22+）或 `fileURLToPath(new URL('.', import.meta.url))`\n\n### 【栈特定约束】（主会话编码前自查）\n\n> ⚠️ **编码前自查纪律（HARD GATE）**：主会话编码前**必须直接读取任务所属项目的项目 AGENTS.md**「文件约定」「栈特定约束」「配置管理」三节（禁止依赖已压缩的 session 记忆）。任一节缺失或为空（未填充占位符）→ **⏸ 暂停询问用户**，待栈信息补齐再编码。禁止在栈信息缺失时开始编码（将无法正确分层/命名/响应包装）。\n\n**自查三节要点（从项目 AGENTS.md 读取）**：\n- **「文件约定」**：包结构 / 分层模型 / 各层命名 / routes/repos/schemas 等存放路径 / 响应包装类型 / DTO 推导方式（`z.infer`）\n- **「栈特定约束」**：持久层技术（MongoDB driver）/ 日志框架 / 依赖注入风格（函数式参数传递）/ 安全机制 / 语言版本约束 / 静态分析工具（tsgo/oxlint）\n- **「配置管理」**：配置工具（环境变量 + Zod env schema）/ 配置 key 约定（`SIMING_*` 前缀）\n\n多项目工作区时，主会话按**任务所属项目**读对应项目 AGENTS.md。\n```\n\n---\n\n## 执行动作\n\n1. 读取技术方案，提取 TypeScript 实现需求清单\n2. 主会话直接编码（编码一律不委派，见 项目 AGENTS 编排文件「编码 delegation 决策」；编码前按下方「编码自律约束段」自查栈信息三节）\n3. 按项目分层架构实现（分层模型、各层职责、命名、响应包装、事务边界、DTO 推导等栈特定约定见项目 AGENTS.md「文件约定」与「栈特定约束」）：\n - **持久层**（core/src/store/repos/）：Zod schema 定义 document 结构 + Repository 函数（接收 `client: SimingClient`）+ MongoDB CRUD；事务用 `withTransaction(client, fn)` 包装\n - **业务层**（core/src/task/ + core/src/dag/ + core/src/sync/）：状态机逻辑 + gate 校验 + DAG 实例化 + sync 引擎\n - **HTTP 层**（server/src/routes/）：Hono routes（`OpenAPIHono` + `createRoute()` + Zod schema `.openapi('Name')` 自动注册）+ `c.req.valid('json'/'param')` 类型安全提取\n - **MCP 层**（cli/src/mcp/）：MCP tool 定义（复用 CLI handler 函数 + `@modelcontextprotocol/sdk` 协议适配）\n - **转换**：MongoDB document ↔ API response 通过 Zod schema 转换（`z.infer<typeof Schema>`）；不直接暴露 MongoDB 原始 BSON\n4. 配置 key 管理（涉及新增 env 时）：按项目 AGENTS.md「配置管理」约定，用 Zod schema 启动时一次性解析（fail-fast）；新增 key 须在 项目环境说明文档（按项目声明） 文档化\n5. MongoDB 变更管理：index 变更有显式 `createIndex()` 调用（在 repo 初始化或 migration 脚本中）；schema validation（JSON Schema at DB level）做兜底\n6. **🔒 编码完成后必须 code-reviewer 审查（HARD GATE，禁止跳过）**——**两轮独立 code-reviewer，各自新 session**：\n - 主 Agent 加载 workflow-discipline（委派骨架） skill\n - **审查 ① 架构/规范审查**（新 session）：委派 code-reviewer subagent（skill 固化绑定自动加载） —— 架构权衡 + 分层规范（config-node.md §五 Layer B）\n - **审查 ② 设计-实现行为一致性审计**（新 session）：委派 code-reviewer subagent（skill 固化绑定自动加载） —— 钻入函数体追踪数据流/边界/副作用，检测\"形式匹配但实质偏离\"（伪批量、吞异常、事务漏洞、副作用顺序错位）\n - **顺序**：①先（架构层问题先暴露修复）→ ②后（钻函数体深度审计）\n - **fix-pass 独立**：两审查维度正交（架构 vs 行为），各自独立 re-verify；修①的问题不必重跑②，反之亦然。各自最多 3 轮，3 轮不通过 → ⏸ 升级用户决策\n - **两轮均 PASS 才算编码节点审查通过**；PASS 由两次 code-reviewer 本次输出判定，主会话不得自审\n\n## 质量 skill（主会话编码必载）\n\n| 委派对象 | 固化绑定 skill | 说明 |\n|---------------|-------------------|------|\n| 主会话（Node/TS 编码） | `code-philosophy` | 编码哲学与规范 |\n\n> Node/TS 轨无 `java-constraints` skill；架构约束 + 编码规范内联在 `config-node.md` §五，主会话编码时对齐。\n> 单测相关的测试规范在 `config-node.md` §五 Layer C + vitest 2 官方文档约束，单测设计节点加载，本步骤不写测试。\n\n## 数据库/配置变更增量记录（通用纪律）\n\n> 任何数据库 schema/配置变更必须有可追溯的增量记录，随编码 commit 提交。无变更时完成判定中显式标注 N/A，禁止静默跳过。\n\n| 变更类型 | 记录要求 |\n|---------|---------|\n| 数据库 index 变更 | 显式 createIndex() 调用迁移文件（位置按项目声明），含 index options |\n| 数据库 schema validation | 迁移文件中显式 collMod validator 变更 |\n| 新增配置 key | 项目声明的环境说明文档追加（用途/默认值/取值范围） |\n| 配置 schema 变更 | 纳入项目配置解析 schema，启动时 fail-fast |\n\n**幂等性**：迁移调用须幂等（重复执行无副作用）；validator 变更前先检查现状。\n\n**禁止**：为让测试通过修改 test database 的 validator（同步须基于真实 schema 变更，非测试适配）。\n## 构建命令\n\n> **CLI 日志落盘（HARD GATE）**：所有构建/测试命令必须按 项目声明的命令日志落盘纪律（若有） 落盘。\n\n> 构建命令与日志落盘方式按项目 AGENTS.md COMMANDS 执行（未声明的命令 → 向用户确认，禁止臆测）。\n\n## 完成判定\n\n**流程步骤映射**（第 1 层）：\n- [ ] 技术方案已读取，TypeScript 实现需求清单已提取\n- [ ] 编码已由主会话直接完成（编码不委派）\n- [ ] 分层实现已按项目分层架构完成（具体分层与命名见项目 AGENTS.md「文件约定」）\n- [ ] 涉及新增配置时：已按项目 AGENTS.md「配置管理」约定写入，每个 key 带注释；不涉及时：N/A\n- [ ] MongoDB 变更记录：涉及 index/schema validation 时已产出 migration 脚本；不涉及时：N/A\n- [ ] 配置变更记录：涉及新增 env key 时已在 项目声明的环境说明文档与配置 schema 同步更新；不涉及时：N/A\n- [ ] 已加载 workflow-discipline（委派骨架） skill，code-reviewer (Verifier) 已调用审查并通过（PASS 必须来自 code-reviewer 本次审查输出，不得引用历史审查或自审）\n\n**完整性约束**（第 2 层）：\n- [ ] 涉及新增配置时：配置文件已按项目约定实际写入（非仅声明已写入）\n- [ ] MongoDB migration 脚本 / 项目环境说明文档（按项目声明） 更新已实际产出（非仅声明已产出）\n- [ ] 项目分层架构各层均有新增/修改的 TypeScript 源文件（具体层名/路径见项目 AGENTS.md「文件约定」）\n\n**独立性约束**（第 3 层）：\n- [ ] TypeScript 代码已独立产出（产出路径：`packages/*/src/` 下项目包结构，具体见项目 AGENTS.md「文件约定」）\n- [ ] 不得引用技术方案章节替代实际编码（技术方案是设计产出物，后端编码是实现产出物，两者不可替代）\n\n## 不得继续的情况\n\n- typecheck 或 build 失败且多次修复（≤3 次）未果，需人工介入排查\n\n## ▶ 直接继续（禁止暂停询问）\n\n完成判定全部 ✅ 后，**先执行 git commit 保护编码成果**：\n\n```bash\ngit add -A\ngit commit -m \"feat(<taskId>): 编码完成 - {任务标题简要描述}\"\n```\n\ncommit 完成后：\n2. **直接继续 → 单测设计**（Node/TS 轨道），不得中断要求确认。\n",
|
|
541
|
-
"category": "process",
|
|
542
|
-
"version": "2.0.6",
|
|
543
|
-
"references": [],
|
|
544
|
-
"scope": "global"
|
|
545
|
-
},
|
|
546
|
-
{
|
|
547
|
-
"name": "track-component",
|
|
548
|
-
"description": "",
|
|
549
|
-
"content": "# UI 组件开发 — UI 前端轨道\n\n> 将技术方案（组件树/路由/状态管理/API 对接）转化为可构建的前端组件代码（React 19 + TypeScript 5.8 + Tailwind CSS 4 + Radix UI primitives）。产出：项目前端源码目录下组件/类型/样式（构建与类型检查按项目命令通过）。\n\n## Agent 配置\n\n| 角色 | Agent | Model | Skills |\n|------|-------|-------|--------|\n| Implementer | **主会话（一律，编码不委派）** | 主会话模型 | `ui-implementation`, `ui-constraints` |\n| Verifier | code-reviewer subagent（**两轮独立调用**，新 session 各启，编排见执行动作第 5 步） | main-worker | ①前端规范：`frontend-consistency`, `ui-constraints`, `frontend-philosophy`, `ui-implementation` ②设计-实现一致性：`design-implementation-consistency` |\n\n> **Worker/Verifier 分离**: Implementer（主会话）实现 → code-reviewer 全新上下文审核。\n\n---\n\n## 🔒 HARD GATE — 编码阶段职责边界\n\n> **本节为 HARD GATE，违反即判定子 Agent 任务失败，主 Agent 必须回滚其所有改动。**\n\n### 核心规则：只改生产代码，不动验证代码\n\n「UI 组件开发」的唯一职责：实现业务组件和交互逻辑。测试、E2E、视觉验证留给 UI 视觉验证和验收归档。\n\n| 判断维度 | 属于 UI 组件开发 | 属于 UI 视觉验证 / 验收归档 |\n|----------|-----------|------------------|\n| 变更目的 | 实现组件 UI + 交互逻辑 | 验证视觉质量 / 交互正确性 |\n| 文件性质 | 生产代码（组件 / 样式 / 类型） | 验证代码（Playwright 脚本 / 测试配置） |\n| 依赖变更 | 技术方案中明确要求的新依赖 | 适配验证工具链 |\n\n### 禁止行为\n\n1. **修改任何测试文件** — 包括 Playwright E2E 脚本、Jest/Vitest 测试文件、测试 fixture。\n2. **自行添加构建依赖** — 不要修改 `package.json`，除非技术方案明确列出且经主 Agent 审核。\n3. **修改构建配置** — 包括 Vite/Webpack/TypeScript 配置、ESLint/Prettier 规则。\n4. **以\"让测试通过\"为目的修改任何文件** — UI 组件开发的通过标准是\"生产代码编译通过\"，不是\"测试通过\"。\n\n### 编码自律约束段（主会话编码时逐条遵守，来源同 HARD GATE）\n\n```\n## 🔒 UI 组件开发 — 编码阶段职责边界\n\n唯一职责：将技术方案转化为可构建的前端组件代码。\n\n### 可以做\n- 创建 React 组件、TypeScript 类型定义、CSS 样式文件\n- 遵循项目组件规范（Tailwind CSS 4 CSS-only 配置 + Radix/Base UI primitives）\n- 实现所有交互状态的视觉反馈（loading / empty / error / populated）\n- 实现响应式布局（移动端适配）\n- 实现基础可访问性（语义化标签、ARIA 属性、键盘导航）\n- 表单校验（Zod + React 19 Actions: `useActionState` / `useFormStatus` / `useOptimistic`）\n\n### 绝对不能做（违反即返工）\n- 禁止修改任何测试文件 — Playwright / Vitest / 测试 fixture\n- 禁止修改 `packages/web/package.json`（除非技术方案明确要求且经用户确认）\n- 禁止修改 Vite / TypeScript / PostCSS 配置（`tailwind.config.js` 不存在，Tailwind 4 用 CSS-only 配置 `@theme`）\n- 禁止以\"让测试通过\"为目的修改任何文件\n- 禁止使用 `any` 类型（Props 接口必须完整类型标注）\n- 禁止使用 `forwardRef`（React 19 中 ref 是普通 prop，`forwardRef` 已 deprecated）\n\n### 遇到测试编译失败时\n这是正常现象。正确做法：忽略测试错误，确保生产代码构建与类型检查（命令按项目 AGENTS.md）通过即可。测试适配在 UI 视觉验证和验收归档专项处理。\n```\n\n---\n\n## 执行动作\n\n1. 读取技术方案，提取 UI 实现需求清单（组件树 / 路由 / 状态管理 / API 对接）\n2. 主会话直接编码（编码一律不委派，见 项目 AGENTS 编排文件「编码 delegation 决策」；遵守上方「编码自律约束段」）\n3. 每个组件实现遵循 `ui-implementation` 3-Pass 协议：\n - **Pass 1 — 骨架**：组件结构 + Props 接口 + 状态声明\n - **Pass 2 — 逻辑**：事件处理 + 数据流 + 副作用（useEffect / watch）\n - **Pass 3 — 细化**：样式 + 动画 + 边界处理 + 可访问性\n4. 每个数据组件覆盖 4 种状态：loading / empty / error / populated\n5. **🔒 编码完成后必须 code-reviewer 审查（HARD GATE，禁止跳过）**——**两轮独立 code-reviewer，各自新 session**：\n - 主 Agent 加载 workflow-discipline（委派骨架） skill\n - **审查 ① 前端规范审查**（新 session）：委派 code-reviewer subagent（skill 固化绑定自动加载） —— 编码风格 + 3-Pass + 四态 + 可访问性规范\n - **审查 ② 设计-实现行为一致性审计**（新 session）：委派 code-reviewer subagent（skill 固化绑定自动加载） —— 方案行为 vs 实现行为比对（如方案要求四态覆盖 loading/empty/error/populated 实现漏了某态、事件处理与数据流与方案不符、副作用时机错位、伪加载状态）\n - **顺序**：①先（前端规范问题先暴露修复）→ ②后（钻组件实现深度审计）\n - **fix-pass 独立**：两审查维度正交（规范 vs 行为），各自独立 re-verify；修①的问题不必重跑②，反之亦然。各自最多 3 轮，3 轮不通过 → ⏸ 升级用户决策\n - **两轮均 PASS 才算 UI 编码节点审查通过**；PASS 由两次 code-reviewer 本次输出判定，主会话不得自审\n\n## 质量 skill（主会话编码必载）\n\n| 委派对象 | 固化绑定 skill | 说明 |\n|---------------|-------------------|------|\n| 主会话（React 编码） | `code-philosophy`, `frontend-philosophy`, `frontend-consistency`, `ui-implementation` | UI 编码全部加载 |\n\n## 构建命令\n\n> **CLI 日志落盘（HARD GATE）**：`tsc`/`npm run build`/`npm run lint` 必须日志落盘按项目声明。\n\n```bash\n# 类型检查\n# 日志落盘按项目声明\n# typecheck 命令按项目 AGENTS.md COMMANDS\n\n# 构建验证\n# 日志落盘按项目声明\n# build 命令按项目 AGENTS.md COMMANDS\n\n# 代码规范（oxlint）\n# 日志落盘按项目声明\n# lint 命令按项目 AGENTS.md COMMANDS\n```\n\n## 完成判定\n\n**流程步骤映射**（第 1 层）：\n- [ ] 技术方案已读取，UI 实现需求清单已提取\n- [ ] 编码已由主会话直接完成（编码不委派）\n- [ ] 每个组件实现已遵循 `ui-implementation` 3-Pass 协议（骨架→逻辑→细化）\n- [ ] 每个数据组件已覆盖 4 种状态（loading / empty / error / populated）\n- [ ] 已加载 workflow-discipline（委派骨架） skill，code-reviewer (Verifier) 已调用审查并通过（PASS 必须来自 code-reviewer 本次审查输出，不得引用历史审查或自审）\n\n**独立性约束**（第 3 层）：\n- [ ] 组件代码已独立产出（产出路径：`packages/web/src/components/`、`packages/web/src/pages/` 等前端代码目录下的 TSX 文件）\n- [ ] 不得引用技术方案「组件树/状态管理」章节替代实际编码（技术方案是设计产出物，UI 组件开发是实现产出物，两者不可替代）\n\n## 不得继续的情况\n\n- 构建失败且多次修复（≤3 次）未果，需人工介入排查\n- review 连续 3 轮不通过 → ⏸ 暂停请用户决策\n\n## ▶ 直接继续（禁止暂停询问）\n\n完成判定全部 ✅ 后，**先执行 git commit 保护编码成果**：\n\n```bash\ngit add -A\ngit commit -m \"feat(<taskId>): 组件开发完成 - {任务标题简要描述}\"\n```\n\ncommit 完成后：\n1. 归档「UI 组件开发」节点（主会话直接执行小步命令）：record set（summary：变更文件清单 + 构建验证 + code-reviewer 审查结果）+ record check add（完成判定逐条）+ artifact add --type code --path（commit hash）；流转由任务状态机自动承载。详见 dev-workflow-buddy skill。\n2. **直接继续 → UI 视觉验证**（UI 轨道），不得中断要求确认。\n",
|
|
550
|
-
"category": "process",
|
|
551
|
-
"version": "2.0.5",
|
|
552
|
-
"references": [],
|
|
553
|
-
"scope": "global"
|
|
554
|
-
},
|
|
555
|
-
{
|
|
556
|
-
"name": "track-e2e-design",
|
|
557
|
-
"description": "",
|
|
558
|
-
"content": "# E2E 设计\n\n> 为 Node/TS 后端 API 设计端到端测试用例。适用轨道：**仅 Node/TS**（UI 轨道跳过）。设计完成（test-reviewer 审查通过）后直接推进 E2E 开发，不暂停。\n\n## HARD GATE：设计 ≠ 写代码\n\n**回答\"测什么场景、预期什么结果\"，禁止回答\"怎么写 E2E 代码\"。**\n\n| 允许（设计层） | 禁止（实现层，留给 E2E 开发） |\n|---------------|------------------------|\n| 用例表格：ID + 场景描述 + 前置条件 + 步骤（文字）+ 预期结果（文字） | 完整的 `test('xxx', async ({ request }) => { ... })` 方法体 |\n| Fixture 设计 + 职责描述（文字） | Fixture 的完整 TypeScript 实现 |\n| 测试数据配置表（参数值 → 预期结果） | `request.post(...)` 等 API 调用代码 |\n| E2E 基础设施：fixture 继承关系、依赖说明（文字） | Playwright config 配置代码 |\n\n**用例详细设计正确示例**：\n```\n#### TASK_ADVANCE_001 — 任务正常推进（P0）\n- 前置条件：server 运行在 :7777，MongoDB rs0 已连接\n- 核心步骤：POST /api/tasks 创建 Task → POST /api/tasks/:id/advance 推进 REQ→PRD\n- 预期：返回 200，response body current_node = \"PRD_DESIGN\"，history 含 advance 记录\n```\n\n**判断标准**：含可执行 TypeScript 代码块 → 实现层，禁止。\n\n## 执行动作\n\n> E2E 用例设计由主会话直接产出，不外派 subagent。任务记录、单测设计文档等上下文已在主会话。Node/TS 轨的 E2E 测试规范来自 config-node skill §五 Layer C（N1-N7 Playwright API testing 规则）+ Playwright 官方文档 + 项目 AGENTS.md。评审委派 test-reviewer 新 session（与单测设计一致，保持 Worker/Verifier 分离；skill 固化绑定自动加载评审标准）。\n\n1. 读取任务记录（含编码实施记录 + 单测开发单测记录）和技术方案\n\n **架构约束读取**：读取项目架构参考的 E2E 分类（位置按项目声明；不存在/为空/仅占位 → 跳过），对齐既有测试架构决策（隔离策略、并行约定、fixture 体系）。\n\n2. 读取单测设计文档，确认已有单测覆盖\n3. 主会话按模块拆解 E2E 场景，每模块覆盖：\n - **Happy Path**：正常 CRUD 全生命周期（创建→查询→更新→查询验证→删除）\n - **校验错误**：缺必填字段 / 字段超范围 / 类型不匹配（Zod schema 拒绝）\n - **状态机验证**：gate 未通过 → 拒绝 advance；暂停点 → 正确暂停\n - **删除后查询**：删除资源后再查询 → 验证返回 404\n - **OpenAPI 校验**：response body 与 OpenAPI spec 一致\n4. 委派 test-reviewer 子 agent（新 session）审查用例完整性和覆盖度（track-e2e-design skill 已固化绑定，自动加载评审标准；交互式 ≤3 轮）\n5. 将 E2E 用例设计**追加**到测试设计文档（与单测设计共用同一文档，追加「E2E 测试用例设计」章节）\n\n## 用例 ID 命名规范\n\n格式：`E2E_{模块缩写}_{场景缩写}_{序号}`\n\n| 模块 | 缩写 | 示例 |\n|------|------|------|\n| Task 管理 | `TASK` | `E2E_TASK_CREATE_001` |\n| DAG 模板 | `DAG` | `E2E_DAG_TEMPLATE_001` |\n| Skill 管理 | `SKILL` | `E2E_SKILL_SYNC_001` |\n| Agent 管理 | `AGENT` | `E2E_AGENT_CREATE_001` |\n| Gate 校验 | `GATE` | `E2E_GATE_FAIL_001` |\n\n## 产出格式\n\n```\n## E2E 测试用例设计\n\n### 用例概览\n| 用例ID | 模块 | 场景 | 优先级 | 类型 |\n|--------|------|------|--------|------|\n| E2E_TASK_CREATE_001 | Task | 创建Task | P0 | Happy Path |\n\n### 用例详细设计\n#### E2E_TASK_CREATE_001 — 创建 Task 成功（P0）\n- 前置条件：server 运行在 :7777，MongoDB 已连接\n- 核心步骤：POST /api/tasks → 返回 200\n- 预期结果：响应体含完整 Task 信息（id/title/current_node/status），MongoDB 有对应记录\n```\n\n## 完成判定\n\n- [ ] 任务记录和技术方案已读取\n- [ ] 单测设计文档已读取\n- [ ] E2E 场景已按模块拆解，用例设计已完成\n- [ ] test-reviewer 已完成 E2E 设计评审（≤3 轮）\n- [ ] E2E 用例设计已追加到测试设计文档\n\n**独立性约束**（防跳节点）\n- [ ] E2E 设计文档已独立追加（不引用单测设计/单测开发的内容替代）\n- [ ] 不得用\"单测设计已有单测覆盖\"跳过 E2E 场景设计\n\n## 不得继续\n\n- HARD GATE 被违反：设计文档出现可执行 TypeScript 代码块\n- 评审连续 3 轮不通过 → ⏸ 暂停\n\n## ▶ 完成后动作（连续执行，不暂停）\n\n设计完成（test-reviewer 审查通过）后直接执行，无需用户确认：\n\n1. 归档「E2E 设计」节点（主会话直接执行小步命令）：record set（summary：E2E 用例总数 + 覆盖场景清单 + 评审结论）+ record check add（完成判定逐条）+ artifact add --type test --file（测试设计文档全文，与单测设计共用）；流转由任务状态机自动承载。详见 `dev-workflow-buddy` skill。\n3. 进入 **E2E 开发** 节点\n",
|
|
559
|
-
"category": "process",
|
|
560
|
-
"version": "2.0.7",
|
|
561
|
-
"references": [],
|
|
562
|
-
"scope": "global"
|
|
563
|
-
},
|
|
564
|
-
{
|
|
565
|
-
"name": "track-e2e-dev",
|
|
566
|
-
"description": "",
|
|
567
|
-
"content": "# E2E 开发\n\n> 按 E2E 设计用例实现 Playwright E2E 测试代码并全部通过。适用轨道：**仅 Node/TS**（UI 轨道跳过）。\n\n> 流程纪律（workflow-discipline）已随节点注入，无需额外加载。\n\n## HARD GATE：构建命令强制\n\n**E2E 测试使用 Playwright**（API testing via `APIRequestContext`），通过项目声明的 E2E 执行入口打真实后端服务验证 API 契约。\n\n**必须使用** 项目声明的 E2E 执行入口命令（位置按项目 AGENTS.md 声明），禁止裸 `npx playwright test`、禁止在 server 包内直接跑 Playwright、禁止在 Web 包内跑后端 E2E。\n\n> **Playwright API testing 规范**：来自 `config-node.md` §五 Layer C（N1-N7 规则）+ Playwright 官方文档（playwright.dev/docs/api-testing）。E2E 开发编码前必读。\n\n> **CLI 日志落盘**：所有 E2E 命令必须按 项目声明的命令日志落盘纪律 落盘。\n\n> **自主环境准备（自主优先原则）**：Playwright 打真实后端服务（项目声明的服务端口）。本机 MongoDB / server 服务的启动、检查、故障排查**全部由 test-executor subagent 自主完成**（详见 `dev-workflow-tester` skill 自主环境准备章节）。**禁止要求用户启动本机服务**——本机依赖属\"环境故障\"分类，由 test-executor 自主处理，不构成上升用户的理由。\n>\n> test-executor 三阶段任务：自主环境准备（探活 MongoDB + server :7777，未运行则自主启动 `项目声明的服务启动命令`）→ 测试执行 → 错误信息收集。主 Agent 只做 Diagnose + 修代码 + 重跑决策。\n\nbash\n# 全量（在 monorepo 根执行）\n# 按 项目声明的命令日志落盘纪律 落盘\n# E2E 命令按项目 AGENTS.md COMMANDS（全量/单文件）\n\n# 单文件（Playwright 文件名 pattern）\n# 按 项目声明的命令日志落盘纪律 落盘\n# E2E 命令按项目 AGENTS.md COMMANDS（全量/单文件）\n\n\n> ⚠ 项目未声明 E2E 入口或 E2E 环境不存在 → 跳过 E2E 开发节点，在节点记录 summary 标注「E2E 暂挂（原因）」。\n\n## Agent 配置（委派指名，skill 已固化绑定）\n\n| 角色 | Agent | 说明 |\n|------|-------|------|\n| Coder | 主会话 | 只写测试代码 |\n| Verifier | code-reviewer | 测试代码审查（新 session，零预设） |\n| 执行 | test-executor | 全部测试命令执行（boundSkills: dev-workflow-tester），主会话禁止亲自跑测试 |\n\n## 执行动作\n\n1. 读取 E2E 设计测试设计文档中「E2E 测试用例设计」章节\n2. 主会话按 `config-node.md` §五 Layer C（N1-N7）+ Playwright 官方文档规范直接编写测试（编码一律不委派）\n3. 按映射规则实现代码：\n - **用例 ID** → `test('E2E_XXX_NNN: 描述', ...)` test name\n - **接口 URL** → `baseURL` + 相对路径（Playwright config 配置 `baseURL: 'http://localhost:7777'`）\n - **请求体** → TypeScript object + Zod schema 校验（如需）\n - **预期结果** → `expect(response.status()).toBe(200)` + Zod `safeParse(response body)` 断言\n - **参数化场景** → Playwright `test.describe` 多 test 或 `testInfo.workerIndex` 数据隔离\n - **测试文件** → `{feature}.e2e.ts` 或 `{feature}.spec.ts`，放在 `e2e/` 目录或 `tests/e2e/`\n - **Fixture** → `test.extend<{ apiContext: APIRequestContext }>({ ... })` 创建独立数据上下文\n4. **⚠️ 执行前 HARD GATE**：**分派 test-executor subagent** 执行三阶段任务（自主环境准备 → 测试执行 → 错误信息收集）。`dev-workflow-tester` skill 固化绑定于 test-executor agent，委派即自动生效\n5. **增量验证**：委托 test-executor 跑 # E2E 命令按项目 AGENTS.md COMMANDS（全量/单文件）\n6. **全量验证**：委托 test-executor 跑 项目声明的 E2E 入口命令 全部通过\n7. **回归验证**：委托 test-executor 跑全量单测 单测全量（命令按项目 AGENTS.md），确认未影响已有测试\n8. **测试完整性静态检查（HARD GATE，主会话执行，禁止跳过）**：执行项目声明的测试完整性检查脚本（若有）—— exit≠0 禁止 checkpoint commit\n9. **test-executor 返回 FAIL** → 主 Agent 加载 系统化根因排查流程（复现→隔离→假设→验证） Diagnose 根因 → 修代码 → 重新委托 test-executor 重跑（最多 3 轮）\n10. **🔒 E2E 编码完成后必须 code-reviewer 代码审查（HARD GATE，禁止跳过）**：\n - 主 Agent 加载 workflow-discipline（委派骨架） skill\n - **必须**委派 code-reviewer Verifier（新 session，全新上下文；skill 固化绑定自动加载）\n - 审查 PASS 由 code-reviewer 本次输出判定，主会话 不得自审\n - FAIL → 修复 → 新 session code-reviewer re-verify（最多 3 轮）\n11. 整理 E2E 测试结果素材（用例数 + 通过率 + skip 清单[如有，逐条列明授权原因] + 覆盖场景 + 项目测试完整性检查结果 与 log 路径），本节点完成时按节点 prompt 归档动作执行 siming 小步命令\n\n## 质量 Skill（主会话编码必载）\n\n| 加载对象 | 固化绑定 | 说明 |\n|---------------|-------------------|------|\n| 主会话（E2E 测试编码） | `code-philosophy` | Playwright API testing 规范来自 config-node.md §五 Layer C |\n| E2E 测试执行（test-executor） | `dev-workflow-tester` | 自主环境准备 + 执行 + 失败信息收集（不分析、不改代码） |\n| Diagnose + 修代码（主 Agent） | 系统化根因排查流程（复现→隔离→假设→验证） | test-executor 报 FAIL 时主 Agent 加载，根因分析 |\n\n## 代码规范\n\n### Playwright API testing（来自 config-node.md §五 Layer C N1-N7）\n- **request fixture**：用 Playwright 内置 `request` fixture（test-scoped，自动 dispose），不用 `playwright.request.newContext()`\n- **baseURL + headers**：`playwright.config.ts` 配置 `baseURL` + `extraHTTPHeaders`（如 `Accept: application/json`）\n- **Zod response 校验**：API response 用 Zod schema 校验（`Schema.safeParse(await response.json())`），断言 `success: true`；禁止只断言 HTTP status 不校验 body\n- **test-scoped fixture**：数据隔离：每个 test 用 fixture 创建独立数据\n- **`testInfo.workerIndex`**：需要唯一标识时用 `testInfo.workerIndex`（单调递增）\n- **API + UI 混合**：API seed → UI 验证 / UI 操作 → API 校验（如有 UI 交互需求）\n- **失败处理**：`testInfo.attach()` 附加请求 URL/headers/status/body 到失败报告\n- **禁止**：裸 `npx playwright test`、硬编码 URL（用 `baseURL` + 相对路径）、`Thread.sleep()` 等待异步结果（用 Playwright auto-waiting）\n- **E2E 失败时**：**Iron Law：未完成根因调查禁止提修复方案。3 次修复失败 → STOP 质疑架构（启发式阈值）。** 先按系统化根因排查流程（4 阶段：复现→隔离→假设→验证）排查，禁止凭直觉改代码\n\n## 完成判定\n\n- [ ] E2E 设计 用例设计章节已读取\n- [ ] config-node.md §五 Layer C（N1-N7）规范已加载，主会话已严格按规范完成编码（编码不委派）\n- [ ] 映射规则已遵循（用例ID→test name、URL→baseURL+相对路径、response→Zod校验 等）\n- [ ] dev-workflow-tester skill 已加载，**已委托 test-executor subagent 执行三阶段任务**（自主环境准备 → 测试执行 → 信息收集）\n- [ ] 委托 test-executor 按模块/文件增量验证已执行\n- [ ] 委托 test-executor 全量 E2E 已执行\n- [ ] 委托 test-executor 全量单测回归验证已执行\n- [ ] 测试完整性检查已执行且通过（无新增 skip、无被删测试文件；skip ≠ pass）\n- [ ] test-executor 返回的 FAIL 已由主 Agent Diagnose + 修复 + 重跑闭环（如有）\n- [ ] 已加载 workflow-discipline（委派骨架） skill，code-reviewer (Verifier) 已调用审查并通过（PASS 必须来自 code-reviewer 本次审查输出，不得引用历史审查或自审）\n- [ ] E2E 测试结果素材已准备（本节点完成时按节点 prompt 归档动作小步写入）\n\n**独立性约束**（防跳节点）\n- [ ] E2E 代码已独立产出（不引用 E2E 设计 内容作为代码）\n- [ ] 回归验证结果基于本次实际执行（不得引用历史/其他任务结果替代）\n\n## 不得继续\n\n- E2E 测试失败定位为后端 Bug（非测试代码问题）→ ⏸ 暂停，需人工确认\n- review 连续 3 轮不通过 → ⏸ 暂停\n\n## ▶ 直接继续（禁止暂停询问）\n\n完成判定全部 ✅ 后立即执行：\n\n### Checkpoint Commit（⚠️ 强制）\nbash\ngit add -A\ngit commit -m \"test(<taskId>): E2E完成 - {描述}\"\n\n\n**commit 完成后**：\n\n2. 进入 **验收归档** 节点\n",
|
|
568
|
-
"category": "process",
|
|
569
|
-
"version": "2.0.7",
|
|
570
|
-
"references": [],
|
|
571
|
-
"scope": "global"
|
|
572
|
-
},
|
|
573
|
-
{
|
|
574
|
-
"name": "track-ut-design",
|
|
575
|
-
"description": "",
|
|
576
|
-
"content": "\n# 单测设计\n\n> 为已实现代码设计测试用例，产出测试计划文档。适用轨道：Node/TS（测试框架/约定见项目 AGENTS.md「测试范式」；UI 轨道跳过）。\n\n## HARD GATE：测试设计 ≠ 写代码\n\n**回答\"测什么、为什么测\"，禁止回答\"怎么写代码\"。**\n\n| 允许（设计层） | 禁止（实现层，留给单测开发） |\n|---------------|------------------------|\n| 用例表格：场景描述 + RIGHT-BICEP 分类 + 预期行为（文字） | 测试函数体（`test('should xxx', () => { ... })`） |\n| Mock 要点：用文字描述\"需 mock A 返回 B\" | `vi.mock(...)` / `vi.spyOn(...)` 代码块 |\n| 断言要点：用文字描述\"验证函数 P 被调用 / 结果为 Q\" | `expect(...)` 断言代码 |\n| 测试文件组织结构（`describe` 分组说明） | 完整的 `beforeEach` mock stub |\n| 数据准备策略（文字描述数据场景） | TypeScript 对象构建 / DB seed 代码 |\n\n**判断标准**：内容含可执行代码块 → 实现层，禁止。\n\n## 执行动作\n\n> 本节点分为 **Worker 设计阶段** 与 **Verifier 评审门控阶段**。设计由主会话直接执行，评审由 test-reviewer 新 session 只读审查（HARD GATE：禁止自审）。主会话与 test-reviewer 新 session 天然不同 session，Worker/Verifier 分离成立。\n\n### 测试设计 · Worker：测试设计（主会话直接执行）\n\n> 测试设计文档由主会话直接产出。Node/TS 轨的测试规范来自 `config-node.md` §五 Layer C + vitest 2 官方文档 + 项目 AGENTS.md「测试范式」。RIGHT-BICEP 策略本身是框架无关的通用测试设计方法论。\n\n1. 读取任务记录（含编码实施记录），梳理变更范围\n2. 按 **RIGHT-BICEP** 策略逐模块设计用例：\n - **Right**：正确输入 → 预期输出\n - **Boundary**：`undefined` / `null` / 空数组 / 极限值 / 边界条件\n - **Inverse**：反向操作验证（创建→删除→查询）\n - **Cross-check**：不同路径到达同一结果的等价性\n - **Error**：非法输入 / 异常路径 / 降级行为\n - **Performance**：耗时/资源敏感路径（按需覆盖）\n3. 确定覆盖率目标：核心路径 100%，边界按复杂度调整（项目 AGENTS.md「测试范式」中的覆盖率要求）\n4. 产出测试设计文档，整理路径引用素材（单测设计归档时经 record set/check add + artifact add --type test --file 登记文档路径与全文\n5. 触发 单测设计→单测开发 评审暂停点，进入测试方案评审\n\n### 测试方案评审 · Verifier：test-reviewer 新 session 审查（HARD GATE）\n\n> ⚠️ **评审门控（连续执行，非暂停点）**：评审是单测设计内部的自动环节，通过后直接推进到单测开发，不暂停等用户。\n> 禁止自审：Verifier 必须是委派 test-reviewer subagent 的新 session，不继承 Worker context。\n\n1. 由 test-reviewer 在新 session 中审查（track-ut-design skill 已固化绑定，自动加载评审标准）：\n - RIGHT-BICEP 六维度覆盖完整性（无维度遗漏）\n - 用例与被测模块一一对应（无模块遗漏）\n - Mock 要点和断言要点是否清晰、可执行（单测开发节点据此编码）\n - 覆盖率目标是否合理\n2. 交互式评审 ≤3 轮（Reviewer 逐条评估 → Worker 修复 / 记录不修复理由 → 重提）\n3. 决定不修复的审查意见，必须在评审结果中记录「审查发现 + 不修复理由」\n4. 评审通过后，将评审结果（含审查发现 + 处理决定）保留在测试设计文档的修订记录中，不单独追加到任务记录（单测开发节点记录仅记录单测实施结果），自动进入流转\n\n## 产出\n\n### 测试设计文档（写入仓库 + artifact 登记）\n\n写入项目文档目录（目录约定按项目 AGENTS.md 声明），文件名 `<taskId>-<标题>-测试设计.md`，随后 `siming_task { action: \"record-artifact-add\", taskId: \"<任务id>\", node: \"UT_DESIGN\", artifactType: \"test\", file: \"<路径>\" }` 全文快照入库。\n\n文档骨架：\n\n```markdown\n# <taskId> - {标题} 单测设计\n\n## 单元测试计划\n**测试策略**：RIGHT-BICEP\n**覆盖率目标**：核心路径 X%，边界路径 Y%\n\n### 被测模块清单\n| 被测模块/函数 | 测试文件 | 用例数 | RIGHT-BICEP 维度 |\n|--------------|---------|--------|-----------------|\n| taskStateMachine | task-state-machine.test.ts | N | Right + Boundary + Error |\n\n### 用例清单（每模块一个表格）\n| # | test name | 维度 | 覆盖分支 | 场景描述 | Mock 要点 | 断言要点 |\n|---|-----------|------|---------|---------|----------|---------|\n| 1 | should advance when all gates pass | R | xxx分支 | 场景描述 | mock gateCheck 返回 passed | 验证 task.current_node 更新 |\n```\n\n## 轨道差异\n\n### Node/TS 轨道\n测试框架（vitest 2）、测试文件命名（`*.test.ts`，co-location 或 `test/` 目录）、Mock 工具（`vi.mock()` / `vi.spyOn()`）、命令、PASS 标准是项目特定信息，见**项目 AGENTS.md「测试范式」**。RIGHT-BICEP 策略本身是框架无关的通用测试设计方法论。\n\n## 完成判定\n\n**测试设计**\n- [ ] 任务记录已读取，变更范围已梳理\n- [ ] RIGHT-BICEP 六维度已逐模块完成用例设计\n- [ ] 覆盖率目标已确定\n- [ ] 测试设计文档已产出，路径素材已整理（单测设计归档时按节点 prompt 归档动作小步写入）\n- [ ] 评审暂停点已触发，已进入测试方案评审\n\n**测试方案评审**\n- [ ] test-reviewer 已在新 session 中完成测试设计评审\n- [ ] 交互式评审已完成（≤3 轮）\n- [ ] 不修复的审查意见已记录「审查发现 + 不修复理由」\n- [ ] 评审结果已记录在测试设计文档修订记录中（不单独追加到任务记录，单测开发节点记录仅记录单测实施结果）\n\n**完整性约束**（防偷工减料）\n- [ ] 测试设计文档已含逐模块用例清单（非全局泛泛描述）\n\n**独立性约束**（防跳节点）\n- [ ] 测试设计文档已独立产出并 artifact 登记\n- [ ] **不得引用技术方案「测试策略」章节替代本节点产出**（技术方案「测试策略」仅描述策略，具体用例设计由单测设计节点独立完成）\n\n**防盖章约束**（HARD GATE）\n- [ ] **禁止以\"现有测试已覆盖\"为由跳过本节点设计工作**。即使现有测试看似覆盖变更，仍须逐模块产出 RIGHT-BICEP 用例清单，显式判定\"现有测试是否覆盖本次变更的新分支/边界\"。盖\"现有覆盖\"章而不做实际设计 = HARD GATE 违规\n\n## 不得继续\n\n- HARD GATE 被违反：设计文档出现可执行代码块\n- 评审连续 3 轮不通过 → ⏸ 暂停，输出评审摘要请用户决策\n\n## ▶ 直接继续（禁止暂停询问）\n\n> 评审（测试方案评审）是单测设计内部的连续执行环节，通过后自动推进，不暂停。\n> 唯一例外：评审连续 3 轮不通过 → ⏸ 暂停，输出评审摘要请用户决策（见「不得继续」）。\n\n完成判定全部 ✅（**含测试设计评审通过**）后立即执行：\n\n1. 归档「单测设计」节点（主会话直接执行小步命令）：record set（summary）+ record check add（完成判定逐条）+ artifact add --type test --file（测试设计文档全文）；流转由任务状态机自动承载。详见 `dev-workflow-buddy` skill。\n3. 进入 **单测开发** 节点（任务记录已在 `对应阶段/`，单测设计→单测开发 Phase 内不流转）\n\n",
|
|
577
|
-
"category": "process",
|
|
578
|
-
"version": "2.0.8",
|
|
579
|
-
"references": [],
|
|
580
|
-
"scope": "global"
|
|
581
|
-
},
|
|
582
|
-
{
|
|
583
|
-
"name": "track-ut-dev",
|
|
584
|
-
"description": "",
|
|
585
|
-
"content": "# 单测开发\n\n> 按单测设计的测试计划编写测试代码，TDD 红绿重构。适用轨道：Node/TS（测试框架/约定见项目 AGENTS.md「测试范式」；UI 轨道跳过）。\n\n> 流程纪律（workflow-discipline）已随节点注入，无需额外加载。\n\n## HARD GATE：TDD 纪律\n\n**RED → GREEN → REFACTOR，禁止跳过任何阶段。**\n\n| 阶段 | 动作 | 验证 |\n|------|------|------|\n| RED | 先写 failing test（单测设计中的 P0 用例） | 确认 test FAIL（test PASS accidentally → 检查正确性） |\n| GREEN | 最小实现让测试通过 | 确认 test PASS（单次） |\n| REFACTOR | 重构消除重复，保持 test PASS | 确认所有测试仍 PASS |\n\n禁止：跳过 RED 直接写实现、删除 failing test 来\"通过\"、空测试（无断言）。\n\n## Agent 配置（委派指名，skill 已固化绑定）\n\n| 角色 | Agent | 说明 |\n|------|-------|------|\n| Coder | 主会话 | 只写测试代码 |\n| Verifier | code-reviewer | 测试代码审查（新 session，零预设） |\n| 执行 | test-executor | 全部测试命令执行（boundSkills: dev-workflow-tester），主会话禁止亲自跑测试 |\n\n## 执行动作\n\n1. 读取单测设计产出的测试设计文档（路径取该节点 artifact 登记）\n2. 主会话直接编写测试代码（编码一律不委派，见 项目 AGENTS 编排文件「编码 delegation 决策」；TDD 循环：RED → GREEN → REFACTOR）\n3. **增量验证**：每完成一个测试文件，立即执行该文件验证通过\n4. **全量验证**：全部测试文件完成后执行全量测试\n5. **测试完整性静态检查（HARD GATE，主会话执行，禁止跳过）**：执行项目声明的测试完整性检查脚本（若有）——exit≠0 禁止推进。新增 skip/被删测试文件 = FAIL：被本任务改坏的测试无条件归本任务，禁止静默 skip 降级（纪律见 workflow-discipline skill）\n6. **🔒 测试编码完成后必须 code-reviewer 代码审查（HARD GATE，禁止跳过）**：\n - 主 Agent 加载 workflow-discipline（委派骨架） skill\n - **必须**委派 code-reviewer（新 session，全新上下文）审查测试代码\n - 审查 PASS 由 code-reviewer 本次输出判定，主会话 不得自审\n - FAIL → 修复 → 新 session code-reviewer re-verify（最多 3 轮）\n7. 整理测试结果素材（测试文件 + 用例数 + 覆盖率 + 通过率 + skip 清单[如有，逐条列明授权原因] + 项目测试完整性检查结果），本节点完成时按节点 prompt 归档动作执行 siming 小步命令\n\n## 构建命令\n\n> **测试执行 = delegate test-executor，无条件**（项目 AGENTS 编排文件「测试执行 HARD GATE」）。以下命令模板供 test-executor 使用，主会话不直接跑。\n\n### 命令模板（命令值取自项目 AGENTS.md COMMANDS）\n> 构建命令与日志落盘方式按项目 AGENTS.md COMMANDS 执行（未声明的命令 → 向用户确认，禁止臆测）。\n\n## 质量 Skill（主会话编码必载）\n\n| 加载对象 | 固化绑定 | 说明 |\n|---------------|-------------------|------|\n| 主会话（Node/TS 单测编码） | `code-philosophy` | vitest 2 测试规范来自 config-node.md §五 Layer C + 项目 AGENTS.md「测试范式」 |\n\n> Node/TS 轨无 `java-springboot-testing` skill；测试规范内联在 config-node.md + 项目 AGENTS.md，主会话委托时注入。\n\n## 测试规范\n\n### 通用（框架无关）\n- **禁止**：测试间共享可变状态、硬编码测试数据（用 `beforeEach` 重置）\n\n### Node/TS 轨道（vitest 2）\n测试文件命名（`*.test.ts`）、co-location vs `test/` 目录、Mock 工具（`vi.mock()` / `vi.spyOn()` / `vi.hoisted()`）、断言风格（`expect().toBe()`）、`describe/test/beforeEach` 组织结构、覆盖率配置（v8 provider）是项目特定信息，见**项目 AGENTS.md「测试范式」**。TDD 红绿重构纪律本身是框架无关的通用方法论。\n\n#### vitest Mock 策略要点（来自 config-node.md §五 + vitest.dev/guide/mocking）\n- `vi.hoisted()` 定义 mock 返回值（hoist 到模块加载前）\n- `vi.mock('module', () => {...})` 替换整个模块\n- `vi.spyOn(obj, 'method')` partial mock（保留原实现，只改指定方法）\n- MSW（Mock Service Worker）mock HTTP 请求（集成测试场景）\n- `vi.stubEnv('KEY', 'value')` mock 环境变量（替代直接改 `process.env`）\n- **不 mock 被测对象本身**，mock 其依赖\n\n## 测试失败修复（⚠️ HARD GATE）\n\n测试失败后 → **Iron Law：未完成根因调查禁止提修复方案。3 次修复失败 → STOP 质疑架构（启发式阈值）。** 必须先按系统化根因排查流程（4 阶段：复现→隔离→假设→验证）排查根因。禁止凭直觉改代码。定位为业务逻辑 Bug 时 → 见「不得继续」。\n\n### 故障分类（先判断类型，再选方法）\n\n- **简单 Bug**（编译错误 / typo / 明确逻辑错误 / 单一组件内）→ 单一根因调查，走系统化根因排查 4 阶段（复现→隔离→假设→验证）\n- **复杂系统故障**（跨服务 / 间歇性 / 环境相关 / 涉及中间件）→ 用 **contributing factors** 视角，禁止简单归因单一根因（参考 Dekker、Allspaw \"no root cause\"、Leveson STAMP）。系统故障是多因素涌现的结果，不是单点故障链\n\n## 完成判定\n\n- [ ] 单测设计文档已读取\n- [ ] 逐测试文件 TDD 循环已执行（RED → GREEN → REFACTOR）\n- [ ] 每个测试文件完成后已执行增量验证\n- [ ] 全部测试文件完成后已执行全量测试\n- [ ] 测试完整性检查已执行且通过（无新增 skip、无被删测试文件）\n- [ ] code-reviewer 已调用审查并通过（PASS 必须来自 code-reviewer 本次审查输出，不得引用历史审查或自审）\n- [ ] 测试结果素材已准备（本节点完成时按节点 prompt 归档动作小步写入）\n\n**独立性约束**（防跳节点）\n- [ ] 测试代码已独立产出（不引用单测设计文档内容作为代码）\n- [ ] 测试代码不得仅引用单测设计路径而不实际编码\n\n**防盖章约束**（HARD GATE）\n- [ ] **禁止以\"现有测试已覆盖\"为由跳过本节点开发工作**。即使单测设计判定\"现有测试已覆盖某分支\"，仍须针对本次变更逐个用例验证存在性 + 执行通过。盖\"现有覆盖\"章而不实际编码/验证 = HARD GATE 违规\n\n## 不得继续\n\n- 测试失败定位为业务逻辑 Bug（非测试代码问题）→ ⏸ 暂停，需人工确认\n- review 连续 3 轮不通过 → ⏸ 暂停\n\n## ▶ 直接继续（禁止暂停询问）\n\n完成判定全部 ✅ 后立即执行：\n\n### Checkpoint Commit（⚠️ 强制）\n```bash\ngit add -A\ngit commit -m \"test(<taskId>): 单测完成 - {描述}\"\n```\n\n**commit 完成后**：\n\n1. 归档「单测开发」节点（主会话直接执行小步命令）：record set（summary：测试文件清单 + 用例统计 + 覆盖率 + 完整性检查结果）+ record check add（完成判定逐条）；流转由任务状态机自动承载。详见 `dev-workflow-buddy` skill。\n2. 按轨道分流：\n\n| 轨道 | 下一节点 |\n|------|---------|\n| Node/TS | **E2E 设计** 节点 |\n",
|
|
586
|
-
"category": "process",
|
|
587
|
-
"version": "2.0.8",
|
|
588
|
-
"references": [],
|
|
589
|
-
"scope": "global"
|
|
590
|
-
},
|
|
591
|
-
{
|
|
592
|
-
"name": "track-visual",
|
|
593
|
-
"description": "",
|
|
594
|
-
"content": "# UI 视觉验证 — UI 前端轨道\n\n> Track 阶段内部验证节点，**阶段内不流转（状态由任务状态机承载）**。对 UI 组件开发产出进行视觉质量审核与修复。输入：UI 组件开发产出的组件代码 + Playwright MCP 截图 + UI 设计规范（来自 PRD/技术方案）+ `ui-constraints` Layer D。输出：5 维度视觉审核报告 + 修复后组件代码 + 回归截图（UI 视觉验证节点归档时按节点 prompt 归档动作小步写入）。\n\n## Agent 配置\n\n| 角色 | Agent | Model | Skills |\n|------|-------|-------|--------|\n| Vision Verifier | `visual-reviewer` subagent | xiaomi/mimo-v2.5 | `ui-verify`, `ui-constraints`, `multimodal-vision` |\n| Fixer | **主会话（一律，编码不委派）** | 主会话模型 | `ui-implementation`, `ui-constraints` |\n| 仲裁者 | 主会话 | main-worker | `workflow-discipline` |\n\n> **Why `visual-reviewer`**: 需要多模态能力分析截图，识别视觉缺陷（布局错位、样式偏离、状态缺失）。\n>\n> **Why Fixer = 主会话**: 视觉缺陷修复是编码（受 项目 AGENTS 编排文件「编码 delegation 决策」约束，编码一律主会话自做），主会话加载视觉域 skill 后直接修复。\n\n---\n\n## 🔒 HARD GATE — Playwright MCP 视觉验收\n\n> **本节为 HARD GATE，未通过不得进入验收归档·全量回归。**\n\n### 核心规则：视觉审核 + 修复循环，直至全部通过\n\n「UI 视觉验证」的核心职责：通过 Playwright MCP 采集截图 → `visual-reviewer` 多模态审核 → 定位缺陷 → 主会话（Fixer）修复 → 回归验证。\n\n### 子 Agent prompt 约束段 — Vision Verifier（主 Agent 必须原文注入）\n\n```\n## 🔒 UI 视觉验证 — Vision Verifier 审核维度\n\n对每张截图从以下 5 个维度逐一审核，给出 PASS / FAIL + 具体缺陷描述：\n\n### 1. 状态完整性 (State Completeness)\n审核每个数据组件是否覆盖 4 种状态：\n- loading: 是否使用 skeleton（非 spinner），skeleton 结构是否与内容布局匹配\n- empty: 是否包含描述文案 + 引导 CTA（非空白页面）\n- error: 是否包含错误信息 + 重试 CTA\n- populated: 数据是否正确渲染\n- 关键检查: finally 块是否重置 loading 状态\n\n### 2. 可访问性 (Accessibility)\n- 交互元素是否使用语义化 HTML（`<button>` 非 `div+onClick`）\n- 图标按钮是否有 `aria-label`\n- 装饰图标是否有 `aria-hidden=\"true\"`\n- 键盘导航是否可用（Tab 键顺序是否合理）\n- `prefers-reduced-motion` 是否生效\n\n### 3. 组件标准 (Component Standards)\n- 是否使用组件库（Radix UI primitives + Tailwind CSS 4），未自行实现 Dialog/AlertDialog/Table\n- 表单提交按钮 `disabled={submitting}`，删除按钮 `disabled={deleting}`\n- 弹窗焦点管理由组件库处理（未手动 autoFocus ref）\n- Props 接口类型完整，无 `any`\n\n### 4. 边界场景 (Edge Case Handling)\n- 列表空状态有引导 CTA\n- 长文本截断 + Tooltip\n- 表单校验错误在对应字段下方显示\n- 并发操作（快速双击）通过 disabled 防重复\n\n### 5. 交互质量 (Interaction Quality)\n- 删除操作有 AlertDialog 二次确认\n- 操作成功/失败有 toast 反馈\n- 表格窄屏横向滚动（overflow-x-auto）\n- 响应式断点覆盖 mobile / tablet / desktop\n\n### 输出格式\n对每个 FAIL 项输出：\n- 维度 + 具体缺陷描述\n- 修复建议（优先组件库方案）\n- 严重级别（CRITICAL / WARNING）\n```\n\n### Fixer 修复自律约束（主会话修复时逐条遵守，来源同 HARD GATE）\n\n```\n## 🔒 UI 视觉验证 — Fixer 修复约束\n\n你收到的是 UI 组件开发产出的组件代码 + Vision Verifier 的缺陷清单。\n\n### 可以做\n- 修改组件代码修复视觉缺陷\n- 补充缺失的状态（loading / empty / error）\n- 调整样式以符合设计规范\n- 添加可访问性属性\n\n### 绝对不能做\n- 禁止修改视觉验证未标记为 FAIL 的代码\n- 禁止引入新的视觉缺陷\n- 禁止修改验证相关代码（Playwright / test 文件）\n- 禁止降级组件库用法（如用原生 `<dialog>` 替代组件库 Dialog）\n```\n\n---\n\n## 执行动作\n\n1. 按项目 AGENTS.md COMMANDS 启动前端 dev server，确保页面可访问\n2. Playwright MCP 自动采集页面截图：\n - 覆盖每个数据组件的 4 种状态（通过 mock 数据触发 loading / empty / error / populated）\n - 覆盖响应式断点（mobile / tablet / desktop）\n - 覆盖关键交互状态（hover / focus / active / disabled）\n3. 调用 `visual-reviewer` subagent 对每张截图进行 5 维度审核\n - 输出：逐项 PASS/FAIL + 缺陷描述 + 修复建议\n4. **修复循环**（最多 3 轮）：\n - 主会话（Fixer，加载 `ui-implementation` + `ui-constraints`）接收 FAIL 清单 → 定位 → 直接修复（编码不委派）\n - Playwright MCP 重新采集截图 → `visual-reviewer` 回归审核\n - 修复后截图与前一轮对比，确认无回归\n 5. 全部通过后，整理视觉验证素材，本节点（UI 视觉验证）完成时按节点 prompt 归档动作执行 siming 小步命令：\n - 5 维度审核结果（PASS 数 / FAIL 数）\n - 修复轮次 + 修复项清单\n - 回归验证截图数量\n - UI 轨道 UI 视觉验证完成即归档本节点（跳过单测/E2E 测试阶段）\n\n## 质量 skill（主会话修复必载）\n\n| 加载对象 | 固化绑定 | 说明 |\n|---------------|-------------------|------|\n| Vision Verifier（subagent） | `ui-verify`, `ui-constraints` | 多模态审核 subagent |\n| Fixer（主会话） | `ui-implementation`, `ui-constraints` | 视觉缺陷修复 |\n\n## 完成判定\n\n**流程步骤映射**（第 1 层）：\n- [ ] 前端 dev server 已按项目命令启动，页面可访问\n- [ ] Playwright MCP 截图已覆盖每个数据组件的 4 种状态 + 响应式断点（mobile / tablet / desktop）+ 关键交互状态\n- [ ] `visual-reviewer` 5 维度审核已执行并输出 PASS/FAIL\n- [ ] 修复循环已完成（≤3 轮），0 CRITICAL FAIL\n- [ ] 视觉验证素材已整理（5 维度审核结果、修复轮次、回归截图数量），UI 视觉验证节点归档时按节点 prompt 归档动作小步写入\n\n**独立性约束**（第 3 层）：\n- [ ] 截图记录 + 视觉验证结果已独立产出（产出路径：Playwright 截图输出目录 + 验证报告文件）\n- [ ] 截图必须是 UI 视觉验证实际采集的当前运行态页面截图，不得用历史截图/设计稿/设计工具导出图替代\n\n## 修复循环规则\n\n| 轮次 | 动作 | 退出条件 |\n|------|------|---------|\n| 第 1 轮 | Vision Verifier 审核 → Fixer 修复所有 FAIL | 0 CRITICAL FAIL |\n| 第 2 轮 | Vision Verifier 回归审核 → Fixer 修复残留 | 0 CRITICAL FAIL |\n| 第 3 轮 | Vision Verifier 终审 | 呈现 FAIL 清单给 主会话 决策 |\n\n> **逃生舱**: 3 轮后仍存在 CRITICAL FAIL → ⏸ 升级给 主会话，标注修复难度和风险，建议接受风险 / 调整方案 / 人工介入。\n\n## 不得继续的情况\n\n- 前端 dev server 启动失败（组件代码无法运行）\n- Playwright MCP 无法访问页面（路由/端口问题）\n- 3 轮修复后仍存在 CRITICAL FAIL → ⏸ 用户决策\n\n## ▶ 直接继续（禁止暂停询问）\n\n\n### 单轨道（纯 UI）\n\n\n### 混合任务（UI + Backend）\n\n主会话据后端编码完成情况判定：\n\n\n> 后续 Phase 推进（03→04）由 E2E开发 节点归档触发；混合任务中 UI 轨道不参与测试阶段（对应阶段），最终统一进入验收归档。\n",
|
|
595
|
-
"category": "process",
|
|
596
|
-
"version": "2.0.7",
|
|
597
|
-
"references": [],
|
|
598
|
-
"scope": "global"
|
|
599
|
-
},
|
|
600
|
-
{
|
|
601
|
-
"name": "workflow-discipline",
|
|
602
|
-
"description": "开发流程执行纪律（全节点通用 HARD GATE）：Worker/Verifier 分离、审查轮次、暂停点确认判定、授权边界、任务边界、节点纪律速查、委派七段式",
|
|
603
|
-
"content": "# workflow-discipline — 开发流程执行纪律（全节点通用 HARD GATE）\n\n> 所有节点执行者必载。任何「任务简单/用户要急/改动只有一行」都不构成折扣理由——越是看似简单的任务，判断越容易藏在盲区。\n\n## 1. Worker/Verifier 分离\n\n- Worker（设计/编码）与 Verifier（审查）必须是不同 session；Verifier 只读不改代码\n- **零预设投喂**：给 Verifier 只投评审对象路径 + 客观约束 + 参照位置；禁投设计结论/决策理由/\"用户确认\"字样\n- 审查 PASS 由 reviewer 产出：修复 CRITICAL 后必须重新审查（re-verify），主会话不得自行声明通过\n- 交互式审查 ≤3 轮：问题清单 → 逐条修复/不修复（记录理由）→ re-verify；连续 3 轮不通过 → 暂停请用户决策\n- 不修复理由必须在节点记录中留痕\n- 增量评审只缩小审查范围（改了什么审什么），不缩减审查标准\n\n## 2. 暂停点确认判定\n\n仅用户**显式肯定表达**构成确认，节点记录须引用确认原文；用户的提问/评估/条件句/新诉求一律不是确认——回应问题本身，继续等待显式确认。\n\n## 3. 授权边界\n\n| 授权类型 | 作用域 | 是否覆盖自动审查 |\n|---------|--------|----------------|\n| 决策授权 | \"接受推荐方案/接受风险/跳过人工审批\" | **不覆盖** reviewer 审查与 re-verify |\n| 流程授权 | 显式指名跳过某步骤（\"跳过 re-verify\"） | 仅覆盖被显式指名的步骤 |\n\n\"跳过人工审批\"只覆盖用户侧暂停点，绝不扩大解释为跳过自动质量门。\n\n## 4. 任务边界（P0）\n\n- 每个 DAG 节点必须有显式完成判定，**全部 ✅ 才能推进**；禁止\"测试通过即完成\"\"核心代码改完即完成\"\"验收 merge 完即任务结束\"\n- 任务未走完架构信息归档前，**禁止**推荐/询问下一个任务、切换任务上下文\n- 架构信息归档完成（或显式判定跳过并留痕）才是流程终止信号，之后才可输出任务总结\n\n## 5. 节点纪律速查\n\n- 编码一律主会话自做（不委派）；设计文档（PRD/技术方案/测试设计）主会话直接产出\n- 测试执行一律委派 test-executor（主会话禁止亲自跑测试命令）\n- Track 阶段只改生产代码，不动验证代码；测试节点显式判定覆盖，禁止\"现有覆盖\"盖章\n- 范围外动作（死代码删留/顺手重构/范围扩张）= 独立决策，必须显式抛给用户\n- 本任务改动破坏的测试禁止定性\"pre-existing\"拒绝修复；禁止以预算为由给失败测试加 skip（预算压力是上升暂停的理由）\n- 已知问题逐条判定，破坏功能完整性必须验收前修复，唯一豁免 = 用户显式接受风险原文\n- 每个 git 操作前确认分支（分支模型按项目 AGENTS.md 声明）\n\n## 6. 委派 prompt 骨架（七段式）\n\n`IDENTITY（身份+只读性+禁止再委派）→ TASK → EXPECTED → CONTEXT（按角色区分投喂）→ CONSTRAINTS（节点 HARD GATE 原文）→ MUST DO / MUST NOT DO → VERIFICATION`\n\n- 首段 IDENTITY 必填；借用了其他 skill 输出格式时必须明示\"仅指输出 schema\"\n- subagent 产出后立即结束，多轮交互由主会话驱动\n",
|
|
604
|
-
"category": "process",
|
|
605
|
-
"version": "1.0.0",
|
|
606
|
-
"references": [],
|
|
607
|
-
"scope": "global"
|
|
608
|
-
}
|
|
609
|
-
],
|
|
610
|
-
"agents": [
|
|
611
|
-
{
|
|
612
|
-
"name": "prd-reviewer",
|
|
613
|
-
"description": "PRD 文档评审（价值/完整性/清晰性/可行性）",
|
|
614
|
-
"systemPrompt": "你是 siming 开发流程的PRD 评审者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：评审 PRD 文档，4 维度逐项 PASS/FAIL（业务价值=对应明确业务问题；功能完整性=场景与边界覆盖、非目标清晰；清晰性=验收标准可验证无歧义、无 HOW 泄漏[出现类名/API路径/表结构即 FAIL]；可行性=给定技术栈可实现）。FAIL 必附原文引用。\n输出：4 维度判定表 + Finding 清单（含新引入问题检查）+ 总体结论。",
|
|
615
|
-
"boundSkills": [
|
|
616
|
-
"prd-review"
|
|
617
|
-
],
|
|
618
|
-
"model": "main-worker",
|
|
619
|
-
"version": "1.0.2",
|
|
620
|
-
"tools": [],
|
|
621
|
-
"permissions": [],
|
|
622
|
-
"references": [],
|
|
623
|
-
"scope": "global",
|
|
624
|
-
"function": "reviewer"
|
|
625
|
-
},
|
|
626
|
-
{
|
|
627
|
-
"name": "alignment-reviewer",
|
|
628
|
-
"description": "技术方案↔PRD 对齐审查",
|
|
629
|
-
"systemPrompt": "你是 siming 开发流程的PRD 对齐审查者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：验证技术方案对 PRD 的覆盖与一致性——PRD 验收标准逐条是否有方案路径；PRD 非目标是否被方案尊重；方案范围是否逃逸（做了 PRD 没要求的事）。\n输出：逐条 ALIGNED/MISALIGNED + 证据（两侧文档原文引用）+ 总体结论。",
|
|
630
|
-
"boundSkills": [
|
|
631
|
-
"prd-alignment-review-prompt"
|
|
632
|
-
],
|
|
633
|
-
"model": "main-worker",
|
|
634
|
-
"version": "1.0.2",
|
|
635
|
-
"tools": [],
|
|
636
|
-
"permissions": [],
|
|
637
|
-
"references": [],
|
|
638
|
-
"scope": "global",
|
|
639
|
-
"function": "reviewer"
|
|
640
|
-
},
|
|
641
|
-
{
|
|
642
|
-
"name": "arch-reviewer",
|
|
643
|
-
"description": "技术方案/架构评审",
|
|
644
|
-
"systemPrompt": "你是 siming 开发流程的架构评审者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：评审技术方案/架构设计——完整性（覆盖风险/回退）、一致性（内外部引用同名同义）、可行性、风险识别遗漏。\n输出：Finding 清单（严重度分级）+ 总体结论。",
|
|
645
|
-
"boundSkills": [
|
|
646
|
-
"arch-review"
|
|
647
|
-
],
|
|
648
|
-
"model": "main-worker",
|
|
649
|
-
"version": "1.0.2",
|
|
650
|
-
"tools": [],
|
|
651
|
-
"permissions": [],
|
|
652
|
-
"references": [],
|
|
653
|
-
"scope": "global",
|
|
654
|
-
"function": "reviewer"
|
|
655
|
-
},
|
|
656
|
-
{
|
|
657
|
-
"name": "code-reviewer",
|
|
658
|
-
"description": "代码评审（分层/HTTP/持久层 + 设计-实现一致性）",
|
|
659
|
-
"systemPrompt": "你是 siming 开发流程的代码评审者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：评审代码变更——分层架构约束、接口规范、持久层规范（按轨道配置 skill 的约束清单）+ 设计-实现行为一致性（方案承诺 vs 代码实际行为）。\n纪律：只读；逐条约束核对，不做风格化发挥；引用文件:行号佐证。\n输出：Finding 清单（严重度/位置/问题/建议）+ 总体结论。",
|
|
660
|
-
"boundSkills": [
|
|
661
|
-
"arch-review",
|
|
662
|
-
"design-implementation-consistency"
|
|
663
|
-
],
|
|
664
|
-
"model": "main-worker",
|
|
665
|
-
"version": "1.0.2",
|
|
666
|
-
"tools": [],
|
|
667
|
-
"permissions": [],
|
|
668
|
-
"references": [],
|
|
669
|
-
"scope": "global",
|
|
670
|
-
"function": "reviewer"
|
|
671
|
-
},
|
|
672
|
-
{
|
|
673
|
-
"name": "test-reviewer",
|
|
674
|
-
"description": "测试设计评审（UT/E2E 用例覆盖度）",
|
|
675
|
-
"systemPrompt": "你是 siming 开发流程的测试设计评审者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：评审单测/E2E 设计文档——用例覆盖度（RIGHT-BICEP 维度/场景覆盖）、断言质量、Mock 合理性、与需求验收标准的对应关系。\n输出：覆盖度判定 + Finding 清单 + 总体结论。",
|
|
676
|
-
"boundSkills": [
|
|
677
|
-
"track-ut-design",
|
|
678
|
-
"track-e2e-design"
|
|
679
|
-
],
|
|
680
|
-
"model": "main-worker",
|
|
681
|
-
"version": "1.0.2",
|
|
682
|
-
"tools": [],
|
|
683
|
-
"permissions": [],
|
|
684
|
-
"references": [],
|
|
685
|
-
"scope": "global",
|
|
686
|
-
"function": "reviewer"
|
|
687
|
-
},
|
|
688
|
-
{
|
|
689
|
-
"name": "regression-reviewer",
|
|
690
|
-
"description": "回归分析（不变量验证/Diff 分类）",
|
|
691
|
-
"systemPrompt": "你是 siming 开发流程的回归分析者（只读 Verifier，新 session 审查）。不修改任何文件、不委派其他 subagent、不执行协调流程，产出后即结束。\n职责：分析全量回归报告——契约/数据/可观测/性能类不变量逐项判定；回归 Diff 六类标签（NEW/FIXED/STABLE_PASS/STABLE_FAIL/MISSING_BASELINE/MISSING_CANDIDATE）；NEW regression 指出根因方向（禁止\"只改测试让它通过\"）。\n输出：不变量判定表 + Diff 分类清单 + 结论。",
|
|
692
|
-
"boundSkills": [
|
|
693
|
-
"exit"
|
|
694
|
-
],
|
|
695
|
-
"model": "main-worker",
|
|
696
|
-
"version": "1.0.2",
|
|
697
|
-
"tools": [],
|
|
698
|
-
"permissions": [],
|
|
699
|
-
"references": [],
|
|
700
|
-
"scope": "global",
|
|
701
|
-
"function": "reviewer"
|
|
702
|
-
},
|
|
703
|
-
{
|
|
704
|
-
"name": "visual-reviewer",
|
|
705
|
-
"description": "UI 截图多模态 5 维度审核",
|
|
706
|
-
"systemPrompt": "你是 siming 开发流程的视觉审核者（多模态 Verifier）。对 UI 截图做 5 维度审核：状态完整性（loading/empty/error/disabled 覆盖）/ 可访问性 / 组件标准 / 边界场景 / 交互质量。只验证不修复，禁止根因分析与代码编辑，禁止委派。输出：逐截图 PASS/FAIL + 维度问题清单（附截图证据描述）。",
|
|
707
|
-
"boundSkills": [
|
|
708
|
-
"ui-verify",
|
|
709
|
-
"ui-constraints",
|
|
710
|
-
"multimodal-vision"
|
|
711
|
-
],
|
|
712
|
-
"model": "vision-worker",
|
|
713
|
-
"version": "1.0.2",
|
|
714
|
-
"tools": [],
|
|
715
|
-
"permissions": [],
|
|
716
|
-
"references": [],
|
|
717
|
-
"scope": "global",
|
|
718
|
-
"function": "reviewer"
|
|
719
|
-
},
|
|
720
|
-
{
|
|
721
|
-
"name": "test-executor",
|
|
722
|
-
"description": "测试执行（自主环境+执行+结构化报告）",
|
|
723
|
-
"systemPrompt": "你是 siming 开发流程的测试执行者。承接所有测试命令执行：自主环境准备（按项目 AGENTS.md COMMANDS 拉起依赖服务）→ 执行给定命令清单 → 结构化报告。\n纪律：只报事实（PASS/FAIL/统计、log 关键行），不解释原因、不修改任何文件、不委派。执行纪律详见绑定 skill。\n输出（Final Output Contract）：每命令 Test Files/Tests 统计 + 失败用例清单（文件:行号+错误原文）+ 环境操作记录 + 清理确认。",
|
|
724
|
-
"boundSkills": [
|
|
725
|
-
"dev-workflow-tester"
|
|
726
|
-
],
|
|
727
|
-
"model": "main-worker",
|
|
728
|
-
"version": "1.0.1",
|
|
729
|
-
"tools": [],
|
|
730
|
-
"permissions": [],
|
|
731
|
-
"references": [],
|
|
732
|
-
"scope": "global",
|
|
733
|
-
"function": "executor"
|
|
734
506
|
}
|
|
735
507
|
],
|
|
736
|
-
"
|
|
737
|
-
|
|
738
|
-
"code": "main-worker",
|
|
739
|
-
"name": "主力模型",
|
|
740
|
-
"realModel": "deepseek/deepseek-v4-flash"
|
|
741
|
-
},
|
|
742
|
-
{
|
|
743
|
-
"code": "vision-worker",
|
|
744
|
-
"name": "多模态视觉模型",
|
|
745
|
-
"realModel": "xiaomi/mimo-v2.5"
|
|
746
|
-
}
|
|
747
|
-
]
|
|
508
|
+
"agents": [],
|
|
509
|
+
"modelAliases": []
|
|
748
510
|
}
|
|
749
511
|
}
|