collab-canvas（话布）
面向 DeepSeek Harness（DSH）的协作画布插件：一块人和 AI 共写的 Markdown 文档面。
它解决什么问题
在聊天窗口里，AI 的长内容会刷屏，改一个段落要重发全文，版本也追不回来。
话布把长内容搬到一块独立画布上：
- 它在 DSH 界面里以 Markdown 文档的形式存在，你可以直接编辑
- AI 通过 9 个
canvas_* 工具读写它，而不是把内容贴进对话
- 双方的每次写入都进撤销历史，随时可以退回去
- 写入带版本检查，AI 不会盲目覆盖你刚改的内容
功能
| 功能 | 说明 |
|---|
| 📝 浏览器内编辑 | 画布在 DSH 页面内渲染与编辑，改动自动保存 |
| 🤖 AI 可读写 | 9 个 canvas_* 工具，模型直接操作画布 |
| ↩️ 撤销历史 | 每次写入入栈，你和 AI 的改动都可回退 |
| 🔒 冲突检测 | canvas_write 支持 baseVersion 强一致检查，不符返回 E_CONFLICT 并给出最新版本 |
| 💾 文件持久化 | 画布落成普通 .md 文件，另有 .canvases.json 记录元信息 |
| 🎯 划词引用 | 选中画布里的文字即弹出划词栏，可把该段引用进对话 |
| 🔗 文档链接/拖放 | 画布内可拖入文档、生成链接 |
| 📁 存储根可配 | canvas_configure 可把画布根目录固定到任意位置（如项目目录） |
| 🎨 跟随主题 | 界面全部使用 var(--dsw-*) 设计 token，换肤自动适配 |
AI 工具
| 工具 | 用途 |
|---|
canvas_list | 列出全部画布与当前活跃画布 |
canvas_create | 新建一个画布 |
canvas_read | 读取画布内容（head 可只取前 N 字符粗看） |
canvas_write | 写入/修改（replace / append / prepend，可选 baseVersion 强一致检查） |
canvas_save | 保存到文件（可指定 filePath） |
canvas_load | 把已有 Markdown 文件加载为画布 |
canvas_locate | 在文档中精确定位一段原文（多处重复时确认是第几处） |
canvas_delete | 删除画布记录 |
canvas_configure | 固定画布存储根目录 |
安装
# 1. 装进 profile（下面两种来源任选其一）
dsh plugin --profile web add collab-canvas # 从 npm 装（推荐）
dsh plugin --profile web add github:godchen520/collab-canvas # 从 GitHub 装（跟随最新提交）
# 2. 把 "collab-canvas" 加进 profile package.json 的 dsh.profile.bundles 数组
# （只加 dependencies 不加 bundles 的话，cordis.patch.yml 不会生效 —— 插件"装了但没启用"）
# 3. 重启
dsh web
两处都要加：dependencies 负责把包装上，dsh.profile.bundles 负责让它的
cordis.patch.yml 进入组合。缺任何一边都会出现"装上了但功能不在"。
npm 安装的好处：不受 npm 对 git 依赖触发的 allowBuilds 构建授权步骤影响，且市场能显示下载量。
数据存放
<存储根>/
├── .canvases.json # 画布元信息（id、标题、关联文件、版本）
├── <标题>.md # 画布正文，普通 Markdown 文件
├── .sessions/ # 会话级清单（运行时状态）
└── attachments/ # 画布里粘贴/拖入的图片
存储根默认取当前会话工作区；用 canvas_configure 可固定到别处，重启后仍生效。
canvas-docs/、uploads/ 属于使用中产生的个人内容，已列入 .gitignore，不进本仓库。
架构
插件由两半组成，分别跑在两个平面：
| 平面 | 文件 | 职责 |
|---|
| Host（DSH Node 进程） | dist/host.js | 注册 9 个工具、HTTP 端点（/api/canvas/*）、画布状态与持久化、编辑器脚本 |
| Client（浏览器页面） | lib/client.js | 注入编辑器 UI、划词栏、右键/长按菜单、与 Host 的 RPC |
dist/host.js 由 src/host/*.js 构建（node tools/build.js）lib/client.js 由 src/client/editor-panel.js 同步而来（客户端为保证运行时不引入打包器，采用直接拼装）
设计细节见 docs/ARCHITECTURE.md 与 docs/DESIGN.md。
开发
npm run build # src/host/*.js → dist/host.js
npm test # 回归测试
npm run verify # 上线前总检（含真跑测试 + 部署一致性 + 文档检查）
npm run deploy # 一键搬运到 DSH 部署目录（--check 只看差异）
部署目录默认由 DSH_HOME 推导：
$DSH_HOME/profiles/web/node_modules/collab-canvas
换机器或换 profile 时，用环境变量覆盖：
CCV_DEPLOY_DIR=/path/to/deployed/collab-canvas npm run deploy
生效方式（两种别混）：
- 改了
src/host/*.js → 搬运后必须完全重启 dsh web（刷新页面不够）
- 只改了客户端 → 搬运后刷新页面即可
兼容性
| DSH 版本 | 状态 |
|---|
| 0.2.x（0.2.0-rc.2 实测） | ✅ 支持 |
本插件从 @deepseek-ai/dsh-tools 取 defineTool（已声明为 peerDependencies），
其余宿主能力（timer、tools、fs、webServer、systemPrompt）全部通过
cordis 服务注入获取。
License
MIT
