codewiki-plus 5.1.0__tar.gz

codewiki_plus-5.1.0/PKG-INFO

@@ -0,0 +1,887 @@
+Metadata-Version: 2.4
+Name: codewiki-plus
+Version: 5.1.0
+Summary: Transform codebases into comprehensive documentation using AI-powered analysis
+Author: CodeWiki Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/mambo-wang/CodeWiki-Plus
+Project-URL: Documentation, https://github.com/mambo-wang/CodeWiki-Plus/blob/main/README.md
+Project-URL: Repository, https://github.com/mambo-wang/CodeWiki-Plus
+Project-URL: Issues, https://github.com/mambo-wang/CodeWiki-Plus/issues
+Keywords: documentation,code-analysis,ai,llm,developer-tools,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: GitPython>=3.1.40
+Requires-Dist: Jinja2>=3.1.6
+Requires-Dist: tree-sitter>=0.23.2
+Requires-Dist: tree-sitter-language-pack>=0.8.0
+Requires-Dist: tree-sitter-python>=0.23.6
+Requires-Dist: tree-sitter-java>=0.23.5
+Requires-Dist: tree-sitter-javascript>=0.21.4
+Requires-Dist: tree-sitter-typescript>=0.21.2
+Requires-Dist: tree-sitter-c>=0.21.4
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Requires-Dist: tree-sitter-c-sharp>=0.23.1
+Requires-Dist: tree-sitter-php>=0.23.0
+Requires-Dist: tree-sitter-kotlin>=1.1.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: openai>=1.107.0
+Requires-Dist: litellm>=1.77.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic-ai>=1.0.6
+Requires-Dist: requests>=2.32.4
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: rich>=14.1.0
+Requires-Dist: networkx>=3.5
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: mermaid-parser-py>=0.0.2
+Requires-Dist: mermaid-py>=0.8.0
+Requires-Dist: fastapi>=0.116.0
+Requires-Dist: uvicorn>=0.35.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: logfire>=4.1.0
+Requires-Dist: coding-agent-wrapper>=0.1.2
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: jieba>=0.42.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+<p align="center">
+  <img src="img/logo-banner.png" alt="CodeWiki-Plus" width="700" />
+</p>
+
+<h1 align="center">CodeWiki-Plus</h1>
+
+<p align="center">
+  <strong>用 AI IDE 驱动的代码仓库文档生成与知识管理工具</strong><br>
+  <strong>AI IDE-Driven Code Documentation Generator & Knowledge Engine</strong>
+</p>
+
+<p align="center">
+  <a href="https://python.org/"><img alt="Python version" src="https://img.shields.io/badge/python-3.12+-blue?style=flat-square" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" /></a>
+  <a href="https://github.com/FSoft-AI4Code/CodeWiki"><img alt="Upstream: CodeWiki" src="https://img.shields.io/badge/upstream-FSoft--AI4Code%2FCodeWiki-orange?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="#zh"><strong>中文</strong></a> | <a href="#en"><strong>English</strong></a>
+</p>
+
+---
+
+<a id="zh"></a>
+
+## 中文
+
+### 这个项目是什么？
+
+CodeWiki-Plus 是 [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki) 的增强分支，核心改动是**让 CodeWiki 无需配置任何大模型 API，直接由 AI IDE（CodeBuddy、Cursor、Claude Desktop 等）自身的模型驱动 Wiki 文档生成**，并在此基础上构建了完整的知识管理引擎。
+
+### 为什么要做这个改造？
+
+原版 CodeWiki 是一个非常优秀的仓库级文档生成框架，它通过 Tree-sitter AST 解析、依赖图构建、拓扑排序等工具链实现高质量的代码文档生成。但它有一个使用门槛：**必须自行配置 LLM API**（申请 API Key、选择 provider、处理模型兼容性），且整个生成过程是黑盒的，用户无法中途干预。
+
+实际上，CodeWiki 的核心工具链——AST 解析、依赖图、Mermaid 校验——完全不需要 LLM。真正需要 LLM 智能的 4 个环节（模块聚类、文档撰写、子模块递归、总览合成），恰好是 AI IDE 的 Agent 最擅长做的事情。
+
+因此，我们将 CodeWiki 的 MCP Server 从"黑盒式一键生成"拆分为**23 个细粒度工具**，让它退化为纯工具链服务器。AI IDE 的 Agent 通过 MCP 协议调用这些工具，用自己的推理能力完成全部文档生成工作：
+
+```
+改造前：
+  IDE → generate_docs(repo) → [CodeWiki 内部调用 LLM API] → 结果
+
+改造后：
+  IDE Agent → analyze_repo → read_code → (Agent 自己推理) → write_doc → overview
+              ↑ 纯工具       ↑ 纯工具    ↑ IDE 自身模型      ↑ 纯工具
+```
+
+### 相比原版 CodeWiki 的增强
+
+| 能力维度 | 原版 CodeWiki | CodeWiki-Plus |
+|----------|--------------|---------------|
+| LLM 配置 | 必须自行配置 API Key | 零配置，IDE 自身模型驱动 |
+| 生成模式 | 黑盒一键生成 | 23 个细粒度工具，Agent 全程可控 |
+| 文档质量 | 通用描述 | Evidence-Based 断言（代码引用 + 置信度） |
+| 生成效率 | 所有组件同等处理 | 代码路由分类，boilerplate 仅保留签名 |
+| 上下文精度 | 模块内组件 | BFS 1-hop 调用图扩展 + 约束索引表 |
+| 增量更新 | 文件级 Git diff | 方法级 content_hash 精确检测 |
+| 知识管理 | 无 | 结构化 Wiki + 笔记飞轮 + 外部文档管理 |
+| 搜索能力 | 无 | BM25 + wikilink 图谱多跳 + 渐进式阅读 |
+| 跨服务分析 | 无 | Monorepo 子服务检测 + 跨服务调用追踪 |
+| 质量保障 | 无 | 11 项 lint 检查 + health score + 问题追踪 |
+
+### 前置条件
+
+- **Python 3.12+**
+- **Node.js**（用于 Mermaid 图表校验，不安装则图表校验会静默跳过）
+- 一个支持 MCP 的 AI IDE（CodeBuddy、Cursor、Claude Desktop 等）
+
+### 快速开始（以 CodeBuddy 为例）
+
+整个过程只需 3 步，不需要任何 API Key。
+
+**第 1 步：安装 CodeWiki-Plus**
+
+```bash
+git clone https://github.com/mambo-wang/CodeWiki-Plus.git
+cd CodeWiki-Plus
+pip install -e .
+```
+
+验证安装：
+
+```bash
+python -c "from codewiki.mcp.server import server; print('MCP Server OK')"
+```
+
+**第 2 步：配置 MCP Server**
+
+在 CodeBuddy 的 MCP 设置中添加以下配置（通常在设置界面的"工具"或"MCP"板块）：
+
+```json
+{
+  "mcpServers": {
+    "codewiki": {
+      "command": "python",
+      "args": ["-m", "codewiki.mcp.server"],
+      "timeout": 36000000
+    }
+  }
+}
+```
+
+配置完成后，CodeBuddy 的 MCP 工具列表中应出现 `codewiki` 相关的 23 个工具。
+
+**第 3 步：在 Agent 模式中输入提示词**
+
+打开 CodeBuddy 的 Agent 模式，用 CodeBuddy 打开你要生成文档的目标项目，然后输入：
+
+```
+帮我分析当前仓库并生成 Wiki 文档，输出到 repowiki 目录。请使用中文撰写文档。
+```
+
+Agent 会自动按照以下流程工作：
+
+```
+阶段 1: 调用 analyze_repo → 得到组件索引、叶节点列表
+        （自动检测 monorepo 子服务，构建跨服务调用关系）
+  ↓
+阶段 2: 调用 get_prompt("cluster") 获取聚类规则
+        调用 read_code_components 阅读源码
+        自主推理，将组件分组为 3-8 个逻辑模块
+        调用 save_module_tree 保存聚类结果
+  ↓
+阶段 3: 按叶优先顺序逐模块生成文档
+        每个叶模块：read_code → 分析推理 → write_doc_file
+        （prompt 自动注入 BFS 调用上下文 + 约束索引表 + 业务规则提取指令）
+        每个父模块：读取子文档 → 合成总览 → write_doc_file
+  ↓
+阶段 4: 生成仓库总览 overview.md
+  ↓
+阶段 5: 调用 close_session 释放资源，构建搜索索引
+```
+
+生成的文档结构：
+
+```
+repowiki/
+├── wiki/                        # LLM Wiki 结构化知识库
+│   ├── overview.md              #   仓库总览（从这里开始阅读）
+│   ├── index.md                 #   自动生成的文档目录索引（按类型分区）
+│   ├── log.md                   #   操作日志（记录每次写入/编辑）
+│   ├── schema.yaml              #   项目文档规范（含 page_types 路由表 + 代码路由规则）
+│   ├── purpose.md               #   项目用途说明（可选，增强搜索相关性）
+│   ├── modules/                 #   模块文档（含组件约束索引表 + Evidence-Based 断言）
+│   │   ├── module1.md
+│   │   └── module2.md
+│   ├── entities/                #   实体页面（类、接口、数据库表等）
+│   ├── concepts/                #   概念页面（设计模式、业务概念等）
+│   ├── sources/                 #   外部文档摘要（第三方文档导入）
+│   ├── comparisons/             #   对比分析页面
+│   └── queries/                 #   研究查询页面
+├── raw/
+│   └── sources/                 #   第三方文档原始文件
+├── notes/                       # 开发知识笔记（支持 candidate→confirmed→rejected 状态流转）
+│   ├── decision-xxx.md          #   架构决策记录
+│   ├── pitfall-xxx.md           #   踩坑记录
+│   ├── workaround-xxx.md        #   临时方案
+│   └── ...
+├── .meta/
+│   ├── project.json             #   项目映射（repo_path/output_dir/cache_db 路径）
+│   ├── symbol_map.json          #   符号→源文件映射（SQLite 主存储的 JSON 兼容副本）
+│   ├── issues.json              #   质量问题追踪（health score 依据）
+│   ├── source_registry.json     #   外部文档注册表
+│   ├── cross_service_links.json #   跨服务调用拓扑（monorepo）
+│   └── overview_refs.json       #   overview 引用模块列表（精确 stale 判定）
+├── module_tree.json             # 模块层级结构
+├── first_module_tree.json       # 初始聚类结果
+└── metadata.json                # 生成元数据
+```
+
+### MCP 工具速查
+
+所有工具均不需要 LLM 配置，由 IDE Agent 通过 MCP 协议调用。MCP Server 内置 **instructions**（能力概览与工作流指南）、**7 个 Prompt 模板**（generate-wiki / extract-knowledge / search-wiki / quality-check / incremental-update / workspace-analysis / cross-service-trace）和 **6 个 Resource**（wiki-catalog / module-tree / index-status 等）。
+
+**代码分析（6 个）：**
+
+| 工具 | 用途 |
+|------|------|
+| `analyze_repo` | 分析仓库，构建依赖图，返回组件索引；支持 SHA256 增量 + 方法级 content_hash 精确检测；自动检测 monorepo 子服务 |
+| `analyze_workspace` | 扫描多仓库工作区，为每个子仓库独立生成 Wiki，顶层生成跨服务总览 |
+| `list_components` | 组件索引查询，支持摘要模式和前缀过滤 |
+| `list_dependencies` | 查询组件/模块依赖关系，支持分页、方向过滤、高影响力组件排名 |
+| `read_code_components` | 根据组件 ID 读取源码 |
+| `view_repo_file` | 查看仓库原始源文件内容，支持行范围截取 |
+
+**文档生成管线（6 个）：**
+
+| 工具 | 用途 |
+|------|------|
+| `write_doc_file` | 创建 .md 文档（自动 Mermaid 校验 + 交叉链接注入 + page_type 路由）；支持无 session 模式 |
+| `edit_doc_file` | 编辑文档（替换/插入/撤销） |
+| `save_module_tree` | 保存模块聚类结果 |
+| `get_processing_order` | 获取叶优先的文档生成顺序 |
+| `get_prompt` | 获取各阶段的提示词模板（含 16 种 prompt_type） |
+| `close_session` | 关闭会话释放资源，构建 BM25 索引 + wikilink 图谱，写入生成元数据 |
+
+**知识管理（7 个）：**
+
+| 工具 | 用途 |
+|------|------|
+| `query_wiki` | BM25 全文搜索 + wikilink 图谱多跳扩展 + **渐进式阅读**（mode=overview/directory/detail）；返回 source_type 标注 |
+| `ingest_note` | 将开发笔记归档到 notes/，支持 8 种类型 + aliases + source_ref；默认写入为 candidate 状态 |
+| `confirm_note` | 将 candidate 笔记升级为 confirmed（正式领域知识） |
+| `reject_note` | 否决 candidate 笔记，后续 query_wiki 不再返回 |
+| `ingest_source` | 导入第三方文档到 `raw/sources/`，注册到 `source_registry.json` |
+| `retract_source` | 撤回已导入的外部文档（flag_stale / remove_refs 两种模式） |
+| `batch_ingest` | 批量导入：一次调用处理多个笔记/文档 |
+
+**质量保障（2 个）：**
+
+| 工具 | 用途 |
+|------|------|
+| `lint_wiki` | 文档-代码一致性检查：**11 项检查**（含 unsupported_claims 无证据断言检测） |
+| `flag_issue` | 标记 Wiki 质量问题，驱动 health score 计算 |
+
+**跨服务分析（1 个）：**
+
+| 工具 | 用途 |
+|------|------|
+| `query_cross_service` | 查询跨服务调用关系（HTTP + MQ），支持 by_service / by_method / by_path / trace 过滤 |
+
+> 另有 2 个遗留工具（`generate_docs`、`get_module_tree`）保留向后兼容，需先通过 `codewiki config set` 配置 LLM API。
+
+### 文档生成质量增强
+
+CodeWiki-Plus 在 Prompt 层和引擎层做了系统性优化，显著提升生成文档的精度和效率。
+
+#### Evidence-Based 业务断言
+
+生成模块文档时，Prompt 要求 LLM 对每条业务规则提供代码证据：
+
+```markdown
+### 业务规则
+
+- **订单金额不可为负** [confidence: 0.95]
+  > evidence: `OrderService.java:L142` — `if (amount < 0) throw new BizException(...)`
+  > reason: 创建订单时强制校验金额非负
+```
+
+`lint_wiki` 新增 `unsupported_claims` 检查：当页面中超过 30% 的业务断言缺少 evidence 时报告警告，帮助识别潜在的 LLM 幻觉。
+
+#### 组件约束索引表
+
+每个模块文档自动生成结构化的约束索引表，方便 LLM 消费者快速定位：
+
+```markdown
+### Component Constraint Index
+
+| Component | Type | Key Constraints | Dependencies |
+|-----------|------|-----------------|--------------|
+| OrderService | business | 金额校验、状态机流转 | PaymentClient, OrderRepo |
+| OrderDTO | boilerplate | 字段映射 | — |
+```
+
+#### 代码路由分类
+
+`analyze_repo` 阶段自动将组件分为三类，差异化处理：
+
+| 分类 | 典型组件 | 处理方式 |
+|------|----------|----------|
+| `business` | Service, Controller, Job, Handler | 完整源码注入 LLM，生成详细文档 |
+| `boilerplate` | DTO, VO, Entity, Config, Mapper | 仅注入签名 + 字段列表，模板化输出 |
+| `infra` | Util, Helper, Factory, Interceptor | 摘要级描述 |
+
+典型 Java/Spring 仓库可减少 30%+ 的 LLM token 消耗。用户可在 `schema.yaml` 的 `code_routing` 配置节自定义分类规则。
+
+#### BFS 调用图上下文
+
+文档生成 Prompt 中自动注入 1-hop 调用上下文（`<CALL_CONTEXT>` 块），为每个核心组件附带直接调用者/被调用者的签名摘要，帮助 LLM 理解跨模块关系：
+
+```
+<CALL_CONTEXT>
+## Neighbors of OrderService.createOrder
+- [caller] PaymentController.initiatePayment(PaymentRequest req)
+- [callee] InventoryClient.deductStock(String skuId, int qty)
+</CALL_CONTEXT>
+```
+
+### 增量更新
+
+`analyze_repo` 内置三层增量优化：
+
+**变更检测**：首次生成后再次调用时，自动比对上次生成状态：
+
+- **Git 策略（优先）**：通过 `git diff` 比对当前 HEAD 与上次生成时的 commit，识别变更文件
+- **SHA256 指纹策略（回退）**：通过文件内容哈希（前 64KB）+ mtime 双重检测变更
+
+**方法级精确检测**：文件变更后，逐组件比较 `content_hash`（SHA256 前 16 位），只有真正变化的方法/类才被标记为 stale。`get_stale_components()` 返回 added / modified / deleted 三类变更列表，支持级联失效关联的 Wiki 页面。
+
+**选择性重解析**：仅重新解析变更文件，未变更文件的组件直接从 SQLite 缓存加载合并。`skip_file_paths` 参数贯穿全链路（DependencyGraphBuilder → DependencyParser → AnalysisService → CallGraphAnalyzer）。
+
+**Overview stale 精确判定**：通过解析 overview.md 中的链接提取引用模块列表（持久化到 `.meta/overview_refs.json`），只有当 overview 实际引用了受影响模块时才标记为 stale。
+
+### Monorepo 跨服务分析
+
+`analyze_repo` 自动检测 monorepo 中的子服务（5 阶段启发式：docker-compose → Dockerfile → 构建清单 → 约定目录 → Spring Boot），为每个子服务分配独立标签，在依赖图上运行 CrossServiceMatcher 识别 HTTP/MQ 跨服务调用关系。
+
+```
+检测流程：
+  docker-compose.yml 服务定义
+  → Dockerfile 构建目标
+  → pom.xml / build.gradle / package.json 构建清单
+  → src/main, app/, cmd/ 等约定目录
+  → Spring Boot @SpringBootApplication 入口
+
+输出：
+  .meta/cross_service_links.json  — 跨服务调用拓扑
+  query_cross_service 工具可按 service/method/path/trace 维度查询
+```
+
+### 知识飞轮
+
+笔记系统引入 candidate → confirmed → rejected 状态流转，确保 LLM 自动沉淀的知识经过研发确认：
+
+```
+LLM 发现跨功能约束
+  → ingest_note(status=candidate) 写入 notes/
+  → query_wiki 返回时标注 [unconfirmed]
+  → 研发确认：confirm_note → 升级为正式知识
+  → 研发否决：reject_note → 不再被搜索返回（保留记录）
+```
+
+### 渐进式阅读协议
+
+`query_wiki` 支持三种消费模式，让 Agent 按需逐层深入，避免一次性加载过多内容：
+
+| mode | 返回内容 | 适用场景 |
+|------|----------|----------|
+| `overview` | 仓库级摘要（< 500 token） | Agent 初次接触项目，快速了解全貌 |
+| `directory` | 按类型分区的页面目录（< 800 token） | 定位目标模块/实体 |
+| `detail` | 指定页面完整内容 | 深入阅读特定文档 |
+| 默认 | BM25 snippet 搜索结果 | 关键词检索 |
+
+```
+Agent 消费路径：
+  query_wiki(mode=overview) → 了解项目
+  → query_wiki(mode=directory) → 找到目标页面
+  → query_wiki(query="xxx", expand=true) → 深入阅读
+```
+
+### 存储架构
+
+CodeWiki-Plus 采用 **SQLite 主存储 + JSON 兼容副本** 的双层架构：
+
+**SQLite（`{repo}/.codewiki/analysis_cache.db`）**：组件索引（含 content_hash）、文件指纹、依赖关系、BM25 搜索索引（token 级倒排）、符号映射（symbol_map）、路由表均存储在 SQLite 中，支持高效查询和增量更新。
+
+**JSON 兼容副本（`output_dir/.meta/`）**：`symbol_map.json`、`module_tree.json` 等保留精简 JSON 副本，供外部工具直接读取。
+
+**持久化项目映射（`.meta/project.json`）**：`analyze_repo` 执行后自动写入 `repo_path`、`output_dir`、`cache_db` 的绝对路径映射。这使得 `query_wiki`、`ingest_note` 等知识管理工具在**无活跃 session** 时也能通过 `project.json` 定位 SQLite 数据库，走 BM25 索引搜索。
+
+```
+搜索路径优先级：
+  活跃 session.cache → .meta/project.json → cache_db → SQLite BM25
+                     ↘ 回退：output_dir.parent/.codewiki/analysis_cache.db
+                     ↘ 最终回退：.meta/search_index.json（全量遍历）
+```
+
+### LLM Wiki 知识系统
+
+除了文档生成，CodeWiki-Plus 还内置了 LLM Wiki 知识管理能力，让生成出的 Wiki 持续演进为项目的活知识库。
+
+#### 结构化知识库布局
+
+所有 Wiki 内容按页面类型（page type）组织在 `wiki/` 子目录下，由 `page_router.py` 统一路由：
+
+| 页面类型 | 目录 | 说明 |
+|----------|------|------|
+| `module` | `wiki/modules/` | 模块文档（含约束索引表 + Evidence-Based 断言） |
+| `entity` | `wiki/entities/` | 实体页面：类、接口、数据库表、配置项等 |
+| `concept` | `wiki/concepts/` | 概念页面：设计模式、业务概念、架构风格等 |
+| `source` | `wiki/sources/` | 外部文档摘要：导入的第三方文档 |
+| `comparison` | `wiki/comparisons/` | 对比分析：技术选型、方案比较等 |
+| `query` | `wiki/queries/` | 研究查询：调研结论、问题排查记录等 |
+
+`write_doc_file` 工具的 `page_type` 参数指定类型即可自动路由到正确目录。
+
+#### schema.yaml 与配置
+
+`schema.yaml` 是项目的文档"宪法"，包含命名规范、必需章节、文档维度、lint 设置、**page_types 路由表**、以及 **code_routing 代码路由规则**。`config.yaml`（CodeWiki-Plus 安装目录下）提供与语言无关的默认配置，首次 `analyze_repo` 时会读取它生成项目级 `schema.yaml`。
+
+**自定义**：修改 CodeWiki-Plus 的 `config.yaml` 改变全局默认值；修改某个项目的 `schema.yaml` 只影响该项目（增量更新时自动合并保留自定义字段）。
+
+#### 交叉链接与别名
+
+- **交叉链接注入**：`write_doc_file` 根据组件级依赖关系自动在文档末尾注入"相关模块"章节（Depends on / Used by），通过 `schema.yaml` 中的 `auto_crosslink` 开关控制
+- **别名（aliases）**：文档 frontmatter 中可声明 `aliases` 列表，搜索时别名获得 **3× BM25 权重提升**
+- **来源引用（source_refs）**：正文中使用 `[^src:name:line_range]` 标记第三方文档出处
+
+#### 来源类型标注
+
+`query_wiki` 搜索结果为每条结果标注 `source_type`，帮助 Agent 判断信息可信度：
+
+| source_type | 含义 | 消费建议 |
+|-------------|------|----------|
+| `auto_generated` | 来自 wiki/ 目录，代码分析自动生成 | 可直接引用 |
+| `developer_note` | 来自 notes/ 目录，人工/LLM 沉淀 | 检查时效性和确认状态 |
+| `ingested_source` | 来自 ingest_source 导入的外部文档 | 注意版本时效 |
+
+#### 外部文档管理
+
+通过 `ingest_source` 和 `retract_source` 管理第三方文档（API 文档、设计规范、RFC 等）的完整生命周期：
+
+```json
+// 导入外部文档
+{ "name": "rfc-7519-jwt", "source_type": "rfc", "source_path": "/path/to/rfc7519.txt",
+  "description": "JWT 规范", "related_pages": ["auth-module"] }
+
+// 撤回外部文档（两种模式）
+{ "source_name": "rfc-7519-jwt", "mode": "flag_stale" }    // 标记过期，保留文件
+{ "source_name": "rfc-7519-jwt", "mode": "remove_refs" }   // 删除文件，清理所有引用
+```
+
+#### 文档健康检查
+
+`lint_wiki` 提供 **11 项检查**，覆盖结构完整性和内容质量：
+
+| 检查项 | 说明 |
+|--------|------|
+| `stale_refs` | 引用了已不存在的组件 |
+| `broken_links` | 断链（wikilink 指向不存在的页面） |
+| `undocumented` | 高影响力组件缺少文档 |
+| `cycles` | 模块间循环依赖 |
+| `coverage` | 文档覆盖率不足 |
+| `orphan_pages` | 没有任何页面链接到的孤立页面 |
+| `no_outlinks` | 没有链接到任何其他页面的死端页面 |
+| `missing_aliases` | 实体页面缺少 aliases 声明 |
+| `stale_sources` | 引用了已撤回外部文档的页面 |
+| `overview_stale` | overview.md 引用了已变更的模块 |
+| `unsupported_claims` | 业务断言缺少代码证据（>30% 触发警告） |
+
+`lint_wiki` 返回 **health_score**（0-100），计算方式为 `100 - Σ(error×10 + warning×3 + info×1)`。
+
+#### 全文搜索
+
+`query_wiki` 搜索能力：
+
+- **BM25 排序** + jieba 中文分词
+- **类型过滤**：`type_filter` 限定搜索范围（module/entity/concept/source/comparison/query）
+- **作用域前缀**：`scope` 支持目录前缀（如 `wiki/entities`、`notes`）
+- **权重增强**：aliases 3× boost、severity 2× boost
+- **图谱多跳扩展**：`hop`（0-3）沿 wikilink 有向边 BFS 发现关联页面，`decay` 控制衰减
+- **深度阅读**：`expand=true` 返回完整页面内容（≤ 3000 字符）
+- **渐进模式**：`mode=overview/directory/detail` 分层消费
+- **状态过滤**：自动跳过 rejected 笔记，candidate 标注 [unconfirmed]
+
+#### 提示词模板
+
+`get_prompt` 支持 **16 种 prompt_type**：
+
+| prompt_type | 用途 |
+|-------------|------|
+| `cluster` | 模块聚类规则 |
+| `system_complex` / `system_leaf` | 文档生成系统指令（含 Evidence-Based + 约束索引表） |
+| `user` | 用户 prompt 模板（含代码路由 + BFS 上下文） |
+| `overview_module` / `overview_repo` | 总览合成 |
+| `entity_page` / `concept_page` | 实体/概念页面生成 |
+| `source_summary` | 外部文档摘要 |
+| `comparison_page` / `query_page` | 对比分析 / 研究查询 |
+| `taxonomy_plan` | Wiki 分类体系规划 |
+| `extraction_scan` | 源码实体/概念候选提取 |
+| `wiki_query` / `wiki_ingest` / `wiki_lint_report` | 知识管理工作流 |
+
+### 使用场景示例
+
+**场景 1：生成仓库文档**
+
+```
+帮我分析当前仓库并生成 Wiki 文档，输出到 repowiki 目录。请使用中文撰写文档。
+```
+
+**场景 2：增量更新**
+
+```
+代码有改动，帮我更新受影响的模块文档。
+```
+
+Agent 调用 `analyze_repo`，自动检测变更文件和 stale 组件，只重新生成受影响的模块。
+
+**场景 3：搜索项目知识**
+
+```
+搜索项目中关于"订单状态机"的所有知识。
+```
+
+Agent 调用 `query_wiki(query="订单状态机", hop=1)`，返回相关文档 + 图谱关联页面。
+
+**场景 4：沉淀开发经验**
+
+```
+记录一个踩坑：Redis 连接池在高并发下偶尔超时，根因是 maxTotal 设置过低。
+```
+
+Agent 调用 `ingest_note(note_type="pitfall", status="candidate")`，写入笔记待确认。
+
+**场景 5：确认/否决知识**
+
+```
+确认 notes/pitfall-redis-connection-pool.md 这条笔记。
+```
+
+Agent 调用 `confirm_note(note_file="pitfall-redis-connection-pool.md")`，升级为正式知识。
+
+**场景 6：导入外部文档**
+
+```
+把 docs/stripe-api-reference.md 导入 Wiki，关联支付模块。
+```
+
+**场景 7：检查文档健康度**
+
+```
+检查一下 Wiki 文档的健康状况。
+```
+
+Agent 调用 `lint_wiki`，返回 11 项诊断报告和 health_score。
+
+**场景 8：跨服务调用分析**
+
+```
+分析这个 monorepo 里各服务之间的调用关系。
+```
+
+Agent 调用 `analyze_repo`（自动检测子服务）→ `query_cross_service(filter_type="all")`。
+
+### 支持的其他 AI IDE
+
+除 CodeBuddy 外，任何支持 MCP stdio 协议的 AI IDE 均可使用：
+
+**Cursor**：在 Settings → MCP 中添加相同的 Server 配置。
+
+**Claude Desktop**：在 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）中添加 MCP 配置。
+
+**其他 IDE**：指定 `command: "python"`, `args: ["-m", "codewiki.mcp.server"]` 即可。
+
+### 原始 CLI 模式（仍然可用）
+
+如果你更习惯命令行一键生成，原始的 CLI 方式完全不受影响。需要先配置 LLM API：
+
+```bash
+codewiki config set \
+  --provider openai-compatible \
+  --api-key YOUR_KEY \
+  --base-url https://api.example.com \
+  --main-model claude-sonnet-4 \
+  --cluster-model claude-sonnet-4
+
+codewiki generate
+```
+
+支持 OpenAI、Anthropic、Azure OpenAI、AWS Bedrock 以及 Claude Code / Codex 订阅模式。详见[上游项目 README](https://github.com/FSoft-AI4Code/CodeWiki)。
+
+### 支持的语言
+
+Python、Java、JavaScript、TypeScript、C、C++、C#、Kotlin、Go、PHP
+
+### 致谢
+
+本项目的核心工具链（Tree-sitter AST 解析、依赖图构建、拓扑排序、Mermaid 校验）全部来自 [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki) 上游项目。以下开源项目的设计思路对我们产生了重要影响：
+
+- [codebase-memory-mcp](https://github.com/nicobailon/codebase-memory-mcp) — SQLite 持久化缓存架构、跨会话复用、三层降级模式
+- [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) — 结构化知识层设计、页面类型路由、交叉链接
+- [Tencent/WeKnora](https://github.com/Tencent/WeKnora) — 外部文档管理、文档健康检查、自适应分块思路
+- [CodingHub](https://github.com/mambo-wang/CodingHub) — MCP Server 最佳实践（instructions / prompts / resources）
+
+我们在上游基础上将 MCP Server 从黑盒模式拆分为 **23 个细粒度工具**，并新增结构化 Wiki、Evidence-Based 断言、代码路由分类、知识飞轮、渐进式阅读、方法级增量检测、monorepo 跨服务分析等能力。
+
+上游论文：[CodeWiki: Evaluating AI's Ability to Generate Holistic Documentation for Large-Scale Codebases](https://arxiv.org/abs/2510.24428)
+
+```bibtex
+@misc{hoang2025codewikievaluatingaisability,
+      title={CodeWiki: Evaluating AI's Ability to Generate Holistic Documentation for Large-Scale Codebases},
+      author={Anh Nguyen Hoang and Minh Le-Anh and Bach Le and Nghi D. Q. Bui},
+      year={2025},
+      eprint={2510.24428},
+      archivePrefix={arXiv},
+      primaryClass={cs.SE},
+      url={https://arxiv.org/abs/2510.24428},
+}
+```
+
+---
+
+<a id="en"></a>
+
+## English
+
+### What is this project?
+
+CodeWiki-Plus is an enhanced fork of [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki) that enables **zero-LLM-config Wiki generation** driven entirely by AI IDEs (CodeBuddy, Cursor, Claude Desktop, etc.) via MCP (Model Context Protocol), plus a full knowledge management engine.
+
+### Why this fork?
+
+The original CodeWiki is an excellent repository-level documentation framework. However, it requires users to configure their own LLM API (API key, provider, model selection), and the generation pipeline runs as a black box with no user intervention.
+
+In practice, CodeWiki's core toolchain—Tree-sitter AST parsing, dependency graph construction, topological sorting, and Mermaid validation—does not need an LLM at all. The 4 stages that do require LLM intelligence (module clustering, document writing, sub-module recursion, and overview synthesis) are exactly what AI IDE Agents excel at.
+
+We refactored CodeWiki's MCP Server from a "one-click black box" into **23 fine-grained tools**, turning it into a pure toolchain server. The AI IDE's Agent calls these tools via MCP and uses its own reasoning to complete all documentation work:
+
+```
+Before:
+  IDE → generate_docs(repo) → [CodeWiki calls LLM API internally] → result
+
+After:
+  IDE Agent → analyze_repo → read_code → (Agent reasons) → write_doc → overview
+              ↑ pure tool     ↑ pure tool  ↑ IDE's own model ↑ pure tool
+```
+
+### Enhancements over upstream CodeWiki
+
+| Dimension | Upstream CodeWiki | CodeWiki-Plus |
+|-----------|------------------|---------------|
+| LLM config | Must configure API key | Zero-config, IDE model driven |
+| Generation mode | Black-box one-click | 23 fine-grained tools, full Agent control |
+| Doc quality | Generic descriptions | Evidence-Based assertions (code quotes + confidence) |
+| Generation efficiency | All components equal | Code routing: boilerplate gets signature-only |
+| Context precision | Intra-module components | BFS 1-hop call graph + constraint index table |
+| Incremental update | File-level Git diff | Method-level content_hash detection |
+| Knowledge management | None | Structured Wiki + note flywheel + external docs |
+| Search | None | BM25 + wikilink graph multi-hop + progressive reading |
+| Cross-service | None | Monorepo sub-service detection + call tracing |
+| Quality assurance | None | 11 lint checks + health score + issue tracking |
+
+### Prerequisites
+
+- **Python 3.12+**
+- **Node.js** (for Mermaid diagram validation; without it, validation is silently skipped)
+- An MCP-compatible AI IDE (CodeBuddy, Cursor, Claude Desktop, etc.)
+
+### Quick Start (CodeBuddy Example)
+
+3 steps, no API key needed.
+
+**Step 1: Install CodeWiki-Plus**
+
+```bash
+git clone https://github.com/mambo-wang/CodeWiki-Plus.git
+cd CodeWiki-Plus
+pip install -e .
+```
+
+**Step 2: Configure MCP Server**
+
+Add the following to your CodeBuddy MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "codewiki": {
+      "command": "python",
+      "args": ["-m", "codewiki.mcp.server"],
+      "cwd": "/your/path/to/CodeWiki-Plus"
+    }
+  }
+}
+```
+
+> Replace `/your/path/to/CodeWiki-Plus` with the actual absolute path where you cloned CodeWiki-Plus.
+
+**Step 3: Prompt your AI Agent**
+
+Open the target project in CodeBuddy, switch to Agent mode, and enter:
+
+```
+Analyze the current repository and generate Wiki documentation into the repowiki directory. Write docs in English.
+```
+
+The Agent follows a 5-stage pipeline:
+
+```
+Stage 1: Call analyze_repo → get component index, leaf nodes
+         (auto-detects monorepo sub-services, builds cross-service topology)
+Stage 2: Call get_prompt("cluster") for clustering rules
+         Read source code, reason about grouping, call save_module_tree
+Stage 3: Document each module leaf-first
+         Leaf modules: read_code → reason → write_doc_file
+         (prompt auto-injects BFS call context + constraint index + business rules extraction)
+         Parent modules: read child docs → synthesize → write_doc_file
+Stage 4: Generate repository overview (overview.md)
+Stage 5: Call close_session to free resources, build search index
+```
+
+### MCP Tools
+
+All tools require zero LLM config. The IDE Agent invokes them via MCP. The server includes built-in **instructions**, **7 Prompt templates**, and **6 Resources**.
+
+**Code Analysis (6):**
+
+| Tool | Purpose |
+|------|---------|
+| `analyze_repo` | Parse repo, build dependency graph; SHA256 incremental + method-level content_hash; monorepo sub-service detection |
+| `analyze_workspace` | Scan multi-repo workspace, generate per-repo Wikis with cross-service overview |
+| `list_components` | Component index query with summary mode and prefix filtering |
+| `list_dependencies` | Query dependencies with pagination, direction filtering, high-impact ranking |
+| `read_code_components` | Read source code by component ID |
+| `view_repo_file` | View raw source file content with optional line range |
+
+**Documentation Pipeline (6):**
+
+| Tool | Purpose |
+|------|---------|
+| `write_doc_file` | Create .md docs with Mermaid validation + crosslink injection + page_type routing; sessionless mode |
+| `edit_doc_file` | Edit docs (str_replace / insert / undo) |
+| `save_module_tree` | Persist module clustering results |
+| `get_processing_order` | Get leaf-first documentation order |
+| `get_prompt` | Retrieve prompt templates (16 prompt_types) |
+| `close_session` | Close session, build BM25 index + wikilink graph, write metadata |
+
+**Knowledge Management (7):**
+
+| Tool | Purpose |
+|------|---------|
+| `query_wiki` | BM25 search + wikilink graph multi-hop + **progressive reading** (mode=overview/directory/detail); source_type annotation |
+| `ingest_note` | File structured notes (8 types) with aliases + source_ref; default candidate status |
+| `confirm_note` | Promote candidate note to confirmed knowledge |
+| `reject_note` | Reject candidate note, exclude from future searches |
+| `ingest_source` | Import third-party docs into `raw/sources/` |
+| `retract_source` | Retract imported docs (flag_stale / remove_refs) |
+| `batch_ingest` | Batch import multiple notes/sources in one call |
+
+**Quality Assurance (2):**
+
+| Tool | Purpose |
+|------|---------|
+| `lint_wiki` | Doc-code consistency: **11 checks** (incl. unsupported_claims evidence detection) |
+| `flag_issue` | Flag quality issues, drives health score |
+
+**Cross-Service Analysis (1):**
+
+| Tool | Purpose |
+|------|---------|
+| `query_cross_service` | Query cross-service calls (HTTP + MQ), filter by service/method/path/trace |
+
+> 2 legacy tools (`generate_docs`, `get_module_tree`) retained for backward compatibility.
+
+### Documentation Quality Enhancements
+
+#### Evidence-Based Assertions
+
+Module documentation prompts require LLM to provide code evidence for each business rule:
+
+```markdown
+### Business Rules
+
+- **Order amount must be non-negative** [confidence: 0.95]
+  > evidence: `OrderService.java:L142` — `if (amount < 0) throw new BizException(...)`
+  > reason: Enforced validation on order creation
+```
+
+`lint_wiki` includes `unsupported_claims` check: warns when >30% of business assertions lack evidence.
+
+#### Code Routing
+
+Components are classified into three categories for differentiated processing:
+
+| Category | Typical Components | Treatment |
+|----------|-------------------|-----------|
+| `business` | Service, Controller, Job, Handler | Full source injected to LLM |
+| `boilerplate` | DTO, VO, Entity, Config, Mapper | Signature + fields only, template output |
+| `infra` | Util, Helper, Factory, Interceptor | Summary-level description |
+
+Reduces LLM token consumption by 30%+ on typical Java/Spring repos. Customizable via `code_routing` in `schema.yaml`.
+
+#### BFS Call Context
+
+Prompts auto-inject 1-hop call context (`<CALL_CONTEXT>` block) with caller/callee signatures for each core component.
+
+### Incremental Updates
+
+Three layers of incremental optimization:
+
+- **Git strategy (preferred)**: `git diff` against stored commit
+- **SHA256 fingerprint (fallback)**: Content hash + mtime dual detection
+- **Method-level detection**: Per-component `content_hash` comparison; only truly changed methods trigger re-generation. `get_stale_components()` returns added/modified/deleted lists for cascade wiki invalidation.
+
+### Monorepo Cross-Service Analysis
+
+`analyze_repo` auto-detects sub-services via 5-stage heuristics (docker-compose → Dockerfile → build manifests → convention dirs → Spring Boot), assigns independent labels, and runs CrossServiceMatcher for HTTP/MQ call relationships.
+
+### Knowledge Flywheel
+
+Notes follow a candidate → confirmed → rejected lifecycle:
+
+```
+LLM discovers cross-cutting constraint
+  → ingest_note(status=candidate)
+  → query_wiki annotates [unconfirmed]
+  → Developer confirms: confirm_note → promoted to verified knowledge
+  → Developer rejects: reject_note → excluded from search (record preserved)
+```
+
+### Progressive Reading Protocol
+
+`query_wiki` supports three consumption modes:
+
+| mode | Returns | Use case |
+|------|---------|----------|
+| `overview` | Repo-level summary (< 500 tokens) | First contact with project |
+| `directory` | By-type page directory (< 800 tokens) | Locate target module/entity |
+| `detail` | Full page content | Deep reading |
+| default | BM25 snippet results | Keyword search |
+
+### Supported Languages
+
+Python, Java, JavaScript, TypeScript, C, C++, C#, Kotlin, Go, PHP
+
+### Acknowledgements
+
+The core toolchain (Tree-sitter AST parsing, dependency graph, topological sort, Mermaid validation) comes from [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki). Influenced by:
+
+- [codebase-memory-mcp](https://github.com/nicobailon/codebase-memory-mcp) — SQLite persistent cache, cross-session reuse
+- [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) — Structured knowledge layer, page type routing
+- [Tencent/WeKnora](https://github.com/Tencent/WeKnora) — External doc management, health checks
+- [CodingHub](https://github.com/mambo-wang/CodingHub) — MCP Server best practices
+
+Paper: [CodeWiki: Evaluating AI's Ability to Generate Holistic Documentation for Large-Scale Codebases](https://arxiv.org/abs/2510.24428)
+
+---
+
+## License
+
+MIT