@tea-agent/loop-agent 0.35.1-beta.0 → 0.35.1-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/AGENTS.md +110 -108
  2. package/CHANGELOG.md +24 -26
  3. package/README.md +165 -165
  4. package/bin/agent-worker.js +0 -0
  5. package/bin/loop-agent.js +57 -21
  6. package/dist/application/task-lifecycle/advance.js +0 -1
  7. package/dist/build-stamp.json +6 -0
  8. package/dist/cli/program.js +2 -2
  9. package/dist/commands/cursor-prompt.js +6 -6
  10. package/dist/commands/init-upgrade.js +19 -351
  11. package/dist/commands/init.js +67 -14
  12. package/dist/commands/loop-benchmark.js +11 -11
  13. package/dist/commands/pi-reuse-benchmark.js +16 -16
  14. package/dist/commands/run-dag-progress.js +0 -14
  15. package/dist/commands/task-advance.js +3 -33
  16. package/dist/executors/dag-pi-executor.js +44 -0
  17. package/dist/shared/operator/capabilities.js +1 -38
  18. package/dist/shared/package-metadata.js +42 -0
  19. package/dist/sidecars/cursor-prompt/executor.js +1 -1
  20. package/dist/worker/console/chat/pi-runtime.js +25 -41
  21. package/dist/worker/console/chat/routes.js +4 -27
  22. package/dist/worker/console/operation-runner.js +0 -24
  23. package/dist/worker/console/operator-actions.js +0 -58
  24. package/dist/worker/console/static/assets/index-CvsQgALl.js +56 -0
  25. package/dist/worker/console/static/assets/{index-Dups4sSM.css → index-hJqCPs_g.css} +1 -1
  26. package/dist/worker/console/static/index.html +2 -2
  27. package/dist/worker/console/static-src/app/useRecoveryConsole.js +5 -0
  28. package/dist/worker/console/static-src/operator-chat/useChatSessions.js +2 -13
  29. package/dist/worker/console/static-src/operator-chat/useComposer.js +7 -30
  30. package/dist/worker/loop-agent/loop-agent-client.js +17 -3
  31. package/dist/worker/observability/read-model.js +20 -0
  32. package/dist/worker/observe/static/copy.js +67 -67
  33. package/dist/worker/observe/static/dag-layout.d.ts +36 -36
  34. package/dist/worker/observe/static/dom.js +220 -220
  35. package/dist/worker/observe/static/relations.js +133 -133
  36. package/dist/worker/observe/static/run-processing.js +148 -148
  37. package/dist/worker/observe/static/views/batch.js +227 -227
  38. package/dist/worker/observe/static/views/failures.js +143 -143
  39. package/dist/worker/observe/static/views/feature.js +492 -492
  40. package/dist/worker/observe/static/views/run.js +453 -453
  41. package/dist/worker/observe/static/views/shell.js +7 -7
  42. package/dist/worker/observe/static/views/timeline.js +163 -163
  43. package/dist/worker/preflight.js +2 -1
  44. package/dist/workflows/dag/backend-test-scenario-param.js +33 -23
  45. package/dist/workflows/dag/canvas-observer.js +275 -275
  46. package/dist/workflows/dag/contract-output-registry.js +14 -0
  47. package/dist/workflows/dag/contract-validator-registrations.js +8 -0
  48. package/dist/workflows/dag/dynamic-runtime/shared.js +9 -1
  49. package/dist/workflows/dag/frontend-implementation-contract.js +233 -39
  50. package/dist/workflows/dag/frontend-prewrite-gate.js +364 -61
  51. package/dist/workflows/dag/frontend-recovery-plan.js +73 -0
  52. package/dist/workflows/dag/frontend-recovery-root-manifest.js +123 -0
  53. package/dist/workflows/dag/frontend-recovery-run.js +539 -0
  54. package/dist/workflows/dag/frontend-repair.js +219 -18
  55. package/dist/workflows/dag/frontend-verification-trace.js +47 -32
  56. package/dist/workflows/dag/frontend-writer-recovery.js +106 -0
  57. package/dist/workflows/dag/frontend-writer-rollback.js +821 -0
  58. package/dist/workflows/dag/init-hybrid.js +41 -24
  59. package/dist/workflows/dag/node-execution.js +89 -0
  60. package/dist/workflows/dag/recovery-recommendation.js +58 -0
  61. package/dist/workflows/dag/runner.js +245 -11
  62. package/dist/workflows/dag/scheduler.js +257 -3
  63. package/dist/workflows/dag/types.js +130 -2
  64. package/docs/architecture/evolution.md +73 -73
  65. package/docs/architecture/system-overview.md +100 -100
  66. package/docs/architecture/worker-and-feature.md +122 -122
  67. package/docs/skills/README.md +7 -7
  68. package/docs/templates/adr.md +60 -60
  69. package/docs/templates/agent-dag-authority-surface-audit.prompt.md +94 -94
  70. package/docs/templates/agent-dag-decision-envelope.schema.json +213 -213
  71. package/docs/templates/agent-dag-decision-gate.prompt.md +246 -246
  72. package/docs/templates/agent-dag-process-supervisor.prompt.md +98 -98
  73. package/docs/templates/agent-dag-report.schema.json +473 -473
  74. package/docs/templates/agent-dag-review-verdict.prompt.md +68 -68
  75. package/docs/templates/backend-test-result.schema.json +99 -99
  76. package/docs/templates/evaluation/agents-map-slim-v1.md +87 -87
  77. package/docs/templates/evaluation/agents-map-verbose-v0.md +153 -153
  78. package/docs/templates/feature-spec.md +53 -53
  79. package/docs/templates/frontend-design-contract.md +42 -42
  80. package/docs/templates/frontend-eval/fixtures/failures/01-type-build-error.md +17 -17
  81. package/docs/templates/frontend-eval/fixtures/failures/02-unit-component-test-fail.md +16 -16
  82. package/docs/templates/frontend-eval/fixtures/failures/03-fixture-schema-drift.md +16 -16
  83. package/docs/templates/frontend-eval/fixtures/failures/04-missing-loading-empty-error-state.md +16 -16
  84. package/docs/templates/frontend-eval/fixtures/failures/05-forbidden-write-writeset-expansion.md +16 -16
  85. package/docs/templates/frontend-eval/fixtures/failures/06-unapproved-dependency-add.md +16 -16
  86. package/docs/templates/frontend-eval/fixtures/failures/07-mock-production-on.md +21 -21
  87. package/docs/templates/frontend-eval/fixtures/functional/01-simple-component-style.md +29 -29
  88. package/docs/templates/frontend-eval/fixtures/functional/02-form-validation.md +28 -28
  89. package/docs/templates/frontend-eval/fixtures/functional/03-list-detail-page.md +28 -28
  90. package/docs/templates/frontend-eval/fixtures/functional/04-api-mock.md +29 -29
  91. package/docs/templates/frontend-eval/fixtures/functional/05-permission-auth-gated-ui.md +27 -27
  92. package/docs/templates/frontend-eval/fixtures/functional/06-ssr-server-client-boundary.md +28 -28
  93. package/docs/templates/frontend-eval/fixtures/functional/07-shared-public-component-api.md +28 -28
  94. package/docs/templates/frontend-eval/fixtures/functional/08-pure-local-no-remote.md +27 -27
  95. package/docs/templates/frontend-eval/metrics.md +138 -138
  96. package/docs/templates/frontend-eval/smoke-targets.md +53 -53
  97. package/docs/templates/frontend-task-constraints.md +35 -35
  98. package/docs/templates/frontend-task-requirement.md +70 -70
  99. package/docs/templates/init-evolution-review.md +35 -35
  100. package/docs/templates/init-managed-agents.md +154 -156
  101. package/docs/templates/interactive-ui-round2-experiment.md +66 -66
  102. package/docs/templates/knowledge-graph-bootstrap-dag.json +118 -118
  103. package/docs/templates/knowledge-sync-dag.json +178 -178
  104. package/docs/templates/knowledge-sync-draft.schema.json +71 -71
  105. package/docs/templates/product-line/closeout.yaml +9 -9
  106. package/docs/templates/product-line/design.md +13 -13
  107. package/docs/templates/product-line/links.md +10 -10
  108. package/docs/templates/product-line/requirement.md +17 -17
  109. package/docs/templates/product-line/test-plan.md +7 -7
  110. package/docs/templates/project-start-checklist.md +9 -9
  111. package/docs/templates/qa-report.md +48 -48
  112. package/docs/templates/sprint-contract.md +29 -29
  113. package/docs/templates/worker-dogfood-evidence.md +80 -80
  114. package/docs/templates/worker-dogfood-setup.md +68 -68
  115. package/harness.json +2 -5
  116. package/package.json +2 -2
  117. package/scripts/kb-bootstrap-init-skeleton.sh +0 -0
  118. package/scripts/kb-graph-incremental-prepare.mjs +0 -0
  119. package/scripts/kb-graph-materialize.mjs +105 -105
  120. package/scripts/kb-graph-promote.mjs +164 -164
  121. package/scripts/kb-query.mjs +554 -554
  122. package/skills/agent-worker/SKILL.md +48 -48
  123. package/skills/agent-worker/references/agent-worker-operator.md +159 -159
  124. package/skills/ai-engineering-context/SKILL.md +48 -48
  125. package/skills/analyze-product-dependencies/scripts/test-validators.mjs +0 -0
  126. package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs +0 -0
  127. package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs +0 -0
  128. package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs +0 -0
  129. package/skills/analyze-product-requirements/scripts/compute-source-identity.mjs +0 -0
  130. package/skills/analyze-product-requirements/scripts/test-validators.mjs +0 -0
  131. package/skills/analyze-product-requirements/scripts/validate-product-analysis.mjs +0 -0
  132. package/skills/analyze-product-requirements/scripts/validate-product-requirement.mjs +0 -0
  133. package/skills/analyze-product-requirements/scripts/validate-requirement-clarification.mjs +0 -0
  134. package/skills/browser-tools/browser-content.js +103 -103
  135. package/skills/browser-tools/browser-cookies.js +35 -35
  136. package/skills/browser-tools/browser-eval.js +53 -53
  137. package/skills/browser-tools/browser-hn-scraper.js +108 -108
  138. package/skills/browser-tools/browser-nav.js +44 -44
  139. package/skills/browser-tools/browser-pick.js +162 -162
  140. package/skills/browser-tools/browser-screenshot.js +34 -34
  141. package/skills/browser-tools/browser-start.js +86 -86
  142. package/skills/browser-tools/package-lock.json +2556 -2556
  143. package/skills/browser-tools/package.json +19 -19
  144. package/skills/code-review-core/SKILL.md +20 -20
  145. package/skills/codebase-scout/SKILL.md +19 -19
  146. package/skills/grill-me/SKILL.md +10 -10
  147. package/skills/local-jacoco-coverage/scripts/run-coverage-analysis.sh +0 -0
  148. package/skills/local-jacoco-coverage/scripts/start-jacoco-agent.sh +0 -0
  149. package/skills/loop-agent/SKILL.md +0 -1
  150. package/skills/loop-agent/references/command-reference.md +639 -641
  151. package/skills/loop-agent/references/docs-converge.md +126 -126
  152. package/skills/loop-agent/references/learned/README.md +21 -21
  153. package/skills/loop-agent/references/pi-prompt.md +23 -23
  154. package/skills/loop-agent/references/pi-subagent-assisted-mode.md +84 -84
  155. package/skills/playwright-cli/references/element-attributes.md +23 -23
  156. package/skills/playwright-cli/references/playwright-tests.md +39 -39
  157. package/skills/playwright-cli/references/request-mocking.md +87 -87
  158. package/skills/playwright-cli/references/running-code.md +241 -241
  159. package/skills/playwright-cli/references/session-management.md +225 -225
  160. package/skills/playwright-cli/references/storage-state.md +275 -275
  161. package/skills/playwright-cli/references/test-generation.md +433 -433
  162. package/skills/requesting-code-review/SKILL.md +101 -101
  163. package/skills/requesting-code-review/code-reviewer.md +168 -168
  164. package/skills/systematic-debugging/CREATION-LOG.md +119 -119
  165. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -158
  166. package/skills/systematic-debugging/condition-based-waiting.md +115 -115
  167. package/skills/systematic-debugging/defense-in-depth.md +122 -122
  168. package/skills/systematic-debugging/find-polluter.sh +63 -63
  169. package/skills/systematic-debugging/root-cause-tracing.md +169 -169
  170. package/skills/systematic-debugging/test-academic.md +14 -14
  171. package/skills/systematic-debugging/test-pressure-1.md +58 -58
  172. package/skills/systematic-debugging/test-pressure-2.md +68 -68
  173. package/skills/systematic-debugging/test-pressure-3.md +69 -69
  174. package/skills/using-git-worktrees/SKILL.md +215 -215
  175. package/skills/verification-before-completion/SKILL.md +154 -154
  176. package/skills/webapp-testing/SKILL.md +19 -19
  177. package/dist/worker/console/operation-wait.js +0 -241
  178. package/dist/worker/console/static/assets/index-SjjjZnV3.js +0 -56
  179. package/dist/worker/console/static-src/operator-chat/slash-palette-nav.js +0 -141
package/README.md CHANGED
@@ -1,165 +1,165 @@
1
- # loop-agent
2
-
3
- `loop-agent` 是面向 AI coding agent 的仓库级任务运行时与治理工具。它把研发任务组织为可审查、可执行、可恢复、可验证的 Agent DAG,并将任务源、写入边界、运行事实和完成证据保存在仓库中。
4
-
5
- 发布包提供两个 CLI:
6
-
7
- | CLI | 职责 |
8
- | --- | --- |
9
- | `loop-agent` | 单仓库任务、Agent DAG、验证、恢复与治理 |
10
- | `agent-worker` | 可选的 Feature、TaskSpec、Task Pool 与 Observe 外层编排 |
11
-
12
- 受治理的 Agent writer 只有 Pi;`cursor-prompt` 仅用于显式手工 one-shot,不进入 DAG 或 Loop 自动写入路径。
13
-
14
- ## 适合解决什么问题
15
-
16
- - 把模糊的 coding 请求转成有任务源、边界和验收标准的执行过程。
17
- - 在 Contract → Scout → Plan → Implement → Verify → Closeout 节点间保留可审查证据。
18
- - 用 `allowedPaths`、`forbiddenPaths` 和 DAG `writeSet` 限制模型写入。
19
- - 在中断、失败或跨会话后,从 `.harness/` 中恢复真实状态。
20
- - 用 shell verification 而不是模型自述判断任务是否完成。
21
- - 可选地通过 `agent-worker` 编排 Feature、Ready Queue、QA、交付与只读 Observe 看板。
22
-
23
- ## 5 分钟开始
24
-
25
- ### 安装
26
-
27
- ```bash
28
- npm install -g @tea-agent/loop-agent@latest
29
- loop-agent --version
30
- ```
31
-
32
- ### 初始化当前项目
33
-
34
- ```bash
35
- loop-agent init instructions --repo-root .
36
- loop-agent init --repo-root . --profile full --merge
37
- loop-agent init doctor --repo-root .
38
- loop-agent inspect --repo-root .
39
- ```
40
-
41
- 初始化会保留已有用户内容,并补充 `AGENTS.md`、`harness.json`、`ai_workspace/loop-agent/`、`.agents/skills/`、`.harness/` 和验证脚本等治理入口。
42
-
43
- 控制器升级后,旧项目可能仍使用过期的 repo-local skills、模板、managed blocks 和治理说明。普通安全仓库命令结束时会自动检测目标项目是否需要对齐:非 TTY 只向 stderr 输出提示且不写入目标;TTY 且无 human decisions、无活跃 DAG/Worker 时,可经明确 `y/yes` 同意后应用 deterministic safe actions;也可手动运行统一入口:
44
-
45
- ```bash
46
- loop-agent init reconcile --repo-root .
47
- ```
48
-
49
- `init reconcile` 在 surface 缺失、存在 human decisions、存在活跃 DAG/Worker 或无法确认 Worker 状态时零写入,并返回 `needs-baseline`、`needs-human-decision` 或 `blocked-active-runtime`;其余情况复用 `init update --apply-safe` 的安全动作并复查返回 `clean`、`needs-model-merge` 或 `needs-safe-update`。
50
-
51
- 写入型自然语言请求「`loop-agent初始化更新`」或「`loop-agent 初始化更新`」必须进入可恢复的统一闭环,而不是只做检查:
52
-
53
- ```bash
54
- loop-agent init upgrade --repo-root . --json
55
- # controller 返回单文件 merge task 后:
56
- loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
57
- ```
58
-
59
- 它在 `.harness/init-upgrades/<run-id>/` 保存身份、扫描、动作收据、合并任务、验证与报告;`--status` / `--report` 只读。默认管理项目 `.opencode/plugins/`、`.pi/extensions/` 和 `.pi/settings.json`,不会默认写 `~/.pi/agent/settings.json`。旧项目首次执行后需 reload 宿主会话,以加载更新后的 AGENTS、skills 与 recovery 产物。明确「检查初始化更新」「只检查,不要修改」仍只运行 `init check-update`。
60
-
61
- 完整说明见[初始化目标项目](website/docs/quick-start/init-target-project.md)。
62
-
63
- ### 运行第一个任务
64
-
65
- 初始化后,在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」(或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」),初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG,**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证,业务实现由受治理 DAG writer 完成。
66
-
67
- ```bash
68
- # 标准单任务路径:唯一 mutation 入口 task advance + 可选只读 task status
69
- loop-agent task advance example-task "实现一个有明确验收标准的小功能" \
70
- --prd path/to/prd.md \
71
- --allowed-path "src/**" \
72
- --forbidden-path ".harness/**" \
73
- --verify "<label>:<command>" \
74
- --json
75
-
76
- # 审查返回的 writeSet / gate.digest 后,同一命令批准并长跑到稳定终态
77
- loop-agent task advance example-task \
78
- --approve-gate "write-set-review:<digest>" \
79
- --json
80
-
81
- # 可选只读查询(不 refresh、不 mutation)
82
- loop-agent task status example-task --json
83
- ```
84
-
85
- `--verify` 命令应取项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的验证命令(不要假定 `npm run typecheck` 存在);`--verify` 可选,省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
86
-
87
- 首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG,然后停在 writeSet gate;未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
88
-
89
- ## 查看执行状态
90
-
91
- ```bash
92
- loop-agent task status example-task --json
93
- # advanced forensic(非标准主路径)
94
- loop-agent dag report --run-id <run-id>
95
- ```
96
-
97
- ### Official 本地操作面(CLI + 统一 Operator Console)
98
-
99
- | 入口 | 命令 | 角色 |
100
- | --- | --- | --- |
101
- | 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
102
- | Loop Operator Console | `agent-worker console` | Official 本地控制面(默认 repo=当前目录、`127.0.0.1:8790`,含 Operate 与 Inspect) |
103
- | Inspect(只读) | `agent-worker console` → `/inspect/`;`observe snapshot` | 统一 Console 内只读检视;`observe serve` 已下线(REMOVED / exit 2) |
104
-
105
- ```bash
106
- # 终端 A:Console(任务/运行操作面;canonical mutation 只经 sibling loop-agent)
107
- agent-worker console # 默认 repo=当前目录、port=8790;本地图形环境默认打开浏览器
108
- agent-worker console --no-open # 只启动服务,不打开浏览器
109
- agent-worker console doctor --repo .
110
-
111
- ```
112
-
113
- 访问 Console <http://127.0.0.1:8790/>;**Operator Chat Official** 是 Console 内的主引导交互。构建时设置 `VITE_OPERATOR_CHAT_DEFAULT_LANDING=chat` 可将 Chat 作为默认 landing;flag 未开启时仍默认进入 Tasks,旧 Task Ops tab 始终保留。顶部「检视」以及 `/inspect/` 提供只读 Dashboard、DAG、时间线与 artifacts;`loop-agent …` / `agent-worker …` CLI direct path 仍是受治理 fallback。当前状态为 **code ready, dogfood pending/unmet**,不宣称已替代 openCode 或其他外部主会话。
114
-
115
- ## 核心边界
116
-
117
- - `.harness/` 保存任务、DAG run、one-shot run、可选 Task Pool 与 `init-upgrades/` 可恢复升级运行事实。
118
- - `ai_workspace/loop-agent/` 保存目标项目的长期治理资料。
119
- - `.agents/skills/` 保存目标项目可审计的 repo-local skills。
120
- - `agent-worker` 通过已发布的 `loop-agent` 子进程执行 DAG,不维护第二套 runtime kernel。
121
- - 当前不内置远程 Task Pool、云 Worker 集群、自动 push、自动创建或合并 PR、生产凭据管理。
122
-
123
- 架构说明见[系统全景](docs/architecture/system-overview.md)和 [runtime 边界](docs/architecture/runtime-boundaries.md)。
124
-
125
- ## 文档导航
126
-
127
- ### 使用者
128
-
129
- - [安装](website/docs/quick-start/installation.md)
130
- - [初始化目标项目](website/docs/quick-start/init-target-project.md)
131
- - [第一次运行](website/docs/quick-start/first-run.md)
132
- - [功能导览](website/docs/overview/feature-map.md)
133
- - [CLI 参考](website/docs/reference/cli.md)
134
- - [Observe 看板](website/docs/guides/observe-ui.md)
135
-
136
- ### 维护者与 Agent
137
-
138
- - [`AGENTS.md`](AGENTS.md):开工协议与工作规则
139
- - [`docs/README.md`](docs/README.md):治理文档总索引
140
- - [`docs/governance/`](docs/governance/README.md):工程原则、工作流与验证方法
141
- - [`docs/runtime/`](docs/runtime/README.md):DAG 运行、恢复与 runtime 手册
142
- - [`docs/operations/`](docs/operations/README.md):本地环境、合并与协作操作
143
- - [`docs/governance/feature-workflow.md`](docs/governance/feature-workflow.md):会话治理与 runtime workflow
144
- - [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md):验证命令选择
145
- - [`docs/architecture/`](docs/architecture/README.md):架构、事实与演进边界
146
- - [`CHANGELOG.md`](CHANGELOG.md):版本变化与 breaking changes
147
-
148
- ## 本仓库开发
149
-
150
- 开始修改前先阅读 `AGENTS.md`。常用验证:
151
-
152
- ```bash
153
- npm install
154
- npm run typecheck
155
- npm test
156
- npm run build
157
- bash scripts/check-repo.sh
158
- ```
159
-
160
- 完整门禁和特定环境排障分别见:
161
-
162
- - [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)
163
- - [`docs/operations/local-development-environment.md`](docs/operations/local-development-environment.md)
164
-
165
- 发布和初始化 surface 变更还应运行 `npm pack --dry-run` 与 `bash scripts/check-init-surface.sh`。
1
+ # loop-agent
2
+
3
+ `loop-agent` 是面向 AI coding agent 的仓库级任务运行时与治理工具。它把研发任务组织为可审查、可执行、可恢复、可验证的 Agent DAG,并将任务源、写入边界、运行事实和完成证据保存在仓库中。
4
+
5
+ 发布包提供两个 CLI:
6
+
7
+ | CLI | 职责 |
8
+ | --- | --- |
9
+ | `loop-agent` | 单仓库任务、Agent DAG、验证、恢复与治理 |
10
+ | `agent-worker` | 可选的 Feature、TaskSpec、Task Pool 与 Observe 外层编排 |
11
+
12
+ 受治理的 Agent writer 只有 Pi;`cursor-prompt` 仅用于显式手工 one-shot,不进入 DAG 或 Loop 自动写入路径。
13
+
14
+ ## 适合解决什么问题
15
+
16
+ - 把模糊的 coding 请求转成有任务源、边界和验收标准的执行过程。
17
+ - 在 Contract → Scout → Plan → Implement → Verify → Closeout 节点间保留可审查证据。
18
+ - 用 `allowedPaths`、`forbiddenPaths` 和 DAG `writeSet` 限制模型写入。
19
+ - 在中断、失败或跨会话后,从 `.harness/` 中恢复真实状态。
20
+ - 用 shell verification 而不是模型自述判断任务是否完成。
21
+ - 可选地通过 `agent-worker` 编排 Feature、Ready Queue、QA、交付与只读 Observe 看板。
22
+
23
+ ## 5 分钟开始
24
+
25
+ ### 安装
26
+
27
+ ```bash
28
+ npm install -g @tea-agent/loop-agent@latest
29
+ loop-agent --version
30
+ ```
31
+
32
+ ### 初始化当前项目
33
+
34
+ ```bash
35
+ loop-agent init instructions --repo-root .
36
+ loop-agent init --repo-root . --profile full --merge
37
+ loop-agent init doctor --repo-root .
38
+ loop-agent inspect --repo-root .
39
+ ```
40
+
41
+ 初始化会保留已有用户内容,并补充 `AGENTS.md`、`harness.json`、`ai_workspace/loop-agent/`、`.agents/skills/`、`.harness/` 和验证脚本等治理入口。
42
+
43
+ 控制器升级后,旧项目可能仍使用过期的 repo-local skills、模板、managed blocks 和治理说明。普通安全仓库命令结束时会自动检测目标项目是否需要对齐:非 TTY 只向 stderr 输出提示且不写入目标;TTY 且无 human decisions、无活跃 DAG/Worker 时,可经明确 `y/yes` 同意后应用 deterministic safe actions;也可手动运行统一入口:
44
+
45
+ ```bash
46
+ loop-agent init reconcile --repo-root .
47
+ ```
48
+
49
+ `init reconcile` 在 surface 缺失、存在 human decisions、存在活跃 DAG/Worker 或无法确认 Worker 状态时零写入,并返回 `needs-baseline`、`needs-human-decision` 或 `blocked-active-runtime`;其余情况复用 `init update --apply-safe` 的安全动作并复查返回 `clean`、`needs-model-merge` 或 `needs-safe-update`。
50
+
51
+ 写入型自然语言请求「`loop-agent初始化更新`」或「`loop-agent 初始化更新`」必须进入可恢复的统一闭环,而不是只做检查:
52
+
53
+ ```bash
54
+ loop-agent init upgrade --repo-root . --json
55
+ # controller 返回单文件 merge task 后:
56
+ loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
57
+ ```
58
+
59
+ 它在 `.harness/init-upgrades/<run-id>/` 保存身份、扫描、动作收据、合并任务、验证与报告;`--status` / `--report` 只读。默认管理项目 `.opencode/plugins/`、`.pi/extensions/` 和 `.pi/settings.json`,不会默认写 `~/.pi/agent/settings.json`。旧项目首次执行后需 reload 宿主会话,以加载更新后的 AGENTS、skills 与 recovery 产物。明确「检查初始化更新」「只检查,不要修改」仍只运行 `init check-update`。
60
+
61
+ 完整说明见[初始化目标项目](website/docs/quick-start/init-target-project.md)。
62
+
63
+ ### 运行第一个任务
64
+
65
+ 初始化后,在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」(或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」),初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG,**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证,业务实现由受治理 DAG writer 完成。
66
+
67
+ ```bash
68
+ # 标准单任务路径:唯一 mutation 入口 task advance + 可选只读 task status
69
+ loop-agent task advance example-task "实现一个有明确验收标准的小功能" \
70
+ --prd path/to/prd.md \
71
+ --allowed-path "src/**" \
72
+ --forbidden-path ".harness/**" \
73
+ --verify "<label>:<command>" \
74
+ --json
75
+
76
+ # 审查返回的 writeSet / gate.digest 后,同一命令批准并长跑到稳定终态
77
+ loop-agent task advance example-task \
78
+ --approve-gate "write-set-review:<digest>" \
79
+ --json
80
+
81
+ # 可选只读查询(不 refresh、不 mutation)
82
+ loop-agent task status example-task --json
83
+ ```
84
+
85
+ `--verify` 命令应取项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的验证命令(不要假定 `npm run typecheck` 存在);`--verify` 可选,省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
86
+
87
+ 首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG,然后停在 writeSet gate;未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
88
+
89
+ ## 查看执行状态
90
+
91
+ ```bash
92
+ loop-agent task status example-task --json
93
+ # advanced forensic(非标准主路径)
94
+ loop-agent dag report --run-id <run-id>
95
+ ```
96
+
97
+ ### Official 本地操作面(CLI + 统一 Operator Console)
98
+
99
+ | 入口 | 命令 | 角色 |
100
+ | --- | --- | --- |
101
+ | 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
102
+ | Loop Operator Console | `agent-worker console` | Official 本地控制面(默认 repo=当前目录、`127.0.0.1:8790`,含 Operate 与 Inspect) |
103
+ | Inspect(只读) | `agent-worker console` → `/inspect/`;`observe snapshot` | 统一 Console 内只读检视;`observe serve` 已下线(REMOVED / exit 2) |
104
+
105
+ ```bash
106
+ # 终端 A:Console(任务/运行操作面;canonical mutation 只经 sibling loop-agent)
107
+ agent-worker console # 默认 repo=当前目录、port=8790;本地图形环境默认打开浏览器
108
+ agent-worker console --no-open # 只启动服务,不打开浏览器
109
+ agent-worker console doctor --repo .
110
+
111
+ ```
112
+
113
+ 访问 Console <http://127.0.0.1:8790/>;**Operator Chat Official** 是 Console 内的主引导交互。构建时设置 `VITE_OPERATOR_CHAT_DEFAULT_LANDING=chat` 可将 Chat 作为默认 landing;flag 未开启时仍默认进入 Tasks,旧 Task Ops tab 始终保留。顶部「检视」以及 `/inspect/` 提供只读 Dashboard、DAG、时间线与 artifacts;`loop-agent …` / `agent-worker …` CLI direct path 仍是受治理 fallback。当前状态为 **code ready, dogfood pending/unmet**,不宣称已替代 openCode 或其他外部主会话。
114
+
115
+ ## 核心边界
116
+
117
+ - `.harness/` 保存任务、DAG run、one-shot run、可选 Task Pool 与 `init-upgrades/` 可恢复升级运行事实。
118
+ - `ai_workspace/loop-agent/` 保存目标项目的长期治理资料。
119
+ - `.agents/skills/` 保存目标项目可审计的 repo-local skills。
120
+ - `agent-worker` 通过已发布的 `loop-agent` 子进程执行 DAG,不维护第二套 runtime kernel。
121
+ - 当前不内置远程 Task Pool、云 Worker 集群、自动 push、自动创建或合并 PR、生产凭据管理。
122
+
123
+ 架构说明见[系统全景](docs/architecture/system-overview.md)和 [runtime 边界](docs/architecture/runtime-boundaries.md)。
124
+
125
+ ## 文档导航
126
+
127
+ ### 使用者
128
+
129
+ - [安装](website/docs/quick-start/installation.md)
130
+ - [初始化目标项目](website/docs/quick-start/init-target-project.md)
131
+ - [第一次运行](website/docs/quick-start/first-run.md)
132
+ - [功能导览](website/docs/overview/feature-map.md)
133
+ - [CLI 参考](website/docs/reference/cli.md)
134
+ - [Observe 看板](website/docs/guides/observe-ui.md)
135
+
136
+ ### 维护者与 Agent
137
+
138
+ - [`AGENTS.md`](AGENTS.md):开工协议与工作规则
139
+ - [`docs/README.md`](docs/README.md):治理文档总索引
140
+ - [`docs/governance/`](docs/governance/README.md):工程原则、工作流与验证方法
141
+ - [`docs/runtime/`](docs/runtime/README.md):DAG 运行、恢复与 runtime 手册
142
+ - [`docs/operations/`](docs/operations/README.md):本地环境、合并与协作操作
143
+ - [`docs/governance/feature-workflow.md`](docs/governance/feature-workflow.md):会话治理与 runtime workflow
144
+ - [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md):验证命令选择
145
+ - [`docs/architecture/`](docs/architecture/README.md):架构、事实与演进边界
146
+ - [`CHANGELOG.md`](CHANGELOG.md):版本变化与 breaking changes
147
+
148
+ ## 本仓库开发
149
+
150
+ 开始修改前先阅读 `AGENTS.md`。常用验证:
151
+
152
+ ```bash
153
+ npm install
154
+ npm run typecheck
155
+ npm test
156
+ npm run build
157
+ bash scripts/check-repo.sh
158
+ ```
159
+
160
+ 完整门禁和特定环境排障分别见:
161
+
162
+ - [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)
163
+ - [`docs/operations/local-development-environment.md`](docs/operations/local-development-environment.md)
164
+
165
+ 发布和初始化 surface 变更还应运行 `npm pack --dry-run` 与 `bash scripts/check-init-surface.sh`。
File without changes
package/bin/loop-agent.js CHANGED
@@ -1,21 +1,57 @@
1
- #!/usr/bin/env node
2
- import { existsSync } from "node:fs";
3
- import { dirname, join } from "node:path";
4
- import { fileURLToPath, pathToFileURL } from "node:url";
5
-
6
- const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
7
- const cliEntry = join(packageRoot, "dist", "cli.js");
8
-
9
- if (!existsSync(cliEntry)) {
10
- console.error(
11
- `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
12
- );
13
- process.exit(1);
14
- }
15
-
16
- try {
17
- await import(pathToFileURL(cliEntry).href);
18
- } catch (error) {
19
- console.error(error instanceof Error ? error.message : String(error));
20
- process.exit(1);
21
- }
1
+ #!/usr/bin/env node
2
+ import { existsSync, readdirSync, statSync } from "node:fs";
3
+ import { dirname, join } from "node:path";
4
+ import { fileURLToPath, pathToFileURL } from "node:url";
5
+
6
+ const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
7
+ const cliEntry = join(packageRoot, "dist", "cli.js");
8
+
9
+ if (!existsSync(cliEntry)) {
10
+ console.error(
11
+ `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
12
+ );
13
+ process.exit(1);
14
+ }
15
+
16
+ /**
17
+ * Stale-dist guard: when running from a source checkout (src/ present), refuse
18
+ * to silently execute a dist/ that predates the latest source edit. The
19
+ * classic failure mode is editing src/** and running the bin without
20
+ * `npm run build`, which executes the previous build. Suppress with
21
+ * --ignore-stale-dist when intentionally running a stale build.
22
+ */
23
+ const srcDir = join(packageRoot, "src");
24
+ const ignoreStale = process.argv.includes("--ignore-stale-dist");
25
+ if (ignoreStale) {
26
+ process.argv = process.argv.filter((arg) => arg !== "--ignore-stale-dist");
27
+ }
28
+ if (!ignoreStale && existsSync(srcDir)) {
29
+ const distCliMtime = statSync(cliEntry).mtimeMs;
30
+ let newestSrcMtime = 0;
31
+ const walk = (dir) => {
32
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
33
+ const full = join(dir, entry.name);
34
+ if (entry.isDirectory()) {
35
+ walk(full);
36
+ } else {
37
+ const mtime = statSync(full).mtimeMs;
38
+ if (mtime > newestSrcMtime) newestSrcMtime = mtime;
39
+ }
40
+ }
41
+ };
42
+ walk(srcDir);
43
+ if (newestSrcMtime > distCliMtime) {
44
+ console.error(
45
+ `loop-agent: dist/ is stale relative to src/ (a source file is newer than ${cliEntry}).\n` +
46
+ ` Run \`npm run build\` before using the bin, or pass --ignore-stale-dist to run the stale build intentionally.`,
47
+ );
48
+ process.exit(1);
49
+ }
50
+ }
51
+
52
+ try {
53
+ await import(pathToFileURL(cliEntry).href);
54
+ } catch (error) {
55
+ console.error(error instanceof Error ? error.message : String(error));
56
+ process.exit(1);
57
+ }
@@ -1031,7 +1031,6 @@ export async function advanceTaskLifecycle(input) {
1031
1031
  cwd: input.repoRoot,
1032
1032
  initOnly: false,
1033
1033
  dryRun: false,
1034
- ...(input.observer ? { observer: input.observer } : {}),
1035
1034
  ...(input.maxConcurrent !== undefined
1036
1035
  ? { maxConcurrent: input.maxConcurrent }
1037
1036
  : {}),
@@ -0,0 +1,6 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "version": "0.35.1-beta.2",
4
+ "gitSha": "91471612918747b6f3d56271eb0198dc83f177a7",
5
+ "builtAt": "2026-08-14T16:38:30.567Z"
6
+ }
@@ -1,7 +1,7 @@
1
1
  import path from "node:path";
2
2
  import { fileURLToPath } from "node:url";
3
3
  import { Command } from "commander";
4
- import { readPackageVersion } from "../shared/package-metadata.js";
4
+ import { readCliVersionLabel } from "../shared/package-metadata.js";
5
5
  import { resolveAdapter } from "../adapters/index.js";
6
6
  import { runCoverageAudit } from "../commands/coverage-audit.js";
7
7
  import { runCoverageReport } from "../commands/coverage-report.js";
@@ -547,7 +547,7 @@ export function buildLoopAgentProgram(options) {
547
547
  program
548
548
  .name("loop-agent")
549
549
  .description("Loop Agent task and DAG automation CLI")
550
- .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
550
+ .version(readCliVersionLabel(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
551
551
  .showHelpAfterError()
552
552
  .option("--repo-root <path>", "repository root")
553
553
  .option("--adapter <name>", "harness adapter name")
@@ -141,7 +141,7 @@ async function runCursorPromptBatch(task, cwd, model, timeoutMs) {
141
141
  }
142
142
  async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
143
143
  const startedAt = Date.now();
144
- process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
144
+ process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
145
145
  `);
146
146
  const runDir = (await computeRunDir(cwd, task)) ?? undefined;
147
147
  const result = await executeCursorPromptStream({
@@ -164,15 +164,15 @@ async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
164
164
  });
165
165
  const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);
166
166
  if (result.ok) {
167
- process.stderr.write(`
168
- [cursor-prompt] done in ${elapsed}s, status=${result.status}
167
+ process.stderr.write(`
168
+ [cursor-prompt] done in ${elapsed}s, status=${result.status}
169
169
  `);
170
170
  }
171
171
  else {
172
172
  const stderr = result.stderr || "(no output)";
173
- process.stderr.write(`
174
- [cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
175
- ${stderr}
173
+ process.stderr.write(`
174
+ [cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
175
+ ${stderr}
176
176
  `);
177
177
  process.exit(1);
178
178
  }