主题
代码模式
使用 OpenWiki 为编码智能体生成并维护仓库文档
代码模式会在 openwiki/ 中构建一个仓库 wiki，其中包含架构、集成和工作流等持久性细节。编码智能体将该 wiki 用作上下文，从而能更高效地在包中工作，减少重复发现并减少 token 消耗。人类也可以阅读相同的 Markdown，但主要受众是智能体。智能体通过 OpenWiki 添加到 AGENTS.md 和 CLAUDE.md 中的指针来发现该 wiki。
openwiki、openwiki --init 和 openwiki --update 均在代码模式下运行。你也可以显式传入该模式：
bash
openwiki code --init
openwiki code --update
openwiki code --update --print再次运行 openwiki --init 会用一个新生成的版本替换现有的已生成仓库 wiki 和 Claims，同时保留用户编写的 openwiki/INSTRUCTIONS.md 简报。在持久化的检出版本上，OpenWiki 会在 openwiki/.run.json 中记录进行中的生成，因此在中断后重新运行同一命令会恢复持久化的页面队列。临时性的 CI 运行器在失败后会从头开始，除非其工作区被保留。在新运行状态变为持久化之前发生设置失败时，会恢复之前的 wiki。
要以另一种语言生成 wiki 页面，请传入 BCP-47 语言环境，例如 ko、zh-CN 或 pt-BR：
bash
openwiki --init --language ko你也可以在 Codex、Claude Code、OpenCode 或 Cursor 中运行 OpenWiki。参见编码智能体集成。
代码模式会产出什么
在成功执行 init 或 update 后，仓库通常包含：
openwiki/：生成的 Markdown wiki（快速入门、架构、运维及相关主题）openwiki/INSTRUCTIONS.md：用户编写的、用于界定范围和优先级的简报。OpenWiki 会在 init 和 update 时读取它。你可以自行编辑，或在聊天中让 OpenWiki 更改它；常规的--init和--update运行不会重写它openwiki/.claims/：结构化的 Claim 边车，用于将事实性页面锚定到有版本的仓库证据openwiki/.page-manifest.json：逐页进度和来源检查点，用于断点续传式的生成openwiki/.last-update.json：上次成功文档检查（包括空操作更新）的元数据AGENTS.md/CLAUDE.md：OpenWiki 会插入或刷新一个<!-- OPENWIKI:START -->…<!-- OPENWIKI:END -->块，告诉编码智能体何时查阅该 wiki。该块之外的现有内容保持不变
在一次活动运行期间，openwiki/.run.json 会为有序页面队列做检查点。OpenWiki 会在成功完成后删除该文件。
有据可依的 Claim
OpenWiki 通过追踪事实性页面背后的实质性命题，使代码 wiki 具备自我纠正能力，而不仅仅是记录 Markdown 文件上次生成的时间。Claim 涵盖未来智能体所依赖的真相：行为、职责、架构、数据流、不变量、失败语义、配置和安全边界。每个 Claim 都指向确切的仓库证据，例如 repo://src/server.ts#L40-L82，并附带该 Claim 确立时 OpenWiki 观察到的证据版本。
Markdown 保持整洁。结构化的 Claim 状态存放于 openwiki/.claims/ 下。页面完成时会持久化已对账的 Claims，将验证投射到 OKF front matter 中，并在将该页面任务标记为完成之前证明结果为完整。有据可依的 Claim 适用于仓库代码 wiki 和仓库证据。源自连接器的事实（包括仅来自 LangSmith 的观察）不会作为 Claim 纳入。
Markdown 输出
OpenWiki 的持久化输出是 Markdown（OKF），而不是静态 HTML 站点。要在浏览器中浏览该 wiki，请运行 openwiki visualize。该命令仅在你的本地机器（127.0.0.1）上提供查看器，或者你可以导出静态可视化器用于托管。
开放知识格式
OpenWiki 在代码模式和个人模式下都会生成 Google 开放知识格式（Open Knowledge Format，OKF） v0.2 捆绑包：
- concept 是普通的 wiki Markdown 页面（一个主题文件）。每个 concept 都有带非空
type的 YAML front matter；其他标准字段是可选的 - 新建和刚初始化的页面会获得
generated: {by, at}。在更新期间，任何正文变化（包括空白字符）都会推进时间戳；未变化的正文会保留其先前事件，而仅 front matter 的变化不会推进它。生产者会被标记为openwiki/<version>（或编码智能体宿主） - 仓库页面会将有据可依的 Claims 证据投射到
sources中。OpenWiki 会对其确定性识别的条目进行对账，同时保留独立编写的来源 - 仓库页面只有在一次成功的页面提交对账了一组非空的完整 Claims、通过最终证据复核并持久化 Claim 边车之后，才会获得
verified: {by: openwiki/<version>, at: ...} index.md和log.md是保留的脚手架文件，而不是 concept。根索引声明okf_version: "0.2"- 可选的 v0.2 来源、信任和生命周期族（
sources、verified、status、stale_after）在存在时会进行校验。生产者定义的扩展字段会在更新和迁移过程中保留 - concept 文档之间的标准 Markdown 链接用于表达关系
LangSmith 连接器
LangSmith 连接器会丰富代码 wiki：它会为你选择的项目拉取最近的 LangSmith 追踪（工具调用、结果和延迟），从而使仓库文档不仅能反映源代码所描述的内容，还能反映代码在运行时的行为。
在代码模式下于 openwiki --init 期间配置它。从来源菜单中，添加 LangSmith，选择你的工作区区域（US、EU 或 APAC），并列出要记录的项目。OpenWiki 会写入一个已提交的 openwiki/.langsmith.json，其中命名了工作区和项目（绝不包含密钥本身）。API 密钥从环境中读取：
bash
OPENWIKI_LANGSMITH_API_KEY="<your-langsmith-key>"在本地，设置向导可以将其保存到 ~/.openwiki/.env。在 CI 中，请将其设为仓库机密并为本次运行导出它。
LangSmith 密钥与工作区和区域绑定。要为多个工作区中的项目生成文档，请为每个工作区添加一个条目，每个条目使用自己的密钥，命名为 OPENWIKI_LANGSMITH_API_KEY_2、OPENWIKI_LANGSMITH_API_KEY_3，依此类推。该连接器会与官方 US（api.smith.langchain.com）、EU（eu.api.smith.langchain.com）和 APAC（apac.api.smith.langchain.com）主机通信。
忽略路径
在仓库根目录创建 .openwikiignore 文件，以防止生成的文档读取或描述私有的、生成的或不相关的路径。该语法支持注释、空行、* 和 ** 通配符、目录规则以及 ! 取反：
txt
secrets/
*.log
!logs/keep.log当 .openwikiignore 包含生效的规则时，OpenWiki 会过滤文件系统发现并限制 shell 执行，从而使被忽略的路径不进入本次运行。
NOTE
这是一条读取边界：被忽略的路径绝不会被读取、扫描或在生成的文档中复现。它并不保证某个主题绝不会被提及，因为智能体仍可能从其他被允许的证据（如测试、README、提交信息或现有 wiki）中推断出被忽略的区域。
图表
OpenWiki 在 Mermaid 图表比文字更能阐明某个 concept 时会嵌入它们。每次运行后，它会校验 Mermaid 围栏。未通过校验的图表会在原处转换为带简短注释的普通 text 围栏，然后在后续 --update 运行时尽可能修复。
为了获得与 GitHub 渲染更接近的校验，请在运行 OpenWiki 的任何位置安装 Mermaid 解析器：
bash
npm install mermaid jsdom当解析器存在时，OpenWiki 会使用它。当它不存在时，OpenWiki 会回退到轻量级检查。无论哪种情况，图表生成都能正常工作。
自定义 wiki 简报
编辑 openwiki/INSTRUCTIONS.md，以引导仓库文档的范围、优先级和偏好的写作约定（例如语气、术语，以及强调或略过哪些内容）。OpenWiki 会在 init 和 update 运行时读取此文件。你也可以在聊天中让 OpenWiki 修改该简报：
bash
openwiki "Update openwiki/INSTRUCTIONS.md to prioritize the public API and skip internal tooling"常规的 --init 和 --update 运行不会重写此文件。