vouch

# 代办 **基于 Git 的、审查门控的知识库，适用于 LLM 代理。MCP 服务器 + JSONL 工具服务器 + CLI。** <p align="center"> <img src="docs/banner.svg" alt="代办 — 提出 → 审查 → 提交 → 检索" width="100%"/> </p> <p align="center"> <a href="https://github.com/vouchdev/vouch/actions/workflows/ci.yml"><img src="https://github.com/vouchdev/vouch/actions/workflows/ci.yml/badge.svg?branch=main" alt="持续集成"></a> <a href="https://pypi.org/project/vouch-kb/"><img src="https://img.shields.io/pypi/v/vouch-kb.svg" alt="PyPI"></a> <a href="https://pypi.org/project/vouch-kb/"><img src="https://img.shields.io/pypi/pyversions/vouch-kb.svg" alt="Python 版本"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/vouchdev/vouch.svg" alt="MIT 许可"></a> </p> > 代理不应每次会话都从无记忆开始 — 但它们也不应该随意写入。 `代办` 是一个适用于 LLM 代理的知识库，具有明确的**审查门控**：代理*提出*写入；人类使用 `代办批准` 批准它们。批准的工件是磁盘上的普通文件 — 用于声明的 YAML，用于页面的 Markdown — 因此知识库存放在您的仓库中，在 PR 中审查，差异清理，可以作为可移植包导出。 仍在 alpha 阶段 — 表面很小，预计在 1.0 之前会有破坏性更改。 > **Gittensor (SN74) 特色。** 代办提供一键启动包，适用于 **Gittensor** — Bittensor 子网 74。`代办初始化 --template gittensor` 播种了一个被引用、已批准的决策内存，包含 SN74 评分模型的已合并 PR 奖励、PAT 验证、抗 Sybil 能力、存储库允许列表、问题乘数和排放分割。这是每个规则背后的持久性 *原因* — 审查、引用并与代码一起提交。 → **[文档/gittensor.md](docs/gittensor.md)** ## 为什么存在 三个有争议的选择将代办与其他产品区分开来： 1. **知识库是仓库中的一个文件夹。** Git 是您的审计日志、备份和同步机制。PR 是您的审查 UI。 2. **写入需要批准。** 代理文件*提案*；人类（或受信任的批准代理）明确接受它们。`proposed/` 被 gitignore，因此拒绝的草稿永远不会污染历史记录。 3. **声明必须引用来源。** 没有至少一个来源/证据 ID 的声明是一个验证错误，而不是警告。来源是内容哈希的；同一个证据注册两次会重复。 ## 何时使用代办 值得使用时： - **您运行或参与 Gittensor（SN74）仓库。** 评分权重、存储库允许列表、防 Sybil 阈值和排放分割在 PR、Discord 和验证器更改中进行辩论 — 然后在没有人记录的情况下解决。`代办初始化 --template gittensor` 为您提供了一个引用的、审查过的 *为什么* 每个规则存在及其取代的内容的记录。参见 [文档/gittensor.md](docs/gittensor.md)。 - **多个代理共享一个仓库**（Claude Code + Cursor + CI 机器人）。审计日志中的每个代理归属使“哪个代理声称什么”可以回答。 - **会话不断重新解释相同的上下文。** 精致的、引用的声明让新会话从团队同意的答案开始，而不是重新 grep。 - **您希望在没有 ADR 仪式的情况下进行决策记录。** `代办结晶` 将会话的持久部分转化为提案；一次批准，它们就永久了。 - **您会像审查代理编写的代码一样审查代理陈述的事实。** 代办是一个 PR 队列，用于声称的知识。 - **合规性/审计轨迹很重要。** 所需的引用 + 追加日志使您能够免费获得“谁决定 X，引用什么，何时”。 跳过它如果： - 独立的个人项目，上下文适合您的脑海。 - 短寿命的分支，没有累积的上下文。 - 您的团队实际上不会审查提案 — 没有门控，代办是一个较差的笔记应用。 ## 安装 ```bash # 一行代码（Linux + macOS）- 选择 Python，确保 pipx，安装 vouch-kb curl -fsSL https://raw.githubusercontent.com/vouchdev/vouch/main/install.sh | sh # …或直接通过 pipx（PyPI 上的 vouch-kb；命令仍为 `vouch`） pipx install vouch-kb # …或从克隆的仓库，在虚拟环境中 pip install -e '.[dev]' ``` 一行代码是 POSIX `sh`，永远不需要 `sudo`，并检测现有的 Claude Code 安装以指向下一步骤（`代办安装-mcp claude-code`）。如果您愿意，可以先检查它 — 它位于存储库根目录的 [`install.sh`](install.sh)。 ## 快速入门 ```bash # 1. 在项目根目录设置知识库 代办初始化 # 2. 作为代理，注册证据 + 提出声明（通过 MCP/JSONL 服务器） 代办服务 # MCP 通过 stdio（Claude Code，Cursor，Codex） 代办服务 --transport jsonl # stdin/stdout 上的换行 JSON # 3. 作为人类，审查和决定 代办状态 # 一行摘要 代办待处理 # 列出待处理提案 代办显示 <id> # 完整详细信息 代办批准 <id> # → 持久工件 代办拒绝 <id> --reason "..." 代办过期 --apply # 可选：清除过时的待处理提案 # 4. 提交 git add .vouch/ && git commit -m "kb: approve auth-uses-jwt" ``` ## 30 秒游览 `代办初始化` 现在创建一个启动配置和一个引用的示例声明，以便您可以在连接代理之前尝试循环： ```bash mkdir 代办演示 && cd 代办演示 代办初始化 代办状态 代办搜索代理 代办引用 代办启动审查知识 ``` 启动声明已经持久并引用启动源。准备好后，用您的第一个真实源和声明替换它。  完整的演练记录在 [文档/example-session.md](docs/example-session.md) 中；使用 `vhs 文档/demo.tape` 从 [文档/demo.tape](docs/demo.tape) 重新渲染 GIF。 ## Gittensor (SN74) 代办的第一个领域模板针对 **Gittensor** — Bittensor 子网 74，它通过规则奖励开源贡献。其评分模型在 PR、Discord 和验证器更改中不断演变，通常在人们的脑海中。代办是其持久的、引用的内存： ```bash cd 您的gittensor仓库 代办初始化 --template gittensor # 播种 1 个源，1 个实体，7 个引用的 SN74 评分声明 代办状态 # 已持久：7 个声明 · 1 个源 · 1 个实体 代办搜索 "排放分割" git add .vouch && git commit -m "chore: add vouch decision-memory KB" ``` 种子包涵盖了合并的 PR 奖励、PAT 验证、评分因素、防 Sybil 能力、存储库允许列表、问题解决乘数和排放分割 — 每个都是引用的、批准的、可取代的声明。当规则更改时，使用 `代办取代` 旧声明为新声明，以便 *更改内容* 的历史记录可查询。 代办**不存储**任何实时信号 — 它不是验证器或矿工客户端，从不读取链上分数。它是位于实时层（Gittensory）旁边的机构内存。种子声明是启动级；一旦您确认实时规则，请使用真实规范或 PR 取代它们。 完整的采用指南 — 安装、播种、连接 MCP 服务器、捕获决策为引用声明： **[文档/gittensor.md](docs/gittensor.md)**。 ## 对象模型 ``` 源 immutable 输入材料（文件，URL，转录，提交，...） 通过 sha256 进行内容寻址 证据 源的范围指针（行范围，时间戳，引用） 声明 原子持久断言 类型：事实 | 决策 | 偏好 | 工作流 | 观察 | 问题 | 警告 状态：工作中 | 可行 | 稳定 | 有争议 | 已取代 | 已存档 | 已编辑 置信度：0.0-1.0 引用：源/证据 ID 列表 实体 类型化事物（人 | 项目 | 仓库 | 概念 | 决策 | 系统 | ...） 关系 类型化边（使用 | 依赖于 | 取代 | 矛盾 | 实现 | ...) 页面 维护的 Markdown — 实体写作、决策记录、会话摘要 会话 代理打开的工作块；捆绑其提案 审计事件 每个突变的追加日志记录 ``` ## 文件布局 在 `代办初始化` 之后，您的仓库包含： ``` .vouch/ ├── config.yaml # 知识库设置 ├── .gitignore # 忽略 proposed/，state.db ├── audit.log.jsonl # 追加审计（已提交） ├── state.db # SQLite FTS5 索引（派生；不提交） ├── claims/<id>.yaml # 审查声明（初始化种子 vouch-starter-*.yaml） ├── pages/<id>.md # 带有 YAML 前面的 Markdown 页面 ├── sources/<sha>/{meta.yaml,content} ├── entities/<id>.yaml # 图节点 ├── relations/<id>.yaml # 图边 ├── evidence/<id>.yaml # 源的范围指针 ├── sessions/<id>.yaml # 代理会话记录 ├── proposed/<id>.yaml # 待处理（gitignored，仅本地） └── decided/<id>.yaml # 已批准/拒绝（已提交用于审计） ``` 文件是真实来源；`state.db` 是可派生的缓存（`代办索引` 重新构建它）。 ## CLI 表面 ``` 代办初始化 # 在 PATH 处设置 .vouch/ 代办发现 [--path P] # 查找最近的 .vouch/ 根目录 代办能力 # 发出 JSON 能力描述符 代办状态 [--json] # 知识库计数 + 待处理提案 代办统计 [--days N] [--json] # 可观察性：队列、审查率、引用 代办检查 [--stale-days N] # 用户可操作问题 代办医生 # 完整扫描包括源验证 代办 fsck # 深度一致性：索引、生命周期、已决定 代办迁移 [--check] [--dry-run] # 安全升级 .vouch/ 格式 代办待处理 # 列出待处理提案 代办审查 [--limit N] [--type KIND] # 引导式提案审查队列 代办显示 <proposal-id> 代办批准 <proposal-id> [--reason ...] 代办拒绝 <proposal-id> --reason "..." 代办过期 [--apply] [--days N] [--json] # GC 过时待处理提案 代办提出声明 --text ... --source ... [--type ...] [--confidence X] 代办提出页面 --title ... [--body -] [--claim ID ...] 代办提出实体 --name ... --type ... 代办提出关系 --from ID --rel uses --to ID 代办源添加 PATH [--title ...] [--url ...] 代办源验证 [--fail-on-issue] 代办取代 OLD_ID NEW_ID 代办矛盾 CLAIM_A CLAIM_B 代办存档 CLAIM_ID 代办确认 CLAIM_ID 代办引用 CLAIM_ID 代办会话开始 [--task ...] [--note ...] 代办会话结束 SESSION_ID 代办结晶 SESSION_ID [--no-page] 代办搜索 QUERY [--limit N] 代办上下文 TASK [--max-chars N] [--min-items N] [--require-citations] 代办索引 代办审计 [--tail N] [--json] 代办导出 --out path.tar.gz 代办导出检查 path.tar.gz 代办导入检查 path.tar.gz 代办导入应用 path.tar.gz [--on-conflict skip|overwrite|fail] 代办同步检查 PATH_OR_BUNDLE 代办同步应用 PATH_OR_BUNDLE [--on-conflict fail|skip|propose] 代办服务 [--transport stdio|jsonl] ``` ## MCP 工具 / JSONL 方法（相同表面，两种传输） 读取（无限制）：`kb.capabilities`，`kb.status`，`kb.search`，`kb.context`，`kb.read_{page,claim,entity,relation}`，`kb.list_{pages,claims,entities,relations,sources,pending}` 源摄入（不门控 — 证据无害且重复）：`kb.register_source`，`kb.register_source_from_path`，`kb.source_verify` 写入（门控 → 产生提案）：`kb.propose_{claim,page,entity,relation}` （带有 `dry_run:true` 进行预览） 决策：`kb.approve`，`kb.reject` （需要主机信任） 生命周期（关于审查知识的元数据 — 直接突变，审计）：`kb.supersede`，`kb.contradict`，`kb.archive`，`kb.confirm`，`kb.cite` 会话：`kb.session_start`，`kb.session_end`，`kb.crystallize` 维护：`kb.index_rebuild`，`kb.lint`，`kb.doctor`，`kb.audit`，`kb.export`，`kb.export_check`，`kb.import_check`，`kb.import_apply` ## 连接到 Claude Code 在您的项目的 `.mcp.json` 中： ```json { "mcpServers": { "代办": { "command": "代办", "args": ["服务"], "env": { "VOUCH_AGENT": "claude-code" } } } } ``` `VOUCH_AGENT` 被记录为 `proposed_by` 和每个审计事件的执行者，因此多代理设置可以正确归因写入。 ## 作为 OpenClaw 插件运行代办 代办在存储库根目录附带一个 [OpenClaw](https://github.com/dripsmvcp/openclaw) 插件清单 — [`openclaw.plugin.json`](openclaw.plugin.json)。将代办存储库放入 OpenClaw 部署中，插件加载器会自动拾取它：MCP 服务器、四个斜杠命令（`/vouch-recall`、`/vouch-status`、`/vouch-resolve-issue`、`/vouch-propose-from-pr`）和 CLAUDE.md 带状代码段作为一个包提供。 清单明确声明代办的信任边界 — 远程调用者的文件系统访问是受限的，每个写入工具都通过审查门控路由，每个生命周期操作都经过审计记录。`configSchema` 只公开 `kb_path`、`agent` 和 `transport` — 没有 API 密钥，没有秘密；代办是本地优先的。 ```bash # 在包含插件存储库的 OpenClaw 部署中： openclaw 插件添加 vouchdev/vouch openclaw 插件启用 vouch ``` 插件的 `mcpServers.vouch` 块与 Claude Code 使用的 `.mcp.json` 形状匹配 — 两个平台驱动相同的 `代办服务` 进程，因此 `kb.*` 接口相同。 ## JSONL 请求/响应形状 JSONL 传输在 stdin 上读取一个信封，在 stdout 上写入一个信封： ```jsonl {"id":"r1","method":"kb.search","params":{"query":"jwt","limit":5}} {"id":"r1","ok":true,"result":[{"kind":"claim","id":"auth-uses-jwt","snippet":"…","score":1.2,"backend":"fts5"}]} ``` 错误以 `ok:false` 和结构化的 `error.code` 返回（`method_not_found`、`missing_param`、`invalid_request`、`internal_error`）。 每个成功的 `kb.*` 结果都是对象形状的，都带有只读的信任元数据，以便客户端检测远程限制： ```json { "id": "r1", "ok": true, "result": { "backend": "fts5", "hits": [], "_meta": { "vouch_trust": { "remote": false, "caller_kind": "jsonl", "auth_subject": null } } } } ``` | 传输 | `remote` | `caller_kind` | `auth_subject` | |-----------|----------|---------------|----------------| | JSONL stdio | `false` | `jsonl` | `null` | | HTTP `/rpc` | `true` | `jsonl_http` | bearer 指纹（如果已验证）| | MCP stdio | `false` | `mcp_stdio` | `null` | | HTTP `/mcp` | `true` | `mcp_http` | bearer 指纹（如果已验证）| | CLI `--json` | `false` | `cli` | `null` | 该块是服务器附加的元数据 — 客户端的突变被忽略。数组形状的结果（例如 `kb.list_claims`）直接通过，不带信任信息（#233）。 ## 可移植包 ```bash 代办导出 --out kb.tar.gz # tar.gz + 清单文件，包含每个文件的 sha256 代办导出检查 kb.tar.gz # 验证清单文件中的每个文件 代办导入检查 kb.tar.gz # 与目标的差异 — 新 / 冲突 / 相同 代办导入应用 kb.tar.gz --on-conflict skip # 应用（默认跳过；如果不覆盖，则永远不会破坏） ``` `proposed/`、`state.db` 和 `audit.log.jsonl` 被排除在包之外 — 只有可提交的工件被传输。 ## 与邻居比较 | | mem0 / Letta | LLM-Wiki 工具 | **代办** | |---|---|---|---| | 知识存储在 | 服务 | 文件系统 | 您的 **仓库** | | 写入审查 | 无 | 无 | **显式批准** | | 需要证据 | 无 | 可选 | **强制** | | 每个代理的属性 | 部分 | 无 | **是**（审计日志）| | 图（实体 + 关系）| 无 | 无 | **是** | | FTS5 搜索 | 无 | 变化 | **是** | | 可移植包 | 无 | 无 | **是** | | 传输 | SDK / HTTP | 无 | **MCP + JSONL** | ## 今日发货 | 区域 | 当前支持 | |------|-----------------| | 知识库 | `.vouch/` 文件夹，YAML 声明/实体/关系/证据/会话，Markdown 页面带有前面的内容，JSONL 审计日志，内容寻址的源 | | CLI | `init`、`discover`、`capabilities`、`status`、`lint`、`doctor`、`fsck`、`pending`、`show`、`approve`、`reject`、`propose-{claim,page,entity,relation}`、`source add`、`source verify`、`supersede`、`contradict`、`archive`、`confirm`、`cite`、`session {start,end}`、`crystallize`、`search`、`context`、`index`、`audit`、`export`、`export-check`、`import-check`、`import-apply`、`serve` | | 工具服务器 | MCP 通过 stdio + JSONL 通过 stdin/stdout，相同的 `kb.*` 接口在两种传输上，功能 + 知识能力描述符 | | 架构 | 13 个 JSON 架构（由 pydantic 中的 Draft 2020-12 生成）+ 手动维护的 `bundle.manifest` 和 `jsonl-envelope` 架构 | | 写入安全性 | 通过 [proposed/](spec/review-gate.md) 的审查门控写入、`dry_run:true` 预览，需要主机信任的 `approve`/`reject`，原子独家创建存储，源摄入和包导入的路径遍历阻止 | | 检索 | `retrieval.backend` 在 `config.yaml` 中选择路径：`auto`（默认 — 嵌入式 → FTS5 → 子字符串），`embedding`，`fts5` 或 `substring`。语义后端（`all-mpnet-base-v2`，`MiniLM-L6`，fastembed-BGE）随安装额外功能发货；`auto` 在它们不可用时降级为 FTS5。上下文包带有引用 + 质量门控 | | 生命周期 | `supersede`、`contradict`、`archive`、`confirm`、`cite` — 直接突变，所有审计 | | 可移植性 | 带有每个文件 sha256 的 tar.gz 包，`export-check`、`import-check`、`import-apply` 具有 skip/overwrite/fail 冲突模式 | | 审计 | 追加日志 `audit.log.jsonl`，每个事件的执行者（`VOUCH_AGENT`），对象 ID，dry-run 标志，可逆标志 | | 适配器 | 通过 `.mcp.json` 和 `VOUCH_AGENT` 环境变量记录的 Claude Code 连接；每个运行时适配器模板尚未发货 | | 验证 | pytest 套件（存储、FTS5、审计、源验证、审查门控、包、JSONL）、ruff + mypy 门控、GitHub CI | | 规范 | [spec/](spec/) 下的已过时快照，[schemas/](schemas/) 中的 JSON 架构，[scripts/gen_schemas.py](scripts/gen_schemas.py) 中的生成器脚本 | ## 状态 1.0 之前的版本。当前实现中没有的内容：每个运行时适配器模板、基准测试装置、多代理同步、超出 Claim/Source 上的单个字段的作用域。如果某个功能对您很重要，请提交问题。 ## 许可 MIT.