Threads 插件 为您的文档带来协作式内联评论。选择文本、留下评论、开启讨论。所有线程都直接存储在您的 markdown 源文件中。无需数据库。

原作者：@svallory

配置

Threads 插件是可选插件。通过 CLI 安装：

npx @docmd/core add threads

在您的 docmd.config.json 中启用它。

示例

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

工作原理

1. 在 npx @docmd/core dev 期间，在任何文档页面上选择文本。
2. 出现评论弹出框。编写评论并提交。
3. 所选文本会突出显示，带有线程标记。
4. 线程作为 ::: threads 块存储在 markdown 文件底部。
5. 无需数据库。您的 markdown 文件保持唯一的真实来源。

预览

以下是线程在实时页面上的外观。有讨论的文本会以 <span class=“threads-preview-highlight”>这样的方式突出显示</span>。线程卡片出现在下方。

<div class=“threads-preview-card”>
<div class=“threads-preview-comment”>
<div class=“threads-preview-avatar”>A</div>
<div class=“threads-preview-meta”><strong>Alice</strong> · 2d ago</div>
<div class=“threads-preview-body”>This section could use a diagram to explain the architecture. What do you think?</div>
</div>
<div class=“threads-preview-comment threads-preview-reply”>
<div class=“threads-preview-avatar”>B</div>
<div class=“threads-preview-meta”><strong>Bob</strong> · 1d ago</div>
<div class=“threads-preview-body”>Good idea - I’ll add a Mermaid flowchart. Does <code>sequenceDiagram</code> work here?</div>
<div class=“threads-preview-reactions”>
<div class=“threads-preview-reaction”>👍 <span>2</span></div>
<div class=“threads-preview-reaction”>🚀 <span>1</span></div>
</div>
</div>
<div class=“threads-preview-comment threads-preview-reply”>
<div class=“threads-preview-avatar”>A</div>
<div class=“threads-preview-meta”><strong>Alice</strong> · 12h ago</div>
<div class=“threads-preview-body”>Perfect. A simple flowchart would be ideal.</div>
</div>
<div class=“threads-preview-footer”>
<div class=“threads-preview-footer-btn”>+ New Comment</div>
</div>
</div>

这里是<span class=“threads-preview-highlight-blue”>带不同颜色的第二个高亮</span>。线程会自动循环使用调色板中的颜色。

<div class=“threads-preview-card threads-preview-card-blue”>
<div class=“threads-preview-comment”>
<div class=“threads-preview-avatar”>C</div>
<div class=“threads-preview-meta”><strong>Charlie</strong> · 3d ago</div>
<div class=“threads-preview-body”>Should we mention backward compatibility here?</div>
</div>
<div class=“threads-preview-footer”>
<div class=“threads-preview-footer-btn”>+ New Comment</div>
</div>
</div>

已解决的线程显示为暗色：

<div class=“threads-preview-card threads-preview-card-resolved”>
<div class=“threads-preview-comment”>
<div class=“threads-preview-avatar”>A</div>
<div class=“threads-preview-meta”><strong>Alice</strong> · 5d ago  <span class=“threads-preview-resolved-badge”>✓ Resolved</span></div>
<div class=“threads-preview-body”>Fixed the typo in the config example.</div>
</div>
<div class=“threads-preview-footer”>
<div class=“threads-preview-footer-btn”>+ New Comment</div>
</div>
</div>

一个浮动的讨论按钮 <span class=“threads-preview-fab”>💬<span class=“threads-preview-fab-badge”>2</span></span> 出现在右下角。它显示打开线程的数量。点击它可跳转到页面上的第一个线程。

存储格式

线程使用 docmd 的容器语法嵌入到您的 markdown 中：

# My Documentation Page

Some content with ==highlighted text=={t-a1b2c3d4} that has a thread.

::: threads
  ::: thread t-a1b2c3d4
    ::: comment c-e5f6a7b8 "Alice" "2026-04-09"
      This text needs clarification.
    :::
    ::: comment c-d9e0f1a2 "Bob" "2026-04-09" reply-to c-e5f6a7b8
      Updated it - does this work?

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

==text=={threadId} 语法将文档正文中突出显示的文本链接到特定线程。

功能

Actions API

threads 插件通过 WebSocket RPC 系统暴露以下 actions。使用 docmd.call() 从浏览器插件调用它们：

作者档案

作者信息存储在 <docsRoot>/.threads/authors.json 中：

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

在开发期间，插件会自动检测您的 Git 用户名和电子邮件以进行作者身份识别。