
helix
HelixHarness workflow plugin for Claude Code and Codex with commands and reusable skills
- version
- 1.0.0
- GitHub stars
- 444
Install
/plugin install helix@helixharness-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add didi/helixharness.
Contents
Discovered from sourceSkills 9
读取 README.md。研发阶段使用当前宿主 command projection 对应的公开命令契约;想法探索、异常调试和问题反馈可独立使用 README 中列出的辅助 Skill,不要求先创建需求。
方案头脑风暴
用户明确要求使用本 Skill 时,独立开展方案探索。无需先执行 Init、创建需求、开启统计或启动平台;不创建 feature、Spec/Tasks 或 eval-log,不启动研发命令。
适合触发的场景:
- requirements are still fuzzy
- more than one design is plausible
- the user asks for options, tradeoffs, or recommendations
- a risky change needs alternatives before execution
如果执行已经明确开始,就不要再用它,除非你确实需要重新打开方案空间。
目标
先扩展选项空间,再收敛到一个站得住脚的推荐路径。
工作流
-
定义这次要做的决策。 写清楚:
- the problem to solve
- hard constraints
- what would make an option unacceptable
-
生成 2-4 个真实可实施的选项。 每个选项都必须能落地,不要只是口号。
-
从实务维度比较方案。 优先比较:
- complexity
- delivery speed
- risk of regression
- migration cost
- operability
- fit with existing architecture
-
暴露未知项。 明确指出哪些事情必须在执行前确认。
-
给出一个推荐方案。 解释为什么它是“当前最适合”的,而不是抽象上最优。
独立使用边界
- 由用户独立调用,不作为研发命令的内部步骤
- 输出要简洁,并且面向决策
- 如果代码库上下文重要,先读相关文件,再提方案
- 方向确认后交付讨论摘要,由用户决定是否将其作为后续需求的输入;本 Skill 不自动进入计划或实现流程
输出格式
- Problem:
- Constraints:
- Option A:
- Option B:
- Option C: (optional)
- Recommendation:
- Open questions:
约束
- 如果明显只有一条路,不要硬凑很多选项
- 不要默认推荐重写
- 不要用模糊语言掩盖关键 tradeoff
- 一旦方向清楚,就停止 brainstorm,进入下一步
HelixHarness Code Review
评审 <fixed-point> 与 HEAD 之间的代码变化,并保持两个独立评审轴:
- Standards:代码是否遵守仓库已经记录的工程规范?
- Spec:代码是否忠实实现当前需求 Spec?
两个轴使用并行、上下文隔离的只读 sub-agent,最后并排展示结果,不合并或跨轴重排 finding。
流程
1. 固定比较点和评审范围
先执行 workflow.py ... review-scope --feature "{feature}",取得 review_head、
apply_baseline_head、empty_tree、changed_paths、excluded_preexisting_paths 和 review_scope_sha256。
执行前工作区基线缺失、范围重叠或脚本拒绝当前状态时,直接返回脚本的 DECISION_NEEDED 或 blocker,
不自行重建范围。只从 changed_paths 构造 staged、unstaged 和本任务新增 untracked 文件的 working-tree delta;
excluded_preexisting_paths 只记录排除事实,不附带内容。
apply_baseline_head=empty_tree时,使用回执中的空树作为<fixed-point>。若review_head=empty_tree, 当前没有已提交差异或 commit list,不调用依赖 commit 的git log/git merge-base。 若 Review 前已有首次提交,使用git diff <fixed-point> <review_head>(两个参数),从差异中排除excluded_preexisting_paths、本需求的 spec/tasks/evidence、私有状态和统计目录, 使用git log <review_head> --oneline记录当前历史。保留真实review_head,不创建或猜测提交。- 其他情况仅评审当前未提交增量时,自动使用回执中的
review_head作为<fixed-point>。只有需要纳入HEAD之前的已提交改动,或任务变化只存在于提交历史中时,才请用户指定 commit、branch 或 tag。 解析为完整 commit ID,再用git diff <fixed-point>...<review_head>和git log <fixed-point>..<review_head> --oneline收集已提交证据。
冻结同一份 Review Bundle,供两个 Reviewer 使用:
- 当前预绑定 Host Context:准确的
plugin_root、canonical_host_id与当前 Host Kit 路径; - 完整 fixed-point 和
review_head(有提交时是 commit ID,无首次提交时是空树 ID); - committed diff、commit list 和 working-tree delta;
review_scope_sha256、changed_paths与excluded_preexisting_paths;- 当前 HelixHarness
spec.md; - Standards 来源文件列表。
Review Bundle 合计没有代码变化时默认停止。唯一例外是经 Workspace 合同验证的只读 RepoJob:
- 父 Coordinator 提供的当前
workspace-plan --command apply必须包含本 job,且mode=read、 repo key、ownership_root 和 Single workflow 与当前仓完全一致;不能仅凭聊天声明或 Spec 中的 “只读”文字启用例外。缺少受控 Workspace root / RepoJob 时停止,不扫描目录猜测来源。 - 同一 Workspace 的
workspace-validate --stage apply必须通过,其spec_receipt_sha256与 本仓 Spec 的workspace_contract_sha256一致;把实际命令输出、原始 RepoJob 与父概要设计附入 Bundle。 - 本次真实的只读检查命令、结果及业务文件相对 Apply 基线未变的证据必须附入 Bundle。
changed_paths=[]不能替代契约检查,也不能用旧报告或其他仓的成功声称本仓已验证。
满足这些条件时仍执行下面的两个独立原生评审,不豁免或预填 APPROVE:Standards 轴核查写域、
业务文件不变性及验证是否符合仓库规范;Spec 轴逐条核查本仓只读契约验收是否有真实证据。
两轴明确记录这是 Workspace read job 的契约验收、没有业务代码改动,不虚构 diff 或行为实现。
普通 Single Apply 和 mode=write RepoJob 的空代码变化仍停止。所有原有收据、Review Scope
及 Archive 门禁保持有效。评审期间不写工作区;review-scope 生成的 review-state.json
留给 Archive 复核范围。
2. 定位 Spec
Spec 固定为当前 feature 的 docs/specs/active/{feature}/spec.md。文件缺失、不可读或与当前 HelixHarness feature 不一致时停止,不使用聊天摘要代替。
评审时的 Evidence 边界
Apply 在双轴 Review 完成后生成本轮 verify-report.md。恢复 Apply 或执行 Bug Fix 时,已有报告可能仍是上轮 Evidence,只供诊断;不得要求它提前包含尚未完成的本轮评审结论,也不得仅因旧报告尚未刷新就阻断当前代码 Review。旧报告不能作为本轮已验证或已获 APPROVE 的证明;本轮实际缺失的测试、错误行为或虚构证据仍须报告。
涉及收据一致性时,由父流程把当前 "{plugin_root}/scripts/workflow.py" validate-tasks 返回的 Spec/Tasks 规范化收据及对应阶段校验结果附入 Bundle;Reviewer 需要复核时只调用同一准确脚本路径。不得用 sha256sum、shasum 或自行对整份 Markdown 求哈希替代:文件字节摘要与合同收据不是同一口径,状态推进本身不代表合同变更。向两个 Reviewer 的 prompt 都传递这一边界。Host Context 或校验结果缺失时向父流程报告缺失输入,不扫描用户目录、临时目录或 plugin cache 寻找另一个脚本/版本。
本轮 Evidence 的生成、修订与当前收据绑定仍由 Apply 在 Review 后完成,并通过 archive-preflight;不得复用无效的旧 APPROVE、修改收据算法或跳过最终证据门禁。
3. 定位 Standards
使用 HelixHarness Apply 已确定的仓库入口、当前 Spec 命中的 docs/harness/ 叶子、docs/hooks/cr-checklist.md(若存在)及其他已加载工程规范。仓库明确规范优先于下面的代码异味基线;跳过工具已经确定性检查的内容。
Standards 轴始终附带 Fowler 代码异味基线。每一项都只是需要结合上下文判断的启发式建议,不是仓库硬规则:
- Mysterious Name:名称不能揭示用途时重命名;无法诚实命名通常说明设计仍含混。
- Duplicated Code:相同逻辑形状出现在多个 hunk 或文件时,提取共享实现。
- Feature Envy:逻辑主要操作另一对象的数据时,把行为移到数据所有者附近。
- Data Clumps:同一组字段或参数反复同行时,形成一个明确类型。
- Primitive Obsession:原始字符串或数值承载领域概念时,使用小型领域类型。
- Repeated Switches:相同类型分支在多处重复时,收敛为一个映射或多态实现。
- Shotgun Surgery:一个逻辑变化要求分散修改许多位置时,收拢共同变化点。
- Divergent Change:一个模块因多个无关原因变化时,按职责拆分。
- Speculative Generality:当前 Spec 不需要的抽象、参数或 hook 应删除或内联。
- Message Chains:调用者依赖长导航链时,把导航隐藏在稳定接口后。
- Middle Man:只做转发的中间层应删除,让调用者直接访问真实能力。
- Refused Bequest:子类忽略大部分继承合同时,改用组合。
测试代码分流
测试代码仍属于 changed_paths 和完整 Review Bundle;不得排除测试文件,也不得只审生产代码。Standards Reviewer 先区分生产代码与测试代码,再对测试代码执行下面的测试代码噪音过滤:
- 优先检查测试有效性:错误或缺失的断言、会造成假通过的 mock/fixture、绕过真实行为的测试机制、flaky 风险、共享可变状态、执行顺序依赖,以及仓库明确测试规范违反。证据充分且无需用户决策时,finding disposition 和 Standards 轴 verdict 都必须是
MUST_FIX;需要新的产品行为、测试策略或不可逆决策时才使用DECISION_NEEDED。这类 correctness 或硬规范问题不得输出ADVISORY、不得降级成纯风格建议。 - 只有存在具体、显著维护风险时才生成测试代码
ADVISORY,例如大段复杂 fixture 在多个测试文件复制且已经可能漂移、测试严重绑定私有实现导致正常重构大面积破坏,或测试数据构造复杂到掩盖被验证行为。finding 必须写出具体风险,不能只说“可以抽取”。 - 普通测试字面量、输入值与预期值分别写出的相同值、单个测试类内的简短重复,以及少量 Given/When/Then setup 不生成
ADVISORY;不得仅以 Primitive Obsession 或 Duplicated Code 名义报告这些内容。 - 为保持 test oracle 独立,不得因为消除重复而共享同一个常量,也不得建议让预期断言引用输入 fixture 或被测生产代码的常量。没有测试有效性、硬规范或显著维护风险时,完全省略该 test-only finding。
4. 并行执行两个评审轴
Standards Reviewer 与 Spec Reviewer 是写入两个 sub-agent prompt 的评审角色,不是固定的 agent type。必须使用当前运行环境原生可用的 sub-agent 能力并行创建两个独立实例;不得把 Reviewer 角色名臆造为专用 agent type。不得仅因某个专用 type 不存在就判定并行独立评审不可用或返回 BLOCKED:lite_review_parallel_unavailable。
同时启动两个上下文隔离、只读的 sub-agent,并向它们提供同一份冻结 Review Bundle。不得由 Implementer 角色扮演 Reviewer,也不得顺序复用同一上下文。运行环境无法完成并行独立评审时返回 BLOCKED:lite_review_parallel_unavailable。
向 Standards sub-agent 提供完整代码变化、commit list、Standards 来源和代码异味基线,要求它按文件或 hunk 报告:
- 违反仓库明确规范的位置,并引用规范文件和规则;
- 发现的代码异味,注明它是 judgement call 并引用代码 hunk;
- 仓库规范与异味基线冲突时,以仓库规范为准;
- 先区分生产代码与测试代码,对测试代码执行上述测试代码噪音过滤;
- 跳过工具已经执行的检查。
向 Spec sub-agent 提供相同代码变化、commit list 和完整 Spec,要求它报告:
- Spec 要求但缺失或只部分实现的行为;
- Spec 未要求的行为或 scope creep;
- 看似实现但实现机制错误的要求;
- Spec 的 Testing Decisions 声明
视觉还原验收: 是时检查 d2c 证据链是否兑现:hard violation = 0、叠图存在、豁免记录真实;声明了但缺证据按 MUST_FIX 报告,未声明的项目不审视觉还原。
每条 finding 都引用具体代码证据;Spec finding 同时引用对应 Spec 内容。两个报告都保持简洁,中文控制在约 800 字以内。
5. 分轴汇总
分别在 Standards 与 Spec 标题下原样或轻度清理两个报告。不得合并或跨轴重排 finding,也不得生成跨轴统一严重度。
最后输出一行分轴摘要:Standards: <finding 数与最严重项>; Spec: <finding 数与最严重项>。不得选出跨轴单一赢家。
6. HelixHarness 结果流转
finding disposition 只有 ADVISORY、MUST_FIX、DECISION_NEEDED;轴 verdict 只有 APPROVE、MUST_FIX、DECISION_NEEDED。ADVISORY 是 finding disposition,不是轴 verdict;它表示有具体证据和可选改进动作,但不影响当前 Spec 正确交付。Fowler 代码异味继续作为 Standards 报告中的非阻断 judgement call;Spec 轴的非阻断 Out of Scope 说明在确有可选改进时也归为 Advisory。Standards 使用稳定 ID STD-A01...,Spec 使用 SPEC-A01...,每条都给出证据、不阻断原因和可选动作。只含 Advisory 的轴仍为 APPROVE。BLOCKED 只表示 Apply 无法继续执行,不是 Reviewer verdict。
MUST_FIX:Implementer 定向修复,运行覆盖测试和仓库完整测试套件,再以同一 fixed point 冻结新 Review Bundle 并重新执行完整双轴 Review。修复可能引入新问题,不得只复审原 finding;不设置固定 Review 轮次上限,并累计must_fix_rounds。BLOCKED:lite_review_no_progress:同一阻断 finding 以相同轴、规则或 Spec 要求、代码路径和失败机制重复出现,且最新代码和验证没有改善时停止。不得只因轮次较多而阻断。DECISION_NEEDED:停止并交回 HelixHarness Apply,不在旧 Review Bundle 上继续。- 两轴都没有 Must Fix 或 Decision Needed 时整体
APPROVE。
Reviewer 不得把 correctness、Spec 明确要求、当前任务引入的实际 scope creep、安全问题或仓库硬规范违反降级为 Advisory;这些必须按证据归为 MUST_FIX 或 DECISION_NEEDED。
输出 fixed-point、Review HEAD、review_scope_sha256、两个分轴报告、稳定 Advisory ID 和 verdict,交回 HelixHarness Apply 生成 Evidence。Reviewer 不修改代码、不生成 Evidence、不询问用户,也不自行启动修复循环。
为什么分成两个轴
一个变化可能通过其中一个轴,却在另一个轴失败:
- 完全遵守工程规范,但实现了错误需求:Standards 通过,Spec 失败。
- 完整实现需求,但违反仓库规范:Spec 通过,Standards 失败。
分开报告可以避免一个轴的问题掩盖另一个轴。
工作流概览
flowchart TD
A[初始化<br/>d-d2c --init --scope] --> B[拉 DSL<br/>fetch-mastergo-dsl]
B --> C[写代码<br/>generate.md + materials.md]
C --> D{迭代循环}
D --> E[截图<br/>capture-page]
E --> F[几何对比<br/>geometry-check]
F --> G[垂直布局<br/>vertical-check]
G --> H[渲染检查<br/>render-check]
H --> I[叠图<br/>diff-overlay]
I --> J{满意?}
J -->|否| C
J -->|是| K[评测<br/>fidelity-report]
K --> L[完成]
A -.-> M[存量项目? → brownfield.md]
D -.-> N[快速迭代? → --overlay-only]
规则文件索引: generate · materials · design-crop · preview · component · update-page · brownfield
d-d2c 工作流
d-d2c 用于按 MasterGo 设计页链接拉取 DSL,再基于 Layer.md(布局树)+ dom.md(DOM/CSS)+ styles.md(样式规格表) + 设计稿实现页面还原。
鉴权页面 / 需要登录态
注入 Session(cookie + localStorage)
--session-state 接受 JSON 字符串,在 Puppeteer 导航前注入:
# 注入 cookie
node d2c-capture-page.cjs --url http://localhost:8080/demo-page \
--session-state '{"cookies":[{"name":"token","value":"abc123","domain":"localhost"}]}'
# 注入 localStorage
node d2c-capture-page.cjs --url http://localhost:8080/demo-page \
--session-state '{"localStorage":{"role":"agent","stage":"4"}}'
也可通过环境变量 D2C_SESSION_STATE 传入。
JSON 结构:
cookies:[{name, value, domain?, path?}]— 通过page.setCookie()注入localStorage:{key: value}— 通过evaluateOnNewDocument注入origin: 可选,指定 localStorage 绑定的 origin
注入 Mock 数据
使用 --mock 注入 JSON 到 window.__MOCK__,或 --mock-script 执行自定义 JS:
# 注入 JSON
node d2c-capture-page.cjs --url http://localhost:8080/demo-page \
--mock '{"userInfo":{"id":1,"name":"test"}}'
# 执行 mock 脚本
node d2c-capture-page.cjs --url http://localhost:8080/demo-page \
--mock-script ./mock.js
Mock 通过 page.evaluateOnNewDocument 在 page.goto 之前注入,抢在所有页面脚本执行前生效。对"挂载即 fetch"的 Vue App,API 拦截、全局 Promise 覆写等 mock 策略在首屏请求发出前已就位。
🔍 Agent 主动检测 & 自动 Mock(⛔ 截图后必须执行)
每轮截图完成后,Agent 必须检查目标组件是否渲染了真实业务数据。不满足时自动生成并注入 mock 数据,无需用户介入。
检测标准(截图后立即判断):
| 信号 | 判断 | 动作 |
|---|---|---|
| 目标组件 DOM 存在但内容为空(骨架屏/加载中/占位符) | 数据未到位 | 进入 mock 生成流程 |
目标组件 v-if/v-show 条件不满足,整个组件不渲染 | 依赖数据缺失 | 进入 mock 生成流程 |
| 列表为空、文案显示默认值/空字符串 | API 未返回数据 | 进入 mock 生成流程 |
| 页面重定向到登录/错误页 | 鉴权问题,非数据问题 | 走 session-state / CDP 路径 |
Mock 生成流程(Agent 自动执行,不询问用户):
-
读取组件源码:分析目标
.vue的<script>部分,识别:props定义(需要父组件传入的数据结构)computed中从 props/store 派生的字段v-if/v-for的驱动条件- API 调用(axios/fetch/request 等)及返回数据结构
-
向上追溯数据源:props 是父组件传的 → 读父组件 → 追溯到最终数据源:
- API 响应(看接口返回的字段)
- Store state(Vuex/Pinia/Redux)
- 路由参数
-
生成 mock 脚本(写入
d-d2c/temp/<page>/mock.js,不残留到业务 diff):// 策略 A(优先):在页面挂载前拦截数据源 // 覆盖 window.fetch / XMLHttpRequest,对匹配 URL 返回 mock 数据 const MOCK_DATA = { /* 根据组件依赖构造的完整数据 */ } const origFetch = window.fetch window.fetch = function(url, ...args) { if (url.includes('/api/xxx')) { return Promise.resolve(new Response(JSON.stringify(MOCK_DATA))) } return origFetch.call(this, url, ...args) } // 策略 B(备选):如果项目有全局 store,直接注入 // 在 app 挂载后通过 __vue_app__ 或 store instance 注入 -
重新截图:带上
--mock-script d-d2c/temp/<page>/mock.js。 -
验证 mock 完整性(⛔ 硬门禁,必须逐条执行,不可仅凭"组件挂载"判定通过):
核心原则:"组件 DOM 存在" ≠ "组件渲染完整"。必须检查组件内部的条件块是否全部渲染。
5a. 对照 template 列出条件块: 重新读取目标组件的
<template>,提取所有v-if/v-show/v-for控制的子树,记录每个条件块的驱动表达式和预期内容。例如:v-if="hasUserInfo" → .user-detail(姓名+联系方式) v-if="cardConfig" → 整卡 v-for="item in list" → .list-item × N5b. 在浏览器中逐条检查(用
page.evaluate):检查项 方法 通过标准 v-if块document.querySelector(选择器)元素存在 v-for列表document.querySelectorAll(选择器).length> 0关键文本 .textContent.trim()非空、非占位符(如"加载中…"/"—"/空字符串) 条件块全部通过 对比模板 vs 实际 DOM 100% 命中 5c. 不符时继续迭代:
- 任一条件块未渲染 → 回到步骤 1,重新分析该块的数据依赖
- 特别关注:数据在 store/API 中存在但 computed 返回
undefined→ 可能是数据归一化(normalize)函数改了字段路径,或 prop 初始为空对象导致的 Vue 响应式边界情况 → 调整 mock 数据结构,把字段放到 normalize 函数实际读取的位置 - 修改 mock 脚本 → 重新截图 → 重新验证,直到所有条件块通过或已达 3 轮上限
5d. 截图后 geometry/render check 正常执行。 条件块补齐后 DSL 节点匹配率应明显提升。
⚠️ 关键约束:
- mock 脚本写入
d-d2c/temp/目录,cleanup 时一并清除,禁止残留到业务源码 - 不要为了 mock 去修改业务代码(路由守卫、bootstrap、Vue 组件等)
- 如果项目已有现成的 mock 机制(如 MSW/vite-plugin-mock),优先用项目自带方案
- mock 数据的字段和类型必须与组件源码中的实际使用一致
连接已有浏览器(CDP endpoint)
如果 Chrome 已打开并登录,通过 CDP 协议连接:
# 1. 启动 Chrome 时开启远程调试
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222
# 2. 获取 WebSocket endpoint;直接读取返回的 JSON 并提取 webSocketDebuggerUrl,
# 不依赖额外 JSON CLI
curl -fsS http://127.0.0.1:9222/json/version
# 3. 传入各脚本
node d2c-capture-page.cjs --cdp-endpoint "ws://127.0.0.1:9222/devtools/browser/..."
--cdp-endpoint 在 capture / geometry / vertical / render 四个脚本中均支持。连接已有浏览器可绕过鉴权,适用于无法自动化登录的场景。
完整执行契约
用户调用 d-d2c --create-page、d-d2c --update-page 或 d-d2c --component,即授权执行包含本地 dev server、浏览器物料、联合闸和 fidelity 在内的完整 workflow。阶段 0/1/2/3 的完成都不是任务终点,禁止询问用户是否继续。
Claude Code 会通过 skill-scoped Stop Hook 读取 checkpoint 状态,并通过 PreToolUse:AskUserQuestion Hook 拦截非法中途提问:只允许在阶段 6 完成、browser handoff 等用户操作、阶段 4 等交互式效果决策、用户取消或有证据的外部输入阻塞时结束当前 turn;其它状态会由确定性脚本拒绝提前停止或询问。--bare / --safe-mode 会禁用 Claude hooks,不属于可保证完整性的直接执行环境。
用户输入
- MasterGo 设计页链接(含
file/layer_id等参数,或可解析到 fileId/layerId 的/goto/链接)。 - 设计图原图(用于对照还原)。
- 业务线(可选):使用
业务线<name>格式,<name>为配置中已声明的转发业务标识。用户未提供时不走转发。
命令参考(均可附 + [Image #1] 传设计原图用于贴图比对,也可附 业务线<name>):
d-d2c --create-page <MasterGo 设计页链接> 业务线<name>:新建整页。默认入口,沿用当前整页还原与自检流程。d-d2c --update-page <页面 vue 的相对路径> <MasterGo 设计页链接> 业务线<name>:更新已有页面或其中一块内容。额外读取rules/d-d2c-update-page.md。d-d2c --component <组件层 MasterGo 设计链接> 业务线<name>:开发组件、弹层、卡片等子树。额外读取rules/d-d2c-component.md。
未显式传子命令时,先按用户意图判定:
| 信号 | 流程 |
|---|---|
| 新建页面、整页、完整画板 | page / create,走当前默认整页流程 |
| 更新已有页、在某个 Vue 页面里改一块、已有页面新增区块 | page / update,先读 rules/d-d2c-update-page.md |
| 组件、弹层、卡片、独立模块、组件级 MasterGo 选层 | component,先读 rules/d-d2c-component.md |
| 判定不明确 | 先向用户确认是新建整页、更新已有页,还是组件级任务 |
组件模式和已有页模式只是流程覆盖层:除对应规则文件列出的差异外,仍遵循当前分支既有的 DSL/filter、代码还原、物料生成、geometry/vertical/render 自检、phase2 联合前置闸和 fidelity 评测流程;不得因为切换模式而改写通用还原逻辑。
DSL 前置依赖(geometry / render / overlay 强制检查)
geometry-check、render-check、diff-overlay 强依赖 DSL 数据。在执行这些检查前,必须先确认 DSL 文件已拉取:
- 检查目标目录下是否存在
dsl_full.json/dsl_layout_marked.json/dom.md/styles.md - 若缺失 → 自动拉取 DSL:
- 优先:使用 MasterGo MCP 直接拉取 DSL 数据(
mcp__mastergo-magic-mcp__mcp__getDsl或getDesignSections) - Fallback: 调用
fetch-mastergo-dsl.cjs --mg-url '<MasterGo链接>' --out d2c/temp/<page>/dsl_full.json
- 优先:使用 MasterGo MCP 直接拉取 DSL 数据(
- DSL 就绪后,再执行 geometry / render / overlay
禁止在 DSL 缺失时跳过 geometry check 或报"需要配置 token"。 这是 d2c 工作流内部的职责,应由 d2c 自动处理,不应向外部暴露。
DSL 与设计图
业务线与转发端点(可选,自建)
默认不连接任何转发端点。本 skill 的默认取数路径是「本机令牌直连 MasterGo」或「经 mastergo-magic-mcp 拉取」;只有当你自建了一个持有 MasterGo 凭证的转发服务、并希望在多人之间共享该凭证时,才需要本节内容。该服务的接口契约不在本文档定义范围,由自建方自行对齐。
业务线为可选输入,统一使用 业务线<name> 格式。可用值由 config/transponder-routes.json 的 businessLines 声明,aliases 可配置别名到规范值的映射(未配置别名时按原值透传)。转发地址由同文件的 transponderUrl 指定,也可用环境变量 HELIXHARNESS_FRONTEND_ASSET_URL 覆盖;配置文件路径可用 HELIXHARNESS_FRONTEND_ROUTES_FILE 覆盖。
- 用户显式指定业务线时,拉取命令必须附加
--business-line <name>。脚本先尝试本地 token 直连,无 token 或直连失败才走转发。 - 用户未指定业务线时,禁止自动补任何默认值,也不得启用转发。
- 转发地址只能从 Skill 内的配置读取,不要要求用户提供或覆盖转发地址。
--no-transponder可显式关闭转发。
node $HELIXHARNESS_PLUGIN/skills/d-d2c/scripts/fetch-mastergo-dsl.cjs \
--business-line '<name>' \
--mg-url '<MasterGo链接>' \
--out d-d2c/temp/<page-dir>/dsl_full.json
MasterGo 设计页链接 + 导出原图 d-d2c/temp/<page-dir>/image-source.png。从 MasterGo 当前设计文件的分享或复制链接入口获取链接,并确认链接指向目标页面或节点(DSL 正文须脚本/MCP 落盘,禁止在对话里编造)。
拉取 DSL → filter → 写 Vue 的命令、必读产物、D2C 复杂矢量、省 token 与图标约束,一律以 rules/d-d2c-generate.md 为准(alwaysApply),本文件不重复展开。
宿主布局与叠图:filter-dsl 会用原始 DSL 自动判定 immersive-overlay / stacked-host。前者删除原生控件但保留顶部 H5 空间,后者才按宿主底边平移/裁切;--design-crop-top 必须使用栅格 designCropTopRaster。详见 rules/d-d2c-design-crop.md。
易混参数
--scope
本 skill 有两个同名但不同义的 --scope,取值形态和生效范围都不一样,不要混用:
| 使用场景 | 取值 | 含义 |
|---|---|---|
初始化 / 存量接入,限定本次扫描范围(d-d2c --init --scope …) | 业务目录路径,如 client/views/<your-module> | 只在该目录内扫描并生成映射文档。这是约定参数(见 rules/d-d2c-mapping-code-sort.md),不由脚本解析 |
| geometry / vertical / render / design-opacity / diff-overlay 等检查脚本 | DSL layoutMark,多个用逗号分隔 | 量化比对只针对该 DSL 子树。这些是脚本的真实参数,取值来自 dsl_layout_marked.json |
判断口诀:值以 / 开头或指向目录 → 扫描范围;值是 layoutMark → 检查范围。
执行入口
- 新建整页(默认 /
--create-page):先读rules/d-d2c-preview.md,再按$HELIXHARNESS_PLUGIN/skills/d-d2c/rules/d-d2c-workflow-self-check.md串行执行全流程,并按d-d2c-generate.md的既有规则落页面和路由。 - 更新已有页(
--update-page <页面 vue 的相对路径>):只读rules/d-d2c-update-page.md作为模式覆盖层,不读取rules/d-d2c-preview.md;目标写入指定 Vue,复用已有路由,真实页不可达时进入 browser handoff,最终验收按真实整页。 - 组件/弹层/卡片(
--component):先读rules/d-d2c-component.md与rules/d-d2c-preview.md,再执行同一套自检流程;产物目录使用d-d2c/temp/component/<name>/,不新增对外业务路由。 - 复杂度分流:
filter-dsl自动产出complexity-plan.json;verdict=complex的页面禁止整页一把梭,按rules/d-d2c-complex-split.md拆解为组件串行小闭环后再拼装。 - 完整自检评测流程强依赖
d2c-fidelity-evaluator;初始化阶段完整读取本插件已捆绑的skills/d2c-fidelity-evaluator/SKILL.md,资源缺失则停止流程并提示修复插件安装。
阶段 1 必须先用 d2c-runtime-health-check.cjs 证明真实项目构建链编译成功且 SPA 已挂载;HTTP 200/端口存活不算证据,源码修改会让旧证据失效。编译、runtime、Cannot GET 或空 SPA 都由 executor 自动修复,禁止询问用户或进入 browser handoff。
已有页只有在运行健康的真实路由重试后仍被业务 flow 重定向时,才按 d-d2c-update-page.md 创建 browser-handoff.json:交互环境启动托管可见 Chrome 并请用户进入目标页;headless/loop 环境输出 EXECUTOR_BLOCKED reason=user-browser-handoff-required page-dir=<page-dir>,由外层恢复同一 run。用户页通过验证后,截图与三项 DOM 检查必须复用同一 CDP tab。
其他规则与脚本均从技能目录内的 $HELIXHARNESS_PLUGIN/skills/d-d2c/ 读取(路径以 rules/、scripts/ 下实际文件为准)。
结构化运行日志(
d2c-run.jsonl/d2c-run-summary.json)仅服务于外层 d2c-eval-loop 的归因,受环境变量D2C_EVAL_LOOP门禁,默认关闭;正常使用 d-d2c 不会产生这些日志文件。
D2C Fidelity Evaluator
Purpose
Score how faithfully a code-generated page restores its design source, then produce an optimization-oriented report that another D2C skill can use to improve the implementation in the next pass.
This skill evaluates visible output fidelity. Source code is used to locate likely causes and suggest implementation changes; source quality is not scored unless it creates visible design mismatch.
Inputs
Expect these inputs from the user or surrounding task context:
- Design screenshot: the original design image.
- Design DSL: structured design data for the same page or frame.
- Implementation source: code files, snippets, or repo paths for the generated page.
- Rendered screenshot: screenshot of the implementation result.
- Overlay screenshot: optional but preferred; a transparent design-over-render overlay image.
If the overlay is available, use it primarily to diagnose layout, size, edge, and alignment drift. Do not use the overlay as the main evidence for color or typography, because the colors are blended.
For v1, assume the screenshots are comparable and the page has rendered successfully. Do not perform viewport, DPR, asset-loading, or blank-page comparability checks unless the user explicitly asks for that.
Host Chrome Boundary
App, WebView, and mini-program container chrome is not part of the page fidelity target. Do not score system status bars, WebView title bars, mini-program capsule controls, native back controls, or bottom gesture bars as implementation omissions or extra elements.
If the design screenshot includes host chrome but the rendered screenshot represents only the H5/business page, evaluate the business page content boundary. When the surrounding workflow provides design_crop_top, treat that top crop as the intended material alignment and do not deduct for the removed host chrome.
If the overlay appears vertically shifted because host chrome was not cropped from the design side, report this as a material alignment issue before assigning implementation deductions. In that case, avoid turning the whole-page offset caused by host chrome into code optimization advice such as adding fake status bars or drawing mini-program capsules.
DSL-Only Mode
When no design screenshot (image-source.png) is available, the evaluator operates in dsl-only mode:
- Activation: Set
D2C_FIDELITY_MODE=dsl-onlyor pass--mode dsl-only - What changes:
- Pixel-level overlay comparison is skipped
- Scoring based on geometry-diff.json (40%) + render-diff.json (40%) + vertical-diff.json (20%)
- Report marked with "基于 DSL 评测(无设计原图)"
- What stays: All DSL-based checks (text, font, spacing, color, layout) still run
Workflow
- Inventory the provided inputs and identify the design frame/page being evaluated.
- Read the design DSL enough to understand the intended element hierarchy, text, bounds, style tokens, and key node IDs.
- Inspect the design screenshot, rendered screenshot, and overlay screenshot if present.
- Compare the implementation against the design across the four scoring dimensions in
references/scoring-rubric.md. - Calculate the overall fidelity score as a weighted average.
- Produce a report using
references/report-schema.md. - Write the complete Markdown report to the target workspace root's
d2c/temp/d2c-fidelity-evaluator-report/folder. Create the folder if needed. - Sort findings by optimization value, not by visual narration order. The highest-priority items should be the ones most likely to raise the next score.
Report File
Every evaluation must create a new Markdown report file on disk.
Determine the target workspace root as follows:
- If the user provides a code file path inside a project, use that project's repository root when it can be detected.
- Otherwise use the current working directory for the evaluation task.
Save reports under:
<target-workspace-root>/d2c/temp/d2c-fidelity-evaluator-report/
Use this filename pattern:
d2c-fidelity-evaluator-r{round}.md
Round selection:
- If the user provides an explicit round number, use it.
- Otherwise, if a screenshot or branch/file name contains a clear round marker such as
r6, use that number. - Otherwise, inspect existing
d2c/temp/d2c-fidelity-evaluator-report/d2c-fidelity-evaluator-r*.mdfiles and use the next integer round. - Never overwrite an existing report. If the selected round file already exists, append
-run-{n}before.md, wherenis the next available integer.
The chat response should include the report path and a concise score summary. The full Markdown report file should include both the human-readable report and the JSON report block.
Scoring Dimensions
Use these weights:
- Layout structure: 40%
- Visual style: 25%
- Content and assets: 15%
- Perceptual similarity: 20%
Overall score:
overallScore =
layoutStructure * 0.40 +
visualStyle * 0.25 +
contentAssets * 0.15 +
perceptualSimilarity * 0.20
Scores are percentages from 0 to 100. Round the final score to the nearest whole number unless precise measurements justify one decimal place.
Report Requirements
The report must be useful as input to a subsequent D2C optimization skill. Avoid generic comments such as "spacing is off" or "style differs". Each important finding must include:
- The affected target element or region.
- The scoring dimension.
- Severity and deduction.
- Expected design behavior.
- Actual rendered behavior.
- Evidence from screenshot, overlay, or DSL.
- A concrete suggested change.
- Acceptance criteria for the next evaluation.
- DSL node ID or code hints when they can be inferred.
- Expected gain, estimating how many overall score points could be recovered.
Prefer fewer high-signal findings over a long list of vague observations. Findings should be actionable, localizable, and re-checkable.
Output
Return both:
- A concise Markdown report for humans.
- A valid JSON report following
references/report-schema.mdfor downstream automation. - The filesystem path of the generated Markdown report.
The Markdown should summarize the score, dimension breakdown, top optimization plan, and key findings. The JSON should preserve the detailed structure for machine consumption.
When the user or surrounding workflow is Chinese, write the human-readable Markdown report in Chinese. Keep JSON field names in English for automation, but prefer Chinese for descriptive JSON string values such as summary, notes, action, rationale, evidence, suggestedChange, and acceptanceCriteria.
Boundaries
- Do not include a separate comparability check in v1.
- Do not score code architecture, framework choice, naming, or maintainability unless it visibly affects fidelity.
- Do not overclaim exact pixel values unless they were measured. Use "about", "roughly", or ranges when estimating visually.
- If DSL and screenshots disagree, treat screenshots as the visual truth and use the DSL as structural evidence.
- If a suggested fix is uncertain, label it as a likely code hint rather than a confirmed cause.
HelixHarness feedback
反馈边界(本 skill 的硬约束,来源
reference/feedback-protocol.md):反馈是用户显式提交的实时上报,与 usage telemetry 完全解耦——不读取对话之外的任何数据、不创建 eval entry、不消费 telemetry consent(已配置反馈目的地时,telemetry 关闭不影响反馈;默认没有平台地址,未配置时仅保留入口,不能发送。未注册宿主以host=unknown上报)。用户明确要求附带时,会话上下文(对话文本 + 工具调用轨迹)随反馈一并发送,发送前经过裁剪(不含工具原始输出、thinking、宿主注入内容)、脱敏(密钥/手机号/邮箱/内网地址替换)与本地标识剥离;绝不写入用户仓库,绝不自动外发任何未经确认的内容。
Runtime 硬门禁:在任何
python3调用前,必须读取并执行{plugin_root}/reference/runtime-preflight.md(本文所有reference/相对路径均指 plugin 根下的reference/,不是本 skill 所在目录旁的 reference/)。runtime preflight 返回runtime_unavailable时按其 fallback 规则处理,不得静默跳过运行时检查。
参数宽容规则:解析
$ARGUMENTS时先按 shell token 分词;每个 token 仅去除尾部常见中英文句读(, . ; : ! ? ,。;:!?、及右侧闭合括号)后,再对 flag 做精确匹配。不得使用任意子串匹配,例如--category-bug不能视为--category。
使用前提
接收地址默认由发布方在 scripts/reporting_config.py 的 DEFAULT_FEEDBACK_ENDPOINT 统一配置,当前默认值为空,后续需要时再填写。用户可以创建或修改 ~/.helixharness/feedback/config.json,用非空 endpoint 覆盖发布默认值:
{
"endpoint": "http://127.0.0.1:7860/feedback/report"
}
发布脚本与用户配置文件是仅有的两种地址来源,不读取地址环境变量。HELIXHARNESS_FEEDBACK_HOME 仍可覆盖配置、草稿和队列目录。缺少文件、字段或值为空时使用发布默认值;文件损坏、字段类型错误或非空地址无效时停止准备,不回退到其他接收方。
接收端必须是实际运行的 helixharness-platform;本机可运行 helixharness-server --port 7860,远程平台替换为可访问的完整地址,127.0.0.1 指插件所在机器。发布地址已有效时无需用户再配置。不猜测接收方,不复用统计的 /report 地址;两种来源均为空时停止发送准备并说明配置方法,不声称“已上报”。
触发形态与同意语义
本 skill 支持三种触发形态。终确认必须覆盖准备好的实际接收地址和完整脱敏内容,不跟着触发形态走:
- 图形选择定型(AskUserQuestion):收集用户原文、分类与 feature 后进入 Step 3 准备草稿;完整内容和接收地址已明确确认时直接发送,不重复确认。
- 文本口头定型(降级路径):口头回答可能有映射歧义,进入 Step 3 后连同实际地址和脱敏内容一并回显确认。
| 触发形态 | 同意规则 |
|---|---|
| 用户调用 feedback Skill 且带反馈正文 | 用户显式发起、正文即用户原话,跳过描述收集;分类与 feature 按 Step 2 收集,按上表定型方式决定是否复述 |
| 用户调用 Skill 但未带正文(收集式提交) | 按下方流程收集,按定型方式决定是否复述 |
| 模型自动触发(识别到用户遇到 HelixHarness 问题) | 同意提交后走 Step 2 收集,按定型方式决定是否复述;文本路径下须复述完整内容(正文 / 分类 / feature)经确认后才发送 |
自动触发的引导规则(识别到用户受挫信号后,何时开口、怎么开口):
- 时机:先完成自救(重试/修复)。若已恢复且用户全程无感,不开口;若仍失败、需要向用户交代失败时,在交代失败的同一句话里顺带引导,不单独成段、不重复追问
- 开口话术三要素:说明检测到了什么(哪个环节出的问题)、问一句是否提交反馈、说明"后续会先跟你确认分类和关联 feature"
- 两段式确认(硬约束):用户同意提交 ≠ 完成收集。同意后必须继续走 Step 2 的分类与 feature 收集,不得在用户说"好/可以"的那一刻跳过收集直接发送;收集完成后按 Step 3 准备草稿并确认实际接收地址与内容
- 节制:同一问题一个会话只引导一次;用户拒绝 → 本会话不再就同一问题二次引导(同会话节流);自救成功且用户无感 → 不引导
- 非交互 / loop(autopilot)上下文禁止自动上报:该场景下本 skill 直接以错误终止并说明原因,不收集、不发送
User Input
$ARGUMENTS
参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
<反馈内容> | 位置参数,反馈正文(1..4000 字符)。与 --category 可组合 | propose 阶段生成的 spec 字段要求不清楚 |
--category <分类> | 可选,bug / docs_unclear / process_stuck / suggestion,缺省 uncategorized | --category docs_unclear |
--feature <name> | 可选,关联的 active feature 名;缺省时按交互确认 | --feature early-repayment |
执行流程
本 skill 是轻量反馈工具,不做插件版本快速检查(不同于业务工作流命令):用户带着问题来,升级提示会打断反馈,且上报内容对插件版本零耦合。runtime preflight 硬门禁(python3 可用性)仍然保留。
Step 1: 读取反馈协议
读取 {plugin_root}/reference/feedback-protocol.md(字段语义、transcript 裁剪与脱敏边界、服务端消费契约的唯一权威定义);读取失败时停止准备和发送,并说明反馈组件不完整。
Step 2: 输入收集(描述先行)
$ARGUMENTS 带反馈内容时:解析出正文与可选 --category / --feature,进入本步收集,随后按 Step 3 准备。正文以用户原话为准,不得改写、总结或补充。--category / --feature 缺哪项就只按本步规则补哪项。
$ARGUMENTS 为空或模型自动触发时:先问一句开放问题(如"说说遇到的问题吧"),拿到描述后再收集分类与 feature——描述是分类推断和 feature 定位的依据,必须先行。
分类推断:从用户描述推断分类并映射到枚举 bug / docs_unclear / process_stuck / suggestion,映射不上即 uncategorized。推断结果只作为推荐项呈现,由用户最终确认。
分类与 feature 的收集——按宿主能力分派。判定规则是确定性的,不得自行裁量:当前会话工具列表里有 AskUserQuestion 就必须走首选路径,没有才走降级路径;禁止在有该工具时降级为纯文本提问。
-
首选路径(会话工具列表含
AskUserQuestion,如 Claude Code)——必须使用:一次调用同时问两问——- "反馈分类":4 个选项(bug / docs_unclear / process_stuck / suggestion,label 用枚举值、description 一句话释义),推断项放第一位并在 label 标"(推荐)";用户经 Other 自由输入时映射枚举,映射不上按
uncategorized - "关联 feature":选项 =
不关联+docs/specs/active/下的 feature(最多再列 3 个,推断项或最近活跃优先并标"(推荐)");active 超出 3 个时经 Other 输入,输入值必须校验存在于 active 列表,不存在则提示重选;docs/specs/active/不存在或为空时该问整体跳过(feature=null) - 选择完成后进入 Step 3 准备草稿;收集选项本身不替代对实际地址和完整脱敏内容的确认。
- "反馈分类":4 个选项(bug / docs_unclear / process_stuck / suggestion,label 用枚举值、description 一句话释义),推断项放第一位并在 label 标"(推荐)";用户经 Other 自由输入时映射枚举,映射不上按
-
降级路径(仅当会话无
AskUserQuestion,如 Codex):对话式收集(下为摘要格式示例,实际值以本轮收集结果为准;在 Step 3 连同实际地址和完整脱敏内容确认后才发送)——当前收集的反馈信息(可直接说要改哪项): - 分类:流程卡住 - 描述:propose 到 P2 卡在确认项清理(你的原话) - 关联 feature:early-repayment无推断依据时相应项写"未分类"/"不关联";用户口头改 feature 名同样必须校验在 active 列表内,不在则提示可选项。
红线不变:feature 值只允许来自 docs/specs/active/ 实际列表 + 用户确认,任何情况下不得猜测或编造;用户显式传 --feature 时使用该值;"不关联"是有效答案,不二次确认、不暗示次优;非交互/loop(autopilot)上下文不收集、不自动上报;用户所选 feature 没有 eval-log 时 related_entry_ids=[],合法。
Step 3: 准备、确认并发送
{plugin_root} 必须来自当前 plugin skill resource(Claude 可用 ${CLAUDE_PLUGIN_ROOT},Codex 使用当前 plugin resource root),不得搜索安装目录。{current_platform} 必须使用 canonical host ID:Claude Code 固定为 claude-code,Codex 固定为 codex。
先准备草稿,不发送。参数必须安全转义:
{helix_python} "{plugin_root}/scripts/feedback_submit.py" prepare --repo-root "{repo_root}" --platform "{current_platform}" --text "{反馈正文}" --category "{分类}"
按用户选择追加 --feature "{feature}"。默认不附带会话;只有用户明确要求附带当前会话时追加 --include-transcript,不搜索历史会话替代。
展示返回的实际 endpoint、完整 item.document 和附带的 item.transcript_md(如有),取得对地址和内容的明确发送确认。已有对同一完整内容及地址的明确授权时不重复确认;内容修改后重新准备。
{helix_python} "{plugin_root}/scripts/feedback_submit.py" send --draft "{draft_path}" --digest "{digest}" --confirmed
--confirmed 必须由真实用户授权支持。脚本失败(exit 1)时向用户原样展示 stderr 中的错误 JSON 并终止,不得重试改写内容。非交互/loop(autopilot)上下文不得自动上报。
Step 4: 回执输出(逐字使用 prepare/send 返回值,禁止手工编造字段)
实时送达(send 的 status: "delivered"):编号与状态取 send 回执,document 和 transcript_stats 取同一已确认的 prepare 草稿 item,未附带会话时如实说明。
## HelixHarness feedback 已发送
- 反馈编号: {feedback_id}
- 状态: 已实时送达配置的平台看板({endpoint})
- 会话上下文: user {transcript_stats.user_messages} / assistant {transcript_stats.assistant_messages},
工具调用 {transcript_stats.tool_calls} 次,脱敏 {transcript_stats.redactions} 处
(transcript_stats.supported 为 false 时,改为如实说明原因,如 codex 会话暂不支持采集)
### 本次发送的完整字段
{逐项列出 document 中的全部字段与值;这是透明披露,不得省略}
进入本地队列(status: "queued"):如实说明看板暂不可达(delivery 字段),报告已进入本地待发队列(queue_path),下次提交反馈时自动补投,最长保留 30 天,只向原接收地址补投;如本次顺带补投了历史队列消息(queue_flushed.flushed),一并说明。
平台拒绝(status: "rejected"):尚未送达,保留草稿并报告原因,不改写内容重发。用户要求重试时可执行 feedback_submit.py retry --confirmed,仅补投已确认且与当前配置地址一致的待发记录。
双宿主说明
- Claude Code 与 Codex 使用同一 CLI(
feedback_submit.py),反馈流程本身无 hook 参与、无 consent 流程 - 会话上下文采集当前仅支持 claude-code 会话;Codex 宿主仍可上报反馈元数据(
transcript_stats.supported=false),不是错误 - 未注册宿主(
{current_platform}无法给出 canonical ID 时):--platform unknown仍可上报,文档中host记为unknown
注意事项
- 过程静默 — 内部动作(读取协议/preflight 文件、列出 feature 目录、校验路径与枚举值)不向用户逐条汇报;用户视角只出现业务话术(提问、选项、复述、回执)。读取必需协议失败时停止发送并说明反馈组件不完整
- 正文即用户原话 — 只做 shell 转义,不改写、不翻译、不截断;超 4000 字符时提示用户精简后重试
- 不读会话之外的数据 — 会话上下文仅取当前会话的对话文本与工具调用轨迹;工具原始输出、thinking、宿主注入内容一律排除
- 幂等 — 同一
feedback_id与相同内容重复上报由服务端去重;相同 ID 的不同内容被拒绝,skill 侧不改写 ID 绕过 - 失败即止 — 校验失败(超长、非法分类、非法 feature 名)原样展示错误,不降级发送
- 不写仓库 — 反馈与上下文不落盘到业务仓库,不执行任何 git 操作
Git 改动影响分析
这是按需调用的独立方法 Skill。普通 Apply、Bug Fix 和 Code Review 不自动调用它;分析不创建 feature、启动统计、修改业务代码或改变 HelixHarness 评审状态。无需先执行 Init,也不依赖 Spec/Tasks 或 helixharness-platform。
输入与范围
用户可以用自然语言指定范围,或提供以下参数:
| 参数 | 含义 |
|---|---|
| 不提供 Git 引用 | 分析当前未提交改动 |
| 一个 Git 引用 | 对比该引用与当前 HEAD 的提交快照,不混入工作区改动 |
| 两个 Git 引用 | 对比第一个与第二个提交快照,不混入工作区改动 |
--req <path> / --design <path> | 可选的需求 / 设计文档 |
--out <path> | 报告文件或目录;默认当前工作目录的 diff-impact-reports/ |
--no-save | 只在对话输出;优先于 --out |
例如:“使用 HelixHarness git-diff-impact,对比 main 和 feature/search,结合 --req docs/search.md 分析影响,--no-save。”引用和路径按独立参数处理,保留含空格路径,不把用户文本拼接为可执行 shell 代码。
未提交模式
先读 git status --short,再用 git diff --no-ext-diff --no-textconv HEAD -- 取得已跟踪文件的暂存及未暂存改动。用 git ls-files --others --exclude-standard 单独列出未跟踪文件;Git diff 不包含它们。仅读取明确属于请求范围的新增源码、配置或文档,不读取凭据、忽略目录或无关生成物。范围混杂且无法确定归属时,先列出候选路径,请用户明确范围;不把整个工作区当作某个 feature 的改动。
无 HEAD 的新仓库按未出生分支处理:以空树为基准,单独检查暂存、未暂存及相关未跟踪文件,并在报告注明没有基准提交。没有范围内改动时结束,不生成“通过”结论。
提交对比模式
用 git rev-parse --verify --end-of-options '<ref>^{commit}' 将每个引用解析为完整 SHA。之后仅用解析后的 SHA 获取 git diff --no-ext-diff --no-textconv <base-sha> <target-sha> -- 及变更清单。这是两个提交快照的直接比较;只有用户要求“分支引入的改动”时才以 merge-base 为基准,并明确记录实际基准。
调用链和行号必须来自目标 SHA 的代码;删除项使用基准 SHA 并标注。用 git show <sha>:<path>、git grep <pattern> <sha> -- 等只读命令检查对应版本,不能用当前工作区替代历史代码,也不切换或重置用户分支。无效引用、非 Git 仓库或未解决的冲突应说明并停止相关分析。
记录完整比较 SHA、范围内文件及排除项。未提交模式先保留本轮差异快照,结束前核对范围内内容是否变化;变化则刷新分析,不能把旧结果当成最新结果。
分析方法
- 建立上下文。 读取适用的 AGENTS.md 和相关模块文档,再读取用户提供的需求 / 设计。没有需求时仍可分析代码,但不声称已验证需求覆盖;文档冲突时列明两边依据,不擅自选择。只读取与当前改动相关的上下文。
- 定位语义变化。 从 diff 定位修改的函数、接口、类型、配置、数据结构和状态,比较输入输出、错误行为、副作用及默认值。新增代码也检查注册、导出和状态写入;不因“仅新增”就自动判低风险。
- 追踪影响。 用当前目标版本的 LSP 引用或文本搜索至少检查一层直接调用方,高风险项再追踪间接消费者。关注事件、回调、反射、依赖注入和共享缓存;未找到引用不等于不存在调用。记录具体路径、行号、触发条件及受影响业务场景。业务意图对齐仅依据用户提供的需求或设计。
- 检查兼容性。 涉及公共契约、构建配置或相关语言时读取 compatibility.md 的对应部分。先从仓库确认支持环境,再核对候选风险。环境范围未知时列出假设及待验证项,不臆造支持版本。需要核实 API 版本事实时使用官方文档,不把记忆当证据。
- 分级和去重。 高风险是有证据的契约破坏、核心行为回归、数据一致性问题或支持环境中的硬失败;中风险是有具体机制、影响有限或仍需验证的行为变化;低风险是有依据的局部影响。把风险等级与证据确定性分开标注,已有效覆盖的守卫、polyfill、转译或降级分支应计入判断。不能仅因某个新 API 或公共接口有变化就判定缺陷。
通常由当前 Agent 按模块分析,不固定增加子 Agent。改动过大时先列出覆盖计划和优先级;未深入检查的文件及调用链明确标为未覆盖,不以低风险或“无问题”代替。只做静态分析时明确说明,不能声称测试已执行或兼容性已经实测通过。
输出
对话先给出主要发现,再给出报告路径。报告包含:
- 分析范围:模式、基准 / 目标 SHA 或工作区快照、已读上下文、排除项;
- 改动概览:涉及模块和行为变化;
- 影响清单:改动位置、直接 / 间接调用方、触发条件、业务影响、风险等级、证据和待验证项;
- 兼容性:已确认的支持环境、有效缓解及受影响环境;不适用时简述原因;
- 建议:需验证的行为及测试方向;不自动执行修复或生成测试;
- 覆盖边界:未覆盖文件、动态调用盲区、未运行测试和仍不确定的结论。
未指定 --no-save 时,保存 UTF-8 Markdown:提交对比用 diff_impact_<base-short-sha>_<target-short-sha>.md,未提交模式用 diff_impact_uncommitted_<YYYYMMDD>.md。--out 以 .md 结尾时视为文件,否则视为目录。同名文件追加 _2、_3 等后缀,避免覆盖。保存失败时仍在对话交付结果,并说明真实错误。
报告是影响分析建议,不是 HelixHarness 的 APPROVE、MUST_FIX、正式 Evidence 或 Archive 收据。用户后续要求修复或接入评审时,由相应流程处理。
系统化调试
用户明确要求使用本 Skill,且真实不一致已经出现时,独立开展调试:
- expected behavior != actual behavior
- test fails
- compile/runtime error appears
- observed behavior regresses or contradicts an agreed requirement
不要把这个 skill 用于模糊的设计讨论。那属于 planning,不属于 debugging。
目标
基于证据找到根因,再用回归检查确认修复真实有效。
工作流
-
明确不一致是什么。 写清楚:
- expected behavior
- actual behavior
- where it was observed
-
稳定复现。 优先用一个确定性的命令、请求或测试来复现。 如果复现不稳定,要明确记录。
-
缩小范围。 检查:
- input data
- call path
- changed files
- environment/config assumptions
-
提出假设。 假设必须具体且可证伪。 好的例子:
- "null value enters mapper X and breaks branch Y" 不好的例子:
- "something is wrong with the service"
-
执行有区分度的检查。 选择能排除某个假设的下一条命令或检查。
-
确认根因。 区分清楚:
- symptom
- trigger
- root cause
-
做最小且合理的修复。 仅在用户已授权修复时执行;只要求诊断时,交付根因、证据和修复建议,不修改代码。 除非根因要求,否则不要顺手做大范围重构。
-
重新执行复现和回归检查。 不重新验证,修复就不算完成。
独立使用边界
- 由用户独立调用,不作为研发命令或代码评审的内部步骤
- 无需先执行 Init、创建需求、开启统计或启动平台
- 不创建 feature、Spec/Tasks 或 eval-log,不启动或推进研发命令
- 交付诊断与验证结果,由用户决定后续处理;未执行修复或验证时如实标明
输出格式
用五行摘要输出调试结果:
- Expected:
- Actual:
- Reproduction:
- Root cause:
- Verified fix:
约束
- 在重新跑过失败场景前,不能说“已经修复”
- 在没找到根因前,不要做大范围改写
- 没有证据时,不要把环境问题和代码问题混为一谈
- 如果无法复现,要明确写出来
HelixHarness 测试驱动开发
TDD 是红灯 → 绿灯循环。本 Skill 规定如何让这个循环产出值得长期保留的测试:什么是好测试、测试应写在哪个边界、应避免哪些反模式,以及循环必须遵守什么规则。每轮循环开始前和执行中都遵循全部规则,不要等结束后再补做。
HelixHarness 集成
入口门禁(任何测试或业务写入前执行)
TDD 只能继承已经建立的 HelixHarness 工作流上下文,以下二者必须满足其一:
- Apply 已加载
docs/specs/active/<feature>/spec.md与对应tasks.md,且 Spec 的 Testing Decisions 已确认当前公共测试 seam; - Bug Fix 已记录可重复的失败场景,并已确认要观察的公共 seam。
聊天中的实现请求、仓库中的普通需求文件或临时测试说明,都不能替代上述 active Spec / Bug Fix 上下文。门禁不满足时,立即返回 BLOCKED: helixharness_tdd_context_missing,不得创建或修改测试、业务代码、TDD 证据或 HelixHarness 工件,并引导用户先进入 Propose 或 Bug Fix。
从当前 spec.md、tasks.md 或已复现的 Bug 场景中选择一个行为切片。测试 seam 必须已经在 Spec 的 Testing Decisions 中确认;seam 缺失或公共接口仍有争议时,返回 HelixHarness Propose 确认,不要在实现阶段自行创建测试入口。
复用 HelixHarness Apply 已通过 reference/loading-protocol.md 加载的项目入口、docs/harness/ 约束、docs/knowledge/ 知识、Spec 和当前 Task。只有任务边界变化时才按该协议重新评估索引叶子。测试名称和接口词汇使用这些已加载事实以及当前代码、配置和测试中的项目语言。
什么是好测试
通过公共接口验证行为,不验证实现细节。代码可以完全重写,但测试不应因此改变。好测试读起来像一条规格说明,例如“有效购物车可以完成结算”明确描述了系统能力;它不依赖内部结构,因此能够经受重构。
具体示例见 tests.md,Mock 指引见 mocking.md。
Seam:测试写在哪里
Seam 是被测试的公共边界:通过这个接口观察行为,而不进入实现内部。只在 seam 上测试,不测试内部结构。
只测试预先确认的 seam。 在 HelixHarness 中,Spec 的 Testing Decisions 就是这份约定。已确认的 seam 不重复询问,未确认的 seam 不写测试。接口形态本身仍有争议时返回 HelixHarness Propose,不要在 Apply 中自行选择或创建接口。
反模式
- 与实现耦合:Mock 内部协作者、测试私有方法,或绕过公共接口从侧面验证,例如直接查询数据库。识别信号是:行为没有变化,仅内部重构就导致测试失败。
- 同义反复:断言用与实现相同的方式重新计算期望值,例如
expect(add(a, b)).toBe(a + b)、按实现逻辑手工生成快照,或断言常量等于自身。这类测试天然不会与实现产生分歧。期望值必须来自独立事实,例如已知字面量、推导完成的样例或 Spec。 - 水平切片:先写完全部测试,再集中实现。批量测试验证的是想象中的行为,容易只测试结构,并在理解实现前过早锁定测试形态。改用垂直切片:一个测试 → 一个实现 → 再进入下一轮;让每个测试都成为根据上一轮结果继续前进的 tracer bullet。
循环规则
- 先红后绿:先写失败测试,再只写足够让它通过的代码。不要预判后续测试或添加推测性功能。
- 一次一个切片:每轮只处理一个 seam、一个测试和一个最小实现。
- 重构不属于本循环:重构放在 HelixHarness Apply 的 Code Review 阶段,不放进红灯 → 绿灯实现循环。任何 Review 修复完成后,都要重跑覆盖该行为的测试。
每个实际执行的 RED-GREEN 切片保留以下最小事实,供 Apply 整体 APPROVE 后一次性汇总到最终 verify-report.md:
- Task ID 与关联 AC ID;
- test file 与 failing test name;
- failing output summary;
- passing output summary。
摘要只保留能证明先红后绿的关键信息,不复制完整测试输出。不得在 TDD 循环中创建或更新 verify-report.md;Apply 在最终测试和双轴 Review 均通过后统一写入正式报告。文档、格式或无法表达为行为测试的配置变更只记录对应的确定性检查,不伪造 RED/GREEN 证据。
Commands 9
/helix:apply
HelixHarness 公共命令唯一契约:本文件只负责公共入口、确定性路由和路由结果消费。业务正文由 Router 返回的唯一
workflow文件承载,不在这里复制单仓或 Workspace 步骤。
Runtime 硬门禁:在任何 Python 调用、需求工件读取或路由判断前,完整读取并执行
reference/runtime-preflight.md。Python 不可用时按其中的恢复规则处理;安装并复检成功后才从下方 Router 继续,暂不安装或失败则输出BLOCKED:helixharness_python_runtime_unavailable。
User Input
$ARGUMENTS
1. 只执行一次确定性路由
把 $ARGUMENTS 原样按当前 shell 的单参数规则安全引用,然后执行:
{helix_python} "{plugin_root}/scripts/workflow_router.py" --repo-root "{repo_root}" route --command apply --arguments={SHELL_QUOTED_ARGUMENTS} --arguments-mode auto
{plugin_root} 必须来自当前 plugin command resource,{repo_root} 是当前仓库根。不得使用 eval 或拼接未经引用的用户文本。除上述 Runtime preflight 外,不得在路由前自行读取 Spec/Tasks、扫描 active/completed 目录或猜测阶段。
2. 只按 action 消费 JSON
退出码 0 或 2 且 stdout 是有效 JSON 时都按 action 处理;只有进程异常、无有效 JSON 或未知 action 才输出 BLOCKED:workflow_router_failed,不得退回模型推断。
load_workflow或repair_feature:完整读取workflow指向的唯一workflows/single/*.md或workflows/workspace/*.md正文并执行,传递feature、execution_scope、workflow_arguments与调用 trigger。不得改写路径、同时加载另一 scope、重新判断流程或递归调用公共入口。recommend_command:原样展示 recommendation 并停止,不读取工作流正文。select_feature:只展示 candidates 让用户选择;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑。不得按顺序、修改时间或语义相似度代选。blocked且reason=feature_required:只请求明确的 feature 名;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑,不把缺少名称当成不可恢复错误。- 其他
blocked:输出BLOCKED:{reason}后停止,不读取工作流正文,不迁移或覆盖冲突工件。
公共命令不写业务工件;只有所选工作流可按自身合同写入。宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol。
/helix:archive
HelixHarness 公共命令唯一契约:本文件只负责公共入口、确定性路由和路由结果消费。业务正文由 Router 返回的唯一
workflow文件承载,不在这里复制单仓或 Workspace 步骤。
Runtime 硬门禁:在任何 Python 调用、需求工件读取或路由判断前,完整读取并执行
reference/runtime-preflight.md。Python 不可用时按其中的恢复规则处理;安装并复检成功后才从下方 Router 继续,暂不安装或失败则输出BLOCKED:helixharness_python_runtime_unavailable。
User Input
$ARGUMENTS
1. 只执行一次确定性路由
把 $ARGUMENTS 原样按当前 shell 的单参数规则安全引用,然后执行:
{helix_python} "{plugin_root}/scripts/workflow_router.py" --repo-root "{repo_root}" route --command archive --arguments={SHELL_QUOTED_ARGUMENTS} --arguments-mode auto
{plugin_root} 必须来自当前 plugin command resource,{repo_root} 是当前仓库根。不得使用 eval 或拼接未经引用的用户文本。除上述 Runtime preflight 外,不得在路由前自行读取 Spec/Tasks、扫描 active/completed 目录或猜测阶段。
2. 只按 action 消费 JSON
退出码 0 或 2 且 stdout 是有效 JSON 时都按 action 处理;只有进程异常、无有效 JSON 或未知 action 才输出 BLOCKED:workflow_router_failed,不得退回模型推断。
load_workflow或repair_feature:完整读取workflow指向的唯一workflows/single/*.md或workflows/workspace/*.md正文并执行,传递feature、execution_scope、workflow_arguments与调用 trigger。不得改写路径、同时加载另一 scope、重新判断流程或递归调用公共入口。recommend_command:原样展示 recommendation 并停止,不读取工作流正文。select_feature:只展示 candidates 让用户选择;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑。不得按顺序、修改时间或语义相似度代选。blocked且reason=feature_required:只请求明确的 feature 名;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑,不把缺少名称当成不可恢复错误。- 其他
blocked:输出BLOCKED:{reason}后停止,不读取工作流正文,不迁移或覆盖冲突工件。
公共命令不写业务工件;只有所选工作流可按自身合同写入。宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol。
用法
/helix:archive <name> [--commit|--no-commit]。提交选择原样交给所选工作流。--no-commit 将提交决定延后到归档后的最终选择,本身不授权 commit 或 push;Workspace 必须把该参数传给每个子仓。--commit 只授权封存的 Apply Scope 本地提交,不授权 push。未传 flag 时按工作流询问。
/helix:bug-fix
HelixHarness 公共命令唯一契约:本文件只负责公共入口、确定性路由和路由结果消费。业务正文由 Router 返回的唯一
workflow文件承载,不在这里复制单仓或 Workspace 步骤。
Runtime 硬门禁:在任何 Python 调用、需求工件读取或路由判断前,完整读取并执行
reference/runtime-preflight.md。Python 不可用时按其中的恢复规则处理;安装并复检成功后才从下方 Router 继续,暂不安装或失败则输出BLOCKED:helixharness_python_runtime_unavailable。
User Input
$ARGUMENTS
1. 只执行一次确定性路由
把 $ARGUMENTS 原样按当前 shell 的单参数规则安全引用,然后执行:
{helix_python} "{plugin_root}/scripts/workflow_router.py" --repo-root "{repo_root}" route --command bug-fix --arguments={SHELL_QUOTED_ARGUMENTS} --arguments-mode auto
{plugin_root} 必须来自当前 plugin command resource,{repo_root} 是当前仓库根。不得使用 eval 或拼接未经引用的用户文本。除上述 Runtime preflight 外,不得在路由前自行读取 Spec/Tasks、扫描 active/completed 目录或猜测阶段。
2. 只按 action 消费 JSON
退出码 0 或 2 且 stdout 是有效 JSON 时都按 action 处理;只有进程异常、无有效 JSON 或未知 action 才输出 BLOCKED:workflow_router_failed,不得退回模型推断。
load_workflow或repair_feature:完整读取workflow指向的唯一workflows/single/*.md或workflows/workspace/*.md正文并执行,传递feature、execution_scope、workflow_arguments与调用 trigger。不得改写路径、同时加载另一 scope、重新判断流程或递归调用公共入口。recommend_command:原样展示 recommendation 并停止,不读取工作流正文。select_feature:只展示 candidates 让用户选择;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑。不得按顺序、修改时间或语义相似度代选。blocked且reason=feature_required:只请求明确的 feature 名;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑,不把缺少名称当成不可恢复错误。- 其他
blocked:输出BLOCKED:{reason}后停止,不读取工作流正文,不迁移或覆盖冲突工件。
公共命令不写业务工件;只有所选工作流可按自身合同写入。宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol。
用法
/helix:bug-fix <name> [description-or-path]。有问题来源时开始或识别修订;只传名称时先进入正文执行 repair-preflight,有未完成修订则复用其身份续跑,无可恢复状态时请求问题来源。只修订 active 单仓需求,不支持 completed 或 Workspace;repair_feature 只加载 workflows/single/bug-fix.md。
HelixHarness 公共命令唯一契约:本文件承载 config 的全部业务步骤。所有宿主通过当前
resources.command_projection加载本文件,使用预绑定 Host Context;完整读取reference/workflow-projection-protocol.md、reference/host-runtime-protocol.md、当前resources.runtime和reference/eval-protocol.md。
在任何 Python 调用前执行
reference/runtime-preflight.md。本命令不推进需求、不写 Stage、不刷新插件版本、不发送反馈或统计测试请求。
User Input
$ARGUMENTS
参数
| 用法 | 行为 |
|---|---|
/helix:config | 只读查看统计有效开关、作用范围、统计与反馈地址及配置来源 |
/helix:config --telemetry enabled --scope project | 开启当前项目统计 |
/helix:config --telemetry disabled --scope project | 关闭当前项目统计 |
/helix:config --telemetry enabled --scope user | 开启当前宿主的本人统计;已有项目级设置仍参与优先级判断 |
/helix:config --telemetry disabled --scope user | 关闭当前宿主的本人统计,优先于项目开启设置 |
/helix:config --report-endpoint https://platform.example/report | 更新本机统计上报地址 |
/helix:config --feedback-endpoint https://platform.example/feedback/report | 更新本机反馈地址 |
/helix:config --reset-report-endpoint | 移除统计地址覆盖,恢复发布默认值 |
/helix:config --reset-feedback-endpoint | 移除反馈地址覆盖,恢复发布默认值 |
当前配置范围只有以上设置;模型、密钥、业务项目配置、平台服务部署不属于本入口。按 shell token 精确解析,URL 保留原文,不裁剪标点;未知参数、混合多项修改、--telemetry 与 --scope 不成对时先说明用法,不做部分写入。用户以自然语言提出多项设置时,先整理明确值和范围,再逐项执行并分别报告结果;失败时停止,不声称全部成功。
查看
{helix_python} "{plugin_root}/scripts/user_config.py" --repo-root "{repo_root}" --platform "{canonical_host_id}"
canonical_host_id 来自预绑定 Host Context,不猜测平台或授权文件位置。脚本使用纯读取授权 API,默认查看不清理私有数据、不改提醒时间、不启动 Runtime。展示有效值、作用范围、配置来源与文件位置;无配置或损坏都如实说明,不伪造默认开启。不要打印完整配置 JSON、授权缓存、项目指纹或凭据。
修改
- 用户已给出明确修改命令或明确自然语言目标、值和范围时,这就是该项修改的授权,不再重复要求确认。参数不完整时,先查看当前值,只询问缺失的必要信息。默认查看、推荐项和未提交的选择不构成授权。
- 开启统计之前逐字展示
reference/eval-protocol.md中helixharness-eval-data-notice-v1的数据说明。用户已明确要求开启时展示说明后执行;仅表达查看/配置意图时展示说明并由用户选择,不能自动开启。 - 使用同一个
user_config.py,追加一项实际修改参数及内部--user-confirmed标记。该标记仅在已有明确请求或选择后由 Agent 传入。授权缓存始终通过捆绑telemetry_consent.py的 API 写入,不手改 JSON。项目开启被用户级关闭覆盖时展示 warning 和实际有效范围,不自动扩大授权。 - 地址配置按当前
HELIXHARNESS_TELEMETRY_HOME/HELIXHARNESS_FEEDBACK_HOME或默认本机目录定位,脚本只合并目标endpoint字段并原子写入,保留其他字段。非法地址或损坏 JSON 拒绝写入并保留原文件;不自行删除重建。URL 不允许凭据、查询参数和 fragment。 - 根据返回的
change.updated、warning 和重新读取的有效值报告。updated=false不能称修改成功。操作后显示实际作用范围和配置来源。
地址设置不代表统计授权;恢复默认地址不是关闭统计,发布默认值可能仍有接收方。停止统计必须显式关闭授权。开启本人范围仅影响当前 Host Kit 的授权缓存,不擅自改另一宿主。关闭后不删除历史账本或平台数据;未发送私有证据由既有授权协议清理。
配置检查只验证格式和实际生效值,不代表服务在线、统计已送达或反馈已发送。地址变更不重定向旧地址待发数据;不调用发送、补投、安装或后台 Worker 来“验证配置”。
宿主资源声明:resources.runtime。
HelixHarness 公共命令唯一契约:本文件同时承载 init 的完整业务步骤和原生命令分发表面。所有宿主都必须通过当前
resources.command_projection加载本文件,并使用预绑定 Host Context;完整读取reference/workflow-projection-protocol.md、reference/host-runtime-protocol.md、reference/tool-semantics.md、当前resources.runtime、resources.subagent_protocol、resources.project_config、resources.project_hooks和resources.telemetry_protocol,不得再读取其他 init command/workflow 补充业务语义。
Init Agent DAG 不变量:本文件中的 Agent tool 拼写按
reference/tool-semantics.md执行。后端 A 组三路并行,B 组保持scan-service → scan-boundary → scan-service-meta依赖顺序;前端保持六路并行。当前 Host Kit 只能映射派发、等待和物理写入者,不得改变 Agent 数量、依赖、产物或 BLOCKED 传播。
Telemetry Host Kit 门禁:读取
reference/telemetry-command-protocol.md和resources.telemetry_protocol,只按 capability、生命周期模式和逻辑动作执行;不得根据宿主名称选择宿主私有缓存、stage 或 finish 流程。
Runtime 硬门禁:在版本检查、consent 或任何
python3调用前,必须读取并执行reference/runtime-preflight.md。Python 不可用时暂不展示统计问询;依赖恢复后由 resolver 解析授权缓存和提醒周期,异步地址不阻止问询,不得因安装 Python 自动开启统计。
参数宽容规则:解析
$ARGUMENTS时先按 shell token 分词;每个 token 仅去除尾部常见中英文句读(, . ; : ! ? ,。;:!?、及右侧闭合括号)后,再对 flag 做精确匹配。feature、数值、枚举和路径参数使用同一规范化结果;不得使用任意子串匹配,例如--workspace-later不能视为--workspace。
Host Kit 项目配置
Host Context 解析成功后,必须读取 resources.project_config 指向的 JSON,并把其中字段作为
本轮 init 的唯一宿主项目配置依据:
entry_file:仓库或 workspace 根入口文件;已有内容只能合并,不能覆盖;entry_template:生成入口文件时使用的模板;workspace_entry_template:生成 workspace 根入口文件时使用的模板;settings_file:需要合并的宿主项目设置;为null时不得为该宿主虚构设置文件。
实际产物、bootstrap message 和 workspace 门禁必须使用 Host Kit 声明值。 新宿主不得通过修改本命令增加入口文件分支。
Init Agent/Task Dispatch Contract
结构化回执与一次格式恢复
result_reencode_budget: 1
该预算仅适用于当前 Host Kit 的 result_encoding=helixharness_structured_text;原生 Agent result
保持原样。派发每个 Init job 时,父流程必须传入同一插件内
hosts/shared/subagent-result-encoding.md 的绝对路径、准确 job_id 和该文件的 canonical 终态模板,
要求 child 完整读取后按模板返回;不得只要求“报告成功”。A 组还必须按下文返回 evidence index。
先确认原生任务成功终止,并独立校验实际产物和写域;仅当原始 final 已含可验证的业务事实、 错误只在编码/schema 时,允许按编码协议向同一 Agent 发起一次无工具、无读写的格式纠正。 原生失败/取消、产物失败或缺失业务事实不适用。保留原始与纠正后回执及真实错误,最多两次校验; 仍不合格时按原门禁停止,不新建 Agent、不重跑扫描、不猜测成功字段。
下列 job 定义 Init 的宿主无关扫描与生成流程。每次派发前必须使用入口已加载的公共子代理
协议与 resources.subagent_protocol;扫描 job 还须完整读取 reference/scan-agent-protocol.md,并将该路径与 Host Context 一起传给子代理;message 必须带仓库根、
项目类型、job_id、完整 prompt_source、依赖、读写边界、预期产物和验证。只有
resources.subagent_protocol 明确返回子代理能力不可用时,才允许父流程读取同一 prompt 内联一次;
容量暂满、等待中、失败或取消都不得触发内联降级。
派发前先从当前 resources.subagent_protocol 确定原生工具及其类型参数;prompt_source 是角色正文路径,
不是原生 Agent 类型,只有 Host Kit 可将逻辑 job 映射为当前已注册类型。每个 Init job 固定为
delegation_policy=leaf,派发 message 开头必须说明:
“你就是本 job 的执行者,直接读取并执行 prompt_source,不再派发同名或其他子任务。”
父流程为每个 job_id 保留一个本轮原生 handle;已有任务仍在运行时只等待,不因尚未生成文件、
输出暂缺或等待超时而重复派发。发现子任务继续派生、同 job 重复运行或并发任务写域重叠时,本轮按
BLOCKED: agent_dispatch_contract_violation 收口,不能仅以最终文件存在判定通过。
每个 job 的 read_scope 必须在派发 message 中解析为明确路径清单:
init_workspace_bootstrap:workspace registry、各 repo 的入口/README/构建元数据与已有docs/knowledge/service-meta.yaml,不得读取 repo 业务实现正文;init_scan_tech|init_scan_db|init_scan_api:当前仓库中各 prompt 声明的构建配置、schema/migration、 接口/IDL 与相关业务符号;三者不得借读其他扫描 job 的未完成产物;init_scan_service|init_scan_boundary|init_scan_service_meta:已验证的 A 组产物、前序 B 组产物, 以及 prompt 为补齐证据明确列出的当前仓库源文件;init_scan_frontend_*:当前仓库的前端 manifest、配置与各 prompt 声明的源码类别;fullstack merge 时init_scan_frontend_meta还可读取已验证的architecture.md;init_service_bootstrap|init_frontend_bootstrap:已验证扫描产物、外部 knowledge(若显式传入)、 当前 Host Kit 项目配置和需要增量合并的既有 HelixHarness 入口/索引/设置文件。
任何 read_scope 不得使用未解析的仓库外 glob;动态 workspace repo 必须先解析为规范路径。
每个 job 同时只读当前已验证 plugin root 中所需的 prompt、协议与模板。明确传入
ownership_root,所有本仓相对路径都从该目录解析;读取、搜索、目录遍历及符号链接遵守
reference/subagent-runtime-protocol.md 的读取边界。单仓 bootstrap 不能读取同级已初始化仓库
作为范例,也不能因缺少模板或扫描事实而搜索父目录。缺口必须返回父流程处理。
| job_id | prompt_source | depends_on | write_scope | forbidden_scope | expected_artifacts / validation |
|---|---|---|---|---|---|
init_workspace_bootstrap | agents/init-workspace-bootstrap.md | W0 repo registry 已确定 | workspace 根入口文件(由 resources.project_config.workspace_entry_template 生成)、helixharness.workspace.yaml、workspace docs/knowledge/**、docs/specs/active/、docs/specs/completed/ | 所有 repo-local 路径 | W1.5 的 8 项 workspace 产物全部存在并通过结构校验 |
init_scan_tech | agents/scan-tech.md | 项目类型为 backend/unknown,或全栈 scan plan 含后端扫描,且未传 --knowledge | docs/knowledge/architecture.md | docs/knowledge/index.md、init state、timings | 文件存在且非空 |
init_scan_db | agents/scan-db.md | 同上 | docs/knowledge/database/** | docs/knowledge/index.md、init state、timings | database/index.md、database/er.md 存在且非空 |
init_scan_api | agents/scan-api.md | 同上 | docs/knowledge/api/** | docs/knowledge/index.md、init state、timings | api/index.md 存在且非空 |
init_scan_service | agents/scan-service.md | A 组三项全部通过 | docs/knowledge/domain-model.md | 其他扫描产物、共享索引、init state、timings | 文件存在且非空 |
init_scan_boundary | agents/scan-boundary.md | init_scan_service | docs/knowledge/service-boundary.md | 其他扫描产物、共享索引、init state、timings | 文件存在且非空 |
init_scan_service_meta | agents/scan-service-meta.md | init_scan_service、init_scan_boundary | docs/knowledge/service-meta.yaml | 其他扫描产物、共享索引、init state、timings | 文件存在、非空且 YAML 可解析 |
init_scan_frontend_meta | agents/scan-frontend-meta.md | 项目类型包含 frontend;全栈全量扫描时额外依赖 init_scan_tech 并增量合并 architecture | docs/knowledge/architecture.md、docs/knowledge/build.md、docs/knowledge/structure.md、docs/knowledge/style.md | 共享索引、init state、timings | 四个文件存在且非空 |
init_scan_frontend_api | agents/scan-frontend-api.md | 同上 | docs/knowledge/api-endpoints.md | 共享索引、init state、timings | 文件存在且非空 |
init_scan_frontend_routes | agents/scan-frontend-routes.md | 同上 | docs/knowledge/routes.md | 共享索引、init state、timings | 文件存在且非空 |
init_scan_frontend_state | agents/scan-frontend-state.md | 同上 | docs/knowledge/state.md | 共享索引、init state、timings | 文件存在且非空 |
init_scan_frontend_components | agents/scan-frontend-components.md | 同上 | docs/knowledge/components.md | 共享索引、init state、timings | 文件存在且非空 |
init_scan_frontend_tracking | agents/scan-frontend-tracking.md | 同上 | docs/knowledge/tracking.md(检测到埋点时) | 共享索引、init state、timings | 文件存在且非空,或 final 明确“未检测到埋点” |
init_frontend_bootstrap | agents/init-frontend-bootstrap.md | 六个前端扫描 job 全部通过;全栈时还依赖 init_service_bootstrap | 下方初始化目标产物和当前宿主项目配置允许的入口/设置 | 已验证扫描产物之外的业务文件 | 初始化目标产物逐项通过 |
init_service_bootstrap | agents/init-service-bootstrap.md | greenfield:预检、consent、免扫描状态写入均通过;其他模式:后端扫描 DAG 全部通过,或外部 knowledge 导入完成;全栈时先于 frontend bootstrap | 下方初始化目标产物和当前宿主项目配置允许的入口/设置 | 已验证扫描产物之外的业务文件 | 初始化目标产物逐项通过 |
A 组 init_scan_tech/init_scan_db/init_scan_api 必须并行;B 组必须严格按
init_scan_service → init_scan_boundary → init_scan_service_meta 串行。六个前端扫描 job 必须保持
六路并行语义;运行时容量不足时只延后物理准入,不得减少 job。全栈全量扫描时,任何动态写域
重叠都必须先串行化;尤其两个会更新 architecture.md 的 job,后执行者只能合并补充,不能覆盖
已验证内容。共享 docs/knowledge/index.md、init state、timings 和最终设置合并始终保持单写者。
A 组三个 final 的 evidence index 业务事实每个 job 最多 30 项;supports 只允许
architecture|database|api,source 必须定位到仓库相对路径和行号、配置键或符号。
native_agent_result 使用宿主原生 Agent result,不新增文本结构要求,父流程只消费原生结果中
真实存在且可验证的 evidence;helixharness_structured_text 必须按当前 resources.subagent_protocol
的结果编码返回 evidence index,缺失即结果校验失败。
父流程校验、去重后把可靠 evidence 与产物路径交给 init_scan_service;没有可靠 evidence 时只消费
已验证产物,不得推断凑数,B 组仍只针对缺口或冲突补查。
User Input
$ARGUMENTS
版本快速检查
进入业务流程前,读取此 plugin 捆绑的 reference/version-update-protocol.md,按“主流程快速版本检查模式”执行:
- 每次命令执行和阶段续跑都调用
{helix_python} "{plugin_root}/scripts/version_update.py" --platform {canonical_host_id} --repo-root {repo_root} check;canonical_host_id必须取自预绑定 Host Context,禁止传操作系统名;不得继承任何前序版本结论 check只认helix@helixharness-marketplace,自动识别正式安装、处理缓存、刷新同一 marketplace 并动态解析其 plugin source;禁止手工调用 plugin list、读取 CHANGELOG 或猜测版本- 严格按脚本最终
next_action执行:continue_silently静默;prompt_update弹框;block_for_update阻断;continue_with_warning只原样输出脚本warning后继续 update_status=latest|current-newer或有效skip_effective=true时必须静默继续;用户刚选择跳过后也不输出 WARN- 快速检查绝不自动安装;选择升级时进入
/helix:update的弹框确认与一次性授权流程
参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
--knowledge <path> | 导入外部知识库文档 | /helix:init --knowledge ./knowledge-seed/ |
--workspace | 初始化多 git 仓库 workspace | /helix:init --workspace |
--repos <paths...> | workspace 初始化时显式指定 repo 路径 | /helix:init --workspace --repos ../order-api ../coupon-api ./web-console |
--refresh | workspace 已初始化时强制重新扫描并刷新 registry 与服务关系基线(默认已 init 则幂等跳过) | /helix:init --workspace --refresh |
入口判断
解析 $ARGUMENTS:
- 含
--workspace→ 执行 Workspace 初始化 - 不含
--workspace→ 执行既有 服务仓库初始化
/helix:init --workspace 是 workspace 模式的唯一初始化入口;不要引入新的 /helix:workspace init 命令。
Workspace init 幂等
--workspace 模式下,进入 W0 之前先在当前工作目录根检查 helixharness.workspace.yaml 是否存在:
- 存在且未带
--refresh→ 视为已初始化,输出回执(如workspace 已初始化,跳过 init;如需刷新 registry 与服务关系基线请加 --refresh)后立即结束,不执行 W0/W1/W2,不刷新任何产物。 - 不存在,或带
--refresh→ 正常执行 W0→W1(含 W1.5 完成验收)→W2。
幂等判定只看 helixharness.workspace.yaml 单个文件;不在此重复检查 service-catalog/graph 等基线(实际执行 init 时由 W1.5 在 W1 之后兜底验收 8 项产物)。--refresh 是刷新 workspace registry 与服务关系基线的唯一入口;默认(无 --refresh)幂等跳过。
Workspace 初始化
Workspace 初始化只在当前工作区根目录执行,目标是建立多仓协调层,不替代各 repo 的单仓 HelixHarness 初始化。
Step W0:发现 repo registry
按以下顺序发现 repo:
- 若传入
--repos <paths...>,只扫描这些路径。 - 否则扫描当前目录下一层包含
.git的目录。 - 对每个 repo 读取:
- repo key:默认使用目录名,若冲突则停止并要求用户确认命名
pathgit remote -v- 当前分支与默认分支
- 是否存在
docs/knowledge/service-meta.yaml - 是否存在当前 Host Kit 的
entry_file - README、package name、pom artifact、go module、部署配置中的服务名线索
生成或刷新:
helixharness.workspace.yaml
该文件只作为 repo registry,不写完整系统知识。完整服务关系写入 docs/knowledge/。
Step W1:workspace bootstrap
调用 Agent tool,完整读取 agents/init-workspace-bootstrap.md,传入 workspace 根目录、原始参数、
明确 repo 列表和每个 repo 的初始化状态;任何 repo-local 写入都视为失败。
Workspace 初始化目标产物:
- Host Kit 的
entry_file helixharness.workspace.yamldocs/knowledge/service-catalog.yamldocs/knowledge/service-graph.mddocs/knowledge/integration-boundaries.mddocs/knowledge/index.mddocs/specs/active/docs/specs/completed/
Step W1.1:repo-local 初始化状态处理
如果 workspace 中的各 repo 已经存在以下任一 HelixHarness 产物:
- 当前 Host Kit 的
entry_file docs/harness/docs/knowledge/docs/knowledge/service-meta.yaml(仅后端、未知或全量全栈模式)docs/specs/active/和docs/specs/completed/docs/hooks/
/helix:init --workspace 只能读取这些 repo-local 产物作为输入,用于生成 workspace registry、service catalog 和 service graph。不得重新生成、覆盖、刷新或迁移任何 repo-local HelixHarness 初始化内容。
如果某个 repo 尚未初始化,在 helixharness.workspace.yaml 中列表记录。初始化判定必须同时满足:
- 当前 Host Kit 的
{repo}/{entry_file}存在且非空; {repo}/docs/harness/index.md与{repo}/docs/knowledge/index.md存在且非空;{repo}/docs/specs/active/与{repo}/docs/specs/completed/是真实目录。
docs/knowledge/service-meta.yaml 只作为服务元数据增强项:存在时记录相对路径,不存在时写
service_meta:null。纯前端 repo 不生成 service-meta 是合法状态,不能因此把已完成 init 的前端仓标为
initialized:false。遍历完所有 repo 后:
- 全部已 init → 直接继续。
- 存在未 init 的 repo → 列出每个 repo 缺失的入口/index/specs 事实,向用户确认:"以下 repo 尚未完成当前宿主的单仓 init:{列表}。是否现在执行单仓
/helix:init?(init 会扫描代码、生成docs/harness、docs/knowledge与入口,供 workspace 级命令使用)"- 用户确认 → 逐个(串行)进入对应 repo 目录执行
/helix:init(走单仓 scan + bootstrap agent,不走 workspace init 逻辑);为每次单仓 Init 重新绑定ownership_root与本仓各 job 的read_scope,不得继承 workspace bootstrap 的全仓读取清单;完成后回写helixharness.workspace.yaml中该 repo 的initialized: true与service_meta,再继续。 - 用户拒绝或未确认 → 保持
initialized: false标记,继续(后续propose的 W1-5 仍会被拦截、再次询问确认)。
- 用户确认 → 逐个(串行)进入对应 repo 目录执行
不得在 workspace init 中静默跳过未 init repo 或自动进入 repo 执行单仓 init。
Step W1.5:workspace root 产物门禁
workspace bootstrap 完成后,顶层命令必须在当前工作目录根逐项检查以下产物是否真实存在:
./{entry_file}(来自 Host Kit)
./helixharness.workspace.yaml
./docs/knowledge/service-catalog.yaml
./docs/knowledge/service-graph.md
./docs/knowledge/integration-boundaries.md
./docs/knowledge/index.md
./docs/specs/active/
./docs/specs/completed/
若任一缺失,立即报告:
BLOCKED: workspace_init_outputs_missing
并列出缺失路径。不得把子 repo 下的 .helixharness/、docs/ 或 telemetry 文件视为 workspace root 产物。
/helix:init --workspace 的成功判定只看 workspace root 上述产物;每个服务 repo 下的 .helixharness/telemetry.json、.helixharness/upload-state.json 不属于 workspace 初始化目标。
Step W2:服务关系基线
/helix:init --workspace 必须在 init 阶段建立 baseline service graph,但不要求一次性完美。
信息来源包括:
- 各 repo 的
docs/knowledge/service-meta.yaml - OpenAPI / Swagger / RPC IDL
- Feign / HTTP client / Dubbo / gRPC 调用声明
- MQ topic producer / consumer
- 数据库表 ownership
- 部署配置、服务名、环境变量
- README / 架构文档
不确定关系不能强行写死,必须进入 uncertain_edges,包含:
confidence: low|medium|high
needs_confirmation: true
evidence: "{可追溯证据}"
若某个 repo 尚未执行单仓 /helix:init,只在 helixharness.workspace.yaml 中标记:
helix:
initialized: false
service_meta: null
不要在 workspace init 中自动进入该 repo 完整执行单仓初始化;如需初始化单个 repo,用户可在 repo 内执行 /helix:init。
Workspace 初始化完成后立即输出报告并停止;不得继续执行下方“服务仓库初始化”流程。
执行编排
服务仓库初始化
需要扫描时,knowledge 扫描必须由顶层命令显式编排并实际触发 Agent tool/子代理调用,不能只把“应当扫描”的要求下沉给 bootstrap agent 后就继续执行。
Step 0:单仓 Git 预检
进入本节前必须完成 runtime/source 检查、版本检查和入口判断。Workspace 根流程不执行本节。
确认 {repo_root} 是本次要初始化的目录;只读调用:
{helix_python} "{plugin_root}/scripts/init_greenfield.py" --repo-root "{repo_root}" probe
- 预检需要已通过 runtime preflight 的 Python。无法恢复时停止本单仓步骤,不猜测仓库状态。
- 脚本退出 2 并返回
reason时,输出对应BLOCKED:{reason}和detail,停止,不做仓库写入。 非 Git 目录请用户自行执行git init或切换到已有仓库;不要代为初始化或创建提交。 - 退出 0 后保留
empty判断并进入 Step 0.5。只有empty=true跳过 Step 1 的扫描。
Step 0.5:数据统计 consent(必须在任何业务写入或 bootstrap 前完成)
单仓服务/前端初始化按 reference/eval-protocol.md 的“数据统计开关与提醒缓存”解析当前平台缓存,并得到 effective_telemetry_mode=enabled|disabled。--workspace 只建立协调层、不创建 repo-local docs/eval/**,因此跳过本次 consent 交互,等待各 repo 单独 init 时处理。
在已支持宿主上,只要本步骤需要展示 consent/开启选项,必须先逐字呈现 reference/eval-protocol.md 中标识为 helixharness-eval-data-notice-v1 的唯一数据说明;本命令内保留如下受静态校验约束的同步副本,不得改写:
数据统计说明:默认关闭。开启后,HelixHarness 在 docs/eval/{feature}/eval-log.json 中记录当前 Git user.name(可用时)、工作流阶段、时间、状态、工件、质量和代码范围等固定事实;该账本可随业务代码提交,不保存原始会话 ID、对话、Token 或工具原始输入输出。
阶段记录本身不读取对话或调用模型。阶段结束后,异步 Runtime 按已授权的精确会话窗口采集 Token、工具及子任务统计和经过筛选脱敏的用户输入、助手回复;不上传 Thinking、原始源码、完整 Diff、附件或原始日志。Archive 冻结采集边界,后台仅处理冻结范围和待投数据,不同步调用会话 classifier。
无论是否配置异步地址,都按授权缓存和提醒周期正常询问统计授权。开启后同步记录本地账本,由平台本地读取或 Git 同步获取;异步采集和投递另需先启动 helixharness-platform,并使用发布脚本 reporting_config.py 中的有效默认地址,或统计私有目录 config.json 的 endpoint 覆盖地址。未配置或地址无效时只跳过异步采集和投递;未授权或关闭时不新增同步账本,也不异步采集或投递。统计和网络异常不阻塞研发。授权允许本机私有采集及向配置地址上报,不等于授权 Git commit 或 push;提交和推送仍由当前命令单独取得授权。关闭后停止新增采集,并由后续命令、Hook 或 Worker 清理未发送私有证据;已提交的历史账本不改写。
- Python 不可用时不调用 resolver、不展示统计说明或开启选项,也不读写 consent 缓存;遵循
reference/runtime-preflight.md恢复运行依赖。恢复并复检成功后从下述 resolve 重新开始。未恢复时,本次不启用统计,不影响无需 Python 的初始化步骤。Git 缺失优先 blocker。 - 调用
{helix_python} "{plugin_root}/scripts/telemetry_consent.py" --repo-root "{repo_root}" --platform "{canonical_host_id}" resolve;- 若
reason=endpoint_unconfigured,静默继续,不展示“地址未配置”“未异步上报”等状态提示,也不主动要求配置;不能跳过下述统计问询。endpoint_invalid仍展示返回的 warning。按prompt_due和allowed_actions处理授权,用户确认后正常调用 choose。
- 若
- 若
prompt_due=true,在创建docs/eval/**、修改.gitignore或调用 bootstrap 前,先展示上述固定数据说明,再提示用户。Consent 子问题必须逐项使用 resolver 的有序allowed_actions[],保持 label 原文和顺序;可以与其他初始化问题合并展示,但不得压缩为通用“开启/关闭”或丢失 project/user scope。 - 若当前有效状态为
enabled且prompt_due=true,询问:保持当前统计范围开启 / 关闭当前项目统计 / 关闭我本人统计。 - 收到用户选择后调用
choose --action {allowed_action.id} --user-confirmed,由脚本完成 scope/mode 映射;推荐项、默认项和 Agent 自主判断都不构成确认。保持关闭后 30 天、保持开启后 180 天内不再提示。禁止直接写缓存 JSON。 choose后保存脚本返回的真实effective_mode并展示 notice/warning。Init 不创建统计 Entry 或追加 eval 跟踪规则;后续需求阶段由 recorder 按有效授权自行准备 Ledger 的 Git 跟踪。- 后续 service/frontend bootstrap 都必须接收
effective_telemetry_mode,不得自行按默认 disabled 重新判断或再次询问。 disabled时,本次 init 从开始到结束都不得新建docs/eval/**或追加 eval.gitignore例外;历史文件不删除。
Step 0.6:确定扫描模式
统计模式已解析后,按 Step 0 的回执确定模式:
-
empty=true:调用下列命令记录状态。成功后进入 Step 1 的免扫描分支;不得派发后端或前端扫描任务。{helix_python} "{plugin_root}/scripts/init_greenfield.py" --repo-root "{repo_root}" prepare退出非零时按回执阻断。若期间已出现项目文件,重新开始正常检测,不覆盖已有状态。
-
empty=false:执行reference/project-type-detection.md的原有类型检测,写入 state,再按原分支编排扫描。 检测结果仍可能为unknown;unknown不等于empty。
Step 1:knowledge 扫描编排
读取 Step 0.6 生成的项目类型检测结果,按类型执行不同扫描 pipeline:
STATE_FILE="docs/.helixharness-init-state.json"
PROJECT_TYPE=$(grep -o '"projectType":[^,]*' "$STATE_FILE" 2>/dev/null | cut -d'"' -f4 || echo "unknown")
分支 0: 空仓库 — projectType=empty 时保留 scanPlan=[] 和 scanStatus=skipped,不调用扫描 agent;继续 Step 2。
分支 1: 后端 / 未知项目 — 执行原后端完整扫描流程
if [ "$PROJECT_TYPE" = "backend" ] || [ "$PROJECT_TYPE" = "unknown" ]; then
# ===== 原有后端扫描流程,100% 不变 =====
- 若 `$ARGUMENTS` 含 `--knowledge`:
- 不调用 `scan-tech` / `scan-db` / `scan-api` / `scan-service` / `scan-boundary` / `scan-service-meta`
- 由后续 bootstrap agent 读取外部知识源并生成 `docs/knowledge/` 入口索引
- 若 `$ARGUMENTS` 不含 `--knowledge`:
- 必须先并行实际调用以下三个 agent:
- `agents/scan-tech.md`
- `agents/scan-db.md`
- `agents/scan-api.md`
- 必须等待上述三个 agent 全部完成后,再实际调用 `agents/scan-service.md`。
- 必须等待 `scan-service` 完成后,再实际调用 `agents/scan-boundary.md`。
- 必须等待 `scan-service` 与 `scan-boundary` 完成后,再实际调用 `agents/scan-service-meta.md`。
- 每个 Agent 完成后检查其目标产物;任一 Agent 未实际触发成功或产物缺失时立即报告 BLOCKED。
**通用约束**:
- 若任一扫描 agent 未实际触发成功,立即停止并报告 BLOCKED,不得跳过后续依赖步骤
# ===== 原有后端扫描流程结束 =================
fi
分支 2: 纯前端项目 — 执行前端简化扫描流程
if [ "$PROJECT_TYPE" = "frontend" ]; then
echo "📱 检测为前端项目,执行前端优化扫描流程"
# 跳过: scan-db, scan-api, scan-service, scan-boundary, scan-service-meta
# 六路并行:
# scan-frontend-meta:元信息扫描(合并 tech + build + structure + style,串行 4 子任务)
# scan-frontend-api:API 调用清单
# scan-frontend-routes:路由配置
# scan-frontend-state:状态管理
# scan-frontend-components:组件清单
# scan-frontend-tracking:埋点检测(无埋点则直接退出,<2s)
# 顶层命令显式触发 6 个 Agent tool,并保持六路并行
# 这些 agent prompt 位于此 plugin 的 agents/ 目录下
# 通过公共 Read/Edit/Write 工具语义读取并更新 STATE_FILE;其他宿主按 resources.runtime 映射。
# 文件缺失或不是 JSON 对象时立即 BLOCKED:init_state_missing,不得跳过状态写入。
# 只把 scanPlan 设为六路前端任务数组,保留其余字段;写后重新 Read,确认 JSON 可解析且值一致。
# ⏱ 计时:Agent tool 返回的 duration_ms 为系统级 wall-clock(非 agent 自报),
# 直接以 {agent: seconds} 格式写入 stateFile.scanTimings 字段
# agent 不再写入 scan-timing 标签——所有计时由 init 编排层统一采集
fi
前端扫描编排:保持六路 Agent tool 并行。每个 Agent 只能写自身 prompt 声明的产物;父流程等待
全部 Agent 结束后统一写 timings,并逐项校验 architecture.md、build.md、structure.md、
style.md、api-endpoints.md、routes.md、state.md 和 components.md。tracking 未检测到埋点时
允许不生成 tracking.md,但 Agent 必须明确报告结果。
分支 3: 全栈 / Monorepo 项目 — 执行 Step 0.6 已确认的完整全栈 scan plan
if [ "$PROJECT_TYPE" = "fullstack-node" ] || [ "$PROJECT_TYPE" = "fullstack-separated" ] || [ "$PROJECT_TYPE" = "monorepo" ]; then
# Step 0.6 的 project-type-detection 已完成唯一一次用户确认:
# 仅前端/仅后端会把 PROJECT_TYPE 归一化为 frontend/backend;仍保留全栈标签只表示用户选择了全量扫描。
# 此处不得再次询问扫描模式,也不得改写已确认的 scanPlan。
# 后端 A 组三路并行,随后按 scan-service → scan-boundary → scan-service-meta 推进。
# frontend-api/routes/state/components/tracking 可与无写域冲突的后端 job 并行。
# init_scan_frontend_meta 额外依赖 init_scan_tech:scan-tech 先写 architecture.md,
# frontend-meta 随后只增量合并前端架构并写 build/structure/style,不得覆盖后端事实。
# 父流程等待 scanPlan 中全部 job 真实完成并逐项校验,再进入串行 fullstack bootstrap。
fi
Step 2:bootstrap 生成
根据 Step 1 的结果选择 bootstrap agent:
空仓库($PROJECT_TYPE = empty):
调用 init_service_bootstrap,传入 bootstrap_mode=greenfield、project-mode=greenfield、
已解析的 effective_telemetry_mode、空扫描产物列表、明确的读写范围和当前 Host Context。
派发前由父流程通过宿主交互确认项目目标、技术栈与运行/测试入口;用户暂未确定的字段标记 TODO。
显式传入 --knowledge 时仍由 bootstrap 按导入约定处理,只作为项目背景或已确认约束,不视为扫描证据。
本模式的最小产物按 Step 3 校验,不要求既有架构、API、数据库或 service-meta.yaml。
纯前端项目($PROJECT_TYPE = frontend):
- 读取 agent prompt:
agents/init-frontend-bootstrap.md - 调用
init_scan_frontend_meta时传入architecture_mode=frontend-create;无既有architecture.md时必须创建纯前端架构文档。 - 传递上下文:仓库根目录、原始参数
$ARGUMENTS、knowledge 扫描结果、当前平台、effective_telemetry_mode - 前端扫描任务全部完成并通过产物校验后,使用原有 Agent tool 调用语义执行该 bootstrap prompt。
后端项目($PROJECT_TYPE = backend / unknown):
使用原有 Agent tool 调用语义执行 agents/init-service-bootstrap.md。bootstrap Agent 按
resources.project_hooks 声明的 owner、merge strategy 和去重键增量合并当前
resources.project_config.settings_file;该字段为 null 时跳过设置写入。完成后必须逐项校验初始化目标产物,否则报告 BLOCKED。
完整全栈 bootstrap($PROJECT_TYPE = fullstack-node / fullstack-separated / monorepo,且用户选择完整全栈扫描):
- 先执行
agents/init-service-bootstrap.md,传入bootstrap_mode=fullstack-base,消费后端扫描 DAG,生成公共目录、后端 knowledge/harness、Host Kit 入口和可选设置。 init_scan_frontend_meta传入architecture_mode=fullstack-merge;它必须等待init_scan_tech并只更新前端架构区块。后端 bootstrap 真实完成并通过产物校验后,再执行agents/init-frontend-bootstrap.md,传入bootstrap_mode=fullstack-merge,消费六路前端扫描结果;只增量补充前端 knowledge/harness/linters 和同一个 Host Kit 入口区块,不覆盖 service bootstrap 已生成内容,也不因公共目录已存在再次询问是否更新。- 两个 bootstrap 绝对串行;最终同时校验后端必需产物、前端必需产物、唯一根索引、Host Kit 的
entry_file和可选 settings 去重结果。任一侧失败都不能把全栈 init 声称为完成。
初始化目标产物:
docs/harness/docs/knowledge/docs/knowledge/service-meta.yamldocs/specs/docs/hooks/docs/eval/(仅统计开启时).gitignore中的 HelixHarness eval 提交例外块(仅统计开启时)- Host Kit 的
entry_file - Host Kit 的
settings_file(非 null 时必须存在,包含project_hooks.payload且无重复)
Step 3:统一初始化产物校验
单仓(greenfield/service/frontend/fullstack)的父流程不能只检查目录存在。除上方目标清单外,必须确认
docs/harness/index.md、docs/knowledge/index.md、docs/knowledge/project-context.md
均为非空文件;project-context.md 内容按当前项目类型对应的 bootstrap 模板逐项核对,
未知项明确标注待确认,不得补造事实或向前端套用服务端字段。知识根索引必须以 Markdown 链接或
三列表格第一列的相对路径直接索引该文件,供 Propose/Apply 加载。
缺失时把准确路径回传给原 bootstrap agent 补齐,由父流程重新核验;未补齐前报告
BLOCKED: init_required_artifact_missing,不得凭 bootstrap 的完成回执跳过检查。
bootstrap 达到真实终态后,父流程必须逐项检查上述初始化目标产物清单,并确认入口文件、知识索引、 目录和可选 settings 合并结果符合当前模式。任一必需产物缺失或为空时沿用既有产物门禁收口;不得以 额外 Python validator 替代逐项检查。
项目 hooks 是完成门禁的一部分,不能以 bootstrap 的 parent-owned 或合并请求代替实际文件:
resources.project_hooks.owner=parent时,父流程在 bootstrap 返回后执行{helix_python} "{plugin_root}/scripts/project_hooks_cli.py" --repo-root {repo_root} --platform {canonical_host_id} merge。owner=bootstrap时由 bootstrap 按原有宿主写入权限执行同一merge命令;父流程不得绕过宿主配置权限。- 两种 owner 均由父流程执行同一路径的
check,核对实际 settings 的必需 hook、去重与 JSON 结构;settings_file=null时工具返回明确 skipped。任何缺失、冲突或检查失败均报告BLOCKED: project_hooks_incomplete,保留其他已生成工件,不得报告 Init 完成。
绿地额外验收:project-context.md 必须明确 project-mode: greenfield,未知事实保留 TODO。
只有目标产物、项目 hooks 和下方统计目录门禁均通过后,由父流程执行以下命令收尾;bootstrap 不写本模式的 state:
{helix_python} "{plugin_root}/scripts/init_greenfield.py" --repo-root "{repo_root}" complete
收尾回执必须为 projectType=empty、scanPlan=[]、scanStatus=skipped 和 bootstrapStatus=completed;
失败按脚本 reason 阻断。不得把跳过的扫描记为完成。
Usage Telemetry
/helix:init 只建立 HelixHarness 工作区基础目录和配置,不写入 usage telemetry。平台侧采用情况由已提交的需求级 eval-log 聚合判断。
Consent、repo 命名和扫描模式选择只服务初始化,不属于任何 feature;不得为了记录这些选择创建 eval entry、调用模型或把事件延迟混入后续 feature。
数据统计开关必须使用 Step 0.5 已解析并传入 bootstrap 的 effective_telemetry_mode;此处不得在产物生成后才首次询问,也不得让 bootstrap 自行回退到默认 disabled。后续通过 scripts/telemetry_consent.py resolve/choose 管理项目统计授权。
完成门禁:
- 若统计保持开启,
/helix:init结束前必须确认docs/eval/目录存在 - 若统计保持开启,
/helix:init结束前必须确认.gitignore允许提交docs/eval/**;若仍被忽略,输出WARN:usage_telemetry_gitignored - 若用户关闭统计,不创建新的 eval-log,不追加 eval
.gitignore例外块;已存在的历史docs/eval/**不删除
约束
- 命令文件只负责编排 — 详细生成流程统一下沉到 bootstrap agents
- 生成的
docs/knowledge/必须支持后续命令按需加载 — 生成唯一根索引docs/knowledge/index.md,直接索引所有叶子文件(含子目录下的),后续命令按reference/loading-protocol.md协议按需加载 - 不捏造信息 — 无法确认的内容必须标
<!-- TODO: 待确认 -->
宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol、resources.project_config、resources.project_hooks。
/helix:propose
HelixHarness 公共命令唯一契约:本文件只负责公共入口、确定性路由和路由结果消费。业务正文由 Router 返回的唯一
workflow文件承载,不在这里复制单仓或 Workspace 步骤。
Runtime 硬门禁:在任何 Python 调用、需求工件读取或路由判断前,完整读取并执行
reference/runtime-preflight.md。Python 不可用时按其中的恢复规则处理;安装并复检成功后才从下方 Router 继续,暂不安装或失败则输出BLOCKED:helixharness_python_runtime_unavailable。
User Input
$ARGUMENTS
1. 只执行一次确定性路由
把 $ARGUMENTS 原样按当前 shell 的单参数规则安全引用,然后执行:
{helix_python} "{plugin_root}/scripts/workflow_router.py" --repo-root "{repo_root}" route --command propose --arguments={SHELL_QUOTED_ARGUMENTS} --arguments-mode auto
{plugin_root} 必须来自当前 plugin command resource,{repo_root} 是当前仓库根。不得使用 eval 或拼接未经引用的用户文本。除上述 Runtime preflight 外,不得在路由前自行读取 Spec/Tasks、扫描 active/completed 目录或猜测阶段。
auto 模式沿用原版名称识别:首个 ASCII 名称 token、引号包裹的名称、feature=... 或 需求名:... 明确指定 feature;没有明确名称的自然语言只作为需求。补名后必须保留需求正文,名称与已绑定上下文冲突时停止。无参数时由 Router 返回唯一已有需求或候选,不自行扫描。
业务正文只接收 Router 返回的 shell-safe workflow_arguments,不重新解析原始 $ARGUMENTS。-- 后全部视为字面需求;--loop、--revise 由 Router 消费并剥离。旧版本迁移及需求地址参数不属于当前合同。
2. 只按 action 消费 JSON
退出码 0 或 2 且 stdout 是有效 JSON 时都按 action 处理;只有进程异常、无有效 JSON 或未知 action 才输出 BLOCKED:workflow_router_failed,不得退回模型推断。
load_workflow或repair_feature:完整读取workflow指向的唯一workflows/single/*.md或workflows/workspace/*.md正文并执行,传递feature、execution_scope、workflow_arguments、可选的revision_requested/workspace_revision与调用 trigger。不得改写路径、同时加载另一 scope、重新判断流程或递归调用公共入口。recommend_command:原样展示 recommendation 并停止,不读取工作流正文。select_feature:只展示 candidates 让用户选择;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑。不得按顺序、修改时间或语义相似度代选。blocked且reason=feature_required:只请求明确的 feature 名;回答后保留原始参数,追加--feature "{用户确认的 feature}"重跑,不把缺少名称当成不可恢复错误。- 其他
blocked:输出BLOCKED:{reason}后停止,不读取工作流正文,不迁移或覆盖冲突工件。
公共命令不写业务工件;只有所选工作流可按自身合同写入。宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol。
用法
/helix:propose <name> <requirement-or-path> [--loop]
/helix:propose <name> --loop
/helix:propose <name> <revised-requirement-or-path> --revise [--loop]
需求来源可为用户文本、文件或可访问 URL。现有 planning 需求可以不重复提供来源。Workspace 由根 helixharness.workspace.yaml 确定,不能从需求文字猜仓库。
--revise 只用于明确修订未归档的 Workspace 需求,必须提供新的需求来源;它重新进入
Workspace Propose 的决策树,不能直接视为新合同已确认,也不重开归档中的需求。
已完成子仓的旧任务和原始 Apply 基线通过受控 Repair 机制保留。普通重复 Propose
不隐式修订合同;Single 需求的修订仍使用 /helix:bug-fix。
--loop
loop_requested=true 时按 Router 返回的 stage 与唯一 workflow 执行 Propose、Apply 或 Archive;以 trigger=loop 进入正文,不嵌套调用公共 Apply/Archive。每阶段成功后重新调用本入口的 Router,参数为 <name> --loop,继续第一个未完成阶段。新需求从 Propose 开始,已 ready 从 Apply 恢复,有效 implemented 证据从 Archive 恢复。
循环只编排这三个阶段。需求取舍与真实失败仍按阶段协议处理;不得跳过 TDD、双轴 Review、证据门禁或用户确有必要作出的决定。需求与测试 seam 已确认后,正常执行任务与归档无需再询问是否继续。失败或 blocked 时停止,保留可恢复状态。
Archive 的提交/推送选择必须按对应 Archive 正文保留;NOTICE:lite_telemetry_delivery_required 按正文仅在最终交付选择前原样展示一次,选择并执行后报告真实状态,不在循环完成摘要中重复提醒。--loop 不构成提交或推送授权;已有明确且覆盖当前精确范围的用户授权按正文复用,不重复询问。需要用户作出的 Archive 提交选择必须等待真实回答,发出问题不等于选择完成;不得把未回答当作“暂不提交”,也不得用完成摘要替代待回答的问题。具体提问与等待方式使用当前 Host Kit 的 ask_user 映射。
每个实际阶段写独立 Stage Entry,不创建 wrapper entry。阶段工件与证据决定续跑,禁止仅凭对话宣称完成。Archive 成功且 active 已移到 completed 后,不再次用 active 路由探测;只有对应正文要求的最终提交/推送选择已获回答并按选择处理,或按正文无需该选择时,才结束循环。业务归档完成但选择待回答时,保持“归档完成,提交/推送待选择”,不重复 move、start 或 finish,不重开已冻结的 Stage Entry。没有 --loop 时执行本次 Propose 后提示 Apply,不自动实现。循环不包含发布或部署。
HelixHarness 公共命令唯一契约:本文件承载 status 的全部业务步骤。所有宿主通过当前
resources.command_projection加载本文件,使用预绑定 Host Context;完整读取reference/workflow-projection-protocol.md、reference/host-runtime-protocol.md和当前resources.runtime。
在任何 Python 调用前执行
reference/runtime-preflight.md。本命令不触发版本刷新、统计询问、Stage start/finish、任务执行、索引修复或自动迁移。
User Input
$ARGUMENTS
参数
| 用法 | 行为 |
|---|---|
/helix:status | 列出当前仓库所有 active 需求,不要求用户先选一个 |
/helix:status <feature> | 查看指定需求;active 不存在时查 completed |
/helix:status --completed | 列出已归档目录中的需求并核验已有证据 |
/helix:status <feature> --completed | 只查指定已归档需求 |
按 shell token 精确解析可选 feature 和 --completed,未知参数报错,不猜测需求名或读取其他项目。配置查询引导到 /helix:config。
执行
{helix_python} "{plugin_root}/scripts/project_status.py" --repo-root "{repo_root}"
按实际参数追加 --feature "{feature}"、--completed,安全传参;只运行当前插件捆绑脚本。默认列出全部 active,不启动 Router 或其他命令。
用结构化输出展示简洁表格:需求、执行范围、记录阶段、已完成/总任务数、问题、建议命令。Workspace 展示各参与仓库的进度与依赖,不以根 Spec 状态替代子仓事实。
empty=true:说明查询范围内没有需求,不擅自 Init 或新建需求。tasks=null:展示“尚无任务数据/不适用”,不能当作 0/0 完成。issues是实际检查发现的问题;blocked_tasks只展示工件记录的任务与依赖,不编造阻塞原因。next_command是建议,不执行。存在问题时先说明需要处理的问题,不能把建议称为已通过所有执行门禁。archive_check=passed表示已有归档工件门禁通过;只有 completed 目录且检查通过才显示“已归档”。failed展示原始原因和对应工件位置,不自动改状态或退回 Apply。- 不重新运行测试或模型评审,不将 task completed、目录存在或摘要状态等同于测试通过。报告注明“依据已有工件检查,未重跑测试和评审”。
只读取规定的项目工件和门禁所需本地状态;不读取统计会话、网络服务或真实数据库,不修复、不写业务文件、不 commit/push。所有其他操作等待用户另行请求。
宿主资源声明:resources.runtime。
HelixHarness 公共命令唯一契约:本文件同时承载 update 的完整业务步骤和原生命令分发表面。所有宿主都必须通过当前
resources.command_projection加载本文件,并使用预绑定 Host Context;完整读取reference/workflow-projection-protocol.md、reference/host-runtime-protocol.md、当前resources.runtime和 Host Kit 声明的 version/update adapter,不得再读取其他 update command/workflow 补充业务语义。
Runtime 硬门禁:在任何
python3调用前,必须读取并执行reference/runtime-preflight.md。Python 不可用时输出受控 warning,不能直接调用版本脚本或暴露command not found。
参数宽容规则:解析
$ARGUMENTS时先按 shell token 分词;每个 token 仅去除尾部常见中英文句读(, . ; : ! ? ,。;:!?、及右侧闭合括号)后,再对 flag 做精确匹配。数值、枚举和路径参数使用同一规范化结果;不得使用任意子串匹配。
User Input
$ARGUMENTS
参数说明
| 参数 | 说明 | 示例 |
|---|---|---|
--check | 只检查版本并展示更新内容,不执行升级 | /helix:update --check |
--all | 更新适配器支持多安装范围时,升级它返回的全部已安装范围 | /helix:update --all |
--strict | 无法识别版本或正式来源时按阻断处理 | /helix:update --strict |
执行协议
读取此 plugin 捆绑的 reference/version-update-protocol.md,严格按该协议执行。所有正式来源识别、已安装范围、缓存位置、版本权威源和原生安装命令均由当前 Host Kit 的 version、update 适配器决定;核心命令不得按宿主 ID 分支,也不得自行推断这些值。
升级授权硬门禁:禁止 Agent 直接执行任何宿主的 plugin 安装或更新命令。
prepare返回正式的prompt.title/message/allowed_actions,交互框必须原样使用;用户选择通过decide --action处理。真正升级只能由scripts/version_update.py install调用当前 Host Kit 的更新适配器执行。推荐项、强制策略、缓存恢复或 Agent 自主判断都不能替代弹框确认。无交互环境输出BLOCKED:helixharness_update_confirmation_required,不得升级。
执行流程
Step 1:调用统一版本入口
{helix_python} "{plugin_root}/scripts/version_update.py" \
--platform {canonical_host_id} --repo-root {repo_root} check --force-refresh
canonical_host_id 必须取自预绑定 Host Context,禁止传 darwin/linux/windows 等操作系统名。
- 脚本必须从 Host Registry 解析当前宿主,动态加载清单声明的适配器。
unsupported_host + continue_silently时静默结束,不创建缓存、授权或提示。next_action=continue_with_warning时原样输出脚本warning;--strict额外将该状态作为阻断。- 不得绕过结构化结果,手工补造当前版本、最新版本、安装范围或升级路径。
Step 2:展示确定性检查结果
只使用 check 输出的结构化字段展示:
- 当前版本和最新版本;
- 当前安装范围;
- 是否推荐或强制升级;
- 当前版本到目标版本之间的完整 release notes;
- 跨版本路径是否包含
update_type=required。
如果已是最新版本,输出:
HelixHarness 已是最新版本,无需升级。
Step 3:执行统一授权状态机
如果传入 --check:
- 只展示版本状态和更新内容;
- 不创建升级 authorization,不执行
decide/install; - 允许版本入口按当前适配器声明的位置刷新检查缓存;
- 用户主动执行本命令或
--check时仍展示更新状态,不受跳过缓存抑制。
如果需要升级且未传 --check:
- 调用
prepare,--scope只能使用check返回且当前更新适配器声明支持的范围;--all只能选择适配器返回的全部已安装范围。 - 交互框原样使用
prompt.title/message/allowed_actions。 - 用户明确选择后调用
decide --challenge-id {id} --action {upgrade_now|skip_update} --user-confirmed。 - 只有
upgrade_now决策成功后,才能调用install --challenge-id {id};install是执行宿主原生更新动作的唯一入口。
skip_update 必须由 decide 保存推荐版本跳过状态,禁止直接改缓存。prepare、decide 或
install 任一步失败都不得声称已升级;required 更新按 BLOCKED:helixharness_update_required 收口,
recommended 更新报告真实失败并停止本次升级。缓存不可写时只原样展示脚本 warning,不得改写到
项目仓库。
推荐升级询问模板:
检测到 HelixHarness 有推荐更新:
- 当前版本:{current_version}
- 最新版本:{latest_version}
- 更新摘要:{summary}
是否现在升级?升级后需要重启当前编程平台或新开会话,本次流程会先暂停。
1. 现在升级
2. 跳过本次更新(出现新版本前不再提示)
如果升级路径包含强制策略:
- 不提供继续使用旧版本选项;
- 强制策略只能阻止继续使用旧版本,不能替代用户授权升级;
- 用户选择升级时,使用
prepare → decide(upgrade_now) → install一次性授权链路; - 用户选择跳过时,
decide(skip_update)取消 authorization,输出BLOCKED:helixharness_update_required并停止; - 无交互环境输出
BLOCKED:helixharness_update_confirmation_required并停止。
强制升级询问模板:
HelixHarness 当前版本必须升级后才能继续:
- 当前版本:{current_version}
- 最新版本:{latest_version}
- 强制原因:{required_reason}
是否立即升级?选择跳过后,本次 HelixHarness 流程将停止。
1. 立即升级
2. 跳过本次升级
Step 4:升级后提示
升级成功后输出:
HelixHarness 已更新。请重启当前编程平台或新开会话,让新的 /helix:* 命令和捆绑资源完全生效。
宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol。
HelixHarness 公共命令唯一契约:本文件同时承载 UT 的完整业务步骤和原生命令分发表面。所有宿主都必须通过当前
resources.command_projection加载本文件,并使用预绑定 Host Context;完整读取reference/workflow-projection-protocol.md、reference/host-runtime-protocol.md、reference/tool-semantics.md、当前resources.runtime、resources.ut和resources.subagent_protocol,不得再读取其他 UT command/workflow 补充业务语义。
UT 流程不变量:保持原命令 Phase 0—3、Agent 后台 worker、队列状态机、每类完整 6 Loop、失败重试、经验沉淀、主项目串行编译/测试/覆盖率和报告门禁。本文中的
Agent、Read、Write、Bash、AskUserQuestion使用reference/tool-semantics.md的公共工具语义;当前resources.ut只映射权限准备、物理派发、等待、容量、运行时 handle 与清理,不得减少 worker、业务步骤、证据或完成条件。
参数宽容规则:解析
$ARGUMENTS时先按 shell token 分词;每个 token 仅去除尾部常见中英文句读(, . ; : ! ? ,。;:!?、及右侧闭合括号)后,再对 flag 做精确匹配。feature、数值、枚举和路径参数使用同一规范化结果;不得使用任意子串匹配。
/helix:ut 命令执行手册
本文件是 UT 唯一完整业务事实源。reference/ut-business-protocol.md 只定义 adapter 可替换的运行机制
和不可降低边界,不能替代本文的扫描细则、状态机、6 Loop、缺陷、覆盖率、同步、恢复和报告契约。
所有宿主执行相同业务章节,并由当前 resources.ut 把本文的公共工具语义映射为真实能力。
User Input
$ARGUMENTS
参数说明
本命令支持两种入口:显式参数入口(
--packages与--concurrency一次给齐)和交互补全入口。 任一参数缺失或非法时,命令不退出:进入 Phase 1 后按 §4.2.0 扫描项目、展示候选包清单, 由用户选择包并指定并发;补全得到的值与显式传入完全等价。包名在执行模式为「继续执行」时可不 补全(沿用已有队列);并发数在所有执行模式下都必须最终确定(2 ≤ N ≤ MAX_CONCURRENCY,MAX_CONCURRENCY = 10)。
| 参数 | 必填 | 说明 | 示例 |
|---|---|---|---|
--packages <pkg1,pkg2,...> | 条件必填¹ | 指定目标包名集合(逗号分隔),仅扫描这些包及其子包下的源代码 | /helix:ut --packages com.example.service --concurrency 5 |
-p <pkg1,pkg2,...> | 条件必填¹ | --packages 的简写形式 | /helix:ut -p com.example.service -c 5 |
--concurrency <N> | 条件必填² | 单测维护 worker 并发数,必须是整数且 2 ≤ N ≤ MAX_CONCURRENCY(MAX_CONCURRENCY = 10) | /helix:ut --packages com.example.service --concurrency 5 |
-c <N> | 条件必填² | --concurrency 的简写形式 | /helix:ut -p com.example.service -c 5 |
| (无参数) | — | 进入 §4.2.0 交互补全:列出候选包清单,由用户选择并指定并发 | /helix:ut |
¹ 全新开始 / 增量补充模式必须最终确定包名集合:可显式传入,也可由 §4.2.0 交互选择补全;继续执行模式可不补全(沿用已有队列)。 ² 所有执行模式必须最终确定并发数:可显式传入,也可由 §4.2.0 交互输入补全。
参数解析与入口判断
解析 $ARGUMENTS:
第一步:参数提取(宽容提取,不校验必填、不退出)
-
检测
--packages或-p参数:- 从
$ARGUMENTS中提取--packages或-p后面的包名列表 - 包名用逗号分隔,去除空格,去重
- 示例:
--packages com.example.service, com.example.controller→["com.example.service", "com.example.controller"] - 找到且非空 → 记为
{packages_arg},状态已提供;未找到或提取后为空列表 →{packages_arg}状态未提供 - 不因缺失而退出:
未提供与后续步骤正常衔接,由 §4.2.0 按执行模式补全
- 从
-
检测
--concurrency或-c参数:- 从
$ARGUMENTS中提取--concurrency或-c后面的整数值 - 值为整数且
2 ≤ N ≤ MAX_CONCURRENCY(10)→ 记为{concurrency},状态已提供且合法 - 未找到 → 状态
未提供;值缺失、不是整数、小于 2 或大于 10 → 状态非法,并记录原始值(用于 §4.2.0.2 的提示语) - 不因缺失或非法而退出:与
未提供同路径,由 §4.2.0.2 补全
- 从
-
其他参数:目前不支持其他参数,如有未知参数可忽略或提示用户
参数补全入口协议
任一参数 未提供 或 非法 时,命令不退出、不输出提示码,继续执行第二步(执行模式判断)与 Phase 0;
在 Phase 1 入口由 §4.2.0 按所选执行模式补全仍缺的参数。补全得到的值与显式传入的值在整个后续流程中
完全等价(同一队列元数据、同一调度常量、同一门禁),同一轮执行内不再重复询问。
第二步:执行模式判断
进入 Phase 0 之前,先检查上次运行状态(§4.0)。此时第一步仅完成宽容提取,{concurrency} 可能尚未确定;如缺失或非法,由 §4.2.0 在进入 Phase 1 后补全,本步骤不因此退出:
-
存在残留文件(
unittest-session.md、unittest-queue.md、worker-*.md):- 读取上次会话信息
- 向用户展示当前状态
- 询问用户选择:继续执行 / 全新开始 / 增量补充
- 增量补充模式:包名可来自显式参数,也可由 §4.2.0 交互选择补全;本步骤不因包名未提供而退出
-
无残留文件:直接进入全新开始模式
第三步:增量补充模式特殊处理
若用户选择"增量补充":
- 包名集合或已由显式参数提供,或将在 §4.2.0.1 通过交互选择确定;确定后与已有队列中的包名合并(去重)
- 保留已有队列中已完成的任务
- 仅对新增包名执行扫描,生成新的 pending 任务
文档摘要
本文档定义 /helix:ut 命令的完整执行流程:
- 扫描项目代码,识别需要单测的类
- 调度
unit-test-worker并发处理单个类 - 汇总执行结果,主项目统一验证
- 临时资源和权限配置管理
核心原则:证据先于声明、发现缺陷不暂停、契约先于发挥、禁止修改业务源代码 架构模式:源外构建模式(直接使用主项目源码,零复制)
1. 核心原则与禁令
1.1 三条铁律
- 证据先于声明:必须展示实际输出才能声称完成
- 发现缺陷不暂停:Low/Medium 缺陷只记录并继续;High 高危 Bug 允许对应 worker 写完整失败结果后提前退出,ut.md 继续处理其他类
- 契约先于发挥:严格按知识库和本文档要求执行,不随意发挥
1.2 绝对禁令
| 禁令 | 说明 |
|---|---|
| ❌ 修改业务源代码 | 主项目源码只可读,不可写 |
| ❌ 修改项目配置文件 | application.yml、build.gradle、pom.xml 等 (项目无单测框架除外) |
| ❌ 在业务执行阶段询问用户问题 | 仅允许 §4.0 模式选择、§4.2.0 参数补全和 §4.2.4 任务清单确认三类业务门禁交互;Phase 2 及之后所有操作直接执行,零确认 |
| ❌ 因已有测试简化流程 | 即使主项目已有测试,也必须完整执行 |
| ❌ 用已有测试结果替代新验证 | 必须在临时目录重新编写并运行 |
| ❌ 在主项目执行构建命令 | 仅 Phase 2-5 统一验证阶段可执行 |
| ❌ 复制/修改敏感文件 | gradlew、gradle wrapper、mvnw 等文件禁止 cp、chmod、移动。调用构建工具时通过路径引用(worker 用绝对路径,主项目内用相对路径),不复制 |
2. 职责边界
2.1 ut.md vs unit-test-worker.md
| 职责项 | ut.md 负责 | unit-test-worker.md 负责 |
|---|---|---|
| 工作流管控 | ✅ 完全负责 | ❌ 不涉及 |
| 任务队列管理 | ✅ 完全负责 | ❌ 不涉及 |
| 并发调度 | ✅ 完全负责 | ❌ 不涉及 |
| 单个类单测生成 | ❌ 不涉及 | ✅ 完全负责 |
| 宿主权限/审批准备 | ✅ 通过 resources.ut 完全负责 | ❌ 只读,不修改 |
| 共享经验库访问 | ✅ 汇总或 parent_finalize 阶段串行合并 | ✅ Loop 0 完整读取;child_locked_append 时锁追加,parent_finalize 时只返回经验候选 |
| 主项目预编译 | ✅ 完全负责 | ❌ 不执行 |
| 主项目统一验证 | ✅ 完全负责 | ❌ 不执行主项目构建 |
| 全局临时资源清理 | ✅ 完全负责 | ✅ child_locked_append 仅清理自己持有的锁;parent_finalize 无锁动作 |
2.2 信号传递契约
- ut.md → worker:通过启动参数和 prompt 传递所有必要信息
- worker → ut.md:业务产物通过文件系统传递;物理终态由
resources.ut映射。支持原有后台 Agent 文件信号的宿主保持以下语义,其他宿主必须先取得真实wait_job终态再校验同一文件契约worker-{ID}-result.md存在 = worker 已完成(使用原子写协议:.tmp→mv)- 文件第一行 = 基础状态(
状态: 成功/状态: 失败) - 文件第二行(如存在)= 结构化子状态标记(
同步状态: 失败/退出原因: 高危Bug) 状态: 超时终止为 ut.md 内部使用(超时代写,仅 ut.md 写入此值,对应队列状态failed+备注: timeout)- ut.md 根据第一行判定队列终态:
状态: 成功→completed,状态: 失败(含状态: 超时终止)→failed;子状态信息记录到备注列
2.3 源外构建模式
核心原则:零复制,直接使用主项目源码,完全隔离构建
# 主项目(只读使用)
{主项目目录}/
├── build.gradle / pom.xml # 🔴 只读:worker 读取配置
├── src/main/java/ # 🔴 只读:worker 直接引用
└── build/classes/java/main/ # 🔴 只读:ut.md 预编译的产物
# 临时区(完全隔离)
{系统临时目录}/{ProjectName}/
├── .gradle-cache/ # 🔴 共享 Gradle 依赖缓存(持久,运行间复用,不在 Phase 2-5 删除)
├── .m2-repository/ # 🔴 共享 Maven 依赖缓存(持久,运行间复用,不在 Phase 2-5 删除)
├── worker-{ID1}/ # 🔴 完全隔离的工作区 1
│ ├── build.gradle # 最小化配置(引用主项目编译产物,指向共享缓存)
│ ├── src/test/java/ # 仅本 worker 的测试代码
│ ├── tmp/ # 独立 JVM 临时目录(-Djava.io.tmpdir)
│ └── build/ # 独立的编译输出
├── worker-{ID2}/ # 🔴 完全隔离的工作区 2
│ └── ...
---
**主项目(只读)**:`build.gradle/pom.xml`、`src/main/java/`、`build/classes/java/main/`
**临时区(隔离)**:`{系统临时目录}/{ProjectName}/` 下的 `worker-{ID}/` 独立工作区
**共享缓存**:`.gradle-cache/`、`.m2-repository/` 持久化,运行间复用
---
## 3. 跨平台临时目录设计
### 3.1 临时目录根路径选择
- macOS/Linux:优先 `$TMPDIR`,回退 `/tmp`
- Windows:优先 `%TEMP%`,回退 `%TMP%`
- 父流程解析为绝对路径后固定传入每个 Worker 的 `{系统临时目录}` 和 `{WorkerTempPath}`;Worker 不重新选择临时目录,权限检查、构建及清理均复用传入路径。
### 3.2 目录结构
- 格式:`{系统临时目录}/{ProjectName}/worker-{ID}/`
- 共享缓存:`{系统临时目录}/{ProjectName}/.gradle-cache/`、`.m2-repository/`
### 3.3 清理规则
- 只清理 `worker-*` 目录,保留共享缓存
- 使用跨平台删除方式,避免硬编码命令
---
## 4. Phase 0-3 完整流程
### 4.0 前置:执行模式确认与状态检测
**此步骤使用参数解析结果(见文档开头「参数解析与入口判断」)**
**前提**:第一步已完成宽容提取。`{concurrency}` 如已合法提供则作为最大并发常量贯穿后续所有 worker 调度;如未提供或非法,由 Phase 1 入口 §4.2.0 补全,本步骤不因此退出。
检查是否存在残留文件:`unittest-session.md`、`unittest-queue.md`、`worker-*.md`
**存在残留**:
- 读取上次会话信息,展示当前状态摘要
- 询问用户选择执行模式:
- **继续执行**:从上次中断处继续,保留已完成工作
- **全新开始**:清空所有状态,重新扫描
- **增量补充**:基于上次运行,新增指定包名的扫描任务(包名可显式提供,也可由 §4.2.0 交互选择补全)
- 记录用户选择,进入对应分支
**无残留**:
- 直接进入全新开始模式
- 使用参数解析得到的包名列表(如有)
### 4.1 Phase 0:前置检查与上下文加载
#### 4.1.1 前置清理与初始化(根据用户选择)
| 分支 | 操作 |
|------|------|
| **继续执行** | 清理临时目录;仅 `child_locked_append` 清理符合 §7 所有权/超时条件的残留锁目录,`parent_finalize` 不检查、不创建、不删除锁。恢复 archived worker 文件,重置 in_progress 任务为 pending,保留已有 failed 任务(由 Phase 2-3 重试机制处理)。**重试行检测**:扫描队列 `备注` 列中已有 `retry:*|orig:W{ID}` 的行,这些为重试任务已在队列中,Phase 2-3 不再为其原 `failed` 行创建新重试行。保留经验库和已有结果 |
| **全新开始** | 生成新会话 ID,清理旧会话托管权限,归档旧状态文件,初始化新会话文件,保留经验库 |
| **增量补充** | 验证包名集合(已由显式参数或 §4.2.0 交互选择确定),清理残留文件,恢复 archived worker 文件,重置 in_progress 任务 |
#### 4.1.2 阅读项目完整知识库
读取 `docs/harness/` 和 `docs/knowledge/` 下所有文件,整理为完整公共知识库传递给每个 agent。排除:`docs/specs/active/`、`docs/specs/completed/`、`docs/hooks/`
**输出**:
Phase 0-1:项目完整知识库加载
- docs/harness/:{N} 个文件
- docs/knowledge/:{N} 个文件
- 知识库总大小:约 {X} 行
#### 4.1.3 推导 Feature 名称
**Feature 名称 = 当前 git 分支名,`/` 替换为 `_`**。
执行命令 `git rev-parse --abbrev-ref HEAD` 获取当前分支名,将其中所有 `/` 字符替换为 `_`,作为 `{feature}`。
示例:
- 分支 `feature_unit_test_command_upgrade_v1` → feature = `feature_unit_test_command_upgrade_v1`
- 分支 `feature/unit-test` → feature = `feature_unit-test`
- 分支 `bugfix/order/timeout` → feature = `bugfix_order_timeout`
`{feature}` 贯穿整个 ut.md 执行流程,用于定位 `docs/specs/active/{feature}/` 下的所有工作文件。
#### 4.1.4 阅读当前活跃需求
读取 `docs/specs/active/{feature}/spec.md` 和 `design.md`(如存在)作为独立需求上下文。如目录不存在,创建 `docs/specs/active/{feature}/` 目录。
#### 4.1.5 检查项目测试基础设施
**推导项目名**:当前工作目录 basename,替换特殊字符为 `-`,转小写
**全新开始时**:清理跨平台临时目录中的残留 worker 目录(保留共享缓存)
检查内容:项目类型、测试框架、Lombok 配置、测试目录结构、覆盖率配置
#### 4.1.6 预编译主项目(所有模块)
**强制执行**:无论任何执行模式,进入 Phase 1 前必须确保主项目已预编译
**继续执行/增量补充快速路径**:验证编译产物目录存在,存在则跳过,否则重新编译
**目标**:预编译所有模块主源码,避免每个 worker 重复编译;**同时提前发现并解决Java版本等环境级问题**,确保worker启动后环境可用。
**只编译主源码,不编译测试**:
- Gradle:`./gradlew clean classes --no-daemon --no-parallel --no-watch-fs -q`(如无 wrapper 则使用 `gradle`)
- Maven:`./mvnw clean compile --batch-mode -q`(如无 wrapper 则使用 `mvn`)
验证:检查 `build/classes/java/main` 或 `target/classes` 目录存在
**关键责任**:
- Phase 0 预编译是确保 worker 环境可用的第一道防线
- 若预编译失败(如Java版本问题、依赖问题等),必须先解决问题再启动 worker
- worker 启动后,不再接受"环境问题"作为跳过门禁的理由
### 4.2 Phase 1:代码扫描与任务列表生成
**前提**:§4.1.6 预编译已成功完成
**使用参数解析结果**:包名列表从文档开头的「参数解析与入口判断」步骤获取
**入口**:如仍有参数缺口(包名或并发数 `未提供`/`非法` 且所选执行模式需要它),先执行 §4.2.0 参数补全;§4.2.1 的扫描结果在补全与后续过滤之间复用,不重复扫描。
| 分支 | 操作 |
|------|------|
| **继续执行** | 读取已有任务队列,输出当前进度(含 §4.2.0.1-续 队列内包进度表),等待用户确认(并发数缺失/非法时先经 §4.2.0.2 确认) |
| **增量补充** | 读取已有任务队列,仅对新包名(显式提供或 §4.2.0.1 选定)执行扫描,排除策略,合并任务队列 |
| **全新开始** | 执行扫描与 §4.2.2 排除策略(§4.2.0.1 已完成时直接复用其排除后结果),再应用包名过滤(显式或 §4.2.0.1 选定),生成任务列表,用户确认 |
**所有分支在用户确认与任务队列生成之前必须通过 §4.2.3 任务数上限校验(`MAX_PENDING_TASKS = 100`),超限即阻断命令。**
#### 4.2.0 参数补全(包名发现与并发确认,仅当所选模式仍有缺口时执行)
**触发条件(缺口矩阵)**:
| 执行模式 | 包名是否必需 | 并发是否必需 | 需要补全的组合 |
|----------|--------------|--------------|----------------|
| **继续执行** | 否(队列已存在) | 是 | 只缺并发 → 按 §4.2.0.1-续 展示队列内包进度后,执行 §4.2.0.2 |
| **全新开始** | 是 | 是 | 缺什么补什么;两者皆缺 → 先 §4.2.0.1 选包,再 §4.2.0.2 定并发 |
| **增量补充** | 是(可交互补全) | 是 | 同上 |
无任何缺口(所选模式需要的参数均已合法提供)时,本节交互部分整体跳过,直接进入 §4.2.1 既有流程;但**继续执行模式仍必须执行 §4.2.0.1-续 的队列内包进度展示**(纯展示、无询问),保证用户始终能区分队列中已有的包及其状态。
**统一交互形式(硬约束,适用于本节全部交互)**:
- 纯文本编号清单,**完整列出、禁止截断、禁止只列前 N 个**;不使用任何结构化选择器或选项数受限的提问工具,所有宿主行为一致
- **禁止代用户选择**:不得自动选第一个、任务数最多或最近使用过的包
- 用户以「序号」或「包名」回复后必须**回显确认**所选内容;用户可直接回复多个序号/包名(逗号或空格分隔),逐个解析、去重、按字母序确认
- 同一轮执行内每个缺口只询问一次;用户明确拒绝补全(如回复"取消")时输出当前进度说明并受控停止,不进入 Phase 2
##### 4.2.0.1 包名发现与选择(仅当所选模式仍需要包名且未提供)
**顺序契约(硬约束):扫描 → 排除 → 再交互。** §4.2.1 全量扫描(不做包名过滤)与 §4.2.2 七条排除规则完整结束之前,不得输出候选包清单、不得发起任何用户交互;清单中的「候选类数」「共 {N} 个包」及统计行一律为**排除后口径**(排除后候选类数为 0 的包不进入清单),用户永远不会面对含排除项的清单。
1. 执行 §4.2.1 扫描(全部源码,**不做包名过滤**)
2. 对扫描结果**完整执行** §4.2.2 七条排除规则
3. 按"包名"分组聚合,得到每个包的候选类计数;按包名字母序输出:
```text
📋 可选包清单(共 {N} 个,请回复序号或包名,可多选)
| 序号 | 包名 | 候选类数 | 备注 |
|:-----|:---------------------|---------:|:---------------|
| 1 | {package1} | {X} | |
| 2 | {package2} | {Y} | 已在当前队列 |
| ... | (全部列出,一个不漏,禁止截断) | | |
> 统计:扫描 {X} 个文件 → 排除 {Z} 个 → 候选 {Y} 个类,分布于 {N} 个包
> 执行模式:{全新开始/增量补充}
> 单次待调度任务上限:100 个类(§4.2.3 将在选定后校验)
请回复要维护的包(序号或包名,可多选)。
「备注」列仅在增量补充模式下标注 已在当前队列(该包在既有队列中已有任务行),其余场景留空;重复类仍由 §4.2.2.1 按文件路径去重,本标注仅为提示。
- 解析用户回复(序号/包名混用、逗号或空格分隔、去重)→ 得到
{packages}→ 回显确认:✅ 已选定包:{p1, p2, ...}(候选 {Y} 个类) - 扫描复用:本次扫描与排除结果保留复用,§4.2.2 之后的流程对同一结果应用所选包的前缀过滤,不得重新扫描(上下文截断恢复后如结果丢失,按本节重扫一次)
- 零候选兜底:排除后全项目候选类数为 0 → 输出以下提示并退出命令(无包可提供,不展示空清单、不询问并发):
ℹ️ 未发现需要单测维护的类
- 扫描文件:{X} 个 → 排除:{Z} 个 → 候选:0 个
- 已按 §4.2.2 排除测试代码、生成代码、接口、枚举、Mapper/DAO、配置类与纯数据载体
无可选包。请确认源码目录或包范围后重试。
4.2.0.1-续 继续执行模式的队列内包识别(仅继续执行模式,在 §4.2.0.2 之前执行)
继续执行模式不重新选包(沿用已有队列),但必须让用户区分出哪些包已在任务列表中及其当前状态:
- 读取队列并按包聚合:读取
unittest-queue.md全部任务行,按"包名"列分组统计各状态数量(completed/failed/in_progress/pending) - 输出队列内包进度表(按包名字母序,完整列出,禁止截断):
📦 当前任务队列中的包(共 {N} 个包 / {M} 个任务,继续执行沿用此队列)
| 序号 | 包名 | 总任务 | 已完成 | 失败 | 处理中 | 待处理 |
|:-----|:---------------------|------:|------:|----:|------:|------:|
| 1 | {package1} | {M1} | {C1} | {F1} | {I1} | {P1} |
| 2 | {package2} | {M2} | {C2} | {F2} | {I2} | {P2} |
| ... | (全部列出,一个不漏,禁止截断) | | | | | |
> 失败任务中可重试的将由 Phase 2-3 自动重试(timeout/critical_bug/retry_exhausted 除外)
> 继续执行不会新增队列之外的包;如需追加新包,请改用"增量补充"模式
{若用户显式传入了包名:⚠️ 你传入的 {p1, p2, ...} 不在当前队列中,继续执行不会处理它们;如需处理请改用"增量补充"模式}
- 显式包名核验:用户在继续执行模式下显式传入了
--packages时,将其与队列内包名集合比对——- 传入包全部/部分不在队列中 → 在上表后输出上述 ⚠️ 提示,逐个列出不在队列中的包名;不退出、不自动转增量、不代用户决定,仅提示正确做法
- 传入包全部已在队列中 → 无额外提示(继续执行本身就只处理队列内任务,包名仅作参考)
- 本小节为纯展示,不询问选择、不等待确认;输出后直接进入 §4.2.0.2(并发数仍缺失/非法时)或按 §4.2 分支表"继续执行"行继续
4.2.0.2 并发数确认(仅当 {concurrency} 未提供或非法)
- 在包名确定之后询问(即使包名来自显式参数),便于用户参考任务数:
⚙️ 请指定 worker 并发数
- 已选包:{p1, p2, ...}(候选 {Y} 个类){或:沿用已有任务队列(见上方 📦 队列内包进度表)}
- 有效范围:2 ≤ N ≤ 10(MAX_CONCURRENCY = 10)
{若原值非法:- 你传入的 "{原值}" 无效:{非整数/小于 2/大于 10},请重新指定}
请回复并发数(整数,2-10)。
- 回复为整数且
2 ≤ N ≤ 10→ 记为{concurrency},回显确认:✅ 并发数:{N} - 重试规则:非法回复 → 输出
❌ 无效并发数 "{回复}",必须为 2-10 的整数并重新展示同一提示;连续 3 次非法后输出以下指引并受控停止(不设默认值、不静默取中值):
❌ 连续 3 次未获得有效并发数,命令停止。
- 用法:/helix:ut --packages <pkg1,pkg2,...> --concurrency <N>
- --concurrency:整数,2 ≤ N ≤ 10
- 示例:/helix:ut --packages com.example.service --concurrency 5
- 并发数一经确定(显式或补全),写入队列元数据(§9.4
worker 并发数),上下文截断恢复后沿用此值调度
4.2.0.3 补全完成后的衔接
{packages} 与 {concurrency} 视同显式传入,继续 §4.2.2 之后的排除/增量去重/门禁/确认流程;§4.2.3 任务数上限校验与 §4.2.4 任务清单确认的行为均不变。包选择回答"扫哪些包",任务清单确认回答"这批类对不对",两者是相互独立的业务门禁,不得合并或互相替代。
4.2.1 扫描所有源代码文件
-
扫描范围:
- 按语言扩展名扫描:
**/*.java、**/*.py、**/*.ts、**/*.js、**/*.go - 按源码目录扫描:
src/main/**/*、app/**/*、lib/**/*、internal/**/*
- 按语言扩展名扫描:
-
去重与排序:
- 去重重复的文件路径
- 按文件路径字母顺序排序
-
提取信息:
- 从文件中提取类名、文件路径、包名
- 不同语言的包名提取方式:
- Java/Kotlin:从
package声明提取 - Python:从目录结构映射
- JS/TS:从目录或
package.json提取 - Go:相对
go.mod的路径
- Java/Kotlin:从
-
包名过滤:
- 仅保留包名以指定包名开头的类。指定包名或来自显式参数,或来自 §4.2.0.1 的交互选择;未指定(继续执行模式沿用已有队列)时不过滤,直接进入排除策略
- 显式参数可在扫描阶段即限定范围(见「参数说明」的仅扫描指定包及其子包);§4.2.0.1 交互选定的包名按其步骤 5 在 §4.2.2 排除结果上做前缀过滤,不重新扫描,不改变排除后口径
4.2.2 执行排除策略
按以下顺序排除,满足任一条件即排除:
| 排除顺序 | 排除标准 | 判断依据 |
|---|---|---|
| 1 | 测试代码 | 文件路径包含 src/test/、/tests/、__tests/ |
| 2 | 自动生成 | 文件内容注释包含 @Generated、@AutoGenerated、generated by、DO NOT EDIT |
| 3 | 接口类 | 类定义包含 interface 关键字(Java/TypeScript),或 type 定义且只有方法签名(Go) |
| 4 | 枚举类 | 类定义包含 enum 关键字(Java/TypeScript),或类继承自 Enum(Python),或文件中包含 const 且全大写常量组(Go) |
| 5 | Mapper/DAO(Java) | 文件名包含 Mapper、Dao、DAO,或类注解包含 @Mapper、@Repository |
| 6 | 配置/启动类(Java) | 类注解包含 @Configuration、@SpringBootApplication、@EnableAutoConfiguration |
| 7 | 纯数据载体 | 类名以 DTO、VO、PO、BO、DO、Query、Req、Res、Request、Response 结尾,且只有 getter/setter/toString/equals/hashCode/构造函数 |
4.2.2.1 增量补充去重(仅增量补充模式)
合并前按文件路径对已有队列和新扫描结果去重:文件路径已在队列中存在的类不加入新任务列表。去重后再执行合并。
4.2.3 任务数上限校验(用户确认与队列生成之前的强制门禁,所有执行模式)
常量:MAX_PENDING_TASKS = 100
校验时机:扫描、排除策略、包名过滤和增量去重完成之后,任务列表展示与用户确认(§4.2.4)之前、任务队列文件生成之前。所有执行模式(全新开始/继续执行/增量补充)都必须执行本校验;校验失败时用户根本不会被询问确认,队列也不会被创建或修改。
待调度任务总数按执行模式计算:
| 分支 | 待调度任务总数 |
|---|---|
| 全新开始 | 本次扫描生成的任务列表中所有类 |
| 继续执行 | 队列中所有非终态任务(pending + in_progress,含超时/孤儿对账后仍需处理的任务) |
| 增量补充 | 已有队列中的非终态任务(存量待执行)+ 本次新包名扫描去重后的新增任务 |
注意:failed(含 timeout、critical_bug、retry_exhausted)为终态,不计入待调度总数;Phase 2-3 的重试任务由本次执行内部创建,不参与本校验。
校验失败(总数 > 100)时的阻断协议:
- 输出以下提示:
❌ 任务数超限:当前待调度任务共 {N} 个,超过单次执行上限 MAX_PENDING_TASKS = 100 个,命令已阻断。
- 执行模式:{全新开始/继续执行/增量补充}
- 本次扫描新增任务:{X} 个
- 存量待执行任务:{Y} 个
- 包名范围:{package1, package2, ...}
请缩小包名范围(指定更具体的子包,或重新执行并选择更小的包集合,可显式传参或交互选择)后重试,确保单次待调度任务总数不超过 100 个类。
- 直接退出命令:不生成任务列表确认输出、不初始化/更新任务队列、不启动任何 worker、不执行 Phase 2-5、不生成汇总报告
- 增量补充模式阻断后,已有队列文件保持原状不受影响,用户可换更小的包名重新执行增量补充
- 继续执行模式如因遗留任务过多被阻断,建议用户改用更小范围的增量补充,或全新开始指定更小的包名
4.2.4 生成任务列表并确认(仅全新开始)
前提:已通过 §4.2.3 任务数上限校验(待调度任务总数 ≤ 100)。
任务排序:按文件路径字母顺序排序
输出格式:
## 单测维护任务列表
| 序号 | 类名 | 包名 | 文件路径 | 备注 |
|------|------|------|----------|------|
| 1 | {Class} | {package} | {path} | |
> 统计:扫描 {X} 个文件 → 排除 {Z} 个 → 包名过滤 {F} 个 → 需单测 {Y} 个
> 指定包名:{package1, package2, ...}
> worker 并发数:{concurrency}(MAX_CONCURRENCY = 10)
> 任务数上限校验:通过({Y}/100)
> 显式传参路径:扫描范围已按 `--packages` 收窄,`包名过滤 {F}` 记 0(无再次过滤);交互选择路径:{F} 为对排除结果做前缀过滤剔除的类数
共识别 {Y} 个类需单测维护。回复"继续"开始处理,或指出遗漏/调整。
4.3 Phase 2:单测维护执行(Ralph Loop 动态并行)
4.3.1 Phase 2-1:初始化共享文件
| 分支 | 操作 |
|---|---|
| 继续执行 | 确保目录存在,验证主项目编译产物存在(缺失则重新执行 §4.1.6 预编译),托管权限,验证已有文件完整性,确定下一个 Worker ID |
| 全新开始 | 确保目录存在,会话文件已创建,初始化共享经验库;仅 child_locked_append 按 §7 确保锁目录不存在,parent_finalize 不检查、不创建、不删除锁。初始化空主结果文件,初始化任务队列,执行 §4.1.6 预编译,托管权限 |
| 增量补充 | 确保目录存在,验证主项目编译产物存在(缺失则重新执行 §4.1.6 预编译),托管权限,验证已有文件完整性,确定下一个 Worker ID |
关键:权限托管必须执行(见 §5)
4.3.2 Phase 2-2:Ralph Loop 动态并行调度
准入门禁:进入主循环前必须已通过 §4.2.3 任务数上限校验(待调度任务总数 ≤ MAX_PENDING_TASKS(100))。上下文截断后重新进入本阶段时,同样先按 §4.2.3 对队列非终态任务复核,超限则按阻断协议退出。
核心参数(公共 Agent 语义):
- 最大并发度 =
{concurrency}(由显式--concurrency参数或 §4.2.0.2 交互补全确定,2 ≤ N ≤ MAX_CONCURRENCY(10),作为常量应用于本节全部 worker 调度) - 任务超时时间 = 3600 秒(1 小时)
- 轮询间隔 = 2 秒
当前 resources.ut 声明 dispatch_mode=background_agent 时原样使用以上参数、文件轮询和 Agent ID;
声明 dispatch_mode=native_job 时由 adapter 映射 spawn_job/wait_job、真实容量和 runtime handle,
不得把容量暂满当能力不可用,也不得用固定文件轮询替代原生终态。两种模式的逻辑 Worker ID、
任务顺序、队列状态、3600 秒业务超时结果、重试与产物校验保持一致。
下方“主循环流程”的动态槽位(容量 = {concurrency},上限 10)、active_slots.agent_id、result 文件轮询和 2 秒等待只属于
dispatch_mode=background_agent 的后台执行机制。dispatch_mode=native_job 必须保持同一逻辑
队列状态机,但 ready job 的准入数量、runtime handle 和等待完全使用 adapter 的真实
dispatch_worker/wait_worker:不预计算固定槽位,不把 handle 写入队列,不用文件出现代替原生终态;
每个 job 终态后仍校验相同 result/defects、目标测试文件、6 Loop、覆盖率和 write scope。
内存跟踪:active_slots({worker_id: {agent_id, start_time, class_name}}),记录当前活跃的后台 agent。可通过队列文件 in_progress 行重建,非事实来源,仅为当前循环会话的便利缓存。
真相源原则:队列文件(unittest-queue.md)是 worker 状态的唯一事实来源;active_slots 是性能缓存,任何分歧以队列文件为准。每次对账时从队列重建 active_slots,运行时的状态变更先更新 active_slots 再原子写队列。
队列原子更新:每次 worker 状态变化时,必须用原子写协议(§6.2)更新 unittest-queue.md:读队列 → 修改目标行 → 写 .tmp → mv 重命名。同一迭代中多个 worker 完成时合并为一次批量写入。写入时机:worker 启动、worker 完成、超时/孤儿处理、对账修正。
队列文件元数据头:队列文件在原有表格基础上增加元数据块(见 §9.4 模板),备注 列在需要时填入结构化信息(如 timeout、critical_bug、sync_failed、orphan_detected、retry_exhausted、retry:N|orig:W{ID}|reason:{text})。
dispatch_mode=background_agent 主循环物理流程(后台 Agent 适配):
-
循环启动对账(首次进入时执行一次;后续每 5 次迭代执行增量对账):
- 扫描
worker-*-result.md,与队列对账:result 文件存在但队列行状态为pending/in_progress→ 读首行和结构化第二行解析状态,原子更新队列行为对应终态 - 扫描
worker-*临时目录:无 result 文件且已超时的 → 执行超时协议(见下方超时处理) - 锁超时检查:仅
experience_write_mode=child_locked_append时检查unittest-experience.lock是否存在且创建时间超过 10 分钟 → 如满足 ut.md 锁清理条件(见 §7),则清理锁目录;parent_finalize跳过 - 从队列
in_progress行重建active_slots;Agent ID 丢失的设为"unknown"(后续通过轮询 result 文件检测完成) - 输出对账摘要:队列总数、已对账 result 文件数(含状态修正数)、孤儿目录数(含超时处理数)、活跃 worker 重建数、锁状态
- 扫描
-
检测已完成 worker:
- 遍历
active_slots,检查worker-{ID}-result.md是否存在 - 结果文件存在:
- 读取首行解析基础状态:
状态: 成功→ 队列状态设为completed。如第二行为同步状态: 失败,备注追加sync_failed状态: 失败→ 队列状态设为failed。如第二行为退出原因: 高危Bug,备注追加critical_bug状态: 超时终止→ 队列状态设为failed,备注追加timeout
- 原子更新队列(设结束时间),从
active_slots移除,输出进度
- 读取首行解析基础状态:
- 结果文件不存在且已超时(>3600s):
- 先复检避免竞态(文件可能刚好写入)
- 不存在则原子写超时 result 文件(首行
状态: 超时终止),队列标记failed+备注: timeout,从active_slots移除,输出超时警告
- 遍历
-
填充空闲槽位:
- 可用槽位 =
{concurrency} - len(active_slots) - 从队列取最多
slots个pending任务(按序号升序) - 对每个任务:分配单调递增 Worker ID(永不重用)→ 启动后台 agent(
run_in_background: true)→ 原子更新队列(pending→in_progress,记录 Worker ID、开始时间、Agent ID)→ 加入active_slots - 输出:
[启动] Worker-{ID} 开始处理 {ClassName}({N}/{Total})
- 可用槽位 =
-
检查退出条件:
- 终态:
completed、failed - 非终态(继续):
pending、in_progress - 队列中所有任务均为终态 → 退出循环,输出摘要,进入 Phase 2-3
- 仍有非终态 → 继续
- 终态:
-
输出进度,等待 2 秒后继续循环
进度输出:
[进度] 迭代#{N} | 已完成={completed} | 失败={failed} | 处理中={in_progress} | 待处理={pending}
阶段性维护报告(每完成 5 个类触发一次):
主循环内维护一个累计完成计数器;每当新完成(进入终态 completed 或 failed)的类数量跨过 5 的整数倍(第 5、10、15…个)时,在屏幕输出一份阶段性报告,包含整体进度和这 5 个类的维护情况。触发阈值的那次迭代中,若一次迭代内新增终态导致跨过多个阈值(如并发下同时完成 6 个),只输出一份报告,批次内容取最近 5 个新终态的类(从内存完成日志 completion_log 取最近 5 条)。
📊 阶段性维护报告(已完成 {X}/{Total} 个类)
整体进度:
- 已完成:{completed} | 失败:{failed} | 处理中:{in_progress} | 待处理:{pending}
- 完成率:{percent}%({X}/{Total})
- 当前并发:{len(active_slots)}/{concurrency}
本批 5 个类维护情况:
| # | 类名 | Worker ID | 状态 | 覆盖率 | 发现缺陷 | 备注 |
|---|------|-----------|------|--------|----------|------|
| 1 | {ClassName} | W{ID} | 成功/失败 | {X}% | {N} 个 | {sync_failed/critical_bug/无} |
| ... |
> 下一次报告将在累计完成数达到 {X+5} 时输出(或全部完成时)。
实现要点:
- 内存维护
completion_log(按完成时间顺序追加{Worker ID, 类名, 状态, 覆盖率, 缺陷数, 备注}),仅用于本报告,不是真相源(真相源仍为队列文件) - 覆盖率、缺陷数从对应
worker-{ID}-result.md的执行摘要表提取;提取失败时填- - 批次不足 5 个的尾部批次(总数非 5 的倍数时的最后一次)在主循环退出后并入 Phase 2-3 前的收尾输出,不单独触发
- 上下文截断恢复后,计数器从队列终态行数重建,已报告过的批次不重复输出
超时与孤儿处理:
- 超时协议(任务
in_progress> 3600s 无 result 文件):先复检避免竞态 → 原子写超时 result 文件(首行状态: 超时终止)→ 原子更新队列(状态:failed,备注: timeout)→ 从active_slots移除 → 输出警告。Phase 2-4 汇总时如 worker 已覆盖超时文件,以 worker 实际结果为准 - 孤儿 Worker(临时目录存在但无 result 文件,已超时):执行超时协议,
备注设为orphan_detected,不删除临时目录(Phase 2-5 统一清理) - 陈旧孤儿(临时目录存在但无队列条目、无 result 文件):记日志,Phase 2-5 清理
上下文截断恢复:
会话上下文截断后,active_slots 丢失但队列文件和 result 文件均在磁盘保留。Phase 2-2 重新进入时执行对账(步骤 0),从磁盘重建全部状态后继续循环。Agent ID 丢失的 worker 通过轮询 result 文件跟踪;临时目录也不存在的 in_progress 任务标记 failed(备注: lost_on_truncation)。
dispatch_mode=background_agent Agent 启动参数(后台 Agent 适配):
Agent 工具调用方式: 使用 Agent 工具启动后台 worker,参数如下:
Agent(
description="Worker-{ID}: 为 {ClassName} 生成/维护单元测试",
prompt="""你是 unit-test-worker agent。请按照 agents/unit-test-worker.md 的指引执行任务。
输入:
- 目标类文件路径:{path}
- Worker ID:{ID}
- 项目名:{ProjectName}
- 主项目路径:{MainProjectPath}
- 系统临时目录:{系统临时目录的绝对路径}
- Worker 临时目录:{WorkerTempPath}(父流程解析的 `{系统临时目录}/{ProjectName}/worker-{ID}/` 绝对路径)
- 主项目编译产物路径:{MainProjectPath}/build/classes/java/main 或 {MainProjectPath}/target/classes
- 共享经验库路径:docs/specs/active/{feature}/unittest-experience.md
- 共享经验库锁目录:docs/specs/active/{feature}/unittest-experience.lock(`child_locked_append` 使用;
`parent_finalize` 只把它列为 forbidden scope,不检查、不创建、不删除)
- 独立输出文件:
- 结果文件:docs/specs/active/{feature}/worker-{ID}-result.md
- 缺陷文件:docs/specs/active/{feature}/worker-{ID}-defects.md
- Feature 上下文:{feature}
- 是否为重试:{否/是}
- 重试次数:{0/1/2}
- 原Worker ID:{无/原ID}
- 之前失败原因:{无/描述}
公共知识库(来自 docs/harness/ 和 docs/knowledge/ 完整内容):
[插入完整的项目知识库内容]
需求上下文(来自 docs/specs/active/{feature}/,独立于知识库):
[插入需求内容(如存在)]
开始执行。""",
run_in_background=true
)
关键要点:
description:简洁说明该 worker 的任务(包含 Worker ID 和类名)prompt:完整的 unit-test-worker 任务指令(见上方)run_in_background=true:在后台运行,不阻塞主循环- 返回的 Agent ID 需记录到队列和
active_slots中
dispatch_mode=native_job 等价映射:不得执行上方固定槽位、Agent ID 入队、2 秒文件轮询这些
物理步骤。父流程仍按同一排序为每个 pending 行分配单调递增 Worker ID,并把同一完整 prompt 交给
dispatch_worker(job);adapter 根据真实容量准入,runtime handle 仅保留在内存。wait_worker(handle)
返回真实终态后,父流程再按相同产物、写域、6 Loop、测试与覆盖率门禁原子更新队列。容量暂满只等待
可用事件,不能改成能力缺失、失败或 inline fallback;上下文恢复时无法证明仍有真实 job 的旧
in_progress 行重置为 pending,不得模拟 handle 或沿用陈旧 Agent ID。
4.3.3 Phase 2-3:失败重试机制
重试规则:
- 收集所有
状态 = failed的任务行 - 检查
备注列排除不应重试的:备注含timeout→ 不重试(ut.md 超时代写,非 worker 真实失败)备注含critical_bug→ 不重试(高危 Bug 阻断)备注含retry_exhausted或已有retry:2→ 不重试(已达上限)
- 其余
failed任务进入重试队列 - 最多重试 2 次(总共执行 3 次)
- 重试也采用并行方式(每批最多 3 个)
重试执行步骤:
- 读取队列文件,收集所有
状态 = failed的任务行 - 对每个
failed任务,在队列中新增一行(新序号,状态 = pending,备注写入retry:{N}|orig:W{原ID}|reason:{原失败原因}) - 将原
failed行暂时保留(Phase 2-4 汇总时归档) - 使用原子写协议(§6.2)写入所有新增行
- 返回 Phase 2-2,主循环将对新
pending行分配新 Worker ID 并启动
重试耗尽处理:
- 重试后仍失败的 worker,由 Phase 2-2 主循环标记为
failed - 当某任务重试次数已达上限(2 次),Phase 2-3 不再为其创建新
pending行,在原failed行的备注追加retry_exhausted
重试 Worker ID 分配:
- 重试任务由 Phase 2-2 主循环分配新的 Worker ID(永不复用原 ID)
- 启动参数必须包含:原Worker ID、重试次数、之前失败原因
4.3.4 Phase 2-4:汇总所有 worker 输出
执行步骤(单线程):
- 先收集缺陷文件:按 Worker ID 顺序检查
worker-{ID}-defects.md,存在则读取并暂存 - 再收集结果文件:按 Worker ID 顺序读取所有
worker-{ID}-result.md - 超时结果核验:对队列中
备注含timeout的任务,重新读取 result 文件首行,如 worker 已覆盖为成功/失败,以 worker 最新结果为准,并通过原子写协议更新队列中对应行的状态为completed或failed,清除备注中的timeout;即使仍为超时,也要检查 defects.md 是否存在 - 重试记录去重:对存在重试关系的任务(队列
备注列含retry:N|orig:W{ID}),按类名分组:- 同一类存在多条记录时,仅保留最终态的任务结果进入主文件(优先级:
completed>failed) - 被去重的行在队列
备注中追加(已归档),不在主结果文件中重复出现 - Worker 输出文件(result + defects)均按最终态 Worker ID 引用,原始失败 Worker 的文件在归档步骤中一并处理
- 同一类存在多条记录时,仅保留最终态的任务结果进入主文件(优先级:
- 汇总写入:将去重后的结果和缺陷汇总写入主文件
- 经验库校验:
child_locked_append读取unittest-experience.md并统计本次已追加经验;parent_finalize先校验各 worker final 的有界经验候选,再由父流程串行、去重、原子合并后统计 - 归档 worker 文件:将已汇总的 worker 文件(含被去重的原始失败文件)重命名为
archived-worker-*.md child_locked_append按 §7 清理符合条件的残留锁目录(使用跨平台删除方式);parent_finalize不检查、不创建、不删除任何经验锁
4.3.5 Phase 2-5:主项目统一验证(串行)
关键:这是唯一在主项目执行构建的阶段
执行步骤:
- 从临时目录恢复缺失的测试文件(如同步失败):
- 读取
备注含sync_failed或 result 文件第二行为同步状态: 失败的任务对应的 worker result 文件,提取「测试文件完整路径」和「临时目录备份路径」字段 - 从临时目录 Read 测试文件内容,Write 到主项目目标路径
- 验证文件存在性
- 读取
- 门禁 1:主项目编译验证:
- Gradle:
./gradlew clean compileTestJava --no-daemon --no-parallel --no-watch-fs -q(如无 wrapper 则使用gradle) - Maven:
./mvnw clean compile test-compile --batch-mode -q(如无 wrapper 则使用mvn)
- Gradle:
- 门禁 2:主项目测试运行:
- Gradle:
./gradlew test --no-daemon --no-parallel --no-watch-fs -q(如无 wrapper 则使用gradle) - Maven:
./mvnw test --batch-mode -q(如无 wrapper 则使用mvn)
- Gradle:
- 清理 worker 临时目录:删除
{系统临时目录}/{ProjectName}/worker-*(保留共享缓存) child_locked_append清理残留锁目录docs/specs/active/{feature}/unittest-experience.lock(如存在);parent_finalize不创建也不清理该锁
4.4 Phase 3:汇总报告与结果输出
4.4.1 生成汇总报告
输出文件:
docs/specs/active/{feature}/unittest-results.md- 单测执行结果docs/specs/active/{feature}/unittest-defects.md- 发现的逻辑缺陷docs/specs/active/{feature}/unittest-summary.md- 汇总报告
4.4.2 输出最终结果
4.4.3 清理宿主权限/审批准备(成功输出后)
仅执行成功时清理:调用当前 resources.ut 的 permission_cleanup。只撤销本次 UT 明确创建且
ownership 可验证的配置或临时授权,不删除用户已有配置,并把 adapter 返回的清理事实写入
unittest-session.md。不需要项目配置写入的 adapter 仍必须返回 permission_cleanup=not_required。
执行失败、中断、或有未完成任务:不清理托管权限
未执行主项目统一验证时不得报告 UT 完成;缺少本轮编译、测试、覆盖率验证的新鲜证据时同样不得报告完成。
5. 宿主权限与调度适配协议
所有执行模式都必须读取当前 resources.ut,并在 Phase 2 首个 worker 派发前完成下列逻辑动作:
permission_prepare(main_project, temp_root, required_tools):使 worker 能准备临时目录、生成和运行 测试、验证覆盖率、同步测试文件并写独立结果;不得绕过宿主 sandbox 或审批。dispatch_worker(job):把本文Agent(..., run_in_background=true)映射为真实派发;job 必须包含 Worker ID、agents/unit-test-worker.md、read_scope、写域、禁写域、预期产物和验证。read_scope 只能包含主项目被测源码/构建配置、目标测试文件、当前 UT session/queue 与已验证依赖结果; 临时副本路径必须先解析,禁止未解析 glob、其他 worker 私有目录或仓库外任意读取。wait_worker(handle):取得当前宿主认可的真实终态,再校验 result/defects、目标测试文件和写域。permission_cleanup(session_record):仅在 Phase 3 成功路径撤销本轮新增项;失败、中断或有未完成 任务时保留可恢复状态。
resources.ut 必须声明 dispatch_mode、experience_write_mode、runtime handle 是否允许写入队列、
权限准备和清理方式。支持原有项目配置与后台 Agent 的 adapter 必须完整保持配置追加不覆盖、
24 小时重新托管、系统临时目录与主项目绝对路径授权、成功后精确回收语义;具体项目路径和配置键
只存在于该 adapter,不进入公共命令。其他 adapter 使用当前宿主审批与原生 job 生命周期实现同一
业务结果,不能通过修改宿主全局配置、自动批准或模拟 Agent ID 达成。
6. 文件架构与状态机
6.1 文件架构
| 文件类型 | 命名模式 | 访问者 | 读写权限 | 说明 |
|---|---|---|---|---|
| 会话标识文件 | unittest-session.md | ut.md | ut.md 独占读写 | 记录当前会话 ID、开始时间、状态、托管权限 |
| 任务队列状态 | unittest-queue.md | ut.md | ut.md 独占读写 | 仅由 ut.md 主线程更新 |
| Worker 独立结果 | worker-{ID}-result.md | 对应 Worker + ut.md | Worker 独占写,ut.md 只读 | 每个 Worker 只写自己 ID 对应的文件 |
| Worker 独立缺陷 | worker-{ID}-defects.md | 对应 Worker + ut.md | Worker 独占写,ut.md 只读 | 每个 Worker 只写自己 ID 对应的文件 |
| 已归档 Worker 文件 | archived-worker-*.md | ut.md | ut.md 只读 | 汇总后不直接删除,重命名归档 |
| 共享经验库 | unittest-experience.md | 由 experience_write_mode 选择 Worker 锁追加或父流程串行合并 | Worker 始终可读;写入必须遵守 adapter | 永远不删除 |
| 经验库锁目录 | unittest-experience.lock | 仅 child_locked_append 的 Worker | 原子创建(mkdir)/ 删除(rm -rf) | parent_finalize 不创建 |
| 主结果文件 | unittest-results.md / unittest-defects.md / unittest-summary.md | ut.md | ut.md 独占读写 | 仅由 ut.md 汇总阶段写入 |
| 归档旧状态文件 | unittest-*-{session_id}-{timestamp}.md | ut.md | 只读 | 全新开始时归档 |
6.2 原子写文件协议
所有更新状态的文件操作必须使用临时文件 + rename 原子操作:
- 先写临时文件:
{原文件名}.tmp - 再
mv原子重命名为目标文件名 - 如目标文件已存在,根据场景决定是跳过还是覆盖
适用文件:unittest-queue.md、unittest-session.md、worker-{ID}-result.md(ut.md 超时代写时)、主结果文件
6.3 任务状态机
| 状态 | 说明 | 可转换到 |
|---|---|---|
pending | 待处理 | in_progress |
in_progress | 处理中 | completed / failed |
completed | 已完成 | — 终态 |
failed | 失败 | pending(重试) |
状态转换规则:
pending → in_progress:启动 worker 时
in_progress → completed:检测到结果文件且状态为成功
in_progress → failed:检测到结果文件且状态为失败;或超时(ut.md 代写 `状态: 超时终止`)
failed → pending:Phase 2-3 创建重试任务
failed 子类型(通过 备注 列区分):
备注含timeout→ 超时终止,不重试备注含critical_bug→ worker 发现高危 Bug 退出,不重试备注含retry_exhausted→ 重试次数耗尽(≥2 次),不再重试备注含retry:N|orig:W{ID}|reason:{text}→ 第 N 次重试中
completed 子类型(通过 备注 列或 result 文件第二行区分):
- result 文件第二行为
同步状态: 失败→ 测试通过但文件同步失败,备注记录sync_failed,由 Phase 2-5 恢复
超时终止处理:
- ut.md 检测到超时,代写 result 文件首行
状态: 超时终止,队列状态设为failed,备注: timeout - Phase 2-4 汇总时需重新读取
备注含timeout的 result 文件首行:- worker 已更新为
状态: 成功→ 改为completed,清除备注中timeout - worker 已更新为
状态: 失败→ 保持failed,备注更新为实际失败原因 - 仍为
状态: 超时终止→ 保持failed,备注: timeout,不重试
- worker 已更新为
7. 锁协议
本节只在 experience_write_mode=child_locked_append 时执行。当前仅有一个锁目录:
unittest-experience.lock,用于控制共享经验库的并发追加写入。parent_finalize 时所有 Worker 禁止
写共享经验库或锁目录,只在 final 返回经验候选,由父流程验证、去重后串行原子合并。
锁超时时间:10 分钟
测试文件同步无需锁:每个 worker 只负责自己目标类对应的测试文件({ClassName}Test.java),不同 worker 写入的测试文件路径天然不同,不存在并发写冲突。
锁超时清理:child_locked_append 下 ut.md 可以删除锁目录,但必须满足以下任一条件;parent_finalize 不检查、不创建、不删除锁目录,本节不适用:
- 所有 worker 都已完成(
active_slots为空,且队列中无in_progress或pending任务) - 锁目录创建时间已超过 10 分钟(与 worker 锁超时阈值一致,避免10-30分钟死区导致经验持续丢失)
8. 异常处理矩阵
| 异常类型 | 触发场景 | 处理策略 |
|---|---|---|
| 任务数超限 | 待调度任务总数(新扫描 + 存量待执行)> 100 | 按 §4.2.3 阻断协议输出提示并退出命令,不询问确认、不生成队列、不启动任何 worker |
| 参数缺失或非法 | --packages/--concurrency 未提供、非整数或越界 | 不退出:按所选执行模式经 §4.2.0 交互补全(包名发现 + 用户选择 + 并发确认);并发连续 3 次无效输入后输出用法指引并受控停止 |
| 上次运行中断 | 检测到存在残留状态文件 | 展示状态,询问用户选择(继续/重新/增量) |
| Worker 超时 | in_progress 状态超过 3600 秒 | ut.md 代写超时终止结果文件(首行 状态: 超时终止),任务标记为 failed(备注: timeout,不重试)。Phase 2-4 汇总时检查是否有 worker 后续覆盖(状态变为 成功/失败),如有则以 worker 最新结果为准 |
| 锁目录残留 | child_locked_append 检测到存在过期的锁目录 | ut.md Phase 0-0 和 Phase 2-4 按 §7 负责清理;parent_finalize 不检查、不创建、不删除锁 |
| 权限阻断 | Worker 遇到权限被拒绝 | Worker 立即写入失败结果,ut.md 检查并补齐权限后重试 |
| 测试文件同步失败 | Worker 同步到主项目失败 | Worker 保留临时目录,ut.md Phase 2-5 检查并手动恢复 |
| 配额中断 | 执行时间或资源超限 | 保留临时文件和状态,下次可继续执行 |
| 结果文件格式错误 | worker 输出无法解析 | ut.md 尽力解析,失败则标记为 failed,归档无效文件 |
| 主项目源码在执行中变化 | 用户修改了主项目源码 | 记录警告,继续执行,最终统一验证时重新编译 |
9. 附录:输出模板
9.1 全新开始输出模板
🆕 全新开始模式
- 新会话 ID:{session_id}
- 归档旧状态文件:{A} 个
- 归档旧 worker 文件:{W} 个
- 清理旧会话托管 settings.local 权限:{已清理/无/跳过,原因}
- `child_locked_append` 清理锁目录:{0/1} 个;`parent_finalize`:当前模式不适用
- 清理临时目录:{M} 个
- 保留经验库记录:{E} 条
9.2 继续执行输出模板
🔄 继续上次执行模式
- 会话 ID:{session_id}
- 恢复 archived worker 文件:{R} 个
- 重置 in_progress 任务:{IP} 个
- `child_locked_append` 清理锁目录:{0/1} 个;`parent_finalize`:当前模式不适用
- 清理临时目录:{M} 个
- 保留经验库记录:{E} 条
9.3 增量补充输出模板
📈 增量补充模式
- 会话 ID:{session_id}
- 本次新增包名:{package1, package2, ...}
- 恢复 archived worker 文件:{R} 个
- 重置 in_progress 任务:{IP} 个
- `child_locked_append` 清理锁目录:{0/1} 个;`parent_finalize`:当前模式不适用
- 清理临时目录:{M} 个
- 保留经验库记录:{E} 条
9.4 unittest-queue.md 初始化模板
## 任务队列状态
> 会话ID:{session_id}
> 最后更新、循环迭代计数等元数据以下方「元数据」块为唯一事实源,不在表头重复维护
| 序号 | 类名 | 包名 | 文件路径 | 状态 | Worker ID | 开始时间 | 结束时间 | Agent ID | 失败原因 | 备注 |
|------|------|------|----------|------|-----------|----------|----------|----------|----------|------|
### 元数据
- 会话ID:{session_id}
- 最后更新:{YYYY-MM-DD HH:MM:SS}
- 循环迭代计数:0
- 活跃Worker数:0
- worker 并发数:{concurrency}(本次会话的最大并发常量,上下文截断恢复后沿用此值调度)
### 状态说明
- pending:待处理
- in_progress:处理中
- completed:已完成(终态)
- failed:失败(终态,进入 Phase 2-3 判断是否重试)
> `failed` 和 `completed` 的子类型通过 `备注` 列区分:
> - `timeout` — 超时终止,不重试
> - `critical_bug` — 高危 Bug 退出,不重试
> - `sync_failed` — 测试通过但文件同步失败(completed 任务的子类型,Phase 2-5 恢复)
> - `retry:N|orig:W{ID}|reason:{text}` — 第 N 次重试
> - `retry_exhausted` — 重试次数耗尽
> - `orphan_detected` — 孤儿临时目录
> - `lost_on_truncation` — 上下文截断丢失
### 包名集合记录
- 指定包名:{package1, package2, ...}
9.5 unittest-experience.md 初始化模板
## 会话问题经验知识库
### 已解决问题清单
| 序号 | Worker ID | 类名 | 问题类型 | 问题特征 | 解决方案 | 适用场景 | 写入时间 |
10. 附录:参数解析快速参考
10.1 参数解析流程图
$ARGUMENTS 输入
↓
宽容提取 --packages/-p(缺失或为空 → 标记"未提供",不退出)
↓
宽容提取 --concurrency/-c(缺失/非整数/越界 → 标记"未提供或非法"并保留原值,不退出)
↓
分割包名列表(逗号分隔,去重)
↓
检查残留状态文件
↓
├─ 存在残留 → 询问用户选择(继续/重新/增量)
│ ├─ 继续 → 进入 Phase 0
│ ├─ 重新 → 进入 Phase 0(全新开始)
│ └─ 增量 → 进入 Phase 0(包名可显式给,也可后续交互选)
│
└─ 无残留 → 进入 Phase 0(全新开始)
↓
Phase 1 入口:按缺口矩阵仍有参数缺口?
├─ 是 → §4.2.0 参数补全
│ ├─ 继续执行模式 → §4.2.0.1-续 输出队列内包进度表(识别已有包)
│ ├─ 需要包名 → 扫描 + 排除 + 按包聚合 → 完整列出候选包清单
│ │ → 用户选择(零候选 → 输出提示并退出)
│ └─ 需要并发 → 提示 2-10 → 用户输入(连续 3 次无效 → 输出指引并停止)
└─ 否 → 直接继续(继续执行模式仍输出 §4.2.0.1-续 队列内包进度表)
↓
扫描/排除/包名过滤/增量去重后、用户确认前:
待调度任务总数(新扫描 + 存量待执行)> 100?
├─ 是 → 输出超限提示,退出命令(不确认、不生成队列)
└─ 否 → 生成任务列表 → 用户确认 → Phase 2 调度 → Phase 3 汇总
10.2 参数解析详细步骤
步骤 1:原始输入获取
- 输入源:
$ARGUMENTS - 输入格式:空格分隔的参数列表
步骤 2:包名参数提取(宽容提取,不退出)
- 查找
--packages或-p参数 - 取该参数后面的值作为包名集合
- 包名集合格式:逗号分隔,允许空格(自动去除)
- 未找到参数或解析结果为空列表 → 标记
{packages_arg}为未提供,继续后续步骤,由 §4.2.0.1 补全 - 示例:
--packages com.example.service, com.example.controller-p com.example.service
步骤 3:并发数参数提取(宽容提取,不退出)
- 查找
--concurrency或-c参数 - 取该参数后面的值,必须解析为整数
- 校验规则:
2 ≤ N ≤ MAX_CONCURRENCY(MAX_CONCURRENCY = 10) - 未找到参数 → 标记
未提供;值缺失、非整数或越界 → 标记非法并记录原始值(用于提示语);两者均不退出,由 §4.2.0.2 补全 - 校验通过后记为
{concurrency},作为 Phase 2-2 worker 调度的最大并发常量
步骤 4:包名解析
- 按逗号分割字符串
- 对每个包名去除首尾空格
- 过滤空字符串
- 结果:字符串数组
[pkg1, pkg2, ...]
步骤 5:状态检测
- 检查文件:
docs/specs/active/{feature}/unittest-session.mddocs/specs/active/{feature}/unittest-queue.mddocs/specs/active/{feature}/worker-*.md
- 判断是否存在残留状态
步骤 6:执行模式选择
- 存在残留:
- 读取
unittest-session.md获取上次状态 - 向用户展示选项
- 记录用户选择
- 读取
- 无残留:
- 默认选择"全新开始"
步骤 7:增量补充特殊处理
- 若用户选择"增量补充":
- 包名或已显式提供,或由 §4.2.0.1 交互选定
- 确定后新包名与旧队列合并(去重)
步骤 8:参数补全(§4.2.0)
- 按缺口矩阵判定所选执行模式仍缺的参数
- 缺包名 → §4.2.0.1:扫描 + 排除 + 按包聚合 → 完整列出候选包清单 → 用户选择 → 回显确认
- 缺并发 → §4.2.0.2:展示范围与已选包任务数 → 用户输入 → 连续 3 次无效则停止
- 补全值与显式传入完全等价
10.3 参数解析示例
示例 1:完全无参数 → 交互补全
输入: $ARGUMENTS = ""
处理:
- 包名 = 未提供;并发 = 未提供(均不退出)
- 检查残留 → 假设无残留 → 全新开始
- Phase 0 完成 → §4.2.0.1:扫描 + 排除 + 按包聚合 → 完整列出候选包清单 → 用户回复 "1,3"
- 回显已选包 → §4.2.0.2 提示并发 → 用户回复 "5" → {concurrency} = 5
- 复用扫描结果过滤所选包 → §4.2.3 校验 → §4.2.4 任务清单确认 → Phase 2
示例 2:并发非法 → 交互纠正
输入: $ARGUMENTS = "--packages com.example.service --concurrency 12"
处理:
- 包名 = ["com.example.service"](有效);并发 = 12 > 10 → 标记"非法",不退出
- 假设无残留 → 全新开始 → Phase 0 → §4.2.0.2:提示含「你传入的 "12" 无效:大于 10」
- 用户回复 "8" → {concurrency} = 8 → 继续 §4.2.2 之后流程
示例 3:参数齐全 → 直达
输入: $ARGUMENTS = "--packages com.example.service,com.example.controller --concurrency 5"
处理:
- 包名 = ["com.example.service", "com.example.controller"];concurrency = 5(合法)
- 无残留 → 全新开始 → §4.2.0 整节跳过
- 仅扫描指定包及其子包,Phase 2-2 最大并发 = 5
示例 4:简写参数,增量补充
输入: $ARGUMENTS = "-p com.example.newpkg -c 3"
处理:
- 包名 = ["com.example.newpkg"];concurrency = 3(合法)→ §4.2.0 跳过
- 假设存在残留文件
- 询问用户后选择"增量补充"
- 新包名加入已有队列
示例 5:缺包名 + 残留 + 继续执行 → 展示队列包进度后只补并发
输入: $ARGUMENTS = ""
处理:
- 包名 = 未提供;并发 = 未提供
- 存在残留 → 用户选择"继续执行" → 包名无需补全(沿用已有队列)
- Phase 0 → §4.2.0.1-续:输出队列内包进度表(每个包的 已完成/失败/处理中/待处理 计数,完整列出)
- §4.2.0.2:只询问并发 → 用户回复 "5" → 继续 §4.2 分支"继续执行"
示例 6:继续执行 + 显式传入不在队列中的包 → 提示不处理
输入: $ARGUMENTS = "--packages com.example.newpkg --concurrency 5"
处理:
- 包名 = ["com.example.newpkg"];concurrency = 5(合法)→ §4.2.0 交互部分跳过
- 存在残留 → 用户选择"继续执行"
- §4.2.0.1-续 仍执行:输出队列内包进度表;核验发现 com.example.newpkg 不在队列中
- 追加 ⚠️ 提示:"com.example.newpkg 不在当前队列中,继续执行不会处理它们;如需处理请改用增量补充模式"
- 不退出、不自动转增量,继续执行队列内任务
10.4 常见场景处理
| 场景 | 处理方式 |
|---|---|
--packages 参数缺失或值为空 | 不退出:按所选模式经 §4.2.0.1 扫描并完整列出候选包,由用户选择(继续执行模式无需补全) |
--concurrency 缺失、非整数、< 2 或 > 10 | 不退出:经 §4.2.0.2 由用户重新指定,原值在提示中回显;连续 3 次无效输入后输出用法指引并受控停止 |
| §4.2.0.1 发现排除后候选类为 0 | 输出"未发现需要单测维护的类"提示并退出命令,不展示空清单、不询问并发 |
| 继续执行模式下识别队列中已有的包 | §4.2.0.1-续 输出队列内包进度表(每包的 总任务/已完成/失败/处理中/待处理 计数),完整列出、禁止截断;纯展示不询问 |
| 继续执行模式显式传入的包不在队列中 | 在包进度表后逐个列出该包名并 ⚠️ 提示"继续执行不会处理;如需处理请改用增量补充",不退出、不自动转增量 |
| 用户在 §4.2.0 中拒绝选择包或并发 | 输出当前进度说明并受控停止,不进入 Phase 2 |
| 待调度任务总数(新扫描 + 存量待执行)> 100 | 按 §4.2.3 阻断协议提示后退出命令(发生在用户确认与队列生成之前) |
| 包名包含空格 | 自动去除空格,按逗号分割 |
| 同一个包名重复指定 | 自动去重,只保留一个 |
| 交互中用户混用序号与包名 | 逐个解析、去重、按字母序回显确认 |
| 参数中包含其他未知参数 | 忽略未知参数,只处理 4 个已定义参数 |
宿主资源声明:resources.runtime、resources.subagent_protocol、resources.telemetry_protocol、resources.ut。 |
Agents 16
任务:前端项目初始化收尾
前提:init 命令已完成 6 路并行扫描(scan-frontend-meta / api / routes / state / components / tracking),产物在 docs/knowledge/ 下。你负责收尾,包括 harness 约束与 linters、knowledge 索引与占位、hooks 与 runtime 配置、平台入口更新、state file 更新与初始化报告。
输入必须包含当前平台($PLATFORM)和顶层 init 已解析的 $EFFECTIVE_TELEMETRY_MODE(只能是 enabled|disabled);不得在本 agent 内重新默认或再次询问 consent。
同时必须消费顶层 init 已解析的 Host Context,读取 resources.project_config:entry_file 是
唯一入口文件,entry_template 是单仓模板,workspace_entry_template 仅供 workspace 使用,
settings_file 是可选项目配置文件。项目 hook 合并语义读取 resources.project_hooks;
settings_file=null 时跳过项目 runtime hooks 配置,不得回退到旧宿主路径。
纯后端/未知项目直接退出。纯前端使用 bootstrap_mode=frontend;完整全栈扫描使用
bootstrap_mode=fullstack-merge,且必须等待 service bootstrap 通过后再增量执行。
读取输入边界
父流程必须传入当前仓库的 ownership_root、明确的 read_scope 和已验证扫描产物。
完整读取 reference/subagent-runtime-protocol.md 的读取边界;只消费这些输入、本仓待合并的
入口/索引/设置和当前 plugin root 的模板与协议。相对路径均从 ownership_root 解析。
不得读取相邻仓库生成的页面、harness、knowledge、hooks 或宿主配置作为范例,不得通过
父目录遍历、Shell/Python 或符号链接绕过范围。模板或扫描事实不足时返回父流程,
不搜索其他仓库或自行补扫。全栈增量模式只复用同一个 ownership_root 的前序产物。
模板路径
以下模板文件位于 plugin 的 templates/ 目录下,必须逐文件读取模板并依据扫描结果填充,不得手写代替:
| 分类 | 模板路径 | 用途 |
|---|---|---|
| harness 总入口 | templates/harness/frontend/index.md.tpl | harness/index.md 骨架 |
| 架构约束 | templates/harness/frontend/architecture/layering.md.tpl | 分层架构约束 |
| 基础设施 | templates/harness/frontend/infrastructure/build.md.tpl | 构建规范 |
| 基础设施 | templates/harness/frontend/infrastructure/types.md.tpl | 类型系统规范 |
| 基础设施 | templates/harness/frontend/infrastructure/lint.md.tpl | 代码质量规范 |
| 不变量 | templates/harness/frontend/invariants/component.md.tpl | 组件开发规约 |
| 不变量 | templates/harness/frontend/invariants/state.md.tpl | 状态管理规约 |
| 不变量 | templates/harness/frontend/invariants/api.md.tpl | API 调用规约 |
| linter | templates/harness/spec-sync-check.py.tpl | 跨工作目录稳定定位 active specs |
| 宿主入口 | Host Kit 的 entry_template | entry_file 生成或合并 |
如果某模板文件不存在,返回父流程报告缺失的具体模板路径;不得读取相邻仓库替代, 不得省略必需产物后报告成功。
执行流程
Phase 0:检查已有内容
先检查以下目录/文件是否已存在:
docs/harness/、docs/harness/index.mddocs/knowledge/、docs/knowledge/index.mddocs/knowledge/prd/、docs/knowledge/exp/docs/knowledge/project-context.md、docs/knowledge/domain-mapping.mddocs/specs/active/、docs/specs/completed/docs/hooks/、docs/hooks/index.md、docs/hooks/post-action.md、docs/hooks/cr-checklist.md- Host Kit 的
settings_file(非null时检查是否已含等价的写后检查配置)
纯前端模式若全部已存在,询问用户是否需要更新某些部分;否则仅补充缺失内容。
bootstrap_mode=fullstack-merge 时公共目录和入口由前序 service bootstrap 创建是预期状态,不再询问,
直接合并前端叶子、索引和入口导航。已存在的文件不覆盖,只增量补充。
Phase 1:post-scan 验证
先检查全部产物是否落盘:
required=(
"docs/knowledge/structure.md"
"docs/knowledge/build.md"
"docs/knowledge/style.md"
"docs/knowledge/routes.md"
"docs/knowledge/state.md"
"docs/knowledge/api-endpoints.md"
"docs/knowledge/components.md"
"docs/knowledge/architecture.md"
)
optional=("docs/knowledge/tracking.md") # 仅埋点检测命中时存在
missing=()
for f in "${required[@]}"; do
[ ! -f "$f" ] && missing+=("$f")
done
if [ ${#missing[@]} -gt 0 ]; then
echo "⚠️ 缺少产物: ${missing[*]}"
# 报告 BLOCKED 和缺失清单给父流程;不自行重跑或补扫
else
echo "✅ 所有前端必需扫描产物已就绪"
fi
if [ ! -f "${optional[0]}" ]; then
echo "ℹ️ 未生成 tracking.md;scan-frontend-tracking 未检测到埋点时属于正常结果"
fi
⛔ 校验要求:上述
required清单中的任一文件缺失 → 报告 BLOCKED,不得自行补扫绕过顶层编排。
Phase 2:生成 harness 约束 + linters
先完整读取 reference/harness-generation-protocol.md,区分当前行为与有规范性来源的约束;
该边界同时适用于后续宿主入口、harness 索引、CR checklist 和 linter。
约束总入口(docs/harness/index.md):
- 读取
templates/harness/frontend/index.md.tpl - 替换其中占位符为实际扫描结果(如组件数量、路由页面数、状态管理方案)
- 全局约束摘要写入 3-5 条最关键的前端约束(从 invaraints/architecture/infrastructure 叶子文件中提炼)
架构约束(docs/harness/architecture/):
- 读取
templates/harness/frontend/architecture/layering.md.tpl - 从
structure.md提取实际分层目录名称替换模板占位符 - 根据项目实际框架(Vue/React)调整分层术语(Composables/Hooks、Pages/Views)
基础设施规范(docs/harness/infrastructure/):
| 文件 | 模板 | 填充来源 |
|---|---|---|
build.md | templates/harness/frontend/infrastructure/build.md.tpl | build.md、architecture.md 中的实际构建工具与配置 |
types.md | templates/harness/frontend/infrastructure/types.md.tpl | tsconfig.json / jsconfig.json 实际配置 |
lint.md | templates/harness/frontend/infrastructure/lint.md.tpl | .eslintrc.* / .prettierrc.* 实际配置 |
不变量约束(docs/harness/invariants/):
| 文件 | 模板 | 填充来源 |
|---|---|---|
component.md | templates/harness/frontend/invariants/component.md.tpl | components.md 中实际组件命名、分层模式 |
state.md | templates/harness/frontend/invariants/state.md.tpl | state.md 中实际 Store 方案 |
api.md | templates/harness/frontend/invariants/api.md.tpl | api-endpoints.md 中实际 API 封装方式 |
不要只复制模板——每个文件至少包含 1-2 处从扫描结果中提取的项目实际数据。
项目模式判定(写入 docs/harness/index.md 全局约束摘要开头):
- 扫描
src/:已有业务页面/组件 →brownfield,基本为空/只有脚手架 →greenfield greenfield:写入"评审以基线架构合理性、可扩展性、运维可行性为主"brownfield:写入"评审以现有系统兼容性、影响范围、迁移成本为主"
Linters(docs/harness/linters/)——与后端 Phase 3 对齐,linter 脚本随 harness 一起生成:
invariant-check.py:
from pathlib import Path
import re
root = Path(__file__).resolve().parents[3]
src = root / "src"
files = [p for p in src.rglob("*") if p.suffix in {".ts", ".tsx", ".vue"} and p.is_file()]
bad_names = [p.relative_to(root).as_posix() for p in files
if p.suffix in {".tsx", ".vue"} and re.match(r"[a-z][a-z0-9]*-[a-z]", p.name)]
for name in bad_names:
print(f"WARNING component naming: {name}")
if list(root.glob("tsconfig*.json")):
count = sum(sum(": any" in line for line in p.read_text(encoding="utf-8", errors="replace").splitlines()) for p in files)
if count > 10:
print(f"WARNING: {count} lines contain ': any'")
print("HelixHarness invariant check complete")
spec-sync-check.py:完整读取 templates/harness/spec-sync-check.py.tpl 并原样写入。不得重新手写
依赖当前工作目录的版本;模板已经从脚本位置解析项目根并保持 warning-only。
使用预检选中的 Python 执行两个 .py 脚本;不依赖 chmod、Bash、grep、head。
Phase 3:生成 knowledge 索引、占位文件与 project-context
3.1 知识库索引
扫描 docs/knowledge/ 下所有知识文件,生成 docs/knowledge/index.md(propose/apply 等命令的入口):
# 知识库索引
> 生成时间:YYYY-MM-DD
## 文档清单
| 文件/目录 | 定位 | 加载时机 |
| :--- | :--- | :--- |
| [技术栈与架构](architecture.md) | 前端技术栈全景 | 所有阶段 |
| [项目上下文](project-context.md) | 项目基本信息 | propose/apply 必读 |
| [目录结构](structure.md) | 项目目录与代码组织 | 设计阶段 |
| [路由配置](routes.md) | 路由映射与权限 | 涉及路由/页面改动时 |
| [状态管理](state.md) | Store 结构与使用 | 涉及状态/数据流改动时 |
| [API 端点](api-endpoints.md) | 接口封装与端点清单 | 涉及接口调用时 |
| [样式方案](style.md) | 样式体系与主题 | 涉及样式/主题改动时 |
| [构建配置](build.md) | 构建工具与优化 | 涉及构建/打包改动时 |
| [组件清单](components.md) | 组件 Props 与依赖 | 涉及组件新增/修改时 |
| [埋点方案](tracking.md) | 埋点框架与事件清单 | 涉及埋点改动时 |
| [领域映射表](domain-mapping.md) | 产品别名→业务域映射 | 涉及跨域/多业务线时 |
"定位"列取每个文件第一段(首个 ## 之前或前 100 字)。tracking.md 仅存在时列入。
3.2 知识库占位文件
docs/knowledge/prd/— 需求归档目录(空目录,仅保留用户提供的需求资料,Archive 不自动生成或复制 Proposal)docs/knowledge/exp/— 经验目录(空目录)docs/knowledge/domain-mapping.md— 产品别名→业务域映射表(空模板,手动维护):
# 领域名称映射表
> 手动维护:将产品文档中使用的别名映射到业务域名称
| 业务域名称 | 产品文档别名 | 说明 |
|-----------|------------|------|
| <!-- TODO: 填写 --> | | |
3.3 汇总扫描计时
从 docs/.helixharness-init-state.json 的 scanTimings 字段读取各 agent wall-clock,输出耗时汇总表格(按降序排列,标注"6 路并行")。
3.4 写入 project-context
生成 docs/knowledge/project-context.md:
# 项目上下文
- **project-mode**: {greenfield|brownfield}
- **技术栈**: {从 architecture.md 提取:框架 + 语言 + UI 库 + 构建工具}
- **状态管理**: {从 state.md 提取}
- **样式方案**: {从 style.md 提取}
- **路由方案**: {从 routes.md 提取}
- **判定依据**:
- greenfield: 当前仓库尚无稳定业务代码,技术方案按首版基线设计评审
- brownfield: 当前仓库已有业务代码或既有系统约束,技术方案按兼容演进设计评审
3.5 初始化 Usage Telemetry 目录
$EFFECTIVE_TELEMETRY_MODE=enabled:创建docs/eval/.gitkeep,确保.gitignore包含docs/eval/**提交例外。$EFFECTIVE_TELEMETRY_MODE=disabled:不新建/不追加/不删除。- 本阶段只准备目录,不写 feature usage entry。
Phase 4:生成 hooks/
4.1 Hook 配置文件
-
docs/hooks/index.md— Hook 机制总览(区分 runtime hooks / workflow gates / review checklists) -
docs/hooks/post-action.md— 写后快速自动检查:# Post-Action 自动检查 每次 Write / Edit 工具写入文件后,Agent 应自检: 1. **Invariant 一致性**:改动是否违反 `docs/harness/invariants/` 中的约束? 2. **Spec 同步**:若改动涉及 `docs/specs/active/` 下的 feature,tasks.md / verify-report.md 是否需要更新? 3. **组件影响**:若改动涉及共享组件,是否评估了所有引用方? 4. **API 变更**:若改动涉及 API 调用方式(参数/返回值),api-endpoints.md 是否需要更新? > 此检查为提醒性质,不阻断操作,但应在下一轮 commit 前闭环。 -
docs/hooks/cr-checklist.md— CR 检查清单:# CR 检查清单 每完成一个功能模块,按以下顺序自检: ## 代码规范 - [ ] 组件命名符合 invariants/component.md 规约 - [ ] Props 数量、类型、回调命名合规 - [ ] 无 `any` 类型(或已加注释说明原因) ## Invariant 合规 - [ ] 未违反 invariants/ 下任一约束 - [ ] 状态管理边界符合 invariants/state.md - [ ] API 调用封装符合 invariants/api.md ## 架构约束 - [ ] 分层依赖方向正确(Pages → Components → Hooks → Services) - [ ] 无循环依赖 - [ ] 未见跨层反向引用 ## Tasks Checkpoint - [ ] task 状态与代码实际进展一致 - [ ] 证据已写入 tasks.md / verify-report.md ## Finding 对账 - [ ] 若本轮来自 Apply 双轴评审或验证反馈:finding 是否有明确接受/拒绝/延期决策 - [ ] 修复是否映射到代码和文档
4.3 按 Host Kit 写入 Runtime Hooks
- 完整读取当前
resources.project_hooks,不得自行构造事件名、matcher、JSON 路径或 payload。 settings_file=null或merge_strategy=unsupported:跳过,不创建替代配置。owner=bootstrap:按reference/runtime-preflight.md从父流程绑定的插件根使用当前系统的启动器执行{helix_python} "{plugin_root}/scripts/project_hooks_cli.py" --repo-root "{repo_root}" --platform "{canonical_host_id}" merge。 使用原有宿主写入权限,按脚本结果确认合并。owner=parent:不得写 settings;在 final 返回结构化PROJECT_HOOKS_MERGE_REQUEST,由父流程校验后串行合并。- 资源与
resources.project_config.settings_file不一致时BLOCKED: project_hooks_contract_invalid。
Phase 5:更新宿主入口文件并输出初始化报告
5.1 更新平台入口文件
- 若 Host Kit 的
entry_file已存在 → 追加规则; - 若不存在 → 基于 Host Kit 的
entry_template生成entry_file; - 不探测或生成其他宿主的入口文件。
追加规则(读取 entry_template,提取四个区块并以 ## HelixHarness 导航 为标题追加):
- 目录导航(用实际 frontend 目录结构替换)
- 关键约束速览(3-5 条,来自
docs/harness/index.md全局约束摘要) - 常用命令(
/helix:propose、/helix:apply等) - Agent 工作规则(含 harness/knowledge 按需加载协议)
追前检查文件末尾是否已含 ## HelixHarness 导航 或 ## Agent 工作规则 → 已存在则不重复,仅确认是否需要更新。
5.2 最终提交 state file
只有 Phase 4 hooks 与 Phase 5.1 Host Kit 入口全部生成并通过逐项验证后,才使用公共
Read/Edit/Write 工具语义原子更新 docs/.helixharness-init-state.json;其他宿主只按
resources.runtime 映射,不依赖外部 JSON CLI:
- state 文件缺失、为空或不是 JSON 对象时立即
BLOCKED:init_state_missing,不得跳过后继续完成。 scanPlan为空时补["scan-frontend-meta","scan-frontend-api","scan-frontend-routes","scan-frontend-state","scan-frontend-components","scan-frontend-tracking"]; 已有非空计划保持不变。设置scanStatus=completed、bootstrapStatus=completed与completedAt。bootstrap_mode=fullstack-merge时额外写frontendCompletedAt,且必须保留前序backendCompletedAt;缺少后端完成事实时BLOCKED:backend_bootstrap_incomplete。所有*At字段固定为当前 UTC Unix epoch 秒的 JSON number,与既有状态产物类型一致,不得写 ISO 字符串或宿主本地时间文本。- 从实际文件列表构造排序、去重后的 knowledge、harness、hooks 三组 deliverables;每个
count必须等于对应files数组长度。 - 只修改上述字段,保留其他键。写入后重新
Read,确认 JSON 可解析、字段类型正确、入口、hooks 及所有 deliverable 文件均存在;任一步失败报告BLOCKED:init_state_update_failed。
不要删除
docs/.helixharness-init-state.json(供后续命令使用)。
5.3 输出初始化报告
## HelixHarness 前端初始化完成
### 项目信息
- 项目模式: {greenfield|brownfield}
- 框架: {Vue/React/...}
- 语言: {TypeScript/JavaScript}
- 状态管理: {Pinia/Redux/Zustand/...}
- 样式方案: {Less/SCSS/Tailwind/...}
- 构建工具: {Vite/Webpack/...}
- UI 库: {Ant Design/Element Plus/...}
- 组件数量: {N} 个 / 路由页面: {M} 个
### 生成的文件
- [x] {entry_file}(来自 Host Kit)— 已更新/新增
- [x] docs/harness/index.md — 约束总入口
- [x] docs/harness/invariants/component.md — 组件开发规约
- [x] docs/harness/invariants/state.md — 状态管理规约
- [x] docs/harness/invariants/api.md — API 调用规约
- [x] docs/harness/architecture/layering.md — 分层架构约束
- [x] docs/harness/infrastructure/build.md — 构建规范
- [x] docs/harness/infrastructure/types.md — 类型系统规范
- [x] docs/harness/infrastructure/lint.md — 代码质量规范
- [x] docs/harness/linters/invariant-check.py — invariant 自动检查
- [x] docs/harness/linters/spec-sync-check.py — spec 同步提醒
- [x] docs/knowledge/index.md — 知识库索引
- [x] docs/knowledge/project-context.md — 项目上下文
- [x] docs/knowledge/domain-mapping.md — 别名→域映射表(需手动填写)
- [x] docs/knowledge/prd/ — 需求归档目录
- [x] docs/knowledge/exp/ — 经验目录
- [x] docs/hooks/index.md — Hook 机制总览
- [x] docs/hooks/post-action.md — 写后自动检查
- [x] docs/hooks/cr-checklist.md — CR 检查清单
- [x] Host Kit `settings_file` 已按 `resources.project_hooks` 合并,或明确为跳过/parent-owned
- [x] docs/eval/.gitkeep — 仅遥测开启时生成
- [x] docs/.helixharness-init-state.json — 已更新
### 下一步
1. 审核 docs/harness/ 下的约束文件,补充项目特有规则
2. 审核 docs/knowledge/ 知识库,确认准确性
3. 手动填写 docs/knowledge/domain-mapping.md(产品别名→业务域)
4. 执行 /helix:propose <feature-name> 开始第一个需求开发
注意事项
- 不删除已有内容 — 已存在的文件保持不动,只补充缺失文件
- 不捏造信息 — 无法通过扫描或用户确认的内容标注
<!-- TODO: 待确认 --> - 约束须有规范性来源 — 生成 harness、宿主入口、CR checklist 或 linter 前完整读取
reference/harness-generation-protocol.md;当前代码行为写入知识库,不能单凭现状生成不可变硬规则 - 空项目处理 — 若无代码,通过交互收集信息后基于模板生成,并显式标记
project-mode: greenfield - 非前端项目直接退出
- 不要删除
docs/.helixharness-init-state.json(供后续命令使用) - hooks 和 linters 是硬门禁 — 与 harness/index.md 同等重要,不得以"首次初始化可选"为由跳过
Telemetry 边界:只消费顶层 init 根据
resources.telemetry_protocol解析的 effective mode; 本 agent 不识别宿主、不读取会话日志、不选择 telemetry adapter。unsupported 按 disabled 初始化且 不创建 eval 目录。
Host Kit 项目配置:执行前必须消费顶层 init 已解析的 Host Context,读取
resources.project_config。entry_file是唯一入口文件,entry_template是单仓模板,workspace_entry_template只供 workspace 使用,settings_file是可选项目配置文件。 项目 hook 合并语义以resources.project_hooks为准;settings_file=null时跳过项目 runtime hooks 配置,禁止搜索或回退到其他设置路径。
任务:执行服务仓库初始化
你负责在单个服务仓库根目录完成 HelixHarness 后端基础初始化。适用于后端/未知项目,也适用于
完整全栈扫描的 bootstrap_mode=fullstack-base 和免扫描的 bootstrap_mode=greenfield;纯前端项目由 init-frontend-bootstrap 处理。
输入
- 当前仓库根目录
- 原始参数:
$ARGUMENTS - 当前平台:
$PLATFORM - bootstrap mode:
service|fullstack-base|greenfield - 顶层 init 已解析的数据统计模式:
$EFFECTIVE_TELEMETRY_MODE(只能是enabled|disabled,不得在 bootstrap 内重新默认或再次询问) - 父流程明确传入的
ownership_root、read_scope、已验证扫描产物与当前 plugin root
读取输入边界
完整读取 reference/subagent-runtime-protocol.md 的读取边界。只消费本 job 清单中的已验证
扫描产物、显式外部 knowledge、本仓待合并入口/索引/设置,以及当前插件模板与协议。
所有本仓相对路径都从 ownership_root 解析,不从 Workspace 根或进程父目录猜测。
禁止读取同级仓库已经生成的 harness、knowledge、hooks 或宿主配置作为参考,也禁止通过
Shell/Python、父目录搜索或符号链接间接读取这些文件。插件模板不可用或扫描事实不足时,
返回缺失路径/事实给父流程;不自行寻找替代来源或重新扫描业务代码。
执行流程
Phase 0: 检查已有内容
检查以下目录/文件是否已存在:
- Host Kit 的
entry_file— 已存在则在末尾追加 HelixHarness 导航区块(不得覆盖已有内容),不存在则基于entry_template生成完整文件 docs/harness/docs/knowledge/docs/knowledge/prd/docs/specs/docs/specs/active/docs/specs/completed/docs/hooks/docs/eval/(仅数据统计开启时)- Host Kit 的
settings_file(非null时检查是否已含等价的写后检查配置)
若全部已存在,询问用户是否需要更新某些部分,否则仅补充缺失内容。
Phase 1: 收集项目信息
bootstrap_mode=greenfield 时只使用父流程传入的 project-mode: greenfield、用户已确认的项目目标、
技术栈、运行和测试入口,以及显式 --knowledge;不读取、等待或生成任何扫描产物。未确定的信息
保留 <!-- TODO: 待确认 -->,不假定架构、数据库或接口。直接按 Phase 2 的绿地分支处理。
其他模式消费父流程已经验证的扫描结果,不重新扫描代码。无法确认的事实返回父流程按宿主协议询问 用户,不得捏造或借用相邻仓库的结论:
-
技术栈:
- 从
architecture.md提取语言版本、Web框架、ORM、RPC框架、数据库、缓存和消息队列
- 从
-
架构风格:
- 从
architecture.md与domain-model.md提取部署形态和代码分层
- 从
-
业务领域:
- 从
domain-model.md、service-boundary.md、service-meta.yaml和已确认的用户决定提取
- 从
-
项目模式:
- 采用扫描结果或父流程明确传入的
greenfield|brownfield,缺失时返回父流程
- 采用扫描结果或父流程明确传入的
-
外部知识库(若有
--knowledge参数):- 读取指定路径/URL的知识文档
- 导入到对应
docs/knowledge/子目录
Phase 2: 生成 knowledge/
Greenfield(无扫描产物)
只生成 docs/knowledge/project-context.md 和链接它的 index.md 作为最小知识库;显式提供
--knowledge 时先导入并索引用户指定的材料,保留既有文档。不要求下方扫描产物,也不创建
没有事实支撑的 architecture、database、API、domain 或 service-meta 文档。完成本节共用的
统计目录和索引规则后继续 Phase 3。下方导入/扫描两分支的额外文件要求仅适用于非 greenfield。
索引使用 Markdown 链接 [project-context.md](project-context.md),或在三列表格第一列明确列出
相对路径 project-context.md;仅在说明文字中提及文件名不算索引。
非 greenfield 且有 --knowledge 参数
- 读取指定路径/URL的文档,导入到
docs/knowledge/ - 生成
docs/knowledge/index.md作为入口索引
非 greenfield 且无 --knowledge 参数,通过扫描 Agent 生成
这些扫描 agent 由顶层 /helix:init 命令显式编排与触发。你在这里不得再重新分发同一批扫描 agent,而是必须消费顶层已产出的扫描结果,并在缺失时报告 BLOCKED。
应直接使用并校验以下既有产物:
| 已产出文件 | 来源 | 用途 |
|---|---|---|
docs/knowledge/architecture.md | scan-tech | 技术栈、框架、中间件、架构模式、工程规范 |
docs/knowledge/database/ | scan-db | 表结构、字段、索引、ER 关系图 |
docs/knowledge/api/ | scan-api | HTTP REST / Thrift RPC / gRPC 接口清单 |
docs/knowledge/domain-model.md | scan-service | 服务定位、模块详情、数据归属、事件流、状态机 |
docs/knowledge/service-boundary.md | scan-boundary | 极简一页:核心定位、核心职责、显性边界 |
docs/knowledge/service-meta.yaml | scan-service-meta | 服务元数据:服务名、业务域、系统角色、上下游、owned data、事件、核心能力 |
校验要求:
- 若
docs/knowledge/architecture.md、docs/knowledge/domain-model.md、docs/knowledge/service-boundary.md、docs/knowledge/service-meta.yaml任一缺失,必须报告 BLOCKED - 若
docs/knowledge/database/或docs/knowledge/api/目录缺失,也必须报告 BLOCKED - 禁止把缺失的扫描产物改为你自己直接扫描后补写,以免绕过顶层扫描编排
结果回报要求:
完成初始化报告时,必须单独列出已消费的扫描结果文件,并标注是否全部来自顶层 /helix:init 预先触发的扫描流程
初始化占位文件(供后续 /helix:propose 使用,初始内容为空模板):
docs/knowledge/project-context.md— 项目上下文(含project-mode: greenfield|brownfield、技术栈、架构风格、业务域)docs/knowledge/domain-mapping.md— 产品别名→业务域映射表(手动维护,生成空模板,用户填写)docs/knowledge/service-meta.yaml— 服务元数据(服务名、业务域、系统角色、上下游、owned data、事件、核心能力)docs/knowledge/service-boundary.md— 服务职责边界文档(由scan-boundary必定生成,不是 knowledge 主入口)docs/knowledge/service-boundary/— 服务职责边界增强目录(仅当scan-boundary能稳定拆分为service-boundary/{domain}/结构时生成;缺失不影响/helix:propose)
domain-mapping.md 空模板格式:
# 领域名称映射表
> 手动维护:将产品文档中使用的别名映射到 service-boundary/ 下的业务域目录名称
| 业务域目录名称 | 产品文档别名 | 说明 |
|--------------|------------|------|
| {domain-dir} | {alias1}, {alias2} | |
service-meta.yaml 生成方式:
- 消费并校验顶层已完成的
docs/knowledge/service-meta.yaml,不得再次派发扫描或覆盖已验证产物 --knowledge导入模式只从显式提供的知识源提取元数据;无法确认保留null或空数组- 元数据单值无法确认时保留
null,列表保留空数组,说明使用 YAML# TODO注释,不推断 owners、repo默认保留给用户手动补充
知识附属目录(非 greenfield):
需求归档目录:创建 docs/knowledge/prd/(空目录,仅保留用户提供的需求资料;Archive 不自动生成或复制 Proposal)
经验目录:创建 docs/knowledge/exp/(空目录)
所有模式的目录和索引
创建 docs/specs/active/、docs/specs/completed/ 两个目录,不创建需求工件。
Usage Telemetry 目录:仅当数据统计保持开启时创建 docs/eval/,包含:
.gitkeep(占位文件,确保初始化后目录可见)
bootstrap 阶段不写 usage telemetry;数据统计开启时,需求级数据由后续 /helix:propose、/helix:apply、/helix:archive 等需求阶段命令写入 docs/eval/{feature}/eval-log.json。若用户关闭统计,不创建新的 eval-log,也不删除历史 docs/eval/**。
Git 跟踪:后续 HelixHarness recorder 在授权状态下准备 docs/eval/** 的跟踪规则;bootstrap 不执行统计写入或 Git 提交。
汇总:生成 docs/knowledge/index.md(知识库唯一索引,使用三列表格格式:文件/目录 | 定位 | 加载时机,直接索引所有叶子文件含子目录下的。「加载时机」列基于实际生成的知识文件内容,用"涉及 X/Y/Z 时"格式填写触发条件;project-context.md 标注为"propose/apply 必读")
无法确认的内容:标注
<!-- TODO: 待确认 -->,不推断
Phase 3: 生成 harness/
先完整读取 reference/harness-generation-protocol.md,按规范性来源区分当前行为与已确认约束;
该边界同时适用于后续宿主入口、harness 索引、CR checklist 和 linter。
bootstrap_mode=greenfield 时生成非空 docs/harness/index.md,只记录已确认的约束和待确认项。
不应用下方基于扫描证据的业务、架构、基础设施文档要求;仍按共用 Linters 规则生成两个可执行
检查入口。没有已确认的不变量时,invariant-check.py 明确报告暂无检查规则并成功退出。
不重新检测项目类型;其他模式延续其已确认的项目模式和扫描事实。
非 greenfield 按收集的技术栈和业务领域生成约束文件(内容填充实际情况,非空模板):
- 生成的
docs/harness/只需一个根级docs/harness/index.md作为唯一索引,使用三列表格格式(文件/目录 | 定位 | 加载时机),直接索引所有叶子文件(含子目录下的)。子目录不生成 index.md。
约束总入口:
docs/harness/index.md— 约束概览 + 全部叶子文件三列索引表 + 全局约束摘要(3-5 条最关键跨域约束)
业务不变量(目录:docs/harness/invariants/):
biz.md— 业务规则(基于业务领域填充)amt.md— 金额规则(仅信贷/支付/电商项目生成)txn.md— 交易规则(仅信贷/支付项目生成)
架构约束(docs/harness/architecture/):
- 必须生成
docs/harness/architecture/index.md,基于扫描结果和已产出的knowledge/architecture.md写入实际约束,至少包含:- 架构风格:单体/多模块/微服务(基于扫描结果),含部署方式和集群角色区分
- 模块/包结构:实际业务包路径,列出核心模块及其职责
- 服务间通信:RPC/HTTP/MQ 的通信约束与端口信息
- 数据源约束:多数据源配置、读写权限
- 服务边界:基于
service-boundary.md提炼的本服务负责/不负责范围 - 技术栈版本:语言、框架、ORM、RPC、中间件的具体版本号
基础设施规范(目录:docs/harness/infrastructure/):
- 按技术栈按需生成以下文件,读取此 plugin 捆绑的对应模板作为内容基础,结合扫描结果或交互收集的信息填充:
| 文件 | 模板 | 生成条件 |
|---|---|---|
api.md | templates/harness/api.md.tpl | 有 HTTP 接口时生成 |
concurrency.md | templates/harness/concurrency.md.tpl | Java 项目时生成 |
database.md | templates/harness/database.md.tpl | 有数据库时生成 |
cache.md | templates/harness/cache.md.tpl | 使用 Redis 时生成 |
mq.md | templates/harness/mq.md.tpl | 使用消息队列时生成 |
security.md | templates/harness/security.md.tpl | 所有项目生成 |
logging.md | templates/harness/logging.md.tpl | 所有项目生成 |
生成原则:
- 已有代码的项目:从扫描结果中提取实际使用模式,覆盖模板中的示例值(如连接池参数、Key 前缀、Topic 枚举等)
- 绿地项目:直接使用模板内容,
<!-- TODO: 待确认 -->标注部分由用户后续补充 - 模板中的
<!-- TODO: 待确认 -->注释:有明确信息则替换,无法确认则保留
交付/证据门禁:
- 不再生成独立
docs/harness/quality-gates/目录 - 运行期门禁统一由
/helix:apply、/helix:archive在docs/specs/active/{feature}/verify-report.md中执行和记录 - Apply 完成时生成
verify-report.md,记录测试与双轴评审证据;Init 不创建 feature 或验证报告。
Linters(docs/harness/linters/):
新生成的 linter 必须是 Python 3.10+ 标准库脚本:通过 Path(__file__).resolve().parents[3] 定位项目根,使用 pathlib/re/subprocess 参数数组执行项目检查,禁止生成依赖 Bash/grep/head/chmod 的实现。现有 .sh linter 保留,runner 可通过显式 Git Bash 兼容运行,但不得跳过检查。
invariant-check.py— 基于技术栈生成基础检查脚本spec-sync-check.py— 完整读取templates/harness/spec-sync-check.py.tpl并原样写入;它从脚本位置 解析项目根,提示代码改动与tasks.md/verify-report.md/ finding 对账之间可能存在脱节;默认 warning-only,不做重阻断,不得重新手写相对当前工作目录的版本
Phase 3.5: 写入项目上下文
生成 docs/knowledge/project-context.md,至少包含:
# 项目上下文
- **project-mode**: greenfield / brownfield
- **业务域**: {domain}
- **架构风格**: {architecture style}
- **技术栈**: {language} / {framework} / {database}
- **判定依据**:
- greenfield: 当前仓库尚无稳定业务代码,技术方案按首版基线设计评审
- brownfield: 当前仓库已有业务代码或既有系统约束,技术方案按兼容演进设计评审
要求:
bootstrap_mode=greenfield时显式写project-mode: greenfield,并记录项目目标、运行方式、测试入口及待确认项。greenfield项目必须明确写明"评审以基线架构合理性、可扩展性、运维可行性为主,不以历史兼容性为主"brownfield项目必须明确写明"评审以现有系统兼容性、影响范围、迁移成本为主"
Phase 3.6: 补充服务元数据
bootstrap_mode=greenfield 时跳过本节,保留已有元数据。其他模式由 scan-service-meta 或显式导入生成 docs/knowledge/service-meta.yaml,至少包含:
service: {service-name}
display_name: {service-display-name}
domain: {domain}
role: {gateway|orchestrator|domain|platform}
repo: <!-- TODO: repo url -->
owners:
- <!-- TODO: owner team -->
upstreams: []
downstreams: []
owned_data: []
published_events: []
consumed_events: []
capabilities: []
status_entities: []
要求:
service默认使用仓库目录名或已识别的服务名display_name优先取 README / 项目名中的业务展示名,无法确认则与service相同role根据代码特征判断:- 多下游编排明显 →
orchestrator - 以对外接入和参数适配为主 →
gateway - 以领域主写数据和核心业务规则为主 →
domain - 以通用支撑能力为主 →
platform
- 多下游编排明显 →
owned_data来自 scan-db + scan-service 可确认的主写表/实体published_events/consumed_events来自 MQ 扫描结果capabilities来自service-boundary.md和domain-model.md提炼- 无法确认的字段保留
<!-- TODO: 待确认 -->或空数组,不推断
Phase 4: 配置 hooks/
Step 4.1 生成 Hook 配置文件:
docs/hooks/index.md— Hook 机制总览(区分 runtime hooks / workflow gates / review checklists)docs/hooks/post-action.md— 写后的快速自动检查(invariant 与 specs/evidence 一致性提醒)docs/hooks/cr-checklist.md— CR 检查清单(代码规范、invariants、架构约束、tasks checkpoint、verification 证据、finding 对账)
Step 4.3 按 Host Kit 将 runtime hooks 写入项目级配置:
- 完整读取当前
resources.project_hooks,不得自行构造事件名、matcher、JSON 路径或 payload。 settings_file=null或merge_strategy=unsupported:跳过,不创建替代配置。owner=bootstrap:按reference/runtime-preflight.md从父流程绑定的插件根使用当前系统的启动器执行{helix_python} "{plugin_root}/scripts/project_hooks_cli.py" --repo-root "{repo_root}" --platform "{canonical_host_id}" merge。 使用原有宿主写入权限,按脚本结果确认合并。owner=parent:不得写 settings;在 final 返回结构化PROJECT_HOOKS_MERGE_REQUEST,包含资源路径、 目标 settings 和已生成的两个 linter 路径,由父流程校验后串行合并。- 资源与
resources.project_config.settings_file不一致时BLOCKED: project_hooks_contract_invalid。
Phase 5: 生成或追加 Host Kit 入口文件
入口文件处理:
- 若 Host Kit 的
entry_file已存在 → 进入下方追加规则; - 若不存在 → 基于 Host Kit 的
entry_template生成entry_file; - 不探测其他宿主的入口文件,也不同时生成多个入口文件。
追加规则:读取 entry_template,提取其中的“目录导航”“关键约束速览”“常用命令”
“Agent 工作规则”四个区块,以 ## HelixHarness 导航 为标题追加到 entry_file 末尾。关键约束
速览中的占位符用实际生成的 harness invariants 填充。
追加前检查文件末尾是否已包含 ## HelixHarness 导航 或 ## Agent 工作规则 区块:
- 若已存在 → 不重复追加,仅确认内容是否需要更新
- 若不存在 → 追加完整区块
无论新增还是追加,入口文件最终必须包含以下核心内容:
- 项目概述(技术栈、架构风格、业务领域)
- 目录导航地图(指向 harness/、knowledge/、specs/、hooks/)
- 关键约束速览(最重要的 3-5 条 invariants)
- 常用命令速查(/helix:propose、/helix:apply 等)
- Agent 工作规则(含 harness 和 knowledge 的按需加载协议引用)
Phase 5.5: 最终提交 state file
bootstrap_mode=greenfield 时本 job 不写 state:由父流程通过所有产物和 hooks 门禁后统一收尾。
其他模式只有 Phase 4 hooks 与 Phase 5 Host Kit 入口全部生成并通过逐项验证后,才使用公共
Read/Edit/Write 工具语义原子更新 docs/.helixharness-init-state.json;其他宿主只按
resources.runtime 映射,不依赖外部 JSON CLI:
- state 文件缺失、为空或不是 JSON 对象时立即
BLOCKED:init_state_missing,不得跳过后继续完成。 scanPlan为空时补后端六路数组;已有非空计划保持不变。设置scanStatus=completed。bootstrap_mode=fullstack-base时设置bootstrapStatus=backend_completed、写backendCompletedAt并移除过早的completedAt;service 模式设置bootstrapStatus=completed与completedAt。所有*At字段固定为当前 UTC Unix epoch 秒的 JSON number,与既有状态产物类型一致,不得写 ISO 字符串或宿主本地时间文本。- 从实际文件列表构造排序、去重后的
deliverables.knowledge.files和deliverables.harness.files,count必须等于对应数组长度。 - 只修改上述字段,保留其他键。写入后重新
Read,确认 JSON 可解析、字段类型正确、入口、hooks 及所有 deliverable 文件均存在;任一步失败报告BLOCKED:init_state_update_failed。
不要删除
docs/.helixharness-init-state.json(供后续命令使用)。
Phase 6: 输出初始化报告
bootstrap_mode=greenfield 时在终态回执列出真实生成的文件、待确认信息及“跳过扫描”;
不使用下方扫描产物清单。最终完成结论由父流程在验收与 state 收尾通过后发布。
## HelixHarness 初始化完成
### 项目信息
- 项目模式: {project-mode}
- 语言: {language}
- 框架: {framework}
- 数据库: {database}
- 架构: {architecture style}
- 业务领域: {domain}
### 生成的文件
- [x] Host Kit `entry_file`
- [x] Host Kit `settings_file` 已按 `resources.project_hooks` 合并,或明确为跳过/parent-owned
- [x] docs/harness/index.md
- [x] docs/harness/invariants/index.md + 相关叶子规则 — {N} 条规则
- [x] docs/harness/architecture/index.md
- [x] docs/harness/infrastructure/index.md + 相关叶子规则 — {N} 个规范文件
- [x] docs/specs/active/、docs/specs/completed/ — 仅创建目录;需求工件由后续 Propose/Apply 生成
- [x] docs/harness/linters/index.md
- [x] docs/harness/linters/invariant-check.py
- [x] docs/knowledge/index.md
- [x] docs/knowledge/prd/
- [x] docs/knowledge/prd/index.md
- [x] docs/knowledge/project-context.md
- [x] docs/knowledge/architecture.md
- [x] docs/knowledge/domain-model.md
- [x] docs/knowledge/domain-mapping.md(空模板,需手动填写)
- [x] docs/knowledge/service-meta.yaml
- [x] docs/knowledge/service-boundary/ — 服务职责边界
- [x] docs/knowledge/api/ — {N} 个接口文档
- [x] docs/knowledge/database/ — {N} 张表
- [x] docs/knowledge/exp/index.md
- [x] docs/specs/active/
- [x] docs/specs/completed/
- [x] docs/hooks/index.md
- [x] docs/hooks/post-action.md
- [x] docs/hooks/cr-checklist.md
- [x] docs/eval/.gitkeep(仅数据统计开启时)
- [x] .gitignore 中包含 `docs/eval/**` 提交例外(仅数据统计开启时)
### 下一步
1. 审核 docs/harness/ 下的约束文件,补充项目特有规则
2. 审核 docs/knowledge/ 知识库,确认准确性
3. 执行 /helix:propose <feature-name> 开始第一个需求开发
注意事项
- 不删除已有内容 — 已存在的文件保持不动,只补充缺失文件
- 不捏造信息 — 无法通过扫描或用户确认的内容标注
<!-- TODO: 待确认 --> - 约束须有规范性来源 — 遵守
reference/harness-generation-protocol.md;当前代码行为写入知识库,不能单凭现状生成不可变硬规则 - 空项目处理 — 若无代码,通过交互收集信息后基于模板生成,并显式标记
project-mode: greenfield
任务:执行 workspace 初始化
你负责在多 repo workspace root完成 HelixHarness workspace 初始化。
执行前必须消费顶层 init 已解析的 Host Context,读取 resources.project_config:
entry_file 是 workspace 根唯一入口文件,workspace_entry_template 是本流程使用的模板;
entry_template 仅供单仓 init 使用,settings_file 在 workspace 模式不写。宿主工具语义读取
resources.runtime,禁止按平台名硬编码入口文件。
输入
- workspace 根目录
- 原始参数:
$ARGUMENTS - repo 发现结果
- 每个 repo 的 HelixHarness 初始化状态
产物边界
workspace init 只写 workspace 根目录下的协调层产物:
- Host Kit 的
entry_file helixharness.workspace.yamldocs/knowledge/service-catalog.yamldocs/knowledge/service-graph.mddocs/knowledge/integration-boundaries.mddocs/knowledge/index.mddocs/specs/active/docs/specs/completed/
不得自动进入子 repo 执行单仓 /helix:init,也不得改写 repo-local docs/harness/。
强制要求:
- 所有上述产物必须落在 workspace root,即当前命令执行目录下
- 子 repo 已存在 HelixHarness 初始化产物时,只读取它们,不重新生成、不覆盖、不刷新、不迁移
- 子 repo 未初始化时,只在
helixharness.workspace.yaml标记initialized: false,不自动补初始化 - 不得只在各服务子目录下生成
.helixharness/文件后就报告完成 .helixharness/telemetry.json、.helixharness/upload-state.json是 repo-local 运行期/遥测文件,不属于 workspace init 目标产物- 若只能生成 repo-local
.helixharness/文件而无法生成 workspace root 产物,必须报告BLOCKED: workspace_root_outputs_not_created
Phase 0:确认 workspace root
检查当前目录是否为 workspace root:
- 当前目录本身可以不是 git repo
- 当前目录下一层或
--repos指定路径中应包含一个或多个 git repo - 若没有发现任何 repo,报告 BLOCKED,并提示用户使用:
/helix:init --workspace --repos <repo-paths...>
Phase 1:生成 helixharness.workspace.yaml
对每个 repo 写入 registry 信息。
格式:
version: 1
workspace:
name: {workspace-directory-name}
root: .
mode: multi-repo
repos:
{repo-key}:
path: ./{repo-path}
remote: {remote-url-or-null}
default_branch: {default-branch-or-current-branch-or-TODO}
role: {role-or-TODO}
helix:
initialized: true|false
service_meta: docs/knowledge/service-meta.yaml|null
规则:
- repo key 默认取目录名;冲突时停止并询问用户,不要自动改名
remote优先取originfetch URL,无法确认写nulldefault_branch优先取远端默认分支,无法确认用当前分支并标注 TODOrole优先从service-meta.yaml的role或 README/部署配置推断;无法确认写TODOhelixharness.initialized只表示当前宿主入口、harness/knowledge index 与 specs 目录是否齐备,不代表业务服务是否可运行service_meta是后端/服务仓增强项;纯前端 repo 可为null,不得据此把已初始化前端仓降为 missing
Phase 1.5:生成 workspace 根入口文件
在 workspace root 生成 Host Kit 的 entry_file,作为当前宿主的 workspace 入口规则。
优先读取此 plugin 捆绑模板:
Host Kit 的 `workspace_entry_template`
若 workspace root 已存在 entry_file:
- 不覆盖用户已有内容
- 只在文件末尾追加或更新
HelixHarness Workspace导航区块 - 不写入 repo-local harness 规则
workspace 入口文件必须明确:
- 当前目录是 HelixHarness workspace root
- 发现
helixharness.workspace.yaml时,Propose/Apply/Archive 由 Router 选择 Workspace scope;其他命令遵循各自的适用范围 - Workspace 根 feature 只保存概要设计
docs/specs/active/{feature}/spec.md,协调跨仓影响范围与依赖 - 各子仓独立执行完整 Single Propose/Apply/Archive:Propose 生成
spec.md、tasks.md,Apply 生成verify-report.md;Archive 校验并移动这三份工件 - 不生成独立 proposal、design、verification、apply-report 或 repo-plan 文件
- 不得绕过 workspace spec 直接进入 repo 子目录生成 feature spec
- repo-local Host Kit 入口文件只在 repo agent 执行本 repo 任务时读取,不作为 workspace propose 的主入口
Phase 2:聚合 service catalog
生成 docs/knowledge/service-catalog.yaml。
优先读取每个 repo 的:
docs/knowledge/service-meta.yaml- README
- OpenAPI / Swagger / RPC IDL
- package / module / artifact 名称
- 部署配置中的服务名
示例结构:
version: 1
services:
- repo: order-api
path: ./order-api
service: order-api
display_name: Order API
domain: order
role: domain
initialized: true
evidence:
- ./order-api/docs/knowledge/service-meta.yaml
无法确认的字段保留 TODO 或空值,不得捏造。
Phase 3:生成 service graph
生成 docs/knowledge/service-graph.md,包含:
- 服务清单
- 已确认调用关系
- MQ topic producer / consumer
- 数据 ownership
- 不确定关系
不确定关系必须带 evidence、confidence、needs_confirmation:
uncertain_edges:
- from: order-api
to: coupon-api
type: http|rpc|mq|data|unknown
evidence: "CouponClient found in ./order-api/src/..."
confidence: medium
needs_confirmation: true
Phase 4:生成 integration boundaries
生成 docs/knowledge/integration-boundaries.md,至少包含:
- workspace 中每个 repo 的职责摘要
- repo 间 API/RPC/MQ/DB 边界
- 已确认 ownership
- 待确认边界
- 后续 propose 阶段如何使用这些信息做 feature-specific impact scan
Phase 5:生成 workspace knowledge index
生成或更新 docs/knowledge/index.md,使用三列表格:
| 文件/目录 | 定位 | 加载时机 |
|----------|------|----------|
| service-catalog.yaml | workspace 服务目录 | workspace propose/apply/archive 按阶段读取 |
| service-graph.md | workspace 服务关系图 | 涉及跨服务调用、MQ、DB ownership 时 |
| integration-boundaries.md | 跨 repo 集成边界 | 识别影响面、设计跨服务契约时 |
Phase 6:输出报告
输出报告前必须执行后置检查:
test -f ./helixharness.workspace.yaml
test -f "./{entry_file}"
test -f ./docs/knowledge/service-catalog.yaml
test -f ./docs/knowledge/service-graph.md
test -f ./docs/knowledge/integration-boundaries.md
test -f ./docs/knowledge/index.md
test -d ./docs/specs/active
test -d ./docs/specs/completed
若任一检查失败,不得输出“完成”,改为输出:
BLOCKED: workspace_init_outputs_missing
缺失:
- {path}
已发现但不计入成功条件的 repo-local 运行期文件:
- {repo}/.helixharness/telemetry.json
- {repo}/.helixharness/upload-state.json
## /helix:init --workspace 完成
### 已生成
- [x] Host Kit 入口文件:`{entry_file}`
- [x] helixharness.workspace.yaml
- [x] docs/knowledge/service-catalog.yaml
- [x] docs/knowledge/service-graph.md
- [x] docs/knowledge/integration-boundaries.md
### Repos
| Repo | Path | HelixHarness | service-meta | 备注 |
|------|------|-------------|--------------|------|
| {repo} | {path} | initialized/missing | yes/no | {TODO/uncertain} |
### 待确认
- {uncertain_edges 或 role/TODO}
### 下一步
/helix:propose <feature> <requirement-or-path>
约束
helixharness.workspace.yaml是 repo registry,不是完整系统知识库- 服务关系基线要有证据;没有证据就进入 uncertain_edges
- 不覆盖用户已有 workspace 文档;refresh 时尽量保留人工补充字段
任务:生成项目 API 接口清单(含完整出入参)
你是一名后端架构师。请扫描整个代码库,生成一份完整的 API 接口清单,每个接口须展开所有请求参数和响应字段,而非仅列出类型名。
输出要求
- 位置:
docs/knowledge/api/index.md(接口总览 + 模块索引,作为内容文件由根knowledge/index.md索引),各模块详细接口输出到docs/knowledge/api/{module}-api.md - 格式:Markdown,按模块分组,每个接口独立小节
扫描策略
步骤 1:HTTP REST 接口扫描
1.1 接口定位
- 查找
@RestController/@Controller类 - 拼接类级别
@RequestMapping+ 方法级别@GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping - 提取参数位置:
@PathVariable→ 路径参数@RequestParam→ 查询参数(记录 defaultValue、required)@RequestBody→ 请求体,记录类型名,进入步骤 1.2 展开字段@RequestHeader→ 请求头参数
- 提取返回类型(方法签名),进入步骤 1.2 展开字段
- 扫描认证注解:
@PreAuthorize/@LoginRequired/@AuthCheck/@NeedLogin→ 标记是否需要鉴权 - 优先取
@ApiOperation(Swagger 2)/@Operation(OpenAPI 3)的value作为功能描述,其次取方法 Javadoc,最后从方法名推断
1.2 出入参字段展开(关键步骤)
对每个 @RequestBody 类型和返回值类型,执行以下操作:
- 找到类定义:搜索对应的 Java/Kotlin/Go 类文件
- 提取所有字段:
- Java:读取所有非
static、非transient字段,优先取@JsonProperty的实际字段名 - 若字段有
@ApiModelProperty(Swagger 2)/@Schema(OpenAPI 3),提取value/description作为字段说明 - 若字段有
@NotNull/@NotBlank/@NotEmpty等 Bean Validation 注解,标记为必填 - 若字段类型是另一个自定义类(非 Java 基础类型/集合),递归展开该类的字段(最多递归 3 层,超出则只记录类型名)
- 若字段类型是
List<T>/Set<T>,记录为Array<T类型>,并展开 T 的字段 - 若字段类型是
Map<K,V>,记录 key/value 类型
- Java:读取所有非
- 处理继承:若类继承父类,合并父类字段
- 处理泛型包装:若返回值是
Result<T>/ApiResponse<T>/CommonResult<T>等统一响应包装,先展开包装类的公共字段,再展开data字段对应的 T 类型
步骤 2:Thrift RPC 接口扫描
- 扫描本系统暴露的 RPC 服务端处理器(Handler)。规则为:查找类定义中实现了 *.Iface 接口,且被 Spring 容器托管(如带有 @Service、@Component 等注解),或包路径属于服务端 handler 层的类(如 XxxHandler implements XxxService.Iface) 数据源优先级与解析流程:
- 优先使用 .thrift 文件(理想态):
- 从 service 定义直接提取方法名、入参 struct 和返回 struct,并递归展开 struct 下所有字段(1: required string name)。
- 无 .thrift 文件时的兜底策略(常见态):
- 若项目中找不到对应的 .thrift 文件,则回退到解析 Java 类的字节码/源码。
- 直接从 Handler 中的 Java 方法签名提取入参类和返回类型类。 对这两个类(即 Request/Response 结构体)进行字段展开,获取完整的字段清单。
- 特殊场景处理(返回类型为 Object):
- 由于部分旧项目或者为了保持通用性,Thrift 接口的返回值会被声明为 Object(如 Object getXxx(XxxRequest request))。
- 当检测到 Java 方法返回类型为 Object 时,扫描器必须跳过接口层,深入检查其对应的 Handler 实现类(如 XxxHandler)的实际返回类型。通常实际业务代码中会返回具体的 Thrift 生成的 Struct(如 GetUserResponse)。
- 若实现类上也未明确(例如完全泛型化),命名约定只能作为继续查找的线索,不能据此确认返回类型或字段。继续核对接口声明、真实返回语句、协议文件、测试或用户明确确认的映射,并记录来源;仍无法验证时将返回类型和未展开字段标为“待确认”,列出缺失证据,不生成猜测的完整对象结构,也不要求业务项目新增映射代码。
步骤 3:gRPC 接口扫描
- 查找继承
*Grpc.*ImplBase的类 - 优先读取
.proto文件:从service定义提取 rpc 方法;从message定义展开所有字段(field number、类型、名称) - 标注
repeated字段为数组类型 - 标注
oneof字段
步骤 4:Dubbo 接口扫描
- 查找
@DubboService/@Service(com.alibaba.dubbo)类 - 找到对应的接口定义类,提取所有方法签名
- 按步骤 1.2 展开出入参字段
步骤 5:通用规则
- 按模块分组:根据包名或类名前缀推断所属业务模块
- API 版本:识别路径中的
/v1/、/v2/等版本前缀并保留 - 枚举类型处理:若字段类型为枚举,列出所有枚举值及含义(从枚举类注释或
@ApiModelProperty提取)
输出格式
api.md(总览)
# API 接口清单
> 生成时间:YYYY-MM-DD
> 信息来源:OpenAPI 规范文件 / 代码扫描(二选一标注)
> 接口总数:N 个(HTTP: X 个,Thrift: Y 个,gRPC: Z 个)
## 模块索引
| 序号 | 模块 | 协议 | 接口数 | 详情文件 |
| :--- | :--- | :--- | :--- | :--- |
| 1 | 用户 | HTTP REST | 8 | [user-api.md](./user-api.md) |
| 2 | 订单 | HTTP REST | 12 | [order-api.md](./order-api.md) |
| 3 | 积分 | Thrift RPC | 5 | [credit-api.md](./credit-api.md) |
{module}-api.md(模块详情,每接口独立小节)
# {模块名} API 文档
> 协议:HTTP REST
> 基础路径:/api/v1/users
> 入口类:UserController
---
## 接口列表
| 序号 | 路径 | 方法 | 功能 | 需要鉴权 |
| :--- | :--- | :--- | :--- | :--- |
| 1 | /api/v1/users/{id} | GET | 查询用户详情 | 是 |
| 2 | /api/v1/users/login | POST | 用户登录 | 否 |
---
## GET /api/v1/users/{id} — 查询用户详情
**入口**:`UserController.getById`
**鉴权**:需要(@LoginRequired)
**描述**:根据用户 ID 查询用户详细信息
### 请求参数
| 位置 | 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| Path | id | Long | 是 | 用户 ID |
### 响应(`Result<UserVO>`)
**包装结构**
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| code | Integer | 状态码,0=成功 |
| message | String | 提示信息 |
| data | UserVO | 用户信息,见下方 |
**data 字段(UserVO)**
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| id | Long | 是 | 用户 ID |
| nickname | String | 是 | 用户昵称 |
| phone | String | 是 | 手机号(脱敏) |
| avatarUrl | String | 否 | 头像 URL |
| status | Integer | 是 | 用户状态:0=禁用,1=正常,2=冻结 |
| createdAt | Long | 是 | 注册时间戳(毫秒) |
---
## POST /api/v1/users/login — 用户登录
**入口**:`UserController.login`
**鉴权**:不需要
**描述**:账号密码登录,返回 JWT Token
### 请求参数
**Path 参数**:无
**Query 参数**:无
**请求体(LoginRequest)**
| 字段名 | 类型 | 必填 | 校验规则 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| username | String | 是 | @NotBlank, 长度 6-32 | 用户名或手机号 |
| password | String | 是 | @NotBlank | MD5 加密后的密码 |
| captchaCode | String | 否 | - | 图形验证码(触发风控时必填) |
### 响应(`Result<TokenVO>`)
**data 字段(TokenVO)**
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| accessToken | String | 是 | JWT Token |
| tokenType | String | 是 | 固定值 "Bearer" |
| expireIn | Long | 是 | 有效期(秒) |
| refreshToken | String | 否 | 刷新 Token |
---
## CreditService.addCredit — 发放积分(Thrift RPC)
**服务名**:CreditService
**实现类**:CreditHandler.addCredit
**描述**:向指定用户账户发放积分
### 请求(AddCreditRequest)
| 字段编号 | 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| 1 | userId | i64 | 是 | 用户 ID |
| 2 | amount | i32 | 是 | 积分数量,必须 > 0 |
| 3 | bizType | string | 是 | 业务类型:ORDER/SIGN_IN/ACTIVITY |
| 4 | bizId | string | 是 | 业务单号,幂等 key |
### 响应(CreditResult)
| 字段编号 | 字段名 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| 1 | success | bool | 是否成功 |
| 2 | balance | i64 | 发放后余额 |
| 3 | errorCode | string | 失败错误码(失败时填充) |
注意事项
- 只输出对外暴露的接口,内部私有方法和
private方法不计入 - 若字段说明无法确定,标注
<!-- TODO: 待确认 --> - 字段嵌套超过 3 层时,只记录类型名并注明"详见 {ClassName} 定义"
- 若存在 OpenAPI 文件,在文档头部标注
信息来源:OpenAPI 规范文件({文件路径}) - 若仅从代码扫描,在文档头部标注
信息来源:代码扫描(准确性依赖注解完整性) - 若项目无任何接口定义,输出说明并退出
- 不要只输出表格摘要,每个接口必须有完整的出入参字段节
- 不修改共享
docs/knowledge/index.md。在 final 返回本 job 的已写入产物及索引建议,由 bootstrap 在扫描全部完成后串行合并索引。
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成服务职责边界文档
你是一名资深后端架构师。基于已有的服务能力地图,提炼一份极简、高信噪比的职责边界文档。
输入来源
主要读取 docs/knowledge/domain-model.md(scan-service 的输出),不重新扫描代码。
若 docs/knowledge/domain-model.md 不存在,直接读取代码库进行分析。
输出要求
- 主输出位置:
docs/knowledge/service-boundary.md - 可选补充位置:
docs/knowledge/service-boundary/(仅当能够按业务域或代码库稳定拆分时生成) - 格式:Markdown,总长度控制在 1 页以内
docs/knowledge/service-boundary.md 是后续流程读取职责边界的稳定文档入口,用于承载边界信息;knowledge 主入口仍是 docs/knowledge/index.md。目录版只是可选增强,不得作为唯一产物。
分析原则
拒绝流水账:不列举具体 API,只提炼业务领域。将"创建、查询、修改订单"合并为"订单全生命周期管理"。
核心性过滤:对每个功能问:如果没有它,这个服务还有存在意义吗?
- 是 → 写入核心职责
- 否 → 忽略
边界判断的代码信号:
| 判断维度 | 代码信号 | 结论 |
|---|---|---|
| 数据持有 vs 引用 | 有 INSERT/UPDATE → 持有;只有 SELECT → 引用 | 持有的数据才是"我的数据" |
| 编排层 vs 原子层 | 有多个 Feign/RPC 调用组合 → 编排;只操作自己的 DB → 原子 | 影响"核心定位"的描述 |
| 显性"不做"边界 | 存在 Feign 调用但无对应 DB 写操作的业务域 → 该域由下游负责 | 写入"不处理 XX" |
| 显性"不持有"边界 | 只读取其他服务数据(ID 引用或同步副本)→ 不持有该数据 | 写入"不持有 XX" |
不猜测:无法从 domain-model.md 或代码中确认的边界,标注 <!-- TODO: 待确认 -->,不推断。
输出格式
# [服务名称]:[一句话核心价值]
## 核心定位
`[关键词1]` `[关键词2]` `[关键词3]`
> [100字以内:在架构中的层级(网关/编排/领域/基础)、核心业务对象、最关键的数据归属。]
## 核心职责
- **[职责1]**:[一句话描述]
- **[职责2]**:[一句话描述]
- **[职责3]**:[一句话描述]
## 显性边界
- **不处理 XX**:[明确说明不负责的业务范围,及由谁负责]
- **不持有 XX**:[明确说明不持有的核心数据,及数据归属方]
注意事项
- 关键词只选 3 个,强迫优先级排序
- 核心职责不超过 5 条,超过说明边界不清晰
- 显性边界至少写 2 条,这是本文档最有价值的部分
- 整篇文档不超过 1 页,超过则说明还在罗列细节,需要继续提炼
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成项目数据模型清单
你是一名数据库架构师。请扫描整个代码库,生成一份完整的数据库表结构清单。
输出要求
- 位置:
docs/knowledge/database/index.md(表清单总览 + 字段详情,作为内容文件由根knowledge/index.md索引),ER 图独立输出到docs/knowledge/database/er.md - 格式:Markdown
- er.md 是独立的可视化文档,格式要求见下方"ER 图输出格式"章节
扫描策略
0. 表认定门槛(必须先判定,再进入表定义定位)
一张表只有在本仓库存在持久化证据时,才认定为"本服务数据表",纳入表清单与 ER 图。持久化证据 = 以下任一:
- ORM 映射:
@Entity/@Table/@TableName、MyBatis@Mapper/<resultMap>/Mapper XML、GORM Model、JPA Repository - 数据访问接入:JDBC/数据源配置(
spring.datasource/JDBC URL/HikariCP/Druid)、@DS、有效 JDBC/MyBatis/JPA 依赖
以下不构成认定依据,不得据此新增表到清单或 ER 图:
- 测试类(
src/test/)里硬编码的表名或 SQL - 代码注释、TODO、文档中提到的表名
- 字符串常量、日志文本中出现的表名
- 下游 RPC 返回结构反推的表名
判定流程:先确认本仓库是否存在上述持久化证据,再决定是否进入后续扫描:
- 四类证据全部为空 → 判定"本服务无直连数据库":跳过下方「表定义定位 / 枚举识别 / 索引识别 / 分库分表识别 / 多数据源标注」全部扫描步骤,直接按"输出格式"中的「无表情形」模板生成
database/index.md与er.md。严禁仅凭表名引用产出表清单。- 任一类证据非空 → 进入下方扫描流程,按有表模板产出正常表清单。
1. 表定义定位
按以下优先级扫描,尽量多源交叉验证:
Java 项目 扫描策略(含多模式兼容):
- 优先识别 JPA/Hibernate 模式:扫描 @Entity / @Table 和 @Column 注解。如果此类注解覆盖度较高,以此为主。
- MyBatis 模式兜底:若 JPA 注解极少,则重点扫描 src/main/resources/mapper/ 下的 XML 文件。提取 的列映射,并使用 JSqlParser 解析 SQL 语句中的表名。
- 纯 SQL 正则/解析兜底:针对无法定位到实体类的项目,遍历所有 DAO/Service 层代码,提取 SQL 字符串,匹配 FROM、JOIN、INSERT INTO 关键字。
Go 项目
- GORM Model 定义(
gorm:"column:xxx") - SQL migration 文件(
.sql)
通用
sql/、migrations/、schema/、db/目录下的.sql文件CREATE TABLE语句 → 最权威的 schema 来源,优先使用
2. 枚举识别
- 找到字段关联的枚举类,列出所有枚举值和含义
- 若无枚举类,从注释或业务代码中推断状态含义
- 枚举值必须写入 database.md 对应字段的"枚举值说明"列,格式:
值:含义,多个值用顿号分隔,如0:禁用、1:正常、2:冻结
3. 索引识别
@Index/@UniqueConstraint注解- SQL 文件中的
CREATE INDEX/UNIQUE KEY语句 - GORM tag 中的
uniqueIndex/index
4. 分库分表识别
- ShardingSphere 配置文件
- 自定义分表注解或路由逻辑
- 若无分表,填"无"
5. 多数据源标注
- 识别
@DS注解(dynamic-datasource)或多 DataSource Bean 配置 - 标注每张表属于哪个数据源
输出格式
database.md 格式
# 数据模型清单
> 生成时间:YYYY-MM-DD
> 数据表总数:N 张
## 1. 表清单总览
| 序号 | 表名 | 中文名称 | 核心字段 | 分库分表 | 数据源 | 所属模块 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 1 | users | 用户表 | id, name, phone, status | 无 | master | 用户 |
| 2 | orders | 订单表 | id, user_id, amount, status | user_id % 16 | order_db | 订单 |
## 2. 表字段详情
### 2.1 users(用户表)
| 字段名 | 数据类型 | 允许为空 | 默认值 | 字段含义 | 枚举值说明 |
| :--- | :--- | :---: | :--- | :--- | :--- |
| id | bigint | 否 | - | 主键ID | - |
| name | varchar(64) | 否 | - | 用户姓名 | - |
| status | tinyint | 否 | 1 | 用户状态 | 0:禁用、1:正常、2:冻结 |
| created_at | datetime | 否 | CURRENT_TIMESTAMP | 创建时间 | - |
> 枚举值说明:有枚举类或注释时必须填写完整,格式为 `值:含义`,多个值用顿号分隔;无法确定时标注 `<!-- TODO: 待确认 -->`
**索引**
| 索引名 | 类型 | 字段 | 说明 |
| :--- | :--- | :--- | :--- |
| PRIMARY | 主键 | id | - |
| uk_phone | 唯一索引 | phone | 手机号唯一 |
| idx_status | 普通索引 | status | 按状态查询 |
---
*共计 N 张数据表*
无表情形(database/index.md)
当"表认定门槛"判定本服务无直连数据库时,跳过上方有表模板,按以下模板输出 database/index.md:
# 数据模型清单
> 生成时间:YYYY-MM-DD
> 数据表总数:0 张
## 扫描结论
本服务无直连数据库(未识别到任何持久化证据)。
已验证为空的证据清单:
- 无 `@Entity` / `@Table` / `@TableName` 等 ORM 映射注解
- 无 MyBatis `@Mapper` / `<resultMap>` / Mapper XML
- 无 `CREATE TABLE` / DDL 文件(`sql/`、`migrations/`、`schema/`、`db/` 目录下均无)
- 无数据源配置(`spring.datasource` / JDBC URL / HikariCP / Druid / `@DS`)
- 无有效 JDBC / MyBatis / JPA 依赖
> 结论:本服务不直接持有数据表。代码中出现的表名仅为文本引用,权威 schema 需查阅下游数据服务。
## 表清单总览
(无)
## 表字段详情
(无)
## 附录:跨服务数据线索(非本服务表)
> 仅当代码(测试类/注释/字符串)中确实出现表名引用时填写本节;否则整节省略。
| 引用表名 | 来源文件:行号 | 引用上下文 | 推测归属服务 |
| :--- | :--- | :--- | :--- |
| xxx | src/test/.../FooTest.java:42 | 测试 SQL 中出现 | 待确认 |
er.md 格式
er.md 是独立的 ER 关系图文档,按业务模块分区,每个模块用独立 mermaid 代码块展示,并附带文字说明提升可读性。
# ER 关系图
> 生成时间:YYYY-MM-DD
> 说明:按业务模块分区展示,聚焦核心关联字段,省略纯审计字段(created_at / updated_at 等)
---
## 模块一:用户体系
**包含表**:users、user_profiles、user_roles
**关系说明**:
- `users` 1:1 `user_profiles`:每个用户对应一份扩展信息
- `users` N:N `roles`(通过 `user_roles` 中间表):用户可拥有多个角色
```mermaid
erDiagram
users ||--|| user_profiles : "user_id"
users ||--o{ user_roles : "user_id"
roles ||--o{ user_roles : "role_id"
users {
bigint id PK "主键"
varchar(64) name "用户姓名"
varchar(20) phone UK "手机号"
tinyint status "0禁用 1正常 2冻结"
}
user_profiles {
bigint id PK
bigint user_id FK "关联 users.id"
varchar(255) avatar "头像URL"
}
roles {
int id PK
varchar(32) code UK "角色编码"
varchar(64) name "角色名称"
}
user_roles {
bigint user_id FK
int role_id FK
}
模块二:订单体系
包含表:orders、order_items、payments
关系说明:
orders1:Norder_items:一笔订单包含多个商品行orders1:Npayments:一笔订单可有多次支付记录(如拆单支付)
erDiagram
users ||--o{ orders : "user_id"
orders ||--o{ order_items : "order_id"
orders ||--o{ payments : "order_id"
orders {
bigint id PK
bigint user_id FK "关联 users.id"
decimal(10-2) amount "订单总金额"
tinyint status "1待付 2已付 3已发货 4已完成 5已取消"
}
order_items {
bigint id PK
bigint order_id FK
bigint sku_id FK
int quantity "购买数量"
decimal(10-2) price "成交单价"
}
payments {
bigint id PK
bigint order_id FK
decimal(10-2) amount "实付金额"
tinyint channel "1支付宝 2微信 3银行卡"
}
跨模块关联
说明:列出跨越以上模块边界的关联关系,帮助理解整体数据流向。
| 主表 | 关联表 | 关联字段 | 关系 | 跨模块含义 |
| :--- | :--- | :--- | :--- | :--- |
| orders | users | orders.user_id → users.id | N:1 | 订单归属用户(订单体系 → 用户体系) |
er.md 生成规则:
- 按业务模块聚合,每模块一个 mermaid 块,不要把所有表塞进一个图
- 每个实体只写核心字段(主键、外键、关键业务字段),省略 created_at / updated_at / deleted_at 等审计字段
- 字段注释用引号写在类型后面,把枚举值的关键含义直接标在字段上(如
"0禁用 1正常") - 每个模块前写"关系说明"文字,用自然语言描述关联含义,不要只靠图形表达
- 跨模块的外键关系统一收录到最后的"跨模块关联"表格中
无表情形(er.md)
当本服务无直连数据库时,er.md 只写一段说明,不画任何 mermaid 图:
# ER 关系图
> 生成时间:YYYY-MM-DD
> 说明:本服务无直连数据库,未识别到任何数据表,无可绘制 ER 关系。
注意事项
- 若同一张表在多处定义(Entity + SQL 文件),以 SQL 文件为准,Entity 作为补充
- 无法确定枚举含义时标注
<!-- TODO: 待确认 --> - 无法确定中文名称时标注
<!-- TODO: 待确认 --> - 不修改共享
docs/knowledge/index.md。在 final 返回本 job 的已写入产物及索引建议,由 bootstrap 在扫描全部完成后串行合并索引。
无数据库情形
若经"表认定门槛"判定本仓库无任何持久化证据(四类全空):
- 直接套用上方输出格式中的「无表情形」模板:
database/index.md走"无表情形(database/index.md)"模板,er.md走"无表情形(er.md)"模板;表清单总数为 0,不画 mermaid 图,严禁沿用有表模板。 database/index.md顶部"扫描结论"明确写"本服务无直连数据库",并列出已验证为空的证据清单(无 @Entity/@Table、无 Mapper、无 DDL、无 datasource 等)。- 代码中出现的表名(测试类/注释/字符串)一律不进入表清单与 ER 图;确有参考价值时,收敛到
database/index.md末尾"## 附录:跨服务数据线索(非本服务表)"小节,逐条标注来源文件:行号,并注明"仅文本引用,非本服务表,权威 schema 需查阅下游 XX 中心服务"。 - 不得为凑数把推断表塞进表清单或 ER 图。
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成前端 API 调用清单
你是一名前端 API 专家。只扫描 API 封装层 和 HTTP 端点引用,不关心组件、状态、路由。
输出位置
docs/knowledge/api-endpoints.md
扫描策略
0. 预检:定位实际 API 目录
不要在枚举路径里猜——先用内容特征反推实际位置:
# 方法 1:从 HTTP 客户端调用反推封装层位置
grep -rh "import.*from.*['\"].*\(request\|axios\|http\|fetch\)" \
{src,client,frontend,web,apps} 2>/dev/null | sort | uniq -c | sort -rn | head -10
# 方法 2:直接找可能的请求封装目录
API_DIRS=$(find {src,client,frontend,web,apps} -type d \
\( -name "api" -o -name "services" -o -name "requests" -o -name "http" \) 2>/dev/null | head -5)
# 方法 3:找请求实例文件(axios.create / fetch wrapper)
grep -rl "axios.create\|new.*Request\|createHttpClient" \
{src,client,frontend,web} --include="*.ts" --include="*.js" 2>/dev/null | head -5
有结果 → 用实际路径;无结果 → fallback 到下方枚举路径。
1. 定位 API 封装层
查找请求封装文件:
src/api//src/services//src/requests/src/utils/request.{ts,js}/src/common/request.{ts,js}client/common/request.{ts,js}- 任何 export 了
request/axios/fetchwrapper 的文件
2. 解析封装基类
- 基础实例:axios / fetch / ky / superagent
- 请求拦截器:token 注入、签名、通用 header
- 响应拦截器:业务码处理、错误统一提示、token 失效跳转登录
- 错误处理策略:统一错误码映射、全局 toast
- 超时配置
- 取消请求:AbortController / CancelToken
3. 提取 API 端点清单
遍历所有源文件(.vue / .ts / .tsx / .js)中的 HTTP 调用:
- 直接 axios 调用:
axios.get/post/put/delete - request 实例调用:
request.get('/user') - 函数封装:
apiGetUser()fetchUser()
对每个调用提取:
- HTTP 方法:GET / POST / PUT / DELETE
- 路径:
/api/user/login//v2/order/list - 调用方:所在文件 + 所在函数
- 参数类型:从 TypeScript 类型签名提取
- 响应类型:从泛型参数提取
4. 按模块分组
按 API 端点前缀分组:
/api/user/*→ 用户模块/api/order/*→ 订单模块
输出格式
# 前端 API 调用清单
> 生成时间:YYYY-MM-DD
> 封装基础:{axios / fetch / ...}
> 端点总数:{N}
## 封装层
| 文件 | 职责 |
|------|------|
| src/utils/request.ts | axios 实例 + 拦截器 |
| src/api/user.ts | 用户模块 API |
| src/api/order.ts | 订单模块 API |
## 拦截器
### 请求拦截器
- 注入 `Authorization: Bearer ${token}`
- 注入 `X-Request-Id: uuid()`
### 响应拦截器
- 业务码 0 成功,其他抛出业务异常
- 401 跳转登录
## 端点清单
### 用户模块 `/api/user/*`
| 方法 | 路径 | 调用方 | 参数 | 响应 |
|------|------|--------|------|------|
| POST | /api/user/login | Login.vue#handleLogin | `{username, password}` | `{token, userInfo}` |
| GET | /api/user/info | useUserStore#fetchUser | - | `IUserInfo` |
| ... | ... | ... | ... | ... |
### 订单模块 `/api/order/*`
...
注意事项
- 无法确定的字段标注
<!-- TODO: 待确认 --> - 非前端项目直接退出,不生成文件
- 端点清单超过 80 条时折叠为概要 + 详细表格(按模块)
- 重点关注高频调用端点(被多处引用的)
- 不要展开 mock 数据处理(除非 mock 是核心模式)
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成前端组件清单(两阶段)
你是一名前端组件专家。不要试图逐个阅读所有组件文件——用两阶段策略高效产出。
输出位置
docs/knowledge/components.md
Phase 1:快速清单 + 评分
0. 预检:定位实际前端目录
不要在枚举路径里猜——用 .vue/.tsx 文件密度反推实际位置:
# 方法 1:统计各候选根目录下组件文件数,最多者即为前端根目录
for d in src client frontend web apps; do
count=$(find "$d" -name "*.vue" -o -name "*.tsx" -o -name "*.jsx" 2>/dev/null | wc -l)
echo "$count $d"
done | sort -rn | head -1
# 取出 count 最大的那个目录作为 FRONTEND_ROOT
# 方法 2:在 FRONTEND_ROOT 下找组件目录
COMPONENT_DIRS=$(find "$FRONTEND_ROOT" -maxdepth 2 -type d \
\( -name "components" -o -name "widgets" -o -name "ui" \) 2>/dev/null | head -3)
# 方法 3:找页面目录
PAGE_DIRS=$(find "$FRONTEND_ROOT" -maxdepth 2 -type d \
\( -name "pages" -o -name "views" -o -name "screens" -o -name "routes" \) 2>/dev/null | head -3)
# 如果 apps/ 是 monorepo,检查 apps/*/src 作为独立前端根目录
[ -d apps ] && find apps -maxdepth 3 -name "*.vue" -o -name "*.tsx" 2>/dev/null | cut -d/ -f1-3 | sort -u
有结果 → 用实际路径;无结果 → fallback 到下方枚举路径。
1.0 先识别框架(决定后续提取策略)
不同框架用不同语法声明 Props/Events/State。先识别再选 pattern:
# 从 package.json 识别前端框架
FRAMEWORK=$(grep -oE '"react"|"vue"|"@angular/core"|"svelte"|"preact"|"solid-js"' package.json 2>/dev/null | tr -d '"' | head -1)
case "$FRAMEWORK" in
vue)
EXT="{vue}"
PROPS_PATTERN="props\s*:|defineProps"
STATE_PATTERN="data\s*\(|ref\(|reactive\(|computed"
EVENTS_PATTERN="\$emit|emits\s*:"
CHILD_IMPORT_PATTERN="import.*from.*['\"]\.\/"
;;
react|preact|solid-js)
EXT="{tsx,jsx}"
PROPS_PATTERN="interface.*Props|type.*Props|PropTypes\.|FC<"
STATE_PATTERN="useState|useReducer|useRef|createSignal"
EVENTS_PATTERN="on[A-Z]\w*\s*\??:|dispatch|createSignal"
CHILD_IMPORT_PATTERN="import.*from.*['\"]\.\/"
;;
*)
# Svelte / Angular / 未知 — 宽泛兜底
EXT="{vue,tsx,jsx,svelte}"
PROPS_PATTERN="props\s*:|defineProps|@Input\s*\(|export let|interface.*Props"
STATE_PATTERN="data\s*\(|ref\(|useState|reactive\(|let\s+\w+\s*="
EVENTS_PATTERN="\$emit|emits\s*:|@Output\s*\(|createEventDispatcher|on[A-Z]\w*\s*\??:"
CHILD_IMPORT_PATTERN="import.*from.*['\"]\.\/"
;;
esac
echo "检测到框架: ${FRAMEWORK:-unknown}, 文件扩展名: $EXT"
1.1 收集元数据(框架自适应,批量不逐个读)
FRONTEND_ROOT="<从预检获得的实际目录>"
SCAN_TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/helix-components.XXXXXXXX") || exit 1
printf '本次扫描临时目录:%s\n' "$SCAN_TMP_DIR"
# 1) 列出所有组件文件 + 行数(扩展名自适应)
find "$FRONTEND_ROOT" -name "*.${EXT}" -exec wc -l {} \; | sort -rn > "$SCAN_TMP_DIR/comp_lines.txt"
# 2) 批量检测哪些文件有 Props/Input
grep -rl "$PROPS_PATTERN" "$FRONTEND_ROOT" --include="*.${EXT}" > "$SCAN_TMP_DIR/comp_has_props.txt"
# 3) 批量检测哪些文件有 Events/Emits/Output
grep -rl "$EVENTS_PATTERN" "$FRONTEND_ROOT" --include="*.${EXT}" > "$SCAN_TMP_DIR/comp_has_events.txt"
# 4) 批量检测哪些文件 import 了本地组件(容器组件)
grep -rl "$CHILD_IMPORT_PATTERN" "$FRONTEND_ROOT" --include="*.${EXT}" > "$SCAN_TMP_DIR/comp_has_children.txt"
记录本次返回的临时目录绝对路径,后续评分和深度分析只读取该目录中的结果;跨 Shell 调用时显式传入此路径,不假设变量自动保留。完成产物写入或终止扫描后,仅删除本次创建的目录;不得通配清理其他扫描目录,也不要在结果读取前通过 Shell 退出清理它。
1.2 评分(框架无关)
对每个组件计算重要性分数:
| 维度 | 条件 | 分值 | 理由 |
|---|---|---|---|
| 页面入口 | 路径在 views/ / pages/ / screens/ 下 | +4 | 页面组件是功能入口,必须深入了解 |
| 有定义接口 | Props/Input 检测命中 | +3 | 有接口 = 被外部消费,需要知道签名 |
| 文件够大 | wc -l > 100 | +2 | 行数多 = 逻辑复杂 |
| 组合者 | import 了本地组件 | +2 | 包含子组件 = 容器模式 |
1.3 分级策略
| 分数 | 数量(典型) | Phase 2 行为 |
|---|---|---|
| ≥7 | ~50 | 深度展开:读文件,提取 Props + Events/Emits + State + 子组件 + 说明 |
| 4-6 | ~250 | 摘要:读文件首 80 行,提取 Props 名称清单 + 一行功能说明 |
| ≤3 | ~310 | 索引:仅输出组件名 + 路径 + 行数,不读文件内容 |
views/ / pages/ 下的页面组件直接给深度展开(+4 保底 → 至少到摘要级)。
Phase 2:按分级产出
深度展开(score ≥7,或在 views/pages 下)
使用 Python 脚本批量读取高分组件文件,用正则提取结构化信息,然后由你(LLM)做后处理:
- 按目录分组 + 业务标题
- 删除无意义字段(如继承来的空 Props)
- 添加功能说明
提取字段(按框架适配):
- 组件名称:文件名
- 文件路径:相对路径
- Props 定义:TypeScript interface、Vue props 对象、React PropTypes、Angular @Input()
- Events/Emits:
$emit/emits:/ callback propsonXxx/@Output() - 内部状态:
data()/ref()/useState()/useReducer()/ class 属性 - 子组件:import 的本地组件
- 一句话说明:这个组件是干什么的
摘要(score 4-6,非页面)
只读文件首 80 行:
- 组件名 + 路径
- Props 名称清单(如
visible, userInfo, onSubmit),不展开类型 - 一句话功能说明
索引(score ≤3)
只列:组件名 + 路径 + 行数,不读文件。
输出格式
(同之前,包含页面组件 / 深度展开 / 摘要 / 索引四个区块)
注意事项
- 先跑 Phase 1 的框架检测 + bash 扫描,拿到评分,再决定读哪些文件。不要一上来就挨个读。
- 推荐用 Python 脚本做批量提取:一次读取全部高分文件 + 正则提取,比逐个 Read 调用快 10 倍
- 非前端项目直接退出,不生成文件
- 无法确定的字段标注
<!-- TODO: 待确认 --> - Props 类型写 TypeScript 类型语法
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:前端元信息全景扫描
你是一名前端架构师。本 agent 合并了 4 个配置扫描任务(全部为配置驱动,扫描范围 < 20 个文件),按顺序串行执行:
- 技术栈识别(对应原
scan-tech的前端部分) - 构建配置扫描(原
scan-frontend-build) - 项目结构分析(原
scan-frontend-structure) - 样式方案识别(原
scan-frontend-style)
父流程必须传入可选 project_entry_file,其值来自当前 resources.project_config.entry_file;入口不存在时
按无项目入口处理。本 agent 不搜索或猜测其他宿主入口。
父流程还必须传入 architecture_mode=frontend-create|fullstack-merge:纯前端 fresh init 使用前者,
完整全栈使用后者;禁止从文件是否存在猜测项目类型。
为什么不并行:这 4 个子任务都是配置驱动(扫描范围 < 20 个文件),并行会引入 4 个独立产物文件 + 4 份 init 报告,复杂度高但收益低。对一个"每个项目只跑一次"的初始化场景,串行更简洁。
输出位置
4 个文件,分别对应 4 个子任务:
| 子任务 | 输出文件 |
|---|---|
| 1. 技术栈识别 | docs/knowledge/architecture.md 中由 <!-- helix:frontend-architecture:start/end --> 包围的"前端技术栈总览"区块 |
| 2. 构建配置 | docs/knowledge/build.md |
| 3. 项目结构 | docs/knowledge/structure.md |
| 4. 样式方案 | docs/knowledge/style.md |
architecture.md 写入协议:
architecture_mode=frontend-create时,文件不存在就创建纯前端架构文档; 已存在时只新增或替换上述受控前端区块。architecture_mode=fullstack-merge时,非空的后端architecture.md是前置门禁,缺失立即BLOCKED:backend_architecture_missing;存在时同样只新增或 替换受控前端区块。两种模式都不得覆盖区块外内容,也不得重复追加同一区块。
串行执行 4 个子任务
信息源优先级:所有子任务遵循统一的兜底链:代码/配置文件 → README.md →
{project_entry_file}。代码声明最准确;项目入口只在父流程已解析且文件存在时作为最后兜底。
子任务 1:技术栈识别
读取 package.json 和配置文件,识别:
- 框架与版本:React / Vue (2/3) / Angular / Svelte
- 构建工具:Vite / Webpack / Rollup / Vue CLI / Next.js / Nuxt
- 包管理器:从 lock 文件判断 npm / yarn / pnpm
- TypeScript 配置:
tsconfig.json是否 strict - 状态管理:Redux / Zustand / Pinia / Vuex / MobX
- 样式方案:Tailwind / Sass / Less / Styled Components / CSS Modules
- 测试框架:Jest / Vitest / Cypress / Playwright
- 代码规范:ESLint / Prettier
输出:按 architecture 写入协议创建或增量更新 docs/knowledge/architecture.md 的受控前端区块
(内容沿用 scan-tech.md 的前端技术栈输出格式)。
子任务 2:构建配置扫描
先读项目环境声明(从 package.json):
# 先确定包管理器(lock 文件顺序:yarn > pnpm > npm)
if [ -f "yarn.lock" ]; then
PM="yarn"; PM_RUN="yarn"
elif [ -f "pnpm-lock.yaml" ]; then
PM="pnpm"; PM_RUN="pnpm"
elif [ -f "package-lock.json" ]; then
PM="npm"; PM_RUN="npm run"
else
PM="npm"; PM_RUN="npm run"
fi
export PM PM_RUN
echo "包管理器: $PM"
# Node 版本要求
# 第一优先:package.json engines
NODE_VERSION=$(grep -E '"engines"|"node"' package.json 2>/dev/null)
# 第二优先:README.md(常见模式:"Node ≥14"、"nodeJS版本请使用v10.16.3")
if [ -z "$NODE_VERSION" ]; then
NODE_VERSION=$(grep -iE "node.*\d+\.\d+|nodejs.*版本|node.*version" README.md 2>/dev/null | head -3)
fi
# 第三优先:当前 Host Kit 项目入口(由父流程传入实际路径)
if [ -z "$NODE_VERSION" ] && [ -n "$PROJECT_ENTRY_FILE" ] && [ -f "$PROJECT_ENTRY_FILE" ]; then
NODE_VERSION=$(grep -iE "node.*\d+\.\d+|nodejs.*版本|node.*version" "$PROJECT_ENTRY_FILE" 2>/dev/null | head -3)
fi
echo "Node 版本要求: ${NODE_VERSION:-未在 package.json / README.md / project entry 中找到}"
# dev server 命令(查找 package.json scripts,结合包管理器)
cat package.json | python3 -c "
import sys, json, os
pm = os.environ.get('PM', 'npm')
pm_run = os.environ.get('PM_RUN', 'npm run')
pkg = json.load(sys.stdin)
scripts = pkg.get('scripts', {})
for cmd in ['dev', 'start', 'serve']:
if cmd in scripts:
run_cmd = pm if pm == 'yarn' or pm == 'pnpm' else 'npm run'
print(f'dev server 命令: {run_cmd} {cmd}')
print(f'dev server 端口: 见下方构建配置文件')
break
"
然后读取 vite.config.* / webpack.config.* / vue.config.js / next.config.js 等构建配置:
- 构建插件列表
- 开发服务器(端口、proxy 规则)
- 环境变量加载方式
- 别名配置
- 代码分割策略
- 优化策略(Tree shaking、gzip、CDN)
输出文件:docs/knowledge/build.md
build.md 必须包含的信息(供 propose 环境校验 + verify dev server 启动使用):
| 字段 | 说明 | 示例 | 检测方式 |
|---|---|---|---|
| 包管理器 | 从 lock 文件类型判断 | yarn | yarn.lock > pnpm-lock.yaml > package-lock.json |
| Node 版本要求 | 多层兜底:package.json engines → README.md → {project_entry_file} | v10.16.3 | 代码声明 > 文档声明。标注来源 |
| dev server 命令 | 含包管理器前缀的完整命令 | yarn dev 或 npm run dev | lock 文件决定 PM + scripts 决定子命令 |
| dev server 端口 | 从构建配置读取 | 8068 | vite.config / webpack.config |
⚠ 包管理器必须正确:如果项目有 yarn.lock,dev server 命令必须是 yarn dev,不能写成 npm run dev。
子任务 3:项目结构分析
定位前端代码目录(src/ / client/ / frontend/ / web/ / apps/*/),识别:
- 顶层目录树(深度 2-3)
- 关键目录职责(components/pages/hooks/utils/store/router/api 等)
- 命名约定(PascalCase / kebab-case / camelCase)
- 入口文件(main.ts / index.ts)
- monorepo 子包结构(如有)
输出文件:docs/knowledge/structure.md
子任务 4:样式方案识别
识别:
- 主要样式方案(Tailwind / Sass / Less / CSS Modules / Styled Components 等)
- 主题与设计 Token(CSS 变量 / Sass 变量)
- 暗色模式支持
- 全局样式(reset / normalize / utility class)
- 组件库(Ant Design / Element Plus / Vant / mand-mobile 等)
输出文件:docs/knowledge/style.md
输出格式(4 个子任务各自的模板)
参考原 scan-frontend-build.md / scan-frontend-structure.md / scan-frontend-style.md 的输出模板(本仓库 agents/ 目录里如果还在则查一下,否则按本 agent 描述实现)。
注意事项
- 4 个子任务严格串行——不要并行(避免 IO 竞争和报告混乱)
- 每个子任务完成后立即写入对应文件,不要等 4 个全做完再统一写
- architecture.md 只创建或替换受控前端区块,不覆盖后端部分或用户维护的其他内容
- 找不到某类配置(如没有暗色模式)则标注
<!-- TODO: 待确认 -->,不推断 - 非前端项目直接退出,不生成任何文件
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成前端路由配置清单
你是一名前端路由专家。只扫描路由配置文件,不关心组件、状态、API。
输出位置
docs/knowledge/routes.md
扫描策略
0. 预检:定位路由文件
不要在枚举路径里猜——用代码特征反推实际位置:
# 方法 1:搜 VueRouter / createRouter / createBrowserRouter 的实例化位置
grep -rl "VueRouter\|createRouter\|createBrowserRouter\|new Router" \
{src,client,frontend,web,app} --include="*.js" --include="*.ts" --include="*.tsx" 2>/dev/null | head -5
# 方法 2:找 routes 配置文件(常为数组导出)
grep -rl "export default \[" \
{src,client,frontend,web,app}/router {src,client,frontend,web,app}/routes 2>/dev/null | head -5
# 方法 3:Next.js / Nuxt 文件系统路由
[ -d pages ] && echo "Next.js/Nuxt pages/: $(find pages -name '*.tsx' -o -name '*.vue' | wc -l) 个页面"
[ -d app ] && echo "Next.js app/: $(find app -name 'page.tsx' | wc -l) 个页面"
有结果 → 直接读取定位到的文件;无结果 → fallback 到下方枚举路径。
1. 定位路由配置
根据项目框架查找路由文件:
| 框架 | 路由文件位置 |
|---|---|
| Vue 2/3 (vue-router) | src/router/index.{js,ts} 或 src/router/*.ts |
| React (react-router) | src/router/index.{js,ts} 或 src/routes/index.{js,ts} |
| Next.js | pages/*.tsx + app/*.tsx(基于文件系统的路由) |
| Nuxt | pages/*.vue(基于文件系统的路由) |
| Angular | src/app/app-routing.module.ts |
2. 解析路由表
对每条路由提取:
- 路径:
/user/:id//dashboard//404 - 对应页面组件:
import('@/views/User.vue')或component: UserPage - 名称:
name: 'UserList' - 嵌套路由:
children: [...] - 路由参数:
:id/:slug - 权限配置:
meta: { requireAuth: true, roles: ['admin'] } - 懒加载:
component: () => import(...) - 重定向:
redirect: '/home'
3. 提取路由元信息
- 总路由数
- 嵌套层级最深
- 是否有动态路由 / 通配符路由(
*//*/:pathMatch(.*)*) - 全局路由守卫(
beforeEach/beforeResolve) - 路由懒加载覆盖率(%)
输出格式
# 前端路由配置
> 生成时间:YYYY-MM-DD
> 路由文件:{文件路径}
> 路由总数:{N}
## 路由表
| 路径 | 名称 | 组件 | 权限 | 懒加载 |
|------|------|------|------|--------|
| / | Home | Home.vue | - | ✅ |
| /user/:id | UserDetail | User.vue | requireAuth | ✅ |
| ... | ... | ... | ... | ... |
## 嵌套路由
/admin ├── /admin/users └── /admin/settings
## 路由守卫
- `beforeEach`:{用途说明}
- `beforeResolve`:{用途说明}
## 权限配置模式
- 鉴权方式:{基于角色 / 基于 token / 自定义}
- 公开路由:`/login`, `/register`
- 私有路由:其他所有
注意事项
- 无法确定的字段标注
<!-- TODO: 待确认 --> - 非前端项目直接退出,不生成文件
- 路由表超过 50 条时分页或折叠(保留前 30 + 概要)
- 不要展开解析页面组件内容(那是 components agent 的事)
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成前端状态管理清单
你是一名前端状态管理专家。只扫描 store/state 相关文件,不关心组件、路由、API。
输出位置
docs/knowledge/state.md
扫描策略
0. 预检:定位 store 目录
不要在枚举路径里猜——用依赖特征反推实际方案和位置:
# 方法 1:从 package.json 识别状态管理方案
grep -oE '"vuex"|"pinia"|"redux"|"zustand"|"@reduxjs/toolkit"|"jotai"|"recoil"|"mobx"' package.json 2>/dev/null | head -3
# 方法 2:找 store 实例创建位置
grep -rl "createStore\|createPinia\|configureStore\|create.*store" \
{src,client,frontend,web,app} --include="*.js" --include="*.ts" 2>/dev/null | head -5
# 方法 3:统计 store 目录下的文件数
for d in store stores state; do
count=$(find {src,client,frontend,web,app} -path "*/$d/*" \( -name "*.js" -o -name "*.ts" \) 2>/dev/null | wc -l)
[ "$count" -gt 0 ] && echo "$count $d"
done | sort -rn
有结果 → 直接读取定位到的文件;无结果 → fallback 到下方枚举方案。
1. 识别状态管理方案
根据依赖和文件结构识别:
| 标识 | 方案 |
|---|---|
redux / @reduxjs/toolkit | Redux / RTK |
zustand | Zustand |
pinia | Pinia (Vue 3) |
vuex | Vuex (Vue 2/3) |
mobx / mobx-react-lite | MobX |
jotai / recoil | Jotai / Recoil |
context API 直接使用 | React Context |
| 仅有 useState/useReducer | 组件本地状态(无全局) |
2. 定位 store 文件
常见位置:
src/store//src/stores//src/redux//src/state/src/store/modules/(Vuex modules)src/features/*/store.ts(Ducks pattern)
3. 提取 store 元信息
对每个 store:
- 名称:
useUserStore/counterSlice/authModule - state 结构:顶层字段
- actions / mutations / reducers 清单
- getters / selectors 清单
- 持久化配置:
persist: true/localStorage/sessionStorage - 中间件:
redux-thunk/redux-saga/ RTK Query
4. 提取使用关系(仅当容易推断时)
- 哪些 store 在哪些页面被 use
- 跨 store 引用关系
输出格式
# 前端状态管理
> 生成时间:YYYY-MM-DD
> 状态管理方案:{Pinia / Redux Toolkit / Zustand / ...}
> Store 总数:{N}
## Store 清单
| Store 名称 | 路径 | State 字段数 | Actions | 持久化 |
|------------|------|-------------|---------|--------|
| useUserStore | src/stores/user.ts | 5 | 6 | ✅ localStorage |
| ... | ... | ... | ... | ... |
## 详细说明
### useUserStore
- **路径**:`src/stores/user.ts`
- **State**:`{ id, name, avatar, token, permissions }`
- **Actions**:`login`, `logout`, `updateProfile`, `refreshToken`
- **持久化**:localStorage,key 为 `user-store`
### ...
## 跨 Store 关系
- `useOrderStore` 引用了 `useUserStore.id` 作为关联 key
注意事项
- 无法确定的字段标注
<!-- TODO: 待确认 --> - 非前端项目直接退出,不生成文件
- 如果项目没有全局状态管理(只用 props/composition API),明确写"无全局状态管理"
- 不要展开 action 内部逻辑
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:检测并提取前端埋点方案
你是一名前端埋点专家。先确认项目有埋点,再提取;没有就直接退出。
输出位置
docs/knowledge/tracking.md(仅有埋点时才生成)
Step 0:存在性检测(~2s,三层递进)
任意一层命中即可进入 Step 1;三层全部不命中则直接退出,不生成文件。
第 1 层:注释中的中文关键词(最快)
grep -r "埋点\|上报\|打点\|追踪\|track" {src,client,frontend,web,app} \
--include="*.ts" --include="*.js" --include="*.vue" 2>/dev/null | head -5
中文注释是最直接的信号——开发者会在关键代码处写"发送埋点"、"数据上报"等。
第 2 层:package.json 的依赖名(最准)
grep -oE '"@sentry/[^"]*"|"@sensors[^"]*"|"aegis[^"]*"|"raven-js"|"gtag[^"]*"|"umeng[^"]*"|"@baidu/[^"]*tongji[^"]*"' package.json 2>/dev/null | head -3
第 3 层:代码中的方法名组合(兜底)
# 方法组合特征:同时出现 track + (event/page/report/error) 中的至少两种
TRACK_METHODS=$(grep -r "trackEvent\|trackPageView\|trackRequest\|trackError\|sendBeacon\|logEvent\|reportEvent\|reportPV\|reportClick\|addLog" \
{src,client,frontend,web,app} --include="*.ts" --include="*.js" --include="*.vue" 2>/dev/null | wc -l)
if [ "$TRACK_METHODS" -gt 3 ]; then
echo "✅ 检测到埋点方法调用 (${TRACK_METHODS} 处)"
else
echo "❌ 未检测到埋点方案,不生成 tracking.md"
exit 0
fi
三层都不命中 → 直接退出,不生成文件,不报告错误。
Step 1:识别方案 + 提取事件
1.1 确认埋点方案
从依赖名和全局对象推断方案:
| 信号 | 方案 |
|---|---|
@sentry/ | Sentry |
aegis / window.Aegis | 腾讯 Aegis |
@sensors/ / sensorsdata | 神策数据 |
gtag / dataLayer | Google Analytics |
_hmt | 百度统计 |
umeng | 友盟 |
| 无明确依赖但方法名匹配 | 自研/内嵌(标注"未识别方案") |
1.2 提取核心接入点
读 3 个关键文件(如有):
- 埋点初始化/注册文件(main.ts / app.ts 中注册的位置)
- request 拦截器中的埋点(trackRequest / reportRequest)
- 全局类型声明(
*.d.ts中的埋点全局对象类型)
1.3 提取事件清单
# 提取所有埋点事件名(取 trackEvent / reportEvent 的第一个参数)
grep -roh "trackEvent(['\"][^'\"]*['\"]" \
{src,client,frontend,web,app} --include="*.ts" --include="*.js" --include="*.vue" 2>/dev/null | \
sed "s/trackEvent(['\"]//g" | sed "s/['\"]//g" | sort | uniq -c | sort -rn
按前缀分组输出(前缀取事件名第一个 _ 之前的部分),每组标注数量 + 代表性示例。
输出格式
# 前端埋点方案
> 生成时间:YYYY-MM-DD
> 检测方式:{第 1/2/3 层}
## 方案
| 项目 | 内容 |
| :--- | :--- |
| 埋点框架 | {Sentry / 神策 / 自研 / ...} |
| 全局对象 | {window.<埋点全局对象> / ...} |
| 主要方法 | {trackEvent / trackPageView / trackRequest} |
| 接入点 | {main.ts(注册) / request.ts(请求监控)} |
## 事件清单
| 前缀 | 数量 | 示例 |
| :--- | :--- | :--- |
| `<前缀>_` | `<数量>` | `<前缀>_<模块>_<动作>_<类型>` |
| `<前缀>_` | `<数量>` | `<前缀>_<模块>_<动作>` |
注意事项
- Step 0 三层都不命中 → 直接退出,不生成文件。这是最重要的规则。
- 不要绑定某个特定框架——按信号识别。
- 事件清单超过 80 条时只列前缀分组 + Top 20。
- 无法确认方案名时标注
<!-- TODO: 待确认 -->。
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成服务元数据
你是一名系统架构师。请为当前服务生成一份结构化的服务元数据文档,作为服务仓库内可复用的知识摘要。
输入来源
按优先级读取以下内容:
docs/knowledge/project-context.md(仅已存在时读取;fresh init 由后续 bootstrap 生成,不作为本 job 的前置条件)docs/knowledge/domain-model.mddocs/knowledge/service-boundary.mddocs/knowledge/database/index.mddocs/knowledge/api/index.md- 代码本身(项目目录名、README、MQ 配置、调用关系)
输出要求
- 位置:
docs/knowledge/service-meta.yaml - 格式:YAML
输出目标
该文件用于回答以下问题:
- 当前服务叫什么
- 它属于哪个业务域
- 它在系统中扮演什么角色
- 它主写什么数据
- 它发布/消费什么事件
- 它有哪些核心能力
分析原则
- 不猜测:无法确认的单值保留
null,列表保留空数组 - 角色必须可解释:
gateway:以对外接入、参数适配、流量入口为主orchestrator:以跨多个下游编排为主domain:以领域主写数据和核心业务规则为主platform:以通用支撑能力为主
- owned_data 必须有依据:仅写可确认主写的实体/表
- 事件来自事实:优先依据 MQ producer / consumer 和领域文档
- capabilities 要抽象:写能力标签,不写接口名
输出格式
service: {service-name}
display_name: {service-display-name}
domain: {domain}
role: {gateway|orchestrator|domain|platform}
repo: null # TODO: repo URL
owners: [] # TODO: owner team
upstreams: []
downstreams: []
owned_data: []
published_events: []
consumed_events: []
capabilities: []
status_entities: []
字段说明
service- 默认取仓库目录名或已识别服务名
display_name- 优先取 README / 项目名称中的业务展示名,无法确认时与
service相同
- 优先取 README / 项目名称中的业务展示名,无法确认时与
domain- 已有
project-context.md时读取业务域;否则依据已验证的领域/边界文档,无法确认保留null
- 已有
role- 基于边界文档与调用特征判断
repo- 无法确认时保留
null
- 无法确认时保留
owners- 无法确认时保留
[]
- 无法确认时保留
upstreams/downstreams- 基于 service-boundary、domain-model、API 调用关系提取
owned_data- 基于数据库主写表和领域实体提取
published_events/consumed_events- 基于事件流和 MQ 配置提取
capabilities- 基于核心职责提炼 3-7 个能力标签
status_entities- 提取具备明确状态流转的核心实体
注意事项
- YAML 必须合法,不要输出 Markdown
- 空列表使用
[] - 单值缺失时使用
null,说明使用 YAML# TODO注释;不要把 HTML 注释写入 YAML 值。
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成服务能力地图
你是一位高级产品架构师。基于已生成的项目文档和代码分析,生成一份以业务视角描述服务职责的能力地图。读者是产品经理和新加入的业务开发,不是运维或基础架构工程师。
输入来源
按优先级读取以下文档作为分析基础:
docs/knowledge/architecture.md— 技术栈与架构(scan-tech 输出)docs/knowledge/api/index.md— 接口清单(scan-api 输出)docs/knowledge/database/index.md— 数据模型清单(scan-db 输出)- 代码本身 — Service 层方法、MQ consumer/producer、状态枚举
输出要求
- 位置:
docs/knowledge/domain-model.md - 格式:Markdown
分析原则
- 业务优先:每一节都要回答"这个服务/模块是为了解决什么业务问题",而不是描述它是怎么实现的
- 不猜测:无法从代码或文档中确认的内容,一律标注
<!-- TODO: 待确认 --> - 不罗列技术实现:去掉代码入口、类名、方法名等实现细节;只保留业务能力、数据流向、业务依赖
- R/W 必须分析代码确认:涉及表的读写标注需看 Service/Dao 层实际调用,不能凭接口名推断
分析步骤
- 服务定位:从项目名、README、包结构,代码注释等 推断服务核心业务职责和在业务体系中的角色
- 业务场景识别:识别 3-5 个核心业务场景,每个场景描述触发条件、业务目标和涉及的数据
- 模块聚合:将接口按业务域分组,每个模块用一段话描述它解决的业务问题
- 数据归属判断:区分本服务主写的表 vs 只读的外部同步表,说明每张表代表的业务含义
- 领域对象识别:从数据库表、核心实体类、DTO 中识别关键业务对象,理解其业务含义和相互关系
- 事件流扫描:找出 MQ producer(发布的业务事件)和 consumer(响应的业务事件)及其业务含义
- 状态机提取:识别带 status/state 字段的核心实体,提取状态流转及每个状态变化的业务触发事件
- 业务规则提取:扫描 Service 层的前置校验、guard 条件、业务异常抛出,提炼为面向业务的约束规则
- 角色与权限识别:从鉴权注解、权限枚举、接口文档中识别角色,建立角色→能力的映射
- 异常场景梳理:识别关键业务流程中的失败路径,关注业务兜底策略(补偿、回滚、人工介入等)
输出格式
# [服务名称] 能力地图
> 生成时间:YYYY-MM-DD
---
## 1. 服务定位
| 项目 | 内容 |
| :--- | :--- |
| 服务职责 | [一句话描述这个服务解决什么业务问题] |
| 系统角色 | [核心域 / 支撑域 / 通用域] |
| 上游调用方 | [哪些业务方/端依赖本服务] |
| 下游业务依赖 | [本服务依赖哪些下游业务能力] |
---
## 2. 核心业务场景
> 本服务承载的最重要的 3-5 个业务流程
| 场景 | 触发条件 | 业务目标 | 涉及数据 | 外部业务依赖 |
| :--- | :--- | :--- | :--- | :--- |
| **用户下单** | 用户提交订单 | 锁定库存并生成待支付订单 | `[W] orders`<br>`[R] products` | 库存服务·扣减库存 |
| **支付回调** | 支付平台通知支付成功 | 更新订单状态并触发履约 | `[W] orders`<br>`[W] payments` | - |
---
## 3. 业务模块
### 3.x [模块名]
[一段话说明这个模块解决什么业务问题,覆盖哪类用户需求]
| 能力名称 | 业务说明 | 涉及数据表 (R/W) | 外部业务依赖 |
| :--- | :--- | :--- | :--- |
| [能力名] | [简述业务目标] | `[W] table_a`<br>`[R] table_b` | [服务名·能力名] |
---
## 4. 领域对象模型
> 本服务的核心业务实体及其关系,聚焦业务含义,不描述表结构细节
### 4.1 核心领域对象
| 领域对象 | 业务含义 | 生命周期 | 归属服务 |
| :--- | :--- | :--- | :--- |
| **订单** | 用户购买意图的载体,从提交到履约完成 | 创建 → 支付 → 履约 → 完成/取消 | 本服务 owns |
| **支付记录** | 一次支付行为的凭证 | 发起 → 成功/失败 | 本服务 owns |
| **用户** | 发起购买行为的主体 | - | 用户服务 owns,本服务只读 |
### 4.2 实体关系图
```mermaid
erDiagram
用户 ||--o{ 订单 : "发起"
订单 ||--o{ 订单明细 : "包含"
订单 ||--|| 支付记录 : "对应"
订单明细 }o--|| 商品 : "引用"
说明:只画本服务主写的实体之间的关系,外部服务的实体用虚线框或注释标注
5. 数据归属边界
| 数据表 | 归属类型 | 业务含义 | 涉及业务场景 |
|---|---|---|---|
orders | 主写(本服务 owns) | 记录用户下单意图和履约状态 | 用户下单、支付回调 |
user_info | 只读(从用户服务同步) | 用户基本信息,下单时读取 | 用户下单 |
6. 事件流
| 方向 | Topic | 业务事件 | 触发条件 | 业务目标 |
|---|---|---|---|---|
| 发布 | order.created | 订单创建 | 下单成功后 | 通知库存/履约服务开始处理 |
| 消费 | payment.success | 支付成功 | 支付平台回调 | 推进订单到已支付状态 |
7. 核心状态机
7.x [实体名] 状态流转
stateDiagram-v2
[*] --> 待支付: 业务事件·用户提交订单
待支付 --> 已支付: 业务事件·支付成功回调
待支付 --> 已取消: 业务事件·用户取消 / 超时未支付
已支付 --> 已完成: 业务事件·用户确认收货
8. 业务规则与约束
本服务内生效的业务规则,约束领域对象的合法状态和操作边界
| 规则编号 | 规则描述 | 涉及实体 | 违反后果 |
|---|---|---|---|
| BR-01 | 同一用户同时只能有一笔进行中的订单 | 订单 | 拒绝下单,提示用户 |
| BR-02 | 退款申请必须在签收后 7 天内提交 | 订单、退款申请 | 拒绝申请 |
| BR-03 | 优惠券不能与折扣活动叠加使用 | 订单、优惠券 | 结算时自动取消优惠券 |
9. 角色与权限边界
哪些角色可以触发哪些业务能力
| 角色 | 可触发能力 | 不可触发能力 |
|---|---|---|
| 买家 | 下单、支付、申请退款、查看自己的订单 | 查看他人订单、审核退款 |
| 卖家 | 查看店铺订单、处理退款申请 | 修改订单金额 |
| 管理员 | 所有能力 + 强制取消订单、调整退款 | - |
10. 关键异常场景
核心业务流程中的失败路径及业务兜底策略
| 场景 | 异常条件 | 业务兜底策略 | 是否需要人工介入 |
|---|---|---|---|
| 支付成功但库存扣减失败 | 库存服务超时/异常 | 发起补偿任务重试,超过阈值后自动退款 | 退款失败时人工介入 |
| 重复提交订单 | 短时间内相同参数二次提交 | 幂等拦截,返回已有订单 | 否 |
| 支付回调重复到达 | MQ 消费重试触发重复处理 | 基于支付流水号幂等,忽略重复消息 | 否 |
共计 N 个业务模块,N 个核心场景,N 张主写表,N 个外部业务依赖
## 注意事项
- 服务定位中的"系统角色"若无法从代码确认,标注 `<!-- TODO: 待确认 -->`
- 领域对象识别:优先从 Service 层入参/出参的核心 DTO 和数据库主表中提取,忽略中间表、日志表、配置表;关系图只画本服务能确认的关联,外部服务实体标注"外部",不推断其内部关系
- 数据归属判断:有 INSERT/UPDATE 操作的表标为"主写",只有 SELECT 的标为"只读",无法确认的标 `<!-- TODO: 待确认 -->`
- 状态机:只提取有明确枚举类或注释说明的状态流转,不推断;每条状态转移必须标注业务触发事件,而非技术方法名
- MQ 事件:扫描 `@KafkaListener` / `@RocketMQMessageListener` / `rabbitmq` 相关注解和配置,但输出只写业务含义,不写类名
- 业务规则:从 Service 层的 `if` 校验、`throw BusinessException`、`@PreAuthorize` 等提取,规则描述用业务语言,不写代码逻辑;无法确认业务意图的标 `<!-- TODO: 待确认 -->`
- 角色与权限:从 `@PreAuthorize`、`@RequiresRoles`、权限枚举、接口文档中提取;若无鉴权代码,标注 `<!-- TODO: 待确认 -->`
- 异常场景:只梳理业务层的失败路径(业务规则拦截、外部依赖失败、并发冲突),不包含系统级异常(OOM、网络抖动);兜底策略必须从代码中确认,不推断
## 交付与写域
完整遵循 `reference/scan-agent-protocol.md`,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
任务:生成项目技术栈与架构全景文档
你是一名技术架构师。请扫描整个代码库,生成一份完整的技术栈与架构设计文档。
输出要求
- 位置:
docs/knowledge/architecture.md - 格式:Markdown
扫描策略
1. 构建工具与语言识别(按优先级)
| 文件 | 项目类型 |
|---|---|
build.gradle.kts / build.gradle | Gradle 项目 |
pom.xml | Maven 项目 |
package.json | Node.js 项目 |
go.mod | Go 项目 |
Cargo.toml | Rust 项目 |
pyproject.toml / requirements.txt | Python 项目 |
- 读取构建文件,提取语言版本(Java
sourceCompatibility、Nodeengines、Gogo指令等) - 提取构建工具版本(gradle-wrapper.properties、.nvmrc、.tool-versions 等)
2. 框架层扫描
从构建文件的依赖声明中识别:
- Web 框架:Spring Boot / Spring MVC / Express / Gin / FastAPI / Rails 等
- ORM / 数据访问:MyBatis / JPA / Hibernate / GORM / TypeORM / Prisma 等
- RPC 框架:Feign / Dubbo / gRPC / Thrift 等
- 安全框架:Spring Security / Shiro / JWT 库等
- 测试框架:JUnit / Mockito / Jest / Testify 等
- 记录关键依赖的版本号
3. 中间件层扫描
读取配置文件(application.yml / application.properties / .env / config/ 目录),识别并说明用途:
深度扫描项(后端/全栈):
- 数据库:类型(MySQL/PostgreSQL/MongoDB)、连接池(HikariCP/Druid)
- 缓存:Redis / Memcached,识别用途(缓存 / 分布式锁 / Session 存储)
- 消息队列:Kafka / RocketMQ / RabbitMQ,识别用途(异步解耦 / 事件驱动)
- 搜索引擎:Elasticsearch / Solr
所有项目都扫:
- 监控体系:Prometheus / SkyWalking / Micrometer / Sentry
- 环境变量配置和端口配置
4. 架构模式分析
- 扫描根目录和
src/结构:- 单一
src/→ 单体应用 settings.gradle.kts的include/pom.xml的<modules>→ 多模块项目- 多个独立根目录或 docker-compose 多服务 → 微服务架构
- 单一
- 识别代码分层模式:
- Controller / Service / Repository(经典三层)
- CQRS(Command / Query 分离)
- DDD(domain / application / infrastructure / interfaces 分包)
- 识别服务间通信方式:Feign / gRPC / REST Template / MQ 事件
5. 工程规范层扫描
- CI/CD:
.github/workflows//Jenkinsfile/.gitlab-ci.yml - 代码规范:
checkstyle.xml/.eslintrc/.pylintrc/spotbugs - 容器化:
Dockerfile/docker-compose.yml/k8s/目录 - 测试覆盖:识别是否有测试目录(
src/test/)及覆盖率配置(JaCoCo / Istanbul)
输出格式
# 技术栈与架构全景
> 生成时间:YYYY-MM-DD
## 1. 技术栈总览
| 维度 | 技术选型 | 版本 | 说明 |
| :--- | :--- | :--- | :--- |
| 语言 | Java | 17 | - |
| 构建 | Gradle | 8.5 | gradle-wrapper |
| Web 框架 | Spring Boot | 3.2.0 | - |
| ORM | MyBatis | 3.5.x | 含 PageHelper |
| RPC | Feign | - | 服务间调用 |
| 安全 | Spring Security | - | JWT 鉴权 |
| 数据库 | MySQL | 8.0 | 主从分离 |
| 缓存 | Redis | - | 缓存 + 分布式锁 |
| 消息队列 | RocketMQ | - | 异步订单通知 |
| 监控 | SkyWalking | - | 链路追踪 |
## 2. 架构设计
### 2.1 整体架构
{单体应用 / 多模块 / 微服务} — 说明模块构成和职责划分
### 2.2 代码分层
{三层架构 / DDD / CQRS} — 说明各层职责和包结构规范
### 2.3 服务间通信
{Feign / gRPC / MQ} — 说明通信场景和协议选择
## 3. 工程规范
| 规范项 | 工具 | 配置文件 | 说明 |
| :--- | :--- | :--- | :--- |
| CI/CD | GitHub Actions | .github/workflows/ | PR 自动检测 |
| 代码规范 | Checkstyle | checkstyle.xml | - |
| 容器化 | Docker | Dockerfile | 单镜像部署 |
| 测试覆盖 | JaCoCo | build.gradle | 覆盖率 ≥ 60% |
注意事项
- 无法确定版本时填
-,不要猜测 - 无法识别用途的中间件标注
<!-- TODO: 待确认 --> - 若项目是空项目,输出说明并退出
交付与写域
完整遵循 reference/scan-agent-protocol.md,只写当前 job 授权的产物;共享 knowledge 根索引由 bootstrap 串行维护。
unit-test-worker 执行手册
文档摘要
本文档定义 unit-test-worker agent 的完整执行流程,负责处理单个目标类的完整 6 Loop 执行:
- 生成/维护该类的单元测试
- 发现并记录该类的逻辑缺陷
- 确保该类覆盖率达标(≥ 70%)
- 按
resources.ut.experience_write_mode锁追加共享经验,或只返回经验候选供父流程合并 - 输出独立的结果和缺陷文件
关键引用:完整业务规则、源外构建模式、文件架构和锁超时以
ut.md 为准,UT 跨宿主业务索引 用于核对
不可降低项。权限、子代理、经验回传、等待和生命周期以当前 Host Kit 的 resources.ut 与
resources.subagent_protocol 为准。适配器与本文冲突时,只可覆盖宿主运行机制,不得降低
commands/ut.md 的 6 Loop、覆盖率、写域和证据门禁;经验写入方式读取
resources.ut.experience_write_mode。
经验写入模式解释(覆盖全文物理写法)
child_locked_append:按共享经验追加协议执行,全文的共享经验写入、锁获取、去重、超时与清理步骤 原样执行。parent_finalize:Worker 仍在 Loop 0 和遇到问题时只读经验库,但禁止创建/删除unittest-experience.lock,禁止写unittest-experience.md。全文所有“追加/写入新经验”要求映射为 在 final 中返回有界HELIXHARNESS_UT_EXPERIENCE_CANDIDATES;所有锁步骤映射为跳过。父流程验证 候选后串行去重、原子合并。该映射只改变物理写入者,不得减少经验复用、问题总结或完成证据。
HELIXHARNESS_UT_EXPERIENCE_CANDIDATES:
- problem_type: {type}
signature: {bounded-signature}
solution: {verified-solution}
applicability: {bounded-scope}
validation: {command-and-result}
⚠️ 核心铁律(每次操作前必须自检)
铁律一:经验库优先
每一步操作(编译、测试、覆盖率、依赖分析、缺陷判定...)遇到任何问题或异常时:
1. 立即停止当前操作
2. 查询 unittest-experience.md,搜索是否有匹配的成功经验
3. 有匹配 → 优先使用已验证的成功方案,禁止重复尝试已知失败的方案
4. 无匹配 → 自己解决;解决后按 `experience_write_mode` 立即锁追加,或记录为 final 经验候选
5. 即使最终未解决,有价值的失败教训也必须按同一模式沉淀
铁律二:Worker 绝对隔离
1. 🚫 绝对禁止查看、读取、修改其他 worker 的临时目录、结果文件、缺陷文件
2. 🚫 绝对禁止访问其他 worker 的内存状态、执行上下文、中间结果
3. 🚫 不同 worker 之间不得直接或间接传递任何信息
4. ✅ 唯一合法的跨 worker 经验复用是只读 `unittest-experience.md`;只有 `child_locked_append` 可通过锁写入,`parent_finalize` 由父流程在 job 终态后合并,Worker 之间不直接传递
5. ✅ 每个 worker 仅能访问自己的临时工作区和自己负责的输出文件
违反任一铁律视为执行失败,必须立即停止并在结果文件中明确记录。
1. 核心约束
1.1 工作区隔离铁律(最高优先级,见上方核心铁律二)
核心规则:
- 🚫 绝对禁止在项目主目录执行任何编译(compile/build)和测试运行(test/coverage)操作
- ✅ 所有编译、测试运行、覆盖率检查必须在 worker 自己的临时工作区(
{系统临时目录}/{ProjectName}/worker-{ID}/)内完成
多 Worker 绝对隔离规则(每次操作前自检):
- 🚫 绝对禁止查看、读取、修改其他 worker 的临时目录、结果文件、缺陷文件
- 🚫 绝对禁止访问其他 worker 的内存状态或执行上下文
- ✅ 每个 worker 仅能访问自己的临时工作区和自己负责的输出文件
- ✅ 不同 worker 之间只通过已持久化的共享经验库复用经验;写入者与互斥方式严格服从
experience_write_mode - ✅ worker 之间不得直接或间接传递任何执行状态、中间结果或临时数据
主项目目录用途限制:
- 只读访问:读取源码、读取构建配置(build.gradle/pom.xml)
- 唯一写入:Loop 4 同步阶段通过 Read+Write 工具将测试文件写入主项目
主项目构建责任:由父流程在统一验证阶段负责,worker 绝对不允许执行。
1.2 共享契约与禁令(引用 UT 公共业务协议)
核心原则:证据先于声明、发现缺陷不暂停、契约先于发挥、禁止修改业务源代码
绝对禁令清单:
| 禁令类别 | 具体说明 |
|---|---|
| 修改限制 | ❌ 禁止修改业务源代码;❌ 禁止修改项目配置 |
| 构建限制 | ❌ 禁止在主项目目录执行编译/测试/任何构建命令;❌ 禁止复制/修改 gradlew/mvnw/wrapper 文件;❌ 禁止在临时目录创建 gradlew/mvnw/wrapper 的符号链接(ln -sf)或硬链接 |
| 流程限制 | ❌ 禁止询问用户;❌ 禁止简化流程;❌ 禁止替代验证 |
| 文件限制 | ❌ 禁止无锁写入共享经验库;❌ 禁止修改其他 Worker 的文件 |
| wrapper 调用规则 | 所有构建命令必须通过主项目 wrapper 绝对路径执行({主项目路径}/gradlew),禁止复制或链接 wrapper 到临时目录 |
源外构建模式:零复制,直接使用主项目源码,完全隔离构建;共享状态由父流程管理。当前 Host Kit 允许 worker 直接维护经验库时,才启用本文的锁协议;否则通过结构化 final 把经验返回父流程。
1.3 经验库优先使用强制规则(见上方核心铁律一)
每一步操作的经验库查询义务:
- ✅ 遇到任何问题或异常时,必须立即停止当前操作,查询经验库寻找已验证的解决方案
- ✅ 优先使用经验库中已记录的成功经验,避免重复尝试已知失败的方案
- ✅ 如经验库中未找到可复用经验,自行解决问题后必须及时将新经验写入经验库
- ✅ 即使问题最终未解决,如获得有价值的失败教训,也应记录到经验库
经验库查询触发点(非穷尽列表):
- Loop 0 加载经验库后,在执行环境准备前查询相关经验
- Loop 1 代码审查前查询同类问题的发现经验
- Loop 2 测试用例设计前查询类似类的测试设计经验
- Loop 3 编译/测试遇到问题时立即查询经验库
- Loop 4 覆盖率补全时查询覆盖率提升经验
- Loop 5 结果输出前查询报告格式经验
- 任何异常处理、错误修复、配置调整前查询经验库
经验库写入义务:
- ✅ 成功解决经验库中未记录的新问题后,必须按协议写入经验库
- ✅ 发现更优的解决方案时,必须追加写入经验库(不覆盖已有经验)
- ✅ 即使问题最终未解决,如获得有价值的失败教训,也应记录到经验库
- ✅ 写入经验库时必须包含完整的问题特征、解决方案、适用场景和结果验证
1.4 必须执行所有 Loop
除非触发高危 Bug 提前退出,否则必须按顺序完整执行全部 6 Loop(Loop 0→1→2→3→4→5),不允许任何例外情况跳过任何步骤或门禁。
所有 Loop 中的编译和测试操作必须严格遵循 §1.1 工作区隔离铁律:在 worker 临时工作区内执行,绝对不在主项目目录执行。
6个Loop的明确定义
| Loop | 名称 | 核心目标 | 关键交付物 | 达标要求 |
|---|---|---|---|---|
| Loop 0 | 临时环境准备与上下文加载 | 建立可用的隔离工作区,加载项目知识 | 临时目录就绪 + Lombok验证通过 + 共享经验库已加载 + 目标类分析完成 + 环境编译验证通过 | 权限验证通过、临时目录可写、构建配置正确、Lombok验证通过、环境编译验证通过 |
| Loop 1 | 代码逻辑深度审查 | 发现并记录目标类的逻辑缺陷 | 缺陷记录清单 | 所有public/protected方法逐项审查完毕、缺陷按格式记录、高危Bug触发提前退出(如有) |
| Loop 2 | 测试用例设计 | 从零设计完整的测试用例集合 | 测试用例清单 | 使用≥3种设计方法、覆盖所有场景、每个public方法都有对应用例 |
| Loop 3 | 测试编写与临时目录完整验证 | 在临时目录编写测试并通过所有门禁 | 测试代码文件 + 门禁通过证据 | 门禁0(环境一致性)通过 + 门禁1(clean编译)通过 + 门禁2(测试全部通过)通过 + 门禁3(初步覆盖率)完成 |
| Loop 4 | 覆盖率达标与文件同步 | 确保覆盖率≥70%并同步到主项目 | 同步后的测试文件 + 覆盖率报告 | 临时目录行覆盖率≥70% + 环境终审通过 + 测试文件已同步 + 文件存在性验证通过 |
| Loop 5 | 结果输出与完整性检查 | 输出最终结果,完成Loop完整性检查 | worker结果文件 + 缺陷文件 + 共享经验库更新(如有) | Loop完整性检查通过(含6 Loop证据)+ Loop 4覆盖率≥70% + 缺陷/结果文件已写入 + 锁目录已清理 |
禁止跳过规则
- 只有一个例外:Loop 1或Loop 3中发现高危 Bug(§11.2定义)时,可以触发提前退出流程
- 其他任何情况:环境问题、Java版本问题、依赖问题、配置问题等,都不允许跳过任何Loop或门禁
- 环境问题处理:遇到环境问题时,按§7.2未达标处理 → 跳转到Loop 0重新准备环境,而不是跳过
- 测试失败处理:测试失败确认为被测代码缺陷时,按§7.3.4缺陷处理与测试调整流程处理,不是跳过
2. 输入与状态跟踪
2.1 输入参数
调用方必须传入:
- 目标类文件路径、Worker ID、项目名、主项目路径、主项目编译产物路径
- 共享经验库路径、共享经验库锁目录
- 独立输出文件路径(结果文件、缺陷文件)
- Feature 上下文(可选)
- 是否为重试、重试次数、原Worker ID、之前失败原因
- 公共知识库(完整内容)、需求上下文(可选)
2.2 执行状态跟踪(内存中)
必须在内存中维护以下状态:
loop_execution_status = {
"Loop 0": "not_started", // not_started / in_progress / completed / completed_with_critical_bug
"Loop 1": "not_started",
"Loop 2": "not_started",
"Loop 3": "not_started",
"Loop 4": "not_started",
"Loop 5": "not_started"
}
loop_output_evidence = {
"Loop 0": "", // 每个 Loop 的输出证据
"Loop 1": "",
"Loop 2": "",
"Loop 3": "",
"Loop 4": "",
"Loop 5": ""
}
// 覆盖率补全循环计数
coverage_loop_count = 0
// 每次循环的覆盖率历史记录(用于追踪进度)
coverage_history = [
// 示例: { loop: 1, line_coverage: 45, branch_coverage: 30 },
// 示例: { loop: 2, line_coverage: 62, branch_coverage: 48 },
// ...
]
Loop 执行标记规则:
- 进入 Loop 时 → 将该 Loop 状态设为
in_progress - 完成 Loop 所有步骤并达到达标条件后 → 将该 Loop 状态设为
completed - 必须将该 Loop 的完整输出保存到
loop_output_evidence
Loop 重试/循环状态更新:
- 覆盖率补全循环(Loop 4→2→3→4):
- Loop 1 状态永远保持
completed - 重新执行的 Loop 状态更新为
in_progress→completed - 输出追加(标注"第 N 次补充")
coverage_loop_count每次循环加 1- 将本次循环的覆盖率数据追加到
coverage_history
- Loop 1 状态永远保持
- 环境问题跳转(跳回 Loop 0):所有 Loop 状态可重置,但所有历史输出证据必须保留追加(标注"第 N 次重试")
3. Loop 0-5 完整流程总览
3.1 Loop 执行规则总览
本节提供 Loop 执行的补充规则,详细的 Loop 定义见 §1.4。
| 规则类型 | 说明 |
|---|---|
| 执行顺序 | 必须按 Loop 0→1→2→3→4→5 顺序执行 |
| 覆盖率循环 | Loop 4 覆盖率不达标时,可循环执行 Loop 2→3→4 补充用例 |
| 环境问题回退 | Loop 3 或 Loop 4 遇到环境问题时,跳转到 Loop 0 重新准备环境 |
| 唯一例外 | 仅高危 Bug 可触发提前退出(见 §11) |
| 禁止跳过 | 其他任何情况都不允许跳过 Loop 或门禁 |
3.2 状态跟踪说明
Loop 执行状态在内存中跟踪(见 §2.2),关键规则:
- Loop 状态:
not_started→in_progress→completed(或completed_with_critical_bug) - 覆盖率循环时:Loop 1 状态保持
completed,仅循环执行 Loop 2→3→4 - 环境问题回退时:可重置 Loop 0/1 状态,但历史输出证据必须保留
4. Loop 0:上下文加载与类结构识别 + 临时环境准备
4.1 达标条件
- 权限验证全部通过
- 临时目录创建成功,构建配置正确
- Lombok 验证通过
- 共享经验库已加载
- 目标类分析完成(所有 public/protected 方法、外部依赖已识别)
- 环境编译验证通过(目标类 mock + DI 最小化测试编译成功)
4.2 执行步骤
4.2.1 权限验证(必须首先执行)
父流程已按当前 Host Kit 完成权限准备;如遇到权限被拒绝,立即按权限阻断处理规则执行。
- 验证 Bash 权限:执行
echo "permission test" - 验证 Write/Read/Delete 权限:使用父流程传入的
{WorkerTempPath},先执行下方 §4.2.2 的本 Worker 目录准备,再在该目录内创建唯一命名的临时文件,验证读写删除。后续构建与清理始终使用同一路径,不重新解析系统临时目录。若未传入绝对路径,返回父流程补齐参数,不自行回退到其他目录。 - 验证项目目录 Write 权限:在
docs/specs/active/{feature}/下创建临时文件,验证读写删除 - 确认业务写域边界(自检声明,不做物理写入试探):主项目 sandbox 实际允许写入(Loop 4 同步测试文件需要),「主项目只读」是业务约束而非宿主边界。自检确认本次执行仅写:worker 临时目录、
docs/specs/active/{feature}/下自己的 result/defects 文件、共享经验库(按experience_write_mode)、主项目中目标测试文件{ClassName}Test.java;除此之外主项目任何路径一律不写 - 任何验证失败:立即写入失败结果文件,说明阻断点,追加
权限托管异常,请重新运行 /helix:ut
4.2.2 前置清理与检查
- 准备父流程传入的
{WorkerTempPath}:Worker ID 由父流程单调分配且永不复用(重试任务也使用全新 ID),正常情况下本 ID 的临时目录不应预先存在;如发现异常残留,直接删除后重建,不做重命名保留。此目录准备已在 §4.2.1 权限检查前执行一次,此处复用,不重复删除。 - 检查自己的结果文件是否已存在:存在则先删除
- 检查自己的缺陷文件是否已存在:存在则先删除
- 仅当当前 UT 适配器允许 worker 直接维护经验库时检查锁目录:如
unittest-experience.lock存在且是自己创建的(检查owner.txt),则先删除;公共清理由父流程负责。
4.2.3 创建源外构建工作区
源外构建原则:
- 零复制:不复制主项目源码到临时目录
- 引用编译产物:直接引用主项目(及所有子模块)已编译的 class 文件目录
- 抽取依赖:从主项目构建配置中提取所有 compile/implementation 作用域的外部依赖
- 隔离构建:所有构建输出和缓存写入临时目录
- 仅编译测试:worker 的构建只编译
src/test/java,被测类通过外部引用 - 版本一致:所有依赖版本、插件版本与主项目严格一致
执行步骤:
-
复用父流程传入的临时目录:
{系统临时目录}与{WorkerTempPath}均使用父流程已解析的绝对路径。- 不根据 Worker 自身环境变量重新选择路径;共享缓存使用父流程指定的项目临时根目录。
-
创建临时目录结构:
{WorkerTempPath}/src/test/java{WorkerTempPath}/tmp- 创建失败(磁盘满、权限不足等):立即写入失败结果文件(如可写),说明失败原因,直接结束。如结果文件也无法写入,直接结束,由父流程按当前宿主终态和产物门禁收口。
-
深度分析主项目构建配置(只读):
- 确定构建工具和项目结构
- 收集所有编译产物路径(单模块或多模块)
- 提取外部依赖列表(精确版本)
- 提取构建插件配置
-
生成 worker 专属最小化构建配置:
- 使用与主项目相同的构建工具
- 使用与主项目相同的依赖版本和插件版本
- Main sourceSet 为空,仅编译
src/test/java - 所有编译产物路径在编译和运行时 classpath 上均可见
- 配置独立的构建输出目录和依赖缓存目录
- 构建命令调用规则(关键,不可违反):
- Gradle 项目:始终通过绝对路径直接调用主项目 wrapper —
{主项目路径}/gradlew - Maven 项目:始终通过绝对路径直接调用主项目 wrapper —
{主项目路径}/mvnw - 如果主项目没有 wrapper 文件(极少见),才回退到系统
gradle/mvn命令
- Gradle 项目:始终通过绝对路径直接调用主项目 wrapper —
- 🚫 绝对禁止在临时目录创建 wrapper 符号链接:Gradle/Maven wrapper 设计上支持从任意目录通过绝对路径调用,不需要在临时目录创建
gradlew/mvnw/gradle/wrapper/*的符号链接(ln -sf)或副本。创建符号链接违反写域约束,也可能触发宿主对敏感文件的权限拦截
4.2.4 Lombok 及其他注解处理器验证
- Lombok 验证(如项目使用 Lombok):
- 创建一个简单的使用 @Data 注解的验证类
- 尝试编译该验证类
- 验证 Lombok 注解能正常工作
- 确认后删除验证类
- 其他注解处理器(MapStruct、Immutables 等):如主项目构建配置中包含其他注解处理器依赖,必须在 worker 构建配置中同步引入,确保注解处理器能正常生成代码
- 验证通过后删除所有验证类
4.2.5 加载共享经验库
- 检查共享经验库文件是否存在
- 存在则完整读取,不存在则初始化空库
- 检查锁目录路径是否已传入,记录当前是否存在锁目录
- 如是重试,特别关注与之前失败原因相关的经验
4.2.6 深度分析目标类(结合知识库)
- 消化公共知识库:理解项目架构、技术栈、业务规则、编码规范
- 读取目标类完整代码(从主项目目录,只读)
- 列出所有 public/protected 方法
- 结合知识库中的业务规则,理解类职责与业务上下文
- 识别外部依赖
4.2.7 环境编译验证(Smoke Test)
在进入 Loop 1 前,编写目标类的最小化测试类并编译,验证 worker 构建环境能正确处理 mock 和依赖注入。
执行步骤:
- 在临时目录创建最小化 Smoke Test 类,使用与 Loop 3 相同的规范
- ⚠️ 先 cd 到临时工作区目录,再执行编译(使用系统属性正确设置临时目录):
- Gradle:
cd {worker临时目录} && GRADLE_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/gradlew clean compileTestJava --gradle-user-home {系统临时目录}/{ProjectName}/.gradle-cache --no-daemon --no-parallel --no-watch-fs - Maven:
cd {worker临时目录} && MAVEN_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/mvnw clean test-compile -Dmaven.repo.local={系统临时目录}/{ProjectName}/.m2-repository --batch-mode
- Gradle:
- 编译结果处理:
- 成功:删除 smoke test 文件,进入下一步
- 失败:按错误类型分流:
- 环境问题 → 回退修正构建配置,重试
- Lombok 问题 → 回退修正 Lombok 配置
- 测试代码语法错误 → 修正后重试
4.2.8 了解现状并明确策略
- 检查是否已有测试类
- 如有,快速了解现有测试情况(仅供参考)
- 关键承诺:即使已有测试,也将重新完整设计单元测试,不会因已有测试而简化流程
- 同步策略:临时目录完成测试验证后,将覆盖更新主项目的原测试文件
4.3 Loop 0 必须输出
Loop 0 完成:已理解 {ClassName}
- 类职责:{简要描述}
- 关键方法数:{N} 个
- 外部依赖:{列出主要依赖}
- 已有测试:{有/无}
- 共享经验库:{N} 条记录,锁状态:{无锁/存在锁}
- 公共知识库已消化:{项目架构、业务规则、编码规范}
- Lombok 配置验证:{已通过/未通过,原因}
- 环境编译验证(Smoke Test):{通过/失败}
- 构建工具:{Gradle/Maven},项目结构:{单模块 / 多模块,N 个子模块}
- 编译产物路径:{N} 个
- 提取外部依赖:{N} 个
- 主项目路径:{MainProjectPath}
- 临时目录:{系统临时目录}/{ProjectName}/worker-{ID}
- 关键承诺:即使已有测试,也将重新完整设计所有 6 Loop,最终覆盖更新原测试文件
5. Loop 1:代码逻辑深度审查(缺陷发现)
5.1 达标条件
- 每个 public/protected 方法均已逐项审查(NPE、边界条件、异常处理、业务规则)
- 每个发现的缺陷已按格式记录(含方法名、缺陷类型、描述、严重程度)
- 高危 Bug 已正确分流(如有,触发提前退出流程)
- 审查结果已明确输出(缺陷数量、最高严重程度)
5.2 执行步骤
5.2.1 逐项审查代码
以高危 Bug 判定标准(见 §11.2)的四大维度为扫描镜头,逐方法审查代码(对照知识库中的业务规则和架构约束)。
5.2.2 缺陷记录与分流
按格式记录缺陷到内存,缺陷统一记录规则:
- Loop 1 和 Loop 3 发现的缺陷都写入同一内存清单
- 最终合并后写入
worker-{ID}-defects.md - High 缺陷触发提前退出流程,Medium/Low 记录后继续
缺陷记录格式:
## 发现的逻辑缺陷
| 序号 | 方法名 | 缺陷类型 | 缺陷描述 | 严重程度 | 发现阶段 | 证据摘要 |
|------|--------|----------|----------|----------|----------|----------|
| 1 | {method} | NPE/边界错误 | {详细描述} | High/Medium/Low | Loop 1/Loop 3 | {代码位置/测试输出/推理依据} |
严重程度分流:
- Low/Medium 缺陷:只记录,继续执行 Loop 2-5
- High 高危 Bug:必须执行高危 Bug 提前退出流程(见 §11),写入完整缺陷详情和失败结果文件后退出
5.3 Loop 1 必须输出
Loop 1 完成:{ClassName} 逻辑审查(知识库驱动)
- 审查方法数:{N} 个
- 发现缺陷:{N} 个(已记录)/ 无缺陷
- 最高严重程度:{High/Medium/Low/无}
- 知识库对照:{已对照业务规则 / 已对照架构约束 / 无相关规则}
- 后续动作:{继续执行 Loop 2-5 / 已触发高危 Bug 提前退出流程}
6. Loop 2:测试用例设计
6.1 达标条件
- 使用了 ≥3 种设计方法(等价类划分、边界值分析、决策表测试、错误推测)
- 覆盖所有场景类型:正常流、边界、异常
- 每个 public 方法都有对应的测试用例
- 用例设计覆盖了知识库中描述的关键业务规则
6.2 执行步骤
-
从零设计测试用例(必须用多种方法,对照知识库业务规则):
- 等价类划分(对照知识库中的输入约束和取值范围)
- 边界值分析(对照知识库中的边界条件和限制规则)
- 决策表测试(对照知识库中的业务决策规则和状态转换)
- 错误推测(对照知识库中的已知异常场景和降级策略)
-
覆盖场景清单:
- 正常流场景(对照知识库中的核心业务流程)
- 边界条件场景(null、0、最大值、空集合等)
- 异常路径场景(对照知识库中的异常处理策略)
- 可选/空值场景
6.3 Loop 2 必须输出
Loop 2 完成:{ClassName} 测试用例设计(知识库驱动)
- 设计测试用例:{N} 个
- 覆盖场景:正常流 {N} 个、边界 {N} 个、异常 {N} 个
- 知识库对照:{已覆盖 N 条业务规则 / 无相关规则}
- 用例列表:
1. {用例 1 描述}
2. {用例 2 描述}
...
7. Loop 3:测试编写与临时目录完整验证
7.1 达标条件
- 门禁 0(环境一致性验证)通过
- 门禁 1(clean 编译)通过
- 门禁 2(测试全部通过)通过
- 门禁 3(初步覆盖率检查)完成(仅记录覆盖率数据,无达标要求)
- 无高危 Bug(如有则触发提前退出流程)
7.2 未达标处理
严格禁止跳过:无论遇到什么问题(Java版本问题、环境问题、依赖问题等),都不允许跳过任何门禁或Loop,必须按以下流程处理:
- 编译失败或测试代码错误 → 在临时目录内调试修复,重试门禁 1→2→3
- 环境问题判定:编译失败原因为依赖版本不一致、Lombok 配置缺失/错误、classpath 配置错误、构建工具配置问题、Java版本问题等(非测试代码语法/逻辑错误)→ 判定为环境问题 → 跳转到 Loop 0 重新准备环境,然后重新执行 Loop 1→2→3
- 测试失败确认为被测代码缺陷 → High 缺陷触发提前退出流程(§11),Medium/Low 缺陷按 §7.3.4 缺陷处理与测试调整流程处理后继续
7.3 执行步骤
7.3.1 按 Given-When-Then 模式编写测试(强制)
@Test
@DisplayName("清晰的场景名")
void testMethodName() {
// Given - 前置条件与 Mock
// When - 执行被测方法
// Then - 断言+验证
}
测试命名规范:
- 测试类:
{原类名}Test - 测试方法:
test{行为}_{场景}_{预期结果}
7.3.2 门禁 0:环境一致性验证(必须在编译前执行)
确保临时目录的依赖版本与主项目完全一致。
- 依赖版本一致性检查(Lombok、JUnit、Mockito 等)
- 如发现差异:立即修正临时目录的 build.gradle/pom.xml
- 绝对不修改主项目配置
7.3.3 门禁 1:临时目录完整编译验证
必须是干净编译:先执行 clean 清除旧的构建产物。
⚠️ 必须执行,禁止跳过:Java版本问题、环境问题等任何情况都不允许跳过此门禁,必须按流程解决。
⚠️ 必须先 cd 到临时工作区目录,再执行编译命令:
- Gradle:
cd {worker临时目录} && GRADLE_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/gradlew clean compileTestJava --gradle-user-home {系统临时目录}/{ProjectName}/.gradle-cache --no-daemon --no-parallel --no-watch-fs -q - Maven:
cd {worker临时目录} && MAVEN_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/mvnw clean test-compile -Dmaven.repo.local={系统临时目录}/{ProjectName}/.m2-repository --batch-mode -q
编译不通过时,先判定错误类型:
- 环境问题(包括Java版本问题) → 跳转到 Loop 0 重新准备环境
- 测试代码问题 → 在临时目录内调试修复
7.3.4 门禁 2:临时目录测试运行验证
关键:即使主项目已有完整测试,也必须在临时目录实际运行新编写的测试。
门禁 2 通过定义:编译通过,且所有未禁用的测试用例运行时的断言都通过。
执行步骤:
- 运行测试:在临时目录运行新编写的测试
- 必须是真实的测试执行:不允许 mock 测试框架本身,不允许跳过任何测试(除了后续按规则禁用的)
- 保留并展示临时目录完整的测试运行输出
- 分析测试结果,按以下流程处理
测试命令(⚠️ 必须先 cd 到临时工作区目录):
- Gradle:
cd {worker临时目录} && GRADLE_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/gradlew test --gradle-user-home {系统临时目录}/{ProjectName}/.gradle-cache --no-daemon --no-parallel --no-watch-fs -q - Maven:
cd {worker临时目录} && MAVEN_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/mvnw test -Dmaven.repo.local={系统临时目录}/{ProjectName}/.m2-repository --batch-mode -q
测试不通过时的处理流程:
步骤 1:判定失败原因类型
| 失败原因类型 | 判定标准 | 处理方式 |
|---|---|---|
| 测试代码错误 | 测试用例本身的语法错误、断言逻辑错误、mock 设置错误、测试数据问题 | 修复测试代码,重新运行测试 |
| 测试设计不合理 | 边界条件过于严格、测试场景不真实、与项目实际使用方式不符 | 调整测试策略,重新运行测试 |
| 业务代码缺陷 | 测试用例正确,但被测业务代码的实际行为与预期不符(基于知识库中的业务规则和代码逻辑) | 进入 Bug 分级判定流程 |
步骤 2:Bug 分级判定
对照高危 Bug 判定标准(见 §11.2)的四大维度,对失败的测试用例所覆盖的代码路径逐维度扫描。
| Bug 等级 | 后续动作 |
|---|---|
| High(高危) | → 立即执行高危 Bug 提前退出流程 |
| Medium(中级) | → 记录缺陷到内存 → 进入用例完善循环 |
| Low(低级) | → 记录缺陷到内存 → 进入用例完善循环 |
步骤 3:缺陷处理与测试调整流程(针对 Medium/Low 缺陷)
目标:确保门禁 2 达标(所有未禁用的测试通过),同时保留对发现缺陷的记录。
流程步骤:
- 记录缺陷:将发现的缺陷记录到内存缺陷清单,缺陷记录需包含:
- 缺陷的基本信息(方法名、缺陷类型、描述、严重程度等)
- 发现该缺陷的测试方法名称
- 证据摘要(测试输出、代码位置等)
- 调整测试策略(二选一):
- 方案 A(推荐):将发现该缺陷的测试方法标记为
@Disabled(JUnit 5)或@Ignore(JUnit 4),并在注释中明确说明:- 发现的缺陷描述
- 禁用原因
- 关联的缺陷记录(如有)
- 方案 B:修改测试用例,使其测试范围避开该缺陷,但保留对其他正常功能的验证;同时在测试代码中添加注释说明被避开的缺陷
- 方案 A(推荐):将发现该缺陷的测试方法标记为
- 重新运行测试:确保所有未禁用的测试都通过
- 验证门禁 2 达标:编译通过且所有未禁用的测试通过,则进入门禁 3
缺陷记录新增字段:
- 发现该缺陷的测试方法:{测试方法全名}
- 测试方法当前状态:{保留原样 / 已禁用 / 已调整}
关键约束:
- 禁止修改业务源代码
- 必须记录所有发现的缺陷
- High 高危 Bug 必须立即退出
- Medium/Low 缺陷不阻塞继续执行,但需调整测试确保门禁 2 通过
7.3.5 门禁 3:临时目录覆盖率初步检查
在临时目录运行覆盖率工具,记录当前覆盖率数据。
门禁 3 与 Loop 4 覆盖率检查的区别:
- 门禁 3(Loop 3):仅记录覆盖率数据,无达标要求,作为后续补充用例设计的基础
- Loop 4:正式的覆盖率达标检查,要求 ≥70%,未达标则进入循环
⚠️ 必须先 cd 到临时工作区目录,再执行覆盖率命令:
- Gradle:
cd {worker临时目录} && GRADLE_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/gradlew jacocoTestReport --gradle-user-home {系统临时目录}/{ProjectName}/.gradle-cache --no-daemon --no-parallel --no-watch-fs -q - Maven:
cd {worker临时目录} && MAVEN_OPTS="-Djava.io.tmpdir={worker临时目录}/tmp" {主项目路径}/mvnw jacoco:report -Dmaven.repo.local={系统临时目录}/{ProjectName}/.m2-repository --batch-mode -q
7.3.6 记录待同步测试文件清单
临时目录单测运行通过后,记录需要同步回主项目的测试文件路径。此阶段仍不进行同步。
7.4 Loop 3 必须输出
Loop 3 完成:{ClassName} 单测编写与临时目录验证
- 编写测试:{N} 个
- 门禁 0 - 环境一致性验证:{通过 / 发现差异已修复}
- 门禁 1 - 临时目录完整编译(含 clean):{通过 / 失败后修复}
- 门禁 2 - 临时目录测试运行:{全部通过}
- 通过的测试:{X} 个
- 禁用的测试(发现缺陷):{Y} 个
- 门禁 3 - 临时目录初步覆盖率:{X}%
- 待同步测试文件:{N} 个
- 缺陷发现情况:{发现 N 个缺陷 / 未发现缺陷}
- 临时目录编译输出(含 clean):
{粘贴临时目录完整编译输出}
- 临时目录测试运行输出:
{粘贴临时目录完整测试运行输出}
8. Loop 4:覆盖率达标与文件同步
8.1 达标条件
- 临时目录行覆盖率 ≥ 70%
- 同步前环境终审通过
- 测试文件已同步回主项目
- 文件存在性验证通过
8.2 未达标处理
- 覆盖率不达标 → 重新执行 Loop 2(补充用例设计)→ Loop 3(编写测试并验证门禁)→ Loop 4(检查覆盖率),循环直到覆盖率 ≥ 70%
- Loop 1 状态永远保持
completed(覆盖率补全无需重新审查代码缺陷) - 重新执行的 Loop 2/3/4 状态更新为
in_progress→completed,输出追加(标注"第 N 次补充") - 硬约束:覆盖率 < 70% 时,不得进入 Loop 5,必须继续循环
- Loop 1 状态永远保持
- 循环期间编译遇到环境问题 → 跳转到 Loop 0 重新准备环境,然后重新执行 Loop 1→2→3→4
- Loop 0/1 从
completed重置为not_started→in_progress - 所有 Loop 输出证据必须保留追加(标注"第 N 次重试")
- Loop 0/1 从
- 环境终审不通过 → 修复差异后重新执行门禁 1-3
- 同步失败 → 记录失败原因,重试写入
8.3 执行步骤
8.3.1 临时目录覆盖率报告(必须先执行)
在临时目录运行覆盖率工具,必须展示临时目录完整覆盖率报告。
8.3.2 覆盖率补全循环(必须循环直到临时目录达标)
循环规则:覆盖率 < 70% → 分析未覆盖代码 → Loop 2 补充用例 → Loop 3 编写测试 → 门禁 0→1→2→3 → 覆盖率检查 → 仍不达标则继续循环。
关键约束:
- 针对未覆盖代码设计补充测试
- 循环期间编译遇到环境问题 → 立即跳转到 Loop 0 重新准备环境
- 持续循环直到临时目录行覆盖率 ≥ 70%
- 每次循环迭代必须输出当前覆盖率数据和未覆盖代码范围
- 硬约束:在进入 Loop 5 前,必须确保临时目录行覆盖率 ≥ 70%,否则不得继续
补充用例设计流程(与初始 Loop 2 区别):
- 读取共享经验库:在开始补充设计前,重新读取共享经验库,查看是否有解决类似覆盖率问题的经验可以复用
- 分析未覆盖代码:仔细阅读 Loop 4 覆盖率报告,精确定位哪些代码行、分支、条件未被覆盖
- 针对性设计补充用例:
- 不是从零开始重写所有测试
- 而是在已有测试文件基础上追加新测试
- 确保已有测试保持不变,避免覆盖回退
- 针对未覆盖的具体场景设计新测试
- 更新循环计数器:记录当前是第几次循环,以及每次循环后的覆盖率数据
- 使用多种设计方法:等价类划分、边界值分析、错误推测等,确保补充用例能真正覆盖未覆盖的代码
初始 Loop 2 与补充用例设计的区别:
| 维度 | 初始 Loop 2 | 补充用例设计 |
|---|---|---|
| 设计起点 | 零开始,基于目标类完整分析 | 基于已有测试 + 覆盖率报告 |
| 测试文件处理 | 完整重写 | 追加新测试,保留已有测试 |
| 设计目标 | 全面覆盖所有 public 方法 | 针对性覆盖未覆盖代码 |
| 输出要求 | 完整用例列表 | 补充用例列表 + 覆盖率提升说明 |
8.3.3 同步前环境终审(覆盖率达标后必须执行)
在将测试文件同步到主项目前,做最后一次完整的环境一致性检查。
- 依赖版本终审
- 终审不通过时:不得同步,必须修复差异后重新执行门禁 1-3
8.3.4 直接覆盖式同步测试文件回主项目(环境终审通过后必须执行)
同步方式:直接覆盖,不合并、不对比、不保留旧内容。 每个 worker 只负责自己目标类对应的测试文件,不同 worker 写入的测试文件路径天然不同({ClassName}Test.java),不存在并发写冲突。
同步协议(严格按顺序):
-
明确计算并记录目标测试文件的完整路径(主项目中的位置)
-
使用 Read + Write 工具直接覆盖同步(绝对禁止使用 cp):
- Read 工具读取临时目录中的测试文件内容
- Write 工具将内容直接覆盖写入主项目目标路径(使用相对路径)
- 无论主项目是否已有测试文件,一律以临时目录中的版本覆盖,不做任何合并或差异对比
- 同步后立即验证文件存在(使用 Read 工具读第一行确认)
-
异常情况:
- 同步失败 → 记录详细失败原因,保留临时目录,重试写入
- 关键:同步失败时,必须在
worker-{ID}-result.md的状态声明行下增加结构化子状态标记同步状态: 失败(第二行),并标记需要 ut.md 从临时目录恢复的文件路径
8.3.5 同步后验证(仅文件存在性检查)
- 验证测试文件确实存在于主项目的目标路径
- 不运行任何构建或测试命令
8.4 Loop 4 必须输出
Loop 4 完成:{ClassName} 覆盖率达标与文件同步
- 行覆盖率:{X}%
- 分支覆盖率:{Y}%
- 目标达成:是 / 否(如否,说明正在循环补全)
- 覆盖率补全循环次数:{N} 次(含 Loop 2→3→4 重试)
- 环境问题回退记录:{无 / 回退 Loop 0 {N} 次,原因:{描述}}
- 临时目录最终覆盖率:{X}%
- 同步前环境终审:{允许同步 / 禁止同步}
- 测试文件已同步回主项目:是 / 失败
- 文件存在性验证:通过 / 失败
- 测试文件完整路径:{主项目中完整绝对路径}
- 主项目统一验证:由 ut.md 在所有 worker 完成后串行执行
- 临时目录覆盖率报告:
{粘贴临时目录完整覆盖率报告}
- 临时目录保留路径:{系统临时目录}/{ProjectName}/worker-{ID}
- 临时目录未删除,供 ut.md 恢复和统一清理
9. Loop 5:结果输出 + Loop 完整性检查
9.1 达标条件
- Loop 完整性检查通过(所有 6 Loop 状态均为 completed,且 6 Loop 证据已输出到结果文件)
- Loop 4 覆盖率验证必须通过:临时目录行覆盖率 ≥ 70%(除非触发高危 Bug 提前退出)
- 缺陷文件(如有)已写入
- 共享经验(如有新经验)已按
experience_write_mode锁追加或进入 final 经验候选 - 结果文件已写入(第一行为状态声明)
- 自己持有的锁目录已清理
9.2 未达标处理
严格禁止跳过:完整性检查发现任何问题都必须返回修复,不允许绕过或跳过。
- 完整性检查发现问题 → 返回执行遗漏的 Loop
- 覆盖率未达标 → 返回 Loop 4 继续循环补全
- 文件写入失败 → 重试直到成功
9.3 执行步骤
9.3.1 Loop 完整性检查(必须执行)
- 检查
loop_execution_status中所有 6 Loop 的状态都是completed - 检查
loop_output_evidence中所有 6 Loop 的证据是否都存在 - 覆盖率达标验证(必须通过):
- 检查 Loop 4 的输出证据中,临时目录行覆盖率是否 ≥ 70%
- 如覆盖率 < 70%,且未触发高危 Bug 提前退出,必须返回 Loop 4 继续循环补全
- 如有 Loop 未完成或证据缺失,必须返回去执行该 Loop
- 将 6 Loop 的输出证据写入
worker-{ID}-result.md(必须执行,不可省略):- 必须将
loop_output_evidence中全部 6 个 Loop 的证据完整写入结果文件(纯编译命令的详细输出可以简化或省略) - 必须保留的证据:各 Loop 的关键输出、达标确认、测试运行输出、覆盖率报告、缺陷发现记录
- 如有多次重试循环:只需要保留最后一次完整循环的证据,或者保留关键的补充用例部分
- 必须将
- 完整性检查通过后才能继续下一步
9.3.2 第 1 步:向独立缺陷文件写入缺陷(如发现缺陷)
- 如 Loop 1 和 Loop 3 中发现了任何缺陷:
- 创建/覆盖独立缺陷文件
worker-{ID}-defects.md - 写入本类发现的缺陷(标记类名、方法名、缺陷描述、严重程度、处理状态"已记录,待后续处理")
- 创建/覆盖独立缺陷文件
9.3.3 第 2 步:按适配模式沉淀新经验(如解决了新问题)
- 如本次执行中解决了新问题:
child_locked_append按共享经验库并发写入协议(见 §10)获取锁并追加完整经验记录parent_finalize不写共享文件或锁,把同一记录加入 final 的HELIXHARNESS_UT_EXPERIENCE_CANDIDATES- 如发现已有等价经验,不重复写入,并在结果报告中记录"已复用已有经验"
9.3.4 第 3 步:向独立结果文件写入报告(必须执行)
- 创建/覆盖独立结果文件
worker-{ID}-result.md - 第一行必须是状态声明:
状态: 成功或状态: 失败 - 写入本类的完成记录(含类名、状态、覆盖率、Worker ID、发现缺陷数、完整执行报告)
- 必须包含 Loop 完整性检查的结果
- 必须包含
loop_output_evidence中全部 6 个 Loop 的完整证据(纯编译输出可简化,其余证据不可省略)
正常完成输出格式(见 §14.1)
9.3.5 清理锁目录(必须执行)
- 清理自己持有的锁目录:仅
child_locked_append执行;如自己持有unittest-experience.lock(检查锁目录内owner.txt中的 Worker ID),必须立即删除(使用跨平台文件删除方式)。parent_finalize不存在 Worker 锁清理动作 - 不删除临时目录:保留供 ut.md 恢复和统一清理
- 不要删除其他 Worker 创建的锁目录
9.4 Loop 5 必须输出
Loop 5 完成:{ClassName} 结果报告与完整性检查
- Loop 完整性检查:全部 6 Loop 已执行,证据已输出到结果文件
- `loop_output_evidence` 已完整写入结果文件:{是/否}(全部 6 Loop 证据已输出)
- 缺陷已写入独立文件:{是/否}
- 结果已写入独立文件:{是/否}
- 新经验已按适配模式沉淀:{锁追加/已返回父流程候选/无/已存在未重复写入}
- 锁目录:{已清理/当前模式不适用}
- 临时目录保留:{系统临时目录}/{ProjectName}/worker-{ID}(由 ut.md 统一清理)
9.5 Agent 任务完成(必须执行)
输出以上内容后,立即停止执行,不再进行任何其他操作。
10. 共享经验库写入协议
本节写锁步骤只适用于 child_locked_append;parent_finalize 只执行读取与二次去重思路,并把候选
放入 final,禁止执行本节任何锁或共享文件写操作。
10.1 读取规则
- Loop 0 必须读取一次共享经验库,建立初始经验上下文
- 每次遇到问题时,必须重新读取共享经验库最新内容,再判断是否已有可复用经验
- 获取写锁后,必须再次读取共享经验库最新内容进行二次去重
10.2 写入或候选返回触发条件
仅当本 worker 自行解决了一个共享经验库中不存在的新问题时才产生新经验:
child_locked_append:按 §10.3 追加写入共享经验库。parent_finalize:禁止执行 §10.3,只把记录放入 final 的HELIXHARNESS_UT_EXPERIENCE_CANDIDATES,由父流程二次验证、去重和串行合并。
10.3 child_locked_append 加锁写入步骤(严格遵守)
-
准备一条完整经验记录,包含 Worker ID、类名、问题类型、问题特征、解决方案、适用场景、写入时间
-
读取最新
unittest-experience.md,确认没有等价经验 -
原子创建锁目录
unittest-experience.lock获取锁(使用mkdir原子操作):mkdir docs/specs/active/{feature}/unittest-experience.lock 2>/dev/null- 如
mkdir成功 → 获得锁,在锁目录内创建owner.txt记录元数据:Worker ID: {WorkerID} 类名: {ClassName} 创建时间戳: {YYYY-MM-DD HH:MM:SS} 用途: 追加写入共享经验库 超时时间: 10 分钟 - 如
mkdir失败 → 锁已被其他 worker 持有
- 如
-
如锁已存在:
- 检查锁目录创建时间,判断是否超时(超过 10 分钟)
- 未超时:等待 30 秒后重试,最多重试 3 次
- 已超时:记录警告"发现超时锁目录,跳过写入新经验",不删除锁目录,继续执行
- 所有重试失败后,在结果中记录"经验未写入原因:无法获取锁",继续执行
-
获取锁后再次读取最新经验库,二次确认没有等价经验
-
只追加写入一条完整记录,严禁重写、截断、排序或清理已有内容
-
写入完成后立即删除自己创建的锁目录:
rm -rf docs/specs/active/{feature}/unittest-experience.lock -
如未能获取锁,必须在 worker 结果中记录"经验未写入原因",但不得影响测试结果文件的原子写入
10.4 经验记录格式
| 序号 | Worker ID | 类名 | 问题类型 | 问题特征 | 解决方案 | 适用场景 | 写入时间 |
11. 高危 Bug 提前退出例外
11.1 适用范围
仅以下两个阶段允许触发提前退出:
- Loop 1:代码逻辑深度审查中发现高危 Bug
- Loop 3:测试编写与验证中通过测试或运行输出确认高危 Bug
其他阶段不得以缺陷为理由提前退出;Low/Medium 缺陷必须只记录并继续执行。
11.2 高危 Bug 判定标准
满足以下任一条件,可判定为高危 Bug:
- 会导致核心业务结果错误、资金/权限/状态等关键数据错误
- 会导致数据丢失、越权访问、安全绕过或不可恢复副作用
- 会导致主流程在常见输入下稳定崩溃,且无法通过测试侧合理隔离继续验证
- 会导致执行路径必然失败(类型转换错误、矛盾条件分支、必然空指针、不可达逻辑等流程性阻断)
- 会导致继续生成单测产生误导性通过结果,掩盖真实生产风险
Bug 分级扫描维度(Loop 1 代码审查和 Loop 3 测试失败共用):
| 维度 | 扫描内容 |
|---|---|
| 1. 静态分析 | 类型转换矛盾、矛盾条件分支、必然空指针链路、判等错误、副作用破坏、资源生命周期错乱 |
| 2. 语义理解 | 业务规则反逻辑、权限/安全绕过、资金/数值计算错误、事务边界错误 |
| 3. 运行时预判 | 合法输入下可能的运行时异常、数据被静默修改、死循环/无限递归风险 |
| 4. 误导性风险 | 异常被吞掉、返回值语义不可能正确、方法依赖隐式全局状态 |
11.3 提前退出必须执行的动作(严格按顺序)
-
将当前 Loop 状态标记为
completed_with_critical_bug -
第 1 步:写入
worker-{ID}-defects.md,包含高危 Bug 的完整详情、证据、影响范围和建议后续处理 -
第 2 步:如本次排查产生新经验,按
experience_write_mode锁追加或加入 final 经验候选 -
第 3 步:仅
child_locked_append清理自己创建的unittest-experience.lock;parent_finalize跳过 -
第 4 步:最后写入
worker-{ID}-result.md,第一行必须是状态: 失败,第二行必须是退出原因: 高危Bug(结构化子状态标记) -
结果文件中必须明确包含:
退出原因: 高危Bug -
保留临时目录:保留临时目录供 ut.md 审查和统一清理
11.4 高危 Bug 详情必填字段
## 高危 Bug 详情
| 字段 | 内容 |
|------|------|
| 类名 | {ClassName} |
| 方法名 | {method} |
| 发现阶段 | Loop 1 / Loop 3 |
| 严重程度 | High |
| Bug 类型 | {逻辑错误/安全风险/数据错误/稳定崩溃/其他} |
| 触发条件 | {具体输入、状态或调用路径} |
| 实际结果 | {实际行为} |
| 预期结果 | {正确行为} |
| 证据 | {代码位置、测试输出、异常堆栈或推理依据} |
| 影响范围 | {影响的业务流程或数据范围} |
| 建议处理 | {建议修复方向,不修改业务代码} |
| 处理状态 | 已记录,阻断当前类单测继续生成 |
11.5 高危 Bug 退出完整性检查
替代 Loop 完整性检查,必须确认:
- 高危 Bug 详情已写入缺陷文件
- 结果文件第一行为
状态: 失败 - 结果文件明确声明
退出原因: 高危Bug - 未修改业务源代码
- 如有新经验,已按
experience_write_mode锁追加或加入 final 经验候选 - 临时目录已保留供 ut.md 审查
- 自己创建的锁目录已清理
11.6 Agent 任务完成(必须执行)
完成以上所有步骤后,立即停止执行,不再进行任何其他操作。
12. 文件操作协议
12.1 输出文件原子性契约
写文件必须按以下顺序,确保 ut.md 能正确检测状态:
- 第 1 步:如有缺陷 → 写入
worker-{ID}-defects.md - 第 2 步:如有新经验 → 按
experience_write_mode锁追加或加入 final 经验候选 - 第 3 步:最后写入
worker-{ID}-result.md(无论成功或失败),必须使用原子写协议:- 先写入临时文件
worker-{ID}-result.md.tmp - 再
mv原子重命名为worker-{ID}-result.md - 严禁直接 Write 到目标文件(父流程在原生终态后读取 result,非原子写入可能暴露不完整证据)
- 先写入临时文件
12.2 结果文件必选规则
- 无论执行成功或失败,必须写入
worker-{ID}-result.md - 结果文件第一行必须是状态声明:
状态: 成功或状态: 失败 - 结果文件第二行(如有子状态)必须是结构化标记:
- 同步失败时:
同步状态: 失败 - 高危 Bug 退出时:
退出原因: 高危Bug - 正常完成时:无需第二行子状态标记
- 同步失败时:
- 父流程按 Host Kit 等待 worker 原生终态,再检查
worker-{ID}-result.md与实际产物;文件存在不能单独作为完成信号
12.3 绝对禁止操作
- ❌ 无锁写入
unittest-experience.md - ❌ 重写、截断、重排或清理
unittest-experience.md已有内容 - ❌ 删除其他 Worker 创建的
unittest-experience.lock - ❌ 写入
unittest-results.md、unittest-defects.md(主结果文件) - ❌ 写入
unittest-queue.md(任务队列文件) - ❌ 修改或删除其他 Worker 的
worker-{其他ID}-*.md文件 - ❌ 修改主项目的任何源码或配置文件
13. 异常处理矩阵
| 异常类型 | 触发场景 | 处理策略 | 是否继续执行 |
|---|---|---|---|
| 权限阻断 | Bash/Write/Edit 操作被拒绝 | 立即写入失败结果文件,说明阻断点;尽量清理自己的锁目录 | ❌ 否(除非能绕开) |
| 临时目录创建失败 | 磁盘满、权限不足等导致无法创建临时工作区 | 立即写入失败结果文件(如可写),说明失败原因;无法写入则直接结束 | ❌ 否 |
| 编译失败 | 临时目录编译不通过 | 调试修复,无法修复则记录失败 | ✅ 是(除非触发高危 Bug) |
| 测试失败 | 单测运行不通过 | 分析原因,确认为缺陷则记录,继续优化 | ✅ 是(除非触发高危 Bug) |
| 锁竞争 | 获取共享经验库锁超时 | 记录警告,跳过经验写入,继续执行 | ✅ 是 |
| 文件 IO 异常 | 写入独立文件失败 | 按原子写文件契约处理,尽力重试 | ✅ 是(除非结果文件无法写入) |
| 配额中断 | 执行时间或资源超限 | 尽力清理自己的锁目录,尽量写入不完整结果,由 ut.md 兜底 | ⏹️ 中断 |
| 主项目源码变化 | 检测到主项目源码在执行中被修改 | 记录警告,继续执行,最终由 ut.md 统一验证 | ✅ 是 |
13.1 权限阻断详细处理
前置说明:
- 正常情况下,ut.md 已预先完成权限托管,不应出现权限阻断
- 如出现权限阻断,说明权限托管可能失效,需要重新运行 /helix:ut
遇到权限阻断时的执行步骤:
- 立即停止当前操作,不等待,不反复重试
- 尽力写入失败结果文件(如有权限):
- 状态标记为
状态: 失败 - 明确说明阻断点和原因
- 在结果文件中追加:
权限托管异常,请重新运行 /helix:ut
- 状态标记为
- 尽力清理自己的临时资源(如有权限):只清理自己创建的锁目录
- 直接结束,不尝试其他操作
- 结果文件也无法写入时:直接结束,由 ut.md 超时机制处理
执行完以上步骤后,立即停止执行,不再进行任何其他操作。任务已完成(因权限阻断终止)。
14. 附录:结果文件格式模板
14.1 正常完成格式
文件第一行必须是状态声明,同步失败时第二行必须是结构化子状态标记:
成功完成(无同步失败):
状态: 成功
# {ClassName} 单测维护完成
成功完成但同步失败:
状态: 成功
同步状态: 失败
# {ClassName} 单测维护完成
同步失败时,
同步状态: 失败必须紧跟在状态声明行之后(第二行),ut.md 据此判定队列状态为completed(备注: sync_failed),并触发 Phase 2-5 文件恢复流程。
完整结果文件模板(以下为成功完成无同步失败的模板,同步失败变体见上方):
状态: 成功
# {ClassName} 单测维护完成
Worker ID:{ID} 完成时间:{YYYY-MM-DD HH:MM} 是否为重试:{是/否} 重试次数:{0/1/2}
执行摘要
| 指标 | 数值 |
|---|---|
| 新增测试方法 | {N} 个 |
| 修改现有测试 | {N} 个 |
| 代码行覆盖率 | {X}% |
| 覆盖率目标达成 | 是 / 否 |
| 发现缺陷 | {N} 个 |
| 临时目录测试验证 | 通过 / 失败 |
| 测试文件已同步到主项目 | 是 / 否 |
发现的缺陷(如有)
| 序号 | 方法名 | 缺陷类型 | 缺陷描述 | 严重程度 |
|---|---|---|---|---|
| 1 | {method} | NPE/边界错误 | {详细描述} | High/Medium/Low |
Loop 执行确认
- Loop 0-5:各 Loop 的完成状态和达标情况见「Loop 执行证据」
Loop 执行证据
各 Loop 的完整输出证据:
证据简化规则:
- 纯编译命令的详细输出可以简化或省略
- 必须保留:各 Loop 的关键输出、达标确认、测试运行输出、覆盖率报告、缺陷发现记录
- 如有多次重试循环:只需要保留最后一次完整循环的证据,或者保留关键的补充用例部分
Loop 0 证据
{粘贴 loop_output_evidence["Loop 0"] 的完整内容,环境编译验证可简化}
Loop 1 证据
{粘贴 loop_output_evidence["Loop 1"] 的完整内容,含审查结果}
Loop 2 证据
{粘贴 loop_output_evidence["Loop 2"] 的完整内容,含用例列表}
Loop 3 证据
{粘贴 loop_output_evidence["Loop 3"] 的完整内容,编译输出可简化,测试运行输出和初步覆盖率必须保留}
Loop 4 证据
{粘贴 loop_output_evidence["Loop 4"] 的完整内容,最终覆盖率报告必须保留}
Loop 5 证据
{粘贴 loop_output_evidence["Loop 5"] 的完整内容,含完整性检查结果}
新增测试文件位置
测试文件完整路径:{主项目中完整绝对路径} 相对路径:{主项目根目录开始的相对路径} 临时目录备份路径:{系统临时目录}/{ProjectName}/worker-{ID}
### 14.2 高危 Bug 提前退出格式
**文件第一行必须是状态声明,第二行必须是结构化子状态标记**:
```markdown
状态: 失败
退出原因: 高危Bug
# {ClassName} 单测维护提前退出
> Worker ID:{ID}
> 完成时间:{YYYY-MM-DD HH:MM}
> 触发阶段:Loop 1 / Loop 3
## 执行摘要
| 指标 | 数值 |
|------|------|
| 新增测试方法 | {N} 个 / 未继续生成 |
| 修改现有测试 | {N} 个 / 未继续修改 |
| 代码行覆盖率 | 未评估(高危 Bug 阻断) |
| 覆盖率目标达成 | 否 |
| 发现缺陷 | {N} 个 |
| 高危 Bug | 1 个或更多 |
## 高危 Bug 详情
{复制 worker-{ID}-defects.md 中的完整高危 Bug 详情}
## Loop 执行确认
- Loop 0:上下文加载完成 + 临时环境准备完成
- Loop 1:{完成 / 发现高危 Bug 后提前退出}
- Loop 2:{因高危 Bug 未执行 / 已完成}
- Loop 3:{因高危 Bug 未执行 / 发现高危 Bug 后提前退出}
- Loop 4:{因高危 Bug 未执行}
- Loop 5:{因高危 Bug 提前退出,改为执行高危 Bug 退出完整性检查}
## 高危 Bug 退出完整性检查
- 高危 Bug 详情已写入独立缺陷文件
- 结果文件第一行为 `状态: 失败`
- 结果文件已声明 `退出原因: 高危Bug`
- 未修改业务源代码
- 如有新经验,已按 `experience_write_mode` 锁追加或加入 final 经验候选
- 临时目录已保留供 ut.md 审查
- 自己创建的锁目录已清理
Sponsors
Details
- Marketplace
- didi/helixharness
- Source
- helixharness
- Category
- Community
- License
- Apache-2.0