@cold777/dsh-takeover 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,152 @@
1
+ # Changelog — dsh-takeover
2
+
3
+ ## [0.2.0] — 2026-11-12
4
+
5
+ 四轴贯通完整版:会话 / 上下文 / 记忆 / 配置四轴协议内立约(各卡带 `axis`/`payload` 轴标记)、同走一根同步链跨机——「寄存 A 机、取件 B 机」从一句文档变成两条命令。卡同步走用户自己的 git 仓库(零存储凭据),环境备份是单文件加密包随同步走。
6
+
7
+ - **四轴 IR 立约**:卡片 extras 的 `axis`(session / memory / config)与 `payload`(files / distilled / manifest)协议内立约——会话卡、记忆卡、配置卡各归其位,取件方按标记决定「接着干 / 按条目吸收 / 先预演再落盘」;旧卡无标记按会话卡处理,round-trip 不丢。
8
+ - **repo 基线**:寄存时采集 origin / HEAD / 分支三元组进 `extras.baseline`,取件方按 clone → checkout → apply → 跑测试四步复原寄存现场(remote/head 拿不到如实降级为说明行,不写空壳假基线)。
9
+ - **上下文物质层**:未跟踪新文件(单件 <64KB)手拼新增 diff 随补丁走,超大/二进制只列清单;补丁超 512KB 先 gzip 压缩随卡、压缩后仍超则 480KB 分块 `.patch.NNN.gz`——最需要带走的时刻也带得走,取件侧按 gzip magic 自动解压重组,解压失败原样归档并如实警告。
10
+ - **救生艇**:设置卡「🛟」一键——上下文炸了模型吐不出工具调用时,`POST /dsh-takeover/lifeboat` 不经模型把当前会话事件流确定性抢出成卡(空壳闸按救生艇语义放行,密钥闸不旁路),同步已启用时自动 syncNow 推走;出卡记生命周期 `lifeboat` 事件留痕。
11
+ - **配置载荷卡**:`handoff_env action=card` 把最近一次备份的清单(path/category/sha256 + backupFile 指针 + bytes)写成 axis='config' 载荷卡寄存进收件箱——writeCard + 信封签名全套纪律,密文 blob 仍在 env-backup/ 随同步盘走,口令永不进卡。
12
+ - **记忆轴贯通**:记忆卡 `payload='files'` 立约随卡;引擎型记忆库(hippo 等)走通用 MEMORY_STORES 掏取契约——条目 JSONL 在场掏条目进「建议加载」段、缺席退回指引;取件即出「记忆已随卡注入」吸收回执(生命周期账本新记 `memory-absorbed`)。
13
+ - **卡链检索**:`handoff_inbox action=history` 按 project / cwd 回查 archived/ 已归档卡(id/标题/寄存时刻/停点摘要/接替 supersedes,时间正序尾 50 条)——接力链可溯,supersedes 走卡面 extras 持久通道。
14
+ - **provider 注册表收敛**:`src/providers.ts` 单一真源,消灭读取器名表/适配器映射/skill 规格四份平行表的漂移面。
15
+ - **换机上下文同步 `handoff_sync`**:设置卡「换机」页填一个私有 git 仓库地址即启用;`setup` / `now`(拉推一步到位)/`push`/`pull`/`status`。HANDOFF_HOME 即工作树:pending/archived 全部卡与机器信封 + 签名密钥 + 环境备份包随仓库走,机器本地记录(生命周期日志/取件溯源/插件开关)经 .gitignore 不入版本库。已消费的卡经 archived tombstone 不在另一台机器重放;合并冲突中止并诚实报错,本地文件原样保留。安全面:插件零存储凭据(userinfo 形态 URL 入口拒收),git 子进程超时硬杀 + 禁交互,仓库本地强制 autocrlf=false(卡字节是信封签名面)。state 路径零网络——30s 轮询不碰任何网。
16
+ - **环境备份/恢复 `handoff_env`**:DSH 全家桶(settings/插件登记五件套/会话库/智能中枢登记/~/.agents/skills/ZCode 用户层)打包单个 .dshenv 加密文件(纯 node 容器,scrypt+AES-256-GCM,口令永不落盘),随同步跨机。恢复三段纪律:`dry` 预演(新建/覆盖/相同三态 diff)→ `apply`(confirm 确认,被覆盖原物自动 checkpoint)→ `rollback` 一键回滚。凭据类文件只存在于加密包内;路径穿越硬闸;node_modules/缓存/日志排除(5.9G 压到 <60M)。
17
+ - **同步盘换机契约**:五条不变量钉死——Syncthing/OneDrive 冲突副本同 id 去重不幻影、原件已消费的迟到副本进可见拒收清单、半截文件拒收可见不塌收件箱、HANDOFF_HOME 链接目录全链穿透、消费即弃跨机不重放。
18
+ - **设置卡**:「换机」「环境」两枚新页签(五页签 + 方向键导航不变);概览新增同步状态瓦片(落后数即待办)。
19
+ - **Windows 4 红清零**:vendor readers 陈旧链 bump(gemini 适配器落地本机)+ .gitattributes 全仓源码钉 LF + 文档断言行尾归一化。
20
+ - 质量闸:测试 **386** 全绿、typecheck+build 干净;双 home + 裸远端真 git 集成测试(换机六场景 + 四轴贯通全链);THREAT-MODEL 新增 T7(环境备份面)并修订 T6(网络面唯一例外 + 救生艇无模型旁路)。
21
+
22
+ ## [0.1.0] — 2026-11-02
23
+
24
+ 首发版。功能面:九家外部会话读取器(claude / codex / opencode / zcode / pi / workbuddy / cursor / grok / gemini)、`handoff: 1` 协议收件环、信封机器签名、单卡忽略、记忆快照交接、接力工作台(导航轨 + 四全宽视图指挥台)。
25
+
26
+ - 文档:README 双语重写为场景驱动版——徽标 hero、三场景、30 秒安装与上手指南、工作原理速览、工具与命令参考。
27
+ - 质量闸:测试 327 全绿、typecheck + build 干净。
28
+
29
+ ## [0.4.5] — 2026-11-01
30
+
31
+ 指挥台版:浮层重排成导航轨 + 四全宽视图——收件箱概览瓦片化、设置卡三段页签化、`--tk-*` 语义 token 落地;设计宪法 DESIGN.md 首次引入,实现按其执行。
32
+
33
+ - **工作台导航轨 + 四全宽视图**:两栏拼盘废除,改为 148px 左导航轨(logo + 收件箱/会话浏览器/交接/记忆快照四视图 + 上手指南 + 版本徽标)+ 右侧全宽视图;四视图常驻挂载、display 切换保状态,视图头=标题 + 一句副标 + 过滤输入 + 视图级动作,视图内滚动、头部与导航轨常驻。
34
+ - **收件箱概览瓦片化**:统计胶囊升级为一行大数字瓦片(19px tabular 大数字 + 小标签 + 左缘 3px 语义色条)——待取件/已存档/可查证/信封/拒收五枚常驻,重复卡热态追加一枚,窄容器自动换行。
35
+ - **设置卡三段页签化**:一屏长滚动废除,改为分段器三页签(命令速览 / 支持矩阵 / 开关语义);`button[role=tab]` + `aria-selected`/`aria-controls` + 方向键导航,[?] 帮助与刷新常驻卡头。
36
+ - **`--tk-*` 语义 token 落地**:表面/描边/文字/品牌渐变/状态三色全部收敛为 CSS 变量——一处引用一处定义,组件禁止裸色值,状态三色闭集映射全局唯一。
37
+ - **设计宪法 DESIGN.md 首次引入**:按 Google Stitch 九段约定固化指挥台设计系统,绑定纪律=改 UI 前必读、改设计先改本文件再改代码;本版实现按其执行。
38
+ - 质量闸:测试 **320** 全绿、typecheck+build 干净;构建产物徽标经 esbuild define 注入验证(`lib/client.js` 含 `v0.4.5`)。
39
+
40
+ ## [0.4.4] — 2026-11-01
41
+
42
+ 信用版:卡带上机器签名、收件箱装上「忽略」、读取器进到第九家——「诚实交接 + 最小惊扰」两条原则落到字节层。
43
+
44
+ - **信封机器签名**:首次 push 自动生成总线密钥 `.signing-key.json`(密钥同步域=信任域);签名面=信封全字段+卡面 `cardSha256`——未持钥改卡面(信封原样)同样可检出。取件侧三态裁决 `ok / tampered / no-key`(跨信任域绝不误报篡改),篡改进死亡地图新理由 `sig_tampered`,取件渲染 🔐/🚨 行;未签名旧卡完全兼容。诚实边界:持全权者连密钥一起换防不住——总线文件的系统权限是最后防线。
45
+ - **pending 单卡忽略**:工作台卡行「忽略」按钮 + `POST /dsh-takeover/dismiss-pending` + `dismissPending`——卡/信封/patch 边车三件原样移入 `archived/`,id 消毒防路径穿越;全新总线无 `archived/` 时先建目录。
46
+ - **第九家读取器 Gemini CLI**:`/resume-gemini` + list/show 全链——JSON/JSONL 双格式、子代理嵌套、`.project_root` cwd 还原;图标走中性兜底;`OUTBOUND_TARGETS` 不加 gemini(交接目标与读取器两轴独立)。
47
+ - **记忆探测路径修正**:hippo-db 探测从遗留 `memory.db` 改到现役 zvec 位置(`~/.hippo` 系)——记忆快照 tab 在现部署下显示真实记忆库。
48
+ - **项目身份系统(会话浏览器)**:cwd 确定性哈希 → 十色板——项目筛选 chips 与会话行同源同色(彩色文件夹图标 + 选中态项目色描边 + 行首项目色左缘条 + 行内同色项目标),456 个会话的长列表滚动中「哪片是哪个项目」一眼可辨;空 cwd 归中性灰不占身份位。
49
+ - **交接目标图标化**:「交接给谁」八家目标补品牌图标(与来源 pills 同款),裸文字钮退场;任意 agent 用本插件品牌小标。
50
+ - **版本徽标自动化**:`v0.4.x` 徽标从 client.ts 手写常量改为构建期经 esbuild define 注入 package.json 版本——发版不再漂移(0.4.3 时代它停在旧值无人察觉)。
51
+ - **测试基建信用修复**:`tests/secret-gate.spec.ts` 三处 `pushHandoff` 缺 `{ dir: home }`——每次全量测试向真实 `~/.handoff` 泄漏一张骨架卡 + 账本拒收事件(历史残留卡的增长规律由此解释),修复后以「跑前跑后 pending 数与 lifecycle 行数双不变」验证;smoke-foreign 技能数断言跟上九家(10→11);smoke-userflow 上总线隔离守卫(默认拒真实总线,`--allow-real-bus` 逃生)+ act5 文案纠偏。
52
+ - 质量闸:测试 **314** 全绿、typecheck+build 干净;真宿主浏览器点击链复验(三段 tab/忽略链:通知行、16→15、archived 三件套盘面核对);密钥闸实战佐证——工作区 diff 含测试夹具串时 patch 边车扫描当场拦截 push(设计行为,假阳性按 redact 指引处理)。
53
+
54
+ ## [0.4.3] — 2026-10-28
55
+
56
+ 居中模态版:接力工作台浮层从「锚定接力按钮位置弹出」改为**真正的视口居中模态**(inset:0 + margin:auto + fit-content,双轴居中)——多台机器、任意窗口尺寸下面板不再偏移;与宿主滚动完全解耦(移除捕获阶段滚动监听);宽度三档分档与高度自适应保持不变。
57
+
58
+ ## [0.4.2] — 2026-10-27
59
+
60
+ 设计语言版:收件箱浮层对齐 Linear 式六支柱(表面分层 / 字体阶梯 / 渐变收敛 / 动效 token / 间距网格 / 细节微光),纯视觉层,数据流与工具语义零改动。
61
+
62
+ - **三级表面 + 描边浮现**:卡片与预览块改为「极淡底 + 1px 描边 + 顶部 1px 内发光」的浮现式呈现;卡行 hover 才浮现描边(30s 轮询长列表不成卡海),未读行保留常驻品牌描边。
63
+ - **字体阶梯收敛**:14(标题,负字距)/ 13(行标题)/ 12(正文)/ 11(meta)/ 10(徽标)五档制度化,`.bt-title-sec` 二级标题类替换全部行内覆写。
64
+ - **渐变收敛 + 徽标降饱和**:品牌渐变只保留未读强调条与主按钮;「新 / 空卡 / 接力自」徽标改低饱和底 + 同色描边。
65
+ - **动效 token 化**:`--bt-ease` / `--bt-dur` 统一缓动与时长;未读强调条 scaleY 展开;骨架脉冲与全部动画带 `prefers-reduced-motion` 降级。
66
+ - **骨架屏**:收件箱冷启动显示脉冲骨架条,替换「加载」纯文字;暗轴补 `--bt-hover` 覆写保证骨架可见。
67
+ - **测试夹具去本机路径样式**:relay.spec 的 `D:/fixture-ws` 虚构串改 `D:/fixture-ws`。
68
+ - 质量闸:独立设计评审(未参与实施者冷读 diff)high/medium 意见清零后合入;测试 300 全绿。
69
+
70
+ ## [0.4.1] — 2026-10-26
71
+
72
+ 归因版:0.4.0 建了证据基建,0.4.1 让证据开口说话——每个数字能回答「为什么」,每个改进能指出「归因结论第几条」。
73
+
74
+ - **死亡地图(拒收证据结构化)**:新增卡片生命周期事件层 `src/lifecycle.ts`——写侧(密钥闸/空壳闸拒收)与取侧(git 核验 MISMATCH/UNAVAILABLE)事件持久化 `~/.handoff/lifecycle.jsonl`(闭集理由 + 尾 500 封顶),读侧坏卡跳过进 state 活性视图;收件箱概览新增「拒收 {n}」徽标与悬浮明细。多写方场景「寄了没消费」从此可自检。
75
+ - **失败归因管线**:`scripts/attribution.mjs` 三源合并(lifecycle 事件 + relay 记录 + archived 回测)出闭集死亡分类——写侧拒收 / 读侧跳过 / **僵尸卡(relay 有取件记录但卡未被消费)** / 存活 / 执行死亡 / 不可归因 / 在册。首轮实测:僵尸卡 10 张(三臂实验取证:取件会话在卡 id 不合规时会绕过收件工具直接读文件,消费即弃被架空)。
76
+ - **三臂对照实验**:`scripts/eval-three-arm.mjs` + `scripts/section-utility.mjs`(行为探针法——不可猜测事实埋进 warnings 段,接手产物逐一检验存活)。隔离收件箱首轮结果:structured 3/3、plain 3/3、minimal 任务完成 3/3 但 marker 探针 **0/3**——诚实结论:强模型小任务下结构化不提升完成率,**交接卡的价值在传递不可猜测的运行态事实**(带交接 6/6 vs 无交接 0/3);阴性结果如实入档。
77
+ - **评测可复现包**:`eval/README.md` 预注册口径(臂设计/探针/统计声明/复现步骤/隐私纪律)——同脚本可追加轮次,第三方可重跑同数字。
78
+ - **蒸馏反哺**:50 张真实卡回测结论(done 段带账本标注的卡延续率 50%、无标注 0%)写进 `skills/handoff.ts` 写卡纪律——标注纪律从形式要求升级为有数字支撑的接手成功率分水岭。
79
+ - 质量闸:测试 276 → **300**(生命周期/归因/探针三套新测试),全量绿。
80
+
81
+ ## [0.4.0] — 2026-10-21
82
+
83
+ 深度版本:五层证据基建——接力质量从「感觉」变成「数字、测试与第三方可复核的证明」。
84
+
85
+ **真机验收收尾(2026-10-23 补)**:全流程真实浏览器验收后落地——记忆卡折叠栏去重(双图标/双文案)、两处 [?] 打开帮助即滚至卡顶、导出入口合并为「导出 ▾」菜单、「只看新卡」从来源 chips 独立为复选框未读开关、浮层双列各自内滚(标题栏/横幅固定,窄容器退化为整体内滚)、已消费徽标改为「已存档」口径并在悬浮提示披露 archived/ 的 50 张滚动保留策略。收件箱组件高级化:统计条改软胶囊(热态品牌描边)、卡行卡片化(hover 描边、未读行首品牌渐变强调条——该类名此前从未有样式)、展开预览内嵌软面板、筛选行合并(未读开关与来源 chips 同行)、双列细滚动条。
86
+
87
+ - **解析层**:真实会话结构克隆脱敏语料(`scripts/corpus-build.mjs`)+ 13 份 golden files 逐字节回归闸(`tests/corpus-golden.spec.ts`)+ 已知生态事故回归(上游存储布局漂移 + BOM/CRLF 边界)+ 恢复语义故障注入(`tests/recovery.spec.ts`)。挖出并修复两个真缺陷:Windows 并发 rename 双成功击穿消费即弃保证(core 引入独占创建认领文件仲裁 + 过期自愈)、补丁孤儿崩溃窗口(清扫扩展到补丁)。
88
+ - **质量层**:首个接力质量基线——50 张真实 archived 卡回测延续率 34.7%,且账本标注率高的卡延续率 50% vs 无标注 0%(`scripts/backtest-archived.mjs`);端到端双卡接力真 host 真模型评测 PASS(`scripts/eval-e2e.mjs`);蒸馏保真度评测器(`scripts/eval-distill.mjs`)。附带修复:`<local-command-*>`/`<command-name>` 命令回声不再冒充用户请求进 goal。
89
+ - **安全层**:`THREAT-MODEL.md` 六类威胁 + 红队套件 8 组进 CI(`tests/redteam.spec.ts`)。修复红队驱动出的缺口:补丁 diff 密钥走私(diff 现过密钥闸)、赋值规则短口令漏网(值下限 14→8 带字符混合要求)。
90
+ - **协议层**:`conformance/`——handoff: 1 可执行符合性套件(11 条要求推导自 SPEC 原文,零依赖)。参考实现与独立第二实现(实现者只读 SPEC,与两仓代码零接触)双双 9/9 MUST 符合;第二实现暴露的 10 条规范歧义记录在 `conformance/SPEC-NOTES.md`。
91
+ - **互通层**:INTERCHANGE v1(dsh-chat-import)↔ handoff: 1 双向转换(`scripts/interop-interchange.mjs`,bundle 双层 sha256 校验 + 确定性蒸馏)。真实交换验证:转换产物经对方插件 v0.26.2 真实 `import_chat` 导入成功。
92
+
93
+ ## [0.3.0] — 2026-10-20
94
+
95
+ Relaying goes bidirectional, and memory joins the loop.
96
+
97
+ - **Send out**: the workbench grows an outbound card — one click queues the deposit instruction into the *current* DSH session; the agent distills and checks the card into the shared inbox, and the other side (Claude Code / Codex / any agent) pastes the per-target pickup instruction shown under the card. Falls back to copying the instruction on hosts without the session controller.
98
+ - **Memory snapshot**: a new card (and a `handoff_memory` tool) scans each agent's local memory files — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.zcode/AGENTS.md`, `~/.config/opencode/AGENTS.md`, `~/.cursorrules`, project-level AGENTS.md / CLAUDE.md / .cursorrules, plus a dsh-hippo store probe with the official `/memory dump` / `/memory import` interop path — and packs the selected ones into a handoff card in the inbox. Secret gate, skeleton gate, coverage ledger and machine envelope all apply, same as session cards.
99
+ - **Beginner pass**: a built-in FAQ card (8 entries, zh/en) ships in the workbench and the settings card; the coverage badge is renamed 「可查证 / Evidence」, the envelope stat is humanized (7426 → 7.4K) with a plain-language tooltip, foreign sessions without a human title get one sniffed from their first user message, and the browser's provider pills now carry brand icons.
100
+
101
+ ## [0.2.3] — 2026-10-19
102
+
103
+ Two-column relay workbench: the popover widens to a side-by-side layout — inbox overview on the left, external session browser on the right — collapsing back to a single column in narrow containers. Visual polish aligned with the product one-pager.
104
+
105
+ ## [0.2.2] — 2026-10-17
106
+
107
+ Relay provenance store: every takeover, takeover-with-deposit, and directed pickup writes `<HANDOFF_HOME>/relay/<sessionId>.json` — which external agent and session (or which inbox card) a session came from, timestamped. Durable in the plugin's own store, cross-machine via `HANDOFF_HOME` sync. The host's experimental plugin-record append stays layered on top as best-effort.
108
+
109
+ ## [0.2.1] — 2026-10-16
110
+
111
+ Relay provenance in the session log itself. Takeover, takeover-with-deposit, and directed pickup now append a first-party record into the DSH session log through the host's experimental plugin-record API (`@deepseek-ai/dsh-session ≥0.2.1-alpha.2`): which external agent and session (or which inbox card) a session came from, timestamped, written right after the delivery lands. The record is an ignorable event — it never enters model context, rides along with forks and resumes, and survives as durable proof of a session's origin. Best-effort by design: on hosts without the API the plugin behaves exactly like 0.2.0.
112
+
113
+ ## [0.2.0] — 2026-10-10
114
+
115
+ First public release. Cross-agent session takeover for DeepSeek Harness: pull, deposit, and take over work across eight external agents over the open `handoff: 1` protocol.
116
+
117
+ ### Added
118
+
119
+ - **External session browser + inbox workbench** (a compact "Relay" chip in the composer toolbar — click it in any session to unfold a floating workbench): browse the most recent sessions of eight external agents — Claude Code, Codex, OpenCode, ZCode, Pi, WorkBuddy, Cursor, Grok — with titles, relative times, project facets, instant filtering, and expandable per-session previews (turn counts, first user request, recent progress, stop point, warnings), plus the consume-once inbox overview with directed pickup, relay-chain filtering, and exports. Readers are lazy: nothing is scanned until you select a provider. The settings card stays settings-only: command quick-reference, reader toggles, and a pointer to the chip.
120
+ - **One-click takeover**: *Take over* / *Take over + deposit* on any listed session creates a new DSH session, delivers the takeover command, renames the session for findability, and switches the app to it automatically. Delivered payloads are identical to the copyable commands; any failure falls back to the clipboard path automatically with the reason surfaced.
121
+ - **Directed pickup**: every inbox card has a *Pick up* action that creates a session and delivers a pickup command naming that exact card.
122
+ - **Handoff cards** (`handoff: 1` open protocol): six-section cards with a four-state evidence ledger (CURRENT_OBSERVED / HISTORY_REPORTED / MISMATCH / UNAVAILABLE), consume-once pickup, and a patch sidecar (uncommitted changes ride with the card as a `.patch`; rejected above 512 KB rather than truncated).
123
+ - **Relay-chain visualization**: cards carry a "← supersedes <id>" badge with one-click chain filtering; chains are verified across hops.
124
+ - **Shared-inbox relay across machines**: point `HANDOFF_HOME` at a synced folder or git repository and the inbox is shared — deposit on one machine, pick up on another (or from a phone file viewer).
125
+ - **Subagent session grouping**: workflow/subagent sessions are folded into a collapsed group so the main list stays work-only.
126
+ - **Project facets & instant filtering** in the browser; per-session structured previews are fetched on demand and never include raw transcripts.
127
+ - **Copy-command fallbacks**: every takeover action has an identical copyable command; reference parsing accepts id, path, title keyword, or `latest`, and cuts at the first newline so a trailing instruction never breaks resolution.
128
+ - **Exports**: single-card and all-card `.md`, plus a self-contained HTML report.
129
+ - **Distillation fidelity benchmark**: a re-runnable probe suite over real sessions (deterministic layer).
130
+
131
+ ### Security
132
+
133
+ - Loopback-only panel: every route rejects non-loopback connections regardless of headers; POST routes additionally require same-origin, and identical takeover requests within a short window are deduplicated.
134
+ - Secret gate on deposit: credential-pattern scanning with redaction guidance; bypasses are recorded on the card.
135
+ - Skeleton gate: all-placeholder cards are rejected unless explicitly confirmed.
136
+ - Read-side size gates for cards and envelopes; task-snapshot caps.
137
+ - Provider disable switch enforced uniformly across reads, previews, and takeovers.
138
+ - Read-only discipline: foreign session stores are never written; no network access beyond the loopback panel.
139
+
140
+ ### Fixed
141
+
142
+ - Inbox new-only filter inversion; stale-response race on the 30s poll; lost-update race on provider toggles.
143
+ - First-run degraded state (missing `pending/` no longer reports an inbox error).
144
+ - Orphan-envelope cleanup now preserves envelopes whose card file is still on disk.
145
+ - Facet filters can no longer become invisible stale filters across provider switches or queries.
146
+ - Several accessibility fixes (ARIA roles, keyboard focus rings, no nested interactive elements, locale-safe labels).
147
+ - Build pipeline: template-escape corruption in the unbundled client build no longer affects copied commands or `.md` exports.
148
+
149
+ ### Quality
150
+
151
+ - 207 automated tests (unit, route-level and UI-render) all green; CI runs typecheck + the full suite + the build on every push and PR.
152
+ - Verified end-to-end on a live host: takeover-with-deposit of a 7,284-turn session completed in ~50s with full ledger coverage; directed pickup consumed a card in ~40s; a scripted end-to-end run (browse → takeover → deposit → directed pickup) completed with zero typing.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-baton contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,132 @@
1
+ <p align="center"><img src="assets/icon.svg" width="72" height="72" alt="dsh-takeover logo"></p>
2
+
3
+ # dsh-takeover · Session Takeover
4
+
5
+ **Take over any agent's half-finished work and keep going — read-only session pull from nine CLIs, one-click check-in, pickup on start. Sessions and memory both hand over.**
6
+
7
+ [![npm](https://img.shields.io/npm/v/@cold777/dsh-takeover)](https://www.npmjs.com/package/@cold777/dsh-takeover) ![tests](https://img.shields.io/badge/tests-327%20passing-brightgreen) ![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.2-orange) ![Node](https://img.shields.io/badge/node-%3E%3D22-green) ![license](https://img.shields.io/badge/license-MIT-lightgrey)
8
+
9
+ - **Take over**: a task half-done in Claude Code — one `/resume-claude` injects a six-section handoff card into the current session and the model just continues;
10
+ - **Hand off**: session too long, switching environments? `/handoff` checks the current session out as a card that any agent can pick up on start;
11
+ - **Across machines**: `handoff_sync` moves the inbox over your own git repo in one command — consumed cards never replay on the other machine; the zero-setup `HANDOFF_HOME`-on-a-synced-drive path still works, and cards stay readable from your phone.
12
+
13
+ ## Install (30 seconds)
14
+
15
+ **npm package name** (paste it in the "Plugins → Add plugin" dialog; CN users resolve via npmmirror automatically):
16
+
17
+ ```
18
+ @cold777/dsh-takeover
19
+ ```
20
+
21
+ **CLI (GitHub source, works right now):**
22
+
23
+ ```bash
24
+ dsh plugin --profile web add github:IKEASven69/dsh-takeover
25
+ ```
26
+
27
+ **Settings card:** DSH Settings → Plugins → Add plugin → paste `github:IKEASven69/dsh-takeover`
28
+
29
+ **Let your agent install it** — send this to your DSH agent verbatim:
30
+
31
+ > Please install the dsh-takeover plugin: run `dsh plugin --profile web add github:IKEASven69/dsh-takeover`. When it finishes, restart the DSH web app, confirm dsh-takeover is enabled under Settings → Plugins, then report the result back to me.
32
+
33
+ Works out of the box (built artifacts are committed — no local toolchain). Pin a release: `github:IKEASven69/dsh-takeover#v0.1.0`. Requires DSH ≥0.2.0-rc.2 and Node ≥22.
34
+
35
+ ## First 30 seconds
36
+
37
+ | You want to | Say / type | What happens |
38
+ |---|---|---|
39
+ | Take over a foreign session | `/resume-claude` (or plain words: "take over the latest Claude Code session") | Read-only pull → six-section card injected into the live turn → the model continues |
40
+ | Hand the current session off | `/handoff` | Current session distilled into a protocol card, uncommitted changes attached as a patch |
41
+ | Pick up on start | `/inbox` | List pending cards → verify and sign for one → context injected, keep working |
42
+ | Browse before deciding | Click the "Relay" chip next to the composer | Workstation opens: browse nine agents' recent sessions, one-click takeover / check-out, memory snapshot |
43
+ | Hand memory over too | Workstation → Memory snapshot → select and pack | CLAUDE.md / AGENTS.md and friends packed into a card; the receiver absorbs them per its "suggested loads" |
44
+
45
+ ## How it works (60 seconds)
46
+
47
+ **The filesystem is the bus.** One card per `.md` file in `~/.handoff/pending/`: writing is delivery, pickup moves it to `archived/` (rolling 50 kept; consume-and-archive, a second pickup of the same id errors).
48
+
49
+ **A card = Markdown + YAML frontmatter + six body sections** (goal / files involved / how far it got / what's left / where it stopped / reader warnings), carrying a four-state evidence ledger (CURRENT_OBSERVED / HISTORY_REPORTED / MISMATCH / UNAVAILABLE) — historical claims never masquerade as present fact. Uncommitted changes in a git repo are attached as a patch automatically (refused above 512KB, never truncated).
50
+
51
+ **Trust lives in the file.** First push generates a bus signing key; cards carry machine signatures; pickup rules three ways — `ok / tampered / no-key`. Tampering is detectable, cross-trust-domain never false-positives.
52
+
53
+ **Read-only promise.** No writes to any foreign agent's session store, no network access, no replaying historical tool calls; raw text never enters the card — only pointers.
54
+
55
+ ## All in one · Four axes, one chain
56
+
57
+ Handover is never one thing — it is four. All four share the same `handoff: 1` card format, the same `~/.handoff` bus, and the same git sync chain; on the user's side it is always a single command:
58
+
59
+ - **Session axis**: `/handoff` distills a half-finished session into a six-section card; any agent picks it up with `/inbox` and keeps going;
60
+ - **Context axis**: uncommitted changes ride along as a patch and the repo baseline (origin / HEAD / branch) travels on the card — a new machine restores the exact scene via clone → checkout → apply → run tests;
61
+ - **Memory axis**: CLAUDE.md / AGENTS.md and friends are packed into a card; the receiver absorbs them into its own memory files via the "suggested loads" section;
62
+ - **Config axis**: the manifest + pointer of the encrypted family backup rides the card while the encrypted blob travels with the sync — restore on a new machine with a dry preview → confirm apply → rollback.
63
+
64
+ What does one card carry? After one `handoff_sync` command, the other machine's inbox holds not just "where the chat left off" but the entire scene needed to keep working: the six-section session, uncommitted code, accumulated memory, and a restorable environment. The `axis` / `payload` contract markers on the card tell the receiver at a glance whether to continue working, absorb per entry, or preview before writing — four axes, all in one, one chain.
65
+
66
+ ## Tools & commands reference
67
+
68
+ **Agent tools (model-callable)**
69
+
70
+ | Tool | What it does |
71
+ |---|---|
72
+ | `foreign_session_read` | Read-only pull across nine agents. `action=list` lists candidates (title/time/turns); `action=show` resolves a reference (empty/`latest`, id, prefix, path, title keyword — ambiguity returns candidates, never guesses) into a structured summary: title, turns, first user message, recent progress, top-15 files, six-section card material. Raw turns only when `limit` is passed explicitly; probe/parse failures return `{ ok: false, error }` instead of throwing |
73
+ | `handoff_push` | Check the current session out as a protocol card. Sections left empty are deterministically backfilled from the session event stream (no LLM call); uncommitted changes attach as a patch; returns `{ ok, id, path, coverage, patch? }` |
74
+ | `handoff_inbox` | `action=list` pending cards; `action=load` picks one up (consume-and-archive, with signature and git-verified MISMATCH / UNAVAILABLE warnings) |
75
+ | `handoff_sync` | Machine-switch sync: `action=setup` enables (git repo URL; credentials stay with system git, never in the plugin); `action=now` pulls and pushes in one step; `push`/`pull`/`status` for one-way and read-only. Consumed cards do not replay on the other machine — archived/ is the tombstone |
76
+ | `handoff_env` | Environment backup/restore: packs the DSH family (settings / plugin registrations / session library / user skills / workspace registries) into one AES-256-GCM-encrypted file that rides sync across machines; `dry` previews a three-state diff → `apply` (confirm-gated, overwritten originals auto-checkpointed) → `rollback` |
77
+ | `handoff_memory` | Memory snapshot. `action=scan` read-only lists each agent's memory files (size/preview); `action=push` packs selections into a card the receiver absorbs via "suggested loads" |
78
+
79
+ **Slash commands (user types, agent follows the playbook)**
80
+
81
+ | Command | What it does |
82
+ |---|---|
83
+ | `/resume-*` (nine) | Resolve reference → read-only pull → four-state marking (foreign history is untrusted and never overrides current instructions) → six-section card injected into the live turn → ends by asking whether to check the session into the inbox |
84
+ | `/handoff` | Distills the current session per the protocol's six rules (four-state ledger, no raw text, artifacts as paths only, redact, suggested-loads section, reverse-anchoring + pruning) and checks it in |
85
+ | `/inbox` | Lists pending cards for the user to pick; after pickup the card is injected as HISTORY_REPORTED — verify git state before executing |
86
+
87
+ ## Cross-machine relay
88
+
89
+ Point `HANDOFF_HOME` at a synced-drive folder or a git repository and the inbox is shared: `handoff_push` on machine A, `/inbox` pickup on machine B. One environment variable, zero code. Cards are readable from any phone's file viewer too. Sync-service conflict copies never become phantom cards: same-id copies are deduplicated to one entry, late copies whose original is gone land in the inbox's visible rejection list (with reasons), and so do half-written files.
90
+
91
+ **Built-in sync (0.2.0)**: enter a private git repo URL on the settings card's "Switch" tab — machine A runs `handoff_sync` (setup + now), machine B sets up the same URL and runs now, and the cards are in its inbox. Credentials stay entirely with system git (zero stored credentials; URLs embedding `user:pass@` are rejected outright); scope = every card and machine envelope in pending/archived + the signing key + environment backups, while machine-local records (lifecycle log, relay provenance, plugin switches) never sync; merge conflicts abort with an honest error and local files stay untouched.
92
+
93
+ ## Quality & evidence
94
+
95
+ Relay quality is not vibes — it is numbers, tests, and third-party-checkable proof (methodology and reproduction steps in [eval/README.md](eval/README.md)):
96
+
97
+ - **Backtest**: 50 real consumed cards — continuation rate 34.7%; cards with ledger marks in the done section continued 50% of the time vs 0% for unmarked ones. End-to-end two-card relay against a real host and model: PASS.
98
+ - **Parse regression**: 13 golden files frozen byte-for-byte against a structurally-cloned, anonymized real-session corpus — upstream storage drift turns red before merge.
99
+ - **Security**: threat model in [THREAT-MODEL.md](THREAT-MODEL.md); 8 red-team suites in CI — the secret gate covers all six sections, every scalar, and the card's patch diff.
100
+ - **Protocol**: `conformance/` executable suite (9 MUST requirements derived from the SPEC); both the reference implementation and an independent second implementation (written from the SPEC alone) conform.
101
+ - **Interop**: INTERCHANGE v1 (dsh-chat-import) ↔ handoff: 1 bidirectional conversion, verified by a real import through their plugin v0.26.2.
102
+
103
+ ## Positioning
104
+
105
+ The "continuable context" need in AI coding splits into three layers: spec tools (spec-kit / OpenSpec and friends) own the **design state**; memory layers (mem0 / Letta / dsh-hippo and friends) own the **preference state**; dsh-takeover owns the **run state** — how far work actually got, where it stopped, which statements are present observations versus secondhand retellings, which machine a card came from. The three layers complement each other.
106
+
107
+ The one-sentence mechanical distinction: **they do "convert, then natively resume in another CLI", "environment backup", "navigation/search", "runtime orchestration", or "task-state transport"; we do in-harness takeover plus machine-switch context sync — cards and backups ride your own git repo, and the handoff semantics and ledgers never change hands.**
108
+
109
+ ## Protocol adoption
110
+
111
+ `handoff: 1` is an open protocol: a six-section Markdown card + YAML frontmatter + the `~/.handoff` shared directory — implementable, auditable and interoperable by any tool (the right to call it open is backed by an independent second implementation, see [Quality & evidence](#quality--evidence)). Already interoperating: [dsh-chat-import](https://github.com/Nwflower/dsh-chat-import) (bidirectional conversion verified via INTERCHANGE v1). If your tool reads or writes the same directory or card format, open an issue to register interoperability.
112
+
113
+ ## Permission scope
114
+
115
+ Writes `~/.handoff/` (override via `HANDOFF_HOME`), reads git status, read-only access to the nine agents' local session stores (zcode and cursor via sqlite readonly, opened on demand; per-agent roots overridable via `HANDOFF_ROOT_<agent>`). cursor imports only supported transcript / store records; grok reads only the visible updates.jsonl stream (never the raw chat_history.jsonl model context); gemini reads only local chats/ session files. Two explicit exceptions since 0.2.0: (1) `handoff_sync` talks to the git repository **you explicitly configure**, via system git (the plugin process builds no network connection and stores no credentials); (2) `handoff_env` backs up and restores family-wide config paths — restore requires a dry preview then explicit confirm before anything is written, overwritten originals are auto-checkpointed for rollback, and credential files exist only inside the encrypted archive (see THREAT-MODEL T6/T7). No reviving external processes, no replaying historical tool calls, raw text never enters cards.
116
+
117
+ ## Development
118
+
119
+ ```bash
120
+ pnpm install # @deepseek-ai/* via npm registry; @agent-handoff/* via file: links
121
+ npm run typecheck
122
+ npm test # node:test + tsx
123
+ npm run build # tsdown → lib/ (@agent-handoff/core + readers bundled in)
124
+ node scripts/smoke-foreign.mjs # live smoke: in-process mount of lib/, real foreign_session_read dispatch
125
+ node scripts/smoke-userflow.mjs # real user journey: pull real local zcode/opencode sessions → check in → pick up
126
+ ```
127
+
128
+ `@agent-handoff/core` and `@agent-handoff/readers` are unpublished; they are wired via `file:../agent-handoff/packages/*` and bundled into `lib/` at build time.
129
+
130
+ ## License
131
+
132
+ MIT
package/README.md CHANGED
@@ -1,3 +1,132 @@
1
- # Temporary Holding Version
1
+ <p align="center"><img src="assets/icon.svg" width="72" height="72" alt="dsh-takeover logo"></p>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # dsh-takeover · 会话接管
4
+
5
+ **把任何 agent 干到一半的活接过来继续干——九家 CLI 会话只读拉取、一键寄存、开局取件,会话和记忆都能交接。**
6
+
7
+ [![npm](https://img.shields.io/npm/v/@cold777/dsh-takeover)](https://www.npmjs.com/package/@cold777/dsh-takeover) ![tests](https://img.shields.io/badge/tests-327%20passing-brightgreen) ![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.2-orange) ![Node](https://img.shields.io/badge/node-%3E%3D22-green) ![license](https://img.shields.io/badge/license-MIT-lightgrey)
8
+
9
+ - **接过来**:Claude Code 里干到一半的任务,`/resume-claude` 一条命令——六段交接卡注入当前会话,模型直接接着干;
10
+ - **交出去**:会话太长想换环境?`/handoff` 把当前会话寄存成一张卡,任何 agent 开局取件继续;
11
+ - **跨机器**:`handoff_sync` 一条命令把收发件箱经你的 git 仓库搬到另一台机器,已消费的卡不重放;`HANDOFF_HOME` 指向同步盘的免配置路径继续可用,手机上也能看卡。
12
+
13
+ ## 安装(30 秒)
14
+
15
+ **npm 包名**(「插件 → 添加插件」对话框直接粘贴;大陆用户自动走 npmmirror 镜像):
16
+
17
+ ```
18
+ @cold777/dsh-takeover
19
+ ```
20
+
21
+ **命令行(GitHub 源,即刻可用):**
22
+
23
+ ```bash
24
+ dsh plugin --profile web add github:IKEASven69/dsh-takeover
25
+ ```
26
+
27
+ **设置卡:** DSH 设置 → 插件 → 添加插件 → 粘贴 `github:IKEASven69/dsh-takeover`
28
+
29
+ **让 agent 自己装**——把下面这段原样发给你的 DSH agent:
30
+
31
+ > 请为本机安装 dsh-takeover 插件:执行 `dsh plugin --profile web add github:IKEASven69/dsh-takeover`。完成后重启 DSH web 端,在 设置 → 插件 里确认 dsh-takeover 已启用,最后告诉我安装结果。
32
+
33
+ 装完即用(构建产物已入库,无需本地工具链)。固定版本:`github:IKEASven69/dsh-takeover#v0.1.0`。需要 DSH ≥0.2.0-rc.2、Node ≥22。
34
+
35
+ ## 30 秒上手
36
+
37
+ | 你想干什么 | 对 agent 说 / 敲 | 背后发生什么 |
38
+ |---|---|---|
39
+ | 接管别家会话 | `/resume-claude`(或自然语言:"把 Claude Code 最新的会话接过来") | 只读拉取 → 六段交接卡注入当前轮 → 模型接着干 |
40
+ | 交接当前会话 | `/handoff` | 当前会话蒸馏成协议卡寄存进共享收件箱,未提交改动自动附补丁 |
41
+ | 开局取件 | `/inbox` | 列出待取件 → 挑一张核验签收 → 上下文注入继续干 |
42
+ | 浏览了再接 | 点输入框工具行的「接力」按钮 | 浮出工作台:九家最近会话浏览、一键接管 / 交接出去、记忆快照 |
43
+ | 记忆一起交接 | 工作台 → 记忆快照 → 勾选打包 | CLAUDE.md / AGENTS.md 等打包成卡,取件方按卡吸收进自己的记忆文件 |
44
+
45
+ ## 它怎么工作(60 秒)
46
+
47
+ **文件系统即总线。** `~/.handoff/pending/` 一个卡片一个 `.md`:写入即投递,取件即移入 `archived/`(滚动保留 50 份;消费即弃,二次取件报错)。
48
+
49
+ **卡片 = Markdown + YAML frontmatter + 六段正文**(目标 / 涉及文件 / 做到哪 / 还差什么 / 停在哪 / 读者警告),带四态证据账本(CURRENT_OBSERVED / HISTORY_REPORTED / MISMATCH / UNAVAILABLE)——历史陈述不冒充当下事实;git 仓库的未提交改动自动随卡附补丁(≤512KB 拒带不截断)。
50
+
51
+ **信任长在文件里。** 首次寄存自动生成总线密钥,卡片带机器签名;取件侧三态裁决 `ok / tampered / no-key`,篡改可检出、跨信任域不误报。
52
+
53
+ **只读承诺。** 不写任何外部 agent 的会话库,不访问网络,不回放历史工具调用;原文不进卡片,卡里只有指针。
54
+
55
+ ## 一即是全 · 四轴一根链
56
+
57
+ 交接从来不是一件事,是四件——但四件共用同一张 `handoff: 1` 卡面、同一个 `~/.handoff` 总线、同一根 git 同步链,落到用户手里永远是一条命令的事:
58
+
59
+ - **会话轴**:`/handoff` 把干到一半的会话蒸馏成六段交接卡寄存,任何 agent 开局 `/inbox` 取件接着干;
60
+ - **上下文轴**:未提交改动随卡附补丁、仓库基线(origin / HEAD / 分支)进卡,新机器按 clone → checkout → apply → 跑测试四步复原寄存现场;
61
+ - **记忆轴**:CLAUDE.md / AGENTS.md 等记忆快照打包成卡随行,取件方按「建议加载」段吸收进自己的记忆文件;
62
+ - **配置轴**:全家桶加密备份的清单+指针上卡、密文包随同步盘走,新机器 dry 预演 → confirm 还原 → 可回滚。
63
+
64
+ 一张卡带走的是什么?`handoff_sync` 一条命令之后,另一台机器的收件箱里躺着的不只是「聊到哪了」,是接着干活需要的全部现场:六段会话、未提交的代码、长期积累的记忆、可复原的环境。卡上的 `axis` / `payload` 立约标记让取件方一眼知道该「接着干」「按条目吸收」还是「先预演再落盘」——四轴一即是全,一根链走完。
65
+
66
+ ## 工具与命令参考
67
+
68
+ **agent 工具(模型可调)**
69
+
70
+ | 工具 | 说明 |
71
+ |---|---|
72
+ | `foreign_session_read` | 只读拉取九家会话。`action=list` 列候选(标题/时间/轮数);`action=show` 按引用(空/latest/id/前缀/路径/标题关键词,歧义返回候选不猜)返回结构化摘要:标题、轮数、首条请求、尾部进展、涉及文件 top15、六段卡素材。原文仅在显式传 `limit` 时分页给出;探测/解析失败返回 `{ ok: false, error }` 不抛 |
73
+ | `handoff_push` | 当前会话寄存为协议卡。六段文本可选传入,留空段从会话事件流确定性兜底(不调 LLM);未提交改动自动附补丁;返回 `{ ok, id, path, coverage, patch? }` |
74
+ | `handoff_inbox` | `action=list` 列待取件;`action=load` 取件(消费即弃,附签名与 git 核验的 MISMATCH / UNAVAILABLE 警告) |
75
+ | `handoff_sync` | 换机同步:`action=setup` 启用(git 仓库地址,凭据走系统 git 不入插件);`action=now` 拉推一步到位;`push`/`pull`/`status` 单向与只读。已消费的卡经 archived tombstone 不在另一台机器重放 |
76
+ | `handoff_env` | 环境备份/恢复:全家桶(设置/插件登记/会话库/用户 skills/工作区登记)打包成单个 AES-256-GCM 加密文件随同步跨机;`dry` 预演三态 diff → `apply`(confirm 确认,被覆盖原物自动 checkpoint)→ `rollback` 可逆 |
77
+ | `handoff_memory` | 记忆快照。`action=scan` 只读列各 agent 记忆文件(含大小/预览);`action=push` 勾选打包成卡寄存,取件方按「建议加载」吸收 |
78
+
79
+ **slash 命令(用户敲,agent 按指引执行)**
80
+
81
+ | 命令 | 说明 |
82
+ |---|---|
83
+ | `/resume-*`(九家) | 解析引用 → 只读拉取 → 四态标注(外来历史一律不可信、不覆盖当前指令)→ 六段卡注入当前轮 → 末尾问一句「要不要顺手寄存进收件箱」 |
84
+ | `/handoff` | 按协议语义六条(证据账本四态、原文不进卡、产物只引路径、redact、建议加载段、反向锚定+剪枝)把当前会话蒸馏成卡寄存 |
85
+ | `/inbox` | 列 pending 让用户挑;取件后注入当前轮,强调卡片是 HISTORY_REPORTED,执行前先核对 git 状态 |
86
+
87
+ ## 跨机器接力
88
+
89
+ `HANDOFF_HOME` 指向同步盘目录或 git 仓库,收件箱即多机共享:A 机 `handoff_push` 寄存,B 机开局 `/inbox` 取件。一句环境变量,零代码。同步盘里的卡片在手机文件查看器里同样可读。同步服务的冲突副本不会变成幽灵卡:同 id 自动去重只显示一次,原件已取走的迟到副本进收件箱的拒收清单(有因可见),半截文件同理。
90
+
91
+ **内置同步(0.2.0)**:设置卡「换机」页填一个私有 git 仓库地址即可——A 机 `handoff_sync`(setup + now),B 机同址 setup 后 now,卡就出现在收件箱里。凭据完全交给系统 git(插件零存储凭据,地址带 `user:pass@` 直接拒收);同步范围 = pending/archived 全部卡与机器信封 + 签名密钥 + 环境备份包,机器本地记录(生命周期日志/取件溯源/插件开关)不参与;合并冲突中止并诚实报错,本地文件原样保留。
92
+
93
+ ## 质量与证据
94
+
95
+ 接力质量不是感觉,是数字、测试与第三方可复核的证明(口径与复现步骤见 [eval/README.md](eval/README.md)):
96
+
97
+ - **回测**:50 张真实交接卡回测延续率 34.7%;done 段带账本标注的卡延续率 50%、无标注 0%。端到端双卡接力真 host 真模型评测 PASS。
98
+ - **回归**:13 份 golden files 逐字节冻结真实会话脱敏语料,上游存储布局一变就红在提交前。
99
+ - **安全**:威胁模型见 [THREAT-MODEL.md](THREAT-MODEL.md);红队套件 8 组随 CI——密钥闸覆盖六段正文、全部标量与随卡补丁 diff。
100
+ - **协议**:`conformance/` 可执行套件(MUST 9 条推导自 SPEC);参考实现与「只读 SPEC 从零手写」的独立第二实现双双符合。
101
+ - **互通**:INTERCHANGE v1(dsh-chat-import)↔ handoff: 1 双向转换,转换产物经对方插件 v0.26.2 真实导入互验。
102
+
103
+ ## 定位
104
+
105
+ AI 编码的「延续上下文」需求由三层各管一段:spec 工具(spec-kit / OpenSpec 一类)管**设计态**——要做什么、验收是什么;记忆层(mem0 / Letta / dsh-hippo 一类)管**偏好态**——项目约定与对话事实的沉淀;dsh-takeover 管**运行态**——实际跑到哪、停在哪、哪些陈述是当下观察、哪些只是历史转述、卡出自哪台机器。三层互补,不互相替代。
106
+
107
+ 同类机制的一句话区分:**他们做「转换后换一家 CLI 原生续跑」「环境配置备份」「导航搜索」「运行时编排」或「任务状态搬运」,我们做 harness 内接管 + 换机上下文同步(卡与备份随你的 git 仓库走,交接语义与账本不换人)。**
108
+
109
+ ## 协议采用
110
+
111
+ `handoff: 1` 是开放协议:六段 Markdown 卡 + YAML frontmatter + `~/.handoff` 共享目录,任何工具可实现、可审计、可互操作(开放协议的资格由独立第二实现背书,见[质量与证据](#质量与证据))。已互通:[dsh-chat-import](https://github.com/Nwflower/dsh-chat-import)(INTERCHANGE v1 双向转换互验)。你的工具若读写同一目录或卡片格式,欢迎开 issue 登记互通。
112
+
113
+ ## 权限范围
114
+
115
+ 写 `~/.handoff/`(`HANDOFF_HOME` 可覆盖)、读 git 状态、只读九家 agent 的本地会话库(zcode 与 cursor 走 sqlite readonly,随开随关;`HANDOFF_ROOT_<家>` 可覆盖各家根路径)。cursor 只导入支持的 transcript / store 记录,grok 只读可见 updates.jsonl 流(永不读 chat_history.jsonl 原始模型上下文),gemini 只读本地 chats/ 会话文件。0.2.0 起两个显式例外:①`handoff_sync` 经系统 git 与**你显式配置**的仓库通信(插件进程内不构造网络连接,零存储凭据);②`handoff_env` 备份/恢复读写全家桶配置路径——恢复必须先 dry 预演再 confirm 落盘,被覆盖原物自动 checkpoint 可回滚,凭据类文件只存在于加密包内(详见 THREAT-MODEL T6/T7)。不复活外部进程,不回放历史工具调用,原文不进卡片。
116
+
117
+ ## 开发
118
+
119
+ ```bash
120
+ pnpm install # @deepseek-ai/* 走 npm registry;@agent-handoff/* 走 file: 链接
121
+ npm run typecheck
122
+ npm test # node:test + tsx
123
+ npm run build # tsdown → lib/(@agent-handoff/core + readers 内联打包)
124
+ node scripts/smoke-foreign.mjs # 实机冒烟:进程内挂载 lib/,真实 dispatch foreign_session_read
125
+ node scripts/smoke-userflow.mjs # 真用户旅程:拉本机真实 zcode/opencode 会话 → 寄存 → 取件全链路
126
+ ```
127
+
128
+ `@agent-handoff/core` 与 `@agent-handoff/readers` 未发布 npm,以 `file:../agent-handoff/packages/*` 依赖、构建时 bundle 进 `lib/`。
129
+
130
+ ## License
131
+
132
+ MIT
@@ -0,0 +1,22 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <defs>
3
+ <linearGradient id="bt-bg" x1="0" y1="0" x2="1" y2="1">
4
+ <stop offset="0" stop-color="#6366F1"/>
5
+ <stop offset="1" stop-color="#8B5CF6"/>
6
+ </linearGradient>
7
+ <linearGradient id="bt-sheen" x1="0" y1="0" x2="0" y2="1">
8
+ <stop offset="0" stop-color="#ffffff" stop-opacity=".26"/>
9
+ <stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
10
+ </linearGradient>
11
+ </defs>
12
+ <!-- 圆角方底:应用图标衬底,深/浅底上都有自带对比 -->
13
+ <rect x="2" y="2" width="60" height="60" rx="15" fill="url(#bt-bg)"/>
14
+ <rect x="2" y="2" width="60" height="60" rx="15" fill="url(#bt-sheen)"/>
15
+ <rect x="2.75" y="2.75" width="58.5" height="58.5" rx="14.25" fill="none" stroke="#ffffff" stroke-opacity=".22" stroke-width="1.5"/>
16
+ <!-- 接管:双箭头 » 进格 |,读作"接管席位"——别的 agent 干到一半,你进来接着掌控 -->
17
+ <g fill="none" stroke="#ffffff" stroke-width="6" stroke-linecap="round" stroke-linejoin="round">
18
+ <path d="M15 19 L27 32 L15 45"/>
19
+ <path d="M29 19 L41 32 L29 45"/>
20
+ </g>
21
+ <rect x="46.5" y="17" width="6" height="30" rx="3" fill="#ffffff" opacity=".9"/>
22
+ </svg>
@@ -0,0 +1,9 @@
1
+ # 官方 bundle 层:`dsh plugin add` 把它合入 profile。
2
+ # 行按包名解析,安装进 profile 的副本就是启动副本。
3
+ # host 半:工具 handoff_push / handoff_inbox / foreign_session_read + slash
4
+ # /handoff /inbox /resume-*×8 + webServer 路由 /dsh-takeover/*(设置卡 JSON API)。
5
+ # 浏览器半(设置页「dsh-takeover」卡)由 package.json 的 dsh.client 声明 +
6
+ # exports["./client"] 提供,不进本 patch。
7
+ - insert:
8
+ - id: dsh-takeover
9
+ name: dsh-takeover
package/cordis.yml ADDED
@@ -0,0 +1,5 @@
1
+ # portable overlay:仅相对包名。--patch 相对 profile 目录解析,
2
+ # 而不是相对本 checkout 裸跑 `pnpm dsh`。
3
+ - insert:
4
+ - id: dsh-takeover
5
+ name: './lib/index.js'