dsh-collab(中文)
English · 中文
非 DeepSeek 官方项目:社区插件,与 DeepSeek 官方无隶属、无背书关系。DSH 商标归其所有者。
把多个 AI 会话变成一个小而可审计的团队:工单、交接、文件记忆、通知。
要解决的问题
在一个工作区里同时跑多个 AI 会话,直到:
- 换会话就失忆——压缩或切换后,它忘了自己在干什么;
- 各写各的——互相覆盖、格式漂移,没人知道哪份是真源;
- 过程不可见——“派了”和“做完了”之间没有进度、接单、证据,也不知道谁卡住;
- 静默停摆——一个会话在等另一个,没人被叫醒。
dsh-collab 把靠聊天的协作变成显式、落文件、可追踪的流程。
三个支柱
| 支柱 | 含义 |
|---|---|
| 记忆在文件里 | 每个场景有身份卡、状态摘要、按日记忆与索引;新会话几秒接上。 |
| 写入走工具 | AI 只调 wb_read / wb_write;每次写入校验(来源 refs、体量、只写自己目录),派生文件自动刷新。 |
| 协作靠工单 | 派单 → 接力 → 回执 → 验收;一单到底,记录每棒耗时与证据。 |
功能
1. 协作协议 v2
- 一任务一单:复合需求(实现+测试+文档)建一张单,用
flow接力;同任务哈希未关闭前不能重复建单。 - 按日单号 PDNNN:
collab/YYYY-MM-DD/PD001-<assignee>.md;跨日引用写YYYY-MM-DD/PDNNN。历史dhNNN只读兼容。 - 按 flow 接力:每棒先 ack(
progress一行)→ 干活 →handoff下一棒(自动唤醒);接管自动,不用额外调用。 - 防跳步:非最后一棒不能
close;最后一棒负责交回主负责人。 - 回执统一(PRT-020):完成 =
submit(带 refs)+ 按 flowhandoff;只 ack/comment/progress 不算回执。 - 主负责人验收:
verify/reject带证据;close时回执 dispatcher、同步 summary 投影。 - 证据纪律:
submit / handoff / verify / close必须带 refs;校验存在性、可读性、..穿越与大小(≤ 20 MB)。 - 依赖 DAG:
depends_on前置单;未满足时单进waiting_on,维护器到点唤醒。 - 超时维护:stale 检测、心跳提醒、
maxReminders上限;超限升级给 dispatcher(只升一次)。 - 异步唤醒:wake 失败自动进 outbox,指数退避重投;宿主会话 API 不可用时明确降级。
- 完成索引:
collab/done-index.md按日期列出完成/取消单。
2. 记忆与身份
- 唯一真源:
_meta/registry.jsonv2(场景/会话/分组);card.json、summary.md、memory/INDEX.md、scene-index.md都是派生,不手改。 - 每个场景的文件:
agents/<id>/card.json(身份/职责/边界/技能)、summary.md(在做/下一步/卡点/指针)、memory/<日期>/*.md(带来源的结论)。 - 自动投影:
wb_write(note)写按日结论,重算 summary 与 INDEX;单文件约 2KB 上限,超出轮转到.detail*.md。 - 交接:重绑会话时生成接力摘要(card + summary + 最近记忆 + 在途单)并给新会话发 seed;旧会话改名标记已交接。
- 入场 seed:新建/选已有/交接都发短 seed:读卡与摘要、看板、无单即回、有实质工作才写回。
3. 内置规则 + 个性化
- 内置规则(只读、随插件):24 条 INV/BND/PRT(来源、真源、边界、协作协议),版本 v2 冻结,不随使用变化。
- 全局规则(可编辑):本机/个人偏好、项目约定写
shared/env/global-rules.md;保存时自动生成注入片段。 - 注入:插件把「内置规则 + 全局规则 + 场景指针」写入
<dataRoot>/AGENTS.md托管段;config.inject=off可关闭。 - 冲突时以内置规则为准;内置规则不因升级被覆盖。
4. 会话生命周期
- 状态机:
pending(未绑定会话)/active(已绑定)/archived(归档);删除进回收站。 - 操作:交接 / 解绑 / 归档 / 恢复 / 回收 / 导出快照;分组(一个场景只在一个组)。
- 自动建技能:创建场景时未选技能会自动生成基础
SKILL.md;设置页可编辑技能。
5. 通知与可观测
- TZNNN 通知:按日编号、只发不回执(无 ack),状态
sent/expired/cancelled;小程序端用notify-feed读未读。 - 事件流:
events/events.jsonl、dispatch.jsonl、violations.jsonl;支持轮转归档(/ops/events/rotate)。 - 自动索引:监听
_meta/registry.json,防抖重算scene-index.md并重新注入 AGENTS。 - 自检:
/doctor与/ops/selfcheck校验数据根、配置、注册表、注入、技能、运行版本 vs 磁盘——不依赖任何外壳脚本。
6. 工具
wb_read(只读):check / scene / order / board / notify / search
(search 支持 scope=memory|playbooks|blackboard|collab、query、since、limit)
wb_write(写入):
| action | 用途 |
|---|---|
note |
写结论(refs 必填、只写自己场景) |
progress |
进度/心跳行(record 别名) |
comment |
单内说明(任何角色) |
notify |
发 TZ 通知(需 to + text,只发不回执) |
task |
建单(五件套 + task_hash/depends_on/write_scopes/collaborators/flow) |
submit |
提交(refs 证据) |
verify / reject |
验收通过 / 退回(仅 dispatcher,refs) |
handoff |
单内接力(next/back,to 在 flow 或 dispatcher) |
close / cancel / reopen |
关单(done/blocked/cancelled)/ 取消 / 恢复 blocked |
7. 设置页(从简)
会话协作设置页只保留:全局规范、场景/分组、技能、其他设置(启动预检、引擎端口、运维、行为预算、高级数据清理)。 超时催办、自动索引等内部策略不再暴露编辑入口(由插件自动维护)。
8. 学习(零 AI,可关闭)
- 只采集异常信号(拒绝、stale、违规、中断、显式反馈),按 rule_id 分类;
- 周报
_meta/learn/weekly.md;候选需样本 ≥3 且占比 ≥30%、7 天观察期,只改插件默认值,每周 ≤3 项、带版本可回退; - 不碰内置规则与用户全局规则。
9. 可靠性与安全
- 写前 hash 守卫(并发冲突明确提示);迁移幂等、可回滚;
manifest.jsonSHA-256 校验; - refs 仅接受可读路径/链接,拒绝
..穿越与超大文件,违规写violations.jsonl; - 回收站二次确认;数据根可配置,多个 DSH 实例共用插件代码但数据隔离。
10. 开发与可移植
- 不需要外壳:独立 DSH profile 配
config.dataRoot即可用; - HTTP API:看板数据、会话、工单、通知、运维、自检、i18n、配置都有接口;
- 测试:6 套(run 78 / load 44 / static 15 / bootstrap 8 / config-dataroot 5 / auto-index 6)。
快速开始
方式一:npm 安装(推荐)
npm i @sessionhive/dsh-collab
方式二:离线包
tar -xzf @sessionhive/dsh-collab-0.2.0.tgz --strip-components=1 \
-C <DSH_HOME>/profiles/<profile>/node_modules/@sessionhive/dsh-collab
在 profile 的 cordis.patch.yml 里挂载:
- insert:
- id: workbench-core
name: '@sessionhive/dsh-collab'
config:
dataRoot: '/你的/.dsh/绝对路径' # 协作数据落在这里
重启 DSH 引擎(插件在启动时加载),然后打开 设置 → 会话协作:
- 新建协作场景(id 小写、选会话、分组可选);
- 全局规范里写你的个性化规则;
- 其他设置 → 启动预检应全绿。
配置(_meta/config.json)
| 键 | 默认 | 说明 |
|---|---|---|
dataRoot(cordis config) |
自动 | 协作数据根(与 harness 安装目录无关) |
inject |
auto |
是否注入内置规则+全局规则到 AGENTS.md(auto/on/off) |
seedOnCreate |
true |
新建会话时是否发 seed |
enginePort |
自动 | 手动覆盖本地引擎端口 |
defaultCwd |
— | 新建会话默认工作区 |
handover.warnContextTokens / contextThresholdTokens |
60000 / 120000 | 上下文提醒 / 交接阈值(依赖宿主提供 usage 时生效) |
protocol.staleMinutes |
3 | 投递后多久没动作算 stale |
protocol.reminderMinutes |
5 | 未提交提醒间隔 |
protocol.maxReminders |
3 | 催办上限(超限升级 dispatcher) |
protocol.expireHours |
24 | 通知过期小时 |
protocol.notifyWake |
true |
超时是否唤醒 |
budget.wakePerScenePerDay |
3 | 唤醒统计(闸已取消,仅计数) |
learn.autoApply |
true |
允许受控自动调优 |
theme / lang |
auto / zh |
主题 / UI 语言 |
数据目录
<dataRoot>/
├─ agents/<场景>/ card.json、summary.md、memory/<日期>/、memory/INDEX.md
├─ collab/<日期>/ PDNNN-*.md(.done.md / .cancelled.md)、done-index.md
├─ notify/<日期>/ TZNNN-*.md(sent/expired/cancelled)
├─ blackboard/ 黑板
├─ shared/env/ global-rules.md(+ .inject.md)
├─ events/ events.jsonl、dispatch.jsonl、violations.jsonl、counter.json
├─ _meta/ config.json、registry.json、scene-index.md、plugin-manifest.json、learn/
├─ skills/<场景>/ SKILL.md
├─ trash/ 回收站
└─ backups/ 迁移/配置备份
日常用法(示例)
# 派单给某个场景(默认不唤醒;wake:true 才唤醒)
wb_write { action: "task", to: "backend-dev", task: "实现 X 接口", loc: "lib/api/*", accept: "curl 200 + 测试通过", wake: true }
# 接单先 ack(一行进度)
wb_write { action: "progress", orderId: "PD001", line: "ack,开始处理" }
# 完成:提交证据 + 按 flow 转交
wb_write { action: "submit", orderId: "PD001", refs: [".../证据.md"] }
wb_write { action: "handoff", orderId: "PD001", to: "frontend-dev" }
# 主负责人验收关单
wb_write { action: "close", orderId: "PD001", status: "done", refs: [".../验收记录.md"] }
# 写记忆(refs 必填)
wb_write { action: "note", scene: "backend-dev", text: "结论:...", refs: [".../证据路径"] }
常见问题
- 设置页看不到催办/索引:它们已收为内部策略,自动维护,不再开放编辑。
- 改完没生效:插件代码在引擎启动时加载——升级后需重启 DSH。
/board404:旧内置看板页已移除;派单/通知数据走/board-data、/notify-feed(Workbench 派单页已接入)。- 上下文压力显示未知:需宿主提供会话 usage 数据;没有时按 unknown 处理,不影响协作。
- 关单被拒:证据不可达:修 refs(建议绝对路径)后重试。
- 会话被 host 归档:重新绑定/交接;归档是冻结不是删除。
- 外部 DSH 没有外壳:插件自检、工具、索引都自包含。
明确不做
- 不是 DeepSeek 官方产品;
- 不自动切换会话、不跑后台 AI 循环、不自动改内置规则/用户规则;
- 暂无向量检索、多用户权限模型、新手引导。
路线
- 0.2.0:当前正式基线(身份统一、协议 v2、内置规则、去旧壳)。
- 之后:上下文用量接入(等宿主数据源)、文档/示例完善、1.0 冻结文件格式。
在 DSH 插件市场里发现
仓库自带格式 1 的市场索引 market/index.json。在 DSH 的 插件 → Discover 里添加:
https://cdn.jsdelivr.net/gh/sessionhive/dsh-collab@main/market/index.json
备用 raw:https://raw.githubusercontent.com/sessionhive/dsh-collab/main/market/index.json
贡献
欢迎 issue 与小型 PR:见 CONTRIBUTING.md。
许可
MIT
No comments yet. Be the first to write one.