@tea-agent/loop-agent 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/AGENTS.md +10 -2
  2. package/CHANGELOG.md +67 -25
  3. package/README.md +82 -11
  4. package/dist/application/dag/args.js +1 -12
  5. package/dist/application/dag/generate-task-dag.js +23 -2
  6. package/dist/application/dag/run-dag.js +1 -27
  7. package/dist/application/dag/validate-dag.js +2 -2
  8. package/dist/application/loop/run-action.js +0 -4
  9. package/dist/cli/command-definitions.js +44 -16
  10. package/dist/cli/program.js +40 -23
  11. package/dist/cli/update/notifier.js +117 -0
  12. package/dist/cli/update/npm-client.js +151 -0
  13. package/dist/cli/update/policy.js +58 -0
  14. package/dist/cli/update/state.js +68 -0
  15. package/dist/cli.js +33 -0
  16. package/dist/commands/cursor-prompt.js +42 -82
  17. package/dist/commands/dag-approve.js +36 -0
  18. package/dist/commands/delegate.js +75 -77
  19. package/dist/commands/doctor.js +0 -18
  20. package/dist/commands/init.js +476 -91
  21. package/dist/commands/instructions.js +7 -10
  22. package/dist/commands/loop.js +4 -20
  23. package/dist/commands/plan.js +50 -0
  24. package/dist/executors/config-core.js +0 -51
  25. package/dist/executors/dag-pi-executor.js +1 -1
  26. package/dist/executors/dag.js +0 -1
  27. package/dist/executors/index.js +0 -2
  28. package/dist/executors/model-routing.js +9 -9
  29. package/dist/executors/shell-executor.js +1 -1
  30. package/dist/governance/checks.js +6 -3
  31. package/dist/governance/exec-plans.js +545 -0
  32. package/dist/governance/manifest-types.js +24 -2
  33. package/dist/infrastructure/harness/loop-action-store.js +0 -3
  34. package/dist/records/harvest.js +2 -23
  35. package/dist/records/one-shot-runs.js +1 -1
  36. package/dist/shared/artifacts-core.js +24 -5
  37. package/dist/shared/output-truncation.js +37 -0
  38. package/dist/shared/package-metadata.js +353 -0
  39. package/dist/{executors/cursor-executor.js → sidecars/cursor-prompt/executor.js} +2 -42
  40. package/dist/sidecars/cursor-prompt/index.js +3 -0
  41. package/dist/sidecars/cursor-prompt/stream.js +121 -0
  42. package/dist/task/config-types.js +28 -12
  43. package/dist/task/delegate.js +9 -21
  44. package/dist/task/runtime.js +1 -2
  45. package/dist/worker/cli.js +29 -2
  46. package/dist/worker/delivery/final-verification.js +47 -11
  47. package/dist/worker/delivery/package.js +63 -10
  48. package/dist/worker/feature/run.js +60 -8
  49. package/dist/worker/loop-agent/loop-agent-client.js +329 -126
  50. package/dist/worker/observability/read-model.js +27 -1
  51. package/dist/worker/observe/static/app.js +326 -45
  52. package/dist/worker/observe/static/index.html +1 -1
  53. package/dist/worker/observe/static/styles.css +5 -4
  54. package/dist/worker/preflight.js +49 -1
  55. package/dist/worker/run-task/run-task.js +22 -12
  56. package/dist/worker/runner/run-ready.js +76 -12
  57. package/dist/worker/task-spec/schema.js +0 -1
  58. package/dist/workflows/dag/convergence/controller.js +1 -1
  59. package/dist/workflows/dag/executor-registry.js +0 -2
  60. package/dist/workflows/dag/init-hybrid.js +402 -25
  61. package/dist/workflows/dag/node-execution.js +61 -7
  62. package/dist/workflows/dag/runner.js +45 -17
  63. package/dist/workflows/dag/scheduler.js +7 -2
  64. package/dist/workflows/dag/sdd-embedded.js +128 -0
  65. package/dist/workflows/dag/skill-instructions.js +5 -4
  66. package/dist/workflows/dag/skill-snapshot.js +527 -0
  67. package/dist/workflows/dag/types.js +42 -9
  68. package/dist/workflows/dag/validate.js +5 -8
  69. package/dist/workflows/loop/actions/dag-action.js +0 -2
  70. package/dist/workflows/loop/actions/shared.js +1 -1
  71. package/dist/workflows/loop/actions.js +14 -31
  72. package/dist/workflows/loop/benchmark.js +1 -1
  73. package/dist/workflows/loop/index.js +1 -1
  74. package/dist/workflows/loop/policy/auto-policy.js +22 -14
  75. package/dist/workflows/loop/policy/path-patterns.js +13 -0
  76. package/docs/README.md +36 -33
  77. package/docs/agent-dag-recovery-playbook.md +1 -1
  78. package/docs/agent-dag-runner.md +2 -2
  79. package/docs/architecture/README.md +26 -0
  80. package/docs/architecture/dag-execution.md +134 -0
  81. package/docs/architecture/evolution.md +52 -0
  82. package/docs/architecture/facts-and-state.md +58 -0
  83. package/docs/architecture/runtime-boundaries.md +45 -17
  84. package/docs/architecture/system-overview.md +93 -0
  85. package/docs/architecture/worker-and-feature.md +81 -0
  86. package/docs/cursor-prompt-sidecar.md +36 -0
  87. package/docs/decisions/README.md +13 -1
  88. package/docs/design/README.md +42 -21
  89. package/docs/development-principles.md +2 -2
  90. package/docs/exec-plans/active/README.md +2 -2
  91. package/docs/exec-plans/completed/README.md +12 -0
  92. package/docs/feature-workflow.md +50 -4
  93. package/docs/harness-methodology-debugging.md +1 -1
  94. package/docs/harness-methodology-tdd.md +3 -3
  95. package/docs/init-surface.manifest.json +60 -25
  96. package/docs/loop-agent-harness.md +28 -4
  97. package/docs/progress/README.md +32 -1
  98. package/docs/reports/README.md +84 -18
  99. package/docs/skills/README.md +2 -1
  100. package/docs/skills/vetted-skill-registry.md +2 -1
  101. package/docs/templates/agent-dag-report.schema.json +6 -6
  102. package/docs/templates/agent-dag.base.json +0 -5
  103. package/docs/templates/agent-dag.final-verification.json +0 -5
  104. package/docs/templates/agent-dag.schema.json +1 -2
  105. package/docs/templates/agent-dag.supervised-implementation.json +1 -6
  106. package/docs/templates/frontend-design-contract.md +33 -0
  107. package/docs/templates/frontend-task-constraints.md +25 -0
  108. package/docs/templates/frontend-task-requirement.md +61 -0
  109. package/docs/templates/harness.schema.json +10 -12
  110. package/docs/templates/hybrid-dag.json +1 -6
  111. package/docs/templates/interactive-ui-round2-experiment.md +1 -1
  112. package/docs/templates/product-line/task.yaml +0 -1
  113. package/docs/templates/project-start-checklist.md +2 -2
  114. package/docs/templates/worker-dogfood-evidence.md +28 -0
  115. package/docs/templates/worker-dogfood-setup.md +20 -0
  116. package/docs/verification-matrix.md +10 -0
  117. package/examples/decision-gate-agent-dag.json +87 -33
  118. package/examples/example-dag.json +0 -5
  119. package/examples/hybrid-loop-agent-dag.json +0 -5
  120. package/harness.json +7 -15
  121. package/package.json +22 -46
  122. package/scripts/check-product-line-docs.sh +10 -7
  123. package/skills/agent-worker/SKILL.md +37 -0
  124. package/skills/agent-worker/references/agent-worker-operator.md +43 -0
  125. package/skills/frontend-design-review/SKILL.md +59 -0
  126. package/skills/frontend-design-review/references/review-checklist.md +37 -0
  127. package/skills/frontend-implementation/SKILL.md +51 -0
  128. package/skills/frontend-implementation/references/code-standards.md +34 -0
  129. package/skills/frontend-implementation/references/design-spec.md +46 -0
  130. package/skills/frontend-implementation/references/node-contracts.md +32 -0
  131. package/skills/frontend-review/SKILL.md +53 -0
  132. package/skills/frontend-review/references/review-findings.md +42 -0
  133. package/skills/frontend-verification/SKILL.md +40 -0
  134. package/skills/frontend-verification/references/verification-checklist.md +56 -0
  135. package/skills/grill-me/SKILL.md +10 -0
  136. package/skills/grill-with-docs/SKILL.md +88 -0
  137. package/skills/grill-with-docs/adr-format.md +47 -0
  138. package/skills/grill-with-docs/context-format.md +60 -0
  139. package/skills/loop-agent/SKILL.md +11 -9
  140. package/skills/loop-agent/references/command-reference.md +13 -15
  141. package/skills/loop-agent/references/docs-converge.md +126 -0
  142. package/skills/loop-agent/references/harness-policy.md +7 -7
  143. package/skills/loop-agent/references/hybrid-dag.md +15 -18
  144. package/skills/loop-agent/references/long-running-loop.md +4 -6
  145. package/skills/loop-agent/references/multi-worktree.md +6 -6
  146. package/skills/loop-agent/references/orchestrator-and-interventions.md +3 -3
  147. package/skills/loop-agent/references/pi-subagent-assisted-mode.md +14 -11
  148. package/skills/loop-agent/references/task-workflow.md +1 -1
  149. package/skills/using-git-worktrees/SKILL.md +215 -0
  150. package/dist/commands/cursor-worker.js +0 -43
  151. package/dist/cursor-worker-entry.js +0 -8
  152. package/dist/executors/cursor-artifacts.js +0 -33
  153. package/dist/executors/cursor-execution-log.js +0 -81
  154. package/dist/executors/cursor-executor-artifacts.js +0 -134
  155. package/dist/executors/cursor-run.js +0 -115
  156. package/dist/executors/cursor-tool.js +0 -94
  157. package/dist/executors/cursor-worker-client.js +0 -223
  158. package/dist/executors/cursor-worker-protocol.js +0 -18
  159. package/dist/executors/cursor-worker-server.js +0 -54
  160. package/dist/executors/cursor-worker.js +0 -3
  161. package/dist/executors/cursor.js +0 -6
  162. package/dist/executors/dag-cursor-executor.js +0 -87
  163. package/dist/workflows/loop/actions/cursor-fix.js +0 -191
  164. package/dist/workflows/loop/policy/cursor-fix-policy.js +0 -31
  165. package/docs/cursor-executor-usage.md +0 -25
  166. package/docs/dynamic-workflow-dag-engine-roadmap.md +0 -1749
package/AGENTS.md CHANGED
@@ -17,6 +17,7 @@
17
17
  - 先验证基线,再叠加改动;如果当前基线已坏,优先定位基线问题。
18
18
  - 完成定义必须可验证;不能靠删测试、降标准或模糊描述制造“完成”。
19
19
  - 搜索先于实现;先查现有代码、文档、脚本、测试,避免重复造轮子或误判系统能力。
20
+ - 受治理 Agent runtime 只有 Pi:DAG writer 固定为 `implement-pi` / `repair-pi`;`cursor-prompt` 仅是显式手工 one-shot sidecar,不进入 Loop auto-execute 或 Delegate 自动写入。
20
21
  - 在 DAG runtime 中,搜索/侦察是显式节点:标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
21
22
  - init surface、runtime 边界、command registry、skill entry 和架构 import 方向是可机器校验的治理契约;相关细节以 `docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/` 和 `scripts/check-*.sh` 为准,顶层 `AGENTS.md` 只指路,不重复维护事实源。
22
23
  - 本仓库既是 loop-agent 源项目,也是目标项目初始化体验的默认模板;任何新增命令、脚本、文档、skill、模板或发布包内容,都要判断它应由 npm 包内置提供,还是由 `loop-agent init` 投影到目标项目,避免出现“本项目能用、初始化项目缺能力”。
@@ -70,7 +71,7 @@
70
71
  - `src/`:loop-agent 运行时代码
71
72
  - `test/`:Vitest 测试套件
72
73
  - `bin/loop-agent.js`:CLI 可执行入口
73
- - `skills/`:loop-agent DAG 模板引用的本地 skill 指令与参考资料;`init --profile full` 还会把同一份 skills 镜像到目标项目的 `.agents/skills/`(外部 agent 兼容路径,包内仍只带 `skills/`)。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block,忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实,但保留 `.harness/prompts/` 和目录占位可共享,不会整目录忽略 `.harness/`。
74
+ - `skills/`:loop-agent 源仓库和 npm 包内置 skill 指令与参考资料;目标项目初始化后只生成 `.agents/skills/`,不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block,忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实,但保留 `.harness/prompts/` 和目录占位可共享,不会整目录忽略 `.harness/`。
74
75
  - `.harness/`:任务、DAG、run、cache 和 live state 等运行态目录
75
76
  - `docs/`:治理文档、计划、报告和模板
76
77
  - `website/`:Docusaurus 用户文档站
@@ -84,7 +85,7 @@
84
85
  - 长期决策写入 `docs/`,不要只留在聊天里。
85
86
  - 面向使用者的新增、修改、删除或修复,应同步更新根目录 `CHANGELOG.md`;保持版本级摘要即可,不写过细技术细节。
86
87
  - 面向用户的中文更新日志、README 和说明文档应使用自然、结果导向的表达:先说明用户能获得什么或问题如何改善,保留必要的命令和产品术语,避免逐字翻译、内部实现细节和无意义的中英混杂。
87
- - 涉及 `loop-agent init` 或目标项目投影的改动,必须同步考虑目标项目生成物:`AGENTS.md`、`README.md`、`harness.json`、`docs/`、`scripts/`、`skills/`、`.agents/skills/`(skills 镜像)、`.harness/prompts`、`.gitignore`(loop-agent runtime managed block)和 npm 包内置 assets
88
+ - 涉及 `loop-agent init` 或目标项目投影的改动,必须同步考虑目标项目生成物:`AGENTS.md`、`README.md`、`harness.json`、`ai_workspace/loop-agent/`、`scripts/`、`.agents/skills/`、`.harness/prompts`、`.gitignore`(loop-agent runtime managed block)和 npm 包内置 assets;目标项目根 `docs/` 和根 `skills/` 的旧投影需要由 `init update --apply-safe` 安全迁移或退役。
88
89
  - 涉及初始化能力演化时,按 `docs/init-surface.manifest.json` 与 `scripts/check-init-evolution-needed.sh` 分级处理:小改 advisory,中等 surface-check,高影响才需要模型审查;不要把所有小改动升级成重流程。
89
90
  - 通用脚本、skill 和模板可以复制或投影;项目相关 README、验证命令、发布/维护脚本必须基于模板和目标项目真实文件生成,不假定目标项目是 TypeScript、Node、前端、后端或工具项目。
90
91
  - 涉及 CLI command、skill entry、runtime boundary、import 方向或发布包范围时,同步更新对应文档、catalog/definition、治理脚本和测试,避免 README、skill reference、CLI help、npm 包内容互相漂移。
@@ -143,3 +144,10 @@ npm run docs:build
143
144
  - 不要用 stub、假数据通路或注释承诺替代真正交付。
144
145
  - 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料;个人工具配置应留在用户级配置或本机会话上下文。
145
146
  - 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验;新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目,必须写清原因和替代入口。
147
+
148
+ ## Cursor Cloud specific instructions
149
+
150
+ 这些是 Cursor Cloud VM 上非显而易见、会反复踩的两个环境坑。标准命令仍以 `README.md` 与 `docs/verification-matrix.md` 为准,这里不重复。启动时的 update script 已执行 `nvm use 22` + `npm ci`。
151
+
152
+ - Node 版本:VM 默认 `node`(`/exec-daemon/node`)是 v22.14.0,但可选依赖 `@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 要求 Node `>=22.19.0`,否则 `npm install`/`npm ci` 会静默跳过它们,导致 `npm run typecheck` 和 `npm run build` 报 `Cannot find module '@earendil-works/...'`。交互式 shell 默认仍是系统 node,跑任何 `npm install`/`npm ci` 前先执行 `nvm use 22`(已预装 v22.22.2)。
153
+ - Git 提交签名会让 git 密集型测试超时:全局 git 配置默认对每次 commit 用 `cursor-git-ssh-keygen`(`gpg.format=ssh` + `commit.gpgsign=true`)签名,该 helper 会间歇性卡住 7–30s,使 `test/worker/delivery/**`、`test/worker/feature/**` 等在临时仓库里做多次 commit 的用例撞上 15/30s 超时而失败(单独跑却能过)。跑 `npm test` 或任何会频繁 commit 的工作前,先对子进程 git 关闭签名:`export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false`(或在目标仓库 `git config commit.gpgsign false`)。关闭后整套 `npm test` 约 60s 全绿。这只影响本地/测试环境,不改仓库代码。
package/CHANGELOG.md CHANGED
@@ -6,34 +6,72 @@
6
6
 
7
7
  ### 新增
8
8
 
9
- - 严格初始化演化检查现在接受 `Head` 为当前 `HEAD` 可解析祖先提交的报告:只要 `Base` 精确匹配 `--base`、`Head` 是 `HEAD` 或其祖先,且 `reportHead..HEAD` 区间没有新的 `model-review` 高影响路径即可通过。仅 `advisory` 或 `surface-check` 的后续变化不会让已完成的高影响审查失效;`working tree` 等不可解析 Head 与无关历史报告仍被拒绝。
10
-
11
- - 新增只读的 `agent-worker feature review`。用户无需翻查原始日志,即可查看 Feature 当前状态、主要阻塞、required AC 覆盖、证据位置和下一条建议命令;`--json` 可供脚本稳定消费。
12
- - 新增 `agent-worker feature run`。它会先校验 Feature 和目标仓库,再复用现有 Worker pipeline 推进一个 Ready Task,随后刷新晨报、Observe snapshot 和 Feature review;`--dry-run` 可在零写入下预览步骤与产物。
13
- - 新增 ProductBug Follow-up 人工接续流程。`agent-worker task draft-followup` 生成可审查、可去重的修复草稿;`agent-worker feature approve-followup --dry-run` 可先检查变更计划,批准后再新增 FIX Task、重连下游依赖并进入 Ready,同时保留原失败证据。
14
- - Follow-up 现已覆盖全部失败分类:可执行类生成严格 TaskSpec,Spec/Risk/Human 类生成行动卡,EnvFailure 只有连续两次失败后才建议环境检查任务;审批事务增加多阶段回滚验证,避免 Packet、Ready state、approval index 半写。
15
- - `agent-worker feature run --git-mode checkpoint` 新增显式授权的本地 Feature 分支事务。成功任务形成带 Feature/Task/AC/run 信息的 checkpoint commit;失败任务保存 patch 与 untracked 证据后恢复 clean。默认仍不 commit,也不会 push、stash、merge 或创建远程 PR。
16
- - 新增 `agent-worker feature verify-final`、`feature delivery` 与 Feature Closeout。用户可在 clean Delivery HEAD 上生成 canonical QA/最终验证证据,再从 checkpoint、成功 run 和 required AC 形成带 hash 的 Delivery Package、Acceptance Coverage 与 PR 草稿;Closeout 默认预览,只有显式 `--apply --owner` 才原子写回并保留幂等、stale facts 与回滚保护。
17
- - Morning report Observe 首页新增共享的 Feature Decision Summary,优先显示状态、下一步、原因、证据和 required AC。新增 `agent-worker report metrics --month YYYY-MM`,同时输出带分母、样本量、时间窗口和缺失数据说明的 JSON/Markdown。
18
- - Observe 总览新增仓库横幅,显示仓库名与绝对路径;KPI 按主要执行链路排列为“Worker 执行”在前、“DAG 运行”在后,DAG 组明确展示活跃运行、执行中/等待节点、暂停和需处理运行,“活跃 Task”更名为“活跃 Worker Task”,每张卡片新增可键盘聚焦的问号帮助,解释数据来源与统计口径。
19
- - Observe 总览的 Feature 决策仅在存在“运行中”或“需处理”的 Feature 时显示;只有可执行、待验收、已交付或已关闭记录时不再占用总览空间。
9
+ - 新增版本更新提醒。发现新版本时可以直接确认升级;忽略某个版本后不会重复提醒,后续新版本仍会正常提示。可用 `LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 关闭检查。
10
+ - 新增 `loop-agent plan create`、`plan complete` 和 `plan check`,统一维护执行计划及其索引,并在生成 DAG 前发现遗漏或不一致。
11
+ - 目标项目可以选择复用本地 SDD skills,为需求、设计、实现和评审节点补充方法指引;未安装时保持原有流程。
12
+ - 新增 `docs/architecture/` 全景、DAG 执行、Worker/Feature、运行态事实与演进五篇主题文档及目录索引,并在 npm package(不投影到 init)内可达。
13
+ - Worker DAG 运行会固定本次使用的 loop-agent 版本与 skill 配置,避免执行过程中因环境变化产生不一致结果。
14
+ - 新增 `npm run self-host:canary -- --deterministic`,可在隔离环境中检查候选发布包是否能够接管常用 CLI、初始化和 DAG 流程。
15
+ - 新增可选的 `agent-worker` skill,为 FeatureTask、交付和失败恢复提供统一的操作指引。
16
+ - 文档站新增功能导览、架构导读与当前规划入口,并把文档收敛检查固化到 `skills/loop-agent`,减少站上文档与仓库治理文档漂移。
17
+ - 前端 DAG repo-local skills 补齐节点输入、输出、证据和失败规则;前端规范会优先查知识库,失败时回退到当前项目 `openSpec/`。
18
+ - 目标项目旧布局迁移:`init check-update`(只读)报告旧根 `docs/` / `skills/` 可安全迁移的 loop-agent owned 文件、空目录和 `harness.json` 中已废弃的模型字段;`init update --apply-safe` 迁移确认未修改的文件、清理空目录并清理废弃字段,本地修改过、来源不明或目标冲突的文件只进入人工决策,不会被覆盖或删除。
19
+
20
+ ### 变更
21
+
22
+ - 根 README 在「核心概念」后增加极简「仓库地图」,方便一眼区分 `src/`、`skills/`、`.harness/`、`docs/` 等职责;细节仍以 `AGENTS.md` 与 `docs/README.md` 为准。
23
+ - 文档治理收敛:站上「当前规划」与 active plan 同步(无进行中计划时明确写出);`docs/README` 只索引核心契约与产物目录入口,progress/report 全量列表下沉到子目录 README;Dynamic Workflow 路线图迁入 `docs/design/`;补齐 design 漏索引与 DAG recovery playbook 入口。
24
+ - 活文档校准:Dynamic Workflow 路线图页首标明已落地 vs 设计输入(Pi-only);六个月规划第 1–2 月改为 archive/reports 指针;`repository-analysis` 冻结为基线快照,新增 `docs/reports/current-capability-summary.md`;落地 ADR 0001–0003(Pi-only、Task Pool 根、双树/docs-converge)。
25
+ - 统一 Feature Packet 的推荐目录和中文说明,相关检查同时兼容现有产品线目录。
26
+ - 目标项目初始化布局收敛:默认把 loop-agent 治理资料生成到 `ai_workspace/loop-agent/`,不再在目标项目根生成 `docs/`;`--profile full` 只把 repo-local skills 写到 `.agents/skills/`,不再生成根 `skills/`。
27
+ - `new-task` 不再预种 L1 空报告模板(`分析报告.md` / `实现计划.md` / `复盘报告.md`);任务 `artifacts/` 默认只保留 `修改记录.md` 与 `验证结果.md`,由 `promote-run` 从 completed run 回填。
28
+ - 运行期间修改 skill 不会影响当前任务,新配置会从下一次运行开始生效。
29
+ - Observe 自动刷新时会保留依赖图、检查器和日志的阅读位置,查看长时间任务时不再被频繁打断。
30
+
31
+ ### 修复
32
+
33
+ - 前端 DAG 从 `需求.md` / `执行约束.md` 读取验证命令时不再交给 shell 解释执行;命令会先解析为受限参数列表并拒绝 shell 特殊语法,避免任务文本触发额外命令。
34
+ - 改进 Windows 下 Git Bash、npm 和集成测试的运行方式,减少环境识别错误与资源竞争导致的误失败。
35
+
36
+ ## [0.10.0] - 2026-07-12
37
+
38
+ ### 破坏性变更
39
+
40
+ - DAG、Loop、Delegate 和 Worker 统一使用 Pi,不再支持 Cursor executor 及相关旧配置。
41
+ - Cursor 仍可通过 `loop-agent cursor-prompt` 手动调用,但不再参与自动执行和受治理写入。
42
+ - Delegate 默认只创建 worktree;需要自动生成并执行 DAG 时必须显式使用 `--auto-run`。
43
+
44
+ ### 迁移提示
45
+
46
+ 1. 删除 harness 和 task 中的 Cursor executor 配置,只保留 `executors.pi`。
47
+ 2. 把 `loopAutoWritePolicy` 改为 `loopAutoExecutionPolicy`(`off` | `approval-required` | `enabled`)。
48
+ 3. 重新运行 `dag run-task` 并使用 `dag validate` 校验 DAG。
49
+ 4. 需要 Cursor 人工辅助时使用 `loop-agent cursor-prompt`,完成后仍需运行项目验证命令。
50
+
51
+ ### 新增
52
+
53
+ - `agent-worker feature review` 可汇总 Feature 状态、阻塞、验收覆盖、证据和下一步;`--json` 可供脚本读取。
54
+ - `agent-worker feature run` 可检查并推进一个就绪任务,`--dry-run` 可在不写入的情况下预览执行结果。
55
+ - 新增失败接续流程,可根据失败类型生成修复任务或人工行动建议,并在批准前保留原始失败证据。
56
+ - `feature run --git-mode checkpoint` 可为成功任务创建本地检查点,并在任务失败后恢复干净工作区;不会自动 push、merge 或创建远程 PR。
57
+ - 新增 `feature verify-final`、`feature delivery` 和 `feature closeout`,覆盖最终验证、交付材料和显式确认后的收尾操作。
58
+ - 晨报、Observe 和 `report metrics` 会集中展示 Feature 状态、下一步、验收覆盖和统计口径。
59
+ - 初始化演化检查可以复用仍然有效的历史审查结果,减少低影响后续改动造成的重复评审。
20
60
 
21
61
  ### 修改
22
62
 
23
- - 根目录 `design/` 已并入 `docs/design/`,视觉参考与产品线设计笔记现在统一从治理文档目录查找,相关索引和引用已同步更新。
24
- - Agent DAG Pi/Cursor 节点现在默认使用简体中文输出说明、分析、报告和文档;可通过 `workflowPolicy.dag.outputLanguage: "en"` 切换英文,代码、命令、路径、JSON 字段和固定协议 token 不会被翻译。
25
- - Dashboard 将“运行活性”调整为更直观的“执行器状态”,并明确区分执行器正常、心跳中断、已经退出、其他主机运行以及旧记录没有心跳等情况。
26
- - 修复 Dashboard 综合 DAG 状态使用中文文案后丢失徽章颜色的问题;完成、失败、暂停、中断和任务已另行完成现在恢复对应的语义颜色。
27
- - Dashboard 节点耗时达到 60 秒后改为按“分钟 + 秒”显示,例如 `2min 5s`,长任务更容易快速阅读。
28
- - Dashboard 的 DAG 节点模型列现在会显示 Pi/Cursor 节点实际路由到的模型;历史运行从 `run.json` 模型矩阵推导,新运行会直接把解析后的模型写入节点状态,Shell/Static 节点仍显示 `-`。
29
- - Dashboard 现在优先展示由生命周期、原始状态和运行活性共同判定的 DAG 当前状态,并单独保留原始记录;新增 `dag reconcile-run`,可在确认执行器已停止后将历史失联 DAG 显式标记为“任务已另行完成”或“已放弃”,同时保存收口前证据。
30
- - Observe DAG 详情页主信息区精简为单一“状态”,已结束 DAG 不再展示执行器心跳等无意义内部维度,状态一致或不允许恢复/收口时也不再显示“一致”或“否”;不一致、可恢复或可收口的警告与操作能力仍在主视图可见,原始状态、生命周期、活性、状态一致性与恢复资格折叠在“诊断信息”中保留。
31
- - DAG 运行现在记录本机执行器 PID、主机和持续心跳;`dag status` / `dag doctor` 可区分活跃、节点长时间无活动、心跳停滞、执行器已退出和远端状态未知,Observe 也不会再把已知孤儿或 paused 运行计为活跃 DAG。
32
- - 节点检查器支持拖动左边缘调整宽度,长 Markdown 表格和输出更容易查看;点击外部空白区域可平滑收起面板。
33
- - 执行过程改为更清晰的事件轨道:工具调用、AI 回复和 Agent 生命周期更容易区分;没有时间记录时会按采集顺序展示,连续协议事件会自动合并,减少无关噪声。
34
- - Observe 风险区拆为“需处理 DAG”与“Worker 风险”两个子块;DAG 按运行去重,不会因同一运行同时存在多个异常信号而重复计数,也不会让历史失败记录长期占用当前风险;Snapshot 投影失败不再静默显示为全零健康状态,而是返回安全错误摘要并在总览提示“指标暂不可用”,不含堆栈或敏感信息。
35
- - 修复旧版(未写 runner 心跳元数据)的运行中 DAG 被 Observe 误判为不活跃的问题:`effectiveStatus=unknown` 只表示活性证据不足,不再覆盖 `lifecycle=active` 且原始 `status` 为 `running`/`pending` 的运行事实,也不再掩盖存在 RUNNING/PENDING 节点的运行。服务端健康计数(活跃运行、执行中节点、等待节点)与前端进行中 DAG 列表现在使用一致的判定语义;`paused`、`terminal`、`stale`、`orphaned` 等明确非活跃事实仍优先于原始 `running`。
36
- - `npm test` 会先运行可并行的纯测试,再串行运行会启动 CLI 或子进程的集成测试。纯测试会根据机器可用并行度自动选择 1 至 4 个 Worker,低配和高配环境都能在稳定性与速度之间取得更合适的平衡。
63
+ - `design/` 已并入 `docs/design/`,设计资料统一从治理文档目录查找。
64
+ - Agent DAG 默认使用简体中文输出;可通过 `workflowPolicy.dag.outputLanguage: "en"` 切换为英文。
65
+ - Observe 和 Dashboard 更集中地展示运行状态、风险、模型、耗时和下一步,并减少已经结束任务中的无关诊断信息。
66
+ - 新增 `dag reconcile-run`,可在执行器已经停止后安全收尾历史失联的 DAG
67
+ - DAG 详情的节点检查器、事件记录和风险区域更易阅读,长内容和异常状态也能得到清楚提示。
68
+ - 测试会根据机器资源安排并行和串行任务,降低资源竞争造成的不稳定。
69
+
70
+ ### 修复
71
+
72
+ - 修复 `cursor-prompt --stream` 超时或异常后可能残留连接或进程的问题。
73
+ - 修复部分运行中 DAG 被误判为不活跃、状态颜色丢失以及风险统计重复的问题。
74
+ - 运行快照暂时无法生成时会明确提示指标不可用,不再显示具有误导性的全零状态。
37
75
 
38
76
  ## [0.9.0] - 2026-07-12
39
77
 
@@ -155,6 +193,8 @@
155
193
 
156
194
  ### 新增
157
195
 
196
+ - 新增 `frontend-implementation` 任务类型与专用 Agent DAG 模板,支持前端 contract / scout / design gate / implement / static verify / behavior verify / review gate / closeout 节点链,并附带 repo-local `frontend-implementation` skill 骨架。
197
+ - 补齐前端 DAG 的 repo-local skills:前端实现、design gate review、实现 review 和 verification closeout,并纳入 npm package / `loop-agent init --profile full` 初始化投影。
158
198
  - `loop-agent init` 支持检查和更新已初始化项目,可提示缺失文件、过期配置和需要人工确认的变更。
159
199
  - 新增 `--version`,可直接查看当前安装的 loop-agent 版本。
160
200
  - 初始化内容和 npm 包内容会进行一致性检查,减少“本仓库可用、初始化项目缺文件”的情况。
@@ -173,6 +213,8 @@
173
213
 
174
214
  ### 修复
175
215
 
216
+ - 前端 DAG 的 static / behavior shell 验证会优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令,避免被通用 adapter 验证命令覆盖。
217
+ - 前端 DAG 节点不再默认注入通用 DAG role skills,改为只加载节点显式声明的前端 skills,避免前端 skill references 被上下文预算挤出。
176
218
  - 修复完整测试运行时,部分真实命令可能因默认超时时间过短而失败的问题。
177
219
 
178
220
  ## [0.2.0] - 2026-07-05
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  `loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG,并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
4
4
 
5
- 它可以作为任意目标项目的稳定控制器:初始化目标项目后,项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引,使 agent 在目标项目里的工作体验尽量与本仓库对齐。
5
+ 它可以作为任意目标项目的稳定控制器:初始化目标项目后,项目会获得 `.agents/skills/`、`ai_workspace/loop-agent/` 治理资料、验证脚本、任务运行态目录和模型执行指引,使 agent 在目标项目里的工作体验尽量与本仓库对齐。
6
6
 
7
7
  ## 快速开始
8
8
 
@@ -20,6 +20,22 @@ loop-agent --version
20
20
  loop-agent --help
21
21
  ```
22
22
 
23
+ ## 自动更新提醒
24
+
25
+ 通过 npm 全局安装的 `loop-agent` 会在普通交互式命令成功结束后检查 `@tea-agent/loop-agent` 是否有新版本。提醒只写入 `stderr`,不会污染命令原本的 `stdout`;失败命令、CI、管道/重定向、`--help`、`--version`、JSON/Markdown 输出以及 DAG/Loop/Delegate/Pi/Cursor 等 controller-sensitive 路径都会跳过。
26
+
27
+ 如果你拒绝版本 A,当前系统用户下不会再提醒 A;之后发布版本 B 时会继续提醒。确认更新时,CLI 会先证明当前安装来自同一 npm global root,然后安装刚确认的精确版本,例如:
28
+
29
+ ```bash
30
+ npm install -g @tea-agent/loop-agent@0.12.0
31
+ ```
32
+
33
+ 需要完全关闭自动检查时设置:
34
+
35
+ ```bash
36
+ LOOP_AGENT_DISABLE_UPDATE_CHECK=1
37
+ ```
38
+
23
39
  检查当前项目的 loop-agent 配置:
24
40
 
25
41
  ```bash
@@ -38,7 +54,7 @@ loop-agent inspect
38
54
 
39
55
  然后运行 `loop-agent init instructions --repo-root .`,按指引使用 full + merge 初始化。需要选择 provider/model,或涉及凭据、成本、部署副作用时先问我;其他能安全默认的选项直接继续。
40
56
 
41
- 初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录,补全根 README 的项目概览、技术栈/目录结构、开发与验证命令,并同步更新 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
57
+ 初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录,补全根 README 的项目概览、技术栈/目录结构、开发与验证命令,并同步更新 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
42
58
 
43
59
  最后运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .`、`bash scripts/check-repo.sh`,如项目测试入口可识别也运行 `bash scripts/ci-tests.sh` 或 `bash scripts/ci.sh`,并汇报结果、假设和剩余风险。
44
60
  ```
@@ -51,7 +67,7 @@ loop-agent init --repo-root <target-repo> --profile full --merge
51
67
  loop-agent init doctor --repo-root <target-repo>
52
68
  ```
53
69
 
54
- `init instructions` 会输出给模型/Agent 执行完整初始化的指引包,不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 `docs/`,复制 repo-local `skills/` 并同步镜像到 `.agents/skills/`(agent 兼容路径,如 OpenCode 自动发现),生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档、`harness.json` IDE schema 指引和 `.harness/` 骨架;已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block(`# LOOP_AGENT_INIT_START/END`),把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等个人/会话运行态事实忽略掉,同时保留 `.harness/prompts/` 和目录占位可共享,不会整目录忽略 `.harness/`,也不会覆盖用户已有的 ignore 规则。
70
+ `init instructions` 会输出给模型/Agent 执行完整初始化的指引包,不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 loop-agent 治理资料,生成语言无关的治理脚本矩阵、中文根 README 入口、`ai_workspace/loop-agent/` 目标项目治理资料、`.agents/skills/` repo-local skills、`harness.json` IDE schema 指引和 `.harness/` 骨架;不会在目标项目根目录生成 `skills/`,也不会把 loop-agent 生成的治理资料写到根 `docs/`。已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block(`# LOOP_AGENT_INIT_START/END`),把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等个人/会话运行态事实忽略掉,同时保留 `.harness/prompts/` 和目录占位可共享,不会整目录忽略 `.harness/`,也不会覆盖用户已有的 ignore 规则。
55
71
 
56
72
  新初始化会写入 `.harness/init-surface.json`,记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目,可以用下面的维护入口对齐新版本初始化能力:
57
73
 
@@ -64,7 +80,7 @@ loop-agent init update --repo-root <target-repo> --apply-safe
64
80
 
65
81
  `check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。`update --bootstrap-surface` 为旧项目补 inferred baseline;`update --apply-safe` 只补缺失文件、目录和 managed block(包括过期的 `.gitignore` managed block),不覆盖已有但无法确认来源的本地文件。
66
82
 
67
- 当初始化由模型/Agent 执行时,它应把初始化当成一个自动化闭环:确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后,运行 deterministic init,随后立刻读取目标项目真实文件,补全根 README 的项目概览、技术栈/目录结构、开发与验证命令,并同步适配 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
83
+ 当初始化由模型/Agent 执行时,它应把初始化当成一个自动化闭环:确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后,运行 deterministic init,随后立刻读取目标项目真实文件,补全根 README 的项目概览、技术栈/目录结构、开发与验证命令,并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
68
84
 
69
85
  初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口,只运行实际存在且工具可用的命令;探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
70
86
 
@@ -79,8 +95,20 @@ loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --st
79
95
  loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
80
96
  ```
81
97
 
98
+ 当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板;例如 `frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链。
99
+
82
100
  `<temp-dir>` 表示平台原生临时目录;也可以省略 `--output`,再使用命令 JSON 输出里的 `outputPath`。
83
101
 
102
+ 非微小工作需要 exec-plan 时,使用确定性生命周期命令维护计划与索引;`new-task` 不会自动创建计划:
103
+
104
+ ```bash
105
+ loop-agent plan create <plan-id> "<title>"
106
+ loop-agent plan check
107
+ loop-agent plan complete <plan-id> --summary "<summary>"
108
+ ```
109
+
110
+ `plan create` 优先复用目标项目模板并回退到发布包内置模板,create/complete 失败时会回滚多文件修改。`dag run-task` 在生成 DAG 草稿前运行同源索引检查,避免遗漏登记直到末端 verify 才暴露。
111
+
84
112
  一次性只读评审或有边界写入:
85
113
 
86
114
  ```bash
@@ -103,6 +131,19 @@ agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id
103
131
  bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
104
132
  ```
105
133
 
134
+ 写入型 Worker 入口会在目标仓库写入前解析并冻结实际启动的 `loop-agent` controller identity。自举或其他需要精确版本约束的批次,可以额外传入:
135
+
136
+ ```bash
137
+ agent-worker feature run \
138
+ --feature-dir <feature-dir> \
139
+ --repo <target-repo> \
140
+ --loop-agent-bin <published-loop-agent-entry> \
141
+ --expected-controller-version <version> \
142
+ --expected-controller-fingerprint <sha256:value>
143
+ ```
144
+
145
+ identity 不只包含 semver,还包含绝对 launch spec、入口 SHA-256,以及覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable package fingerprint。校验失败时会在 materialize、Task Pool `Running` 或其他目标仓库写入前停止,并保留实际 identity 供诊断。
146
+
106
147
  `feature review` 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动;默认输出简洁人类摘要,`--json` 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。
107
148
 
108
149
  `feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec,执行独立、不会 promote/closeout 或移动 HEAD 的最终验证,并原子投影 canonical QA aggregate 与 HEAD-bound final-verification evidence。`feature delivery` 复用 checkpoint transaction,校验 branch/HEAD/clean、commit trailers、changed files、成功 run、QA、最终验证和 required AC 后,在 `.harness/task-pool/` 原子生成 Delivery manifest、Acceptance Coverage 与 `PR.md`;`--dry-run` 零写入。`feature closeout` 默认只预览 gates;显式 `--apply --owner <owner>` 才会在前后校验与整体回滚保护下写入 Feature Closeout,重复相同 facts 会幂等复用。
@@ -124,19 +165,39 @@ nightly wrapper 按 feature 互斥,保留批次/超时退出码,并输出 mo
124
165
  - **Agent DAG**:把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
125
166
  - **`.harness/`**:记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
126
167
  - **`harness.json`**:描述项目名、治理根目录、模型路由、executor 和验证脚本;`docs/templates/harness.schema.json` 为 IDE 提供补全和字段说明,运行时仍由 Zod schema 校验。
127
- - **repo-local skills**:目标项目本地的 `skills/`(loop-agent 主路径)优先于发布包内置 skills,便于项目定制 agent 行为;`init --profile full` 还会把同一份 skills 镜像到 `.agents/skills/`,让外部 agent(如 OpenCode)也能自动发现。DAG skill 解析顺序为:用户配置目录 → `skills/` → `.agents/skills/` → 发布包内置。
168
+ - **repo-local skills**:目标项目本地 skills 统一放在 `.agents/skills/`,便于项目定制 agent 行为并让外部 agent 自动发现。DAG skill 解析顺序为:用户配置目录 → `.agents/skills/` → 发布包内置 `skills/`。
169
+ - **可选 SDD skill 嵌入**:如果目标项目在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`,`dag run-task` 会把它们作为知识与方法补充追加到对应的 Contract、Plan、Implement/Repair、Verify、Review 节点。loop-agent 仍控制 DAG、状态、写入边界、验证和收口;不会自动运行 SDD 初始化/扫描 skill,也不会推进 `ai_workspace` 状态或归档。没有这些 repo-local skills 时,生成结果保持原有默认流程。
170
+ - **run-owned skill snapshot**:新 DAG run 会在任何节点执行前,把本次实际注入 prompt 的 resolved skill profiles 冻结到 run 自己的 `.runtime/skill-snapshot.json`。后续节点、dynamic child、approve/resume 都使用同一份 hash-anchored snapshot;run 内修改 skill 只会从下一次 run 生效。
171
+ - **controller identity**:`agent-worker` 把一次 Feature/batch 实际使用的发布包、入口、启动参数和 package 内容 fingerprint 固定下来,并把 identity 传播到 Worker、Task Pool、batch/Feature 与最终验证证据。
172
+ - **`agent-worker` operator skill**:`skills/agent-worker/` 只负责 Feature Packet、TaskSpec、Task Pool、自举 release train 和失败恢复的外层路由;单个 DAG 实现、DAG kernel 修复和节点执行仍由 `loop-agent` 负责,该 skill 不进入默认 DAG role skills。
128
173
  - **治理文档**:`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
129
174
  - **shell verification**:完成声明必须有可复现命令作为依据,而不是只靠聊天结论。
130
175
 
131
176
  这些治理原则的设计思想吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践:人类掌舵,智能体执行;仓库作为记录系统;任务小步推进;用结构化 handoff 与可复现验证跨 session 保持连续性。背景资料收录在 `website/docs/practices/`。
132
177
 
178
+ ## 仓库地图
179
+
180
+ 本仓库按职责分区;更细的开工协议与会话规则见 `AGENTS.md`,治理索引见 `docs/README.md`。
181
+
182
+ | 路径 | 职责 |
183
+ |---|---|
184
+ | `bin/`、`src/` | CLI 入口与运行时代码 |
185
+ | `skills/` | repo-local skill 指令与 references |
186
+ | `.harness/` | task、DAG run、cache、live state 等运行态事实 |
187
+ | `docs/` | 长期治理文档、计划、报告与模板 |
188
+ | `website/` | 面向使用者的文档站 |
189
+ | `scripts/`、`test/` | 验证脚本与测试套件 |
190
+ | `examples/` | 可复制 DAG 示例(默认不投影到目标项目) |
191
+ | `features/`、`dogfood/` | 样板 Feature Packet 与 dogfood 样本(本仓库维护用) |
192
+ | `harness.json`、`AGENTS.md`、`CONTEXT.md` | 项目配置、agent 开工地图与术语表 |
193
+
133
194
  ## 能力概览
134
195
 
135
196
  - 生成、校验、执行和汇总 Agent DAG。
136
197
  - 从任务说明生成标准 DAG,并按依赖顺序运行规划、实现、验证和收口节点。
137
198
  - 维护 `loop` 长程任务状态,包括目标、轮次、信号、验证事实和收口草稿。
138
- - 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
139
- - 保留 Cursor executor 作为显式启用的可选后端。
199
+ - 通过 Pi executor 执行只读规划、评审、诊断和有边界写入(唯一受治理 Agent writer)。
200
+ - 保留 `cursor-prompt` 作为显式、手工触发的 one-shot sidecar(不是受治理 DAG/Loop writer)。
140
201
  - 通过 shell executor 运行确定性的验证命令。
141
202
  - 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
142
203
 
@@ -152,7 +213,7 @@ loop-agent examples copy example-dag.json --repo-root <target-repo>
152
213
 
153
214
  ## 迭代本仓库
154
215
 
155
- 如果要用 loop-agent 迭代 loop-agent 本仓库,控制器必须来自已发布的 npm 安装包。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器;首次安装或有意升级可用 `@latest`,但一次自举任务启动后不要在任务中途升级控制器。
216
+ 如果要用 loop-agent 迭代 loop-agent 本仓库,发布版本 N 必须作为整个维护批次的固定 controller,候选版本 N+1 只能在隔离安装槽中接受接棒验证。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为 controller;首次安装或有意升级可用 `@latest`,但一次自举任务启动后不要中途升级或重新通过 PATH 解析入口。
156
217
 
157
218
  ```bash
158
219
  npm install -g @tea-agent/loop-agent@latest
@@ -161,7 +222,17 @@ loop-agent doctor
161
222
  loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
162
223
  ```
163
224
 
164
- `@latest` 只用于安装或升级,不要在 DAG 节点里反复用 `npx @latest` 拉取。自举任务应记录 `npm list -g` 显示的实际版本号。
225
+ `@latest` 只用于安装或升级,不要在 DAG 节点里反复用 `npx @latest` 拉取。自举证据应记录 controller version、portable package fingerprint、候选 commit/tarball hash 和失败 run;semver 相同并不代表 package 内容相同。
226
+
227
+ 源码仓库提供 repo-maintainer deterministic takeover canary。它打包候选、安装到临时隔离 slot,由维护脚本独立计算 canonical package fingerprint 并与候选实现交叉核对,再通过候选包内两个绝对入口执行 full init、doctor、inspect、docs audit、目标项目治理检查、Feature validation/dry-run 和一个只含 static/shell executor 的小型 DAG;所有子进程都有硬超时,PATH trap 证明没有回退全局 `loop-agent` / `agent-worker` 命令,run evidence 则证明没有观察到 Pi/model executor:
228
+
229
+ ```bash
230
+ npm run self-host:canary -- --deterministic --output <evidence.json>
231
+ # 或验证已经构建好的候选 tarball
232
+ npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
233
+ ```
234
+
235
+ 该脚本属于源码仓库维护入口,不进入发布包的 `files` surface;`--live` 当前明确拒绝执行。deterministic canary 证明候选包和 static/shell runtime 能接棒,但不会调度 Pi executor,也不承担 Pi skill source 解析证明;run-owned skill snapshot 的候选包解析由 snapshot 定向测试和真实 DAG 证据单独证明。
165
236
 
166
237
  ## 文档导航
167
238
 
@@ -205,11 +276,11 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
205
276
 
206
277
  ## 发布包内容
207
278
 
208
- 发布包包含静态运行和指导资料:`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
279
+ 发布包包含静态运行和指导资料:`bin/`、`dist/`、`skills/`(包括 `loop-agent` 与可选的 `agent-worker` operator skill)、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
209
280
 
210
281
  `docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实;npm 包只携带这些目录的 README,不携带本仓库已有历史记录。
211
282
 
212
- DAG skill 指令优先从目标项目或用户配置目录解析;目标项目未提供本地 `skills/` 时,CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。
283
+ DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析;目标项目未提供本地 skill 时,CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
213
284
 
214
285
  ## 发布前检查
215
286
 
@@ -16,12 +16,11 @@ function parseMaxConcurrent(value) {
16
16
  }
17
17
  export function parseDagRunTaskArgs(args, defaultCwd) {
18
18
  if (args.length === 0) {
19
- throw new Error("usage: dag run-task <task-id> [--output <path>] [--profile auto|minimal|standard|reviewed|supervised] [--strict-models] [--no-cursor] [--execute] [--init-only] [--dry-run] [--cwd <dir>] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
19
+ throw new Error("usage: dag run-task <task-id> [--output <path>] [--profile auto|minimal|standard|reviewed|supervised] [--strict-models] [--execute] [--init-only] [--dry-run] [--cwd <dir>] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
20
20
  }
21
21
  let taskId;
22
22
  let outputPath;
23
23
  let strictModels = false;
24
- let noCursor = false;
25
24
  let execute = false;
26
25
  let initOnly = false;
27
26
  let dryRun = false;
@@ -50,10 +49,6 @@ export function parseDagRunTaskArgs(args, defaultCwd) {
50
49
  strictModels = true;
51
50
  continue;
52
51
  }
53
- if (arg === "--no-cursor") {
54
- noCursor = true;
55
- continue;
56
- }
57
52
  if (arg === "--execute") {
58
53
  execute = true;
59
54
  continue;
@@ -135,7 +130,6 @@ export function parseDagRunTaskArgs(args, defaultCwd) {
135
130
  taskId,
136
131
  outputPath: outputPath ? path.resolve(outputPath) : undefined,
137
132
  strictModels,
138
- noCursor,
139
133
  execute,
140
134
  initOnly,
141
135
  dryRun,
@@ -257,7 +251,6 @@ export function parseRunDagArgs(args, defaultCwd) {
257
251
  let dryRun = false;
258
252
  let maxConcurrent;
259
253
  let runId;
260
- let noCursor = false;
261
254
  let canvasPath;
262
255
  let canvasName;
263
256
  let canvasesDir;
@@ -288,9 +281,6 @@ export function parseRunDagArgs(args, defaultCwd) {
288
281
  else if (arg === "--run-id") {
289
282
  runId = args[++i];
290
283
  }
291
- else if (arg === "--no-cursor") {
292
- noCursor = true;
293
- }
294
284
  else if (arg === "--canvas-path") {
295
285
  canvasPath = args[++i];
296
286
  }
@@ -335,7 +325,6 @@ export function parseRunDagArgs(args, defaultCwd) {
335
325
  dryRun,
336
326
  maxConcurrent,
337
327
  runId,
338
- noCursor,
339
328
  canvasPath,
340
329
  canvasName,
341
330
  canvasesDir,
@@ -4,7 +4,9 @@ import { resolveShellCommands } from "../../executors/shell-executor.js";
4
4
  import { parseDagSpec } from "../../workflows/dag/types.js";
5
5
  import { pathMatchesPattern } from "../../shared/git-progress.js";
6
6
  import { loadHarnessManifest } from "../../governance/harness.js";
7
+ import { assertExecPlanIndexConsistent } from "../../governance/exec-plans.js";
7
8
  import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
9
+ import { loadTaskConfig } from "../../task/runtime.js";
8
10
  import { validateDagUseCase } from "./validate-dag.js";
9
11
  import { runDagUseCase } from "./run-dag.js";
10
12
  const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
@@ -14,7 +16,7 @@ function buildValidateInput(repoRoot, dagPath, parsed) {
14
16
  dagPath,
15
17
  strictModelMatrix: parsed.strictModels,
16
18
  strictGovernance: false,
17
- forbidExecutors: parsed.noCursor ? ["cursor"] : [],
19
+ forbidExecutors: [],
18
20
  };
19
21
  }
20
22
  function shouldRunExecution(parsed) {
@@ -196,6 +198,12 @@ async function resolveProfileRouting(repoRoot, parsed, candidateProfile) {
196
198
  }
197
199
  export async function generateTaskDagUseCase(input) {
198
200
  const { repoRoot, ...parsed } = input;
201
+ // Deterministic exec-plan preflight: fail closed on real index drift
202
+ // before any expensive DAG generation or execution. Empty/consistent
203
+ // repos stay compatible so the default DAG flow is unblocked.
204
+ await assertExecPlanIndexConsistent(repoRoot);
205
+ const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
206
+ const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
199
207
  const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
200
208
  outputPath: parsed.outputPath,
201
209
  template: "standard-dag",
@@ -208,6 +216,20 @@ export async function generateTaskDagUseCase(input) {
208
216
  codeChange: [],
209
217
  reasons: ["dag run-task validate did not report governanceProfile"],
210
218
  });
219
+ if (isFrontendImplementationTask) {
220
+ profileRouting.selectedTemplate = "frontend-implementation";
221
+ profileRouting.source = "taskKind";
222
+ profileRouting.routingReasons = [
223
+ 'taskKind "frontend-implementation" selects the dedicated frontend DAG template',
224
+ ];
225
+ if (parsed.profile === "auto") {
226
+ profileRouting.selectedByProfile =
227
+ resolveAutoRoutingProfile(profileRouting.candidateProfile);
228
+ }
229
+ else if (parsed.profileExplicit) {
230
+ profileRouting.selectedByProfile = parsed.profile;
231
+ }
232
+ }
211
233
  const initResult = profileRouting.selectedTemplate === "standard-dag"
212
234
  ? candidateResult
213
235
  : await initHybridDagFromTask(repoRoot, parsed.taskId, {
@@ -258,7 +280,6 @@ export async function generateTaskDagUseCase(input) {
258
280
  dryRun: parsed.dryRun,
259
281
  maxConcurrent: parsed.maxConcurrent,
260
282
  runId: parsed.runId,
261
- noCursor: parsed.noCursor,
262
283
  canvasPath: parsed.canvasPath,
263
284
  canvasName: parsed.canvasName,
264
285
  canvasesDir: parsed.canvasesDir,
@@ -1,30 +1,8 @@
1
- import { readFile } from "node:fs/promises";
2
1
  import { createDagEventObserver } from "../../workflows/dag/event-observer.js";
3
2
  import { composeDagRunObservers } from "../../workflows/dag/observer-compose.js";
4
3
  import { createDagCanvasObserver, resolveCanvasPath, } from "../../workflows/dag/canvas-observer.js";
5
4
  import { loadDagSpecFromFile, runDag } from "../../workflows/dag/runner.js";
6
- import { assertValidDagSpec, collectForbiddenExecutorIssues, } from "../../workflows/dag/validate.js";
7
- async function loadRawTaskExecutorMap(dagPath) {
8
- const raw = JSON.parse(await readFile(dagPath, "utf-8"));
9
- const map = new Map();
10
- for (const task of raw.tasks ?? []) {
11
- if (typeof task.id === "string")
12
- map.set(task.id, task.executor);
13
- }
14
- return map;
15
- }
16
- function assertNoCursorTasks(spec, rawTaskExecutors) {
17
- const issues = collectForbiddenExecutorIssues(spec, ["cursor"]);
18
- if (issues.length === 0)
19
- return;
20
- const details = issues
21
- .map((issue) => {
22
- const implicitDefault = rawTaskExecutors.get(issue.taskId) === undefined;
23
- return `task=${issue.taskId}${implicitDefault ? " (implicit cursor default)" : ""}`;
24
- })
25
- .join("; ");
26
- throw new Error(`--no-cursor forbids cursor executor tasks: ${details}`);
27
- }
5
+ import { assertValidDagSpec } from "../../workflows/dag/validate.js";
28
6
  function getCanvasFlushErrorMessage(error) {
29
7
  return error instanceof Error ? error.message : String(error);
30
8
  }
@@ -50,10 +28,6 @@ function buildRunDagNextSteps(runId) {
50
28
  }
51
29
  export async function runDagUseCase(input) {
52
30
  const spec = await loadDagSpecFromFile(input.dagPath);
53
- if (input.noCursor) {
54
- const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
55
- assertNoCursorTasks(spec, rawTaskExecutors);
56
- }
57
31
  assertValidDagSpec(spec);
58
32
  const resolvedCanvasPath = resolveCanvasPath({
59
33
  canvasPath: input.canvasPath,
@@ -51,7 +51,7 @@ async function loadRawTaskExecutorMap(dagPath) {
51
51
  return map;
52
52
  }
53
53
  function ensureNoForbiddenExecutors(spec, forbidExecutors, rawTaskExecutors) {
54
- const supported = new Set(["cursor", "pi", "shell", "static"]);
54
+ const supported = new Set(["pi", "shell", "static"]);
55
55
  const normalized = forbidExecutors.map((executor) => {
56
56
  if (!supported.has(executor)) {
57
57
  throw new Error(`unsupported executor for --forbid-executor: ${executor}`);
@@ -72,7 +72,7 @@ function ensureNoForbiddenExecutors(spec, forbidExecutors, rawTaskExecutors) {
72
72
  async function ensureStrictSkillResolution(spec, repoRoot) {
73
73
  const failures = [];
74
74
  for (const task of spec.tasks) {
75
- if (task.executor !== "pi" && task.executor !== "cursor")
75
+ if (task.executor !== "pi")
76
76
  continue;
77
77
  const skills = resolveDagNodeSkills(spec, task);
78
78
  if (skills.length === 0)
@@ -1,4 +1,3 @@
1
- import { runLoopCursorFix } from "../../workflows/loop/actions/cursor-fix.js";
2
1
  import { runLoopDagAction } from "../../workflows/loop/actions/dag-action.js";
3
2
  import { runLoopPiReview } from "../../workflows/loop/actions/pi-review.js";
4
3
  import { runLoopShellVerification, } from "../../workflows/loop/actions/shell-verify.js";
@@ -10,9 +9,6 @@ export async function runLoopAction(input) {
10
9
  if (input.action === "pi-review") {
11
10
  return runLoopPiReview(input.repoRoot, input.taskId, input.options);
12
11
  }
13
- if (input.action === "cursor-fix") {
14
- return runLoopCursorFix(input.repoRoot, input.taskId, input.options);
15
- }
16
12
  if (input.action === "dag") {
17
13
  return runLoopDagAction(input.repoRoot, input.taskId, input.options);
18
14
  }