观澜 (GuānLán)
中文 | English
《孟子·尽心上》"观水有术,必观其澜"——在信息的汪洋中洞察脉络与趋势。
观澜让 Agent 增量地构建并持续维护一个结构化、互相链接的知识 wiki,而不是每次提问都从原始文档临时检索(传统 RAG)。你只管投喂资料、提问、给方向;摘要、交叉引用、归档全交给 Agent。知识被"编译"一次后持续保鲜,随每篇新资料、每次提问而复利增长。
这是 Karpathy LLM Wiki 模式 的一个实现。
核心理念
- markdown 始终是唯一事实来源——整个知识库就是一组本地 markdown 文件,任何索引/图谱/缓存都是可幂等重建的派生物。
- Agent 全权拥有 wiki 层,人不直接写——人投喂、提问、给方向;生成与维护交给 Agent。
raw/只读不可变——Agent 只读原始资料、永不修改,保证事实可追溯。- 确定性优先——结构检查、断链、frontmatter 校验走脚本(零 LLM、可离线);需 LLM 的
ingest/query统一经 Agentao 运行时治理。
能做什么
| 命令 | 作用 | 需模型? |
|---|---|---|
guanlan init |
初始化一个知识库(确定性模板) | 否 |
guanlan ingest |
投喂一篇资料,Agent 生成/更新 wiki 页 | 是 |
guanlan query |
对知识库提问(--backfill 可把答案沉淀回 wiki) |
是 |
guanlan search |
整页全文检索(BM25 + 中文分词) | 否 |
guanlan check / health / lint |
校验 / 体检 / 结构 lint | 否 |
guanlan graph |
生成可交互的 [[wikilink]] 知识图谱 |
否 |
guanlan web |
在浏览器里浏览、问答、维护(可选叠加层) | 部分 |
guanlan mcp |
把 wiki 只读暴露给 MCP 客户端(可选叠加层) | 部分 |
还有
reindex(索引回填)、heal(缺失实体物化)、audit(语义审计:复核raw/已变但 wiki 未重综合的漂移源)、remove(源撤回:把误摄/已撤稿源移入.trash/)、convert(PDF/DOCX/… 转 markdown)等。逐命令细节见 用户指南。
安装
pip install guanlan-wiki
PyPI 发布名是
guanlan-wiki(裸名guanlan已被一个无关项目占用);安装后命令行与导入名仍是guanlan。需 Python 3.10+。
init/check/health/lint/graph/search零 LLM、可离线运行;ingest/query/ Web 问答需配置一个模型(经 Agentao 运行时)。
可选宿主(叠加层,按需装):
pip install 'guanlan-wiki[web]' # 浏览器宿主 guanlan web
pip install 'guanlan-wiki[mcp]' # 只读 MCP 服务端 guanlan mcp（需官方 SDK mcp>=2）
快速开始
# 1. 初始化一个知识库(确定性、零 LLM,可重复运行不覆盖)
guanlan init my-wiki
# 2. 投喂资料 / 提问(需配置模型)
guanlan -C my-wiki ingest path/to/source.md
guanlan -C my-wiki query "你的问题"
# 3. 维护(零 LLM、可离线)
guanlan -C my-wiki check # frontmatter / 断链 / 来源校验
guanlan -C my-wiki health # 桩页 + index↔磁盘同步
guanlan -C my-wiki lint # 孤儿页 / 断链 / 缺失实体
guanlan -C my-wiki graph # 写出 graph/graph.json + graph.html
在浏览器里用(可选):
pip install 'guanlan-wiki[web]'
guanlan -C my-wiki web # 起本地 Web 宿主,仅监听 127.0.0.1,默认开浏览器
浏览器里可:浏览 wiki 并跟随 [[wikilink]] 导航、跑 check·health·lint 看报告、看 graph、从 raw/ 触发 ingest 等写作业(含 heal 补全、audit 漂移复核、backfill 回填)、与 agent 只读多轮对话。仅供本机单用户——绝不要把端口暴露到网络。
完整上手见 用户指南 → 快速上手。
生成结构
my-wiki/
├── AGENTAO.md # Agent 行为约束 + 指针
├── SCHEMA.md # 本库 Schema:领域 / 启用页面类型 / 自定义规则
├── raw/ # 原始资料(只读,事实来源)
└── wiki/ # Agent 全权生成的知识层
├── index.md # 全量页面目录
├── log.md # append-only 时间线
└── overview.md # 跨资料活体综述
💡 知识库长起来后,可让 LLM 先分析当前库的真实状态、再据此更新
SCHEMA.md(领域边界 / 页面类型用法 / 命名与标签约定 / 演进中的组织偏向);含可直接复用的提示词,见 用户指南 → 快速上手 §1.1 让 LLM 辅助更新SCHEMA.md。
文档
- 📖 用户指南
docs/guide/—— 安装、上手、各命令、Web/MCP 宿主(中英双语) - 🏗️ 设计文档
docs/DESIGN.md—— 完整设计(面向开发,权威规格) - 📋 CHANGELOG.md —— 版本与里程碑进展
开发
uv run guanlan init /tmp/demo # 跑 CLI
uv run pytest # 跑测试
维护引擎是 skills/guanlan-wiki/(SKILL.md + references/conventions.md + 脚本),开发期命中 Agentao 的 repo-root skill 发现路径(<工作目录>/skills/),免安装。详见 CLAUDE.md。
许可证
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file guanlan_wiki-0.1.18.tar.gz.
File metadata
- Download URL: guanlan_wiki-0.1.18.tar.gz
- Upload date:
- Size: 7.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c37c85f75637e6e90326c3cf5d7200ae10ea0039ef82c95bc81788d2b5f2ecf3
|
|
| MD5 |
867f71504597a281081e763e5c9daa6d
|
|
| BLAKE2b-256 |
7bacb6e0a9e6bf4bb30db08c6c18a7eadcd0f0b0b259aa58925a82224540fc6c
|
Provenance
The following attestation bundles were made for guanlan_wiki-0.1.18.tar.gz:
Publisher:
release.yml on jin-bo/guanlan
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
guanlan_wiki-0.1.18.tar.gz -
Subject digest:
c37c85f75637e6e90326c3cf5d7200ae10ea0039ef82c95bc81788d2b5f2ecf3 - Sigstore transparency entry: 2291445631
- Sigstore integration time:
-
Permalink:
jin-bo/guanlan@aa9582a6b6e58cdeba83ce30847d9b6574dcb6a4 -
Branch / Tag:
refs/tags/v0.1.18 - Owner: https://github.com/jin-bo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@aa9582a6b6e58cdeba83ce30847d9b6574dcb6a4 -
Trigger Event:
push
-
Statement type:
File details
Details for the file guanlan_wiki-0.1.18-py3-none-any.whl.
File metadata
- Download URL: guanlan_wiki-0.1.18-py3-none-any.whl
- Upload date:
- Size: 3.4 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
14b6f6500cd1caafa8a4cc624b2ec3514bc6f6e3cde24107f35dc00a8de6c3b2
|
|
| MD5 |
7bd39cef792a7088b356554ccd55c5cb
|
|
| BLAKE2b-256 |
f369be5025c517a662f0acf880961adb329405f0b7409ddd4dd60c475a487f6c
|
Provenance
The following attestation bundles were made for guanlan_wiki-0.1.18-py3-none-any.whl:
Publisher:
release.yml on jin-bo/guanlan
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
guanlan_wiki-0.1.18-py3-none-any.whl -
Subject digest:
14b6f6500cd1caafa8a4cc624b2ec3514bc6f6e3cde24107f35dc00a8de6c3b2 - Sigstore transparency entry: 2291445638
- Sigstore integration time:
-
Permalink:
jin-bo/guanlan@aa9582a6b6e58cdeba83ce30847d9b6574dcb6a4 -
Branch / Tag:
refs/tags/v0.1.18 - Owner: https://github.com/jin-bo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@aa9582a6b6e58cdeba83ce30847d9b6574dcb6a4 -
Trigger Event:
push
-
Statement type:
