smart_brain 0.1.2 → 0.2.0

data/docs/user_guide.md

@@ -0,0 +1,546 @@
+# SmartBrain + SmartRAG 用户指南
+
+> SmartBrain v0.1.4 · 记忆运行时 + 上下文编排器
+> 配套 SmartRAG · 资源 RAG 后端（向量 + FTS + RRF + rerank）
+
+---
+
+## 1. 这是什么
+
+**SmartBrain** 是一个 **Agent Memory Runtime（记忆运行时）+ Context Composer（上下文调度器）**：把对话事件、工具结果、结构化记忆转化为**可检索、可治理、可解释**的长期记忆，并在每轮对话前为模型装配「最小充分上下文」。
+
+**SmartRAG** 是它的**资源知识库后端**：对文档/网页/仓库做分块、embedding、FTS、混合检索与 rerank。
+
+两者分工清晰：
+
+| | SmartBrain 管 | SmartRAG 管 |
+|---|---|---|
+| 对话记忆 | ✅ turn / message / tool_call / refs | — |
+| 结构化记忆 | ✅ decisions / tasks / goals / entities / profile / cases / patterns | — |
+| 知识治理 | ✅ 思维分层 + 生命周期 + KG + Fact-check + Brief | — |
+| 资源检索 | 通过 adapter 调用 SmartRAG | ✅ 文档/网页/仓库 RAG |
+
+SmartBrain 有三种用法，**共享同一套能力**：
+1. **Ruby 库**（嵌进任意 Ruby/Agent 进程）
+2. **CLI**（`smart_brain` 命令，shell 或 `! smart_brain ...`）
+3. **MCP / HTTP**（Claude Code、Cursor 等 agent 原生调用）
+
+---
+
+## 2. 安装
+
+```bash
+cd /root/smart_brain
+bundle install           # 装依赖（sequel/pg/sinatra/puma/...）
+bundle exec ruby -Ilib -e "require 'smart_brain'; puts SmartBrain::VERSION"
+```
+
+可选能力按需开启（默认零外部依赖即可运行）：
+
+| 能力 | 需要 | 开启方式 |
+|---|---|---|
+| 持久化（跨重启记忆） | PostgreSQL | `SMARTBRAIN_BACKEND=postgres` |
+| LLM 真摘要 / rerank | Ollama（或 OpenAI 兼容端点） | `SMARTBRAIN_LLM_PROVIDER=ollama` |
+| 资源 RAG | SmartRAG 实例 | `SmartBrain.configure(smart_rag_client: ...)` |
+
+---
+
+## 3. 三十秒快速开始
+
+### 3.1 Ruby 库
+
+```ruby
+require 'smart_brain'
+SmartBrain.configure
+
+# 1) 提交一轮对话（写记忆）
+SmartBrain.commit_turn(
+  session_id: 'demo',
+  turn_events: {
+    messages: [{ role: 'user', content: '我们用 Postgres 做持久化' }],
+    decisions: [{ key: 'decision:db:storage', decision: '默认用 Postgres' }],
+    entities:  [{ key: 'entity:db:pg', name: 'Postgres', canonical: 'postgres', kind: 'db', remember: true }]
+  }
+)
+
+# 2) 下一轮前，装配上下文（带证据、可解释）
+context = SmartBrain.compose_context(
+  session_id: 'demo',
+  user_message: '持久化方案是什么？'
+)
+
+puts context[:working_summary]      # 滚动摘要
+puts context[:evidence].size        # 召回的证据（memory + 可选 resource）
+puts context.dig(:debug, :trace)    # request_id → plan_id → context_id 全链路
+```
+
+### 3.2 多 Scope 调用
+
+跨会话共享项目记忆时，显式传入 domain 和读写 scope：
+
+```ruby
+scope_context = {
+  read: [
+    { type: 'global', id: 'default' },
+    { type: 'project', id: 'project-001' },
+    { type: 'task', id: 'task-030' }
+  ],
+  write: [{ type: 'project', id: 'project-001' }, { type: 'task', id: 'task-030' }],
+  default_write: { type: 'task', id: 'task-030' }
+}
+
+SmartBrain.commit_turn(
+  domain_id: 'tenant-a', session_id: 'conversation-1', scope_context: scope_context,
+  turn_events: { decisions: [{ key: 'decision:db', decision: 'use PostgreSQL' }] }
+)
+```
+
+`write` 必须属于 `read`，`default_write` 必须属于 `write`。单条结构化记忆的 `scope_ref` 只能指向 `write` 中的 scope。传 `scope_context` 时不能省略 `domain_id`；旧调用同时省略二者时，仍映射到隔离的 `legacy/session:<session_id>`。
+
+### 3.3 CLI
+
+```bash
+# 写记忆
+smart_brain commit --data '{
+  "session_id": "demo",
+  "turn_events": {
+    "messages": [{"role":"user","content":"用 Postgres"}],
+    "decisions": [{"key":"decision:db:storage","decision":"默认用 Postgres"}]
+  }
+}'
+
+# 召回 + 装配上下文
+smart_brain compose --data '{"session_id":"demo","user_message":"持久化方案？"}'
+
+# 直接搜记忆
+smart_brain search --data '{"session_id":"demo","query":"Postgres"}'
+
+# 状态
+smart_brain status
+```
+
+> 提示：`--data` 也可省略，从 stdin 读 JSON：`echo '{...}' | smart_brain search`。
+
+### 3.4 MCP（接 Claude Code / Cursor）
+
+```bash
+smart_brain mcp        # stdio JSON-RPC，19 个工具
+```
+
+Claude Code 配置（`~/.config/claude/claude_desktop_config.json` 或项目 `.mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "smart_brain": {
+      "command": "/path/to/smart_brain/exe/smart_brain",
+      "args": ["mcp"],
+      "env": { "SMARTBRAIN_BACKEND": "postgres" }
+    }
+  }
+}
+```
+
+详见 [`docs/mcp.md`](mcp.md)。
+
+---
+
+## 4. 核心工作流：commit → compose 循环
+
+每个 session 是一个「记忆宫殿」。**每轮对话两步**：
+
+```
+用户消息
+   │
+   ├──(读)──► compose_context(session_id, user_message)
+   │            │
+   │            ├─ Plan：RetrievalPlanner 生成检索计划（是否需要资源检索）
+   │            ├─ Retrieve：memory FTS + relational + (可选) SmartRAG
+   │            ├─ Fuse：去重 + rerank + diversity + token 预算
+   │            └─ Compose：产出 ContextPackage
+   │
+   ▼ 模型回复
+   │
+   └──(写)──► commit_turn(session_id, turn_events)
+                │
+                ├─ EventStore：记录真相（turn/messages/refs）
+                ├─ Extract：抽取结构化记忆（门控）
+                ├─ KG：抽取三元组（turn_events[:edges]）
+                └─ Consolidate：更新 working_summary（可走 LLM）
+```
+
+- **`compose_context` 之前调用**，把证据喂给模型；
+- **`commit_turn` 在助手回复之后调用**，沉淀本轮。
+
+### ContextPackage 结构
+
+| 字段 | 含义 |
+|---|---|
+| `working_summary` | 滚动摘要（模板或 LLM） |
+| `recent_turns` | 最近窗口对话 |
+| `evidence` | 召回证据（memory/resource/graph，带 source/score/tier/mode） |
+| `constraints` | token 预算、diversity、截断配置 |
+| `debug.trace` | `context_id / request_id / plan_id` 全链路 |
+| `debug.why_selected` | 每条证据为何入选 |
+
+---
+
+## 5. `turn_events`：每轮可以写入什么
+
+`commit_turn` 的 `turn_events` 是一个 hash，支持以下键（**全部可选**，按需传）：
+
+| 键 | 类型 | 说明 | 写入门控 |
+|---|---|---|---|
+| `messages` | `[{role, content}]` | 对话消息（user/assistant/tool） | 必写（事件层） |
+| `tasks` | `[{key, title, status}]` | 任务（todo/doing/done/blocked） | 必写 |
+| `decisions` | `[{key, decision}]` | 决策/承诺 | 必写 |
+| `goals` | `[{key, goal}]` | 长期目标 | 条件写 |
+| `events` | `[{key, title}]` | 里程碑/异常 | 条件写 |
+| `preferences` | `[{key, value, confirmed}]` | 偏好（需 `confirmed:true`） | 条件写 |
+| `profile` | `[{key, facts:[...]}]` | 用户/主体画像 | 条件写 |
+| `cases` | `[{key, problem, solution, outcome}]` | 案例/经验 | 条件写 |
+| `patterns` | `[{key, rule}]` | 归纳出的模式/规则 | 条件写 |
+| `entities` | `[{key, name, canonical, kind, remember}]` | 实体（频率/结构/显式门控） | 条件写 |
+| `retractions` | `[{type, key, reason}]` | 撤回旧事实 | 覆盖旧条目为 retracted |
+| `refs` | `[{ref_type, ref_uri, ref_meta_json}]` | 引用（file/url/artifact） | 必写（事件层） |
+| `edges` | `[{subject, predicate, object}]` | **KG 三元组** | 写入 kg_edges |
+
+**key 规则**（保证同一事实落到同一 key）：`<type>:<scope>:<name>`，如 `decision:smartbrain:storage`、`task:mvp:bootstrap`、`entity:db:postgres`。
+
+---
+
+## 6. 记忆模型：类型、分层、生命周期
+
+### 6.1 九种记忆类型
+
+`profile / preferences / goals / tasks / decisions / entities / events / cases / patterns`（见 `docs/memory_types.md`）。
+
+### 6.2 思维分层（Mind Model）
+
+每条记忆带一个 `tier`，context 装配按优先级 `dao_tian → dao_ren → shu → qi → evidence`：
+
+| Tier | 含义 | 默认 type 映射 |
+|---|---|---|
+| `dao_tian` 天道 | 不可变根本原则（**仅手动钉入**） | — |
+| `dao_ren` 人道 | 经验规则/架构决策 | decisions / patterns / profile |
+| `shu` 术 | 工具/任务技巧 | tasks / goals |
+| `qi` 器 | 具体示例/配置 | cases / preferences |
+| `evidence` 证据 | 原始观察 | entities / events |
+
+### 6.3 两个正交的状态轴
+
+- **`status`（冲突轴）**：`active / superseded / retracted` —— preferences/goals/tasks 覆盖旧值；retraction 撤回。
+- **`lifecycle_status`（治理轴）**：`raw / candidate / promoted / demoted` —— 知识生命周期。
+
+### 6.4 知识生命周期（Stage-1）
+
+```
+evidence ──distill──► candidate ──gate──► promote(promoted) ──demote──► demoted
+```
+
+- **distill**：从 evidence 提炼一条候选知识（仅 `dao_ren`/`qi` 层可蒸馏）。
+- **gate**：只读检查是否达 promote 门槛（默认 ≥ `lifecycle.min_supporting_refs` 条支撑，或 reviewer=human）。
+- **promote**：gate 强制，提升为 `promoted`（写入 `knowledge_events` 审计）。
+- **demote**：evidence-backed 降级（`reason_type`: contradicted/obsolete/superseded）。
+
+默认 `candidate`/`demoted` 不进自动 context（只有 `raw`/`promoted` 进）。
+
+---
+
+## 7. 知识图谱（KG）
+
+三元组 `subject-predicate-object` + **时态有效性**（`valid_from`/`valid_to`），与 memory_items 正交。
+
+```ruby
+# 写入（commit_turn 时随 edges 传入，或单独加）
+SmartBrain.kg_add(session_id: 'demo', subject: 'postgres', predicate: 'uses', object: 'jsonb')
+
+# 查询（支持 subject/predicate/object 过滤，默认仅 active）
+SmartBrain.kg_query(session_id: 'demo', subject: 'postgres')
+
+# 失效（置 valid_to + status=invalidated）
+SmartBrain.kg_invalidate(edge_id: id, reason: 'obsolete')
+
+SmartBrain.kg_stats(session_id: 'demo')   # {total:, active:, invalidated:}
+SmartBrain.kg_timeline(session_id: 'demo', subject: 'postgres')
+```
+
+KG 会自动**反馈到检索**：`compose_context` 时若 query 提到某 entity，其相关边会作为 `mode:'graph'` 证据出现。
+
+CLI：`smart_brain kg <add|query|invalidate|stats> --data '{...}'`。
+
+---
+
+## 8. 事实核查（Fact-check）
+
+**离线、零 LLM、零网络**的矛盾检测，扫描一段文本 vs session 的 entities + KG：
+
+| 类型 | 触发 |
+|---|---|
+| `SimilarNameConflict` | 文本 token 与已知 entity 的 Levenshtein 距离 ≤ 阈值（默认 2） |
+| `RelationContradiction` | 文本提到某 active triple 的两端 + 否定 cue（stopped/不再/弃用…） |
+| `StaleFact` | 文本引用了已失效（`valid_to < now`）的 triple |
+
+```ruby
+SmartBrain.fact_check(session_id: 'demo', text: '我们停用了 postgres 的 jsonb')
+# => {findings:[...], counts:{total:, similar_name:, relation_contradiction:, stale_fact:}}
+```
+
+CLI：`echo '{"session_id":"demo","text":"..."}' | smart_brain fact-check`。
+建议在 assert 新关系前先 `fact_check`（MCP `instructions` 已内置此规则）。
+
+---
+
+## 9. Brief / wake-up / resume
+
+**确定性、citation-first、不写 DB、不调 LLM**（默认）的认知快照：
+
+```ruby
+# 完整快照（每条 key_fact 带 memory_item_id + source_turn_id 引用）
+SmartBrain.brief(session_id: 'demo', query: '当前状态')
+# => {summary, key_facts, evidence, entities, unresolved, uncertainty, next_actions}
+
+# 最小恢复负载（会话重启时用）
+SmartBrain.wake_up(session_id: 'demo')
+# => {l0:{identity, principles, preferences}, l1:{goals_decisions, summary}}
+
+# 模糊找会话
+SmartBrain.resume(query: 'demo')   # => [{session_id, recent_decisions, next_actions}]
+```
+
+CLI：`smart_brain brief --data '{...}'`、`smart_brain wake-up --data '{...}'`。
+
+---
+
+## 10. 存储后端
+
+| | memory（默认） | postgres |
+|---|---|---|
+| 持久化 | 进程内，重启丢 | ✅ 跨进程/重启 |
+| FTS | 子串匹配 | ✅ `memory_chunks` GIN 索引（中文按字符 unigram 命中） |
+| 适用 | 开发/测试/纯库 | 生产 / agent 工具 |
+
+切换：
+
+```bash
+# 方式一：环境变量
+export SMARTBRAIN_BACKEND=postgres
+export SMARTBRAIN_DB_NAME=smart_brain_development   # 其余 SMARTBRAIN_DB_{HOST,PORT,USER,PASSWORD}
+
+# 方式二：config/brain.yml
+# storage:
+#   backend: postgres
+```
+
+**首次使用 Postgres**：建角色与库（一次性）：
+
+```bash
+sudo -u postgres createuser -d smart_brain
+sudo -u postgres psql -c "ALTER USER smart_brain PASSWORD 'smart_brain';"
+sudo -u postgres createdb -O smart_brain smart_brain_development
+smart_brain migrate          # 自动建表（幂等）
+```
+
+> SmartBrain 在 `backend=postgres` 启动时会**自动 migrate**（幂等），无需手动建表；`smart_brain migrate` 用于单独执行。
+
+---
+
+## 11. LLM 集成（可选）
+
+默认 `provider: stub`（确定性、零网络）：summary 走模板、rerank 走词法。切到真实 LLM 后：
+
+| 能力 | stub | ollama/openai |
+|---|---|---|
+| working_summary | 模板 | ✅ 真摘要（带模板兜底，`summary_method` 标注） |
+| Fusion rerank | 词法 | ✅ LLM-as-judge（`rerank_enabled` 开启时） |
+| distill 起草 | 直接存传入文本 | ✅ 可由 LLM 从 evidence 起草 |
+
+```bash
+# 本地 Ollama（已装 qwen3 / llama2 等）
+export SMARTBRAIN_LLM_PROVIDER=ollama
+# config/brain.yml 的 model_provider.model 改成你的模型名
+```
+
+```yaml
+# config/brain.yml
+model_provider:
+  provider: ollama          # stub | ollama | openai
+  model: qwen3
+  base_url: http://localhost:11434
+  rerank_enabled: false     # compose 每轮都跑，默认关；改 true 启用 LLM rerank
+  think: false              # 关思维链（支持的 ollama 版本更快更干净）
+```
+
+> 思维链模型（qwen3/deepseek-r1）同步调用较慢；SmartBrain 会自动剥离 `<think>` 块，并在超时/截断时**优雅降级**到模板/词法。摘要只在触发时（每 N 轮或阶段事件）才跑，不影响每轮延迟。
+
+---
+
+## 12. 与 SmartRAG 集成（资源检索）
+
+SmartBrain 在 `compose_context` 时由 `RetrievalPlanner` 判断**是否需要资源检索**（命中「查资料/引用/标准/论文」等意图，或 refs 中有相关 URL），命中则调用挂载的 SmartRAG client。
+
+### 12.1 进程内直连（推荐）
+
+```ruby
+require 'smart_rag'
+require 'smart_brain/adapters/smart_rag/direct_client'
+
+rag = SmartRAG::SmartRAG.new(database: {...}, llm: {...}, embedding: {...})
+scope_mapper = lambda do |domain_id:, scopes:|
+  { filters: { topic_ids: scopes.map { |scope| "#{domain_id}:#{scope[:type]}:#{scope[:id]}" } } }
+end
+rag_client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag, scope_mapper: scope_mapper)
+
+SmartBrain.configure(smart_rag_client: rag_client)
+```
+
+### 12.2 HTTP 直连
+
+```ruby
+require 'smart_brain/adapters/smart_rag/http_client'
+
+# transport 是任意响应 call(plan, timeout_seconds:) 的对象，转发到 SmartRAG HTTP 端点
+rag_client = SmartBrain::Adapters::SmartRag::HttpClient.new(
+  transport: my_transport, timeout_seconds: 5, scope_mapper: scope_mapper
+)
+SmartBrain.configure(smart_rag_client: rag_client)
+```
+
+Mapper 返回 `{ filters: ... }`，adapter 将其放入 RetrievalPlan 的 `scope_filters`。当请求包含 project/expert/task/global scope 时，SmartRAG 响应必须确认 `scope_filter_applied: true`。默认 `fail_closed: true`：mapper 缺失、映射失败或后端未确认都会清空资源证据，并返回 warning，避免跨 domain/scope 泄漏。
+
+### 12.3 不挂载
+
+不传 `smart_rag_client` 时用 `NullClient`（返回空证据），SmartBrain 仍正常工作（memory-only）。
+
+资源证据与记忆证据在 `Fusion::Merger` 里**统一去重 + rerank + diversity**（resource 按 document+section+chunk 去重，memory 按 item_id 或 turn+message），按 `memory_resource_ratio`（默认 40/60）切分预算。
+
+---
+
+## 13. Agent 工具面（MCP / HTTP / CLI 全清单）
+
+### 13.1 MCP 工具（19 个）
+
+`commit_turn` · `compose_context` · `search_memory` · `status`
+· `knowledge_distill` · `knowledge_gate` · `knowledge_promote` · `knowledge_demote`
+· `knowledge_promote_to_scope` · `knowledge_retract` · `knowledge_lineage`
+· `kg_add` · `kg_query` · `kg_invalidate` · `kg_timeline` · `kg_stats`
+· `fact_check` · `brief` · `wake_up`
+
+`initialize` 时返回 `instructions`（轻量 MEMORY_PROTOCOL），客户端连上即学。
+
+### 13.2 HTTP API
+
+| 方法 | 路径 | 入参 |
+|---|---|---|
+| POST | `/commit` | `{domain_id?, session_id, scope_context?, turn_events}` |
+| POST | `/compose` | `{domain_id?, session_id, scope_context?, user_message, agent_state?}` |
+| POST | `/search` | `{domain_id?, session_id, scope_context?, query, limit?}` |
+| GET  | `/status` | — |
+| POST | `/migrate` | — |
+| POST | `/knowledge/{distill\|gate\|promote\|demote\|retract\|promote-to-scope\|lineage\|events}` | 见对应方法 |
+| POST | `/kg/{add\|query\|timeline\|invalidate\|stats}` | 见 §7 |
+| POST | `/fact-check`、`/brief`、`/wake-up` | 均支持 `domain_id` 和 `scope_context` |
+| POST | `/fact-check` | `{session_id, text}` |
+| POST | `/brief` | `{session_id, query?}` |
+| POST | `/wake-up` | `{session_id}` |
+
+```bash
+smart_brain serve --host 0.0.0.0 --port 9292   # Puma
+curl -s localhost:9292/status
+curl -XPOST localhost:9292/commit -H 'Content-Type: application/json' -d '{...}'
+```
+
+### 13.3 CLI 全命令
+
+```
+smart_brain status | migrate
+smart_brain commit | compose | search | fact-check | brief | wake-up   --data JSON | stdin
+smart_brain knowledge <distill|gate|promote|demote|events>             --data JSON
+smart_brain kg <add|query|invalidate|stats>                            --data JSON
+smart_brain serve [--host H] [--port P]
+smart_brain mcp
+smart_brain --version | --config PATH
+```
+
+---
+
+## 14. 可观测性
+
+```ruby
+SmartBrain.diagnostics
+# => {
+#   backend: 'postgres',
+#   metrics: { compose_p95_ms:, memory_resource_ratio: '3/5', token_over_budget_rate: },
+#   turns:, summaries:,
+#   compose_logs:, commit_logs:
+# }
+```
+
+- **全链路追踪**：`request_id → plan_id → context_id` 贯穿 Plan→Retrieve→Fuse→Compose。
+- **P95 延迟**、**memory/resource 命中比**、**token 超预算率**。
+- 每次 commit/compose 的 explain 都记录「为何写入 / 为何选中证据 / 哪些被丢弃」。
+
+---
+
+## 15. 端到端示例（Ruby + SmartRAG + 真实 LLM）
+
+```ruby
+require 'smart_rag'
+require 'smart_agent'
+require 'smart_brain'
+require 'smart_brain/adapters/smart_rag/direct_client'
+
+# 1) 资源后端
+rag = SmartRAG::SmartRAG.new(database: { adapter:'postgresql', host:'127.0.0.1', ... },
+                             llm: { provider:'openai', endpoint:'...', model:'...' })
+SmartBrain.configure(smart_rag_client: SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag))
+
+session = "proj-#{Time.now.to_i}"
+loop do
+  print 'you> '; msg = $stdin.gets&.strip or break
+
+  ctx = SmartBrain.compose_context(session_id: session, user_message: msg)
+  # 把 ctx[:working_summary] / ctx[:evidence] / ctx[:recent_turns] 拼给 LLM ...
+  reply = call_your_llm(ctx, msg)
+
+  SmartBrain.commit_turn(session_id: session, turn_events: {
+    messages: [{ role:'user', content: msg }, { role:'assistant', content: reply }],
+    decisions: extract_decisions(msg, reply),   # 你的结构化抽取
+    edges: extract_edges(msg, reply)
+  })
+end
+```
+
+> 结构化抽取（decisions/entities/edges）可以由你自己的逻辑或 LLM 完成；SmartBrain 只负责**存储、门控、检索、治理**，不强制抽取方式。
+
+---
+
+## 16. 测试与运维
+
+```bash
+bundle exec rspec                                   # 默认套件（memory 后端，零网络）
+SMARTBRAIN_PG=1 SMARTBRAIN_DB_NAME=smart_brain_test \
+  bundle exec rspec                                 # 含 PG 持久化/FTS/lifecycle/KG 集成
+SMARTBRAIN_LLM=1 bundle exec rspec spec/smoke_ollama_spec.rb   # 真实 Ollama 冒烟
+```
+
+常用 env 开关：`SMARTBRAIN_BACKEND` / `SMARTBRAIN_DB_*` / `SMARTBRAIN_LLM_PROVIDER` / `SMARTBRAIN_LLM_BASE_URL` / `SMARTBRAIN_LLM_API_KEY`。
+
+---
+
+## 17. 能力边界（当前不支持）
+
+- **多 Agent Cowork**（bus/channel/handoff）、**Phase-3 自进化**（runtime adoption）、**AAAK 格式化**、**Bench/评估** —— 未实现（P3）。
+- **跨项目命名空间**（wing/room）—— 暂只有 `session_id`；`resume` 按 session_id 模糊匹配。
+- **记忆侧向量检索** —— 当前是 FTS + 子串，无 embedding（资源侧向量检索由 SmartRAG 提供）。
+- **LLM 自动三元组抽取 / planner 全量 LLM 化** —— KG 由 `turn_events[:edges]` 显式传入。
+
+---
+
+## 18. 进阶文档
+
+- 设计与契约：`docs/smartbrain_design.md`、`docs/policies.md`、`docs/memory_types.md`
+- 策略与治理：`docs/retrieval_plan.md`、`docs/evidence_pack.md`、`docs/context_package.md`
+- MCP 接入：`docs/mcp.md`
+- 差距与路线：`docs/gap_vs_mempal.md`
+- 示例：`example.rb`、`conversation_demo.rb`