OpenWiki：定位、模式与知识格式

定位

OpenWiki 是建立在 Deep Agents 上的开源 CLI，用 Markdown 持续生成和维护面向 agent 的 wiki。核心价值不是“自动生成一个静态网站”，而是把架构、集成、评估和工作流等耐久上下文先写入 wiki，让 coding agent 先读知识索引，再只检查必要源码，从而减少重复发现和 token 消耗。

人类可以阅读同一批 Markdown 或使用本地 visualizer，但首要受众是 agent。OpenWiki 没有给 Claude/Codex 提供专有 connector；code mode 通过根目录 AGENTS.md 与 CLAUDE.md 中的指针让兼容 agent 发现 wiki。

两种模式

模式	输出	适用场景
Code（默认）	当前仓库 `openwiki/`	为 coding agent 维护仓库知识
Personal	`~/.openwiki/wiki`	从本地仓库、Gmail、Notion、Slack、Web、HN、X 等来源构建个人知识库

Code mode 的 openwiki、--init、--update 默认针对当前仓库；Personal mode 需要显式使用 openwiki personal。

Code mode 产物与所有权

openwiki/：生成的 Markdown wiki。
openwiki/INSTRUCTIONS.md：用户维护的 scope 与 priority brief；普通 init/update 不重写。
openwiki/.last-update.json：最后一次有效文档变化的元数据，用于避免 no-op 更新循环。
根 AGENTS.md / CLAUDE.md：只更新 OPENWIKI:START 到 OPENWIKI:END marker block，其他内容保留。

这形成清晰所有权：brief 由人维护，wiki 内容由生成流程维护，agent instruction 文件只允许 marker 内的可控更新。

Open Knowledge Format（OKF v0.1）

一个 concept 是一个普通 Markdown 主题页，必须有非空 type frontmatter。
index.md 与 log.md 是保留脚手架，不属于 concept。
根 index 声明 okf_version: "0.1"；嵌套 index 没有 frontmatter。
标准 Markdown 链接表达 concept 关系；合法 timestamp 和 producer extension fields 在更新与迁移中保留。

OpenWiki 的耐久输出是 OKF Markdown，不是 HTML。需要面向人托管时，再使用 GitHub Pages、MkDocs 或 OKF-compatible viewer 渲染。

Ignore 是读取边界，不是语义消失保证

.openwikiignore 支持注释、空行、*、**、目录规则和 ! negation。命中的路径不会被读取、扫描或原样写入，shell discovery 也会受限。

但是其他可见证据（测试、README、commit message、已有 wiki）仍可能间接表明被忽略区域存在。因此 ignore 能防止直接读取，不保证最终文档绝不提及某个概念；高敏感仓库仍需做来源最小化与生成结果审查。

Personal mode 数据流

source connector
  -> ~/.openwiki/connectors/<connector>/raw/
  -> source-specific agent run
  -> ~/.openwiki/wiki/

Connector secret 只按环境变量名引用，实际值进入 ~/.openwiki/.env，不能写进 config。
同一 source 可配置多个实例，例如两个不同主题的 web search。
macOS 可把 connector schedule 安装为用户 LaunchAgent，日志写入 ~/.openwiki/logs/。
cron delete 只删除保存的 schedule 并卸载 LaunchAgent，不删除 auth、config、raw data 或 wiki。

Personal mode 会接触邮件、Notion、Slack 等私人数据，使用前必须明确授权来源、数据保留边界和敏感级别；本次学习没有连接或读取任何个人账户。

本地可视化

openwiki visualize [path] 在 127.0.0.1 启动 graph + Markdown reader：

默认读取 ./openwiki、端口 4321；占用时自动递增。
--no-open 只启动服务，不自动打开浏览器。
文件编辑可实时反映。
graph 显示 concepts 与 Markdown links，不显示 INSTRUCTIONS.md 等脚手架。

适用与不适用

适合：多次由 agent 维护的中大型仓库、知识发现成本高、上下文重复读取明显的场景。

谨慎使用：高敏感源码、brief/ignore 尚未治理、生成内容无人审查，或个人 connector 会把不同授权域资料混入同一 wiki 的场景。