ttwy-frontend-agent-kit

面向当前前端仓库的任务书、范围审计、Mock-first、Review、QA、Ponytail 和暂存交付工具包。默认执行模型为 current-branch：业务代码直接落在项目当前已检出的分支，不创建 Worker 分支或 Git worktree。

交付边界

• workflow dispatch 只记录当前项目根目录、已检出分支与冻结 HEAD；Worker、Review、QA 都在该目录执行。
• 同一仓库只能有一个活跃业务运行。创建运行不要求先提交单个模块；派发时仅接管位于本次已批准路径内的已有业务 diff，并记录清单后与新改动一起完成 Review、QA 和一次性暂存。运行期间 HEAD、任务书、scope.json 或已绑定接口合同的外部变化都会阻断。
• 任务书、scope.json、Mock-first、规格/代码审查、Ponytail、菜单合同与接口合同校验保持不变。原型 HTML 或作为设计基线的截图任务额外冻结逐页 prototypeTrace：原型源 SHA-256、页面、路由、组件、聚焦测试、可见元素、交互状态与可延后合同项。
• 不运行 npm ci 或 npm install；直落模式只复用已有依赖。依赖缺失时阻断并报告。
• Worker 仅能改批准路径，不能编辑工作流资料，也不能执行 Git 暂存、提交、合并、变基、推送、分支或 worktree 操作。

安装与初始化

npm install --save-dev @tantuwuyou/frontend-agent-kit
npx ttwy-frontend-agent init --profile pc-admin

初始化会生成当前仓库的 AGENTS.md、角色规则、任务书模板和校验脚本；不会创建 Git 分支或 worktree。

本包是公开 npm 包。自动初始化异常时，可使用 npm install -D @tantuwuyou/frontend-agent-kit --ignore-scripts 后显式执行 npx ttwy-frontend-agent init --profile <profile> 恢复。

工作流

ttwy-frontend-agent workflow create --taskbook <中文任务书.md> --scope <scope.json>
ttwy-frontend-agent workflow approve --run <运行编号> --tasks T-01 --approved-by <确认人>
ttwy-frontend-agent workflow dispatch --run <运行编号>
ttwy-frontend-agent workflow progress start --run <运行编号> --task T-01 --started-by <执行人>
ttwy-frontend-agent workflow progress implement --run <运行编号> --task T-01 --implemented-by <执行人> --evidence <代码完成证据>
ttwy-frontend-agent workflow progress complete --run <运行编号> --task T-01 --completed-by <确认人> --evidence <质量通过证据>

派发后，控制器在同一项目目录安排 Worker 实现、记录任务进度、绑定真实接口或获批 Mock-first 适配器，并在每个门禁前重新审计冻结资料和基线差异。progress implement 会立即勾选该任务，并按任务书全部冻结任务显示代码进度百分比；它不表示 Review、QA、人工验证或暂存通过。质量门禁全部通过后，控制器再执行 workflow progress complete 记录交付完成。

任务书中的接口时序由 apiContractTiming 约束；需求池条目、其他需求来源、clarification、冲突检查和范围确认必须在审批前冻结。

原型一致性门禁

原型 HTML 输入时，或截图被明确作为页面设计基线时，scope.json.prototypeTrace 必须覆盖每个任务；每个新增 menuStructure 页面/路由必须存在相同任务、路由和组件的追溯项。仅描述当前现状的截图可继续作为普通 intake.evidence。每项包含源 HTML/截图 SHA-256、页面名、路由、Vue 文件、聚焦测试、可见元素、交互状态和仅限 URL/字段语义/权限/价格/状态机的 deferredContracts。可观察 UI 不得以“接口待补”跳过。

ttwy-frontend-agent workflow prototype extract --source <Axure页面.html>
ttwy-frontend-agent workflow prototype matrix --run <运行编号>
ttwy-frontend-agent workflow prototype review --run <运行编号> --trace PT-01 --status passed --reviewed-by <审查人> --evidence <对照说明> --screenshot <当前页面截图.png>

extract 只用 Node 标准库从 Axure HTML 提取 data-label、表格单元格和页面说明，输出待确认候选清单，不修改原型或业务代码。matrix 输出“原型页 → 路由 → Vue 文件 → 测试文件 → 验收截图”的当前追溯表。Spec Review 未记录全部已批准页面为 passed 或合规的 deferred-contract 时不能通过；两种结果都必须有浏览器截图，故 deferred-contract 不能跳过可见 UI 对照。failed 自动创建 R-xx。原型修复先是 implemented，重新浏览器对照并记录截图后才成为 prototype-verified，可继续审查和 QA。

真实接口合同缺失时，严禁推断 URL、方法、字段、响应、权限、价格或业务规则。只有批准了 apiDeliveryMode: "mock-first"、mockAdapterPaths 与 reconciliationAuthorized: true 的任务可使用本地 Mock。真实合同补齐后：

ttwy-frontend-agent workflow api reconcile --source-run <运行编号> --task T-01 --document <接口文档.md> --data <API_DOC_DATA.json>

该命令在同一运行回到实现并要求完整复验，不创建关联分支、worktree 或合入动作。

审查、QA 与暂存

控制器按冻结范围推进规格审查、代码审查、Ponytail、自动 QA 和所需人工验证。QA 对基线后的业务文件做快照；范围越界、QA 改写业务文件或冻结资料漂移会阻断运行。

所有批准任务和门禁通过后执行：

ttwy-frontend-agent workflow stage --run <运行编号> --staged-by <确认人>

stage 只执行 git add -- <批准业务文件>，记录状态 staged 与文件清单。它不会创建 commit，也不会 merge、rebase、切换分支或 push。若暂存区存在未批准的业务文件，命令会阻断。

scope.json.ponytailExceptions 仅用于冻结且有理由的最小复杂度例外；控制器仍须运行 Ponytail 审计。PC 动态菜单任务用 menuStructure 表达结构，只生成待执行 admin_menus SQL，不生成 rules.perm 角色授权 SQL。

运行状态

implementation、spec-review、code-review、qa、ready-to-commit、ready-to-commit-mock、staged、awaiting-api-contract、interrupted 与 blocked 都保存在 .ttwy-agent/workflow.json。interrupted 可在同一分支恢复；blocked 需要先恢复冻结资料、范围或合同的一致性。

ttwy-frontend-agent workflow status --run <运行编号>
ttwy-frontend-agent workflow interrupt --run <运行编号> --reason <原因> --reported-by <人>
ttwy-frontend-agent workflow resume --run <运行编号> --resolved-by <人> --evidence <证据>

阻断与恢复

blocked 表示冻结任务书、范围、合同、HEAD 或范围审计不一致，必须先恢复原因；interrupted 是可恢复中断（资源或环境问题），使用同一运行、同一当前分支执行 workflow resume。两者都不会创建新 worktree。

开发与验证

npm test
npm run pack:check

发布由获授权人员在完成验证后另行执行；工作流本身不发布、不推送，也不改变当前 Git 分支。