# TODO（功能规划）

> 未来功能规划清单，按优先级排序。每项实现后请移入 [CHANGELOG.md](../CHANGELOG.md)
> （只记用户可见的功能性改动）。

## dsh 兼容性（dsh 0.1.0-rc.7 → 0.1.0-rc.8，2026-08-20）

**状态**：✅ 静态兼容已确认（检查 + 补验完成）：rc.8 相对 rc.7 有 537 个提交，经静态比对 +
用 rc.8 类型重新 build（通过）判为**无破坏性影响**；README 兼容性章节已更新到
0.6.0 / 0.1.0-rc.8。剩余「运行时冒烟」作为收尾建议，见下。

**已确认兼容**（静态比对 rc.7 vs rc.8 + rc.8 类型编译通过）：

- host 侧契约零变更：`agent/pre-step`（`PreStepDecision`）、`contextProvenance`/`contextForm`
  注入机制、`notesApiHandler` 契约、`dsh-host-webserver` 均无改动；
- client 关键契约保留：`createSnapshotStore` 签名一致、`InputTriggerServiceContract` 零 diff、
  `MarkdownText`/`Modal`/图标组件保留、locale `TranslateNS` 保留；
- 插件 4 个 slot 注入点全部保留（`sidebar.footer.action` / `conversation.chat.assistant-actions`
  / `shell.overlay` / `settings.section`）；ui-conversation slots 契约**纯新增**，无删改；
- **client 加载协议保留**：`window.__ModuleLoader__`（client-modules contract C6）在 rc.8 的
  `cordis-client-runner` 中保留，插件 tsdown bundle 的 `__ModuleLoader__.load` 加载方式不变；
  `ui-renderer` 为动态 client bundle、等全部 entry 激活后 mount root，装配协议兼容；
- 插件依赖全部 `*` peer（运行时从 host 解析），node_modules 已对齐 rc.8，`npm run build` 通过。

**剩余（运行时冒烟，建议在 rc.8 环境点一遍）**：重启 dsh web 到 rc.8 后，浏览器逐项验证
侧边栏入口、@ 引用候选/chip/注入、记入笔记、笔记管理器增删改查与预览、Git 同步、写锁互斥、
设置面板。若有回归再回到本条处理。

**验收标准**：✅ README 兼容性章节已更新到 0.6.0 / 0.1.0-rc.8；运行时冒烟无回归。

## 2. 笔记加入对话上下文（@ 引用）

**状态**：✅ 已实现（0.4.0 + NEXT_VERSION）：`@` 候选/chip/跨工作区、序列化为标准 markdown
链接 `[标题](路径)`、host `agent/pre-step` 内容注入（含引用约定）。细化项见 2.1/2.2。

### 2.1 引用摘要（暂缓）

- 在注入时只放「标题 + 前 N 字符摘要」（而不是全文），模型需要细节时再按路径 `read` 全文，
  减少注入内容的上下文占用。
- **暂缓**：当前注入的是全文（context.md §3.7），摘要可缓解长笔记占上下文的问题——需要
  权衡「模型直接拿全文」与「摘要 + 按需 read」的可靠性差异后再定。

### 2.2 引用笔记的样式优化（待做）

**目标**：把「笔记引用」在三个展示面上的观感从「能用」提升到「好看、可识别」。

**现状**：

- 输入框 chip：dsh 硬编码胶囊（蓝底、原生 4em 单元格），插件已做标签前置截断（>4 字符 → 前 4 + …）；
- 发送后的消息行：`引用笔记 [标题](.dsh-notes/xxx.md)`（标准 markdown 链接语法，标题与路径
  结构化绑定；dsh 用户气泡是纯文本渲染，暂不可点击）；
- 注入上下文行：通用「上下文注入」DisclosureRow（来源标 `md-notes`，内容头部带一行
  「引用约定：回答中引用用 markdown 链接」），无笔记专属外观。

**设想**（各受 dsh 渲染机制约束，见 context.md §2.1/§3.3/§3.7）：

1. **输入框 chip**：
   - 跨工作区引用的 chip 能看出工作区来源（如标签带 `工作区·` 前缀，或 hover tooltip 显示完整路径）；
   - 截断上限按 chip 实际像素宽自适应（当前 4 字符对中英混排偏保守）。
   - 受限点：chip DOM 为 dsh 硬编码（`InputBar`），尺寸 4em 固定；曾用 `DshChipCell` 字体覆盖
     放大（6em/10em），按平台「不注入核心样式」规范已移除——后续若要更大标签区，需平台开放
     chip 尺寸或渲染扩展点。
2. **发送后的消息行**：✅ 已落地 **markdown 链接语法** `[标题](路径)`（标准、渲染器可识别）。
   剩余：
   - 等 dsh 提供用户消息内容块的渲染扩展点后，把引用渲染成可点击的行内卡片/链接；
   - 或评估 dsh 的 `/name`、`@name` 词元 chip 渲染（`projectUserText` 的 `refChip`）能否套用。
3. **注入上下文行**：
   - 来源标签显示**笔记标题**而非 `md-notes`（受 `contextProvenance` 的 kind 映射约束，
     需在 source 里携带标题字段或选用 dsh 已有 form/provenance 通道）；
   - 行内摘要（标题 + 前 N 字）与更贴合的图标/配色（当前走通用 `OpaqueBody`）。
   - **手动删除持久化**：注入的笔记内容会一直留在会话历史里（直到 compaction）。
     在注入上下文行上加「删除」按钮：host 新增 API（如 `contextRemove(sessionId, path)`），
     按 `source.kind === 'md-notes'` + `path` 定位该消息，用 surface `{ op: 'replace', start, end }`
     把它从模型可见历史中移除（compaction 同款机制）；只删注入内容、不动用户自己的消息；
     删除后不会复活（pre-step 只扫描新提交消息找引用）。

**验收标准**：三个展示面都能一眼识别「这是一篇笔记引用」及其来源工作区/标题；
明暗主题下样式一致；不破坏现有引用功能（候选/chip/注入）。

## 3. Git 冲突渲染及可视化解决

**目标**：推送/更新遇到 git 冲突时，不再只给纯文本错误，而是可视化展示并引导解决。

**冲突模型（现状）**：插件是**镜像同步**（复制 `.md`），冲突 = 同一笔记在本地与远端
**内容不同**（`changedNotes` 检测）；现有解决 = 二选一确认弹窗（用远端/用本地覆盖）+
`gitSync`（`git pull` 合并远端，此时才可能出现 git 冲突标记）。

**方案定稿（2026-08 调研）**：需要**本地/远端交叉编辑合并**（逐块选边 + 手动微调合并结果），
因此采用可编辑的合并编辑器：

- **首选：CodeMirror 6 + [`@codemirror/merge`](https://www.npmjs.com/package/@codemirror/merge)**
  （MIT）：并排两路 diff + 冲突块 **accept/reject 按钮**（逐块接受左/右/两边），结果区
  可自由编辑；三路模式有 ours/theirs/combined。体积可控（~300KB gzip 级），可内嵌管理器，
  tsdown 内联进 bundle。
- **备选**：Monaco diff editor（功能更强但体积大，需裁剪 worker/语言包）。
- **只读备选**：diff2html（~20KB，仅「查看差异 + 二选一」，**不支持交叉编辑合并**——不满足
  本项目标，仅作只读预览用）。

**设想**：

- 冲突检测已具备（`remote-changed`、`non-fast-forward` 错误码）；在此基础上：
  - **冲突渲染**：管理器内嵌 CodeMirror merge 面板，渲染**远端 vs 本地**对比（host 新增 API
    返回远端 clone 中该笔记的内容），逐文件查看差异。
  - **可视化解决**：冲突块逐块接受/拒绝（ours/theirs/combined）+ 合并结果直接编辑，写回本地
    （可经 git 提交）；保留「用远端覆盖 / 用本地覆盖」整篇快捷操作。
  - 合并（`gitSync`）的结果展示合并状态与剩余冲突。
- **host 扩展**：新增读远端 clone 中目标笔记内容的 API（现有 gitStatus 基础设施可扩展）。

**验收标准**：推送/更新遇冲突时，管理器展示冲突列表与可编辑的差异视图，用户可逐块选择
保留/合并并保存结果。

## 4. 笔记能力增强

**目标**：围绕「记、查、找、读」提升笔记使用体验——从纯文件编辑升级为顺手的信息管理。
笔记量大了之后，检索、导航、互链与快速访问比渲染细节更影响日常体验，优先做这些。

**渲染基础**：✅ 已就绪（0.4.0）：预览改用 dsh `MarkdownText`（micromark/mdast 生态：
GFM 全套、TeX 公式（KaTeX）、代码高亮（Shiki）、CJK 友好加粗、XSS 安全内置——原始
HTML / 危险协议禁用）。自研 `renderMd` 已移除，`markdown.ts` 只留 `fmtTime`。因此表格 /
任务列表 / 图片 / 嵌套列表 / 代码块语言高亮等语法开箱即用，且与 dsh 聊天渲染一致。

**设想**（按优先级）：

- **4.1 笔记搜索**（高）：管理器加搜索框，跨工作区**全文搜索**（标题 + 内容），输入即时
  过滤、命中高亮，结果按工作区 / 笔记分组展示命中位置。host 侧只读遍历各工作区
  `.dsh-notes` 下的 `.md`（规模小每次现扫，量大再考虑索引 / 防抖）。
  验收：多笔记工作区秒级定位；结果展示命中上下文。

- **4.2 标题目录（TOC）**（高）：预览顶部 / 侧栏按笔记标题生成目录，点击锚点跳转。
  约束：`MarkdownText` 标题渲染无锚点（dsh 未开放 heading 定制）——先评估 dsh 是否有
  heading id / 滚动定位扩展点；若无，降级为提取标题列表、点击 `scrollIntoView` 定位
  （需自建轻量标题提取，与 MarkdownText 输出并行）。
  验收：长笔记可一键跳到任意标题。

- **4.3 笔记互链 + 反链**（中，**精细化设计待定稿**）：在笔记内容里引用其他笔记并支持跳转。
  **方向（用户反馈）**：不采用反引号包 `笔记名` 的粗糙触发（fileMentions 曾试做后回滚，
  观感与预期差距大）——应采用与对话引用一致的 **`@笔记名`** 语法（或 `[[笔记名]]` wiki
  链接），先细化设计再实现：
  - **渲染链路**：`@笔记名` 在 MarkdownText 里是普通文本（渲染为纯文本、无交互），且
    MarkdownText **不接受自定义 mdast 节点渲染器**。可选方案：
    a) **预处理 + fileMentions**：渲染前把匹配的 `@笔记名` 替换为行内代码形式喂给
       `fileMentions`（有反引号/代码样式副作用，需评估观感）；
    b) **自建渲染管线**：micromark + mdast 扩展 + 自有 React 渲染器（可复用 dsh 的
       highlight/katex，代价高但完全可控）；
    c) **给 dsh 提需求**：MarkdownText 开放自定义行内节点渲染扩展点（最干净，依赖上游）。
  - **匹配规则**：`@标题` 或 `@文件名`；当前工作区优先 → 全工作区；**同名歧义**的处理
    （候选选择 / 忽略 / 后缀区分）；大小写与空格归一化。
  - **交互**：点击跳转目标笔记（复用 open 路由）；hover 显示标题 / 路径；目标不存在
    （改名 / 删除）时的**失效样式**（如灰色删除线）与是否提示创建。
  - **反链**：host 扫描各笔记内容，找出引用当前笔记的 `@` / `[[…]]`，编辑器旁展示
    「谁引用了它」。
  验收：`@笔记名` 点击直达、同名歧义可解决、失效可见；反链列表准确。

- **4.4 快速访问**（中）：星标置顶 + 最近编辑列表（管理器顶部快捷区）；星标单独存
  （不入库，遵守 meta 缓存规则）。
  验收：常用笔记一步到达。

- **4.5 编辑体验**（中）：自动保存（防抖）、字数统计、编辑 / 预览切换快捷键
  （探索 dsh 快捷键注册扩展点；无扩展点则仅插件内监听）。
  验收：编辑不丢改动、字数可见。

- **4.6 图片支持**（中）：拖拽 / 粘贴图片存入笔记同目录（或 `.dsh-notes/assets/`），
  markdown 以相对路径引用并预览（MarkdownText 原生支持图片语法）。注意：Git 同步当前只
  同步 `.md`（「Only `.md` files sync」），图片入库需扩展同步范围，需一并评估。
  验收：截图可直接贴入并预览；若扩展同步则图片随笔记推送。

- **4.7 导出**（低）：单篇导出 md / HTML（浏览器下载）；全部导出打包 zip（需引入打包
  依赖，或逐篇下载）。
  验收：笔记可脱离插件带走。

- **4.8 配套测试**（中，承接原剩余项）：`MarkdownText` 为 dsh 组件无需自测；可测领域
  逻辑（`sanitizeName`、`titleOf`、`blocksToText` 等，用 `fs.mkdtemp` 跑真实读写），
  引入 vitest + `npm test`。
  验收：`npm test` 全绿；领域逻辑改动有用例保护。

**安全 / 平台约束**：搜索、反链走 host 只读遍历，不碰笔记外文件；互链 / 反链复用既有
name 解析与 @ 引用逻辑；新 UI 文案进 `md-notes` 字典（中英）；渲染安全由 MarkdownText
保证（不引入原始 HTML 透传）；不注入核心样式——依赖注入样式的增强（如自定义标题锚点）
受平台约束，标注「探索扩展点，受限则降级」。

**验收标准**：大笔记量下可秒级搜索定位；预览可按目录跳转；互链可点击直达、反链准确；
星标 / 最近让常用笔记一步到达；新功能文案双语一致。

## 5. 交互体验优化

**目标**：磨平日常使用中的摩擦点——本地改动与远端状态可见、长操作不阻塞界面、编辑不静默丢失。

**设想**（按优先级）：

- **5.1 本地编辑未推送提醒**（高）：笔记本地修改 / 新建后未 git push 时给出**可见且持久**的提醒——
  例如管理器底部状态行 / 工作区行显示「未推送 N 处」（现状 `git.uncommitted` 已有未提交计数，
  但不醒目），并在关闭前提示，避免用户以为已同步、换设备后丢失改动。
- **5.2 记入笔记即时化**（高）：✅ 卡顿根因已修复（NEXT_VERSION）——文本改由 client 从
  浏览器会话快照提取（`note-text.ts`），host 只写文件，不再 `sessionQuery.readSession`
  全量读会话（曾同步阻塞事件循环卡住面板）。剩余可选优化：写入后台化（弹窗立即关、后台
  追加，完成以状态提示 / 刷新列表）——写入已近毫秒级，必要性降低，暂缓。
- **5.3 编辑器脏状态提醒**（中）：编辑未保存时切换笔记 / 关闭管理器前提示（或自动保存）——
  现状：切换笔记直接丢弃未保存内容。
- **5.4 保存快捷键**（中）：Cmd/Ctrl+S 保存当前笔记（探索 dsh 快捷键注册扩展点；无则插件内监听）。
- **5.5 笔记写入互斥（写锁）+ 全局写入状态**（高）：✅ 已实现（NEXT_VERSION）——host 通用
  `KeyedLock`（write / appendConversation / delete 三操作互斥，冲突返回 `note-writing`）+
  client 通用 busy 切片（`store.busy` + `BusyTracker`，域前缀 `note/<ws>/<name>`，可扩展至
  git / export 等未来任务域）；笔记入口 loading + tooltip「X 个笔记正在写入」、记入弹窗
  不可选中 + 行尾 loading、管理器行 loading + 隐藏删除 + 操作栏禁用 + 「正在写入文件」提示
  三处联动，写入完成自动还原。方案 [write-lock.md](write-lock.md)，状态总纲 [state.md](state.md)。
- （可按需扩展：保存成功定位、操作 loading 统一、多标签编辑等。）

**验收标准**：未推送改动在界面上清晰可见且关闭前有提醒；记入笔记不阻塞弹窗；未保存编辑
不静默丢失；保存可用快捷键触发。