---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - openwiki
  - knowledge-management
topic: OpenWiki 定位、模式与知识格式
sources:
  - https://docs.langchain.com/oss/openwiki/overview
  - https://docs.langchain.com/oss/openwiki/quickstart
  - https://docs.langchain.com/oss/openwiki/code-mode
  - https://docs.langchain.com/oss/openwiki/personal-mode
  - https://docs.langchain.com/oss/openwiki/visualize
last_verified: 2026-08-11
---
# 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 数据流

```text
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 的场景。