🧭 核心功能与定位

OpenWiki 旨在解决文档维护的痛点，通过 AI 代理自动生成并更新文档。其核心价值在于：

  • 自动生成与更新：AI 代理读取你的代码或数据源，生成结构化的 Markdown 维基，并在每次代码变更时自动更新。
  • 两种模式：
    • code 模式：为 Git 仓库生成文档。
    • personal 模式：为个人知识（如笔记、邮件、聊天记录）生成维基。
  • 可验证的事实（Grounded Claims）：记录文档中每个事实的源代码证据（文件+行号），当代码变更时，能精确定位需要更新的文档段落。
  • 多模型支持：内置支持 OpenAI、Anthropic、Gemini、Bedrock 等 13 种模型提供商。
  • 编码代理集成：可直接在 Codex、Claude Code、OpenCode 等代理内部运行，复用其认证和工具。
  • 交互式可视化：提供浏览器界面，将维基文档以节点图形式展现，方便浏览。

📦 安装

1. 前提要求

  • Node.js 22 或更新版本。
  • 包管理器：推荐使用 npm 或 pnpm。

2. 安装 OpenWiki CLI

1
npm install -g openwiki

Windows 用户：如果使用 bun 安装，可能需要 Visual Studio Build Tools（含 C++ 桌面开发工作负载）来编译原生依赖。

🚀 快速开始（代码模式）

1. 初始化维基

在你想要文档化的 Git 仓库根目录下运行：

1
openwiki --init
  • 首次运行会引导你选择 AI 模型提供商（如 OpenAI）、设置 API Key 并选择模型。
  • 它会在当前目录下创建一个 openwiki/ 文件夹，存放生成的 Markdown 文档和相关元数据。

2. 更新维基

当代码发生变更后，运行以下命令更新文档：

1
openwiki --update
  • OpenWiki 会检测代码变化，只更新受影响的部分。
  • 如果没有任何实质性变化，它会跳过模型调用，避免浪费。

3. 查看维基

  • Markdown 文件：所有文档都在 openwiki/ 目录下，你可以直接用编辑器或 GitHub 查看。

  • 交互式可视化：运行以下命令，在浏览器中打开一个可交互的节点图：

    1
    openwiki visualize

    默认地址为 http://127.0.0.1:4321。

🔧 进阶用法与配置

1. 编码代理集成（推荐）

如果你已经在使用 Codex、Claude Code 或 OpenCode，可以让 OpenWiki 直接在其中运行：

1
2
3
4
# 安装对应集成
openwiki integrations install codex
openwiki integrations install claude
openwiki integrations install opencode

安装后，在代理中提问：

“根据当前源代码和测试，初始化此仓库的 OpenWiki。”

2. 个人知识库模式 (personal)

为你的个人知识（如笔记、邮件）建立维基：

1
openwiki personal --init

数据源配置在初始化过程中进行，支持连接 Notion、Slack、Gmail、Twitter、本地 Git 仓库等。

3. 模型与提供商配置

  • 环境变量：通过设置 OPENWIKI_PROVIDER 和对应的 API Key 环境变量（如 OPENAI_API_KEY）来切换模型。

  • 支持的提供商：OpenAI、Anthropic、Gemini、AWS Bedrock、OpenRouter、GitHub Copilot、Ollama 等。

  • 示例（使用 Ollama 本地模型）：

    1
    2
    3
    4
    5
    OPENWIKI_PROVIDER=openai-compatible \
    OPENAI_COMPATIBLE_API_KEY=ollama \
    OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1 \
    OPENWIKI_MODEL_ID=llama3.2 \
    openwiki --init

4. 持续集成（CI）自动化

将 OpenWiki 集成到 CI 流水线中，实现文档自动更新。

  • GitHub Actions：复制 openwiki-update.yml 到 .github/workflows/ 目录。
  • 该工作流会定期运行 openwiki --update，如有文档变更，会自动创建一个 Pull Request。

📋 常用命令参考

命令 说明
openwiki --init 初始化当前仓库的代码维基。
openwiki --update 更新当前仓库的代码维基。
openwiki personal --init 初始化个人知识维基。
openwiki visualize 启动交互式维基可视化界面。
openwiki auth <provider> 为个人维基的数据源（如 Notion）进行 OAuth 认证。
openwiki ingest all 运行个人维基的所有数据源摄入。
openwiki integrations install <codex> 为指定编码代理安装集成。
openwiki --help 查看完整帮助信息。

❓ 常见问题与注意事项

  • 大型代码库的 Token 消耗：OpenWiki 会读取代码库内容并调用 LLM，对于大型仓库，初始生成可能会消耗较多 token。建议从核心模块开始，或使用 openwiki/INSTRUCTIONS.md 文件指导代理聚焦重点。
  • 文档准确性：OpenWiki 通过“Grounded Claims”机制追踪每个事实的来源。如果怀疑文档过时，运行 --update 会重新验证所有声明。
  • 数据隐私：个人模式的数据源（如 Gmail、Slack）通过本地 OAuth 认证，数据在本地处理。模型调用通过你选择的 API 提供商，请参考其数据政策。
  • CI 中的模型认证：在 CI 中运行 openwiki --update 时，需要设置环境变量（如 OPENAI_API_KEY）并提供给工作流。

总结

OpenWiki 为自动化文档维护提供了一个强大的解决方案。建议从 code 模式开始，在本地仓库运行 openwiki --init 体验其生成能力，并通过 openwiki visualize 直观浏览生成的维基。如果你日常使用编码代理（如 Codex），请务必安装其集成，让文档生成无缝嵌入工作流。对于团队项目，配置 CI 自动化更新可以确保文档始终与代码同步。项目采用 MIT 许可证，自由且开源。