@tea-agent/loop-agent 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 这里记录每个版本面向使用者的主要变化。保持简短即可：新增、修改、修复或删除了什么，不需要展开实现细节。
 
-## [0.1.0] - 未发布
+## [0.2.0] - 2026-07-05
+
+### 新增
+
+- 新增 `loop-agent init` 初始化目标项目，包含模型指引输出、merge 初始化、初始化体检、repo-local skills 投影、语言无关治理脚本矩阵、runtime boundary 文档、skill entry/architecture boundary 检查和目标项目版治理文档；根 README 默认生成中文项目入口，并以 managed block 合并已有 README；模型执行初始化时必须在同一轮自动完成项目识别、README/验证矩阵适配和体检闭环；`examples` 改为工具内置查看/按需复制，不在初始化时默认写入目标仓库。
+
+### 修改
+
+- `harness.json` 支持用 `adapter: "loop-agent"` 与真实项目名分离，目标项目无需把 `project` 写成 `loop-agent` 才能使用默认 adapter。
+- README 重组为兼顾 npm/GitHub 展示和本仓库迭代导航的入口，明确区分快速开始、目标项目初始化、任务运行、核心概念、本仓库开发和发布包内容，并补充新项目初始化时可直接交给模型执行的提示词。
+
+### 修复
+
+- npm 发布包范围纳入 `docs/architecture/runtime-boundaries.md`，确保 runtime boundary 治理文档随 0.2.0 包一起发布。
+- Cursor DAG worker 在构建产物中使用 `.js` worker 入口且不依赖 `tsx`，避免发布包/本地 build 运行 Cursor 节点时先因 worker 入口解析失败。
+
+## [0.1.0] - 已发布
 
 ### 新增
 

package/README.md

@@ -1,55 +1,113 @@
-# loop-agent
-
-`loop-agent` 是从 `agent-memory/tools/code-agent` 独立出来的 TypeScript 工作流运行时，用来支撑 AI coding agent 在一个仓库内完成可恢复、可验证、可交接的研发任务。
+# loop-agent
 
-它保留了原 `code-agent` 的核心思路：以 Agent DAG 为主路径，用 `.harness/` 记录运行态事实，用 shell verification 作为完成依据，并把长期治理、计划和交接资料沉淀到 `docs/`。
+`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
 
-当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
-
-## 核心能力
-
-- 生成、校验、执行和汇总 Agent DAG
-- 支持以 Agent DAG 为主的任务生成、校验、执行和收口
-- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿
-- 通过 Pi executor 执行只读规划、评审和诊断
-- 通过 Pi executor 的 `toolProfile: "write"` 执行有边界的写代码任务；Cursor executor 保留为显式启用的可选后端
-- 通过 shell executor 运行确定性的验证命令
-- 检查任务状态、运行态工件、文档链接和源码结构等治理规则
-
-## 目录结构
-
-| 路径 | 用途 |
-|---|---|
-| `src/` | CLI、命令、工作流、执行器、任务运行时、治理和共享 helper |
-| `test/` | Vitest 回归测试 |
-| `bin/loop-agent.js` | CLI 可执行入口 |
-| `skills/` | loop-agent 和 DAG 模板引用的本地 skill 指令与参考资料 |
-| `.harness/` | 任务、DAG、run、cache 和 live state 等运行态目录 |
-| `docs/` | 治理文档、工作流规则、执行计划、报告和模板 |
-| `website/` | Docusaurus 用户文档站 |
-| `examples/` | 可复用 DAG 示例 |
-| `scripts/` | 仓库验证和维护脚本 |
-
-## 安装
+它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
 
-```bash
-npm install
+## 快速开始
+
+到一个新项目时，可以直接对当前 agent 说：
+
+```text
+请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
 ```
 
-发布包 CLI 使用构建产物：
+作为 CLI 使用时，安装已发布包：
 
 ```bash
-npm run build
+npm install -g @tea-agent/loop-agent@latest
 loop-agent --help
 ```
 
-本地源码调试使用开发入口：
+检查当前项目的 loop-agent 配置：
 
 ```bash
-npm run dev -- --help
+loop-agent doctor
+loop-agent inspect
 ```
 
-如果要用 loop-agent 迭代 loop-agent 本仓库，不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器。应安装 npm 上已发布版本，让已安装的稳定版本操作当前仓库。首次安装或有意升级时使用 `@latest`，启动一次自举任务后不要在任务中途升级控制器：
+## 初始化目标项目
+
+在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：
+
+```text
+请用 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，可以使用：
+
+```bash
+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/`，生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档和 `.harness/` 骨架；已有 README 会保留用户正文并插入/更新 loop-agent 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：
+
+```bash
+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`。
+
+一次性只读评审或有边界写入：
+
+```bash
+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 的有边界任务说明>"
+```
+
+## 核心概念
+
+- **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
+- **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
+- **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本。
+- **repo-local skills**：目标项目本地的 `skills/` 优先于发布包内置 skills，便于项目定制 agent 行为。
+- **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
+- **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
+
+## 能力概览
+
+- 生成、校验、执行和汇总 Agent DAG。
+- 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
+- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
+- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
+- 保留 Cursor executor 作为显式启用的可选后端。
+- 通过 shell executor 运行确定性的验证命令。
+- 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
+
+## 内置示例
+
+`examples/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
+
+```bash
+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`，但一次自举任务启动后不要在任务中途升级控制器。
 
 ```bash
 npm install -g @tea-agent/loop-agent@latest
@@ -60,68 +118,51 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 `@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举任务应记录 `npm list -g` 显示的实际版本号。
 
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+## 文档导航
+
+| 路径 | 用途 |
+|---|---|
+| `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
+| `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
+| `docs/README.md` | 治理文档索引 |
+| `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
+| `docs/architecture/runtime-boundaries.md` | runtime 层边界和依赖方向 |
+| `skills/loop-agent/` | loop-agent skill 入口和 references |
+| `examples/` | 可复用 DAG 示例 |
+| `website/docs/` | 面向使用者的 Docusaurus 文档站内容 |
+
+## 本仓库开发
+
+本地源码开发：
 
-发布包可作为任意目标项目的稳定控制器。DAG skill 指令优先从目标项目或用户配置目录解析；目标项目未提供本地 `skills/` 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。
+```bash
+npm install
+npm run build
+node bin/loop-agent.js --help
+npm run dev -- --help
+```
+
+常用验证命令：
 
-## 常用命令
-
 ```bash
 npm run typecheck
 npm test
 bash scripts/check-repo.sh
 bash scripts/ci.sh
-npm run docs:dev
 npm run docs:build
 ```
 
-跨平台约定：
+当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
 
-- `scripts/*.sh` 是 Bash 脚本；Windows 上请通过 Git Bash 或已配置的兼容 Bash 运行，不要求使用 WSL 或 POSIX 路径。
-- 实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径。仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
+Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
 
-创建并运行一个任务 DAG：
+## 发布包内容
 
-```bash
-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 .
-```
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
 
-`<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
-
-一次性只读评审或有边界写入：
-
-```bash
-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 的有边界任务说明>"
-```
-
-## 文档站
-
-面向使用者的 Markdown 文档放在 `website/docs/`，通过 Docusaurus 渲染为静态 HTML。
-
-```bash
-npm run docs:dev
-npm run docs:build
-npm run docs:serve
-```
-
-构建产物输出到 `website/build/`。仓库根目录的 `docs/` 仍然是治理根目录，不和用户文档站混用。
-
-## 验证原则
-
-选择能覆盖本次变更的最小命令：
-
-- 文档或治理变更：`bash scripts/check-repo.sh`
-- TypeScript 运行时代码变更：`npm run typecheck`
-- 行为变更：`npm test`
-- 完整本地门禁：`bash scripts/ci.sh`
-
-Windows 上的 Bash 验证命令同样通过 Git Bash 或配置好的 Bash 执行；不要把 `/tmp`、`which`、POSIX shell builtin 等假设写进跨平台 CLI 逻辑。
-
-不要在没有新鲜验证结果的情况下声明完成。
+`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+
+DAG skill 指令优先从目标项目或用户配置目录解析；目标项目未提供本地 `skills/` 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。
 
 ## 发布前检查
 
@@ -136,9 +177,3 @@ npm pack --dry-run
 ```
 
 发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。
-
-## 改造来源
-
-`loop-agent` 来自 `agent-memory/tools/code-agent` 的主仓库化改造。原型阶段的 `code-agent` 文档偏内部说明；当前仓库入口文档面向独立项目维护和使用。
-
-已完成的主仓库重构记录保留在源码仓库的历史 execution plans 中；发布包只携带目录说明和可复用运行资料。

package/dist/adapters/index.js

@@ -14,9 +14,10 @@ export async function resolveAdapter(repoRoot, explicit) {
     }
     try {
         const manifest = await loadHarnessManifest(repoRoot);
-        const adapter = ADAPTERS[manifest.project];
+        const adapterName = manifest.adapter ?? manifest.project;
+        const adapter = ADAPTERS[adapterName];
         if (!adapter)
-            throw new Error(`no adapter registered for project "${manifest.project}"; valid options: ${Object.keys(ADAPTERS).join(', ')}`);
+            throw new Error(`no adapter registered for project "${adapterName}"; valid options: ${Object.keys(ADAPTERS).join(', ')}`);
         return adapter;
     }
     catch (error) {

package/dist/adapters/loop-agent.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import { buildStepContextFiles } from './context.js';
 import { loadHarnessManifest } from '../governance/harness.js';
 function getKeyRepoPaths(repoRoot, manifest) {
@@ -58,6 +59,10 @@ async function getContextFilesForStep(repoRoot, manifest, taskId, step, taskConf
     });
 }
 function getVerifyCommands(repoRoot, options) {
+    const manifestCommands = getManifestVerifyCommands(repoRoot, options.preset);
+    if (manifestCommands) {
+        return applyQuota(manifestCommands, options);
+    }
     const quickCommands = [
         {
             args: ['bash', 'scripts/check-repo.sh'],
@@ -84,11 +89,48 @@ function getVerifyCommands(repoRoot, options) {
         : options.preset === 'standard'
             ? [...quickCommands, ...standardCommands]
             : [...quickCommands, ...standardCommands, ...fullCommands];
+    return applyQuota(selectedCommands, options);
+}
+function applyQuota(commands, options) {
     if (options.phase === 'final' || !options.quota || options.quota === 'full') {
-        return selectedCommands;
+        return commands;
     }
     const maxCommands = options.quota === '1' ? 1 : 3;
-    return selectedCommands.slice(0, maxCommands);
+    return commands.slice(0, maxCommands);
+}
+function commandFromScript(repoRoot, label, command) {
+    return {
+        args: ['bash', '-lc', command],
+        cwd: repoRoot,
+        label,
+    };
+}
+function getManifestVerifyCommands(repoRoot, preset) {
+    try {
+        const manifest = JSON.parse(readFileSync(path.join(repoRoot, 'harness.json'), 'utf-8'));
+        const quick = typeof manifest.scripts?.quickVerify === 'string'
+            ? manifest.scripts.quickVerify
+            : undefined;
+        const standard = typeof manifest.scripts?.standardVerify === 'string'
+            ? manifest.scripts.standardVerify
+            : undefined;
+        const full = typeof manifest.scripts?.fullVerify === 'string'
+            ? manifest.scripts.fullVerify
+            : undefined;
+        if (!quick && !standard && !full)
+            return undefined;
+        const quickCommands = quick ? [commandFromScript(repoRoot, 'repo quick verification', quick)] : [];
+        const standardCommands = standard ? [commandFromScript(repoRoot, 'repo standard verification', standard)] : [];
+        const fullCommands = full ? [commandFromScript(repoRoot, 'repo full verification', full)] : [];
+        if (preset === 'quick')
+            return quickCommands;
+        if (preset === 'standard')
+            return [...quickCommands, ...standardCommands];
+        return [...quickCommands, ...standardCommands, ...fullCommands];
+    }
+    catch {
+        return undefined;
+    }
 }
 export const loopAgentAdapter = {
     name: 'loop-agent',