前言¶
在 DeepSeek Harness（DSH）的聊天窗口中，AI 生成的长文档容易刷屏，修改一个段落往往需要重发全文，且对话历史中的版本难以追溯。collab-canvas（话布）提供了解决方案：它将长内容从对话中剥离，托管到一个独立的 Markdown 文档画布上。你在浏览器内直接编辑，AI 通过 9 个专用工具读写，双方的操作均进入撤销历史并支持冲突检测。
核心功能¶
- 浏览器内编辑：画布在 DSH 界面内渲染与编辑，改动自动保存。
- AI 可读写：AI 通过
canvas_*系列工具直接操作画布，而非将内容贴入对话。 - 撤销历史：每次写入入栈，人和 AI 的改动均可回退。
- 冲突检测：
canvas_write支持baseVersion强一致检查，若内容被覆盖则返回E_CONFLICT。 - 文件持久化：画布以普通 Markdown 文件存储，配合
.canvases.json记录元信息。 - 划词引用：选中画布文字可弹出引用栏，将段落带入对话。
- 文档链接/拖放：支持在画布内拖入文档或生成链接。
- 存储根可配：通过
canvas_configure可将画布根目录固定到任意位置。 - 跟随主题：界面使用
var(--dsw-*)设计 token，自动适配主题换肤。
安装与启用¶
安装命令如下：
dsh plugin --profile web add collab-canvas
安装完成后，必须进行两步配置才能启用插件：
- 在 profile 的
package.json中将"collab-canvas"加进dsh.profile.bundles数组。 - 确保
dependencies字段也包含该包。
注意：只添加 dependencies 而不加 bundles 会导致 cordis.patch.yml 未生效，表现为“装上了但功能不在”。推荐使用 npm 安装，可避免 git 依赖触发的构建授权问题，且能在市场显示下载量。
AI 工具¶
插件提供了 9 个工具，用于管理画布：
canvas_list：列出全部画布与当前活跃画布。canvas_create：新建一个画布。canvas_read：读取画布内容（head参数可截取前 N 字符）。canvas_write：写入或修改画布（支持replace/append/prepend及baseVersion）。canvas_save：保存画布到指定文件路径。canvas_load：将已有 Markdown 文件加载为画布。canvas_locate：在文档中精确定位一段原文（处理重复文本）。canvas_delete：删除画布记录。canvas_configure：固定画布存储根目录。
数据存放与架构¶
画布文件与元信息存储在指定的存储根目录下：
<存储根>/
├── .canvases.json # 画布元信息（id、标题、关联文件、版本）
├── <标题>.md # 画布正文
├── .sessions/ # 会话级清单
└── attachments/ # 粘贴/拖入的图片
默认存储根为当前会话工作区。架构分为两部分：
- Host（DSH Node 进程）：运行在
dist/host.js，负责注册工具、HTTP 端点、状态持久化与编辑器脚本。 - Client（浏览器页面）：运行在
lib/client.js，负责注入 UI、划词栏及与 Host 的 RPC 通信。
开发与部署¶
开发涉及构建与搬运到 DSH 部署目录：
npm run build # 编译 src/host/*.js → dist/host.js
npm run deploy # 搬运到部署目录
npm run verify # 上线前总检
部署目录默认由 DSH_HOME 推导，可通过环境变量 CCV_DEPLOY_DIR 覆盖。
生效规则：
- 修改了 src/host/*.js → 搬运后必须完全重启 dsh web（刷新页面不够）。
- 只修改了客户端 → 搬运后刷新页面即可。
适用场景¶
适合需要将 AI 协作内容沉淀为文档、进行版本控制或多人（人+AI）协同编辑的场景。使用前请检查源码与许可证。
总结¶
collab-canvas 解决了 DSH 中长文档难以管理的问题，通过工具化接口让 AI 能够安全地读写 Markdown 文档。掌握其安装配置与部署规则，是高效利用该插件的前提。
