@docmd/plugin-threads 插件可在文档页面上实现协作式内联评论与文本标注。高亮与讨论线程使用自定义容器块（::: threads）原生存储在 Markdown 源码文件中。无需外部数据库。

原作者: @svallory

安装与设置

通过 CLI 安装插件：

npx @docmd/core add threads

在 docmd.config.json 中启用线程配置：

Live 开发服务器依赖要求

Threads 讨论交互界面、高亮标注工具以及 Markdown 文件持久化写入操作，依赖本地实时运行的开发服务器（docmd dev）以及 WebSocket RPC 连接。

由于 Threads 声明了 requiresLiveServer: true：

• 本地开发运行（docmd dev）：右侧停靠滑块标签、行内评论预览卡片、选区弹出框以及侧边栏面板完全正常加载并提供全量交互。
• 静态生产构建（docmd build）：自动剔除前端脚本与样式，确保公开发布的生产站点保持极致轻量、零冗余，且不会产生无效的 WebSocket 连接重试报错。文档中原有的 Markdown 语法块（::: threads 与 ==文本=={t-...}）依然保持完整解析，不会产生格式错乱。
• 手动覆盖：如果您明确希望在静态构建中打包 Threads 前端资源，可以在 plugins.threads 中显式配置 "devOnly": false。

全局配置示例

{
  "plugins": {
    "threads": {
      "sidebar": true,
      "devOnly": true
    }
  }
}

工作流概览

1. 文本选择: 在本地实时开发期间（npx @docmd/core dev）选择文本段落。
2. 评论弹出框: 在弹出模态框中输入反馈。
3. 锚点注入: 选中的文本段落会附带线程标识符进行高亮（==高亮文本=={t-a1b2c3d4}）。
4. Markdown 持久化: 线程结构作为 ::: threads 块追加在 Markdown 文件的底部。
5. Git 同步: 讨论历史与文档编辑一同保存在版本控制中。

交互式预览

附带讨论的文本会接收到内联彩色高亮。线程卡片在下方渲染：

额外的高亮会自动循环使用不同的调色板：

已解决的讨论以置灰状态展示：

右侧贴边停靠的标签触发器 💬2 贴紧视口右边缘，显示未解决的主题计数。将鼠标悬停在任何高亮文本上时，会直接在内容中呈现内联评论预览卡片，而点击标签则会滑出讨论侧边栏抽屉。在打开和关闭抽屉时，页面主题会无缝持久保存，无需重新加载整个页面。

Markdown 存储格式

线程使用容器块语法保存在文档源码文件中：

# 引擎概览

核心架构特性包含带有附着线程的 ==高亮文本=={t-a1b2c3d4}。

::: threads
  ::: thread t-a1b2c3d4
    ::: comment c-e5f6a7b8 "Alice" "2026-04-09"
      This text requires additional technical detail.
    :::
    ::: comment c-d9e0f1a2 "Bob" "2026-04-09" reply-to c-e5f6a7b8
      Updated with extra specifications.

      ::: reactions
        - 👍 Alice
      :::
    :::
  :::
:::

核心功能

• 文本选择: 高亮任意文本以锚定新线程。
• 嵌套回复: 嵌套对话线程。
• Emoji 反应: 为评论添加反应计数器。
• 解决状态: 标记线程为已解决并带有作者归属。
• 作者身份: 本地 Git 凭证自动解析头像与个人资料信息。

RPC Actions API

Threads 插件暴露可由 docmd.call() 调用的 WebSocket RPC 端点：

作者个人资料存储

作者个人资料缓存在 <docsRoot>/.threads/authors.json 中：

{
  "alice@example.com": {
    "name": "Alice",
    "avatarUrl": "https://gravatar.com/avatar/..."
  }
}