💬 dsh-plugin-consult

去问已经知道答案的 Session；默认借用上下文，不改写原对话。

🧠 另一个活跃 Session 已经研究过你即将接手的子系统？
🧭 想得到聚焦答案，又不想合并两段对话或重复调研？
🧾 希望问题、已知事实、分工与回复路径都能被检查？

✨ dsh-plugin-consult 让活跃 Session 变成你的同事。

只问一个同事，复用它已经获得的上下文，并让答案通过当前 Agent 的正常 DSH 回合返回。Fork 默认保护源对话；Align 则是一次明确的“写回”选择。

问题 + 已知事实 + 分配任务 → 默认 fork / 按意图 align → 回复 + 共享分工板

为什么需要咨询 · 功能 · 安装 · 快速开始 · 安全边界 · 技术细节

English · 简体中文

真实 DSH fork 咨询返回三条兼容性审查结论

_{截图来自 DSH Web 中的真实双 Session 验收流程。}

🎯 为什么需要咨询

长时间运行的 Coding 工作会形成局部专家：一个 Session 已经理解 API 契约，另一个掌握迁移方案，第三个正在追踪失败测试。如果每次都把历史复制进新 prompt，不仅浪费上下文，也容易让事实逐渐漂移。dsh-plugin-consult 让当前 Agent 直接去问一个活跃的同事 Session，复用对方已经拥有的上下文。

模式	目标	源 Session	适合场景
Fork，`align=false`	可复用工作副本 A′	咨询不会写入	单向审查、事实查询、专家建议
Fresh fork，`fresh=true`	新建干净副本 A″	咨询不会写入	不沿用旧咨询通道历史的独立回答
Align，`align=true`	原 Agent A	咨询写入 A 的日志	两边都必须记住的显式对齐

同一对 Session 可以同时存在 fork 与 align 通道。模式属于通道身份的一部分，不会在背后悄悄切换。

✨ 功能

🧠 去问已有上下文，而不是再启动一个空白 Agent

系统提示会以标题和 ID 列出一组有界的活跃同事 Session。任务发生重叠时，发起方可以调用 ask_peer，而不是自己再搜索一遍。

每次咨询都可以携带：

需要回答的精确 question；
对方不应重复调研的 known 已知事实；
带明确归属的 tasks；
默认开启的 welcome_questions，允许对方把缺失上下文反问回来。

🌿 默认保护源对话

默认通道会与工作副本 A′ 对话。再次咨询会复用同一副本，保留咨询连续性，但不改写原 Session A。fresh=true 会从 A 已完成的历史重新 fork 一个干净 A″；只有 align=true 才明确选择直接与 A 对话。

下面的真实验收流程让一个 API 契约 Session 审查 v2 兼容性。ask_peer 记录了 mode: fork、共享分工板，以及有界等待 30 秒后的 pending；完整回复随后通过正常回合异步到达。

展开后的 ask_peer 工具结果，显示 fork 模式、共享分工板和异步 pending 状态

📋 传递共享分工板，而不是含糊交接

每条通道都有包含 goal、known、tasks 和 questions 的分工板。两边都能用 consult_board 读取或更新；只有同事侧可以用 consult_ask 向发起方追问。分工板会随咨询结果一起进入模型上下文和 Session log，人与 Agent 看到的是同一份证据。

⚡ 短暂等待，然后继续工作

ask_peer 只等待调用方给出的 wait_ms，并且只有在目标原本空闲、咨询回合已经开始时才等待。对方忙碌时，请求会排队，不会打断它正在进行的回合；回复超过等待时间后，会通过以下两种方式之一送达：

发起方的下一次工具结果，经 tools/post-execute 附加；或
发起方已经空闲时，通过一个 follow-up 回合送达。

无需忙等轮询。consult_progress 可以读取有界预览，完整回复只投递一次。

🧹 查看、停止、提升与清理

Agent 工具和斜杠命令可以查看通道状态与近期进度、取消咨询、把 fork 提升为普通会话，并清理工作副本。工作副本会从工作区会话列表中归档，并可在空闲超时后释放；其日志仍可继续恢复。

⚡ 安装

0.1 版本是一个源码 overlay，还不是已发布的独立 bundle。把它克隆到 DeepSeek Harness 源码仓附近，复制示例 patch，再把占位符替换为 src/index.ts 的绝对路径：

git clone https://github.com/biuboomc/dsh-plugin-consult.git
cd dsh-plugin-consult
cp cordis.yml cordis.local.yml

# 编辑 cordis.local.yml：
# name: '/absolute/path/to/dsh-plugin-consult/src/index.ts'

cd /path/to/deepseek-harness
pnpm dsh --profile web \
  --patch /absolute/path/to/dsh-plugin-consult/cordis.local.yml

Host 启动后打开设置 → 插件 → 插件列表；consult 行应显示已启用且已挂载。Agent 工具会提供给符合条件的活跃 Agent；这是纯 Host 插件，不会新增一个独立 Web Dashboard。

当前仓库没有编译后的 package entry、完整依赖声明、Release tag 或软件许可证。本文不会虚构尚未验证的一行式 bundle 安装。

🚀 快速开始

1. 准备一个专家 Session

让一个 Session 调研或负责边界明确的领域，并保持活跃；冷 Session 需要先 resume，之后才能被咨询。

2. 从另一个 Session 发问

去问“API 契约负责人”这个 Session，审查 v2 error schema。
已知：公开客户端依赖 code、message 和 requestId。
只让它识别 breaking changes，并给出最小兼容迁移方案。
这是单向咨询，不要写入原 Session；最多等待 30 秒。

发起方应从同事 roster 识别目标，并调用 ask_peer，携带 align: false、known、tasks 和 wait_ms: 30000。

3. 只有两边都必须记住时才对齐

去跟评测 Session 对齐最终验收口径，也写进它自己的 Session。
欢迎它反问缺失信息，并等待 30 秒。

这时应使用 align: true。Align 不能和 fresh=true 同时使用。

🧰 适合咨询的任务

同事专长	聚焦问题	价值
API 契约负责人	找出 schema breaking changes 与迁移边界	复用该 Session 已有的兼容性决策
安全审查者	挑战一个威胁模型并列出缺失控制	让主实现回合保持聚焦
测试调查者	解释一个失败簇及最强复现证据	避免并行重复诊断
迁移专家	检查回滚顺序、不变量和可观测性	把运维上下文带回当前计划
文档负责人	核对公开术语与兼容承诺	防止实现与文档漂移

好的咨询只问一个同事一个有界问题。如果确实需要两个同事，应给他们不同任务，而不是广播同一道题。

🛡️ Session 隔离不是工作区隔离

Fork 模式保护的是源 Session log，它不是文件系统沙箱。

工作副本会继承源 Session 的 cwd 和 Agent 选项。
标准 DSH approval service 存在时，Fork 的 approval policy 会设为 never，并禁止发起新的同事咨询；但不需要审批的工具仍可能存在。
因此，只要挂载的 preset 和工具允许，fork 仍可能读取或修改共享工作区。需要文件隔离时，应配合只读 prompt、只读 preset 或独立 worktree。
align=true 会写入原 Session，且不会限制原 Agent 的工具或审批。
Align 通道上的 consult_stop 会取消原 Agent 当前回合。
promote_consult 只适用于 fork 通道。
队列和未投递回复存在进程内存中，不是持久后台任务系统。

插件默认防止意外改写对话，但不能替代 DSH 的 sandbox、approval、worktree 或策略控制。

🔧 技术细节

🧭 工具与命令

接口	作用
`list_peers`	按近期活动列出活跃同事，并显示既有通道身份与模式。
`ask_peer`	携带问题、分工板与有界等待，打开或继续 fork/align 通道。
`consult_board`	读取或更新共享目标、事实、任务和问题。
`consult_ask`	让同事向发起方追问；普通发起方不能使用。
`consult_status`	查看通道状态、排队深度与投递状态。
`consult_progress`	读取同事近期可见输出的有界预览。
`consult_stop`	取消当前咨询回合，并只返回一次可见的半成品。
`promote_consult`	把工作 fork 提升成普通独立 Session。

斜杠命令：/consult-status、/consult-progress <id>、/consult-stop <id>、/consult-promote <id> 和 /consult-cleanup。

⏳ 异步状态

`ask_peer` 结果	含义
`ready`	空闲目标在 `wait_ms` 内完成，回复当场返回。
`pending`	咨询回合已经开始，但没有在有界等待内完成；回复进入投递队列。
`queued`	同事原本正忙；问题排队，不打断它当前回合。
`stopped`	等待期间咨询被取消。

同一个 Agent step 里只有第一次咨询等待可以阻塞；目标忙碌或后续咨询会立即返回。结果会带上通道 mode、fork 状态（new、continued、fresh 或 source）以及当前分工板。

🏗️ Cordis 架构

flowchart LR
  Roster["系统提示中的同事 roster"] --> B["发起方 Agent B"]
  B --> Entry["Agent 工具 / 斜杠命令"]
  Entry --> Service["Consult service"]
  Service --> Channels["通道索引 + 队列"]
  Channels --> Fork["工作副本 A′（默认）"]
  Channels --> Align["原 Agent A（显式 align）"]
  Logs["Session log 标记：result + board"] <--> Service
  Fork --> Delivery["回复投递"]
  Align --> Delivery
  Delivery --> Hooks["tools/post-execute 或空闲 follow-up"]
  Hooks --> B
  Lifecycle["Cordis 生命周期 + 工作区注册表"] --> Fork

通道索引只是运行时投影。进入工具时，插件会扫描活跃 Session log 中的 [consult-result] 与 [consult-board] 标记，重新连接已知 working Session ID，并在需要时 resume 已归档 fork。插件卸载会归档和释放自己持有的工作副本，绝不会归档或释放 align 的原目标。

⚙️ 配置

选项	默认值	含义
`maxRounds`	`8`	每条通道最多咨询轮数，包含排队任务。
`maxWaitMs`	`180000`	单次同步等待的上限。
`maxAskBack`	`4`	同事向发起方反问的上限。
`archiveWorkingForks`	`true`	从普通工作区会话列表隐藏插件工作副本。
`forkIdleMs`	`1800000`	工作副本空闲 30 分钟后释放；`0` 表示保持活跃。

🚧 当前限制

roster 只显示活跃 Agent；冷 Session 需要先 resume。
Fork 需要源 Session 已经完成至少一轮；Align 可以直接面向活跃 Agent。
如果发起方整轮结束且不再运行工具，未投递回复会等到下一次活动。
队列和投递状态不会跨 Host 重启保存，但日志标记可以重建通道索引。
当前没有自定义 Web UI、worktree 隔离、跨 Host 协调或持久后台任务队列。
被提升的 fork 是普通 Session，不会自动归档。

🧪 开发与验证

本次 README 更新在 DSH Web 中完成了真实双 Session 验收：

Session A 记录 API 兼容性契约。
Session B 以默认 fork 模式发起咨询，并等待 30 秒。
ask_peer 返回 pending；共享分工板异步完成。
回复进入 B，形成上图所示三点审查结论。
再次打开 A 时，它仍只有原始一轮，确认 fork 没有写入源日志。

本分支的兼容性修复还为当前 Harness schema 校验器显式标注了所有嵌套 board 对象。

当前仓库没有声明软件许可证。仓库公开不等于获得复用或再分发权；维护者应在发布可分发包之前选择并加入许可证。

biuboomc/dsh-plugin-consult