governed-second-brain-plugin

<h1 align="center">受管控的第二大脑 — 插件</h1> <p align="center"> 一个本地优先的 Claude Code + Cowork 插件：将您自己的文件转化为受管控的、<code>qmd://</code> 引用的第二大脑，并具有篡改证据的 SHA-256 哈希链审计追踪。<br> <strong>编译，然后管控。</strong> 一个插件，两种模式：<strong>本地</strong>（默认 — 进程内，无守护进程，无网络，无 API 密钥用于检索）或 <strong>团队</strong>（通过网络代理到共享的受管控大脑）。 </p> <p align="center"> <img src="https://img.shields.io/badge/License-Apache--2.0-10b981?style=flat-square" alt="许可证：Apache-2.0"> <img src="https://img.shields.io/badge/本地优先-进程内-0ea5e9?style=flat-square" alt="本地优先"> <img src="https://img.shields.io/badge/MCP-stdio-8b5cf6?style=flat-square" alt="MCP 标准输入输出"> </p> --- ## 📍 该产品存在于两个仓库 | | 仓库 | 描述 | |---|---|---| | **首页 / 論文** | **[intent-solutions-io/governed-second-brain](https://github.com/intent-solutions-io/governed-second-brain)** | 伞形项目 — *为什么* 存在该项目，竞争性分析，"编译，然后管控" 論文，收据论证。 从这里开始了解 **故事**。 | | **插件**（您当前所在） | **[jeremylongshore/governed-second-brain-plugin](https://github.com/jeremylongshore/governed-second-brain-plugin)** | 可安装的代码 — 本地标准输入输出 MCP 服务器 + 技能。 从这里开始 **运行**。 | 它建立在三个引擎之上： | 引擎 | 仓库 | 层 | |---|---|---| | **ICO** | [jeremylongshore/intentional-cognition-os](https://github.com/jeremylongshore/intentional-cognition-os) | **编译** — 从语料库中导出知识（可选；唯一出口部分） | | **INTKB** | [jeremylongshore/qmd-team-intent-kb](https://github.com/jeremylongshore/qmd-team-intent-kb) | **管控** — 确定性去重 → 策略 → 提升 + 哈希链审计 | | **qmd** | [tobi/qmd](https://github.com/tobi/qmd) | **检索** — 设备上搜索；每个命中都是 `qmd://` 引用 | 该插件**捆绑**了编译后的 INTKB 包，因此它在进程内运行管控 + 检索循环 — 引擎保持独立的仓库；这里没有分叉或私有化它们。 ## 它能做什么 大多数“AI 记忆”让代理更好地*回忆*。它做了两件事，而类别跳过了：它**管控**什么被允许成为持久记忆（确定性去重 / 策略 / 提升 — 通过代码，而不是模型），并且它发送一个**收据** — 一个 `qmd://` 引用和一个 SHA-256 哈希链审计事件 — 对于每次写入。 在您的机器上运行；您的文件永远不会离开它（检索是本地的；可选的 ICO *编译* 步骤是唯一出口，并且是可选的）。 ### 工具表面 | 工具 | 类型 | 描述 | |---|---|---| | `brain_search` | 读取 | 在您的受管控内存（`qmd://` 收据）上进行引用搜索，进程内 | | `brain_status` | 读取 | 按生命周期状态 + 类别计数 | | `brain_audit_verify` | 读取 | 验证审计追踪 — SHA-256 哈希链 **和** 外部锚点日志；标记任何篡改 | | `brain_capture` | 写入 | 将事实捕获为管控 **提案**（到本地队列） | | `brain_govern` | 写入 | 排空队列 → 去重 → 策略 → **提升**，带有哈希链审计收据 — 无守护进程 | | `brain_transition` | 写入 | 退休 / 重新生命周期内存（已审计） | 两个技能前端：**`/brain`**（引用答案）和 **`/brain-save`**（管控捕获）。 ## 收据不做什么 诚实是收据的重点。 链条为您提供**篡改检测** — 完整性 + 排序， 因此编辑或重新排序的记录被 `verify` 捕获。 它 **不是** 防篡改： 在您自己的机器上，具有访问权限的写入者可以编辑事件 **和** 重新哈希链条向前。 在单个信任边界内（您的机器），这正是您想要的完整性保证； 跨参与者不可否认性需要外部链条头锚点（在路线图中）。 它 **不是** 区块链和 **不是** 不变存储。 ## 独立验证锚点日志 `brain_audit_verify` 是*内置*检查 — 它在写入链条的同一个代码库中运行（循环信任）。 对于“不信任我们，自己运行”，有一个**独立的零依赖验证器**，它重新导出每个锚点哈希本身，导入**没有任何**来自此插件或引擎。 这是收据的 `cat log.md` — 一个文件，只有 Node.js 内置模块（`crypto`，`fs`，`child_process`），无需构建步骤： ```bash # 默认情况下为 $HOME/.teamkb/audit/anchors.jsonl node scripts/verify-anchors.mjs # 显式，并交叉检查实时数据库头与最新锚点 node scripts/verify-anchors.mjs \ --anchors "$HOME/.teamkb/audit/anchors.jsonl" \ --audit-dir "$HOME/.teamkb/audit" \ --db "$HOME/.teamkb/teamkb.db" npm run verify-anchors # 相同，通过包脚本 node scripts/verify-anchors.mjs --json # 机器可读输出 ``` 它检查外部锚点日志（`anchors.jsonl`，一个追加哈希链）的四件事： 1. **每记录完整性** — 从规范正文重新计算每个 `anchorHash`； 任何编辑都是 `ANCHOR_HASH_MISMATCH`。 2. **链条链接** — `record[0].prevAnchorHash` 为 `null`， 每个后续 `prevAnchorHash` 等于前一条记录的 `anchorHash`， 并且 `chainedRows` 永远不会减少。 3. **外部见证（git）** — 确认锚点日志已提交且干净（未提交或未推送的日志仅*本地*见证 — 显示为警告，而不是硬失败）。 4. **可选数据库交叉检查**（`--db`，需要 `sqlite3` 在 PATH 上）— 最新锚点的 `chainHead` 必须等于实时审计链的当前头部，并且其 `chainedRows` 不能超过当前计数， 捕获历史的静默重写，内置链条行走单独会错过。 退出 `0` 表示通过（仅见证警告仍退出 `0`）； 在任何完整性，链接或历史重写失败时返回非零。 使用 `npm run verify-anchors:test` 运行验证器的自身测试。 ## 安装 一条命令，两种模式： ```bash # A) 零出口（受监管/客户端数据的默认）— 没有任何内容离开机器 npx governed-second-brain init <您的文件夹> --index-only # B) 完整编译 — ICO 在管控之前导出知识（6 次传递）； 可选出口到 DeepSeek DEEPSEEK_API_KEY=… npx governed-second-brain init <您的文件夹> ``` 它在 `~/.teamkb` 下建立了一个受管控的、引用 `qmd://` 的、哈希链审计的大脑，安装了每个平台的本机依赖，并**自动将 MCP 服务器注册到 Claude Code**（`claude mcp add`； `--no-register` 跳过）。 完整模式运行一个响亮的预飞行同意（您的文件文本发送到 DeepSeek； `--yes` 跳过提示）。 需要 Node.js 20+，C/C++ 工具链（用于 `better-sqlite3`）和 PATH 上的 `qmd` 2.x 进行检索。 完成后，启动一个新的 Claude Code 会话 — `governed-brain` 工具已启用。 对于 `/brain` 和 `/brain-save` 技能也是如此，`claude plugin install governed-second-brain`. ### 团队模式 — 指向共享大脑 **相同的**插件在设置 `TEAMKB_API_URL` 时以**团队模式**运行： 代替进程内的本地大脑，它通过网络上的共享管控大脑 HTTP API（INTKB 的 `apps/api`）进行代理 — 因此整个团队查询并贡献于**一个**管控大脑。 设置两个环境变量： - **`TEAMKB_API_URL`** — 您团队大脑的 API 基础（例如 `http://<host>:3847`） - **`TEAMKB_API_TOKEN`** — 您的个人承载令牌（由大脑的操作员颁发） 您需要访问该 API 的网络可达性 — 通常是私有网络 / VPN，例如 **Tailscale**（大脑被设计为远离公共互联网）。 调度器根据 `TEAMKB_API_URL` 自动检测模式： 设置 → 团队，未设置 → 本地。 相同的 `/brain` + `/brain-save` 技能无论哪种方式。 在团队模式下，工具表面是 **`brain_search`**（读取）+ **`brain_capture`**（提议）+ **`brain_transition`**（仅限管理员）— 管控在服务器端运行，因此没有客户端 `brain_govern`： **模型提出，服务器处置**， 每个提升都有哈希链收据。 成员令牌可以读取 + 提议； 否则，管理员操作（转换）返回清晰的 403。 > 团队模式是**无依赖** — 它仅使用 `fetch` + MCP SDK，从不使用本机存储 — 因此它直接从市场克隆中运行，零构建。 <details><summary><strong>从源代码构建</strong>（用于黑客运行时）</summary> ```bash pnpm -C ../qmd-team-intent-kb build # 包绑定 INTKB 的编译包（兄弟校验，构建） pnpm install && pnpm build # esbuild → 插件运行时/governed-brain.cjs node bin/init.mjs init <您的文件夹> --index-only ``` </details> **供应链（0.1.4 中发布）：** npm **出处**（通过 CI 发布工作流）和 `gsb.lock.json` 可复制销钉 — 精确的 ICO × INTKB × qmd × 插件元组，由与销钉集的完整链 CI 烟雾测试验证。 **即将推出：** 自动 Cowork MCP 注册。 ## 许可证 Apache-2.0. 伞形项目和两个引擎仓库都是 Apache-2.0； qmd（上游）由其作者 [@tobi](https://github.com/tobi) 以 MIT 许可。 --- <p align="center"> 由 <a href="https://github.com/jeremylongshore">Jeremy Longshore</a> · <a href="https://intentsolutions.io/">Intent Solutions</a> · 论文在 <a href="https://github.com/intent-solutions-io/governed-second-brain">intent-solutions-io/governed-second-brain</a> </p>