内容
# 第二大脑 — 面向 Claude Code 的便携式知识库
一个Claude Code **市场插件**，给予任何代理一个第二大脑：回忆 + 捕获技能，由git仓库支持，通过捆绑的**零依赖**MCP服务器提供支持，并具有**匿名git-token处理**。
从 [Noah Almighty / avatar-chat](https://example.invalid) 的大脑技能中提取，以便在 vanilla Claude Code（或任何MCP-capable代理）中运行独立于该系统的进程内工具和多租户信任模型。
## 内部结构
```
.claude-plugin/marketplace.json ← 市场清单（此仓库是一个市场）
plugins/second-brain/
├── .claude-plugin/plugin.json ← 插件清单
├── .mcp.json ← 启动捆绑的MCP服务器
├── mcp/ ← “大脑”MCP服务器（Node，零依赖）
│ ├── index.mjs ← JSON-RPC/stdio循环 + 工具调度
│ ├── git.mjs ← 令牌匿名git管道
│ ├── search.mjs ← wiki/上的关键词排名
│ └── vault.mjs ← 路径保护的文件系统帮助程序
└── skills/ ← 大脑搜索 / 提取 / 反射 / 清理 / 迁移
```
知识库本身是一个单独的git仓库，持有 `wiki/`（精选笔记）和 `raw/`（捕获） — 您通过环境变量（如下）指向插件。每个安装一个知识库。
## 安装
```
/plugin marketplace add jinyoung/brain-skills # 或此仓库的本地路径
/plugin install second-brain
```
需要 `node`（≥18）和 `git` 在PATH上。无需 `npm install` — MCP服务器仅使用Node内置模块，因此在插件克隆后立即运行。
## 配置（环境变量）
插件的 `.mcp.json` 从您的环境变量中读取：
| 变量 | 含义 |
| ----------------- | ----------------------------------------------------------------------------- |
| `BRAIN_DIR` | 知识库的本地工作树路径。默认值：`~/.second-brain`。 |
| `BRAIN_REPO` | 远程知识库：`owner/repo`，GitHub URL或任何git URL。省略则仅限本地使用。 |
| `BRAIN_GIT_TOKEN` | `BRAIN_REPO` 的身份验证令牌（私有仓库 / 推送）。**可选** — 参见下面的身份验证。 |
| `BRAIN_GIT_HOST` | `owner/repo` 形式的GitHub主机。默认值：`github.com`。 |
- **使用 `BRAIN_REPO`：** 知识库将在首次使用时克隆/同步，`commit`会推送回去。
- **不使用它：** `BRAIN_DIR` 是一个纯粹本地的git仓库；`commit` 保留在本地。
## 身份验证到远程知识库
两种方式，按优先级顺序：
### 1. 凭证助手（推荐 — 环境变量中没有令牌）
**保持 `BRAIN_GIT_TOKEN` 未设置。** 没有令牌，MCP服务器不会附加身份验证头，git会以正常方式解析凭证 — 从您的OS密钥链 / git凭证助手：
```
gh auth login # 或 git-credential-manager, osxkeychain, libsecret, …
# 不要设置 BRAIN_GIT_TOKEN
```
为什么这样更安全：导出的PAT作为环境变量被每个代理生成的子进程继承 — 包括其Bash工具 — 因此模型可以使用 `printenv` 读取它，它将出现在模型的上下文中（即离开您的机器）。相反，将令牌保留在OS密钥链中意味着它永远不会作为环境变量出现，代理可以读取。服务器以非交互方式运行git（`GIT_TERMINAL_PROMPT=0`），因此如果助手没有缓存的凭证，它会快速失败而不是挂起。
### 2. `BRAIN_GIT_TOKEN` 环境变量（备用）
如果您确实使用环境变量，请优先使用 **细粒度PAT作用于仅限知识库仓库**（`contents: read/write`）以限制其泄露时的波及范围。令牌在git方面仍然是**匿名**的（如下）— 但上述环境变量暴露的注意事项适用。
## Git令牌匿名化
令牌被视为一个秘密，绝不能持久化或泄露（从avatar-chat的`marketplace.ts`移植的模式）：
1. **远程URL中绝不出现。** 嵌入它会将其写入磁盘上的 `.git/config`。相反，它在每次调用时作为 `git -c http.extraHeader=Authorization: Basic <base64>` 头部提供，git在传输时使用它，但绝不持久化。
2. **从错误中删除。** `execFile` 拒绝包含完整的argv（包括该头部，其base64解码回令牌）。每个git错误都经过 `scrubGitError` 处理，该函数在将任何内容返回给模型或记录之前将其删除为 `[REDACTED]`。
3. **仅限环境变量。** 令牌仅从 `BRAIN_GIT_TOKEN` 读取；它绝不会被任何工具回显。
提交作者/提交者来自您自己的git配置 — 身份不会被覆盖。
## 工具（作为 `mcp__brain__*` 显示）
| 工具 | 目的 |
| ------------ | ------------------------------------------------------------- |
| `search` | `wiki/`上的排名回忆（标题/别名 > 标签 > 正文）。 |
| `get_note` | 读取完整的 `wiki/…` 笔记 + 解析的图页脚（链接 → 路径，悬空标志，反向链接）。 |
| `list_files` | 列出工作树（可选地限定在子目录中）。 |
| `read_file` | 读取任意知识库文件。 |
| `write_file` | 创建/覆盖文件（父目录创建）。 |
| `commit` | 暂存所有，提交并推送（令牌匿名）。 |
| `status` | 报告远程 / 工作树 / 知识库布局 / 待处理路径。 |
您也可以使用Claude Code的内置工具编辑工作树（通过 `status` 查找路径），但始终 **使用 `mcp__brain__commit` 持久化** — 只有该路径会推送并匿名化令牌。
## 开发
MCP服务器仍然具有 **零运行时依赖** — `plugins/second-brain/package.json` 只连接了Node的内置测试运行器（无需 `npm install` 即可运行插件）。测试涵盖了纯逻辑（前言解析，搜索排名，路径保护，令牌擦除，维基链接图）以及真正的本地git提交：
```
cd plugins/second-brain && npm test # node --test, 无依赖
```
## License
MIT
