# session-handoff 安装与实机验收报告

验收日期：2026-11-14（北京时间）。测试只在独立验收目录进行；未修改 little-town 归档、wyszz-new 或其他业务项目，未改服务配置。

## 输入与安装

- 输入 ZIP：17,798 字节，SHA256 `046577fd5027eac7d2bd80c0dbe36232a3ec0076bd38deda4adf66bb71dfd92c`。
- 已实际解压检查：顶层 session-handoff/SKILL.md、scripts/handoff.py、references/、assets/、tests/ 均完整（8 文件）。
- HOME=/vol1/ai/home，CODEX_HOME=/vol1/ai/agents/codex；Codex CLI 0.167.2，DSH npm 包 0.2.1-rc.2。DSH 启动封装也将 HOME 指向 /vol1/ai/home，未发现本次安装目标存在客户端 HOME 分歧。
- 新安装：`/vol1/ai/home/.agents/skills/session-handoff/`。
- 原 Codex 入口 `/vol1/ai/agents/codex/skills/session-handoff`、DSH 入口 `/vol1/ai/home/.dsh/skills/session-handoff` 均保留，经过 `/vol1/ai/agents/shared/session-handoff` 软链接指向新安装。
- 旧版备份：`/vol1/ai/agents/shared/session-handoff.backup-20261114-1634/`；验收目录另有 backup-installed/。先比较后安装；原版相对输入包仅增强触发元数据、增加安装调试提示词，本次均保留。
- 安装时跨盘 rename 失败 Errno 18，未覆盖原目录；改用源目录同盘改名备份后安装成功。
- frontmatter 包含 name、description，保留本机原有触发描述，版本更新为 1.0.1。DSH headless 的 dsh-base 实际启用 skill、skill-filesystem、tool-skill；实际调用日志有 `skill(name="session-handoff")`，不是仅测试文件可读。
- 参考：[OpenAI 官方技能文档](https://learn.chatgpt.com/docs/build-skills)。文档不能代替以下实机触发证据。

## 测试与根因修复

命令（技能根目录）：`python3 -m unittest discover -s tests -v`。

| 阶段 | 测试数 | 退出码 | 结果 |
|---|---:|---:|---|
| 原包基线 | 12 | 0 | 全通过 |
| 新增回归用例，修复前 | 13 | 1 | 1失败，复现恢复无偏好旧版本却保留当前偏好 |
| 修复后 | 13 | 0 | 全通过 |
| 安装后同命令 | 13 | 0 | 全通过 |

根因：save_locked 把 new_prefs=None 一律解释为“继承现有偏好”，restore 到没有偏好文件的旧快照时也走此分支。修复只让普通 save 继承现有偏好；restore 按目标快照恢复“文件不存在”的状态。回滚前偏好保存在新历史 previous-preferences.md，旧历史仍保留。新增测试同时验证活动偏好消失、原历史保留、前镜像存在及全历史校验通过。未引入依赖。

完整失败记录（实际首次失败输出）：

```text
test_anchor_drift_rejected (test_handoff.HandoffTests.test_anchor_drift_rejected) ... ok
test_archive_tampering_detected (test_handoff.HandoffTests.test_archive_tampering_detected) ... ok
test_explicit_anchor_change_allowed_logged (test_handoff.HandoffTests.test_explicit_anchor_change_allowed_logged) ... ok
test_first_save_and_verify (test_handoff.HandoffTests.test_first_save_and_verify) ... ok
test_lock_prevents_simultaneous_save (test_handoff.HandoffTests.test_lock_prevents_simultaneous_save) ... ok
test_missing_headings_rejected (test_handoff.HandoffTests.test_missing_headings_rejected) ... ok
test_missing_preferences_can_be_created_later (test_handoff.HandoffTests.test_missing_preferences_can_be_created_later) ... ok
test_restore_to_snapshot_without_preferences_removes_active_preferences (test_handoff.HandoffTests.test_restore_to_snapshot_without_preferences_removes_active_preferences) ... FAIL
test_rollback_is_new_snapshot_and_keeps_later (test_handoff.HandoffTests.test_rollback_is_new_snapshot_and_keeps_later) ... ok
test_snapshot_id_path_traversal_rejected (test_handoff.HandoffTests.test_snapshot_id_path_traversal_rejected) ... ok
test_symlink_handoff_directory_rejected (test_handoff.HandoffTests.test_symlink_handoff_directory_rejected) ... ok
test_tampering_blocks_save_and_verify (test_handoff.HandoffTests.test_tampering_blocks_save_and_verify) ... ok
test_two_round_handoff_preserves_old_snapshot (test_handoff.HandoffTests.test_two_round_handoff_preserves_old_snapshot) ... ok

======================================================================
FAIL: test_restore_to_snapshot_without_preferences_removes_active_preferences (test_handoff.HandoffTests.test_restore_to_snapshot_without_preferences_removes_active_preferences)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/vol1/ai/home/session-handoff-validation-20261114/session-handoff/tests/test_handoff.py", line 138, in test_restore_to_snapshot_without_preferences_removes_active_preferences
    self.assertFalse((self.root / ".handoff/preferences.md").exists())
AssertionError: True is not false

----------------------------------------------------------------------
Ran 13 tests in 0.964s

FAILED (failures=1)

```

独立临时空项目回归：`python3 /vol1/ai/home/session-handoff-validation-20261114/regression.py`，退出码 0。覆盖：

1. 首次 save 创建 current.md、history/<id>/ 和偏好，verify 成功。
2. 第二次 save 更新进度与确认偏好，第一次历史 SHA256 不变。
3. 故意遗漏 A-001，save 返回 2，旧 current 字节不变。
4. 篡改 current 后 verify、save、restore 均返回 2；历史未被覆盖。
5. 测试脚本恢复人为篡改前的原始字节（这是受控测试清理，不是自动恢复功能），再 restore 到首版成功，生成第三个历史且保留第二版与回滚前镜像。
6. 模拟 Import 运行 status/verify 后仅加载最新 current 正文，未加载所有历史；verify 本身读取最新归档校验哈希属于内部校验。

## 真实客户端测试

这是实际启动 Codex CLI / DSH headless 独立模型会话，不是直接运行 handoff.py 冒充客户端触发；未覆盖桌面/网页交互界面。

### Codex

- 旧会话：`01a1d92d-f733-7d40-be27-53881db7872e`。
- 新会话：`01a1d92f-adb7-7f81-87e5-8b21a3af79fe`，独立 codex exec，只输入“继续上个对话”，未 resume/fork 旧会话。
- 旧会话自动发现技能后实际读取 SKILL.md、调用 save、verify（退出码0）；新会话实际调用 status/verify、读取 current，创建 resumed.txt 并读取校验内容为 HANDOFF_RESUMED（退出码0）。新会话未读取历史正文，未再次保存交接。
- 首次验收指令“只允许读写当前目录”误把用户级技能读取也禁止了，旧会话正确报告未生成文件；明确允许读取技能后在同一旧会话重试成功，未把失败记成成功。
- 交接 current 为 1,474 UTF-8字节；新会话读取最新快照，不重载旧对话。输入 token 日志是多次模型请求累计，包含宿主技能/全局规则，不能据此宣称总 token 节省比例，未做对照基准。

### DSH

- 旧会话：`session-8ab5f464-10bf-4369-9885-c556d4eb1f9d`。
- 首次 run：`20261114-163031-e35d0b`；纠正后 run：`20261114-163342-32d3c3`，均 done、退出码0，实际 skill 工具发现并触发。
- 首次发现两处模型行为偏差：把“结论优先、提供命令依据”扩写成未经确认的用户偏好；为把快照ID/验证状态写进正文多次保存。本次收紧 SKILL.md：偏好须附用户原话/明确确认来源；禁止预写新快照ID与未执行结果，最终结果放脚本输出与最终汇报。纠正后重新加载技能并 Export，偏好只保留明确原话，无快照ID预写，全历史 verify --full 成功，6份历史全部保留。
- 独立新会话：`session-acb55aca-86f7-428a-88c7-06505ae17d67`；run `20261114-163530-33d616`，未传旧 session_id，仅输入“继续上个对话”。结果 done、退出码0；实际调用技能、status/verify，读取 current.md 与 preferences.md，未读取历史正文；创建 resumed.txt 并核验为 HANDOFF_RESUMED（15字节、无换行）。主验收进程再次读取并断言相同；Import 后仍为6份历史，没有再次保存交接。

## 限制

- 历史哈希用于检测内容不一致，不是数字签名；不能防止有写权限的恶意进程同时重写内容与 manifest。
- 脚本不能从自然语言证明“偏好确由用户确认”或“permit 参数已获授权”；依赖执行模型遵循技能规则。DSH 行为经人工纠正后通过，不能保证以后永不推断。
- 不测试 Windows、Python 3.9、断电/磁盘满故障、GUI 内触发和长对话压缩保真；本次 Linux/Python 环境通过不能代表全部平台通过。
- current 被外部篡改时 restore 同样拒绝；需要先保留异常文件并核对证据、按明确授权处理不一致，技能不会自动绕过保护。
- 保持现有机器协议的 UTC 快照ID与 created_utc 字段兼容；本报告和人工记录用北京时间。
- 未来客户端刷新/重启后的长期稳定性未作持续监测；本次新启动的 CLI/headless 会话发现与触发有实证。

## 文件与本地证据

修订 ZIP：`/vol1/ai/home/session-handoff-validation-20261114/session-handoff-v1.0.1.zip`
大小：20,521 字节。
SHA256：`04901316e3e43397b015a4457fe3f285858d5ce714e8272675958da4e5b6cbc3`。
已校验 ZIP CRC，包含完整技能源码、模板、参考文档、13项测试与安装调试提示词，不含缓存、凭据或会话记录。

原始测试与客户端日志保留在 `/vol1/ai/home/session-handoff-validation-20261114/`；DSH事件在相应 `/vol1/ai/dsh-runs/<run_id>/events.ndjson`。这些原始日志不对外分发。知识库按本场唯一对话与流程另行留痕。
