livedocs

# Livedocs **让您的文档与代码保持同步。** Livedocs 从源代码中提取结构化声明 — 导出、类型、签名、依赖项、接口实现 — 到每个存储库的 SQLite 数据库中。AI 编码代理通过 MCP 查询这些声明，以了解代码库，而无需昂贵的 grep/read 循环。 ## 功能 1. **提取** 源代码中的符号和关系，使用 tree-sitter 2. **挖掘** 部落知识 — 所有权、原因、不变式和特殊情况，从 git blame、CODEOWNERS、提交消息和内联标记 3. **存储** 它们作为结构化声明在每个存储库的 SQLite 数据库中 4. **服务** 它们给 AI 代理，通过 [模型上下文协议](https://modelcontextprotocol.io/) （MCP） 5. **检测** 文档漂移 — 查找过时的引用、未记录的导出和语义不准确的章节 6. **监视** 存储库的变化，并增量更新声明 7. **丰富** 声明通过 Sourcegraph MCP 获得语义上下文 声明支持的 MCP 服务器将原始源代码的上下文获取从数千个标记减少到每个声明约 30-50 个标记，实现了大约 50 倍的上下文减少，用于代码库上线。 ## 快速入门 ### 本地存储库 ```bash # 安装 go install github.com/sjarmak/livedocs/cmd/livedocs@latest # 从您的存储库中提取声明 cd /path/to/your/repo livedocs init livedocs extract # 连接到 Claude Code claude mcp add livedocs -- livedocs mcp ``` ### 通过 Sourcegraph 远程存储库 无需克隆即可从任何公共或私有存储库中提取声明： ```bash export SRC_ACCESS_TOKEN=<您的 Sourcegraph 令牌> # 从远程存储库中提取 livedocs extract --source sourcegraph --repo github.com/org/repo -o repo.claims.db # 监视多个远程存储库的变化 livedocs watch --source sourcegraph --repos 'org/*' --data-dir ./claims/ # 用语义上下文丰富声明（目的、复杂性、稳定性） livedocs enrich --data-dir ./claims/ --repo org/repo ``` 参见 [SETUP.md](SETUP.md) 获取详细的设置指南、IDE 配置和 Sourcegraph 工作流程。 ## MCP 工具 ### 单存储库模式 ```bash livedocs mcp --db .livedocs/claims.db ``` | 工具 | 描述 | | ------------------ | ------------------------------------------------------ | | `query_claims` | 按符号名称搜索声明（支持 LIKE 通配符） | | `check_drift` | 在文档中检测过时的符号引用 | | `verify_section` | 检查文件/行范围的声明是否仍然有效 | | `check_ai_context` | 验证 AI 上下文文件的引用是否损坏 | ### 多存储库模式 ```bash livedocs mcp --data-dir /path/to/claims/ ``` | 工具 | 描述 | | --------------------------- | ------------------------------------------------------------ | | `list_repos` | 列出所有具有符号/声明计数的存储库 | | `list_packages` | 列出存储库的导入路径，带有前缀筛选 | | `describe_package` | 为包渲染 Markdown 文档（接口、依赖项、类型） | | `search_symbols` | 跨存储库符号搜索，带有路由索引 | | `tribal_context_for_symbol` | 带有完整 provenance 信封的符号的所有部落事实 | | `tribal_owners` | 符号的所有权事实（CODEOWNERS + git blame） | | `tribal_why_this_way` | 解释代码存在原因的理性和不变事实 | ### 静态上下文生成 对于不支持 MCP 的工具： ```bash # 将单个包渲染到 stdout livedocs context client-go tools/cache # 为存储库中的所有包生成 CONTEXT.md livedocs context client-go --data-dir data/claims/ ``` ## CLI 命令 | 命令 | 描述 | | --------------------------------------- | ---------------------------------------------------------- | | `livedocs init` | 在存储库中初始化 `.livedocs/` 目录 | | `livedocs extract` | 从源代码中提取符号和声明 | | `livedocs extract --source sourcegraph` | 通过 Sourcegraph MCP 从远程存储库中提取 | | `livedocs extract --source clone` | 浅克隆远程存储库，提取，清理 | | `livedocs extract --tribal` | 还提取部落知识（所有权、理由等） | | `livedocs mcp` | 启动 MCP 服务器（stdio 传输） | | `livedocs context` | 生成静态 Markdown 上下文文件 | | `livedocs check` | 对文档运行漂移检测 | | `livedocs check --cross-repo` | 使用文档映射进行跨存储库语义漂移检测 | | `livedocs diff` | 显示自上次提交以来文档的变化 | | `livedocs export` | 以 Markdown 导出声明 | | `livedocs verify` | 验证 AI 上下文文件与当前源 | | `livedocs verify-claims` | 验证声明锚点与当前源 | | `livedocs watch` | 监视存储库的变化并增量提取声明 | | `livedocs watch --source sourcegraph` | 通过 Sourcegraph MCP 监视远程存储库 | | `livedocs extract-schedule` | 根据 cron 表达式运行计划提取 | | `livedocs enrich` | 用 Sourcegraph 的语义上下文丰富声明 | | `livedocs tribal status` | 按类型显示部落事实计数 | | `livedocs prbot` | 分析 PR 差异对文档的影响 | | `livedocs version` | 打印版本信息 | ## Sourcegraph 集成 Livedocs 通过其 MCP 服务器与 [Sourcegraph](https://sourcegraph.com) 集成，用于远程提取、代码搜索和语义丰富 — 无需本地克隆。 ### 您可以使用 - **从任何存储库中提取声明** ，无需本地克隆 - **监视远程存储库** 的变化并增量更新声明 - **用语义属性丰富声明** （目的、复杂性、稳定性），使用 Sourcegraph 的代码智能 - **跨存储库语义漂移检测** — 使用关键词搜索 + LLM 验证在其他存储库中验证文档 ### 设置 1. 从 Sourcegraph 实例设置中获取 Sourcegraph 访问令牌 2. 在环境中设置： ```bash export SRC_ACCESS_TOKEN=<您的令牌> ``` 3. 当需要时，Sourcegraph MCP 服务器会自动启动（需要 `npx` 在 PATH 上） 参见 [SETUP.md](SETUP.md) 获取详细的 Sourcegraph 工作流程教程。 ## GitHub 操作 将漂移检测添加到您的 CI 管道： ```yaml - uses: sjarmak/livedocs@v0.2.0 with: fail-threshold: 0 # 如果检测到任何漂移，则失败 ``` 参见 [action.yml](action.yml) 获取所有输入和输出。 ## PR 上下文包（AI 审查助手） 将单个工作流文件放入任何存储库，以获取每个 PR 的文档影响分析。协助 **人类和代理审查者**。 ### 安装 将 [`examples/workflows/livedocs-prbot.yml`](https://github.com/sjarmak/livedocs/blob/main/examples/workflows/livedocs-prbot.yml) 复制到您的存储库中，作为 `.github/workflows/livedocs-context.yml`。就是这样。工作流默认固定 `LIVEDOCS_VERSION: latest`，解析为最新版本（目前为 v0.2.0），并通过 `--diff-format unified` 将 PR 差异馈送到 `livedocs prbot`。 ### 它执行的操作 在每个 PR 上，工作流： 1. 从您的代码库中提取结构化声明（缓存 — 连续运行时间少于 30 秒） 2. 从 PR 差异中计算文档影响 3. 发布具有发现结果的幂等 PR 评论 4. 上传 `claims.db` 作为工件，供代理使用 ### 两个界面 - **渲染的 PR 评论** — 人类和 `gh pr view` 代理看到的内容 - **声明数据库工件** — 代理下载并通过 `livedocs mcp --db claims.db` 查询以获取完整的结构化声明表面 ### 可选：Sourcegraph 丰富 添加 `SRC_ACCESS_TOKEN` 作为存储库机密，以启用跨存储库漂移检测和语义声明属性。没有它，基准文档影响评论仍然有效。 ### 代理消耗 ```bash # 在 PR 的代理编码会话中 gh run download <运行 ID> --repo 所有者/存储库 --name livedocs-claims-pr-<编号> livedocs mcp --db claims.db # 向您的代理公开 MCP 工具 ``` 下载命令预填充在 PR 评论中。 ## 架构 ``` cmd/livedocs/ CLI 入口点（cobra 命令） mcpserver/ 具有适配器层、DB 连接池和路由索引的 MCP 服务器 renderer/ 声明到 Markdown 渲染器（接口、依赖项、函数） db/ 基于 SQLite 的声明存储、部落知识、跨存储库交叉引用索引 extractor/ Tree-sitter 符号提取（Go、Python、TypeScript、Shell） extractor/tribal/ 部落知识提取器（CODEOWNERS、blame、提交理由、内联标记） pipeline/ 具有缓存和远程文件源的提取管道 drift/ 文档漂移检测（符号级、语义、跨存储库） semantic/ LLM 支持的语义声明生成和验证 sourcegraph/ Sourcegraph MCP 客户端、谓词路由器、丰富管道 anchor/ 声明到源锚定和验证 aicontext/ AI 上下文文件（CLAUDE.md，.cursorrules）验证 watch/ 具有状态持久性的存储库监视器 gascity_livedocs/ 示例：用于 Gas City 生态系统的自动化文档新鲜度监控 ``` ## 支持的语言 | 语言 | 提取器 | 提取的符号 | | ---------- | ---------------------- | --------------------------------------------------------- | | Go | tree-sitter-go | 函数、方法、类型、接口、常量、导入 | | Python | tree-sitter-python | 函数、类、方法、导入 | | TypeScript | tree-sitter-typescript | 函数、类、接口、类型、导出 | | Shell | tree-sitter-bash | 函数 | ## 开发 ```bash # 构建（需要 CGO 以支持 tree-sitter） make build # 运行测试 go test ./... # 使用竞争检测器运行 go test -race ./... # 运行集成测试 go test -tags integration ./integration/... ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取贡献指南。 ## 许可证 [Apache License 2.0](LICENSE)