loop-agent

loop-agent 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 .harness/、docs/ 和 shell verification 记录执行事实、长期治理资料和完成依据。

它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。

快速开始

到一个新项目时，可以直接对当前 agent 说：

请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。

作为 CLI 使用时，安装已发布包：

npm install -g @tea-agent/loop-agent@latest
loop-agent --version
loop-agent --help

检查当前项目的 loop-agent 配置：

loop-agent doctor
loop-agent inspect

初始化目标项目

在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：

请用 loop-agent 完整初始化当前项目。

如果本机还没有 `loop-agent` 命令，请先运行 `npm install -g @tea-agent/loop-agent@latest`，再记录 `npm list -g @tea-agent/loop-agent --depth=0` 的实际版本。

然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。

初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。

最后运行 `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`，并汇报结果、假设和剩余风险。

如果手动运行 CLI，可以使用：

loop-agent init instructions --repo-root <target-repo>
loop-agent init --repo-root <target-repo> --profile full --merge
loop-agent init doctor --repo-root <target-repo>

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 规则。

新初始化会写入 .harness/init-surface.json，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：

loop-agent init check-update --repo-root <target-repo> --json
loop-agent init check-update --repo-root <target-repo> --markdown
loop-agent init update --repo-root <target-repo> --bootstrap-surface
loop-agent init update --repo-root <target-repo> --apply-safe

check-update 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。update --bootstrap-surface 为旧项目补 inferred baseline；update --apply-safe 只补缺失文件、目录和 managed block（包括过期的 .gitignore managed block），不覆盖已有但无法确认来源的本地文件。

当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 docs/verification-matrix.md 和必要的 scripts/ci-tests.sh。

初始化生成的 scripts/ci-tests.sh 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 package.json、Makefile、go.mod、Cargo.toml、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。

运行任务

创建并运行一个标准 Agent DAG：

loop-agent new-task <task-id> "任务标题"
loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .

<temp-dir> 表示平台原生临时目录；也可以省略 --output，再使用命令 JSON 输出里的 outputPath。

一次性只读评审或有边界写入：

loop-agent pi-prompt --cwd . --tools read,grep,find,ls "只读评审这个任务，不要编辑文件。"
loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含 allowedPaths 和 forbiddenPaths 的有边界任务说明>"

产品线 feature packet 可用伴生 Worker CLI 做 docs CI；仓库也提供外部 CI/cron wrapper，调度仍由外部系统负责：

agent-worker task validate-feature <feature-dir>
agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>
agent-worker feature run --feature-dir <feature-dir> --repo <target-repo> --dry-run [--git-mode checkpoint]
agent-worker feature verify-final --feature-dir <feature-dir> --repo <target-repo> --task-id <qa-execute-id>
agent-worker feature delivery --feature-dir <feature-dir> --repo <target-repo> --qa-evidence <path> --final-verification <path> [--dry-run]
agent-worker feature closeout --feature-dir <feature-dir> --repo <target-repo> [--apply --owner <owner>]
agent-worker report metrics --repo <target-repo> --month <YYYY-MM>
agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>
agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <target-repo> --owner <owner> --dry-run
bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>

feature review 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动；默认输出简洁人类摘要，--json 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。

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 会幂等复用。

Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展示 Status、Next Action、Why、Evidence。report metrics 同时生成 monthly JSON/Markdown，所有比例都包含分子、分母、样本量、UTC 窗口和缺失数据说明。

feature run 把 validation、目标仓库 preflight、Ready Queue、现有 run-ready、晨报、Observe snapshot 和最终 review 串成一次 Feature 意图。默认不写 Git 且每次最多推进一个 Ready 写任务。显式 --git-mode checkpoint 才允许创建本地 agent/<feature-id> 分支：每个成功任务通过 write-boundary/sensitive-file audit 后提交 checkpoint；失败任务先保存 binary patch、changed/untracked inventory 与内容，再恢复到最近 checkpoint 并验证 clean。它从不授权 push、远程 PR、merge 或 stash。--keep-failed-diff 会保留失败 diff、返回 NeedsAction 并立即停止后续任务。

如果 Task 产生业务失败，feature run 仍会完成晨报、snapshot 和最终 review，但结果为 needs-action、进程退出非零，并保留 batch 与失败证据；无 Ready 时正常退出，并通过 noReadyReason 区分已关闭、可交付、待 QA、需人工处理、依赖阻塞或空 Feature。

失败可通过显式 Follow-up 决策闭环接续：ProductBug、TestBug、FlakyTest、DependencyFailure 会生成可批准 Task 草稿；EnvFailure 最近两次连续失败后才生成 ENV-CHECK-*，否则优先给出 retry；SpecUnclear、ContractMismatch、RiskyChange、NeedsHuman、Unknown 只生成人工行动卡，绝不进入 Ready。人工用 feature approve-followup --dry-run 复核 baseline、证据 hash、ID 冲突和事务计划，再带 --owner 批准。批准后新增 TaskSpec、重连下游依赖并进入 Ready；原失败 run/state/handoff 保持不变，重复 run 的新草稿会 supersede 旧 unresolved 草稿但保留历史。

nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。

自 0.8.0 起，.harness/task-pool/ 是唯一受支持的 Task Pool runtime root，其中包含根级 runs.jsonl、events.jsonl、states/、artifacts/、failure-handoffs/、observability/ 和 reports/。这是 hard cutover：旧路径不读取、不迁移、不合并、不重映射；升级意味着本地 Worker Task Pool 历史重置。

核心概念

• Agent DAG：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
• .harness/：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
• harness.json：描述项目名、治理根目录、模型路由、executor 和验证脚本；docs/templates/harness.schema.json 为 IDE 提供补全和字段说明，运行时仍由 Zod schema 校验。
• repo-local skills：目标项目本地的 skills/（loop-agent 主路径）优先于发布包内置 skills，便于项目定制 agent 行为；init --profile full 还会把同一份 skills 镜像到 .agents/skills/，让外部 agent（如 OpenCode）也能自动发现。DAG skill 解析顺序为：用户配置目录 → skills/ → .agents/skills/ → 发布包内置。
• 治理文档：docs/ 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
• shell verification：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。

这些治理原则的设计思想吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践：人类掌舵，智能体执行；仓库作为记录系统；任务小步推进；用结构化 handoff 与可复现验证跨 session 保持连续性。背景资料收录在 website/docs/practices/。

能力概览

• 生成、校验、执行和汇总 Agent DAG。
• 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
• 维护 loop 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
• 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
• 保留 Cursor executor 作为显式启用的可选后端。
• 通过 shell executor 运行确定性的验证命令。
• 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。

内置示例

examples/ 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：

loop-agent examples list
loop-agent examples show example-dag.json
loop-agent examples copy example-dag.json --repo-root <target-repo>

迭代本仓库

如果要用 loop-agent 迭代 loop-agent 本仓库，控制器必须来自已发布的 npm 安装包。不要使用当前工作区的 npm link 或 npm run dev 作为控制器；首次安装或有意升级可用 @latest，但一次自举任务启动后不要在任务中途升级控制器。

npm install -g @tea-agent/loop-agent@latest
npm list -g @tea-agent/loop-agent --depth=0
loop-agent doctor
loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>

@latest 只用于安装或升级，不要在 DAG 节点里反复用 npx @latest 拉取。自举任务应记录 npm list -g 显示的实际版本号。

文档导航

| 路径 | 用途 | |---|---| | AGENTS.md | 本仓库的 agent 开工协议、会话协议和长期工作规则 | | harness.json | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 | | docs/README.md | 治理文档索引 | | docs/verification-matrix.md | 不同变更类型对应的验证命令 | | docs/production-readiness.md | Production Readiness v0.1 支持范围、证据和验收标准 | | docs/architecture/runtime-boundaries.md | runtime 层边界和依赖方向 | | skills/loop-agent/ | loop-agent skill 入口和 references | | examples/ | 可复用 DAG 示例 | | website/docs/ | 面向使用者的 Docusaurus 文档站内容 | | website/docs/practices/ | Anthropic、OpenAI Codex、腾讯端到端工程与社区 harness 实践资料 |

本仓库开发

本地源码开发：

npm install
npm run build
node bin/loop-agent.js --help
npm run dev -- --help

常用验证命令：

npm run typecheck
npm test
bash scripts/check-repo.sh
bash scripts/ci.sh
npm run docs:build

当前 CLI 使用 commander 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。

Windows 上运行 scripts/*.sh 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 --output / --dag / --cwd 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 / 作为稳定分隔符。

发布包内容

发布包包含静态运行和指导资料：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。

docs/progress/、docs/reports/、docs/exec-plans/、docs/decisions/ 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。

DAG skill 指令优先从目标项目或用户配置目录解析；目标项目未提供本地 skills/ 时，CLI 会回退到 npm 包内置的 skills/。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。

发布前检查

发布 npm 包前至少运行：

npm run typecheck
npm test
npm run build
node bin/loop-agent.js --help
npm pack --dry-run

发布入口 bin/loop-agent.js 只加载 dist/cli.js；npm run dev -- <args> 只用于源码开发和定位问题。