# 交接 Skill 部署（DSH 与 Codex）交付报告

- 交付时间：2026-11-14 01:25（北京时间）
- 来源对话：ChatGPT「设计智能体交接协议」（conversation_id `6af7352f-8050-83e8-b5f6-3f80ed3cb4c0`）
- 安装位置：`/vol1/ai/agents/codex/skills/session-handoff`、`/vol1/ai/home/.dsh/skills/session-handoff`（均软链到 `/vol1/ai/agents/shared/session-handoff`）

---

## 一句话结论

**装好了**：`session-handoff` v1.0.0 已装进 Codex 与 DSH 两个宿主，两边都能被识别并真实触发（DSH 已实测「交接」→ 落盘 + verify 通过，「继续上个对话」→ 恢复通过）；**Codex 侧只差"真跑一次"没做**——它的 5 小时额度已用满（02:52 才重置），报的是配额，不是技能问题。

---

## 一、怎么把内容从分享页拿出来的（关键过程）

你是对的：分享页 curl / 无头 chromium 都读不到正文。实际可行的路子是这样，**内容一个字节没靠猜**：

1. 用 VM 里已登录的 ChatGPT（`gpt` 通道，CDP `127.0.0.1:9230`）打开 `/c/6af7352f-…`，**侧栏里就是原始对话**，比分享页干净。
2. 页面是虚拟渲染的，DOM 一次只给一段；按 `data-turn-key` 累积滚动，拿全 6 轮问答（含 `data-conversation-role` 锚点）。
3. 正文里那两个附件是 `sandbox:/mnt/data/session-handoff-v1.0.zip` 和 `…-install-test-prompt.md`——**ChatGPT 沙盒里的文件，NAS 这边没有直链可下**；点下载链接会落在 VM 的 Windows 磁盘上，NAS 取不到。
4. 于是改走它的私有接口：页面自己用的是
   `GET /backend-api/conversations/<id>?num_turns=50&include_has_versions=true`
   （**复数 conversations**）；直接 `fetch` 会回「请登录以查看此对话」，必须带 `/api/auth/session` 里的 `accessToken` 做 Bearer 头。拿到 486 KB 完整会话 JSON。
5. JSON 里 `container.exec` 那几条消息**就是当时的构建命令**（`cat > …/SKILL.md <<'MD'` 之类，含两次补丁和 zip 打包）。我把这 8 条命令路径改到本地后**原样重放**，复原出整个 skill 包。

**复现证据（不是"应该一致"）**：

| 校验项 | 对话原稿 | 本地复原 |
|---|---|---|
| `session-handoff-install-test-prompt.md` 的 SHA256 | `b9befa9d97c26db2ddc5d25adaf46bb68d7ecf770e6132310d5e1fb917e6d3fe` | **完全相同** |
| ZIP 字节数 | 17,798 | **17,798** |
| ZIP 内 8 个条目清单 | README/SKILL.md/2 assets/2 references/handoff.py/test_handoff.py | **完全一致** |
| 单元测试 | 12/12 | **12/12 OK** |

ZIP 自身的 SHA256 与对话里的 `046577fd…` 不同（本地是 `37f7e701…`），原因只有一个：**zip 打包带时间戳**，同样内容不同时刻打出来哈希必然不同；上面四项已经足以证明内容一致。

---

## 二、Skill 基本信息

| 项 | 值 |
|---|---|
| 名称 | `session-handoff` |
| 版本 | `1.0.0`（对话里叫 v1.0） |
| 会话定稿版本 | 只有一版——第 6 轮「自己来制作这个 skill」产出的 v1.0；前面 5 轮是设计讨论（12 模块 / 三层内容 / 手动触发 / 历史备份），**没有第二版成品**。中间有两次代码补丁（并发前像校验、previous-* 哈希校验），已按顺序重放，属 v1.0 内部修订 |
| 安装后体积 | 100 KB（9 个文件，已清掉 `__pycache__`） |
| SKILL.md | 7,582 B（原稿 7,303 B，差异见第五节） |
| 主脚本 | `scripts/handoff.py` 16,837 B（Python 3.9+，纯标准库） |
| 纯文本 ZIP | 17,798 B，见文末链接 |

功能一句话：在同一项目目录里，旧会话说「交接」把任务状态压成 `.handoff/current.md`（每次更新留历史），新会话说「继续上个对话」只读必要信息接着干。

---

## 三、两个宿主的安装结果

### 路径与实际做法

```
/vol1/ai/agents/shared/session-handoff        ← 唯一实体（canonical）
/vol1/ai/agents/codex/skills/session-handoff -> /vol1/ai/agents/shared/session-handoff
/vol1/ai/home/.dsh/skills/session-handoff    -> /vol1/ai/agents/shared/session-handoff
```

`ls -l` 真实输出：

```
lrwxrwxrwx 1 root root 38 Nov 14 01:05 /vol1/ai/agents/codex/skills/session-handoff -> /vol1/ai/agents/shared/session-handoff
lrwxrwxrwx 1 root root 38 Nov 14 01:05 /vol1/ai/home/.dsh/skills/session-handoff -> /vol1/ai/agents/shared/session-handoff
```

**为什么用软链而不是各放一份**：
1. 这台机器上 22 个 blender 技能、nature 系列技能在 Codex/DSH 都是这么做的（指向 `/vol1/ai/agents/shared/…`），一致；
2. 两边必须"内容保持一致"——两份实体会漂移，软链物理上不可能不一致；
3. 以后升级只改一处，不会出现"DSH 是新版、Codex 是旧版"；
4. DSH 的技能加载器明确 `watchFollowSymlinks: true`（会跟随软链），已实测生效（见下）；Codex 的技能目录本来就是 `~/.codex/skills -> /vol1/ai/agents/codex/skills` 的软链链。

### 文件清单（9 个）

```
/vol1/ai/agents/shared/session-handoff/SKILL.md                        7,582
/vol1/ai/agents/shared/session-handoff/README.md                       1,223
/vol1/ai/agents/shared/session-handoff/调试提示词.md                   3,260
/vol1/ai/agents/shared/session-handoff/scripts/handoff.py             16,837
/vol1/ai/agents/shared/session-handoff/assets/current-template.md      1,014
/vol1/ai/agents/shared/session-handoff/assets/preferences-template.md    424
/vol1/ai/agents/shared/session-handoff/references/content-policy.md    3,287
/vol1/ai/agents/shared/session-handoff/references/operating-notes.md   2,943
/vol1/ai/agents/shared/session-handoff/tests/test_handoff.py           7,148
```

各文件 SHA256：

```
046c488f837f9ffce9ff7cb39f538030226df319e4c4e81a15d6998b292ed41d  SKILL.md
f94b511b596155dde7028d757aaa24c2088880fc9cd597c4b50cb79f76659b65  scripts/handoff.py
a476a7f6cb4b6bed0d683a3713f4e9ca1a2d9daf37ec3f244852011890feaafb  references/content-policy.md
b2bcbd5ea928ab14fff2405d5598e17cc7d2108dd32a5bec5a2bd44570946487  references/operating-notes.md
d527960cbe866254a8cb66f4b9b9c9b50b41867500800b1f7d5fe1ce0750079c  assets/current-template.md
815d3e5662e450429e0a6be44c4be3071ccce039a825404f1cf899c2e7b0c389  assets/preferences-template.md
9c7d047b163a0cad1e71935da6f7668da6ff0eff3f90721e1c585a3d7604e460  tests/test_handoff.py
3585b316c049ae36c0aa97dc39c4e332d1788ed3867654d5d52f2a21ec74d10e  README.md
b9befa9d97c26db2ddc5d25adaf46bb68d7ecf770e6132310d5e1fb917e6d3fe  调试提示词.md
```

---

## 四、识别验证（真实输出）

### 1. Codex：模型侧技能目录里确实有它

Codex 没有 `skills list` 子命令，但有 `codex debug prompt-input`（把模型可见的 prompt 输入渲染成 JSON）。实测：

```
$ codex debug prompt-input "x" | grep -c session-handoff
2
```

目录里的真实条目：

```
- session-handoff: Use when 用户说“交接”“保存当前对话供新会话继续”“继续上个对话”“读取交接”。
  手动会话交接/接力/上下文压缩 Skill：导出精简而可靠的项目任务快照，或从同一项目的 .handoff/current.md 恢复。
  适用于 Codex 或 DSH 的同工具新旧会话。不是跨 Agent 互发消息，不做自动定时保存。
  (file: r0/session-handoff/SKILL.md)
```

`(file: r0/session-handoff/SKILL.md)` 说明它是通过 `$CODEX_HOME/skills` 扫到的，路径对、格式对、被当成可加载技能。

### 2. DSH：用 DSH 自己的发现代码扫了一遍

DSH 没有对外的"列技能"命令（catalog 是喂给模型侧的），所以我直接实例化它自己的 provider `@deepseek-ai/dsh-skill-filesystem`（`watch:false`，只读扫描，不碰运行中的服务）跑了一次真实发现：

```
DISCOVERED 81 skills
MATCH session-handoff: 1
{
  "name": "session-handoff",
  "invocation": { "modelInvocable": true, "userInvocable": true },
  "provider": "filesystem",
  "source": "user-dsh",
  "rank": 400,
  "locator": { "path": "/vol1/ai/home/.dsh/skills/session-handoff/SKILL.md",
               "directory": "/vol1/ai/home/.dsh/skills/session-handoff" },
  "metadata": { "hermes": { "tags": ["交接","handoff","上下文压缩","session","codex","dsh"] } }
}
--- LOADED BODY ---
body bytes: 7063
body head: # Session Handoff — 手动会话接力 ⏎ 目的：在**同一项目目录**内，让旧会话…
```

`source: user-dsh`（rank 400 的用户级目录）、`modelInvocable: true`、正文 7,063 B 能完整读出——识别、解析、加载三段都通。DSH 的 watcher 会自己发现，**没有重启任何服务**。

---

## 五、调试提示词自测（真实触发，不是"应该能触发"）

**先说取舍**：完整那份 `调试提示词.md` 是"安装 + 全套回归 + 真实会话验收"的施工单，里面第 3 步要装到 `~/.agents/skills/`、第 4 步要跑 6 项回归——按你这次的硬约束（只往两个宿主 skills 目录各加一个、别的不许动）我不该让它照单执行全套，那既越界也重复劳动。所以我按那份提示词的**成功标准原文**（"旧会话只需说『交接』…新会话只需说『继续上个对话』…"）做了最轻的真实会话触发。

### 5.1 DSH：只说「交接」

```
$ dsh headless "交接"          # cwd = 临时 git 项目 sh-trigger（app.py + 一次 init 提交）

已保存交接：20261113T171732576294Z-3c3ec8，校验通过。

## 落盘结果
- 快照：…/sh-trigger/.handoff/
  - current.md（3,849 B，sha256 0238753d…41983）
  - history/20261113T171732576294Z-3c3ec8/{current.md, manifest.json}
- 命令与返回：save --agent dsh → "result": "saved"；verify → "verified"，snapshots_checked: 1；
  删掉草稿后再 verify 仍通过。
- 未建 preferences.md：本会话没有用户明确确认过的长期偏好，不把一次性指令升级成偏好。
- 工作树：git status 仅新增未跟踪的 .handoff/，业务文件 app.py 未动，未自动提交。
```

它写出来的 `current.md` 也确实是按技能规范的样子（我抽查过）：

```
## 硬性约束
- [A-001] 本轮只执行"交接"（Export），不顺手继续原安装/验收任务，也不扩展需求。
- [A-002] 交接内容只能写有证据的事实；测试、验收、文件状态无法确认时写"未验证/待核实"，禁止虚构。
- [A-003] .handoff/ 内不得写入令牌、密钥、Cookie 等机密。
```

锚点编号、真实性铁律、不把一次性指令升级成偏好——三条都按 SKILL.md 执行了。

### 5.2 DSH：只说「继续上个对话」（同一项目，新会话）

```
已接管这份交接。先说结论：从 .handoff/current.md 恢复成功，Import 侧首次实测通过；…

| 检查 | 结果 |
| 技能触发 | 本会话输入「继续上个对话」后，技能被识别并加载 |
| status | current_exists=true、history_count=1、latest 与快照 ID 一致 |
| verify | verified，1 个快照，退出码 0 |
| 哈希一致性 | current.md 的 sha256 0238…1983 = manifest.current_sha256 = history 副本 |
| 工作树 | HEAD 仍 f450769 init；仅多出未被 Git 跟踪的 .handoff/ |
按技能规则，Import 时不再生成新快照，也没有改动 current.md。
```

Export → Import 闭环在真实 DSH 会话里跑通了。

### 5.3 Codex：没跑成，卡在额度（如实记录）

```
$ codex exec -s workspace-write --json "交接"
{"type":"error","message":"You've hit your usage limit. Upgrade to Pro … or try again at 2:52 AM."}
{"type":"turn.failed", …}
```

当时的额度实测（`codex_quota_report.py`）：

```
5 小时窗口：已用 100% / 剩余 0%  重置 11-14 02:52（约 1 小时 38 分后）
本周窗口：已用 51% / 剩余 49%    重置 11-19 12:17
计划：plus  账号：qingru2006@gmail.com
```

→ Codex 侧**技能"被列进模型可见目录"已证实**（第四节 1），**"真跑一次"未验证**，原因是配额，不是技能。另外记一笔：`codex exec` 直连 chatgpt.com 是 000，必须带 `HTTPS_PROXY=http://127.0.0.1:7890`（代理下 401 = 通），否则会一路 `workspace routing discovery timed out`。

---

## 六、调试提示词

全文原样存在：`/vol1/ai/agents/shared/session-handoff/调试提示词.md`（3,260 B，SHA256 `b9befa9d…d3fe`，与 ChatGPT 原稿逐字节相同）。
SKILL.md 末尾新增了一节 `## 安装与实机调试` 指向它。

它包含的部分：任务要求 7 条（先核实输入/核查兼容性/安全安装/先执行测试含 6 项回归/真实会话测试/发现问题直接修复并回归/最终交付要求）+ 成功标准。

---

## 七、与对话原稿的差异（逐条）

只动了 frontmatter 和一句指针，**正文条款一条没删、没改、没加功能**：

1. **加了 `version: 1.0.0`** —— 原稿 frontmatter 只有 name/description；按你要求补 version 字段（对话里称 v1.0，写成 SemVer 形式）。
2. **加了 `metadata.hermes.tags`** —— `[交接, handoff, 上下文压缩, session, codex, dsh]`，同样是按你要求补的，不影响 DSH/Codex 解析（DSH 把 metadata 当 open YAML 收下，已实测读得到）。
3. **description 改写为首句触发式** —— 原句是"手动会话交接/接力/上下文压缩 Skill。用户说……时导出……；用户说……时恢复……"。为了满足"第一句是自包含触发条件 `Use when …`"，把它重排成
   `Use when 用户说“交接”“保存当前对话供新会话继续”“继续上个对话”“读取交接”。手动会话交接/接力/上下文压缩 Skill：导出精简但可靠的项目任务快照，或从同一项目的 .handoff/current.md 恢复。适用于 Codex 或 DSH 的同工具新旧会话。不是跨 Agent 互发消息，不做自动定时保存。`
   **原有六个语义块全部保留**，没有新增任何能力描述；长度 162 字符（上限 1024）。
4. **SKILL.md 末尾新增 4 行 `## 安装与实机调试` 指针** —— 指向 `调试提示词.md`（你要求的"在 SKILL.md 里指向它"）。除这两处外，SKILL.md 与原稿 `diff` 为空。
5. **安装文件名**：原附件名 `session-handoff-install-test-prompt.md` → 改叫 `调试提示词.md`（内容一字未动，SHA256 相同）。
6. **安装路径**：原稿提示词第 3 步建议 `~/.agents/skills/`，按你这次的指定装到 `$CODEX_HOME/skills` 和 `~/.dsh/skills`（软链到 shared）。提示词正文里那句话**我没改**，所以它仍写着 `~/.agents/skills/`——这是对话原稿的表述，保留原样。

---

## 八、未核实项 / 遗留

1. **Codex 真实会话触发未验证**（配额满，02:52 后重置）。补跑方式：`HTTPS_PROXY=http://127.0.0.1:7890 codex exec -s workspace-write "交接"`，在任一 git 项目里，看是否生成 `.handoff/`。
2. **Codex 侧只验证了"能列出来"，没验证"能否在弹出的会话里真正 load 正文并执行"**——和上一条同一件事。
3. **DSH 非交互 headless 模式下的技能发现**：这次就是在 headless 下跑通的（两次），但**网页/桌面 profile 里是否同样自动加载没单独测**（watcher 会看同一目录，理论上一致）。
4. **导出 ZIP 的 SHA256 与对话原稿不同**（时间戳差异，见第一节），只保证内容一致，不保证二进制一致——如果你要跟原稿哈希对账，用 ChatGPT 页面上的下载拿原件。
5. **副作用（不是我主动做的）**：DSH 那两次真实运行里，它自己按平时习惯往 `/vol1/ai/agent-kb/` 写了两个文件（对话记忆 + 流程复现），还提议 02:55 自动补跑 Codex 验收——我**没有**批准任何自动补跑。

## 九、边界自查

- Hermes 自己的 skills：**没动**（`<available_skills>` 里没有 session-handoff，也没写进 Hermes 目录）。
- DSH / Codex 其他配置：**没动**，只往两个 skills 目录各加了一个软链（目录里原有条目 unlink 都没发生）。
- 服务：**没有重启** dsh / codex-web / gateway（DSH 自己 watch 到新目录，无需重启）。
- 消息：没有对外发布任何东西，没发邮件。
- 测试产物都在 `cache/scratch` 下（`sh-testproj`、`sh-trigger`、`build/`），要清可以直接删。

## 十、复现用的脚本（我自己加的，供下次照抄）

- `/vol1/ai/_scripts/cdp-await.js` —— 在已打开页面里执行 async 表达式（`awaitPromise`），拿去 `fetch` 带 token 的私有接口。
- `/vol1/ai/_scripts/cdp-hook-net.js` —— 重载页面抓所有 `/backend-api/` 请求，用来找"页面到底调哪个接口取数据"。
- `/vol1/ai/_scripts/cdp-hook-download.js` —— 点下载链接并监听网络（这次没用上，沙盒文件没有可下的 URL）。
- 抓取/解析/重放的临时脚本：`cache/scratch/{fetch_conv.js,parse_conv2.py,extract_code2.py,replay_build.py,install_skill.py,dsh_skill_probe.mjs}`

**下次遇到"ChatGPT 分享页读不到正文"**：直接用 VM 已登录会话打开原对话 → 拿 `/api/auth/session` 的 accessToken → `GET /backend-api/conversations/<id>?num_turns=50&include_has_versions=true`。`sandbox:/mnt/data/...` 的附件不用找下载链接，`container.exec` 的构建命令原样重放就能复原件。
