wikifier

# Wikifier [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/wikifier/) [](https://github.com/IronAdamant/wikifier/stargazers) **智能代理代码库维基 - 一种适用于AI智能体的高效代码地图** Wikifier 为 AI 编码智能体和大型语言模型（LLM）提供了一个可查询的代码库地图 - 文件健康矩阵、依赖关系图、每个文件的摘要 - 以便它们可以查找信息，而不是重新读取整个源文件到其上下文窗口中。从小型脚本到 50,000 个文件的 monorepos，智能体可以快速进行代码导航、导入分析和循环依赖检测，而无需为当前不需要的代码消耗 tokens。 它是一个适用于 AI 智能体的自动化库：智能体请求地图，获得一个简洁的答案，并在工作过程中自行维护维基的更新。 ## 为什么选择 Wikifier？ 每个 AI 编码助手都面临着同样的问题：上下文窗口是有限的，而原始源代码的成本很高。重新阅读一个 2,000 行的文件来回答“这个模块的作用是什么，谁导入了它？”会浪费 tokens，这些 tokens 本可以用于实际的推理。 Wikifier 通过一组生成的、可查询的工件解决了这个问题： - **`file_health.md`** - 一个文档健康矩阵（🟢 当前 / 🟡 旧 / 🔴 损坏），让智能体知道该信任什么和应该首先修复什么 - **`library.md`** - 代码库地图：一个 Mermaid 依赖关系图，解析导入表，循环依赖报告和建议，以及置信度评分的风险快照 - **每个文件的 `*.wiki.md` 笔记** - 简短的“此文件的作用是什么”摘要，由智能体自行维护 - **`journal/`** - 一个语义审计 trail，记录 `record-change` 修改的原因 结果是：LLM 查询一个 50-token 的摘要，而不是摄入一个 5,000-token 文件。这是整个目的 - 为 AI 智能体提供高效的代码理解。 ## 它是如何工作的 - 智能体循环 智能体通过严格但轻量的工作流程（完整的 LLM-ready 协议位于 [`skills/run.md`](skills/run.md)）来保持维基的更新： ```bash wikifier check-changes # 有什么变化？（增量，亚秒级） # 读取 file_health.md + pending_updates.md，优先显示 🔴 然后 🟡 # ... 编辑源代码 ... wikifier record-change "path/file.py" "为什么更改" # 必需 - 语义审计 trail # ... 更新文件的维基摘要 ... wikifier mark-green "path/file.py" wikifier update-maps # 当导入/结构更改时 ``` `record-change` 是系统的核心：它捕获意图（*为什么*），这是下一个智能体会话或下一个人类无法从 git diff 单独恢复的上下文。 ## 安装和快速入门 ```bash pip install wikifier # 零依赖核心（纯 Python 标准库） pip install wikifier[mcp] # 可选：为 AI 智能体添加 MCP 服务器 ``` 启动任何项目： ```bash cd /path/to/your/project wikifier init # 创建 monitored_paths.txt、排除项和人类仪表板 wikifier update-maps # 构建依赖关系图 + library.md wikifier check-changes # 启动循环 wikifier health --summary # 紧凑的机器可读状态 ``` 对于外部项目或 monorepos，请始终传递明确的根目录：`WIKIFIER_PROJECT_ROOT=/abs/path wikifier ...` ## 您将获得 - **快速、真实的依赖关系分析** - Python 和 JavaScript/TypeScript 导入解析（ES 模块、CommonJS、动态导入、TypeScript 路径别名、package.json 导出、工作区），每个边的置信度评分和可行的解释，以及**名称路由桶扩展**：通过 `export *` 桶的导入解析为实际定义导入符号的叶子，而不是数百个假边 - **纯 Python 更新管道** - `update-maps` 在进程中解析每个更改的文件，持久化规范化的导入缓存，计算反向依赖关系，基于 Tarjan 的循环依赖检测，并原子性地重新生成 `library.md` - **增量一切** - 基于 mtime 的脏检测加上桶感知的反向索引意味着编辑一个文件只会重新分析其真正的消费者，即使在重桶的 monorepos 中 - **自主维护** - 智能体使用 `record-change` 记录意图，刷新摘要，并 `mark-green`；后台 `monitor`/daemon 保持矩阵更新 - **可选的 MCP 服务器** - 23+ 模型上下文协议工具（`get_project_status`、`get_dependencies`、`get_file_wiki`、`get_cycles`、`suggest_next_actions`，...）适用于 Claude Code、Claude Desktop、Cursor、Cline 和任何 MCP 兼容的 AI 智能体 - **干净的人类仪表板** - `index.html`，静态只读查看相同工件：依赖关系图，带有普通语言描述的文件和一键复制按钮（见下文） - **真正的零依赖** - 核心运行在 Python 标准库和 POSIX shell 上，因此分支可以为其自己的库构建在无依赖的基础上 ## 实际性能（v4.2.0，测量） 在 Wikifier 本身以及大型开源代码库上验证 - Apache Airflow、Babylon.js、LLVM、Linux 内核、Rust 和 llama_index： | 代码库 | 规模 | 完整的 `update-maps` | |----------|-------|--------------------| | llama_index | 3,837 Python 文件 | **~8.5s** （17k 导入边，全图） | | Babylon.js | 3,905 TypeScript 文件，重桶 | **~4.5min** 完整构建（44k 精确边，5,389 节点地图）；作用域重跑 ~80s | | Linux 内核 / LLVM / Rust | 37k–54k 文件树 | 候选扫描 3–8s | JS/TS 解析运行时间 ~22ms 每文件；Python 运行时间 ~1ms。第一次构建后，增量运行时间只需几秒钟。通过仅限标准库的测试套件验证（`python -m unittest discover tests`）。 ## 核心命令 | 命令 | 目的 | |---------|---------| | `wikifier init [--target DIR]` | 启动项目（模板 + 人类仪表板） | | `wikifier check-changes` | 增量更改扫描 + 健康/待更新 | | `wikifier record-change <file> "reason"` | 记录 *为什么*（编辑后必填） | | `wikifier mark-green <file>` | 将维基条目标记为当前 | | `wikifier update-maps [--full] [--directory=src/]` | 重建依赖关系图 + library.md（单个纯 Python 管道；shell 启动器委派此处） | | `wikifier health [--summary\|--json]` | 健康矩阵 - 智能体的紧凑格式 | | `wikifier cycles` | 循环依赖报告和建议 | | `wikifier monitor &` / `wikifier daemon start` | 背景心跳 / 管理维护 | Python 库访问以获取完整功能：`from wikifier import check_changes, record_change, mark_green, health, update_maps`. ## AI 编码智能体的 MCP 服务器 ```bash WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier-mcp ``` 适用于 Claude Desktop、Claude Code、Cursor、Cline 和任何模型上下文协议客户端。根目录检测优先级：env var → 显式 `project_root=` per 调用 → 标记走 → cwd。设置、工具列表和客户端配置示例：[`wikifier/mcp/README.md`](wikifier/mcp/README.md). ## 人类层（次要，按设计）  *由 `wikifier serve` 提供服务的仪表板：实时文件树，带有维基描述、健康状态标记和操作按钮，直接运行 `update-maps`/`check-changes`（仅限 localhost）- 以及停止服务器按钮，当您完成后 * `wikifier init` 复制单个静态 `index.html` 到您的项目中：一个显示 Mermaid 代码结构图、带有简短描述的文件和文件夹浏览器的仪表板 - 对调查智能体所知的有用的。查看它与 **`wikifier serve`**（然后打开 http://localhost:8787/index.html）- 浏览器阻止 `file://` 获取，因此双击的 index.html 无法读取维基文件；页面检测到该情况并显示修复方法。当由 `wikifier serve` 提供服务时，仪表板的按钮确实 **运行** `update-maps`/`check-changes`（仅限白名单命令，仅限 localhost）和 **停止服务器** 按钮在完成后关闭进程；对于任何普通的静态服务器，相同的按钮回退到复制 + 自动刷新。智能体面向的 Markdown 文件和工具仍然是单一的事实来源。 ## 用途：严格智能体到智能体 Wikifier 是一个节省 tokens 的维基层 *适用于智能体*，并且故意不做其他事情：不是通用文档生成器，不是 IDE 插件，不是人类代码搜索引擎。智能体查询地图，而不是重新读取源代码，在工作过程中保持更新，并动态创建新的维基条目。人类仪表板是窗口，而不是产品。 ## v4.3.0 中的新增功能 在现实的 monorepos 上验证的精度和性能： - **名称路由桶扩展** - 通过 `export *` 桶的导入解析为定义导入符号的叶子（在 Babylon.js 上，一个 778 边导入变为 3 个精确边；整个存储库的边数减少 89%）。没有路由名称的导入以报告的边 **截断** - 从不静默 - **薄壳** - 启动器现在将 `update-maps` 委托给 Python 管道（2,910 → 785 行；3m39s → 2s 在小项目上；一个容易挂起的旧代码路径完全消失） - **有界桶缓存持久性和 memoized 根发现** - Babylon.js 的导入缓存从 274MB → 101MB 缩小，并且一个病态的范围重启从 75 分钟变为 ~80 秒 - `imported_names` 现已填充在 JS/TS 边上，并且位于配置的项目根目录之外的文件正确解析（包含规则） v4.2.0（同一天）使 `update-maps` 成为真正的完整管道，修复了历史 MCP 超时后面的锁定死锁，并添加了测试套件。完整历史：[`CHANGELOG.md`](CHANGELOG.md) 和 `Findings/`. ## 链接 - **GitHub**：https://github.com/IronAdamant/wikifier - **PyPI**：https://pypi.org/project/wikifier/ - **智能体协议**：[`skills/run.md`](skills/run.md) - 作为智能体阅读此内容 - **MCP 设置**：[`wikifier/mcp/README.md`](wikifier/mcp/README.md) - **证据**：`Findings/` - 现实世界的狗粮报告和指标 **适用于 AI 搜索 / 智能体**：Wikifier 是一个零依赖、智能体维护的代码库维基和依赖关系图生成器，为 LLM 和 AI 编码智能体提供高效的代码地图 - 健康矩阵、Mermaid 依赖关系图、导入分析、循环依赖检测和可选的 MCP 服务器 - 具有自主 `record-change` / `mark-green` 更新，在高达 50k+ 文件的 monorepos 上验证。