内容
状态 RAG MCP —— 落地化
> **两个智能代理和一个智能控制系统比一群代理做得更仔细的工作，同时消耗更少的令牌。**
> 一个基于状态的 RAG，它将**验证的当前状态置于代理的路径中**，使其从**事实**中推理，而不是从过时的回忆或昂贵的重新推导中。
**状态：** 早期 / 探索性 —— 理论和方法的实际测试已经在日常使用中验证；公共工具正在被提取，**令牌节省的主张正在被衡量，而不是被宣称**。完整状态见下文。仅限标准库，无依赖。该方法本身是一个单独的阅读材料：OLOGY.md](./METHODOLOGY.md)**。
---
## 赌注
行业代理**集群**的方向发展， = **的前提。我们的赌注：一个**最小化**的设置 —— 两个代理加上一个基于状态的控制系统 —— 能够产生更仔细、更**可验证**的工作，同时降低令牌成本。
- **推理/架构代理** （一个高级模型）—— 设计、审查、进行根本原因分析。
- **执行代理** （一个普通模型）—— 构建、部署、运行。
- —— 设置策略并设定上限：不可逆转的/面向外部的更改需要批准。
集群通过重新推导上下文、协调和重复来消耗令牌。瓶颈从来不是**有多少代理** —— 而是**每个决策是否落地和验证**。解决这个问题，两个代理就能走得很远。完整的模式 —— 边界、实际案例研究 —— 在 **[METHODOLOGY.md](./METHODOLOGY.md)** 中。
### 为什么它有效 —— 控制系统
1. **落地，而不是重新推导。** 系统的当前、协调状态被注入到代理的路径中。它不会在每个会话中重新探索世界；它会读取验证的事实。**这就是这个工具提供的功能。**
2.边界进行验证。** 推理代理永远不会信任执行代理的**报告** —— 它会直接检查实时状态（“服务是否实际运行？”，而不是“你说它运行吗？”）。
3. **为正确的层选择正确的模型。** 昂贵的推理只在需要的地方进行；廉价的执行在其他地方进行。集群无法拉动的成本/延迟杠杆。
4. **紧凑、机器优先的制品。** 状态接是和结构文本。
## —— 一个的 RAG，作为 MCP
不是基于文档的向量-RAG。一个**基于状态的 RAG**：一个规范存储在每次更改时写入，一个**协调器** 保持其 ≡ 现实（漂移/孤立检测），以及一个** 当前状态中。纪律：**回忆 —— 验证状态。模型上下文协议公开，以便**代理都可以| 功能---|---|
| `state_onboard()`次调用获取状态（ 状态、移、规则、最后决策） `state_query(domain, filter)` | 按需获取的切片state_verify(claim)` | ★ *不要相信报告 —— 与事实进行验证* → `{holds, actual, evidence}` |
| `state_reconcile(domain)` | 模型 ≡ 现实 → 漂移 / 报告 |
预先注入上下文的资源（`state`, `state`, `state://rules`, `state://h）。 分割是刻意的 —— **资源** 提供前端加载（在会话开始时注入摘要）；**工具** 提供延迟路径（仅查询需要的内容）。
**它是领域无关的。** 您注册自己的 `StateProvider` （SQLite、JSON、Git、API —— 任何） 和一个 `Reconciler` （如何为每个领域观察现实）。 完整的抽象、参考实例、Git/VCS 实例、远程模式以及与其他上下文源的组合： **[INTERFACE.md](./INTERFACE.md)**。
**它可以组合。** 状态 RAG 是一个工具，而不是整个机架：将其通过 MCP 与内容 RAG、内存服务器和其他工具并行连接。 使整体保持诚实的纪律是**权限排序** —— 对于**当前**事实，协调状态优先于内存和文档。
## 安装
**要求：** Python **3.10+**。 除此之外，服务器标准库，没有 `pip install`。
```bash
git clone <此仓库> state-rag-mcp
python3 state-rag-mcp/tests/test_state_rag.py # 可选：22 个检查，约 1 秒
```
服务器是一个命令（stdio；您的 MCP 客户端会启动它）：
```bash
python3 /绝对路径/state-rag-mcp/mcp_server.py --state /绝对路径/your-state.json
python3 /绝对路径/state-rag-mcp/mcp_server.py --sqlite /绝对路径/your-state.db # 任何 SQLite 数据库
python3 /绝对路径/state-rag-mcp/mcp_server.py --git /绝对路径/your-repo # 一个 Git 工作树
python3 /绝对路径/state-rag-mcp/mcp_server.py --microstack /绝对路径/state-rag-mcp/corpus/microstack # 演示
```
> **架构说明：** 服务器**在本地运行，与您的代理一起**（stdio）。您的状态存储在您的代理存储在的位置。它不是网络服务，不会与任何地方的电话联系。（远程**状态**在提供者层支持 - 请参阅 [INTERFACE.md](./INTERFACE.md)。）
### 每个客户端的配置
所有 stdio MCP 客户端都需要相同的三个事实：`command: python3`, `args: [launcher, --flag, path]`。 在所有地方使用**绝对路径**。
**Claude Code (CLI):**
```aude mcp add state-rag -- python3路径/state-mcp/mcp_server.py --state /绝对路径/state.json
```
或在 `.mcp.json` / **Claude Desktop** 中使用 `claude_desktop_config.json`json
{ "mcpServers": { "rag": {
command": "python3",
"args": ["/绝对路径/state-rag-mcp/mcp_server.pystate", "/绝对.json"] } } }
```
**OpenCode** (`opencode.json`, 0.x 形状)：
```json
mcp":state-rag": {
"type": "local",
": ["python3", "/绝对-rag-m_server.py", "--state",路径/state.json } }
```
** (/mcp.json`), **Cline** (`cline_mcp_settings.json`), **Windsurf** (`~/.codeium/windsurf/mcp_config.json`) — 所有这些都使用与 Claude Desktop 相同的 `mcpServers` 形状。
### 验证安装（无需客户端）
```bash
printf '%' '{"json2.0","id":1,"method":"initialize","params":{}}' \
| python3 /绝对路径/state-rag-mcp/mcp_server.py --microstack /绝对路径/state-rag-mcp/corpus/microstack
```
您应该会看到一行包含 `"serverInfo": {"name": "state-rag-mcp"}` 的 JSON。
## 快速入门 — 60 秒演示
仓库中附带一个微小的虚构部署 (`corpus/microstack/`)，包含**三个已播种的：一个服务声明为活动但实际上已停止，一个规则冲突和一个孤立进程。
**1. 请求整个画面：**
```bash
cd state-rag-mcp
printf' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"state_onboard","arguments":{}}}' \
| python3 mcp_server.py --microstack corpus/microstack
```
→ 一个紧凑的摘要：9 个服务，3 个漂移（从原始文件实时重新计算，而不是从快照读取），规则，最后记录的决策。
**2. 抓住一个谎言** — 声称 `cache` 正在运行，与事实相反：
```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"state_verify","arguments":{"domain":"services","filter":{"name":"cache"},"expect":{"actual":"running"}}}}' \
| python3 mcp_server.py --microstack corpus/microstack
```
→ `"holds": false` **带有证据**：声明 `active`，观察到 `stopped`。 这是整个哲学在一个调用中的体现：*不要相信报告 — 与状态进行验证。*
**3. 附加您的代理**，询问它：
- *"系统的当前状态是什么？有任何漂移吗？"* → 它调用 `state_onboard` 一次。
- *"缓存服务是否与声明的一致？"* → 它调用 `state_query` / `state_verify`。
**测量的最佳用法模式** （参见 [Measured](#measured-not-proclaimed)）：**在会话开始时注入摘要** （对于广泛的问题最便宜），然后**使用有针对性的 `state_query` 进行后续** （对于狭窄的问题最便宜）。 冷重新探索始终是最昂贵的。
## 将您的系统上线 — 三个步骤
### 步骤 1 — 将服务器指向您的状态
**JSON（最快启动）。** 任何顶级键包含记录列表的 JSON 文档：
{ "system": "my-stack",
": [ {"nameapi", "staterunning", "version": "1.2.0"} ],
"rules": [ "api and worker versions must match" ],
"last_decision": {"id": "D-1", "text": "approved cache upgrade"} }
```
```bash
python3 mcp_server.py --state /绝对路径/my-state.json
```
**SQLite.** 每个表/视图自动成为一个可查询的领域 —— 或传递显式映射（参见 `instances/sqlite_ops.py` 中的实际生产示例）。按构造方式只读打开（`mode=ro`）：
```python
_rag.sqliteiteStateProvider
provider = SqliteStateProvider("ops.db",
domains={"services": "services", "blockers": "v_open_blockers"},
meta={"system": "my```
**Gitgit /path/to/repo` — 工作树成为一个实时的漂移报告（参见 [INTERFACE.md](./)）。
**API / 任意。** 实现两个方法（这是**远程模式** — 服务器保留本地，提供者跨越网络；SSH 通道提供者是相同的形状）：
```python
from state_rag.provider import StateProvider
import json, urllib.request
class ApiStateProvider(StateProvider):
def __init__(self, base self.base =
_domains(self):services", "incidents", "meta"]
query(self, domain):
if "meta":system": "my]
with urllibopen(f"{selfdomain}") as r = json.load(r if filter: records = [x for x in records if all(x.get(k) == v for k, v in filter.items())]
return records
```
### 步骤 2 — 塑造摘要（什么在 onboard 时很重要）
原始转储不属于模型的上下文（我们的第一个真实规范摘要权重为 44k 字符；策略将其削减到 12k）。 为每个领域声明重要内容 — 细节永远不会丢失，它仍然是一个 `state_query` 远离：
```DIGEST_POLICY = {
"services": {"fields": ["name", "state", "version": 60},
"deploys {"fields":", "result"], 5, "last": True},
"": {"skip": True # 可不是 onboard 材料
}
```
### 步骤 但推荐）协调器
AG 赚取：**声明 vs → 类型漂移**，实时计算。
```from state_concile import Re
class MyReconciler(Reconciler):
domain = "services"
def declared(self): 模型：您的清单 / 数据库 / 配置
return load_manifest()
observe(self): 实：ps, systemctl, API 探针 return probe_running_processes()
```
通用差异产生 `declared_but_missing`, `orphan`, 和您注册的 `rule_violation`s — 正是演示中播种的三种漂移类型。 在实例模块中连接它（`instances/microstack.py` 是 40 行的参考）。
## 用例
| 场景 | 调用模式 |
|---|---|
| 代理会话启动 — “我在哪里？” | 注入 `digest` 资源，或一次 `state_onboard`服务 X 是否正常？” 会话中 | `state_query(services, {name: X}) 约 80 个令牌 |
| （或人）的报告 | `state_verify filter, expect)` → holds/mismatches + 证据 |
| 部署后健康检查 |_reconcile()` → 实时漂移列表，缺失，规则冲突） |
门控 | 在脚本中运行协调；如果漂 预期，则失败管道 |
## 测量，而不是宣称
我们拒绝发布一个未经验证的令牌节省数字。 [EXPERIMENT.md](.//microstack/EXPERIMENT.md) 定义重复的实验：相同的任务在**冷**（代理重新探索）与**上线**（注入状态）与**MCP**（查询状态）下运行，在一个小型受控语料库上，使用相同的模型，≥5 次试验，**按正确性评分** （产生错误答案的节省被取消资格）。诚实的发现是一个**权衡** — 上线赢得广泛的任务，延迟查询赢得狭窄的任务，冷的总是失败 — 以这种方式在 [RESULTS.md](./corpus/microstack/RESULTS.md) 中报告，连同所有注意事项。
## 状态（诚实）
| 部分 | 状态 |
|---|---|
| 理论 + 方法 | ✅ 在日常使用中验证 |
| MCP 服务器（仅限标准库） | ✅ 22/22 检查 + 端到端 stdio 烟雾测试 |
| 受控语料库 + 实验 | ✅ 权衡特征（上线赢得广泛，延迟查询赢得狭窄，冷的总是失败；正确性完好） |
| 第二个实时实例（SQLite 数据库的真实生产规范） | ✅ 14/14 结构检查；从 44k→12k 的经验教训中获得的摘要策略 |
| Git/VCS 实例 | ✅ `GitStateProvider` + 协调器（ `--git` ）；三种漂移类型从 `git status` 中脱出；只读；17/17 检查 |
| 远程模式（远程状态，本地服务器） | ✅ 按设计在提供者层；远程 MCP *传输* = 开放集成点，未发货 |
| 技能（9）+ 代理规格（2） | ✅ 纪律和两个角色，可安装 |
| 发布级令牌计数器（实际 MCP 附件 + 计费使用） | ⬜ 待处理 |
| 现实语料库 + 已发布数字 | ⬜ 验证后 |
*图例：✅ 已构建和测试 · ⬜ 已声明/路线图。 `METHODOLOGY.md`skills/` 和 `agents/` 是实践文档（我们每天运行的不是编排代码 — 这里没有任何东西成它不是的东西。*
## 更深入
METHODOLOGY.mdOLOGY.md)**两个代理模式：质量形成的四个实际的四轮案例研究和诚实的局限性。
- **[INTERFACE.md](./INTERFACE.md)** — 扩展和集成：提供者抽象、参考实例/VCS 实例模式以及与其他上下文组合。
- **[skills/](./skills/)** — 九个学科作为可移植、可安装的技能（每个都有其疤痕）。
- **[](./agents/) 两个角色作为的代理规格者 · 执行者corpus/micro](./corpus** —语料库、实验设计和结果。
## 仓库布局
```
state-rag-mcp/
├── README.md ← 本文（是什么 · 安装 · 用法 · 状态）
├── METHODOLOGY.md ← 两个代理模式（工具背）
├── INTERFACE.md ← 扩展（抽象 · git · 远程 · 组合）
├── skills/可移植个学科（ Code 中安装 agents/ ←角色作为可代理规格（推理者 · 执行者）
├── m.py ← 任何 MCP 客户端的单文件启动器
├── state_rag/ ← 库（标准库）：提供者 · sqlite_provider · git_provider · reconcile · digest · server
├── instances/ ← 参考实例（microstack · 真实的规范 · git）
└── corpus/microstack/ ← 受控测量语料库
├── raw/ ←面临的内容（必须 ├── synthesized ← 协调RAG 的产品）
├── EXPERIMENT.md · RESULTS.md · GROUND_TRUTH.md · TASKS.md
```
## 血统与哲学
基于 Stafford Beer 的**可行系统模型** 和 **Cybersyn** 项目（智利，1971 年）—— 一个系统是**可描述**、**可治理** 和 **可审计** 的时候是可行的。 “不要相信，验证”在这里不是口号；它是协调器和每个边界验证的纪律，使机械化。社区优先，并**来自全球 — Cybers继承者，即好的控制论服务于人 许可证
代码：**Apache-2.0** ([LICENSE](./LICENSE)) · 文档：**CC-BY-4.0**。
该模块的许可比 AGPL 核心更宽松，它是从 AGPL 中提取出来的 — 它旨在被社区采用、嵌入和改进。改进可以流动回来；该
