# pilot-harness

> DSH 一次性任务执行组合包，跳过 Web 与浏览器，直接在命令行跑一次 Agent 并退出。

## Metadata

- Author: [@op7418](https://github.com/op7418)
- Repo: <https://github.com/op7418/pilot-harness.git>
- GitHub: [op7418/pilot-harness](https://github.com/op7418/pilot-harness)
- Stars: 240
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `ai-agent`, `codepilot`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `linux`, `macos`, `typescript`, `windows`
- Forks: 13
- Open Issues: 16
- Last push: 2026-08-20T12:42:53.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headless
```

## Wiki

## 一句话定位
dsh 的一次性任务组合包：在不启动 Web 界面或浏览器的前提下，从命令行接收一条任务文本，跑完一个 Agent 后把答案打到 stdout 并退出。

## 核心能力
- 在命令行一次性执行任务，无需打开 Web 界面或浏览器
- 自动创建一个持久化 Agent，把命令行任务作为用户消息提交，等 Agent 进入空闲后退出
- 退出前调用 sessions.flush 把本次会话持久化，并把最后一条非空 Assistant 文本写入 stdout
- 用退出码反馈结果：最终 turn 以"completed"收尾时退出码 0，其他情况（含错误、中止、空白 turn）退出码 1
- 不打开任何监听端口，纯进程级执行，适合 CI、脚本、定时任务等自动化场景
- 启动阶段缺少任务文本会被拒绝，提示用法并以非零码退出，避免空跑

## 技术实现
- **语言**: TypeScript（ESM，`"type": "module"`）
- **关键依赖**: @deepseek-ai/cordis（插件框架）、@deepseek-ai/dsh-agent（Agent 与 Inbox）、@deepseek-ai/dsh-session（持久化会话）、commander（命令行解析）
- **架构模式**: cordis 命名导出函数插件（`name`/`inject`/`Config`/`apply`），与 `headless-startup`、`headless-invariant` 三个同名插件一起被 `cordis.patch.yml` 注入到 dsh-base 之上；runner 通过 Cordis 上下文获取宿主服务（`agentDefaultModel`、`agents`、`sessions`），再经宿主提供的 `appExit` 钩子退出
- **入口文件**: src/index.ts（runner）、src/startup.ts（命令行提供方）、src/invariant.ts（不变量伴生插件）

## 适用场景
想在 CI、脚本或定时任务里直接跑一次 AI 任务、不愿意或不能开 Web 控制台时，这个组合包最合适。它只读取命令行参数、跑完一个 Agent、把答案打到 stdout、用退出码告诉调用方成败。
也可以作为 dsh 自身最小可用 Agent 调用栈的参考——一次性 runner + Code Mode worker + base 工具栈，足以理解 Cordis 插件如何在不挂载 Web 的情况下驱动一次完整对话。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7+ | 依赖工作区内的 dsh-base、dsh-agent、dsh-session、dsh-llm、dsh-invariants、dsh-cmdline、dsh-agent-default-model、dsh-code-runtime-worker-thread 等包；这些 peerDependencies 全部以 `workspace:^` 形式声明 |
| Node.js | ^22.19.0 \|\| >=24.0.0 | monorepo 根 `package.json` 中 `engines` 字段的要求；bundle 自身未单独声明 |
| 平台 | 跨平台 | 全部为 Node.js 进程级逻辑，无系统调用或原生绑定 |
| 原生模块 | 无 | 依赖全部为纯 JS/TS，没有 node-pty、node:sqlite 等原生依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headless
```

安装后通过 `dsh --profile headless "你的任务"` 调用本组合包。

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| task | 字符串（必填） | 要让 Agent 执行的单次任务文本；命令行上多个词会以空格拼接 | 无 |

> 该字段由 `cordis.patch.yml` 中的 `headless-startup` 插件在解析命令行后通过惰性配置注入，runner 自身不直接接受 Cordis 配置。

## 常见问题

**Q: 任务可以多轮对话吗？**

A: 不可以。runner 只把命令行参数作为一条用户消息提交给 Agent，等 Agent 处理完一个 turn 后就退出，没有追问或继续对话的入口。

**Q: 退出码如何判断成败？**

A: 退出码 0 表示最终 turn 以"completed"收尾；其他情况（含中止、模型报错、没有 turn 发生）均为 1，方便脚本与 CI 直接判断。

**Q: 答非所问或模型报错时输出在哪？**

A: 最后一条非空 Assistant 文本写到 stdout；模型报错的错误码和消息以"dsh: CODE: message"格式写到 stderr；正常情况下 stderr 为空。

**Q: 不传任务文本会怎样？**

A: 启动器在解析阶段就会拒绝，提示"a task is required"并以退出码 1 退出，runner 不会被激活，整个进程不进入 Agent 创建流程。

**Q: 会打开端口吗？**

A: 不会。这个组合包不挂载 Host、HTTP server 或 Web runtime，进程不监听任何端口，适合在容器或受限网络环境下运行。

**Q: 怎么卸载？**

A: 在当初安装时使用的 profile 下执行 `dsh plugin --profile web remove github:op7418/pilot-harness/packages/bundle/headless` 即可。

**Q: 这个组合包会修改模型提示词吗？**

A: 会。它的 cordis 补丁把 system-prompt 的人格改为"You are a coding agent powered by the {{model}} model"，并把当前工作目录注入到 persona。

**Q: 数据存在哪？**

A: 退出前会调用 sessions.flush 把这次会话持久化到宿主配置的 Session 存储，具体路径由 DSH 启动器和 Session 插件决定，本组合包不另设本地文件。

## 上手难度
入门 — 调用方式只有 `dsh --profile headless "你的任务"` 一个命令，没有 UI、配置文件或额外参数，普通用户复制一行命令就能跑起来。

## 已知问题与限制
- **只支持一次提交**：runner 没有交互式追问入口，提交完一条任务就等待退出，不支持多轮 follow-up。
- **依赖宿主提供 `ctx.appExit` 钩子**：在没有提供该钩子的宿主环境启动 headless profile 时，激活阶段会抛出"the launcher must provide ctx.appExit before the tree mounts"并失败。
- **不挂载 Web 工具栈**：没有 Host、HTTP、Web runtime 或浏览器插件，无法复用 Web 形态下的任何交互能力（如审批、文件浏览器、扩展 UI）。
- **未发现 TODO/FIXME 注释**：源码中暂无未解决的开发标记。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [pilot-harness](https://deepseek-plugin.org/plugins/op7418/pilot-harness/packages/bundle/headless)
Wiki generated by AI (model: `MiniMax-M3`)