dsh-project-context
为 DeepSeek Harness (dsh) 提供项目级持久上下文：把 dsh 的事件流会话在项目内留档， 再依次蒸馏成记忆、上下文与技能，最后在上下文将满时交接给新会话。
当前版本 v0.4.3；逐版本变更见 CHANGELOG.md。
安装
cd <这个仓库> && pnpm install && pnpm build
dsh plugin --profile web add /path/to/dsh-project-context # 自动应用包内 cordis.patch.yml
dsh --profile web --dump-config | grep -A3 project- # 验证
仓库带着构建产物（lib/ 纳入跟踪），pnpm build 只在你要改 src//client/ 时才需要（见「开发」）。
卸载：dsh plugin --profile web remove dsh-project-context。
架构与数据流
会话（事件流）
│ ① 存档：无模型调用，逐轮增量 append
▼
session.jsonl（唯一权威）──► session.md（全量渲染，人读）──► INDEX.md（每会话一行）
│
├─ ② 整理（1 次调用，节流） raw 对话 + MEMORY/CONTEXT ─► CONTEXT.md + MEMORY.md ─► 每轮注入
│
├─ ③ 沉淀（1 次调用，低频） MEMORY/CONTEXT + 索引 ─► skills/<name>/SKILL.md
│ └ 证据不足（<2 个已存档会话）─► memory/skill-candidates/<name>.md
│
└─ ④ 交接（1 次调用） 当前会话 ─► 新会话（旧段摘要 + 最近原文 + 旧存档指针）+ HANDOFF.md
| 阶段 | 插件（子路径） | 触发 | 产物 |
|---|---|---|---|
| ① 存档 | project-context（主入口，/context、/session-log） |
事件驱动（见下）；/session-log |
session.jsonl、session.md、INDEX.md |
| ② 整理 | project-memory（/memory、/memory update） |
idle / disposed + 节流；命令 | CONTEXT.md + MEMORY.md（每轮注入） |
| ③ 沉淀 | project-autolearn（/autolearn） |
材料有更新 且（累计轮 ≥ autolearnTurns(20) 或距上次 ≥ autolearnIntervalMs(30min)）且项目内至少有一个真实存档 |
.agents/skills/<name>/SKILL.md；证据不足写 skill-candidates/ |
| ④ 交接 | project-handoff（/handoff） |
上下文占用越过阈值 且没有仍在运行的后台子代理，且触发它的 turn/end 之后本会话未再开新轮；命令 |
新会话 + HANDOFF.md |
四个插件是同一包内的独立 cordis 插件，共享一份配置与生命周期
helper（会话身份、串行后台任务、落盘跟踪）。② 的 raw 输入由本会话事件派生；③ ④
只作用于顶层会话（origin !== "subagent"），① 对子会话同样留档。
数据布局
<project>/.agents/
├── skills/<name>/SKILL.md # ③ 沉淀的项目技能（description 常驻，body 按需加载）
└── memory/
├── memory.jsonl # ② 权威记忆：append-only 记录 {"ts","op":"replace"|"append","text"}
├── MEMORY.md # ② 由 journal 折叠渲染（人读 / 注入 / 外部手改入口）
├── MEMORY.md.memory-backup-* # 覆写前的字节级备份（保留最新 5 份；1 小时内的不删）
├── MEMORY.md.lock / .steal # 跨进程写锁（30s 陈旧；claim 防双抢）
├── session-index.lock / .steal # ① 索引的跨进程写锁（同一套 30s/35s 参数；与 MEMORY.md 分开）
├── memory-log-*.jsonl # journal 超 512KB 折叠后的归档（保留最新 5 份）
├── CONTEXT.md # ② 工作态：摘要 / 关键点 / open tasks（每轮注入）
├── HANDOFF.md # ④ 最近一次交接摘要（含旧存档指针）
├── autolearn-state.json # ③ 沉淀闸门（材料时间戳 + 上次尝试时刻，跨重启生效；本地件，被忽略）
├── skill-candidates/<name>.md # ③ 待确认候选（approve 后转正）
├── .gitignore # 首次写出时生成：忽略 journal / 备份 / 锁 / errors.log / autolearn-state.json 等本地件
├── errors.log # 各阶段捕获的异常；密钥脱敏后写入，单条截断 8000 字符，>1MB 轮换保留最新 64k
└── session-logs/
├── INDEX.md # ① 机械索引：每会话一行，按 id 去重、只留最新 200 行
├── .gitignore # 首次写出时生成，忽略整个目录
└── <session-id>/{session.jsonl,session.md}
记忆与存档同构：journal 是唯一权威、MEMORY.md 是派生渲染。
写入顺序固定为「先在锁内做字节级备份 → 追加 journal → 渲染 MEMORY.md」，因此崩溃只会让渲染落后于
journal，读取时以 journal 折叠结果为准；手改 MEMORY.md（且比 journal
新）会被读取优先采信，并在下一次整理时作为一条记录收进 journal 历史。损坏的 journal
行会被跳过并计数（写 errors.log，/memory 提示），整份不可读时 fail closed 而不是静默回退。旧版
<memory>/session-index.md 会在每次写索引时并入新索引（同 id 以新索引的行为准）、链接改写为相对
形式并按行内日期排序；只有它持有的每一行都已写进新索引时才删除它，因此 200 行上限丢行时旧文件留在
原处、下次再采。
配置不在项目内：开关与参数写在当前 profile 的设置 patch 文档里（project-context 条目，
设置卡片编辑；dsh 0.1.7-rc.2 会把旧的 ~/.dsh/settings.yaml 段一次性导入该文档，文件改名为
settings.yaml.imported）。dsh
自身仍把会话存在 ~/.dsh/sessions/…，session-logs/ 是项目内副本，便于随项目阅读与检索。
更早版本的目录布局在 session 启动时自动迁移（旧记忆 / 上下文 / 日志 /
技能各归其位；文件/目录类型冲突时两侧都保留并在日志点名；.omp 旧记忆存在但读不了会记进
errors.log 而不是静默跳过）。
源码结构
src/
├── project-context/ # ① 存档（包主入口 "dsh-project-context"）
│ ├── index.ts # 插件入口：turn/end 追加、idle/disposed 落盘、/context、/session-log
│ ├── session-log.ts # session.jsonl / session.md 写入
│ ├── session-index.ts # INDEX.md 渲染与跨进程锁
│ ├── archive.ts # 存档回读（渲染成对话供 ③ 取证）
│ ├── session-jsonl.ts # session.jsonl / pi JSONL 解析与索引元数据
│ ├── zip.ts # dsh 导出 zip 的目录、deflate 条目与 session.jsonl 读取
│ └── import.ts # 回填入口：单会话 / 单文件 / 整目录，幂等
├── project-memory/ # ② 整理（"dsh-project-context/memory"）
│ ├── index.ts # 插件入口：整理 pass 编排、/memory update、/memory 回执
│ ├── memory-store.ts # 记忆子系统对外门面（不变量文档 + 公共 API 再导出）
│ ├── journal.ts # 追加日志：解析 / 折叠 / 轮转 / 归档
│ ├── record.ts # 一次写入：采纳外部编辑、追加、重建渲染、legacy 导入
│ ├── load.ts # 读取路径：journal / MEMORY.md / legacy，损伤报告
│ ├── document.ts # 文档规范化与按行截断标记
│ ├── poison.ts # 存储回复（JSON poison）解码与归一化比较键
│ ├── backup.ts # 写入前字节级备份与清理
│ ├── consolidate.ts # 整理 pass：节流、单飞、提示与结果落地
│ └── context-doc.ts # CONTEXT.md 渲染
├── project-autolearn/ # ③ 沉淀（"dsh-project-context/autolearn"）
│ ├── index.ts # 插件入口：闸门、/autolearn 命令
│ ├── skill.ts # 技能形状、SKILL.md 渲染、正文/描述安全校验
│ ├── candidate.ts # 候选文件、准入规则、approve/reject 转换
│ ├── inventory.ts # 技能清单（进提示词）与可取证的历史会话 id
│ ├── parse.ts # 模型回复 → 候选；回溯预算
│ ├── prompt.ts # 提示词：共享规则、正向 pass、回溯 pass
│ ├── pass.ts # pass 本身：每项目节流 + 单飞
│ └── learn-state.ts # 项目本地状态（闸门时间戳等）
├── project-handoff/ # ④ 交接（"dsh-project-context/handoff"）
│ ├── index.ts # 插件入口：session/event 监听、attempt 编排、命令注册
│ ├── threshold.ts # 触发点 min(quality, capacity) 与护栏覆盖报告
│ ├── conversation.ts # 会话切分、未答问题、文件索引、语言解析
│ ├── summary.ts # 摘要提示与输出预算、HANDOFF.md 与首条消息文本
│ ├── child.ts # 子会话创建、模型/权限携带、放弃回滚
│ ├── perform.ts # 一次交接事务（摘要 → 落盘 → 播种 → 切换标记）
│ ├── classify.ts # 失败分类：延后 / 暂态 / 终态
│ ├── guard.ts # 子代理与轮次落定守卫
│ ├── state.ts # 进程内按会话标记与测压节流
│ ├── runtime.ts # 宿主服务结构视图与路由解析
│ ├── auto.ts # 自动触发：测压并在越过阈值时交接
│ ├── command.ts # /handoff 参数解析、status 回执、手动交接
│ ├── language.ts # 交接语言检测、标题本地化、陈旧提示识别
│ ├── marker.ts # 交接会话标记（host 与浏览器共用）
│ └── watch.ts # 浏览器侧自动切换
├── shared/ # 四个插件共用
│ ├── lock.ts # 跨进程写锁（记忆文件与会话索引共用，泛型 target）
│ ├── project-state.ts # 项目状态**门面**（原始布局/迁移文档 + 公共 API 再导出）
│ ├── paths.ts # 项目根定位（git + 缓存）与全部路径助手
│ ├── limits.ts # 存储文档与提示输入的字符预算
│ ├── files.ts # 文件系统原语：原子写、缓存读、探测、移动/合并、临时清理
│ ├── gitignore.ts # `.agents/.gitignore` 托管块
│ ├── error-log.ts # errors.log 轮转、诊断截断与脱敏写入
│ ├── redact.ts # 日志脱敏
│ ├── migrate.ts # 旧布局（`.pi` / `.agents/memory/skills` / `~/.omp`）一次性迁移
│ ├── config.ts # 默认值与字段定义
│ ├── settings.ts # 设置命名空间（web 卡片 ↔ cordis 配置）
│ ├── lifecycle.ts # 会话身份、串行后台任务、落盘跟踪
│ ├── text.ts # 文本计量、裁剪与渲染（回复头 / 截断 / token 估算）
│ ├── output-budget.ts # 辅助调用的输出预算：推理预留、自适应边界、重试余量
│ ├── conversation.ts # 会话渲染成对话分段 + 记忆输入适配
│ ├── reply-json.ts # 从模型回复里读取结构化 JSON（容错扫描 + 解析）
│ └── model-call.ts # 插件来源的辅助模型调用、路由与元数据
client/ # 设置卡片、字段表、zh/en 文案（bundle 进 lib/client.js）
scripts/
├── build-client.mjs # 客户端 bundle
└── import-archives.mjs # 回填 CLI（不依赖运行中的 dsh）
自动归档（①）
| 时机 | 动作 |
|---|---|
turn/end |
session.jsonl 追加增量（不渲染 Markdown） |
agent idle / disposed |
追加 JSONL + 追加 session.md + upsert INDEX.md |
session/disposed |
收尾写出 + 释放进程内游标 |
session/flush |
等待进行中的写入（上限 90s），保证落盘 |
/session-log write |
手动立即写出（含索引刷新） |
session.jsonl：首行 header，之后每个 dsh 事件一行。进程内按游标增量 append，长会话不重写整份；每次写入记下目标文件的 inode + 字节数 + mtime，只有三者都仍是本进程写下的那一份才追加——被外部改写（--replace回填、手工截断/重写）时下一次写入整份重建，不把新事件接到别人的内容后面； 没有新事件的写入不产生任何字节。session.md：全事件 pretty-JSON 渲染（含 tool 调用/结果、thinking、compaction、模型切换）， 供人阅读与交接导航，不参与自动流程。INDEX.md：每会话一行- [id](id/session.md) — YYYY-MM-DD — 标题，标题取session/title（回退首条用户消息），同一会话原位刷新、按 id 去重后只留最新 200 行；同一进程内的写入走一条写链，跨进程则走<memory>/session-index.lock（与MEMORY.md同一套 30s 陈旧 / 35s 等待参数；仍在运行旧构建的宿主不遵守此锁，重启后才受同一把锁约束）。等不到锁时这次 索引写入失败并记进errors.log，该行在下一轮写索引时补上。- 项目根 = 会话 cwd 的 git 顶层（
git rev-parse --show-toplevel），非 git 目录回退 cwd；首次写日志时自动放一个忽略整个目录的session-logs/.gitignore，不动项目根 ignore。 - 只归档插件启用后实际发生的会话（首次写出会带上该会话此前的完整事件快照）；
更早结束的会话用下面的回填补。异常写入
.agents/memory/errors.log（scopesession-log），单条截断 8000 字符，文件超过 1MB 时保留最新约 64000 字符并写入截断标记，不打断会话。
回填历史会话（①补，无模型调用）
# CLI（不依赖运行中的 dsh；自带 zip 读取，无需 unzip）
node scripts/import-archives.mjs --project <项目根> <archive.zip|session.jsonl|目录>…
node scripts/import-archives.mjs --project . --dry-run sessions_archive/ # 只解析并报告
node scripts/import-archives.mjs --project . --replace --no-md archives/ # 覆盖；不渲染 session.md
# 交互 profile 里：/session-log import sessions_archive/
- 导入结果落在
<项目根>/.agents/memory/session-logs/<session-id>/，session.md用与实时路径同一份渲染器、INDEX.md用同一份索引写入， 因此后续整理/沉淀/交接读到的回填会话与实时归档无法区分。 session.jsonl逐字节保留原文（只把结尾规范化成一个换行；重序列化会丢掉旧版 header 里已删除的字段）。- 幂等：已归档的会话默认跳过，
--replace才覆盖；全程不调用模型。--no-md只写 canonical JSONL + 索引（session.md体积是 JSONL 的数倍，纯机读场景可省）。 - 输入支持 dsh 自己导出的 zip：会话日志在 zip 根，文件名随格式代次变化（当前
session.v3.jsonl，第 0 代才是session.jsonl），子代理日志在subagents/<id>/下——导入只看根目录并优先取最高代次。 - 实测规模参考：21 个 zip / 586,909 个事件 → 13s 导入，约 1.1GB（
session-logs/自带.gitignore，不随项目入库）。
配置
Settings → Plugins → 已安装列表里的 dsh-project-context 一行（打开后是记忆整理 / 技能沉淀 /
自动交接三区，共享的辅助模型路由在记忆整理区末尾），host 侧实时生效。卡片挂在插件页的
plugins.bundle.config 槽位、键为 bundle 包名 dsh-project-context（该槽位按包名分派；
plugins.item 归官方插件卡片），经宿主的 configForms 服务读写本命名空间，并由 whileServed
门控——profile 没装 host 半时页面上不会留下痕迹。
卡片本身不是自绘的：框架、保存按钮、文本/数字行、只读与未加载提示都来自平台的
@deepseek-ai/dsh-client-ui-primitives（SettingsForm / SettingsValueField / Switch / Pill /
Tag / Button），暂存写入用平台的 SettingsFormModel，本仓库只提供一张字段表
（client/card-fields.ts：21 行 = spec + 投影 + 渲染行三者共同的唯一来源）和一份纯几何、零颜色
的排版样式表。因此保存语义也是平台的：一次原子 mutate（带 revision fence）、Host 拒绝时保留草稿，
离开页面即丢弃草稿——所以卡片上没有「放弃」按钮（与官方设置页一致）。
命名空间就是 Loader 条目 id project-context：dsh 0.1.7-rc.2 起，设置表单由归属插件模块导出的
Config schema 投影而来（SettingsForms.schema(entry) 读 entry.fiber.runtime.Config），
不再有 settings.register / installSection 这类运行时注册 API。所以 host 半边把
PluginSettingsSchema 作为 Config 从 project-context 入口导出；四个插件共享同一个命名空间
（该入口发布自己 fiber 的 live config，其余三个读取它），base 层因此恒为
cordis.patch.yml 里 project-context 那一行的 config:，改其余三行不生效。
新增字段必须带 volatile 标记（.extra("volatile", true)，见 src/shared/settings.ts）：
describe() 用 volatileForm() 过滤，一份没有该标记的 schema 会让整个条目从被服务命名空间里
消失，卡片随之无错误、无日志地不渲染（test/settings-form.test.mjs 逐个字段钉住这条）。标记同时让
这些字段以活引用交给插件，所以 resolvePluginConfig 会按 cosmokit 的共享协议解引用，而共享设置
是读取器而非快照——loader 对只改 volatile 字段的写入是原地提交引用、不重启条目。
设置值写在当前 profile 的 patch 文档里（SettingsForms.documentPath），不再是
~/.dsh/settings.yaml：rc.2 在 Loader 安定后把该文件里的旧段一次性导入 profile（文件改名为
settings.yaml.imported），既有配置因此自动接续。面板未覆盖的字段回落到 profile 配置，再回落到默认值。
| 字段 | 默认 | 说明 |
|---|---|---|
archiveEnabled |
true |
关掉后不再自动写会话存档与索引（/session-log write 仍可用） |
memoryEnabled |
true |
关掉后不再自动整理（命令仍可用） |
consolidateTurns |
6 |
较上次整理新增的用户消息数达到后在 idle 触发 |
consolidateIntervalMs |
300000 |
自动整理最小间隔 |
forceDedupeMs |
15000 |
强制调用去重窗口 |
autolearnEnabled |
true |
关掉后不再自动沉淀技能（命令仍可用） |
autolearnTurns |
20 |
自上次沉淀累计的用户消息数阈值 |
autolearnIntervalMs |
1800000 |
自动沉淀最小间隔；仅在有新 MEMORY/CONTEXT 内容时执行 |
maxTokens |
8192 |
辅助模型调用的起始输出上限；整理会按「记忆+上下文需回吐的 token 数」自适应上调 |
maxOutputTokens |
32768 |
自适应上调的边界（≥256）：输入很大时把单次输出上限往它上调。它是自适应上调的边界而不是绝对天花板：maxTokens 更大时以 maxTokens 为准；若适配器自己给出更小的模型上限，则以模型上限为准。交接摘要的失败重试同样被该边界压住（min(2×maxTokens 或 32768 的较大者, max(maxTokens, maxOutputTokens))；边界低于起始上限时重试被取消，只发一次原请求） |
provider / model |
空 | 辅助调用路由覆盖；默认用 agent 最近一次请求的路由 |
handoffEnabled |
true |
关掉后不再自动交接（含交接子会话标题的事后改名），/handoff 仍可用 |
handoffThresholdAuto |
true |
自适应阈值 = 护栏取小：质量层（autoCompactTokenLimit ?? knee(window)——宿主暴露可用输入上限时优先用它，目前 dsh 只暴露 contextWindow，故恒回退膝曲线）与可用窗口；基线/保留量只决定可行性下限。false 时用固定比例 |
handoffThresholdRatio |
0.4 |
handoffThresholdAuto: false 时的固定比例（0.1–0.95）；被 4K 安全边际压掉时阈值标签会写明实际值 |
handoffBudgetSummaryTokens |
64000 |
自适应模式：每次摘要移交的对话量（8000–200000）。这是手动设定的阈值请求，触发点由护栏决定；一旦被护栏压掉，/handoff status 点名被覆盖的值与压住它的那条护栏，不静默 |
handoffBudgetRecentTokens |
20000 |
最近对话原文带入新会话（0–200000，0 = 只带摘要）。切点按消息而不是按轮，且至少要保留一条消息，所以实际带入量最多比它多一条消息（每条渲染后 ≤ 4000 字符）。用户自己的最后一次输入另有一段独立带入（见 ④），不受该值影响 |
handoffThinking |
off |
摘要调用思考级别：off 或 session |
handoffLang |
auto |
交接语言：auto 按对话判定（CJK≥2 → zh；纯拉丁≥20 字母 → en；否则沿用上一条交接提示的语言，兜底 en），也可固定 zh / en |
handoffPendingQuestion |
defer |
最后一条助手消息是未答问题时：defer 让自动交接等回答（手动 /handoff 始终执行），wait 照常交接并把问题作为独立段落带进新会话，且该段落取代常规的「先做下一步」结尾（= pi 侧 handoffGuard: wait） |
命令（web/交互 profile）
| 命令 | 行为 |
|---|---|
/context |
显示 CONTEXT.md、会话日志与索引路径 |
/memory update |
立即整理一次（②）：更新 MEMORY.md 与 CONTEXT.md；回执按实际结果区分已更新 / 被截断 / 无新内容 / 被去重 / 失败 |
/session-log |
只读：显示会话日志目录与索引路径，并提示用 /session-log write 立即写出 |
/session-log write |
立即写出当前会话 JSONL + Markdown（并刷新索引） |
/session-log import <path…> |
回填导入历史档案（zip/jsonl/目录，幂等、无模型调用） |
/memory |
显示项目记忆路径与状态 |
/autolearn |
立即沉淀技能（③）；证据不足时按索引回读 session.jsonl；list / approve <name> / reject <name> |
/handoff |
立即交接：摘要当前会话并另开新会话继续 |
/handoff status |
显示开关、阈值、当前上下文占用与保留量；手动设定的阈值被护栏压掉时点名被覆盖的值与压住它的护栏（质量膝 / 容量 / 安全边际）；自动交接因“没有更早内容可摘要”被跳过时，一并报告从何时起被跳过与原因（重新可摘要即清除） |
/handoff on / off |
开关自动交接 |
/handoff threshold auto / threshold 0.4 / threshold 60% |
切自适应；给比例则切固定比例。裸 auto 与裸比例已退役，不再生效 |
/handoff budget summary 64k / budget recent 20k |
每次摘要的移交量 / 逐字保留的近端对话（budget recent 0 = 只带摘要）；summary 是被护栏约束的请求，被压掉时 /handoff status 点名 |
/handoff thinking off|session |
切换摘要 thinking |
/handoff pending defer|wait |
未答问题时：延后交接 / 照常交接并把问题带进新会话 |
/handoff lang auto|zh|en |
交接语言：自动判定或固定中文 / 英文 |
说明
- ② 由
project-memory独占：idle / disposed 触发，session/flush等待进行中的调用；同一项目一次只跑一个整理 pass，版本去重避免重复写入。 - ③ 由
project-autolearn独占：先读MEMORY.md+CONTEXT.md+INDEX.md，模型可返回至多 3 个待回读会话，插件从对应session.jsonl提取对话（忽略assistant/message.stream等大负载、各截断 16KB）后二次调用。闸门时间戳持久化在.agents/memory/autolearn-state.json， 重启后不会重复沉淀；它记录的是本次真正蒸馏的材料时间戳（而不是调用时刻）， 所以整理恰好在同一 idle 写入的新记忆不会被当成“已沉淀”而漏掉。 自动沉淀时项目里一个真实存档都没有就直接跳过（正式技能要两个、候选要一个，跑了也不会有产物， 白花一次模型调用；/autolearn显式强制仍会调用）；prompt 里带<existing-skills>清单并禁止重名；已学习技能的正文不再随每次提示词推送，模型要用inspect_skill点名索取 （最多 2 个），跟进轮才附上——没展示过正文的已学习名字一律拒绝覆盖 （body not shown this pass）；回读前逐个校验session-logs/<id>/session.jsonl真实存在（模型幻觉出的 id 会被丢弃，全部落空时按“无证据”处理）；输出上限按需自适应上调（受maxOutputTokens约束）。正式技能需要至少两个已验证的存档会话做证据，只举一个会话的提案进skill-candidates/等/autolearn approve；已存在的技能不覆盖，含提示注入话术的 body 一律拒绝。 - ④：摘要输入是
MEMORY.md、最近对话窗口与文件操作索引，不依赖整理是否运行；摘要失败退避 5 分钟；未答问题按handoffPendingQuestion处理——wait会把问题原文作为独立段落带进新会话（此前只跳过延后、问题实际会丢）， 并以该段落取代常规的“先做下一步”结尾。 用户自己的最后一次输入会被单独带入，且不依赖handoffBudgetRecentTokens：它既可能是用户手打 的消息，也可能是ask_user_question的选择或自填答案（读answers[].selected与answers[].custom两者）。它与“未答问题”段落按位置取胜者，只有更新的那一项进入续会话——所以 用户刚答完的问题不会被当成“仍在等他回答”，而答案之后新问的问题也不会被旧答案顶掉。用户跳过的 问题、以及 timed 模式返回的{"pending":true,…}都不算表态，不会被当成“用户说过的话”带入（上游tool-ask-user的两种结果形状里只有answers是答案）。带入该段落时结尾改为「用户已经表态，不要 再问一遍；若球在用户手上就说清在等什么」，正是为了拆掉“没有下一步就再问一次”那条指令。 自动交接在本会话还有未结束的后台子代理时延后（枚举读subagents.listChildren()并取其中mode: continuable的直接子会话：0.1.6 的分类行与 0.1.7-alpha.1 的裸目录行{id, createdAt, mode, label}都带mode，一次读取同时覆盖两个版本；是否在跑读活体注册表agents.get(id)?.status === "running"，不能读清单里的activity——那个字段的含义是「Session store 还持有这个子会话」，落定后仍驻留的 teammate 也会报running，会把交接无限期挡住；上游list_agents在同样位置重新判状态，并写明 “Report turn activity without exposing whether the child is loaded”。 读不懂的清单必须交回会话日志扫描，而不是当成「没有在跑」：diagnostic行、没有mode的行、查询失败、 或拿不到agents服务都走日志，只有空清单才是「确实没有」。teammate 是同一个注册表里的 continuable 直接子会话（subagents.startContinuable建的，会写subagent/catalog），所以正在跑的 teammate 同样让自动交接延后。手动/handoff now也受这条守卫约束：交接会退休旧会话并取消其中在跑的 子代理，所以有在跑的直接拒绝并点名——回执给出数量、子会话 id 与杠杆（先interrupt_agent，或等它们 落定后重试），且不创建任何子会话）： 子代理落定会唤醒父会话并开启新一轮，此时交接会变成父子两个会话同时改同一个项目（本仓库 2026-09-16 实际踩到过），所以等到没有在跑的子代理再交；同一个失败还会从另一侧发生——触发点是turn/end，但 harness 会在当前轮一关就立刻把队列里的用户消息开成下一轮， 所以只要交接时队列里已经有消息，父会话在插件写摘要的那几秒里就已经在跑新一轮了（本仓库 2026-09-17 实际踩到过：turn/end与下一轮turn/start只差 4 毫秒，8.3 秒后子会话被创建，父子同时改了同一处代码）。所以自动交接在触发它的那个turn/end之后本会话又开了新轮时直接放弃（不算失败、不占失败退避、不写errors.log，只记一条限频服务端日志）。检查点有四处：摘要调用前、摘要调用后、 投递首条消息前（创建子会话是 RPC、再带上权限与模型，这段窗口里开的新轮同样要拦）、 以及投递之后（消息 RPC 本身也是窗口）。前两处还没创建任何东西，直接放弃；后两处子会话已存在， 于是撤销而不是硬删（dsh 没有删除会话的 RPC）：未播种的——不播种、标题改成handoff deferred · …（不带切换标记，浏览器不会切过去）、并用workspaceRegistry.archiveSession()归档掉，侧栏不会多出一个空会话（归档只隐藏不删除，客户端uiWorkspace.unarchiveSession可以还原）；已播种的——先用sessionController.cancel()撤销刚投递的那一轮，取消成功才归档，取消失败或运行时没有该调用就保持可见， 免得把一个可能还在跑重复续接的会话藏起来。HANDOFF.md放最后写， 所以任何被放弃的尝试都不会在项目里留下文件。真正的交接失败（不是延后）保持可见，仍以handoff failed · …留在列表里以便排查。这套守卫是尽力而为的：最后一次检查之后还剩一个renameRPC 的窗口，无法再收窄；下一次尝试照常。判定读的是会话日志里更晚的turn/start，因为turn/end提交时 driver 的 phase 仍是running，读agent.status无法区分“这一轮刚结束”和“已经在跑下一轮”；落在某次尝试进行中的turn/end不会被丢掉，而是记下来、等这次尝试结束后按它补评（否则一次被吞掉的、真正空闲的turn/end可能让该会话再也不交接；若这次尝试以失败告终，则补评先受 5 分钟失败退避约束，不会立刻重试）。手动/handoff now不受这条轮次落定限制（它本身就在一轮里执行），但仍受上面的子代理守卫约束（有在跑的 就拒绝并点名）。自动交接因“没有更早内容可摘要” 而跳过时写一条限频的服务端日志（约 10 分钟一次），并在/handoff status的回执里报告从何时起被跳过、以及原因（同一个会话一旦重新变得可摘要，这条报告随即清除）——dsh 没有 host 侧的通知服务，UI 里不会主动弹提示，/handoff status是唯一可见面；要看当时的上下文占用也用它，要强制移交用/handoff now（手动路径的回执是可见的）。 没有可摘要的更早消息时（空会话，或整段对话都落在handoffBudgetRecentTokens原文窗口内）直接拒绝，手动/handoff now回一条错误说明而不是伪造摘要，并提示用/handoff budget recent 0摘要整段对话。交接跟随对话语言（handoffLang，含摘要指令、六个段落标题与首条消息）； 重放中上一轮交接提示会被替换成一行标记，不再把陈旧的交接提示原样带进孙会话。 带入的"最近对话原文"是把消息渲染成文本（## user/## assistant/## tool result，助手只调工具时是[tool: 名称]）——dsh 的交接只能把文本投给子会话、 不能重放结构化消息，所以这里是渲染而不是 pi 的真消息重放； 工具输出会一并带入（每条截断 1500 字符，textOf读tool-result块），同一份渲染也是整理/沉淀的输入。新会话沿用父会话的 agent preset、权限预设与当前模型/思考级别（sessionController.create既不接受 model 也不接受权限：创建后先按permissionPresets.current(父会话)取预设并经服务的set(子会话, 预设)写入沙箱模式与审批策略，再按父会话最后一次请求的路由调selectModel， 最后才投递首条消息——否则用户切到的"完全访问"到了子会话会退回"每个敏感操作都要问"；父会话是custom组合、子会话尚未进入内存、或运行时没有这些服务时按原样创建，失败只记警告不影响交接）， workspace 按 cwd 精确匹配接入（匹配不到就只用 cwd 创建），首条消息里的存档指针是绝对路径、HANDOFF.md里写仓库相对路径；浏览器端在标题出现时自动切换， 但当前会话输入框非空或正在提交时不抢。新会话被标记后，被替换的旧会话会被「退休」：先停掉它 仍在运行的工作，再归档掉。dsh 的交接是分叉（子会话是另一个会话），旧会话不结束就仍算「活动」， 而工作区列表按活动度分组，于是它排在自己延续的上面——这正是用户报的「handoff 的新会话落在旧会话 下面」。宿主没有「结束会话」的 RPC，archiveSession是唯一等价物，且必须带stopActivity：不带该 标志时宿主对仍有运行中工作的会话直接拒绝归档；归档只隐藏，日志、归档产物与工作区位置都保留， 客户端可还原。带stopActivity时宿主还会经 subagent 家族的workspace/session-stop，把该会话仍在 运行的子代理后代（含 teammate）逐个cancel——所以被替换会话里在跑的子代理不会变成孤儿，反过来 也意味着交接会中断它们手上的活。时机是重点：自动档触发时该会话已经落定，立即退休；手动档/handoff now跑在 自己那一轮里，此时归档会停掉正在渲染回执的那一轮，所以排到该会话的turn/end再退休（一次性，session/disposed丢掉标记）。pi 侧不需要对应处理：它的 handoff 走ctx.newSession()，是替换 而非分叉，旧会话随之结束。阈值 0.4 早于 dsh 内置压缩的 0.8，两者可共存。 - ②③④ 只作用于顶层会话（
origin !== "subagent"），① 对子会话同样留档；各阶段的异常都写.agents/memory/errors.log，不打断会话（④ 的“交接延后”按设计不算异常，只记服务端日志）。
更新日志
见 CHANGELOG.md。
开发
pnpm typecheck # host + 客户端 tsc --noEmit
pnpm build # host → lib/*.js，客户端 bundle → lib/client.js
pnpm test # 先编译再跑 node:test 回归（test/）
lib/ 纳入版本控制：main / exports / files 都指向它，所以 clone 下来不构建也能装（商店读的
固定 Commit 里必须有运行时产物）。改 src/ 或 client/ 后要 pnpm build 并提交重建的产物；
pnpm build 是确定性的——构建完 git diff --exit-code -- lib 必须为空。
test/card-render.test.mjs 是唯一真正渲染卡片的测试（其余客户端测试都是对源码的字符串扫描，
能证明某个字符串不在，不能证明控件进了 DOM）：它把 client/settings-card.tsx 连同平台的
SettingsForm / SettingsValueField / Switch / Pill 用 esbuild 打成一个包，经 react-dom/server
渲染，再按字段表核对——21 行各出现一次、5 个布尔是开关、3 个枚举各自每选项一个胶囊、整页只有平台的
一个保存控件，并且保存是一次带 revision fence 的原子写入、被拒后草稿保留且不会卡在「保存中」。
为此 react / react-dom / clsx / zustand / immer 是 devDependencies（浏览器 bundle 把它们
全部外部化，只有这个测试用）。其中后三个本不是本仓库的依赖：@deepseek-ai/dsh-client-ui-primitives
与 @deepseek-ai/dsh-client-store 的 lib/index.js 会 import 它们，但两个包的 manifest 只声明了 cordis
peer——Shell 从自己的 workspace 供，所以一直没人发现；自己打包的测试必须自己供上。同一份
lib/index.js 还会 import shiki / katex / micromark / simple-icons 等（markdown 与代码块那一面，
本卡片不渲染），测试对这些注入惰性 passthrough，并在 t.diagnostic 里列出实际被替换的模块。
host 侧对 @deepseek-ai/* 仅 type-only import（唯一的运行时值依赖是 schemastery，已声明在
peerDependencies）；客户端 bundle 的 esbuild 外部化列了 react / react/jsx-runtime /
@deepseek-ai/dsh-client-store / @deepseek-ai/dsh-client-ui-primitives（四者都由 web shell 的平台种子
提供），而实际 require 出去的只有 react/jsx-runtime 与 @deepseek-ai/dsh-client-ui-primitives——store
目前只作类型使用，留在列表里是显式的防回归声明（内联平台包会把它自带的 CSS modules 一起卷进单文件
bundle，那样加载不了）。
宿主半边按 dsh 0.1.7-rc.2 的 API 写，peerDependencies 的下限即该版本。rc.2 的这几处都是
破坏性变更、本包不再兼容 0.1.5–0.1.7-alpha 线：设置表单来自模块导出的 Config（installSection
已删）、agent/session-start 改为 agent/created、工具结果是独立的 role: 'tool' 消息（tool-result
内容块已删）、消息 source.kind 的 catch-all plugin 已删。
客户端改动只有 pnpm build（或 pnpm build:client）才会进 lib/client.js：pnpm test 只编译
host，漏跑会让服务端继续分发旧 bundle；重建后运行中的 dsh web 经 client HMR 自动换版（boot graph
的 rev 变化），刷新页面即可。改 host 侧（src/）要先 pnpm build，再重启承载插件的那个 host
才生效——可能是 dsh web，也可能是桌面端的 dsh-desktop（其 host 监听
127.0.0.1:19387）；只看提交或构建
时间不能判定已生效，要对进程启动时间。
许可证
MIT © 2026 呼啸山庄 (P02-1010751281)，见 LICENSE。
设置卡片按官方设置页（@deepseek-ai/dsh-client-ui-settings-* 各卡片）的写法组装：槽位注册 +
平台表单模型 + 平台控件。早期版本的卡片外壳与 store 探测层曾改编自
dsh-auto-continue（MIT，Copyright (c) 2025
HsiangNianian），这两处在改用平台组件后已删除。
No comments yet. Be the first to write one.