docs: add zero-dependency examples guide for issue #58

examples/README.md

@@ -2,6 +2,37 @@
 
 示例按依赖复杂度分为三组，建议按顺序探索。
 
+## 零外部依赖示例
+
+以下示例仅依赖项目核心依赖，使用 FileBackend 或内存后端，无需安装 OceanBase、配置 LLM API key 或任何外部服务。确保已 `uv sync` 后直接运行即可。
+
+### 推荐首试
+
+| 示例 | 一句话说明 | 命令 |
+|---|---|---|
+| `basic/pipeline_file.py` | 最简 FileBackend 写入 + 关键词检索 | `uv run python examples/basic/pipeline_file.py` |
+| `advanced/research_agent.py` | 完整链路：写入→链接→检索→expand→Trace→compact→路由→skill | `uv run python examples/advanced/research_agent.py` |
+
+### 全部零依赖示例
+
+| 示例 | 功能亮点 | 运行命令 | 预期输出 |
+|---|---|---|---|
+| `basic/pipeline_file.py` | FileBackend 落盘 + 关键词子串检索 + Orchestrator 底层调用 | `uv run python examples/basic/pipeline_file.py` | 打印 3 条写入 item、3 组 query 的命中 ID、磁盘文件数 |
+| `advanced/research_agent.py` | 多源写入、链接、检索/expand、Trace 导出、compact、策略路由、skill 导出 | `uv run python examples/advanced/research_agent.py` | 10 步逐步输出，最终打印 scope 总 item 数和磁盘文件数 |
+| `advanced/evidence_chain.py` | 证据链 DAG：upstream / evidence_chain / chain_confidence | `uv run python examples/advanced/evidence_chain.py` | SRE 故障场景 5 步输出，含 DAG 节点数、置信度传播、冲突检测、关键路径 |
+| `advanced/powermem_minimal.py` | PowerMem 最小集成（内置 mock，无需安装 powermem） | `uv run python examples/advanced/powermem_minimal.py` | 打印 plugged 记忆数 + 检索命中列表 |
+| `advanced/self_evolution_demo.py` | 自演进四特性：冲突解决 + 双时效 + 效用反馈 + 失败反思 | `uv run python examples/advanced/self_evolution_demo.py` | 4 个分节输出，分别展示冲突退役、drift 隔离、boost 变化、pitfall 规则 |
+| `advanced/powermem_plug.py` | PowerMem DataPlug（默认 mock 模式，可选真实 powermem） | `uv run python examples/advanced/powermem_plug.py` | 5 步输出：导入→挂载→追加→统一检索→溯源对比 |
+| `demo/seed.py` | demo 种子脚本（FileBackend，写入合规 lesson + trace） | `uv run python examples/demo/seed.py` | 打印 seeded lesson 列表和完成提示 |
+| `full_pipeline_file.py` | 兼容 shim，导出 `basic/pipeline_file.py` 的公开 API（不自动执行 `main()`） | `uv run python -c "from examples.full_pipeline_file import run_file_backend_demo; run_file_backend_demo(...)"` | 无直接输出（仅加载模块）；调用其导出函数可复现 `pipeline_file.py` 的行为 |
+
+> **注意**：以下示例**不是**零依赖：
+> - `basic/langchain_deepagents_example.py` — 需要 `OPENAI_API_KEY` + `contextseek[langchain]` extras
+> - `basic/langchain.py` — 需要 `contextseek[langchain]` extras
+> - `basic/pipeline_ob.py` — 需要 OceanBase + embeddings provider
+> - `advanced/llm_full_pipeline_ob.py` — 需要 OceanBase + LLM API
+> - `gis/` 下所有示例 — 需要 OceanBase >= 4.2.2 且 `GEO_ENABLED=true`
+
 ## [basic/](basic/) — 入门示例
 
 依赖最小，适合初次了解 ContextSeek。
@@ -10,8 +41,8 @@
 |---|---|---|
 | `pipeline_file.py` | FileBackend（无需外部服务） | 本地文件后端，关键词检索 |
 | `pipeline_ob.py` | OceanBase | 向量 + 全文混合检索 |
-| `langchain.py` | FileBackend | LangChain Memory / Retriever 桥接 |
-| `langchain_deepagents_example.py` | FileBackend（无需外部服务） | LangChain + DeepAgents + ContextSeek 的真实集成示例 |
+| `langchain.py` | FileBackend（需 `langchain` extras） | LangChain Memory / Retriever 桥接 |
+| `langchain_deepagents_example.py` | FileBackend + OpenAI API | LangChain + DeepAgents + ContextSeek 的真实集成示例（需 `OPENAI_API_KEY`） |
 
 ```bash
 uv run python examples/basic/pipeline_file.py  # 零外部依赖，推荐首选

examples/advanced/README.md

@@ -76,6 +76,24 @@ uv run python examples/advanced/powermem_minimal.py
 
 ---
 
+## self_evolution_demo.py — 自演进四特性演示
+
+```bash
+uv run python examples/advanced/self_evolution_demo.py
+```
+
+**依赖：** 仅项目本身，无需额外安装。
+
+场景：在内存后端上演示 ContextSeek 自演进引擎的四个核心特性。
+
+演示：
+- 冲突检测与双时态有效期（新证据覆盖旧证据，旧条目自动退役）
+- Drift 隔离（偏离当前共识的条目被标记隔离，不参与召回）
+- 效用反馈循环（"use it or lose it"——长期未被检索的条目降权）
+- 失败驱动反思（`PitfallReflector` 从失败 trace 中提取规则）
+
+---
+
 ## powermem_plug.py — PowerMem DataPlug 完整演示
 
 ```bash

examples/basic/README.md

@@ -64,6 +64,10 @@ pip install "contextseek[langchain]"
 
 ## langchain_deepagents_example.py — LangChain + DeepAgents 集成示例
 
+**依赖：** 需要 `OPENAI_API_KEY` 环境变量 + `contextseek[langchain]` extras。
+
+> 此示例执行真实 LLM 调用（ChatOpenAI），不是零外部依赖示例。
+
 ```bash
 uv run python examples/basic/langchain_deepagents_example.py
 ```