daodishisha28/dsh-sidechat-plugin

DeepSeek Harness SideChat

为 DeepSeek Harness 提供普通、持久化、可恢复的 SideChat 澄清会话。

SideChat 不是临时浮层，也不是 subagent 或 fork。每个 SideChat 都是一个正常的 DSH Session：拥有完整会话页面、原生模型选择器、多轮对话和持久化 transcript；即使卸载插件，历史 Session 仍能作为普通会话读取。

当前版本：0.3.4
已核验 DSH 基线：0.1.2-alpha.1，提交 cd5ef81481

主要能力

- 在任意 Session 中使用 /side 创建独立 SideChat，并自动进入新会话；
- 默认使用最近一条直接 user/assistant 文本作为最小 Seed；
- 支持 tail:1、task、none、tail:2、tail:4、pick:1、pick:many、turn、selection 和 summary Seed；
- Seed 只保存直接文本，不复制 reasoning、工具调用、工具结果或完整父 transcript；
- Seed 内容与来源消息保存为不可变 provenance；
- 可选择“只读模式”或“继承”权限；
- 父 Session 中提供与“对话”“轨迹”并列的“子会话”视图；
- SideChat 使用完整 DSH Session 页面，可恢复并继续多轮对话；
- 支持模型生成、预览、编辑和提交结构化 Fold；
- 支持 revision、增量 Fold、对比和软撤回；
- 支持把指定 assistant 回复无回复引用到父会话；
- 支持 archive、restore、abandon 和 orphaned 状态；
- /sideusage 展示可验证的 token 用量，不用估算值冒充精确值；
- 创建、Fold、Cite 和生命周期操作均通过 slash 命令完成，Header 只保留身份与父会话导航。

权限模式

创建 SideChat 时，在 Seed 策略之后选择权限模式。

| 模式 | 行为 |
|---|---|
| 只读模式（推荐） | 候选能力为 read、glob、grep、Shell、Web、Plan、用户提问、子代理和 workflow；最终工具是候选集合与父会话实际可见工具的交集。沙箱固定为 read-only，审批固定为 never。 |
| 继承 | 继承父会话创建时的 Agent preset、有效 sandbox、approval 和可见工具上限。 |

所有权限都由 Host 重新计算。浏览器提交的模式、Session ID 或工具名称不能直接获得授权。权限快照保存在 storageDomain，DSH 重启后会重新应用限制。

环境要求

| 依赖 | 版本 |
|---|---|
| DeepSeek Harness | 0.1.2-alpha.1 |
| Node.js | ^22.19.0 或 >=24.0.0 |
| pnpm | >=10.0.0  --force
pnpm dsh --profile web --dump-config
pnpm dsh --profile web

更新插件源码后重新执行：
powershell
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add . --force

然后重启 DSH。浏览器仍显示旧 Client bundle 时使用 Ctrl+F5 强制刷新。

卸载：
powershell
dsh plugin --profile web remove dsh-sidechat-plugin

卸载只移除插件 UI、Host service 和 SideChat 关系解释能力，不会删除已经创建的普通 Session 或 transcript。

快速使用

1. 在父 Session 的输入框中输入 /side。
2. 用方向键选择 Seed，按 Enter 确认。
3. 选择“只读模式”或“继承”，按 Enter 确认。
4. 输入澄清问题：Enter 创建，Shift+Enter 换行，Esc 取消。
5. 在完整 SideChat 页面继续多轮对话。
6. 使用 /sidefold 生成 Fold；预览中 Enter 提交、Shift+Enter 换行、Esc 取消。
7. Fold 提交成功后自动返回父 Session。

插件内包含确认和取消的对话框遵循同一套键盘约定：Enter 确认、Esc 取消；文本框使用 Shift+Enter 换行。

Slash 命令

| 命令 | 作用 |
|---|---|
| /side、/btw | 创建普通持久化 SideChat；默认 Seed 为 tail:1 |
| /sidechats | 列出当前工作区 SideChat，当前 Session 的直接子会话优先 |
| /sideresume | 打开已有 SideChat 并继续原 transcript |
| /sideback | 从 SideChat 返回直接父 Session |
| /sidefold | 生成完整或增量 Fold，预览编辑后提交到父会话 |
| /sidecite | 选择 assistant 回复并引用到父会话 |
| /sideusage | 查看 SideChat、父会话增量和额外 Seed 调用的 token 用量 |
| /sidecompare | 比较两个 committed Fold revision |
| /sidewithdraw | 软撤回指定 revision，保留审计历史 |
| /sidearchive | 归档当前 SideChat |
| /siderestore | 恢复 archived SideChat |
| /sideabandon | 放弃当前 SideChat，但保留 Session 和 transcript |
| /sidecites | 查看 Cite 记录并打开目标 Session |
| /sidecite-cross | 显式跨父 Cite；Host 默认关闭 |

Seed 策略

| Seed | 说明 |
|---|---|
| tail:1 | 默认；最后一条直接 user 或最终 assistant 文本 |
| task | 使用父会话最近模型 route 做一次无工具调用，生成不超过 500 token 的任务式最小上下文 |
| none | 不带父上下文，只发送澄清问题 |
| tail:2 / tail:4 | 最近两条或四条直接文本 |
| pick:1 / pick:many | 选择一条或多条直接文本 |
| turn | 冻结指定 turn 的直接文本 |
| selection | 冻结一条消息中的指定字符区间 |
| summary | 对用户明确选择的消息做一次独立 bounded summary |

task 和 summary 会产生一次额外模型调用。task 不写入、不唤醒、不推进父 Session；失败时不会遗留半创建的 SideChat。

架构与安全

- SideChat 是普通 Session，不使用 origin: subagent、continuable lifecycle、settlement 或 fork；
- A/B 关系、Seed provenance、状态、权限快照、Fold revision 和幂等状态只保存在 storageDomain；
- Session log 不写入 sidechat/* 自定义事件；
- 持久化 SideChat 内容只使用 DSH 已知 user/message 和正常 assistant/message；
- Fold/Cite 通过 Agent.runMaintenance() 等待父会话真正 idle 后 no-reply append；
- Fold/Cite 投递本身不创建父 turn、不 followup、不 steer；Fold 追加后若将达到配置的上下文占用阈值，会先退出 maintenance、显式压缩父会话旧历史、重新测量，再完整追加 Fold。该压缩通常会产生一次独立的压缩模型调用；Cite/撤回不走此压力保护；
- Host 重新验证 parent、child、workspace、lifecycle identity、message ID 和 revision；
- Seed、Recall、Cite 与 Fold 内容始终按不可信背景处理；
- orphaned SideChat 可以读取，但不能再向不存在的原父会话 Fold 或 Cite。

Fold/Cite 使用 domain pending → 安全 append/flush → domain committed 三阶段事务。消息带不可变 marker；如果 Host 在 append 后、状态提交前崩溃，恢复逻辑只补状态，不重复写入消息。

配置

默认 bundle 配置位于 cordis.patch.yml：

| 配置 | 默认值 | 说明 |
|---|---:|---|
| foldMaxTokens | 500 | Fold 最大输出预算 |
| foldAppendThresholdRatio | 0.8 | Fold 完整追加后的父上下文占用阈值；达到阈值时先压缩旧历史并重测，仍超阈值则不追加 |
| citeMaxTokens | 500 | Cite 最大文本预算 |
| readMaxMessages | 5 | 一次精确 Recall 最大消息数 |
| readMaxChars | 20000 | 一次精确 Recall 最大字符数 |
| seedSummaryMaxTokens | 500 | summary Seed 输出预算 |
| seedTaskMaxTokens | 500 | task Seed 输出预算 |
| allowCrossParentCite | false | 是否允许同工作区显式跨父 Cite |
| preset | sidechat-clarifier | 只读 SideChat preset |

打包发布

生成 npm tarball：
powershell
pnpm pack

prepack 会重新构建并执行 manifest smoke。tarball 只包含运行所需 bundle、声明、preset、配置、文档和许可证，不包含 src/、测试、node_modules/、本地 pnpm store 或历史 tarball。

可选的 DSH 源码契约复核

普通构建不需要 DSH 源码。如果维护者恰好有 DSH checkout，可额外验证实际源码锚点：
powershell
$env:DSH_SOURCE_DIR = ''
pnpm verify:contracts

该变量仅用于维护期核验，不是安装或构建依赖。

已知限制

1. 当前只对 DSH 0.1.2-alpha.1 做过完整核验；升级 DSH 前应重新运行源码契约复核和真实 Web smoke。
2. DSH 的公开 SessionController.selectModel() 会保存全局默认，创建 UI 因此固定继承父会话最近模型；进入 SideChat 后仍可使用原生模型选择器切换。
3. DSH header.lineage 是 single slot，SideChat breadcrumb 使用不冲突的 Header actions slot。
4. 外部 bundle 无法进入当前 DSH 的 generated Remote assembly，插件使用公开、认证的 connection.rpc.handle('/sidechat') 通道。
5. archive 和 abandon 是插件组织状态；SideChat 仍保留在普通 Session 列表中。
6. /sideusage 只展示 provider 已持久化且能组成完整 turn 的 usage；证据不完整时显示“不可得/不完整”。
7. “继承”通过父 preset ID 创建，并以父会话当时实际可见工具为 Host allowlist；preset 恰在创建窗口热更新时，子会话可能装载同 ID 的新 generation，但不会突破父工具上限。

项目结构

src/                    Host、Client 与共享业务源码
presets/                sidechat-clarifier Agent preset
types/dsh-compat.d.ts   独立构建用的 DSH 公共契约声明
tests/                  Unit、Host 与 Client 测试
scripts/                构建、契约、可移植性与 manifest 检查
docs/                   API Spike、设计偏差与人工验收清单
cordis.patch.yml        DSH bundle composition

文档

- M0 API 核验与设计偏差
- M2 API 核验与设计偏差
- 真实环境人工验收清单
- 产品需求与技术设计

License

MIT