内容
# Klear-Team-Brain
[](https://github.com/Asklear/Klear-Team-Brain/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org)
> **您团队的集体记忆，用于 AI 辅助编码。** 自主托管，极轻量级，对正在工作的团队成员无需额外操作。
中文 | [English](./README.en.md)
---
## 问题
您的团队使用 Claude Code / Codex 进行编码，但 **实际重要的上下文（推理、为什么更改、死胡同）被困在每个人的本地 AI 聊天中，并且在他们关闭标签页后就会丢失。** 因此：
- *"为什么这个功能设计成这样?"* —— 没有任何 PR 中有这个讨论；讨论发生在某人的聊天中，而不是提交消息中。
- *"谁正在进行这个重构，进展如何?"* —— 您需要询问周围的人，或等待每日例会。
- 有一位团队成员离开或辞职，**上一周的推理随着他们离开了。**
知识依赖于 "询问正确的人"。当他们忙碌或离开时，上下文就会中断。
**Klear-Team-Brain 自动将整个团队的 AI 会话汇集到一个共享内存中，与实时的 GitHub 代码状态和团队文档融合。然后，您可以直接在编辑器中询问，或在 Web UI 中浏览：**
> *"在哪里进行了身份验证重构?"*
> *"如何决定计费模式?"*
> *"谁最近在处理 ETL？"*
您从团队的 **会话 + 代码 + 文档** 中获得答案，并附有引用。**正在工作的团队成员无需执行任何操作；需要了解的人只需询问或打开仪表板。**
---
## 亮点
- **零努力捕获** —— 每个人继续使用 CC/Codex；后台收集器自动将会话流入内存，无需手动操作。
- **两种查询方式** —— ① 在编辑器中以自然语言询问（MCP）；② 浏览 Web 仪表板（按人员/仓库/时间筛选会话，查看进度和使用情况统计）。
- **极轻量级，自主托管** —— 服务器仅为 **一个 Git 仓库 + 一个 Node 进程 + 一个静态前端**：无需数据库，无需队列，无需向量存储。**一个小型 VPS（低内存运行正常）** 足以满足需求。查询通过 `git grep` 运行，**无需服务器端 LLM 调用** —— 理解发生在编辑器中的代理中。
- **优先考虑隐私** —— 仅允许列出的目录上传；机密信息在上传前在客户端被编辑；所有数据保留在您自己的基础设施上。
---
## 快速开始
**前提条件：** Node 22+，以及一个 MCP-capable 编辑器/CLI（Claude Code 或 Codex）用于询问。
1. **建立一个服务器** （一个小型 VPS）。参见 [DEPLOY.md](./DEPLOY.md) —— 安装 Node，克隆，设置 `TRUTH_DIR`，添加一个 roster + tokens，配置 HTTPS，运行为服务。
2. **让每个成员加入** —— 将客户端指向您的服务器：
```bash
curl -fsSL https://your-server.example.com/get | bash # 下载客户端并注册 `brain` 命令
brain join <YOUR_INVITE_TOKEN> # 验证 + 选择工作区 + 连接 MCP + 首次同步 + 安装 resident
```
3. **开始使用** —— 在编辑器中询问，或打开 `https://your-server.example.com/` 以浏览仪表板。
一旦加入，收集器就会在后台监视您的 AI 会话，并在会话稳定后上传每个会话 —— **之后无需手动操作。**
---
## 两种查询方式
### ① 在编辑器中询问（MCP）
连接 MCP 后，在 CC / Codex 中用自然语言询问（例如 *"身份验证重构在哪里进行?"*）。代理将内存视为一个 **只读文件夹**，并使用类 Unix 原语来定位、读取和合成 —— 所有这些都通过一个相对于 truth-store 的路径绑定在一起：
| 工具 | 功能 |
|---|---|
| `grep` | 搜索内容（正则表达式全文检索，通过 git grep）。默认为编辑后的转录；`raw=true` 包括原始 jsonl。 |
| `find` | 按名称/通配符查找文件（与 grep 互补：一个搜索内容，一个搜索名称）。 |
| `read` | 按路径读取任何文件（分页大文件，偏移/限制）。 |
| `ls` | 检查结构：哪些空间存在，分支，会话计数。 |
| `log` | 活动时间线（git 历史记录；按空间/作者/时间范围）。 |
| `read_github` | 联系 GitHub 获取实时代码状态或文件的当前内容（代码本身不存储）。 |
服务器端查询通过 `git grep` / `git ls-files` / `git log` / `fs` 运行 —— **execFile，无 shell，在 `TRUTH_DIR` 内锁定，只读** —— 且 **无服务器端 LLM 调用**。
> **连接其他编辑器：** MCP 服务器是一个 stdio 服务器；命令始终为 `<node> <install-dir>/mcp/server.mjs`（`brain mcp` 打印您的确切路径）。在 Claude Code、Codex 或任何 MCP-capable 客户端（Gemini CLI / Cursor / Cline / opencode…）中添加它作为 stdio MCP 服务器。
### ② 浏览 Web UI
服务器在 `/` 处托管一个 **静态仪表板**（无需额外部署）—— 适用于那些更喜欢扫描而不是输入的人：查看整体团队进度，按人员/仓库/时间筛选会话，查看令牌使用情况和活动统计，浏览镜像文档。
**浏览会话** —— 按人员/仓库/时间筛选，排序为最近活动：
**使用情况统计** —— 按天/周/人员/仓库/工具聚合令牌，会话和回合：
---
## 工作原理
```
每个机器（客户端） 您的服务器（自主托管）
┌────────────────────────┐ ┌──────────────────────────────────┐
│ ① 收集客户端/同步 │ gzip+token │ ② 服务器/server.mjs（HTTP，HTTPS │
│ resident，监视 AI │ ──────────▶ │ 通过代理（如 Caddy） │
│ 会话；门控到允许 │ │ /ingest → git truth store │
│ 列表圈 │ │ TRUTH_DIR + 4h GitHub 轮询 → │
│ │ │ 代码状态 │
│ 查询 A：在编辑器中询问 │ search+fetch│ /grep /find /read /ls /log │
│ 查询 B：打开 Web UI │ ◀────────── │ + 静态仪表板托管在 / │
└────────────────────────┘ └──────────────────────────────────┘
```
内存是一个单一的 **git 仓库**，融合了三个来源 —— **每个来源都在其自然位置捕获：**
| 您想知道什么 | 主要存在于 | 如何进入内存 |
|---|---|---|
| **进度 · 推理** | CC/Codex 会话 | 蒸馏 + 编辑，存储为全文转录 |
| **代码状态** | GitHub | 不存储；按需获取 + 4 小时轮询到 `code-state` |
| **目标 · 决策（人类编写）** | 团队文档（Lark/Feishu wiki） | 文档正文单向镜像；grep/read 它，在源处编辑 |
> **设计权衡：** 只有 "真相"（原始材料 + 元数据）保持干净和完整 —— 因为它很昂贵且无法重建；"视图"（查询/索引/仪表板）是可互换和可丢弃的。会话以 **蒸馏** 形式进入（内联图像剥离，巨型工具输出截断 —— 信号，非字节）；生产者机器上的字节精确原始文件保留在 `~/.codex` / `~/.claude` 中。
---
## 隐私与安全
- **范围门控：** 仅当会话的工作目录位于机器的 `upload_folders` 允许列表中时，才会上传会话 —— 默认情况下，允许列表内的 circle 是共享的，外部是私有的。
- **编辑：** 机密/token + 家目录路径在上传前在客户端被剥离，服务器在 `.md` 处和 `/read` 出口处进行二次检查。
- **凭证永不存储：** 成员令牌，GitHub PAT 和文档源凭证都存放在服务器端，并被 gitignored；可以提交 roster（无机密）。
- **内存是整个价值 —— 永不推送到公共远程，并备份。** 在仅对您的 circle 开放的基础设施上自主托管。
> **状态：** 早期，自主托管，单租户。您运行自己的服务器；没有任何内容离开您的基础设施。
---
## 可选：镜像团队文档（Lark / Feishu）
如果您的团队在 Lark/Feishu **wiki** 中保留人类编写的文档（目标，决策，笔记），服务器可以单向 **镜像** 这些文档正文到内存中，以便询问代理可以 `grep`/`read` 它们与会话和代码一起。设置一次：
1. **在 Lark/Feishu 开发者控制台中创建一个自定义应用**（一个 *企业自定义应用*）；记下其 **App ID** + **App Secret**。
2. **启用读取范围** 在 *权限* 下：`docx:document.readonly`，`drive:drive.readonly`，`wiki:wiki.readonly`，然后发布一个版本并让管理员批准。（无需搜索范围 —— 镜像在本地搜索。）
3. **在整个 wiki 上授权应用 — 这一非显而易见的步骤，实际上限制了访问权限。** 租户令牌应用只能看到它已被显式添加到的 wiki，而控制台不允许您直接添加应用。相反：
1. 创建一个组/聊天。
2. 将 **此应用的机器人** 添加到该组 — 它必须是与 **相同的** App ID（添加错误的机器人是最常见的失败原因）。
3. 在 wiki 中，转到 **设置 → 成员 → 角色和权限 → 管理员 → 添加管理员** 并添加 **该组**。
然后应用对整个 wiki 有读取权限（传播需要 ~1–2 分钟）。
4. **将凭证放到服务器上：** 复制 `feishu.example.yaml` → `feishu.yaml`（机密 → gitignored），填写 `app_id` / `app_secret`，然后重启。完全省略它，文档层将保持静默关闭。
5. **验证：** 在一个轮询周期后，文档出现在 `feishu/<wiki>/…` 内存中，可通过 `grep` 搜索。
> 中国 Feishu (`open.feishu.cn`) 和国际 Lark (`open.larksuite.com`) 是隔离的平台 —— 在您的团队使用的平台上创建应用。创建新的 **wiki**？重复步骤 3，或 brain 将看不到它。
---
## 更新日志
每个版本中更改的内容：[更新日志](./public_docs/CHANGELOG.en.md)（[中文](./public_docs/CHANGELOG.zh-CN.md)）。
## 非目标
它聚合并帮助您理解 CC/Codex 会话 + GitHub + 文档中的内容。 它 **不是** 即时通讯工具、项目管理器或代码托管工具，也不会取代它们。
## 贡献
欢迎提出问题和 PR —— 参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 和 [SECURITY.md](./SECURITY.md)。该项目在内部开发并镜像到此处；外部贡献被审查和合并上游，然后流回。
## 许可证
[Apache-2.0](./LICENSE) © Asklear
