内容
# 代码库维基
**面向 AI 代理的 MCP 接口架构知识库。**
代理发现服务，生成带有 Mermaid C2/C3/序列图的 LLM 驱动文档，并为语义搜索编制索引。包括自学习笔记和一流的工作流/流程索引。
## 快速入门
```bash
npm install -g @carreira-cloud/codebase-wiki
cd my-project
codebase-wiki init # 初始化知识库
codebase-wiki serve # 在 http://localhost:3080 浏览
codebase-wiki start-mcp # 为 AI 代理启动 MCP 服务器
```
## 命令
| 命令 | 描述 |
|---------|-------------|
| `init` | 初始化当前仓库的知识库 |
| `serve` | 启动 Web UI（markdown + mermaid 渲染，flows 标签） |
| `start-mcp` | 启动 MCP 服务器（stdio JSON-RPC，12 种工具） |
| `search <query>` | 按关键词搜索文档、笔记和流程 |
| `get <service>` | 检索服务的完整文档 |
| `list` | 列出所有索引服务 |
| `stats` | 统计：服务、流程、笔记、内容大小 |
| `install-opencode` | 安装 OpenCode 技能和命令 |
## MCP 工具
### 文档（8 种工具）
| 工具 | 描述 |
|------|-------------|
| `wiki_index` | 索引 LLM 生成的架构文档 |
| `wiki_search` | 按关键词搜索文档 |
| `wiki_get` | 检索服务的完整文档 |
| `wiki_list` | 列出所有索引服务 |
| `wiki_delete` | 删除服务的文档 |
| `wiki_stats` | 统计：服务、内容大小、笔记数、流程数 |
### 自学习笔记（3 种工具）
| 工具 | 描述 |
|------|-------------|
| `wiki_note` | 存储自学习发现笔记 |
| `wiki_notes_search` | 按关键词搜索代理笔记 |
| `wiki_notes_list` | 列出笔记（可选类型过滤） |
### 工作流和流程（3 种工具）
| 工具 | 描述 |
|------|-------------|
| `wiki_flow_index` | 索引带有关键词和链接服务的流程图 |
| `wiki_flow_search` | 按关键词搜索所有服务的流程 |
| `wiki_flow_list` | 列出流程（可选服务/流程类型过滤） |
## OpenCode 命令
```
/wiki generate <service> → 代理发现、生成文档、通过 MCP 编制索引
/wiki generate-all → 为所有服务生成文档
/wiki enhance <service> <flow> → 添加 Mermaid C3/C2/序列图
/wiki discover-flows <service> → 发现和索引所有带有边缘情况的工作流
/wiki flow-search <query> → 搜索所有服务的流程
/wiki flow-list <service> → 列出服务的流程
/wiki search <query> → 搜索文档 + 笔记 + 流程
/wiki get <service> → 检索完整文档
/wiki list → 列出所有索引服务
/wiki stats → 知识库统计
```
## 自学习
代理在发现新内容时会自动添加笔记。六种笔记类型：
| 类型 | 触发 |
|------|---------|
| `gotcha` | 意外的行为、边缘情况、已知错误 |
| `pattern` | 两个以上服务中重复出现的模式 |
| `integration` | 未文档化的服务集成细节 |
| `convention` | 代码约定、命名模式 |
| `decision` | 设计决策（轻量级 ADR） |
| `tip` | 快捷方式、有用的命令、工作流技巧 |
## 流程和图表
每个流程都独立编制索引，包含：
- **Mermaid 序列图**（正常路径 + 错误路径 + 边缘情况）
- **关键词** 用于可发现性
- **链接服务** 用于跨服务导航
- **流程类型**：happy_path、error_path、edge_case、recovery、full
图表在 Web UI 中通过 Mermaid.js 渲染。UI 还通过 marked.js 渲染服务文档 markdown（表格、代码块、标题）。
## 架构
```
src/
├── cli.ts # CLI 入口（8 个命令）
├── mcp-server.ts # MCP JSON-RPC 服务器（12 种工具）
├── ui-server.ts # Web UI（marked.js + mermaid.js，flows 标签）
├── lancedb/client.ts # JSON 文件存储（文档、笔记、流程）
├── types.ts # TypeScript 类型
└── index.ts # 公共 API 导出
docs/
├── getting-started.md
├── mcp-tools.md
├── self-learning.md
├── configuration.md
└── architecture.md
```
存储：`.codebase-wiki/rag_db/docs.json` + `notes.json` + `flows.json`
## 许可证
MIT — [Bruno Carreira](https://github.com/bruno-carreira)
