# Loop Agent

[English README](README.md)

> **你睡你的，Loop 交给我。**

<!-- release-skill:capability:external-write-boundary -->
> **外部写入边界：** 帮助与环境检查默认只读；正式运行只写入用户授权的目标；发布仅在冻结计划
> 获得明确批准后，才写入公开 GitHub 仓库、npm 注册表和插件市场。

<!-- release-skill:capability:safe-first-command -->
> **安全首条命令：** 请求使用 `loop-agent:help`；该入口不写文件，也不发起网络请求。

Loop Agent 是一套兼容 Codex 和 Claude Code 的分层智能体编排插件。它不要求单个模型在一次
会话中掌控整个长程任务，而是通过分层规划、独立执行、证据审阅、返工与验收，帮助更多
“足够好但并不完美”的模型稳定完成长程工作。

插件将 loop 角色拆分为独立进程：

- **L0**：私有开发支持，不作为公开插件能力。
- **L1 监督器**：入口与元监督层。选择交付 Profile，每个交付周期委派一个新 L2 进程，拥有客户验收权，仅在风险或异常时抽样 L3 证据。
- **L1 启动包生成器**：将简短的用户请求转化为 Engagement Brief 和命令平面启动包。
- **L2 规划器**：规划并监督一个交付周期。两种路由：目标工作流规划器用于多步骤目标，窄规划器用于有界单目标任务。拥有供应商验收权。
- **L3 Worker**：执行一个已分配的叶子任务。规范 Skill 为 `loop-l3-delivery-task-runner`。旧名称 `loop-l3-workflow-worker` 为兼容别名，指向同一 Skill。

## 交付 Profile

Profile 复用通用 L1/L2/L3 运行时协议，不增加新的层级：

- `post_design_automated_delivery`：当需求和产品设计基线已批准时，自动化技术设计/开发/测试。
- `full_software_delivery`：将每个已批准的阶段建模为独立交付周期，在声明的 HITL 门处暂停。
- `editorial_delivery`：相同的任务/阶段机制，配备编辑、研究员、撰稿人、事实核查员和审阅者等专家角色。

## 进程模型

每一层作为独立进程运行：

1. L1 通过 `launch-layer-process.mjs` 以有界超时启动 L2。
2. L2 通过相同的启动器为每个叶子任务启动 L3。
3. L3 写入 `delivery-task-result.json` 终端合约。
4. L2 写入供应商验收决策（`acceptance-decision.json`）。
5. L1 读取交付包并写入客户验收决策。
6. 供应商级别的返工使用新任务 ID 和新 L3 进程。客户级别的返工创建新交付周期和新 L2 进程。

## 外部运行根目录

运行目录在插件外部。Engagement Brief 记录 `run_root` 和 `target_repository` 路径。插件不在通用 Skill 中嵌入项目特定路径。

## 当前状态

运行时脚本和合约 schema 已稳定。集成测试使用假子进程和真实确定性运行时脚本，执行完整的 L1→L2→L3 交付链，包括返工和验收分离。

### 稳定门禁

`npm test` 是稳定的长期任务门禁，运行全部共享确定性测试、合约测试和集成测试。稳定门禁覆盖范围：

- L1 甲方任务监督者与启动包生成器
- L2 乙方项目经理（目标工作流规划器和窄规划器）
- L3 乙方项目组（顶层交付任务执行与工作流执行）
- 工作流执行包与进程证据
- 验收链（乙方验收和甲方验收）
- 层级启动器与监控守护进程
- 适配器构建、安装与包分发

### 实验性门禁

`npm run test:self-iteration` 是实验性的自学习门禁，**不属于**稳定门禁，存在已知失败。

**自学习当前状态：** 共 1065 项测试，1047 项通过，18 项失败，0 项跳过。

实验性门禁覆盖范围：

- 自迭代状态机
- 判定标准保险库（确定性控制面）
- 用例污染隔离域
- 评测轮次门禁
- Skill 自学习集成

## 目录

```text
.codex-plugin/plugin.json
skills/
scripts/
references/
profiles/
```

项目特定规则应放在 profile 中；通用技能不应写死目标仓库、产品或私有流程。

## 方法锁定解析

`scripts/resolve-method-lock.mjs` 是 L2 方法锁定操作的稳定可执行接口。它读取已验证的
方法注册配置和显式查询过滤器，调用 `queryMethods`、`resolveMethod`、`selectAndLockMethod`
（无重复），并写入恰好一个已验证的方法锁定 JSON 结果。

```bash
# 锁定首个匹配方法（默认选择策略）
node scripts/resolve-method-lock.mjs \
  --config method-registry.json \
  --output method-lock.json

# 锁定显式方法引用
node scripts/resolve-method-lock.mjs \
  --config method-registry.json \
  --output method-lock.json \
  --ref plugin:my-skill

# 严格模式 — 任何注册错误均失败
node scripts/resolve-method-lock.mjs \
  --config method-registry.json \
  --output method-lock.json \
  --mode strict

# 使用查询过滤器
node scripts/resolve-method-lock.mjs \
  --config method-registry.json \
  --output method-lock.json \
  --domain delivery --kind workflow
```

**配置字段**：`command`、`command_args`、`index_path`、`plugin_roots`、
`project_roots`、`timeout_ms`、`max_output_bytes`、`mode`。

**模式**：`compatible`（默认）在软错误时回退到内置锁定（`COMMAND_MISSING`、
`NO_QUERY_MATCH`、`UNCONFIGURED`）。`strict` 严格失败。

**错误代码**：`COMMAND_MISSING`、`NO_QUERY_MATCH`、`INPUT_READ_FAILED`、
`STALE_EFFECTIVE_INDEX`、`INVALID_SELECTION`、`REGISTRY_LOCK_FAILED`。

**锁定字段**：`ref`、`kind`、`provider`、`index_content_hashes`、
`verification`、`diagnostics`、`selection_source`。

脚本通过 `npm run build` 生成到两个适配器中（`adapters/claude/scripts/`、
`adapters/codex/scripts/`）。

## 校验

```bash
node scripts/check-skills.mjs
node scripts/check-loop-token-budgets.mjs
npm test                    # 稳定长期任务门禁（全部共享测试）
npm run test:self-iteration # 实验性自学习门禁（18 项已知失败）
npm run build:check
```

## 冒烟测试

冒烟测试启动真实 Claude 进程并执行完整的 L1/L2/L3 交付链。
它们是**可选的**，默认 `npm test` 不会运行。

```bash
# 跳过（默认）— 以明确的跳过原因退出 0
npm run test:smoke

# 直接分层冒烟 — L0-L3 真实 Claude 交付
LOOP_AGENT_REAL_SMOKE=1 npm run test:smoke

# 仅 direct 过滤器
LOOP_AGENT_REAL_SMOKE=1 LOOP_AGENT_REAL_SMOKE_FILTER=direct npm run test:smoke

# 方法注册冒烟
LOOP_AGENT_METHOD_REGISTRY_REAL_SMOKE=1 npm run test:smoke

# 自迭代 — 确定性测试工具 + 真实自迭代冒烟
LOOP_AGENT_REAL_SMOKE=1 LOOP_AGENT_REAL_SMOKE_FILTER=self-iteration npm run test:smoke

# L1-L2-L3 链 — 完整三层验收，真实 Claude（约 30-60 分钟）
LOOP_AGENT_REAL_SMOKE=1 LOOP_AGENT_CHAIN_SMOKE=1 LOOP_AGENT_REAL_SMOKE_FILTER=chain npm run test:smoke
```

**过滤器：** `direct`、`l0-l3`、`self-iteration`、`chain`。未知过滤器将以明确错误退出（非零）。

**运行时开销：** direct 冒烟测试启动一个真实 Claude 进程，超时为 15 分钟。
自迭代冒烟测试启动一个包含两次试验周期的多阶段工作流。完整冒烟运行请预留 20 分钟以上。
链测试启动三个真实 Claude 进程（L1→L2→L3）执行完整交付链；请预留 30-60 分钟。

**证据目录：** 运行产物保存在 `runs/real-smoke/direct-<timestamp>/` 或
`runs/real-smoke/self-iteration-<timestamp>/` 下。每次运行包含目标审查快照、工作流证据、
delivery-task-result 和 watchdog 证据。

**故障排查：**

- *未找到 Claude CLI：* 安装 Claude CLI 并确保 `claude --version` 报告 >= 2.1.172。
- *版本低于最低要求：* 更新 Claude CLI。最低支持版本为 2.1.172。
- *冒烟测试挂起：* 检查运行目录下的 watchdog 证据 JSON。stale 定时器默认 600 秒，
  max 定时器默认 900 秒。
- *未知过滤器错误：* 使用已知过滤器：`direct`、`l0-l3`、`self-iteration`、`chain`。
- *链测试超时：* 链测试超时为 95 分钟。如挂起，请检查运行目录下的 L1/L2/L3 进程证据
  和执行日志。每层有 600 秒的流空闲定时器。

## 从 npm 安装

```bash
npm install loop-agent@0.1.1
```

先使用只读入口：

```text
请使用 loop-agent:help
```

## 本地安装

```bash
npm run build
npm run install:global
codex plugin add loop-agent@personal
```

安装脚本会把 Codex adapter 写入 `~/plugins/loop-agent`，注册到个人 Codex marketplace；
同时把 Claude Code adapter 写入 `~/.claude/plugins/loop-agent`，并把 skill 目录同步到
`~/.claude/skills`。

## 版本要求

需要 Node.js >= 22.0.0。