@tea-agent/loop-agent 0.7.4 → 0.8.0

package/README.md

@@ -1,204 +1,206 @@
-# loop-agent
-
-`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
-
-它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
-
-## 快速开始
-
-到一个新项目时，可以直接对当前 agent 说：
-
-```text
-请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
-```
-
-作为 CLI 使用时，安装已发布包：
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --version
-loop-agent --help
-```
-
-检查当前项目的 loop-agent 配置：
-
-```bash
-loop-agent doctor
-loop-agent inspect
-```
-
-## 初始化目标项目
-
-在新项目中，最简单的用法是让当前 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/` 并同步镜像到 `.agents/skills/`（agent 兼容路径，如 OpenCode 自动发现），生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档和 `.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`、`.task-pool/`、`.worktrees/` 等个人/会话运行态事实忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
-
-新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
-
-```bash
-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：
-
-```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 的有边界任务说明>"
-```
-
-产品线 feature packet 可用伴生 Worker CLI 做 docs CI；仓库也提供外部 CI/cron wrapper，调度仍由外部系统负责：
-
-```bash
-agent-worker task validate-feature <feature-dir>
-bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
-```
-
-nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
-
-## 核心概念
-
-- **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/`（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/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
-
-```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
-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 实践资料 |
-
-## 本仓库开发
-
-本地源码开发：
-
-```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: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 包前至少运行：
-
-```bash
-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>` 只用于源码开发和定位问题。
+# loop-agent
+
+`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
+
+它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
+
+## 快速开始
+
+到一个新项目时，可以直接对当前 agent 说：
+
+```text
+请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
+```
+
+作为 CLI 使用时，安装已发布包：
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
+loop-agent --help
+```
+
+检查当前项目的 loop-agent 配置：
+
+```bash
+loop-agent doctor
+loop-agent inspect
+```
+
+## 初始化目标项目
+
+在新项目中，最简单的用法是让当前 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/` 并同步镜像到 `.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。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
+
+```bash
+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：
+
+```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 的有边界任务说明>"
+```
+
+产品线 feature packet 可用伴生 Worker CLI 做 docs CI；仓库也提供外部 CI/cron wrapper，调度仍由外部系统负责：
+
+```bash
+agent-worker task validate-feature <feature-dir>
+bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
+```
+
+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/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
+
+```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
+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 实践资料 |
+
+## 本仓库开发
+
+本地源码开发：
+
+```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: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 包前至少运行：
+
+```bash
+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>` 只用于源码开发和定位问题。

package/bin/agent-worker.js

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "worker", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `agent-worker: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  const cli = await import(pathToFileURL(cliEntry).href);
-  await cli.main(process.argv);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "worker", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `agent-worker: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  const cli = await import(pathToFileURL(cliEntry).href);
+  await cli.main(process.argv);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/bin/loop-agent.js

@@ -1,21 +1,21 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  await import(pathToFileURL(cliEntry).href);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  await import(pathToFileURL(cliEntry).href);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}