guanlan-wiki 0.1.0__tar.gz

guanlan_wiki-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+# 推到 main 或对 main 发 PR 时跑：lint + 全量测试。
+# 全程离线——测试用 fake runner / monkeypatch，不打真实 LLM，无需任何 API key。
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# 同一分支/PR 的新推送取消旧的在跑任务，省额度。
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 装 uv（带依赖缓存）
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: 装 Python 3.12
+        run: uv python install 3.12
+
+      # ruff 用 uvx 临时拉，不进 lock；与本地 `uvx ruff check` 一致。
+      - name: Lint（ruff）
+        run: uvx ruff check guanlan tests
+
+      # --extra web 装上 fastapi/uvicorn/markdown，否则 test_web.py / test_aliases.py
+      # 会被 importorskip 跳过；dev 组（pytest）uv sync 默认带上。
+      - name: 装依赖
+        run: uv sync --extra web
+
+      - name: 跑测试
+        run: uv run --extra web pytest -q

guanlan_wiki-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release (PyPI)
+
+# 推 v* tag 时构建并发布到 PyPI。用 Trusted Publishing（OIDC）——仓库不存任何 token：
+# 需先在 PyPI 为项目 guanlan-wiki 配好 pending publisher（绑定本仓库 + 本 workflow +
+# environment 名 pypi），见 docs/发布到-PyPI.md。
+on:
+  push:
+    tags: ["v*"]
+
+# 默认不给任何权限；发布 job 单独申明 id-token: write 换取 OIDC 凭据。
+permissions: {}
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/guanlan-wiki
+    permissions:
+      id-token: write # Trusted Publishing 必需
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 装 uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: 构建 sdist + wheel
+        run: uv build
+
+      # 发布前再跑一遍 twine check，产物不合规就别上传。
+      - name: 校验产物
+        run: uvx twine check dist/*
+
+      - name: 发布到 PyPI（Trusted Publishing，免 token）
+        uses: pypa/gh-action-pypi-publish@release/v1

guanlan_wiki-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# macOS
+.DS_Store
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local agentao residue (from previous experiments in this dir, if any)
+.agentao/
+agentao.log
+agentao.log.*
+
+# Claude Code 本机运行时状态（scheduled_tasks.lock 含 sessionId / pid / 进程起始时间），
+# per-machine 不入仓——否则别的 checkout 会继承陈旧锁 + 本地会话元数据。
+.claude/
+
+# Qoder
+.qoder/
+
+# Dev-only sample wiki data & derived (local testing only — never pushed; see docs/DESIGN.md §4.7)
+# Templates live in examples/; only the repo-root sample config + data/derived dirs are ignored.
+/raw/
+/wiki/
+/graph/
+/workspace/
+
+# Repo-root sample config copied from examples/ (may carry machine paths / private dev settings).
+# Anchored to root so examples/AGENTAO.md and examples/SCHEMA.md stay tracked.
+/AGENTAO.md
+/SCHEMA.md

guanlan_wiki-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

guanlan_wiki-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+观澜 (GuānLán) is an implementation of the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): an Agent incrementally builds and maintains a structured, cross-linked markdown knowledge wiki instead of doing fresh RAG retrieval on every query. The full design (in Chinese) is the authoritative spec — read [`docs/DESIGN.md`](docs/DESIGN.md) before any non-trivial change.
+
+**Current status: P4 (optional local Web host).** P2's closed loop (`guanlan init` / `ingest` / `query` / `check` / `install-skill`, wired through Agentao) + P3's three on-demand zero-LLM maintenance tools (`guanlan health` / `lint` / `graph`) + P4's **optional** Web host (`guanlan web`, needs `pip install 'guanlan[web]'`) are all implemented. P4 puts the existing commands in a browser via a thin FastAPI/uvicorn layer (127.0.0.1-only, `workers=1`) under a `guanlan/web/` subpackage that carries *no business intelligence*: it reuses `run_ingest` / `run_check` / `run_health` / `run_lint` / `build_and_write_graph` / `pages.*` and an embedded read-only `Agentao` for chat. **Read/write split** (DESIGN §5.2): the only write job `ingest` reuses the P2 subprocess + single-writer gate (one background worker, FIFO); all Q&A (one-shot + multi-turn) goes through a read-only in-process embedded `Agentao` (`.arun`, token-streamed, memory-only). Web-side `raw/` writes, `query --backfill`, writable work-sessions, session persistence, multi-format ingest remain post-P4 (DESIGN §8). When adding features, match the phase boundaries in DESIGN §4.4 / §7.
+
+The **P2 spec** (module layout, deterministic gate, `raw/` snapshot + `check` contracts, exit codes, Agentao integration) is [`docs/P2-最小闭环.md`](docs/P2-最小闭环.md); the **P3 spec** (`pages.py` shared primitives with strict/lenient frontmatter tiers, `graph`/`health`/`lint` contracts, `EXIT_LINT_FINDINGS`, advisory-not-gate exit semantics) is [`docs/P3-健康与图谱.md`](docs/P3-健康与图谱.md); the **P4 spec** (`guanlan/web/` layout, the read/write split, single-worker `ingest` job, read-only embedded chat with the four embedding pitfalls + token-streaming transport contract, HTTP API + SSE contracts, no new exit codes) is [`docs/P4-Web宿主.md`](docs/P4-Web宿主.md) — together they document how the current code is structured. The **P3.1 spec** (optional `aliases` frontmatter feeding the single `pages.py` resolution point: `alias_index` / `link_resolution_index` / alias-aware `link_target_stems`, `check` uniqueness validation `aliases.collides_stem`/`aliases.duplicate`, alias edges in `graph`, Web `[[alias]]` linking — a zero-LLM half-phase enhancement, not a new milestone; P5 still = multi-format) is [`docs/P3.1-别名解析.md`](docs/P3.1-别名解析.md). Two **landing designs for P4 §10 deferred items** (specced, not yet implemented) are [`docs/P4.1-Web投喂.md`](docs/P4.1-Web投喂.md) (**P4.1** — `POST /api/raw` paste-to-save: a human source-add, *not* a gated agent write; serialized through the existing single-writer `JobQueue` to avoid the `run_guarded_write` `raw/` snapshot window; default no-overwrite, slug + `.md`) and [`docs/P4.2-会话落盘.md`](docs/P4.2-会话落盘.md) (**P4.2** — session persistence/restore: reuse `agentao.embedding.{save_session,load_session,list_sessions,delete_session}` under `<kb>/.agentao/sessions/`, conversation id → agentao UUID, lazy restore that re-applies the read-only two-point posture; thin adaptation over agentao's *snapshot-file* semantics — dedup the catalog by `session_id` and prune to one snapshot per session *before* each save (since `save_session` rotates by file-count right after writing) so the 10-*file* rotation cap behaves as a 10-*session* cap). Both are zero-LLM Web-host half-phases that stay inside the P4 boundary (no new exit codes, no SSE changes, no writable sessions).
+
+## Commands
+
+```bash
+uv run guanlan init /tmp/demo            # scaffold a knowledge base (deterministic, zero-LLM)
+uv run guanlan -C /tmp/demo check        # deterministic validation (frontmatter / broken links / sources)
+uv run guanlan -C /tmp/demo health       # P3: stub pages + index↔disk sync (advisory; --strict → exit 6)
+uv run guanlan -C /tmp/demo lint         # P3: orphans / broken links / missing entities (advisory)
+uv run guanlan -C /tmp/demo graph        # P3: write graph/graph.json + graph.html (--json-only skips html)
+uv run guanlan -C /tmp/demo web --no-browser   # P4: optional local Web host (needs guanlan[web]; 127.0.0.1 only)
+uv run pytest                            # run all tests
+uv run pytest tests/test_web.py          # P4 Web host tests (skipped if guanlan[web] absent)
+uv run pytest tests/test_init.py::test_init_is_idempotent_and_non_destructive  # single test
+```
+
+(`ingest` / `query` and the Web host's chat drive Agentao + the skill and need a configured model; `init` / `check` / `health` / `lint` / `graph` are the zero-LLM ones runnable offline. `guanlan web` needs the optional `web` extra: `uv pip install 'fastapi>=0.110' 'uvicorn>=0.29' 'markdown>=3'`, or `pip install 'guanlan[web]'`.)
+
+Python 3.12+, dependencies managed by `uv` (see `uv.lock`). The package depends on `agentao` (the governed Agent runtime executing LLM-driven `ingest`/`query` via subprocess, and — in P4 — embedded read-only for Web chat). The `web` extra (fastapi/uvicorn/markdown) is optional and not part of the core install.
+
+## Architecture
+
+The project deliberately separates three concerns. Internalize this split before editing — most design decisions follow from it.
+
+1. **`guanlan/` — the thin CLI wrapper (this package).** It carries *no business intelligence*. Its only jobs are: (a) `init` (deterministic template generation, zero LLM), and (b) in P2, orchestrating Agentao + the skill and enforcing deterministic gates on write operations. `cli.py` is argparse-only; `init.py` does the file generation.
+
+2. **`skills/guanlan-wiki/` — the maintenance engine.** This is where the actual wiki-maintenance workflows live (`SKILL.md` = workflows, `references/conventions.md` = default page/frontmatter/naming conventions, and `scripts/*.py` = deterministic checks, to be added in P2/P3). The engine is shipped/installed *once* and is **not** copied into each knowledge base. It is intended to run under Agentao's skill discovery.
+
+3. **User knowledge base (generated by `guanlan init`).** Holds only data + per-base config: `AGENTAO.md` (Agent behavior hard-constraints + pointers), `SCHEMA.md` (this base's domain/page-types/custom rules), `raw/` (read-only sources), `wiki/` (Agent-owned generated layer: `index.md`, `log.md`, `overview.md`, plus `sources/ entities/ concepts/ syntheses/`).
+
+### Two run modes (do not mix them)
+
+- **Development = repo root *is* a sample wiki.** Set Agentao's `working_directory` to this repo root; `skills/guanlan-wiki/` then hits Agentao's repo-root discovery path (`<wd>/skills/`), so the engine is found with no install. Sample wiki data (`raw/`, `wiki/`, `graph/`) and the dev-copied `AGENTAO.md`/`SCHEMA.md` are `.gitignore`d — they may contain machine-local paths and never get committed.
+- **External real wiki = global install.** The skill is installed to `~/.agentao/skills/guanlan-wiki/` (cwd-independent), with the user's base as `working_directory`. There is intentionally no "discover repo skills/ from an external wiki" path.
+
+### init template duality (`guanlan/init.py`)
+
+`init` copies a template tree. `_templates_dir()` resolves two locations by priority: bundled `guanlan/_templates/` (installed wheel) → repo-root `examples/` (development). The wheel's `force-include` in `pyproject.toml` copies `examples/{AGENTAO.md,SCHEMA.md,wiki}` into `guanlan/_templates/` at build time — so **`examples/` is the single source of truth for init templates**; edit templates there, not in `_templates/`. `init` never overwrites existing files (idempotent) and substitutes a `__DATE__` token in `wiki/` seed files.
+
+## Invariants that drive the design
+
+These come up repeatedly in DESIGN and the skill; preserve them in any change:
+
+- **Markdown is the only source of truth.** Any index / graph / cache is a derivative that must be idempotently rebuildable from markdown — it never becomes authoritative.
+- **`raw/` is read-only and immutable.** In P2 this is enforced *deterministically by the wrapper* via a before/after snapshot (filename + size + mtime, SHA256 if needed) around the Agentao call — not by permission config, since a snapshot also catches shell `mv`/`rm`/`python` writes that bypass `write_file`.
+- **Zero-LLM scripts vs. LLM-only workflows.** Deterministic work (frontmatter/wikilink/structure checks, graph building) is plain Python scripts with no LLM. LLM is used *only* for `ingest` and `query`, and always via the Agentao runtime — scripts must never carry their own LLM client or API keys.
+- **`SCHEMA.md` / `AGENTAO.md` / `index.md` / `log.md` / `overview.md` are config, not content** — exclude them from index/graph/lint scans.
+- **Data conventions** (frontmatter fields, kebab-case vs TitleCase naming, `[[wikilink]]` resolution, `index.md`/`log.md` formats, the `## ⚠️ 矛盾与存疑` contradiction-marking format) are specified in `skills/guanlan-wiki/references/conventions.md` and DESIGN §4.5. A base's `SCHEMA.md` may override defaults.
+
+## Conventions
+
+The codebase (code comments, docstrings, design docs, user-facing CLI output) is written in **Chinese**. Match that when editing existing files.

guanlan_wiki-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2026 jin-bo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

guanlan_wiki-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: guanlan-wiki
+Version: 0.1.0
+Summary: 观澜 — 增量构建并维护结构化、互链的 markdown 知识 wiki（Karpathy LLM Wiki 模式）
+Project-URL: Homepage, https://github.com/jin-bo/guanlan
+Project-URL: Repository, https://github.com/jin-bo/guanlan
+Project-URL: Issues, https://github.com/jin-bo/guanlan/issues
+Author-email: jin-bo <jinbobo@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agentao,karpathy,knowledge-base,llm,markdown,rag,wiki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Requires-Dist: agentao[cli]>=0.4.8
+Requires-Dist: pyyaml>=6
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: markdown>=3; extra == 'web'
+Requires-Dist: uvicorn>=0.29; extra == 'web'
+Description-Content-Type: text/markdown
+
+# 观澜 (GuānLán)
+
+> 《孟子·尽心上》"观水有术，必观其澜"——在信息的汪洋中洞察脉络与趋势。
+
+观澜是 [Karpathy LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 的一个实现：让 Agent **增量地构建并持续维护一个结构化、互相链接的知识 wiki**，而不是每次提问都从原始文档临时检索（传统 RAG）。知识被"编译"一次后持续保鲜，随每篇新资料、每次提问而复利增长。
+
+- **markdown 始终是唯一事实来源**——整个知识库就是一组本地 markdown 文件，任何索引/图谱/缓存都是可幂等重建的派生物。
+- **Agent 全权拥有 wiki 层，人不直接写**——人负责投喂资料、提问、给方向；摘要、交叉引用、归档全交给 Agent。
+- **`raw/` 只读不可变**——Agent 只读原始资料，永不修改，保证事实可追溯。
+- **确定性优先**——结构检查、断链、frontmatter 校验走脚本（零 LLM）；需 LLM 的 ingest/query 统一经 Agentao 运行时治理。
+
+完整设计见 [`docs/DESIGN.md`](docs/DESIGN.md)。
+
+## 状态
+
+🚀 **P4（Web 宿主，可选叠加层）** —— 在 P2 最小闭环（`guanlan init` / `ingest` / `query` / `check` / `install-skill`）与 P3 维护工具（`health` / `lint` / `graph`）之上，新增一个**可选**的本地 Web 宿主，把上述命令搬进浏览器：
+
+- `guanlan web` —— 起一个仅监听 `127.0.0.1` 的本地 Web 宿主（需 `pip install 'guanlan[web]'`）。浏览 wiki（`[[wikilink]]` 可点击导航）/ 跑 check·health·lint 看报告 / 看 graph / 从 `raw/` 选一篇触发 ingest（单 worker 串行，轮询结果）/ 与 agent **只读多轮对话**（token 流式）。
+- 它是 **MVP 之后的可选叠加层**：不装 `guanlan[web]`、不起 `guanlan web`，整套东西照旧用 CLI 跑通。markdown 仍是唯一事实来源，Web 只是 ingest 与问答的另一个入口、wiki 的只读浏览器。
+- **读写分线**：唯一写作业 `ingest` 复用 P2 子进程 + 单写者门禁；所有问答（一次性单轮 + 多轮）走只读进程内嵌入 `Agentao`（默认只读、不过门禁、仅内存）。
+
+P3 三个零-LLM 维护工具（advisory）：
+
+- `guanlan health` —— stub 页面 + index↔disk 同步（`--strict` → 退出码 6）。
+- `guanlan lint` —— 孤儿页 / 断链 / 缺失实体。
+- `guanlan graph` —— 确定性 `[[wikilink]]` 图谱 → `graph/graph.json` + 自包含 `graph/graph.html`（`--json-only` 跳过 html）。
+
+**P3.1 别名解析（零-LLM 增强）** —— entity/concept 页可在 frontmatter 声明可选 `aliases`，让别名进入 `[[wikilink]]` 解析命名空间（与页名同口径、大小写不敏感）：`[[大模型]]` / `[[LLM]]` 都解析到声明它们的页，**消假断链**（check / lint / graph / Web 一致）、**补 CJK 同义召回**（别名纳入 query 2-gram 与 ingest 去重）。别名全局唯一由 `check` 确定性校验（撞页名 / 重复 → 阻断写门禁）。这不是新里程碑，P5 仍是多格式与自动化。细化见 [`docs/P3.1-别名解析.md`](docs/P3.1-别名解析.md)。
+
+Web 端写 `raw/`、`query --backfill`、可写多轮工作会话、会话落盘、多格式 ingest 留待 P4 之后（见 DESIGN §8 与 `docs/P4-Web宿主.md` §10）。别名自动物化建页（`heal`）、同义词表、向量检索按需驱动、另开方案。
+
+## 快速开始
+
+```bash
+# 在空目录初始化一个知识库（生成 AGENTAO.md / SCHEMA.md / raw/ / wiki/）
+guanlan init my-wiki
+
+# 或就地初始化当前目录
+guanlan init
+```
+
+`init` 是确定性的（零 LLM），已存在的文件不会被覆盖，可安全重复运行。
+
+投喂资料、提问、维护：
+
+```bash
+# 投喂资料 / 提问（需配置模型，经 Agentao 运行时）
+guanlan -C my-wiki ingest path/to/source.md
+guanlan -C my-wiki query "..."
+
+# 零-LLM、可离线运行的确定性工具
+guanlan -C my-wiki check     # frontmatter / 断链 / 来源校验
+guanlan -C my-wiki health    # stub 页面 + index↔disk 同步（--strict → exit 6）
+guanlan -C my-wiki lint      # 孤儿页 / 断链 / 缺失实体
+guanlan -C my-wiki graph     # 写出 graph/graph.json + graph.html（--json-only 跳过 html）
+```
+
+可选 Web 宿主（叠加层，需先装 `guanlan[web]`）：
+
+```bash
+pip install 'guanlan[web]'          # 装可选依赖（fastapi / uvicorn / markdown）
+guanlan -C my-wiki web              # 起本地 Web 宿主，仅监听 127.0.0.1，默认开浏览器
+guanlan -C my-wiki web --port 9000 --no-browser   # 换端口 / 不开浏览器
+```
+
+浏览器里可：浏览 wiki 并跟随 `[[wikilink]]` 导航、跑 check·health·lint 看报告、看 graph、
+从 `raw/` 选一篇触发 ingest（轮询结果）、与 agent 只读多轮对话（token 流式）。
+**仅供本机单用户**——绝不要把该端口暴露到网络。
+
+生成结构：
+
+```
+my-wiki/
+├── AGENTAO.md       # Agent 行为约束 + 指针
+├── SCHEMA.md        # 本库 Schema：领域 / 启用页面类型 / 自定义规则
+├── raw/             # 原始资料（只读，事实来源）
+└── wiki/            # Agent 全权生成的知识层
+    ├── index.md     # 全量页面目录
+    ├── log.md       # append-only 时间线
+    └── overview.md  # 跨资料活体综述
+```
+
+## 开发
+
+```bash
+uv run guanlan init /tmp/demo   # 跑 CLI
+uv run pytest                   # 跑测试
+```
+
+维护引擎是 `skills/guanlan-wiki/`（`SKILL.md` + `references/conventions.md` + 脚本），
+开发期命中 Agentao 的 repo-root skill 发现路径（`<工作目录>/skills/`），免安装。
+
+## 许可证
+
+[Apache License 2.0](LICENSE)

guanlan_wiki-0.1.0/README.md

@@ -0,0 +1,95 @@
+# 观澜 (GuānLán)
+
+> 《孟子·尽心上》"观水有术，必观其澜"——在信息的汪洋中洞察脉络与趋势。
+
+观澜是 [Karpathy LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 的一个实现：让 Agent **增量地构建并持续维护一个结构化、互相链接的知识 wiki**，而不是每次提问都从原始文档临时检索（传统 RAG）。知识被"编译"一次后持续保鲜，随每篇新资料、每次提问而复利增长。
+
+- **markdown 始终是唯一事实来源**——整个知识库就是一组本地 markdown 文件，任何索引/图谱/缓存都是可幂等重建的派生物。
+- **Agent 全权拥有 wiki 层，人不直接写**——人负责投喂资料、提问、给方向；摘要、交叉引用、归档全交给 Agent。
+- **`raw/` 只读不可变**——Agent 只读原始资料，永不修改，保证事实可追溯。
+- **确定性优先**——结构检查、断链、frontmatter 校验走脚本（零 LLM）；需 LLM 的 ingest/query 统一经 Agentao 运行时治理。
+
+完整设计见 [`docs/DESIGN.md`](docs/DESIGN.md)。
+
+## 状态
+
+🚀 **P4（Web 宿主，可选叠加层）** —— 在 P2 最小闭环（`guanlan init` / `ingest` / `query` / `check` / `install-skill`）与 P3 维护工具（`health` / `lint` / `graph`）之上，新增一个**可选**的本地 Web 宿主，把上述命令搬进浏览器：
+
+- `guanlan web` —— 起一个仅监听 `127.0.0.1` 的本地 Web 宿主（需 `pip install 'guanlan[web]'`）。浏览 wiki（`[[wikilink]]` 可点击导航）/ 跑 check·health·lint 看报告 / 看 graph / 从 `raw/` 选一篇触发 ingest（单 worker 串行，轮询结果）/ 与 agent **只读多轮对话**（token 流式）。
+- 它是 **MVP 之后的可选叠加层**：不装 `guanlan[web]`、不起 `guanlan web`，整套东西照旧用 CLI 跑通。markdown 仍是唯一事实来源，Web 只是 ingest 与问答的另一个入口、wiki 的只读浏览器。
+- **读写分线**：唯一写作业 `ingest` 复用 P2 子进程 + 单写者门禁；所有问答（一次性单轮 + 多轮）走只读进程内嵌入 `Agentao`（默认只读、不过门禁、仅内存）。
+
+P3 三个零-LLM 维护工具（advisory）：
+
+- `guanlan health` —— stub 页面 + index↔disk 同步（`--strict` → 退出码 6）。
+- `guanlan lint` —— 孤儿页 / 断链 / 缺失实体。
+- `guanlan graph` —— 确定性 `[[wikilink]]` 图谱 → `graph/graph.json` + 自包含 `graph/graph.html`（`--json-only` 跳过 html）。
+
+**P3.1 别名解析（零-LLM 增强）** —— entity/concept 页可在 frontmatter 声明可选 `aliases`，让别名进入 `[[wikilink]]` 解析命名空间（与页名同口径、大小写不敏感）：`[[大模型]]` / `[[LLM]]` 都解析到声明它们的页，**消假断链**（check / lint / graph / Web 一致）、**补 CJK 同义召回**（别名纳入 query 2-gram 与 ingest 去重）。别名全局唯一由 `check` 确定性校验（撞页名 / 重复 → 阻断写门禁）。这不是新里程碑，P5 仍是多格式与自动化。细化见 [`docs/P3.1-别名解析.md`](docs/P3.1-别名解析.md)。
+
+Web 端写 `raw/`、`query --backfill`、可写多轮工作会话、会话落盘、多格式 ingest 留待 P4 之后（见 DESIGN §8 与 `docs/P4-Web宿主.md` §10）。别名自动物化建页（`heal`）、同义词表、向量检索按需驱动、另开方案。
+
+## 快速开始
+
+```bash
+# 在空目录初始化一个知识库（生成 AGENTAO.md / SCHEMA.md / raw/ / wiki/）
+guanlan init my-wiki
+
+# 或就地初始化当前目录
+guanlan init
+```
+
+`init` 是确定性的（零 LLM），已存在的文件不会被覆盖，可安全重复运行。
+
+投喂资料、提问、维护：
+
+```bash
+# 投喂资料 / 提问（需配置模型，经 Agentao 运行时）
+guanlan -C my-wiki ingest path/to/source.md
+guanlan -C my-wiki query "..."
+
+# 零-LLM、可离线运行的确定性工具
+guanlan -C my-wiki check     # frontmatter / 断链 / 来源校验
+guanlan -C my-wiki health    # stub 页面 + index↔disk 同步（--strict → exit 6）
+guanlan -C my-wiki lint      # 孤儿页 / 断链 / 缺失实体
+guanlan -C my-wiki graph     # 写出 graph/graph.json + graph.html（--json-only 跳过 html）
+```
+
+可选 Web 宿主（叠加层，需先装 `guanlan[web]`）：
+
+```bash
+pip install 'guanlan[web]'          # 装可选依赖（fastapi / uvicorn / markdown）
+guanlan -C my-wiki web              # 起本地 Web 宿主，仅监听 127.0.0.1，默认开浏览器
+guanlan -C my-wiki web --port 9000 --no-browser   # 换端口 / 不开浏览器
+```
+
+浏览器里可：浏览 wiki 并跟随 `[[wikilink]]` 导航、跑 check·health·lint 看报告、看 graph、
+从 `raw/` 选一篇触发 ingest（轮询结果）、与 agent 只读多轮对话（token 流式）。
+**仅供本机单用户**——绝不要把该端口暴露到网络。
+
+生成结构：
+
+```
+my-wiki/
+├── AGENTAO.md       # Agent 行为约束 + 指针
+├── SCHEMA.md        # 本库 Schema：领域 / 启用页面类型 / 自定义规则
+├── raw/             # 原始资料（只读，事实来源）
+└── wiki/            # Agent 全权生成的知识层
+    ├── index.md     # 全量页面目录
+    ├── log.md       # append-only 时间线
+    └── overview.md  # 跨资料活体综述
+```
+
+## 开发
+
+```bash
+uv run guanlan init /tmp/demo   # 跑 CLI
+uv run pytest                   # 跑测试
+```
+
+维护引擎是 `skills/guanlan-wiki/`（`SKILL.md` + `references/conventions.md` + 脚本），
+开发期命中 Agentao 的 repo-root skill 发现路径（`<工作目录>/skills/`），免安装。
+
+## 许可证
+
+[Apache License 2.0](LICENSE)