LivingDocs

AI 驱动的文档健康监测工具。它可检测过时的代码注释、发现知识缺口、提醒人员离职风险，并摄取 Slack、Teams 和电子邮件对话，让整个组织的知识始终可搜索且保持最新。

安装

需要 .NET 10 SDK。

dotnet tool install -g LivingDocs.Mcp

工具

工具	版本	描述
scan_repo	免费	扫描代码仓库，并列出过时文档文件及其过时百分比（0–100%）
query_docs	免费	使用代码库中的文档注释，回答有关代码库的自然语言问题
index_repo	免费	为代码仓库构建或刷新语义搜索索引
suggest_doc_update	免费	请 Claude 重写过时的文档注释
write_back	免费	将 Claude 生成的文档更新直接写入源文件
detect_gaps	免费	查找没有任何文档的文件，并按提交活跃度排序
departure_risk	免费	找出关键文件的唯一贡献者（公交因子）
write_docs	专业版	将更新后的文档写入 docs/<File>.md，并附上 UTC 时间戳 — 完整审计记录
sync_confluence	专业版	将更新后的文档写回 Confluence 页面
scan_org	专业版	扫描 GitHub 组织中的所有代码仓库，并生成组织级报告
index_slack	专业版	将 Slack 频道编入知识库索引 — 可通过 query_docs 搜索
index_teams	专业版	将 Microsoft Teams 频道编入知识库索引
index_email	专业版	将 IMAP 邮件文件夹编入知识库索引

快速测试

livingdocs-mcp scan /path/to/your/repo

Scanning /path/to/repo ...
Files examined : 12
Stale docs     : 2

  [██████████]  100%  src/Tax.cs
               doc updated : 2024-09-01
               code changed: 2025-01-15

  [████░░░░░░]   40%  src/Auth.cs
               doc updated : 2024-12-01
               code changed: 2025-01-28

---

设置 — Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "livingdocs": {
      "command": "livingdocs-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

重启 Claude Desktop。工具会显示在 + 菜单下。

---

设置 — Claude Code

在项目根目录中添加 .mcp.json 文件：

{
  "mcpServers": {
    "livingdocs": {
      "command": "livingdocs-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

或者进行全局注册：

claude mcp add livingdocs -s user -- livingdocs-mcp

然后在 Claude Code 聊天界面中：

scan this repo for stale docs              → uses scan_repo
what does the Auth module do?              → uses query_docs
suggest a fix for src/Tax.cs              → uses suggest_doc_update
find undocumented files                   → uses detect_gaps
who owns the payments module?             → uses departure_risk

---

设置 — GitHub Copilot（VS Code）

VS Code 1.99+ 支持在 Copilot Agent 模式下使用 MCP 服务。在项目中添加 .vscode/mcp.json 文件：

{
  "servers": {
    "livingdocs": {
      "type": "stdio",
      "command": "livingdocs-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

打开 Copilot 聊天面板，切换到 Agent 模式，即可使用这些工具。

注意： @livingdocs Copilot Extension Agent 已构建并部署，但由于 GitHub Copilot 计划尚未支持注册 Agent URL，目前仍待开放。与此同时，上述 MCP 服务路径可正常使用。

---

设置 — GitHub Webhook

Webhook 集成会监视代码仓库中每次 PR 合并，并自动以 PR 评论的形式发布过时文档报告。还可选择发送 Slack 通知，其中包含一个 自动起草 按钮，只需单击一次即可生成文档修复。

1. 部署 LivingDocs.CopilotExt

Webhook 处理程序以 Web 服务的形式运行。将其部署到任意主机（Railway、Fly.io、VPS）：

# Docker
docker build -t livingdocs-ext .
docker run -p 8080:8080 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GITHUB_WEBHOOK_SECRET=your-secret \
  -e LIVINGDOCS_REPO_PATH=/path/to/local/repo \
  livingdocs-ext

2. 在 GitHub 中注册 Webhook

前往你的仓库 → Settings → Webhooks → Add webhook：

字段	值
Payload URL	https://your-server/api/github/webhook
Content type	application/json
Secret	任意随机字符串 — 设置为 GITHUB_WEBHOOK_SECRET
Events	选择单个事件 → 仅勾选 Pull requests

3. 设置必需的环境变量

变量	必需	说明
GITHUB_WEBHOOK_SECRET	是	必须与在 GitHub 中输入的密钥一致
LIVINGDOCS_REPO_PATH	是	仓库本地克隆的绝对路径
GITHUB_TOKEN	建议	具有 repo 作用域的 PAT — 发布 PR 评论和获取差异内容时需要
ANTHROPIC_API_KEY	是	用于 AI 影响分析和语义文档映射
SLACK_WEBHOOK_URL	可选	用于 Slack 过时文档提醒的传入 Webhook URL
SLACK_SIGNING_SECRET	可选	启用 Slack Auto-draft 按钮（Slack App → Basic Information）

4. 每个已合并 PR 会发生什么

1. GitHub 发送一个 pull_request 事件，其中包含 action: closed, merged: true
2. LivingDocs 验证 HMAC-SHA256 签名
3. 从 GitHub API 获取已更改的文件
4. 针对本地仓库运行过时文档检测
5. 调用 Claude 分析差异内容，并映射受影响的 .md 文档
6. 将报告作为 PR 评论发布
7. 发送 Slack 通知（如果已配置），其中包含 Auto-draft top doc 按钮

---

Pro 版

提供 7 天免费试用 — 开始试用无需信用卡。

Pro 工具需要许可证密钥：

export LIVINGDOCS_LICENSE_KEY=LD-xxxx-xxxx-xxxx

或者将密钥添加到 MCP 配置中的 env 块：

{
  "mcpServers": {
    "livingdocs": {
      "command": "livingdocs-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "LIVINGDOCS_LICENSE_KEY": "LD-xxxx-xxxx-xxxx"
      }
    }
  }
}

开始 7 天免费试用 — LivingDocs Pro（之后每月 $10）。

---

免费工具 — detect_gaps

查找没有任何文档注释的源文件，并根据提交活动为它们排序。最繁忙但未编写文档的文件是优先级最高的知识缺口 — 这些代码频繁变更，却从未得到说明。

在 Claude 中使用：

detect_gaps on /path/to/repo

输出示例：

Knowledge gaps in '/path/to/repo'
Files scanned: 42  |  Documented: 28  |  Undocumented: 14 (33%)

Top undocumented files by activity:
  src/payments/retry.ts          42 commits    last changed 2024-11-03  by Alice
  src/auth/session.ts            31 commits    last changed 2025-01-08  by Bob

To add docs to the highest-priority file, run:
  suggest_doc_update on /path/to/repo src/payments/retry.ts

---

免费工具 — departure_risk

识别作为关键文件唯一或主要贡献者的作者 — 这就是经典的“单点故障”问题。某位作者的提交占比 ≥60%，且总提交次数 ≥5 的文件会被标记为知识单点。

在 Claude 中使用：

departure_risk on /path/to/repo

输出示例：

Departure risk analysis for '/path/to/repo'
Files analysed: 42  |  High-risk files: 8

Authors with exclusive knowledge:

  Alice Chen  (6 files)
    • src/auth/session.ts        12 commits  (83% by Alice Chen)
    • src/payments/retry.ts       9 commits  (75% by Alice Chen)

  Bob Smith  (2 files)
    • src/core/engine.go         22 commits  (91% by Bob Smith)

To generate a handover doc for the riskiest file:
  suggest_doc_update on /path/to/repo src/auth/session.ts

---

Pro 工具 — write_docs

检测文件中过时的文档注释，通过 Claude 生成更新后的文档，并将结果附加到仓库内的 docs/<FileName>.md 中 — 每次运行都会添加 UTC 时间戳。每次运行都会新增一个带日期的章节，逐步建立完整的审计记录，追踪文档随时间的演变。

在 Claude 中使用：

write_docs on /path/to/repo for src/Tax.cs

创建或追加到 docs/Tax.md：

# Tax.cs — LivingDocs Documentation


## 2026-05-19

### TaxCalculator.Calculate
Calculates net tax payable given gross income, deductions, and the current financial year slab rates...

*Confidence: 92%*

---

---

Pro 工具 — sync_confluence

检测文件中过时的文档注释，通过 Claude 生成更新后的文档，并将结果写入对应的 Confluence 页面（如果页面不存在，则创建该页面）。

必需的环境变量：

变量	说明
CONFLUENCE_BASE_URL	你的 Confluence Cloud URL，例如 https://mycompany.atlassian.net/wiki
CONFLUENCE_EMAIL	Atlassian 账号电子邮件地址
CONFLUENCE_API_TOKEN	从 id.atlassian.com/manage-profile/security/api-tokens 获取的 API token
CONFLUENCE_SPACE_KEY	目标空间密钥，例如 DEV（可在空间 URL 中查看）

在 Claude 中使用：

sync_confluence on /path/to/repo for src/Tax.cs

---

Pro 工具 — scan_org

扫描 GitHub 组织中的每个仓库，并返回组织范围的陈旧度报告。对每个仓库执行浅克隆、运行过时文档检测，然后清理。

必需的环境变量：

变量	描述
GITHUB_TOKEN	具有 repo 和 read:org 权限范围的个人访问令牌

在 Claude 中的用法：

scan_org on my-company

示例输出：

Org: my-company — 8 repos scanned | 142 files | 5 stale docs

⚠️ Repos with stale docs
api-service — 3 stale / 48 files
  - src/Auth.cs (100%)
  - src/Tax.cs (80%)

✅ Clean repos (6)
frontend, user-service, admin-api, ...

---

Pro 工具 — index_slack

从 Slack 频道获取消息，并将其添加到仓库的知识索引中。建立索引后，query_docs 除了返回代码文档的结果外，还会返回 Slack 讨论的结果——因此，搜索“我们为什么选择 Postgres？”时，既能找到代码注释，也能找到作出该决定的 Slack 讨论串。

消息按讨论串分组，以保留上下文。系统会自动过滤机器人消息、加入／离开事件以及少于 30 个字符的消息。

必需的环境变量：

变量	描述
SLACK_BOT_TOKEN	机器人令牌（xoxb-...）——Slack 应用 → OAuth 和权限

所需的机器人 OAuth 权限范围： channels:history、channels:read

在 Claude 中的用法：

index_slack on /path/to/repo C1234ABCD

然后跨代码和 Slack 查询：

query_docs on /path/to/repo "how does the auth flow work?"

---

Pro 工具 — index_teams

通过 Graph API 从 Microsoft Teams 频道获取消息，并将其添加到知识索引中。使用客户端凭据 OAuth——无需用户登录。

必需的环境变量：

变量	描述
TEAMS_TENANT_ID	Azure AD 租户 ID
TEAMS_CLIENT_ID	Azure AD 应用（客户端）ID
TEAMS_CLIENT_SECRET	Azure AD 客户端密钥

Azure AD 应用设置：

1. 在 Azure 门户 → 应用注册中注册一个应用
2. 添加应用程序权限：ChannelMessage.Read.All
3. 授予管理员同意
4. 创建客户端密钥
5. 从 Graph Explorer 获取团队／频道 ID

在 Claude 中的用法：

index_teams on /path/to/repo <teamId> <channelId>

---

Pro 工具 — index_email

从 IMAP 邮箱文件夹获取电子邮件，并将其添加到知识索引中。电子邮件中的工程讨论、事故报告和架构决策都可以与代码文档一起搜索。系统会自动去除邮件引用（以 > 开头的行）。

支持 Gmail 应用专用密码、Microsoft 365 以及任何标准 IMAP 服务提供商。

必需的环境变量：

变量	描述
IMAP_HOST	IMAP 服务主机名，例如 imap.gmail.com
IMAP_USERNAME	电子邮件地址
IMAP_PASSWORD	密码或应用专用密码
IMAP_PORT	端口（默认值为 993）

**Gmail 设置：**使用应用专用密码，而非账号密码。需要启用两步验证。

在 Claude 中的用法：

index_email on /path/to/repo folder=Engineering

为获得最佳效果，请创建专用文件夹（例如 Engineering/Architecture），并将相关邮件筛选到其中。

---

Enterprise 级别

Enterprise 许可证可完全离线运行——许可证验证无需联网。非常适合气隙环境和受监管行业。

工作原理：

1. 联系 [[email protected]](mailto:[email protected]?subject=LivingDocs Enterprise)，并提供公司名称和团队规模
2. 接收签名的 JWT 许可证密钥和发票
3. 设置 LIVINGDOCS_LICENSE_KEY=<jwt>——验证在本地完成，不会调用外部 API

Enterprise 功能：

• 离线 JWT 许可证验证（由 RSA-256 签名，可在气隙网络中使用）
• 支持 Azure OpenAI——使用自己的 Azure 部署，而非 Anthropic
• 独立二进制文件——无需 .NET SDK，可从 GitHub Releases 下载
• 优先支持和定制发票（按年或一次性支付）

Azure OpenAI 设置：

{
  "mcpServers": {
    "livingdocs": {
      "command": "livingdocs-mcp",
      "env": {
        "LIVINGDOCS_LICENSE_KEY": "<enterprise-jwt>",
        "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com",
        "AZURE_OPENAI_API_KEY": "your-azure-key",
        "AZURE_OPENAI_DEPLOYMENT": "gpt-4o"
      }
    }
  }
}

---

环境变量

变量	必填	描述
ANTHROPIC_API_KEY	是（AI 功能）	Anthropic API 密钥 — 使用 Azure OpenAI 时不需要
LIVINGDOCS_LICENSE_KEY	是（Pro/Enterprise）	来自 Polar.sh 的 LD-xxxx 密钥或 Novaders LLP 提供的 JWT
AZURE_OPENAI_ENDPOINT	Enterprise	Azure OpenAI 资源终结点
AZURE_OPENAI_API_KEY	Enterprise	Azure OpenAI API 密钥
AZURE_OPENAI_DEPLOYMENT	Enterprise	Azure OpenAI 部署名称，例如 gpt-4o
GITHUB_TOKEN	建议	具有 repo + read:org 权限范围的 PAT — 用于 scan_org、PR 评论和私有仓库
GITHUB_WEBHOOK_SECRET	Webhook	HMAC 密钥 — 必须与 GitHub 仓库 Webhook 设置中配置的密钥一致
LIVINGDOCS_REPO_PATH	Webhook	Webhook 处理程序要扫描的本地仓库克隆的绝对路径
CONFLUENCE_BASE_URL	sync_confluence	Confluence Cloud URL，例如 https://mycompany.atlassian.net/wiki
CONFLUENCE_EMAIL	sync_confluence	Atlassian 账户邮箱
CONFLUENCE_API_TOKEN	sync_confluence	Atlassian API 令牌
CONFLUENCE_SPACE_KEY	sync_confluence	Confluence 空间密钥，例如 DEV
SLACK_WEBHOOK_URL	可选	PR 合并后用于发送过时文档 Slack 提醒的传入 Webhook URL
SLACK_SIGNING_SECRET	可选	在 Slack 通知中启用“自动起草”按钮（Slack App → 基本信息）
SLACK_BOT_TOKEN	index_slack	具有 channels:history + channels:read 权限范围的机器人令牌（xoxb-...）
TEAMS_TENANT_ID	index_teams	Azure AD 租户 ID
TEAMS_CLIENT_ID	index_teams	Azure AD 应用（客户端）ID
TEAMS_CLIENT_SECRET	index_teams	Azure AD 客户端密钥
IMAP_HOST	index_email	IMAP 服务器主机名，例如 imap.gmail.com
IMAP_USERNAME	index_email	邮箱地址 / IMAP 登录名
IMAP_PASSWORD	index_email	密码或应用专用密码
IMAP_PORT	index_email	IMAP 端口 — 默认为 993（SSL）
DO_NOT_TRACK	可选	设置为 1 以停用匿名遥测（见下文）
LIVINGDOCS_TELEMETRY	可选	设置为 off 以停用匿名遥测（见下文）

遥测

LivingDocs 会发送少量匿名使用数据，以便我们了解用户完成了哪些设置步骤（安装、启动服务、首次成功建立索引，以及显示升级提示的时间）。每个事件仅包含随机安装 ID、应用版本和操作系统 — 绝不会包含你的代码、文件路径、仓库名称或任何个人数据。

如要选择退出，请设置以下任一环境变量：

DO_NOT_TRACK=1
# or
LIVINGDOCS_TELEMETRY=off

支持的语言

C#、TypeScript、JavaScript、Python、Go

从源代码构建

git clone https://github.com/dinesh-mys/livingdocs
cd livingdocs
make build
make test
make scan REPO=/path/to/your/repo

架构

┌──────────────────────────────────────────────────────────────┐
│                        Interfaces                             │
│  Claude Desktop │ Claude Code │ VS Copilot │ GitHub Webhook  │
└───────┬──────────────────────────────────────┬───────────────┘
        │                                      │
   livingdocs-mcp                    LivingDocs.CopilotExt
   (MCP server)                      /api/github/webhook
        │                            /api/slack/actions
        │                            /api/copilot/chat (SSE)
        └──────────────────┬─────────┘
                    LivingDocs.Core
   ┌────────────────────────┴────────────────────────────────┐
GitScanner  DocExtractor  StaleDocDetector  ClaudeService
GapDetector  DepartureRisk  IndexService  DocWriterService
SlackConnector  TeamsConnector  EmailConnector  ConfluenceService

项目

项目	用途
LivingDocs.Core	共享引擎 — git 扫描、文档提取、过时检测、Claude API、知识缺口 + 离职风险分析、Slack/Teams/Email 连接器、Confluence 同步、组织扫描
LivingDocs.McpServer	CLI + MCP 服务 — 以 LivingDocs.Mcp 名称发布到 NuGet
LivingDocs.CopilotExt	GitHub Webhook 处理程序、Slack 通知 + 审批流程、Copilot Extension SSE 终结点
LivingDocs.Tests	xUnit 测试套件（94 项测试）

反馈与支持

• Bug 报告 → GitHub Issues
• 功能请求 → GitHub Issues
• 问题与想法 → GitHub Discussions

许可证

MIT — 参见 LICENSE。