万象-会话交接与任务迁移

> 一句话：在上下文被压掉之前，把"现在在哪、下一步做什么"变成磁盘上的事实。

🔴 注意事项（硬约束 · 2026-09-23 立）

当任务上下文使用量达到阈值（默认 90%）时，不得中断或影响当前正在执行的任务。
阈值只表示"该准备交接了"，不表示"可以停下来"；相应的处理仅在当前任务执行完成后才触发。

可核验判据：PreCompact 事件只写 .workbuddy/relay/pending.json；
交接文档只在 Stop / FinalStop 里产出。relay.log 会分别留下
PreCompact -> 仅登记待处理标记（不打断任务） 与 Stop -> handoff ... 两行。

为什么立这条：交接的目的是不丢进度；若为交接而打断正在跑的任务，
就变成"为了保住进度而破坏进度"。压缩是系统的动作，交接是我们的动作 ——
系统可以打断，我们不可以加码。

一 · 适用与路由

本技能是任务辅助总入口，进来先分流到三条线：

★ 三线的执行前提不同，这是本技能最要紧的一条：

> 拿 A 线的时机去改库，会截断会话历史 —— 这是本技能最容易犯的错。

什么时候不用：

先判一句：要换会话、要挪任务、要并任务（三者之一）才进本技能；否则不进。

与 C 篇的关系（重要，含一处推翻）：
omni-delivery-handoff §C1 曾断言「别指望"上下文水位"信号，本机没有可靠的 token 计数器暴露给模型」。
该结论部分被推翻（2026-09-23 实测）：模型自身确实看不到水位，但脚本能读到 ——
transcript 每条 message 带 message.usage.input_tokens（本轮会话实测 46,572 → 144,372 单调递增）。
所以正解不是二选一，而是两条一起用：C 篇负责"始终最新"，本技能负责"跨窗口时不留死角"。

二 · 三条线的工作流

A 线 · 会话接力

1. 测水位 —— 读 transcript 最后一条 usage，除以窗口上限 → 产出水位百分比。判据：拿到 used / window / pct 三个数。
2. 判触发（只在任务执行完成后） —— pct ≥ threshold_pct（默认 90） 为真，且当前时点是 Stop / FinalStop（本轮任务已跑完）。
   若此刻是 PreCompact（可能落在任务中途）→ 只登记待处理标记，不生成任何文档（见文首注意事项）。
   判据：relay.log 能区分"仅登记"与"已生成"两种行。另外有 5 个百分点节流（regen_step_pct），防止每个回合都刷文档。
3. 抽事实 —— 从 transcript 机械提取：产出物（Write/Edit 的 file_path）、命令（Bash/PowerShell）、任务、读过的对象；从三维记忆文件读标题索引。判据：每条都能回指到源文件行。
4. 成文 —— 填八节骨架，机械段标「⚙️ 自动」，语义段留「✍️ 待补」占位。产出 <工作区>/会话交接.md + .workbuddy/relay/history/<时间戳>.md 归档 + .workbuddy/relay/latest.json 指针。
5. 补写 —— 模型补全「✍️ 待补」五段（目标/进度/待办/决策/坑）。判据：五段都不再含 待补 字样。
6. 接续 —— 新会话里跑 prompt 把「读 <路径> + 复述回读」发给接续者。

# 测水位（人工随时可跑）
python <技能目录>/scripts/relay.py probe --cwd "<工作区绝对路径>"

# 手动生成交接（用户说"上下文满了"时）
python <技能目录>/scripts/relay.py build --cwd "<工作区绝对路径>" --trigger manual

# 打印接续提示词（发给新会话的第一句）
python <技能目录>/scripts/relay.py prompt --cwd "<工作区绝对路径>"

# 冒烟测试
python <技能目录>/tests/smoke_test.py --cwd "<工作区绝对路径>"

// hooks/hooks.json 的三条接线（PreCompact / Stop / SessionStart）
{
  "PreCompact":  [{ "hooks": [{ "type": "command",
      "command": "python \"${CODEBUDDY_PLUGIN_ROOT}/scripts/relay.py\" hook", "timeout": 30 }] }],
  "Stop":        [{ "hooks": [{ "type": "command", "command": "... relay.py hook", "timeout": 30 }] }],
  "SessionStart":[{ "hooks": [{ "type": "command", "command": "... relay.py hook", "timeout": 20 }] }]
}

# 核心判据（scripts/relay.py · compute_usage 的等价简化版）
used   = int(last["message"]["usage"]["input_tokens"])  # 累积上下文，非单轮增量
window = int(cfg["context_window"])                     # 默认 200000
pct    = used * 100.0 / window
trigger = pct >= cfg["threshold_pct"]                   # 默认 90
# 注意：cache_read_input_tokens 是 input_tokens 的子集，不可相加

B 线 · 任务位置迁移

归属键只有一个：sessions.cwd（侧栏按它分组）。以下两处须保持一致，脚本会一并纳入修订：

转写规则 = 盘符小写 + : \ / 一律转 - + 合并连续 -（<盘>:\workbuddy\X → <盘>-wordbuddy-X）。实测 41/41 命中。

硬判据：sessions.status = working 一律拒绝迁移（不得中断正在跑的任务）；
运行中守卫（2 分钟内有心跳即中止）；移动用 os.replace 而非 shutil.move；
逐文件 sha256；目标同名拒绝覆盖；每次运行写独立快照可回滚。

它解决的实景问题：库内同一工作区可能同时存在 D:/x/y 与 D:\x\y 两种写法 → 侧栏显示成两个空间分组。
normalize 只改库里的字符串、不搬任何文件（两种写法生成的槽位名相同）。实测本机有 2 处此类重复。

C 线 · 任务合并与归档

完整方案见 references/任务合并方案.md（判定标准 / 三层保留 / 原任务处理三问的正式答案）。要点：

• 判定：C1 同空间（硬判据）+ C2 标题 2-gram Jaccard ≥ 0.35 + C3 首条真实诉求 Jaccard ≥ 0.35；
  「强建议」= C1 且（C2 或 C3）；成组用 Kruskal + 单组上限 8（朴素并查集有连通传染，实测连出过 48 条）。
• 标题要从数据库补（默认开，--no-db 关）：自动化会话的 jsonl 里没有标题，只靠文件侧会整批被跳过（实测跳掉 46 份）。
• 三层保留：L1 索引进新任务（3–10k token）/ L2 全文逐字节副本留 sources/ / L3 按需检索。
  绝不拼接会话文件 —— 实测两条就 226,027 token，拼接后新任务开局即超窗。
• 原任务处理：pack 完全不动原任务；要让它从侧栏消失用 archive（默认 --mode deleted，
  因为 deleted_at 是有实证的隐藏开关，archived 的效果从未验证）。
• 本技能的脚本不写宿主数据库：数据库一律以只读方式打开（mode=ro / immutable=1）读取现况；
  一切改动只生成 .sql 修订脚本（同时产出 .undo.sql 可一键还原），
  由使用者在应用完全退出后用 sqlite3 CLI 执行。脚本不做任何直连写入。
  护栏：改前整组备份（db + -wal + -shm）＋ 字段级快照 ＋ 按 run 归档可回滚。
• 🔴 pack 成功 ≠ 合并生效（2026-09-24 实测）：两步不自动衔接，pack 收尾只会提示你去确认。
  用户报「昨天合并了但列表还是 N 条」时，先查 deleted_at 是否非空 —— 为 None 即归档从未执行，
  不是异步/缓存/前端未刷新。排查口径见 references/任务合并方案.md §3.1。
• 🔴 自动化日报是「序列」不是「重复」（2026-09-24）：每天定时新建同名会话（如 07:30 日报），
  因 judge() 不按创建时间判重，会被判为「强建议 / 标题相似 1.00」。
  ⇒ 归档只是止血，今天归档明天再生一条。判据：问「删掉它明天会不会又出现」 ——
  会 ⇒ 是序列，需从自动化侧收敛（固定会话续写 / 定期批量归档）。详见 §5.1。

R="<SKILL_DIR>/scripts/task_merge.py"
python "$R" scan                                    # 扫候选（只读）
python "$R" plan   --ids A --ids B                  # 预览方案（只读）
python "$R" pack   --ids A --ids B                  # 生成合并包（不动原件）
python "$R" verify --pack "<包目录>"                 # 校验完整性
python "$R" archive --ids A --ids B --pack "<包>"    # 生成归档 SQL（不改库）

# ↑ archive 只出脚本，要生效须手工三步：
#   ① 备份 workbuddy.db / -wal / -shm 三条
#   ② 完全退出 WorkBuddy（托盘也退）
#   ③ sqlite3 "$USERPROFILE\.workbuddy\workbuddy.db" < <生成的 .sql>
python "$R" restore --run last                       # 生成还原 SQL（同样手工执行）

四条实测坑：① 旧会话首条 user 消息常是宿主注入的提示词，不过滤会让所有会话"标题相似 1.00"；
② 缺标题必须留空串（共用占位符会算成完全相似）；③ <conversation_history_summary> 类标记会混进标题；
④ archived 与 deleted_at 是两套独立机制（archived 那 18 条的 deleted_at 全为空）。

三 · 失败模式与踩坑

• 失败 1（实测）：内联 python -c 写含中文/引号的内容会被 Git Bash 当命令执行、退出码仍为 0。→ 一律 Write 成 .py 再跑；本次冒烟测试脚本 tests/smoke_test.py 就是这个定式的产物。
• 失败 2（实测）：VAR=x; cmd && cmd 这类复合命令在本机沙箱直接报 sandbox-center cmd decisionRecord missing actual resource subject。→ 拆成单条命令，或写成脚本文件。
• 推翻条件：若日后客户端把 usage.input_tokens 改成按"本轮增量"计（而非累计），则 compute_usage 的判据失效 → 改为对 usage_seq 做差。
• 边界：本技能保证"文档里有真事实"，不保证"文档写得全" —— 语义段落（目标/决策/待办）靠模型补写，漏写时接续者必须回头问用户。

四 · 检查点

🔴 CHECKPOINT 0 · 不打断任务（最高优先级）：生成动作只能出现在 Stop / FinalStop。
PreCompact（可能落在任务中途）只允许登记标记。违反即视为本技能失败 —— 判据见文首「注意事项」。

🔴 CHECKPOINT 1 · 生成前：确认 is_substantial 通过（工具调用 ≥5 或用户轮数 ≥2）。过短的会话不生成 → 避免在工作区堆噪声文件。

🛑 CHECKPOINT 2 · 交付前：交接文档必须满足三条 —— ① 八节标题齐；② 元信息段的水位与时间戳非空；③ 「✍️ 待补」段落已补写或已被显式标注"未补写"。缺项先别交付。

破坏性操作：会覆盖工作区根的 会话交接.md（每次覆盖，历史留归档）。除此之外无删除行为。首次运行前建议确认工作区根没有同名文件。

五 · 反例黑名单与红线

• 不许把交接文档写成成果汇报 —— 它给的是"接手者"，不是"评审人"（成果汇报讲做了什么，交接讲现在在哪、下一步做什么）。
• 禁止在交接文档里抄长正文（设计文档、规则全文）。只放状态与索引，否则它自己变成一份要啃的长文。
• 禁止把凭据（API Key、口令、票据）写进交接文档或日志。
• 禁止在任务执行中生成交接或做任何耗时动作 —— 见文首「注意事项」，这是本技能的最高约束。
• 红线：transcript 与生成的文档可能含真实项目名/甲方名 —— 若要对外分享交接文档，先过脱敏（走 omni-knowledge-distill 的脱敏扫描）。

回滚与备份：归档目录 .workbuddy/relay/history/ 每次生成都留副本，可直接取回上一版主文件。本技能不改动 transcript 与记忆文件（全程只读）。

关于数据库（2026-09-24 起）：本技能所有脚本都不写宿主数据库。需要改归属 / 归档时，
脚本只生成 .sql 脚本（连同一份 .undo.sql 还原脚本）放在备份目录，由用户先备份
workbuddy.db / -wal / -shm、完全退出 WorkBuddy，再用 sqlite3 CLI 手工执行。
只读连接用三级回退链（mode=ro → mode=ro&nolock=1 → immutable=1），
即使库目录不可写（只读盘 / 沙箱）也能正常读取。

六 · 资源

落账：每次生成追加一行到 <工作区>/.workbuddy/relay/relay.log（含水位与触发方式），便于回溯"什么时候交接的、当时多少水位"。

七 · 交付前自检

• [ ] 结构：frontmatter 十键齐；正文 ≥80 行；代码块 ≥3、文件名 ≥5。
• [ ] 内容：水位判据给出具体数值与来源字段，第三方可复算。
• [ ] 冒烟：tests/smoke_test.py 退出码 0，输出留档。
• [ ] 证据：交接文档八节齐，且「⚙️ 自动」段落的内容与磁盘真实情况一致（抽查 ≥3 条）。

常见误用与常见问题（FAQ）

常见误用（反模式）

常见问题

• Q：三条线怎么分？ A：A 线会话接力／B 线任务位置迁移／C 线任务合并与归档；先走「一 · 适用与路由」。
• Q：有哪些反例不能踩？ A：见「五 · 反例黑名单与红线」。
• Q：交付前要检查什么？ A：见「七 · 交付前自检」；检查点见「四 · 检查点」。
• Q：回流是必需的吗？ A：是 —— 见「八 · 经验回流（出厂件 · 硬条款）」。
• Q：失败模式在哪看？ A：见「三 · 失败模式与踩坑」。

八 · 经验回流（出厂件 · 硬条款）

• hooks/hooks.json —— PreCompact / Stop / SessionStart 三事件
• hooks/feedback.mjs —— 投递实现（自限时钟、失败静默、不造记录）
• FEEDBACK.md —— 写给使用者的说明

> ⚠️ 打包 / 上架时，hooks/ 与 feedback.mjs 必须提升到插件根（hooks.json 里用的是
> ${CODEBUDDY_PLUGIN_ROOT}，技能目录下不会被加载 —— 已实测）。