# DSH Collab-Canvas 设计文档

> 状态：V1 范围已冻结 · 本文档是需求的唯一权威来源
> 关联文档：[ARCHITECTURE.md](./ARCHITECTURE.md) · [TOOL-SCHEMAS.md](./TOOL-SCHEMAS.md)

## 1. 项目概述

**名称**：DSH Collab-Canvas
**定位**：DeepSeek Harness 的人机协作画布插件

**要解决的问题**：人机协作时，方案、代码、设计稿等内容在对话中反复复制粘贴，上下文割裂、历史难追溯。

**解决方案**：人和 AI 在同一画布上直接编辑同一份内容。AI 的产出直接落在画布上，人的修改 AI 立即可见，双方共享同一个工作面。

**核心价值**：多种画布（文档 / 代码 / UI 设计 / 工作流）通过事件系统联动，模仿专业 IDE + AI Agent 工作台的体验——修改任意一个面板，其它面板可以感知、跳转、上下文自动同步。联动是这个插件的灵魂，而不是几个互相孤立的标签页。

## 2. 需求决策记录

以下结论来自与用户的逐项确认，是范围的最终依据：

| 决策点 | 结论 | 备注 |
|--------|------|------|
| 画布类型 | 文档 / 代码 / UI 设计 / 工作流 四类 | 分期实现 |
| **V1 范围** | **文档画布 + 事件骨架** | 最小可用版本 |
| 协作模式 | **AI 直接编辑 + 人可撤销** | 流畅优先，不做审批制 |
| 持久化 | **保存为本地文件** | workspace 内优先，支持映射外部目录 |
| AI 触发方式 | 对话引用 / 右键菜单 / 指令栏，**全部支持** | 分阶段落地 |
| UI 设计画布定位 | AI 根据描述和图片生成；人可指定改哪里、怎么改；支持拖拽、框选、提供素材替换 | 不限于安卓，覆盖 PC 软件、各种插件等 |
| AI 协作深度 | **全栈协作**：读写内容 + 触发工作流执行 + 分析结果并反馈 | 工作流触发在 V2 启用 |
| 工作流页定位 | 集成 Harness 现有 subagent/workflow 能力，不重新造轮子 | |

## 3. V1 功能范围

### 3.1 文档画布

| 功能 | 说明 |
|------|------|
| Markdown 编辑 | 纯文本编辑区，等宽字体 |
| 实时预览 | 左右分栏，编辑区与预览区同步滚动 |
| 文件操作 | 新建 / 打开 / 保存 / 另存为 |
| Undo / Redo | 完整编辑历史栈，**人和 AI 的编辑统一入栈**，均可撤销 |
| 自动保存 | 编辑防抖后自动写盘，断电/重启不丢内容 |
| 会话恢复 | 重启后从 `.canvases.json` 元数据恢复画布列表和内容 |
| `[[文件路径]]` 标记 | V1 仅渲染为链接样式；点击跳转到代码画布的能力 V2 接入后启用 |

### 3.2 AI 能力

模型通过六个动态工具直接操作画布（详见 TOOL-SCHEMAS.md）：

```
canvas_list    canvas_read    canvas_write
canvas_save    canvas_load    canvas_trigger_workflow (V2 预留)
```

触发入口：

| 入口 | V1 | 说明 |
|------|----|----|
| 对话中引用 | ✅ | 用户说"帮我在画布里写XX"，AI 调 canvas_write 直接写入 |
| 画布底部指令栏 | ✅ | 输入指令引导用户发送到对话，由 AI 执行（具体机制待勘察，见 ARCHITECTURE §8） |
| 选中文本右键 AI 操作 | ⏳ V2 | 改写 / 扩展 / 翻译 / 总结 |

AI 编辑行为约定：
- AI 编辑**默认直接生效**，不弹确认框；
- 人可通过 Ctrl+Z 或历史面板撤销任意一次 AI 编辑；
- 每次 AI 编辑都带 `source: 'ai'` 标记入历史栈，历史面板中可视化区分。

### 3.3 事件骨架

- 定义 `CanvasEvents` 常量表与 Host 内事件总线（详见 ARCHITECTURE §5）；
- V1 所有内容变更、文件保存、AI 编辑都会发布事件；
- V1 不消费这些事件做跨面板联动，但为 V2 联动铺平接口。

## 4. 明确排除在 V1 之外

- ❌ 代码画布、UI 设计画布、工作流画布的完整实现
- ❌ 跨面板跳转联动（文档→代码、代码→预览等）
- ❌ 多人实时协作（WebSocket 同步）
- ❌ 移动端适配
- ❌ 富文本编辑器、所见即所得模式

## 5. 用户流程（V1）

1. 从侧边栏「画布」入口打开画布面板 → 新建一个文档画布；
2. 人直接写需求方案；或对 AI 说「帮我在画布里写一版登录模块的设计方案」→ AI 通过 `canvas_write` 直接写入；
3. 人对某段 AI 生成的内容不满意 → Ctrl+Z 撤销该次编辑，或直接在画布上改；
4. 内容随编辑自动保存到 `<workspace>/canvas-docs/<标题>.md`；
5. 会话重启 → 画布列表从元数据恢复，点开继续编辑。

## 6. 成功标准（验收清单）

- [ ] 能创建、编辑、保存 Markdown 文档画布
- [ ] AI 能读取画布内容并直接编辑（对话中说一句话即生效）
- [ ] Undo/Redo 正常工作，包括撤销 AI 的编辑
- [ ] 编辑内容自动保存到文件，防抖生效（不每键写盘）
- [ ] 重启会话后能从文件恢复画布列表与内容
- [ ] 外部路径不在白名单时明确拒绝并提示，不崩溃
- [ ] 版本冲突（人正在编辑时 AI 写入）有明确的冲突处理，不静默覆盖
- [ ] 事件总线骨架就位，所有关键动作发布事件
- [ ] 插件停止/更新后无残留副作用（定时器、DOM、监听全部清理）