# https://github.com/PDgit12/knitbrain 项目说明书

生成时间：2026-06-23 18:41:36 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [无损上下文压缩与 Read 优化](#page-2)
- [记忆、知识图谱与层级路由工作流](#page-3)
- [自治循环、多平台集成与运维](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[无损上下文压缩与 Read 优化](#page-2), [记忆、知识图谱与层级路由工作流](#page-3), [自治循环、多平台集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [tsconfig.build.json](https://github.com/PDgit12/knitbrain/blob/main/tsconfig.build.json)
- [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/engine/knowledge.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/knowledge.ts)
- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [src/setup.ts](https://github.com/PDgit12/knitbrain/blob/main/src/setup.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
</details>

# 项目概述与系统架构

## 一、项目定位与核心目标

`knitbrain` 是一个面向 AI 编程代理（agent）的**统一上下文与记忆底座**（unified substrate），以 MCP（Model Context Protocol）服务器形式交付，暴露 **27 个工具**，覆盖所有主流 MCP 客户端（Claude Code、Cursor、Codex、Copilot、Windsurf、Cline 等）[README.md:1-30]()。

它在 README 中明确点出与同类工具的关键差异：

> "Most tools in this space pick one axis. Compression layers shrink tokens but remember nothing. Memory layers remember but burn your context window. knitbrain is **one substrate** that does both."

`knitbrain` 在单基底上同时承担四类职能——**压缩、记忆、工作流、自主循环**，运行时为**纯 Node、零 Python、零 ML 运行时、所有数据本地化** [README.md:11-19]()。安装方式与运行要求如 [package.json:33-58]() 所示：`engines.node >= 18.0.0`，仅依赖 `@modelcontextprotocol/sdk`、`@vscode/tree-sitter-wasm`、`gpt-tokenizer` 三个运行时包。

`npm run verify` 串联 `typecheck → lint → test → build → consistency → bench` 全套质量门禁 [package.json:36-58]()；TypeScript 构建通过 `tsconfig.build.json` 限定 `rootDir: src`，与 `tests/`、`scripts/` 解耦 [tsconfig.build.json:1-8]()。

## 二、系统架构总览

下图展示 `knitbrain` 的分层架构。客户端通过 MCP 握手进入系统，工具调用经由分发层在**压缩、记忆、知识图谱、工作流、团队协作**五个子系统中路由；可选的请求代理（proxy）在 API-key 模式下提供线缆侧压缩。

```mermaid
graph TB
  Client["MCP 客户端<br/>(Claude Code / Cursor / Codex ...)"] -->|stdio MCP| Server["MCP 服务器<br/>src/mcp/tools.ts"]
  Server -->|dispatch| Router["压缩路由器<br/>src/optimizer/router.ts"]
  Router -->|detect ContentType| Types["ContentType:<br/>json/code/text/prose/search/log/diff"]
  Router -->|skeleton + ⟨recall:hash⟩| CCR["CCR 内容寻址存储"]
  Server -->|verbatim| Workflow["工作流引擎<br/>src/engine/workflow.ts"]
  Workflow -->|tier: inquiry→complex| Agent["Agent 生成器<br/>src/engine/agents.ts"]
  Agent -->|spawn| Team["团队看板 / 知识图谱<br/>src/engine/memory.ts & knowledge.ts"]
  Server -.->|optional| Proxy["请求代理<br/>src/proxy/optimize-request.ts"]
  Proxy -->|API key| Provider["LLM Provider"]
  Provider --> Client
```

### 关键约束

- **输出调度策略**：工具根据其 `output` 字段分为 `"data"`（自动压缩，返回骨架 + recall 句柄）与 `"verbatim"`（按字面返回，绝不骨架化） [src/mcp/tools.ts:21-36]()。
- **绝不扩张守门**：若压缩节省比例低于 `PARAMS.minSavingPct`，直接透传原文 [src/optimizer/router.ts:80-100]()。
- **声明救援**：对代码块执行 `rescueDecls`，把因 brace 范围超出而被吞掉的顶层签名重新追加到骨架尾部，保证 API 表面积永不消失 [src/optimizer/router.ts:30-45]()。

## 三、核心子系统

### 3.1 压缩与内容寻址存储

路由器是系统的"省 token 引擎"。它通过 `detect()` 对输入做**确定性**内容类型识别（无 ML），识别顺序为 `json → diff → search → log → code → text`，结构化形状严格优先于宽松启发式 [src/optimizer/router.ts:55-65]()。`ContentType` 枚举在 [src/optimizer/types.ts:1-6]() 中定义。压缩后的原始字节以**内容寻址**方式存入 CCR（`Content-Addressed Recall Store`），通过 `⟨recall:HASH⟩` 句柄随骨架返回，agent 可按需 `knitbrain_retrieve` 取回字节完全一致的原文 [src/mcp/tools.ts:60-90]()。

真实数字来自约 300 万真实工具结果 token 的全量测量：平均节省约 **46%**（仅计 ≥400 token 块时约 55%）[README.md:30-45]()。`scripts/bench.ts` 将测试夹具按"真实形状分布"（代码 47%、重复日志 17%、短文 16%、长文 7%、测试输出 6%、JSON 5%、diff 1%）组织，并设**保真底线**——错误行与结果摘要必须 byte-for-byte 存活 [scripts/bench.ts:1-30]()。

### 3.2 记忆与知识图谱

`createMemory()` 提供**项目级、文件落盘的**学习与交接（handoff）系统，learnings 按"outcome 评分"排序，错误上报的 learning 会被降低权重（discredit）[src/engine/memory.ts:1-60]()。`createKnowledge()` 构建依赖图谱（TS/JS 正则解析，零依赖），并在加载时一次性构建**反向邻接索引**以将 `queryDependents` 降为 O(1) 查找；**幽灵剪枝**保证已删除文件不会从陈旧缓存中冒头 [src/engine/knowledge.ts:1-50]()。

### 3.3 分级工作流与自校准

工作流引擎是**确定性**（无 ML）的分级路由器，按关键词正则将任务归入 `inquiry / trivial / standard / complex` 四档 [src/engine/workflow.ts:1-50]()。`complex` 触发 plan-mode 与完整 6 阶段流程；分类器通过 `knitbrain_record_false_positive` 工具累积误报，触发阈值偏移（`scopeAdjust`），形成**自愈式**反馈环 [src/mcp/tools.ts:200-240]()。Agent 生成器根据项目文件列表提议子 agent，写入 `.claude/agents/<safe-name>.md`，名称被强制 slug 化以保证安全 [src/engine/agents.ts:1-50]()。

### 3.4 自主循环

外层提供 `knitbrain loop <goal>`（单 worker 验证门控）与 `knitbrain fan <goal>`（N 个隔离 git worktree 并行）两条命令，**永不自动合并** [README.md:60-80]()。`AGENTS.md` 通过 `knitbrain setup` 写入，承载域架构与质量门禁规约 [CLAUDE.md:1-50]()；`runSetup` 自动检测平台并以非破坏方式写入原生 MCP 配置 [src/setup.ts:1-50]()。

## 四、版本亮点（0.4.4）

最新版 0.4.4 修复了 `knitbrain_read` 的关键可用性问题：此前拒绝 MCP 服务器 `cwd` 之外的所有路径，导致用户级安装时回退到宿主原始 `Read`。修复后**接受绝对路径**，与宿主 `Read` 形成真正的"直接替代"关系；277 个测试全部通过，CI 绿色。此变更使 `knitbrain_read` 在 Claude Code 等传入绝对路径的宿主中真正可用 [src/mcp/tools.ts:100-130]()。

## 五、See Also

- [压缩与内容寻址子系统（CCR）](#) — 路由器、句柄协议、保真度
- [记忆与知识图谱子系统](#) — learnings 排序、依赖图谱、handoff
- [工作流与分级路由](#) — Tier 词汇、calibration、plan-mode 触发
- [MCP 工具目录](#) — 27 个工具的 `output: data | verbatim` 分类
- [本地部署与 setup](#) — 平台检测、`AGENTS.md`、原生配置写入

---

<a id='page-2'></a>

## 无损上下文压缩与 Read 优化

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [记忆、知识图谱与层级路由工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
</details>

# 无损上下文压缩与 Read 优化

## 设计目标与核心原则

knitbrain 的核心承诺是 **"无损 (lossless) 上下文压缩"**：把工具结果（例如长文件读取、JSON、日志、diff）压缩成仍可被智能体 (agent) 导航的"骨架 (skeleton)"，并把完整原文写入内容寻址的召回存储 (Content-Addressed Recall, CCR)。当骨架信息不足时，智能体通过 `⟨recall:HASH⟩` 句柄按字节回填——保证信息永远不会丢失。压缩路径在节省比例低于阈值时也会 **"透传 (pass-through)"** 不展开，避免无效压缩造成的浪费，参见 [src/optimizer/router.ts:48-72](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts) 的 `NEVER-EXPAND GUARD`。

README 明确指出，knitbrain 是 **"一整块基板"**，同时承担记忆、压缩、工作流三类职能，其中压缩基线来自约 300 万真实工具结果 token 的实测，**平均节省约 46%**（资料来源：[README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)）。

## 压缩路由器架构

路由 (router) 是压缩系统的入口。它先做 **确定性内容类型检测 (deterministic content-type detection)**，再把载荷交给对应的专用处理器 (handler)。检测顺序经过精心排序：JSON → diff → search → log → code → text，结构化形态优先于松散的代码启发式，避免 grep 输出和测试日志误判为代码（资料来源：[src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)）。

```mermaid
flowchart LR
    A[工具结果 / 文件读取] --> B[detect]
    B -->|json| J[compressJson]
    B -->|diff| D[compressDiff]
    B -->|log| L[compressLog]
    B -->|search| S[compressSearch]
    B -->|code| C[AST / anchor]
    B -->|text| T[prose anchor]
    J --> R[CCR 召回存储]
    C --> R
    D --> R
    L --> R
    S --> R
    T --> R
    R --> K[⟨recall:HASH⟩ + 骨架]
```

处理器使用 tree-sitter WASM 做 **AST 骨架 (signatures/schema 保留，函数体裁剪)**；文本走句子锚点 (sentence anchor)；log/diff/search 走各自的结构化处理器。代码路径还有一个 **声明救援 (declaration rescue)** 步骤，重新追加被函数体省略"吞掉"的顶层签名，防止多文件串联时签名消失（资料来源：[src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)）。

## knitbrain_read 与 0.4.4 路径修复

`knitbrain_read` 是面向所有 MCP 客户端的 **Read 替代品**：以结构保留的骨架 + 召回句柄返回，节省约 70–90% token。社区近期反馈（0.4.4 发布说明）指出，该工具过去 **拒绝 MCP 服务器工作目录之外的路径**，而 Claude Code 等宿主实际传入的是 **绝对路径**，导致用户级安装回退到宿主原始 Read，破坏"用 knitbrain 替代原始 Read"的工作流。

修复方案：在 `knitbrain_read` 内既接受绝对路径，也接受相对于 `process.cwd()` 的相对路径；不再做项目根路径拒绝——智能体本身已具备宿主 Read 的能力，此处做 scope 仅影响可用性而不增加安全性（资料来源：[src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)）。这与 `knitbrain_ping`、召回 `onRetrieve` 投票等"出口规约 (output discipline)"一致——`data` 类自动压缩，`verbatim` 类原样返回，保证协议/治理输出按字面读取（[src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)）。

## 内容类型与召回契约

`ContentType` 枚举定义了六类：json / code / text / prose / search / log / diff。`prose` 是 **产出型 (produced)** 而非检测型——短文本经句子锚点压缩后被归为 prose，拥有独立的 TOIN (Token-Oriented Instrumentation Network) 自我调优系数（资料来源：[src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)）。

`CompressResult` 接口同时携带 `skeleton`、`handle`、`contentType`、`compressed`、`originalTokens`、`skeletonTokens`、`savedPct`，使得下游 (`knitbrain_metrics`、`knitbrain_evals`) 能基于 TOIN 信号调整各类型召回率，形成 **闭环自调优**（资料来源：[src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)）。

## 代理请求侧的协同优化

在 API-key 路径上，`knitbrain wrap claude` 启动的回环代理会进一步在请求侧做 **缓存对齐 (cache alignment)**：把"Today's date is …"等动态行从系统提示前缀移到带标记的尾部段，正文保留不变，让前缀字节跨会话稳定——直接拉高 prompt-cache 命中率（资料来源：[src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)）。OAuth 流量无法被拦截，因此这条线仅对 API-key 用户生效，但 **工具结果压缩主路径与认证方式无关**。

## 基准测试与置信度

`scripts/bench.ts` 维护两套测试套件：**Real-shape Suite** 用与 3.3M 真实 token 分布同形的样本（代码 47%、重复日志 17%、短散文 16%、长散文 7%、测试输出 6%、JSON 5%、diff 1%）跑完整路由器，每个形态的下限设在实测之下，回归即构建失败；**Best-case Suite** 仍保留旧的合成上界 fixture，只用于校验单个处理器的天花板——**不会被作为真实世界数字引用**（资料来源：[scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)）。`package.json` 的 `verify` 脚本串联 typecheck → lint → test → build → consistency → bench，277 个测试覆盖这一保证（资料来源：[package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)）。

## See Also

- [knitbrain 架构总览](https://github.com/PDgit12/knitbrain#readme)
- [工作流分级与 Tier 路由](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [记忆与学习系统](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)

---

<a id='page-3'></a>

## 记忆、知识图谱与层级路由工作流

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [无损上下文压缩与 Read 优化](#page-2), [自治循环、多平台集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/engine/knowledge.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/knowledge.ts)
- [src/engine/calibration.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/calibration.ts)
- [src/engine/feedback.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/feedback.ts)
- [src/engine/meter.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/meter.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [src/optimizer/structured.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/structured.ts)
- [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
</details>

# 记忆、知识图谱与层级路由工作流

## 概述

knitbrain 的核心并不只是"压缩工具结果"——它是把**记忆、文件级知识图谱、分类器与四层任务路由**编织成同一张控制平面，使代理在压缩与无压缩之间、跨上下文与跨会话之间保持一致的判断与学习回路。系统在 [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts) 维护项目级持久记忆，在 [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts) 内置无机器学习的确定性四档分级，并在 [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts) 暴露的 MCP 工具中形成可被代理调用的"评分—记录—校正"闭环。

## 层级路由工作流

四档任务分类由 [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts) 中的纯正则路由器完成：`inquiry`（只读提问，直接回答）、`trivial`（一行修复，execute → verify）、`standard`（单域任务，轻量循环）、`complex`（跨域 / 高扇出 / 触类型与认证，进入完整 6 阶段并自动 plan 模式）。分类依据来自三组信号：任务描述中的关键字（如 `architect / refactor / security` 触发复杂档；`typo / rename` 触发琐档）、`INQUIRY` 句式正则、以及 `fileCount` 与 `scopeAdjust` 的阈值组合。

```mermaid
flowchart LR
  A[任务描述] --> B{INQUIRY 句式?}
  B -- 是 --> C[inquiry]
  B -- 否 --> D{COMPLEX 关键词?}
  D -- 是 --> E[complex + 6 阶段]
  D -- 否 --> F{TRIVIAL 关键词?}
  F -- 是 --> G[trivial]
  F -- 否 --> H[fileCount + scopeAdjust]
  H --> I[standard]
  E --> J[calibration 反馈]
  G --> J
  I --> J
  J -- 校准 --> D
```

资料来源：[src/engine/workflow.ts:18-50]()。值得注意的细节是：关键字触发的 `complex` 在 `scopeAdjust` 大于 0 时仍被尊重——只有当阈值被**调高**才收紧，**调低**不会让显式的风险词失势。`autoPlanMode` 标志位与 `phases` 列表会随档位一同返回，供下游 MCP 工具组合行动。

## 知识图谱与压缩路由

`Knowledge` 子系统是"按文件维度记忆代理能跑、不能跑什么"的索引层，与路由器深度耦合：[src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts) 中的 `detect()` 按严格优先级 `json → diff → search → log → code → text` 判定载荷类型，[src/optimizer/structured.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/structured.ts) 用至少 20 行且 ≥30% 命中日志签名（时间戳、级别、栈帧、`PASS/FAIL`）来识别 `log`——这一阈值早于更松散的代码启发式，避免 grep 倾倒与测试日志被错判为代码并低质量压缩。`ContentType` 在 [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts) 中明确定义为 `"json" | "code" | "text" | "prose" | "search" | "log" | "diff"`，其中 `prose` 由短文锚点**产出**而非检测得来，是独立的 TOIN 类别，让"短散文被反复回拉"得以独立降权。路由器还内嵌"声明救援"逻辑——若多文件转储中某函数的大括号吃掉后续签名，会被 `rescueDecls()` 重新追加，保证 API 表面永不消失。

## 记忆、反馈与校准闭环

项目级记忆以 `learnings.json` + `handoff.txt` 两份文件落地于 [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)。`recordLearning` 在写入前做摘要子串去重，前向迁移旧记录（`helpful/unhelpful` 缺省为 0），并以 `topLearnings` 列表作为代理冷启动时最先消费的提示。反馈回路通过 [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts) 暴露的 `knitbrain_feedback_false_positive` 等 verbatim 类工具让代理上报"声称档位 vs 实际档位"：校准器在 `recordFalsePositive` 中累计同向错误，达阈值后**位移** `scopeAdjust`，并把分类器触发 `complex` 所需的最小文件数从 4 改写为 `max(2, 4 + scopeAdjust)`。该闭环使 [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md) 中声明的"Complex 触类型/认证/高扇出"语义可以由用户投票**反向收紧**，而不会被一次误报永久放大。

## 度量与配额

`Meter`（[src/engine/meter.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/meter.ts)）与 `Quota`（[src/engine/quota.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/quota.ts)）把压缩、CCR 存储、检索率等指标聚合成 `knitbrain_metrics` 的输出，让代理和仪表盘都能观察到 TOIN 调参的实时证据。`compress` 函数对节省率低于 `PARAMS.minSavingPct` 的载荷**直接透传**——压缩不是义务，[src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts) 在末尾的"NEVER-EXPAND GUARD"会让系统宁愿保留原文也不强行骨架化。

## 常见失效模式

- **绝对路径被拒**：0.4.4 之前的 `knitbrain_read` 拒绝 MCP server cwd 之外的文件，导致用户级安装回退到宿主原生 Read。修复后接受绝对路径并显式回退到 `resolve(process.cwd(), …)。资料来源：[src/mcp/tools.ts:knitbrain_read]()`。
- **复合多文件转储吞签名**：路由器通过 `rescueDecls()` 补救；若下游手工拼接仍可见签名缺失，可调高 `minSavingPct` 让系统倾向透传。
- **复杂档过宽**：若 `complex` 误命中过多，调用 `knitbrain_feedback_false_positive` 三次同向即可让 `scopeAdjust` 上调并抬高文件数门槛。

## 另见

- 参见 [压缩路由与 TOIN 调参](#) 了解 `detect → skeletonize → recall` 的完整流水线。
- 参见 [MCP 工具清单](#) 查看 27 个工具的输入/输出形态。
- 参见 [代理子图与多工作树 fan-out](#) 了解 `complex` 触发的子代理创建路径。

---

<a id='page-4'></a>

## 自治循环、多平台集成与运维

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [记忆、知识图谱与层级路由工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/engine/knowledge.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/knowledge.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
- [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
</details>

# 自治循环、多平台集成与运维

## 总体架构与定位

knitbrain 是一个本地化 MCP (Model Context Protocol) 服务器，单进程提供 27 个工具，同时承担压缩、记忆、工作流和自治循环四层职责，被设计为"单一基底"。它通过一行 MCP 配置即可接入 Claude Code、Cursor、Codex、Copilot、Windsurf、Cline 等宿主；纯 Node 实现、三个依赖、无 Python、无 ML 运行时，数据完全不出本机。运行时上下文（`ToolContext`）把 CCR 召回存储、记忆、知识图、反馈、团队看板、计量、技能、校准、活动日志等子系统注入到每个工具的 `run` 函数中，构成统一的工具分派扼流点。

资料来源：[src/mcp/tools.ts:1-40]()、[README.md:1-30]()、[package.json:1-30]()

```mermaid
flowchart LR
  Host["MCP 宿主<br/>Claude Code / Cursor / Codex / Copilot / Windsurf / Cline"] -->|stdio MCP| Server["knitbrain MCP 服务器<br/>27 tools"]
  Server --> Router["路由器<br/>classify + compress + recall"]
  Router -->|data| CCR["CCR 召回存储<br/>content-addressed"]
  Router -->|verbatim| Agent["直接回写"]
  Server --> Mem["Memory<br/>learnings + handoff"]
  Server --> Know["Knowledge<br/>file graph + dependents"]
  Server --> Team["Team Board<br/>agents + posts"]
  Server --> Cal["Calibration<br/>scopeAdjust"]
  Server --> Dash["Live Dashboard<br/>auto-detected"]
  Loop["knitbrain loop / fan"] -->|verify-gated| Server
  Fan["git worktree 隔离 N 工作器"] --> Loop
```

## 自治循环（loop / fan）

自治循环分两层：内层是 MCP 握手之上的 `load → classify → plan → build → verify → record` 流程；外层由 `knitbrain loop <goal>`（单工作器 AFK 排空复选框目标文件，verify-gated）和 `knitbrain fan <goal>`（N 个工作器在独立 git worktree 中并行、绝不自动合并）两条命令承载。任务由 `classifyTask` 路由为四档：`inquiry` / `trivial` / `standard` / `complex`，每档决定执行深度——`inquiry` 直接回答；`trivial` 走 execute → verify；`standard` 走 research → execute → review；`complex` 走完整 6 阶段并自动进入 plan mode。`scopeAdjust` 是 false-positive 反馈循环派生的校准拨盘：正数提高 complex 的文件计数门槛，负数降低；只有关键词触发的 complex 才豁免此调整。

资料来源：[src/engine/workflow.ts:1-30]()、[CLAUDE.md:1-60]()、[README.md:30-90]()

对于 complex 任务，`proposeAgents` 最多生成 4 个角色化子代理（`name` / `scope` / `tools` / `reviewGate` / `brief`），并通过 `writeAgent` 写入 `.claude/agents/<slug>.md`。`writeAgent` 会对 name 做严格的 slug 校验（仅 `[a-z0-9_-]`，禁止分隔符、点号、空名），保证不会逃出 `.claude/agents` 目录；agent 创建事件发布到团队看板并镜像到 hub，每个子代理以 telegraphic skill body 作为 mission brief 冷启动优化。

资料来源：[src/engine/agents.ts:1-30]()、[src/mcp/tools.ts:1-60]()

## 多平台集成与 MCP 接入

`knitbrain_read` 等工具在分派扼流点被强制分类：`"data"` 自动压缩为 skeleton + `⟨recall:hash⟩` 句柄并把原文存入 CCR；`"verbatim"` 原样返回，绝不被骨架化。最新发布的 0.4.4 修复了 `knitbrain_read` 拒绝 MCP 服务器 cwd 之外绝对路径的回归——Claude Code 等宿主实际传入的就是绝对路径，旧版本会因此把用户级安装打回到宿主原始 Read；新版本同时接受绝对路径与相对路径（用 `isAbsolute` 判定并 `resolve(process.cwd(), …)` 兜底），实现对宿主 Read 的"即插即用"取代，同时保持 277 项测试 CI 全绿。

平台探测从 MCP 握手 + 环境变量自动推断宿主与套餐，无需配置；原生用量窗口（Claude OAuth、Copilot 配额）仅在宿主开放时显示，per-agent 优化计量在任何 MCP 客户端上都可用，因为它度量的是 knitbrain 自己的吞吐。可选的 `knitbrain wrap claude` 回路代理为 API key 用户在 wire 上也压缩请求（OAuth 流量无法拦截，订阅用户不适用该路径）；`src/proxy/optimize-request.ts` 的 `alignDynamicContent` 把"Today's date is …"等易变行移到带标记的尾部并空白归一化，从而稳定 Anthropic/OpenAI 协议的提示前缀缓存命中率。

资料来源：[src/mcp/tools.ts:1-90]()、[src/proxy/optimize-request.ts:1-40]()、[README.md:1-120]()

## 运维、质量门禁与记忆

`package.json` 暴露一组覆盖类型、风格、测试、构建、基准、端到端、生产审计的脚本，`verify` 是聚合门禁；`scripts/bench.ts` 的 real-shape 套件按 3.3M 真实工具结果 token 的统计形状运行完整路由器，任何 shape 回归即失败构建，并断言保真度（错误行、结果摘要必须 byte-for-byte 往返）。CLAUDE.md 把代码域进一步划分为 Core Logic、Infrastructure、Quality Assurance，并为各域指派评审代理（`knit-typescript-pro`、`code-reviewer`、`knit-qa-expert` 等），所有合并前必须通过统一门禁。

记忆子系统（`createMemory`）是项目级、文件后端、确定性的：learnings 通过 `helpful` / `unhelpful` outcome 信号自我净化（错误上报 discredit 并下沉，有用则上升），`learningHealth` 把学习分为 `unproven` / `proven` / `discredited`；handoff 会带时间戳并在加载时判定 `handoffStale`，避免跨会话的过期状态被当作新事实。知识子系统（`createKnowledge`）构建文件依赖图并预计算反向邻接索引，使 `queryDependents` 保持 O(1)；`existsSync` ghost-prune 保证已删除的节点不会从陈旧缓存中冒名出现。

资料来源：[package.json:1-60]()、[scripts/bench.ts:1-20]()、[CLAUDE.md:1-90]()、[src/engine/memory.ts:1-50]()、[src/engine/knowledge.ts:1-30]()

## See Also

- 压缩路由器与 CCR 内容寻址
- 校准与 false-positive 反馈循环
- 团队看板与 hub 镜像

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：PDgit12/knitbrain

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/PDgit12/knitbrain | host_targets=mcp_host, claude_code, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/PDgit12/knitbrain | README/documentation is current enough for a first validation pass.

## 3. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/PDgit12/knitbrain | matched external service / cloud / webhook / database keyword

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/PDgit12/knitbrain | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/PDgit12/knitbrain | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/PDgit12/knitbrain | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/PDgit12/knitbrain | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/PDgit12/knitbrain | release_recency=unknown

<!-- canonical_name: PDgit12/knitbrain; human_manual_source: deepwiki_human_wiki -->