# OpenCode Delegate skill 安装记录（DSH）

- 日期：2026-10-24 02:14–02:23（北京时间）
- 结论：**已安装、已被 DSH 热发现、relay 机制已用上游测试套件 + 一次真实派发验证**；真实生成这一环被 **OpenCode 官方按 IP 拦截免费模型（HTTP 403 FreeTierError）** 挡住，属账号/网络侧授权问题，**不是安装问题**（下一节给出证据与解法）。

## 1. 装在哪

| 项 | 值 |
|---|---|
| 安装路径 | `/vol1/ai/home/.dsh/skills/opencode-delegate/`（DSH 用户级技能目录） |
| 内容 | 6 个文件 / 88,819 B（`SKILL.md` + `scripts/relay.mjs` + `references/` 4 篇） |
| 入口 | `SKILL.md`（name: `opencode-delegate`，metadata.version 0.5.0，license MIT） |
| 权限 | `drwxr-xr-x root:root`，与其他用户级技能一致 |
| 安装方式 | `git clone --depth 1` 上游后，把**完整** `skills/opencode-delegate/` 目录整包拷入（不是只拷 SKILL.md） |

没有装第二份到 `/vol1/ai/home/.agents/skills/`（那里是 symlink 池，本机自装技能惯例只放 `.dsh/skills/`），也没有放项目级 `.dsh/skills/`，避免同一技能两份、agent 读到旧版。

## 2. 来源

| 项 | 值 |
|---|---|
| 仓库 | https://github.com/amElnagdy/delegate-skills |
| 定位 | "delegate-skills"：把编码任务派给另一个 CLI 实现者（18 个实现者技能 + `delegate-setup` 车道配置 + `codex-background` 等待边界） |
| 本次安装的板块 | `skills/opencode-delegate`（即用户说的「opencode 板块」） |
| 提交 | `3aa72d681a79e2a9d09bd9a316353003ae1cb4a7`（2026-10-14，`Merge pull request #145 …`） |
| 版本 | skill 元数据 `0.5.0`；relay 自述「Verified against opencode CLI v1.17.13」 |
| 许可证 | MIT |
| 依赖 | Node 18+、git、已安装并已登录的 `opencode` CLI；relay 本体零 npm 依赖（只用 Node 内置模块 + 调 `opencode`/`git` 两个外部命令） |

## 3. 校验证据（都实跑了）

1. **逐文件完整性**：安装树与上游 `skills/opencode-delegate/` 逐文件 sha256 全等，**6/6 一致**；
   安装树清单摘要（对 `sha256sum` 排序结果再取 sha256）= `5c8646c453daaa8e884a2092a4906847f5f88b2f962aaa3993965f0a759c9000`。
2. **DSH 发现**：拷完目录后 DSH 的 skill-filesystem watcher 立即热更新技能目录，本会话的可用技能列表**当场出现 `opencode-delegate`**（无需重启 GUI / 无需新会话）。
3. **加载**：`skill` 工具按名字加载成功，返回的 base directory 正确指向 `/vol1/ai/home/.dsh/skills/opencode-delegate`，正文完整（5 步 loop + 权限/授权模型 + 4 篇 references）。
4. **relay 可执行**：在**安装目录内**直接跑 `node scripts/relay.mjs --help` → exit 0，完整打印 32KB 脚本的用法（`--brief/--cd/--model/--agent/--read-only/--resume-last/--session/--timeout/--lane/--no-auto/--pure/--out-dir`）。
5. **上游测试套件**（在临时 clone 里跑，安装内容与之逐字节相同）：
   `node test/relay-smoke.mjs --only opencode,package-shape,syntax` → **146 项 ok、all green**。覆盖：opencode 1.x 的 `--variant` 独立开关、2.x 的 `provider/model#variant` 合并、plan/read-only 不传 `--auto`、`--variant` 缺 `--model` 的用法错误、模型 id 里 `@cf/`/`@default`/`~latest` 原样透传、`--pure` 在 2.x 被拒、事件流解析（session/text/cost/model/variant/agent/auto/resumed/touchedFiles）等。
6. **环境实测**：`opencode --version` = **1.19.4**（`/mnt/ssd/apps/nodejs_v24/bin/opencode`），node v24.15.0，git 2.39.5；`opencode auth list` 显示 **1 条凭据：OpenCode api**；`opencode models` 正常列出 zen 模型（含 `opencode/deepseek-v4.1-flash-free` 等免费项）。注意 relay 针对 1.x 走「`--variant` 作为独立 flag」分支，1.19.4 实测派发参数正确。
7. **真实端到端派发（一次）**：用安装后的 relay 对一个临时 git 仓库跑 `--read-only`（plan agent）小任务：
   - 结果：opencode 进程被正常拉起、参数正确、`sessionId = ses_e95ffcd59ffen6eIqtcizKi1Oh`、事件流被解析，`result.json` 写出且 `status: failed`、`exitCode: 1`。
   - 根因（事件流里的原始报错，直接 `opencode run` 复现同样）：
     `APIError 403 FreeTierError — "OpenCode's free models aren't available from your current network because we've detected abusive traffic from this IP address. This isn't related to your account. … subscribe to OpenCode Go at https://opencode.ai/go"`
   - 判读：**派发链路（版本探测 → argv → 事件解析 → result.json → session 续跑 id）全通**；被拒的是**模型供给侧**（这台机器的出口 IP 被 opencode.ai 风控）。临时代码仓库与临时 clone 已全部删除。

## 4. 沙箱/文件权限的坑（重要）

本会话最初是 `workspace-write`，此时 `opencode auth list` / `opencode models` / `opencode run` 全部报
`Error: Unexpected error / Unknown: FileSystem.open (/vol1/ai/home/.local/share/opencode/log/opencode.log)`
——因为 opencode 需要**写** `~/.local/share/opencode/`（log + `opencode.db`），而 workspace-write 下该路径是只读。
切到 `danger-full-access` 后同一条命令立刻正常。

**结论：真要在 DSH 里跑 opencode 派发，会话的文件权限必须允许写 `/vol1/ai/home/.local/share/opencode/`**（否则 relay 会以 `failed` 收场，且 stderr 里只有这一条 FileSystem 报错）。只装技能、不实际跑，则 workspace-write 也能装（本记录里的安装就是先被拒、放权后完成的）。

## 5. 怎么用

### 触发方式

直接对话里说，例如：

```
让 OpenCode 把 xxx 模块重构成 yyy，改完把 diff 给我，我来 review 和提交。
```

DSH 会命中 `opencode-delegate` 技能（描述里覆盖 "have OpenCode do X / delegate this to OpenCode / run it through OpenCode"），
然后按技能里的 5 步走：写 brief → 用 relay 派发 → 等完成 → 自己复核 diff/跑 gates → 自己 commit。

### 手动派发命令

```bash
node /vol1/ai/home/.dsh/skills/opencode-delegate/scripts/relay.mjs \
  --brief brief.txt \
  --model opencode/<model> \
  --cd /path/to/repo
```

| 选项 | 作用 |
|---|---|
| `--model <provider/model>` | **新开跑必填**（OpenCode 没有安全默认模型）；续跑会继承原 session 的模型 |
| `--read-only` | 用 `plan` agent，只读复核/诊断，不改工作树（且不传 `--auto`） |
| `--resume-last` / `--session <id>` | 续上一次/指定 session，只发增量 brief |
| `--timeout 2h` | relay 侧看门狗，超时杀整棵进程树并把 `status` 记为 `timeout` |
| `--lane <name>` | 车队车道（需另装 `delegate-setup` 并生成配置；**本次未装**） |
| `--no-auto` | 不传 `--auto`，尊重 agent 自己的 allow/ask/deny（headless 下可能卡在 ask） |
| `--pure` | 不加载外部插件（仅 1.x；2.x 会拒绝） |

产物：`<out-dir>/result.json`（status/exitCode/sessionId/finalMessage/touchedFiles/cost 等）+ `events.jsonl` + `final.txt`；默认 out-dir 在系统临时目录，**不动被 review 的仓库**。relay **从不 commit**。

### 本机可用模型（当前）

- `opencode/*` zen 模型：免费档（`*-free`）**当前被 IP 风控 403**；付费/订阅档需要先 `opencode auth login` 或订阅 OpenCode Go。
- 想换个 provider：`opencode auth login` 加凭据，然后 `--model <provider>/<model>`，用 `opencode models` 查准确 id。

## 6. 本次没装的相关板块（按需再装）

| 技能 | 作用 | 本次是否需要 |
|---|---|---|
| `delegate-setup` | 发现本机已装实现者 CLI、提议并写入「车道」(fleet lanes) 配置；只配置不派发 | 只有想用 `--lane` 才需要 |
| `codex-background` | 让 Codex 侧把派发挂起等待（MCP 工具 `delegate_run`/`delegate_wait`） | 只有 Codex 做编排才需要；DSH 走 shell + 后台任务即可 |

## 7. 更新与卸载

```sh
# 更新：重新克隆到所选 revision，整包替换（不要新旧文件混着合并）
git clone --depth 1 https://github.com/amElnagdy/delegate-skills /tmp/delegate-skills
rm -rf /vol1/ai/home/.dsh/skills/opencode-delegate
cp -a /tmp/delegate-skills/skills/opencode-delegate /vol1/ai/home/.dsh/skills/opencode-delegate

# 卸载：只删这一个目录
rm -rf /vol1/ai/home/.dsh/skills/opencode-delegate
```

DSH 的 watcher 会自动感知目录变化，更新/卸载都不需要重启。

## 8. 文件清单与 sha256

| 文件 | 字节 | sha256 |
|---|---|---|
| `SKILL.md` | 11,461 | `f9f754136c0acabb037465da167fe4787a2c332d0c44535da8976905b02c7711` |
| `scripts/relay.mjs` | 32,195 | `86c9b3b0e47a661a5df1760fc235f01985d7bc1923eab0f966e61fd2f590590b` |
| `references/dispatch-and-poll.md` | 7,971 | `e95e4158c7f8541d942c9af0995c4bfeed83d8e5e8ee02883b190ea0574919b0` |
| `references/multi-task-queues.md` | 3,122 | `097b2c52997235a20cb82c13cdc5695aef0afffb283bd124b6944c40a51fefe1` |
| `references/review-and-land.md` | 6,203 | `4a449c732d9f023fc26106d46b8a9de6624421bf59ddbec3fb97ea7c0f72f698` |
| `references/writing-the-brief.md` | 7,867 | `20f33825a1b484bccad7352e99d7749c13cd1a32499c32e1bb216acbbdc23d36` |

> 上游 SKILL.md 在 `references/writing-the-brief.md` 里给的键用 `openai/gpt-...` 等示例模型，只是格式示例；实际用哪个模型由机主授权。

## 9. 备注

- 该仓库是一个 **Skills CLI 包**（`npx skills add amElnagdy/delegate-skills`），但本机是 DSH 的目录式技能发现，直接整包拷目录最稳，且能逐文件比对上游。
- 技能默认假设编排者是 Claude Code / Codex；DSH 属于"任意能跑 shell + 读文件的编排者"，用法等价：`run_in_background` 跑 relay，完成后读 `result.json`（DSH 的 bash 后台任务天然贴合）。
- 安全口径（技能原文）：`build` agent 默认带 `--auto` 自动批准、写能力全开；`plan`（`--read-only`）不给 `--auto`。**复核与提交永远是编排者（DSH/你）的责任**，`result.json` 里的自述不能当证据。
