guanlan: Instructions file for Claude Code

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: 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 before any non-trivial change.

Current status: released through v0.1.32; the roadmap is fully implemented — P2 minimal closed loop, P3 health/graph family, P4 optional host layer (Web + MCP + IM, through P4.17's Streamable HTTP transport, P4.18's move to MCP SDK v2 / protocol 2026-07-28, P4.19's read-only Web panel for the opposite direction — the external MCP servers agentao already injects into this KB — P4.20's in-browser rendering of ```flint chart-spec blocks into data charts, P4.21's IM host: a platform-agnostic core plus thin per-platform adapters, v1 = personal WeChat + Feishu, and P4.22's clickable citations: a zero-LLM /page command everywhere plus Feishu card callbacks that a click turns into a synthesized inbound message, so all five intake gates are reused and the Q&A path needed zero changes, and P4.24's MCP Skills publication: guanlan mcp also publishes one static read-only skill, guanlan-query, through the io.modelcontextprotocol/skills extension, and read_page gained an optional name so clients can follow [[links]]; the skill file lives in guanlan/mcp/published_skills/, deliberately not repo-root skills/, which is an Agentao discovery path), P5 retrieval + multi-format ingest, and every half-phase P2.1–P5.4. No roadmap spec remains unimplemented; per-phase flags, behavior, and red lines live in the docs/P*.md file for that phase, not here. P4.22's main path passed real-machine acceptance on 2026-08-17 (click → toast → the page comes back), but several items are still open — which WS frame type Feishu delivers card callbacks on (the code handles both, so the shim stays), the unauthorized-click and forwarded-card paths — so read docs/P4.22-IM可点引用.md §9 for what was actually observed before claiming any individual item is verified. P4.23 moved the runtime to agentao 0.5.3; the floor is now agentao[cli]>=0.5.18,<0.6. Since 0.5.10, a confirmation where agentao.transport.gate_note() is set (remote MCP skill consent) must be asked every time, never auto-allowed, and must not flip confirm_mode — Conversation._confirm_tool_cb / resolve_confirm enforce it, and IM (confirm_ui=False) denies at once (docs/P4.24-MCP技能发布.md appendix B). Before touching the embedded path, know that arun returning normally means neither "the model answered" nor "the turn wasn't stopped": agentao returns LLM errors, empty/truncated output and user stops ([Cancelled: …]) as ordinary strings. Conversation.turn() tells them apart via agent.last_turn — an incomplete turn stays a structured return, a cancelled one is re-raised as AgentCancelledError. Rationale in docs/P4.23-Agentao0.5.3接入.md.