内容
> 语言: [中文](./README.zh.md)
# LLM-WIKI 治理
**AI 编写项目文档的治理。** `llm-wiki-governance` 是一个零依赖的命令行工具，用于保持 AI 编码代理的项目知识（`docs/llm-wiki/`）**可信和最新**：它将每个声明与实际代码绑定，当代码发生变化时标记文档，保持 AI 编写的內容在人类审核后，并强制在 CI 中执行。适用于任何技术栈、任何代理，并**与 OKF 兼容**。
## 为什么需要治理层？
*LLM wiki* —— 一个精炼的、相互关联的知识库，代理在每次任务中读取而不是重新推导你的代码库 —— 是一个已被验证的模式（在 2026 年推广，并在 Google 的 Open Knowledge Format 中正式化）。难点从来不是*创建*，而是保持其诚实。
| 方法 | 代理如何获取上下文 | 问题 |
| --- | --- | --- |
| **RAG** | 每次查询重新检索和重新推导源代码 | 重复、昂贵，没有共享的真实来源 |
| **普通 LLM wiki** （一个 Markdown 文件夹，例如 OKF 项目） | 读取手动编写的知识库 | 悄悄过期 → 文档*撒谎* |
| **受管 LLM wiki** （此工具） | 读取相同的 wiki — 但**经过验证、检查漂移、CI 强制执行** | — |
**这里的“治理”是什么意思：**
- **信任状态** — AI 编写的文档保持 `needs_review`；只有人类才能将其提升为 `verified`。命令行工具*永远*不能自我批准。
- **证据 + 漂移** — 每个声明都链接到实际文件/行/符号；当源代码更改时，`evidence.stale` / `drift` 标记文档以供重新审核。
- **CI 强制执行** — `validate` 在 pre-commit / GitHub Actions 中运行，因此未经审核或漂移的 wiki 将导致构建失败而不是悄悄损坏。
- **代理可查询** — 只读 MCP 服务器允许代理*询问* wiki 而不是重新扫描代码。
- **安全建设** — 预览优先写入、追加式更改日志、敏感值编辑和**零运行时依赖**。
```text
没有：任务 -> 重新扫描代码库 -> 重新推导结构和规则 -> 工作
有：任务 -> 读取 index.md -> 读取相关（已验证）的 wiki 文档 -> 只检查需要的文件 -> 工作
```
命令行工具构建结构和防护栏；代理从实际代码中丰富文档；人类批准 `verified`；CI 保持其诚实。可用于遗留维护、功能开发、事件响应、入职、移交和跨代理共享项目知识。
## 支持的环境
| | |
| --- | --- |
| **运行时** | Node.js ≥ 18.18.0 · Windows, macOS, Linux |
| **依赖** | 无 — 没有运行时第三方依赖 |
| **检测** | Node · Python · Go · Rust · JVM · PHP · Ruby · .NET · 移动端（Android / Flutter / iOS / React Native）· 基础设施（Docker / Compose / Kubernetes / Helm / Terraform） |
| **标准** | **OKF 兼容** — `--profile okf-v0.1` 验证 Open Knowledge Format `type`/`aliases`/`tags`；核心验证器接受 OKF `type` 作为 `doc_type` 的别名 |
| **代理 / 编辑器** | Codex (`AGENTS.md`), Claude Code (`CLAUDE.md`), Cursor, GitHub Copilot, Windsurf, Gemini CLI — 另外还有任何 MCP 客户端通过 `llm-wiki mcp` |
| **独立** | 命令行工具（init / validate / audit / graph / stats / CI）完全**无需代理** |
## 快速开始
```bash
npm install -D llm-wiki-governance
npx llm-wiki quickstart --write --type frontend --agent claude # 或 --agent codex
```
`quickstart --write` 检测项目，创建 wiki + 适配器文件，并打印移交提示。将该提示粘贴到您的代理中：它读取 `docs/llm-wiki/index.md`，从实际源文件丰富文档，并将所有内容标记为 `needs_review` 以供您批准。首先使用 `quickstart --dry-run` 预览。
添加 `--skills` （或 `--agent claude|cursor`）还会生成可调用的、基于 wiki 的自动化提示 — 一个 Claude 技能（`/llm-wiki-feature`）、一个 Cursor 规则和一个与代理无关的提示 — 用于持续的功能/修复/文档同步工作，每个提示都带有项目领域映射的快照。
**已经有一个 OKF（或纯 Markdown）知识文件夹？** 将命令行工具指向它，以添加验证、漂移检测和 CI，而无需更改格式 — `--profile okf-v0.1` 将其视为一等公民。
## 推荐的代理和模型
命令行工具不需要模型。只有**丰富**步骤 — 代理读取代码并编写准确的、基于源代码的文档 — 才需要，而这就是模型质量最重要的地方。
| 任务 | 模型层级 |
| --- | --- |
| **Wiki 丰富** （从代码编写/刷新文档） | 代理的**最强推理/编码模型** （例如 Claude Opus 类模型、高推理 GPT-5 类模型或每个工具的顶级编码模型）。准确性和低幻觉在这里很重要。 |
| **例行维护** (`docs-sync` 小更改，运行 `validate`/`status`) | 中档或经济型模型就足够了。 |
| **命令行工具本身** (`init`, `validate`, `audit`, `graph`, `stats`, `mcp` 服务器) | 无模型 — 纯 Node，在任何地方和 CI 中运行。 |
`llm-wiki mcp` 服务器是确定性的（无模型）；调用其工具的代理可以是任何模型，遵循相同的丰富指南。
## 核心命令
| 命令 | 功能 |
| --- | --- |
| `quickstart --write` | 设置 wiki + 适配器，打印代理移交提示（`--skills` 还生成自动化技能）。 |
| `validate` | 结构和安全验证，用于本地检查 / CI（`--strict`， `--changed`）。 |
| `audit` · `status` | 完整发现报告 · 当前 wiki 状态。 |
| `graph` · `stats` | 知识图（文本/JSON/Mermaid/DOT）· 健康快照（验证 % / 丰富 % / 证据覆盖率）。 |
| `drift` · `fix` · `migrate` | 漂移检测和降级 · 有限安全自动修复 · 合同升级（均预览优先）。 |
| `handoff` · `prompt` | 代理移交提示 · 可重复的任务提示（功能/修复/重构/文档同步/OKF 提取）。 |
| `mcp` | 运行只读 MCP 服务器（见下文）。 |
完整的命令、选项、退出代码和程序 API 参考：运行 `npx llm-wiki help <command>` （离线），或查看 [PUBLIC_API.md](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/docs/llm-wiki/PUBLIC_API.md)。
## 实践中的治理
- **谨慎验证。** 代理编写的文档保持 `needs_review`；人类将其提升为 `verified` 后再阅读。命令行工具的任何操作都无法绕过这一点。
- **尽早捕获漂移。** 每个文档都引用 `source_files` / 精确的 `evidence`；当这些更改时，`evidence.stale` 和 `drift` 标记文档。运行 `drift --downgrade` 将过时的 `verified` 文档降级为 `needs_review`。
- **在同一更改中保持最新。** 在代码更改的同时更新 wiki（`prompt --task docs-sync` 或 `docs-sync` 技能），并在 pre-commit / CI 中运行 `validate --changed`。
- **让代理自行服务。** 将您的代理指向 `mcp` 服务器，以便它像工具一样查询 wiki 而不是重新扫描代码。
- **连接 CI。** 复制 [`templates/github-actions/llm-wiki-validate.yml`](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/templates/github-actions/llm-wiki-validate.yml) 以在每个 PR 上运行 `validate`，或在一步中引用复合操作 — `uses: Dowon-Kim7949/llm-wiki-governance/.github/actions/validate@v1.7.0` （固定确切标签）。
- **使其可读。** `graph --format mermaid`、`stats` 和 `audit --format html` 帮助人类查看语料库；它保留在 Markdown-in-git（在 GitHub/GitLab、Obsidian、MkDocs 上渲染 — 不是静态站点生成器）。
## 代理原生（MCP）
`llm-wiki mcp` 在标准输入输出上运行 [Model Context Protocol](https://modelcontextprotocol.io) 服务器（换行分隔的 JSON-RPC 2.0，仅限 Node 内置 — 无第三方 SDK）。在 MCP 客户端中注册它：
```json
{ "mcpServers": { "llm-wiki": { "command": "npx", "args": ["-y", "llm-wiki-governance", "mcp"] } } }
```
它公开**只读**工具 — `validate`, `audit`, `next`, `status`, `doctor`, `stats`, `graph`, `explain`, `handoff`, `prompt` — 以便代理可以检查 wiki 但永远不会写入。详细信息： [PUBLIC_API.md](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/docs/llm-wiki/PUBLIC_API.md) · [GATE_REVIEW.md](./GATE_REVIEW.md) （Gate 11）。
## 从代码中使用
导入包而不是使用 shell 命令 — 适用于 CI 包装器、编辑器集成和测试：
```js
import { commands, normalizeOptions, run } from "llm-wiki-governance";
const r = await commands.audit(normalizeOptions({ cwd: process.cwd() }));
// r.command, r.result, r.findings, r.schemaVersion
const code = await run(["validate", "--strict"]); // 0 pass / 1 error / 2 blocked / 3 usage
```
`--format json` 输出带有顶级 `schemaVersion`，以便包装器可以固定合同。完整 API 见 [PUBLIC_API.md](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/docs/llm-wiki/PUBLIC_API.md)。
## 安全一览
预览优先（写入仅限 `--write` / `--apply`）；`verified` 仅限人类在每个命令中；`docs/llm-wiki/log.md` 和现有适配器文件永远不会被覆盖；类似敏感值的永远不会被打印或写入；没有运行时第三方依赖。完整范围决策： [GATE_REVIEW.md](./GATE_REVIEW.md)。
## 了解更多
- [PUBLIC_API.md](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/docs/llm-wiki/PUBLIC_API.md) — 完整的命令 / 选项 / 退出代码 / 配置 / 程序 API / MCP 参考。
- [GATE_REVIEW.md](./GATE_REVIEW.md) — 接受的安全范围（修复 / 迁移 / 漂移 / MCP / 技能）和发布门控。
- [ROADMAP.md](./ROADMAP.md) — 方向和已发布的歷史。
- [EXAMPLES.md](https://github.com/Dowon-Kim7949/llm-wiki-governance/blob/main/docs/llm-wiki/EXAMPLES.md) — 实际示例 · [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md) — 维护者发布步骤。
- 社区： [CONTRIBUTING.md](./CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) · [SECURITY.md](./SECURITY.md)。
