dsh-autopilot

Readme

# dsh-autopilot

Done means verified.

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的验收驱动自动完成引擎。

> Agent 说「做完了」，不等于任务完成。

```mermaid
flowchart TD
    A["Agent：Done."] --> B[Autopilot 独立验收]
    B --> C["第一轮：Build / Feature 未过"]
    C --> D[NOT DONE]
    D --> E[按失败项修复]
    E --> F["第二轮：全部必选检查通过"]
    F --> G[VERIFIED COMPLETE]
```

| 检查 | Agent 自称完成 | 修复后再验 |
| --- | :---: | :---: |
| Tests | 通过 | 通过 |
| Typecheck | 通过 | 通过 |
| Build | **未过** | 通过 |
| Feature | **未过** | 通过 |
| **结论** | **不能签发** | **VERIFIED COMPLETE** |

模型声称完成 ≠ 任务已经完成。只有 **验收标准 → 独立验证 → 全部必选检查通过**，才能签发证书。

## 安装

需要 Node.js 20.19+，以及已安装的 DeepSeek Harness（`npx @deepseek-ai/dsh web` 或源码检出）。

### 作为 Harness 插件

```sh
# 从本仓库安装到某个 Harness profile
dsh plugin add https://github.com/245678000000/dsh-autopilot

# 或用本地 checkout 做 overlay
pnpm dsh web --patch /absolute/path/to/dsh-autopilot/cordis.patch.yml
```

插件入口是 `cordis.patch.yml`。装好后会在官方 Goal 栈之后插入 Autopilot，不替换 `ctx.goals`。

### 独立 CLI（不需要跑完整 Harness）

```sh
git clone https://github.com/245678000000/dsh-autopilot.git
cd dsh-autopilot
npm install
npm run build
node dist/cli.js evaluate --cwd ./fixtures/file-only
```

项目里的 shell 验收默认不执行。只有你明确授权时才跑：

```sh
node dist/cli.js evaluate --cwd ./examples/login --allow-commands
```

常用命令：

```text
dsh-autopilot evaluate [--cwd <dir>] [--spec <file>] [--allow-commands]
dsh-autopilot status
dsh-autopilot criteria
dsh-autopilot certificate
```

---

## 它解决什么问题

常见 Agent 工作流是：改几个文件，跑一下命令，然后说「Done.」。这句话后面可能藏着测试失败、构建失败、漏掉的需求、残留 `TODO`，或接口状态码不对。

Autopilot 挂在官方 `agent/turn-stopping` 上，用确定性评估器独立验收。只有 `canCertifyCompletion()` 放行，才会调用 `ctx.goals.complete()`。

## 验收标准

在项目根目录放 `.autopilot.yml`：

```yaml
version: 1
goal:
  objective: 实现登录
budget:
  maxRepairAttempts: 5
criteria:
  - id: tests
    description: 单元测试通过
    required: true
    evaluator:
      type: command
      command: npm test
      expect:
        exitCode: 0
```

完整编码示例见 `examples/login/.autopilot.yml`。

## 完成认证

全仓库只有一扇门：`canCertifyCompletion()`。

签发 `VERIFIED COMPLETE` 必须同时满足：

- 每一项 **必选** 标准都有当前结果
- 结果是 `passed`
- PASS 带有 **可观察证据**
- 工作区改动后，结果不是 **过期（stale）** 的
- 必选但无法验证的项不会被放行

Worker 说「Done.」只会被记成一份被忽略的提议。

通过后会写出 `CompletionCertificate`：

```text
VERIFIED COMPLETE

6 / 6 required checks passed

✓ tests
✓ typecheck
✓ build
✓ login success case
✓ login failure case
✓ no placeholder

Attempts:
3
```

## 重试与阻断

可修复的失败会生成结构化反馈（期望 / 实际 / 输出摘录 / 回归），并用 `agent.steer(...)` 让当前 turn 继续。若设置 `continuationMode: goal-round`，则交给官方 `@deepseek-ai/dsh-goal-round-driver` 排下一轮。

重试有上限。默认：`maxRepairAttempts = 5`，`maxEvaluations = 10`，`maxRounds = 8`，墙钟 30 分钟。

不是所有失败都该再试。缺密钥、缺人决策、审批拒绝、必选标准无法验证，会变成 `BLOCKED`，并写明 `need` / `resolvedWhen`。缺 API key 不会空转 20 轮。

## 回归、无进展、振荡

每次评估都会和上一轮对比。`PASS → FAIL` 会标成 **REGRESSION DETECTED**。

连续三次相同失败指纹是 `NO_PROGRESS`。A/B 来回翻转是 `OSCILLATION`。各自最多触发 **一次** 策略重置；再犯就 `BLOCKED`。

## 和官方 Goal 的关系

Autopilot 不替换 `@deepseek-ai/dsh-goal`。

| 验收结果 | 官方 API |
| --- | --- |
| 认证通过 | `ctx.goals.complete(agent, ref)` |
| 需要人 / 预算耗尽 / 无进展 | `ctx.goals.block(agent, ref, { code, message })` |
| 可修复失败 | Goal 保持 `active`；`steer` 或交给官方 driver |

模型调用的 `update_goal complete` 会在 `tools/pre-execute` 被拦截，只当提议。

人类 `/goal` 不变。Autopilot 额外提供 `/autopilot`。

对照的 Harness commit：`47f943859b`（`0.1.0-rc.5`）。细节见 [`docs/harness-integration.md`](docs/harness-integration.md)。

## 评估器

| 类型 | 查什么 |
| --- | --- |
| `command` | 真实 exit code / stdout / stderr |
| `file` | exists / contains / notContains / sha256 |
| `regex` | 匹配次数 |
| `git` | 工作区是否脏、允许改哪些路径 |
| `http` | status / headers / JSON path（防 SSRF） |
| `manual` | 等人确认，否则 blocked |
| `agent` | 最后手段的独立评判；schema 校验；从不默认 PASS |

优先级：确定性检查 → 结构化工具检查 → LLM 评判。

## 安全

`.autopilot.yml` 视为不可信项目配置。危险命令会拒绝。HTTP 默认只允许 localhost。云 metadata（`169.254.169.254`）会被拦住。评估器没有工作区写权限。Autopilot 不会绕过 Harness 审批。见 [`docs/security.md`](docs/security.md)。

## Demo

```sh
npm run demo
```

1. Agent 说「Done!」——构建和错误密码用例失败——修复——**VERIFIED COMPLETE**
2. 自信说错：「测试都过了」对照 `exit code 1`
3. 连续 4/5 同样失败 → **BLOCKED**
4. 测试先 PASS 再 FAIL → **REGRESSION**

```sh
npm run bench
```

合成场景，只跑控制器，不编造数字。

## 限制

- 没有可观察测试的标准，验不了。
- LLM 评估器是概率性的。非法输出记为 `error`，不是 `pass`。
- 写坏的验收标准会签发错误证书。
- 外部系统可能不可用。
- 有些任务必须由人判断。
- 测试通过在数学上不能证明软件正确。
- Autopilot 提高完成可靠性，不保证完美结果。
- 受信任的进程内插件如果直接调用 `ctx.goals.complete()`，官方 Goal 服务仍然认。Autopilot 拦截的是模型工具，不是所有 in-process 调用。

## 路线图

- **v0.1** — 编码验收、command/file/http/git、官方 Goal + turn-stopping、修复循环、回归/无进展/振荡、证书
- **v0.2** — 浏览器评估器、界面验收、可选 Time Machine 检查点
- **v0.3** — 研究 / 数据管道评估器、多 Agent 独立核验
- **v0.4** — CI 与 GitHub PR 验收、团队策略包

## License

MIT