内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
<img alt="qmd-team-intent-kb — 受管团队记忆，用于 Claude Code。管控层。" src="assets/banner-light.svg" width="860">
</picture>
</p>
# qmd-team-intent-kb
**由 qmd 提供支持的 Claude Code 受管团队记忆平台。**
将 Claude Code 会话洞察转化为持久、可管控、适用于整个团队的记忆。qmd-team-intent-kb 捕获 AI 辅助开发过程中产生的机构知识，应用确定性管控策略，并通过 qmd 的本地全文索引使精选知识可搜索。
> **编译-然后-管控堆栈的一部分（Bob's Big Brain）** — INTKB 是 **管控** 层。上游，[intentional-cognition-os](https://github.com/jeremylongshore/intentional-cognition-os) （编译）发出它所消耗的卷；下游，[qmd](https://github.com/tobi/qmd) （检索）通过 `qmd://` 引用提供精选结果。→ [生态系统概述](https://github.com/intent-solutions-io/bobs-big-brain-umbrella)
## 定位
该项目具有明确的职责分工：
- **qmd** 是两个本地检索后端之一。它擅长一件事：快速、离线全文搜索。
- **qmd-team-intent-kb** 提供其周围的一切：编排、治理、生命周期管理、重复数据删除、分析、团队共享内存模型和混合检索 — qmd 二进制文件与本地进程内 FTS5（BM25）后端通过确定性互惠排名融合，然后由新鲜度和类别重新排名。服务保持无模型和确定性；语义（sqlite-vec）后端在检索评估门后延迟。
- **从第一天起就具备企业能力。** 租户隔离、审计跟踪和治理策略是架构要求，而不是事后才想到的。
## 架构论文
系统建立在严格的信息流中，带有刻意的信任边界：
1. **Claude Code 提出记忆。** 在会话期间，Claude Code 生成记忆候选者 — 见解、模式、决策和经验教训。这些是提议，而不是事实。
2. **确定性代码决定什么成为持久的团队记忆。** 策略引擎根据可配置的治理规则评估每个候选者。秘密过滤、重复数据删除评分、相关性评估和租户隔离都以编程方式强制执行。不涉及 LLM 判断的晋升决策。
3. **qmd 作为本地检索和索引引擎。** 精选的、批准的记忆被同步到本地 qmd 索引中，以便进行快速、离线搜索。边缘守护进程处理复制和冲突解决。
4. **规范的记忆控制平面拥有真相、生命周期、治理、重复数据删除和分析。** 控制平面 API 是记忆状态的单一真相来源。它管理整个生命周期：收件箱、审查、晋升、存档和替换。
5. **Git 是镜像、导出和分发层 — 不是规范数据库。** Git 导出器将精选知识发布到 git 仓库中，采用结构化的 Markdown + frontmatter 格式。Git 启用分发和版本控制，但它位于控制平面的下游。
6. **默认搜索目标是精选知识。** 当开发人员或 Claude Code 会话查询记忆时，默认搜索范围是精选的、策略批准的知识。这是一个刻意的设计约束。
7. **收件箱和存档内容不得污染默认搜索。** 收件箱中的原始候选者和存档中的已退休记忆被排除在默认检索之外。访问它们需要显式、刻意的查询。这可以防止未经审查或过时的内容污染团队知识。
## 單體庫結構
```
qmd-team-intent-kb/
├── apps/ # 可部署的应用
│ ├── api/ # 控制平面 REST API（Fastify）
│ ├── curator/ # 记忆晋升、重复数据删除、替换
│ ├── edge-daemon/ # 本地 qmd 同步守护进程
│ ├── git-exporter/ # Git 镜像/导出
│ ├── mcp-server/ # MCP 服务器 — 本地 + 团队大脑工具
│ └── reporting/ # 分析和生命周期仪表盘
├── packages/ # 共享库
│ ├── schema/ # 共享 Zod 模式和领域类型
│ ├── qmd-adapter/ # 融合 qmd + 原生 FTS5 检索、评估框架
│ ├── claude-runtime/ # Claude Code 会话捕获
│ ├── policy-engine/ # 记忆治理策略评估
│ ├── eval-surface/ # 治理决策 + 来源 CI 评估
│ ├── repo-resolver/ # 多仓库上下文解析
│ └── common/ # 共享实用程序
├── kb-export/ # Git 导出的精选知识输出
├── 000-docs/ # 项目文档和 RFC
├── examples/ # 使用示例和模板
├── scripts/ # 构建和维护脚本
├── tests/ # 集成测试（仓库根目录）
└── .github/ # CI/CD 工作流和模板
```
### 应用
| 软件包 | 目的 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/api` | 控制平面 REST API。记忆 CRUD、搜索委托、治理管理、身份验证。规范内存状态的中央权威机构。 |
| `apps/curator` | 记忆晋升引擎。根据策略验证候选者，重复数据删除，检测替换，分配生命周期状态。 |
| `apps/edge-daemon` | 本地同步守护进程，带有卷监视、整理周期、陈旧扫描、PID 锁定和优雅关闭。复制到本地 qmd 索引。 |
| `apps/git-exporter` | 将精选知识发布到 git 仓库，采用结构化的 Markdown + frontmatter。仅增量导出。 |
| `apps/mcp-server` | MCP 服务器，暴露大脑给 Claude Code。读取工具（`teamkb_search`、`teamkb_status`、`teamkb_neighbors`）始终注册；写入工具（`teamkb_propose`、`teamkb_import`、`teamkb_transition`、`teamkb_sync`）由管理员控制。以本地（进程内 qmd）或团队模式（通过 tailnet 将远程大脑代理到远程）运行。 |
| `apps/reporting` | 分析、生命周期报告、治理审计跟踪和团队知识仪表盘。 |
### 库
| 软件包 | 目的 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/schema` | 共享 Zod 模式和派生的 TypeScript 类型，用于整个领域模型。数据形状的单一事实来源。 |
| `packages/qmd-adapter` | 混合检索。融合 qmd 二进制文件与本地进程内 FTS5（BM25）后端，通过互惠排名融合（RRF，k=60），根据新鲜度和类别重新排名，并强制执行仅限精选的默认搜索。随附 Recall@10 / nDCG@10 分层评估框架，控制 CI 中的排名更改。 |
| `packages/claude-runtime` | 从 Claude Code 会话中捕获记忆提议。挂钩到会话事件，应用预策略秘密过滤。 |
| `packages/policy-engine` | 根据治理规则评估候选者。秘密检测、重复数据删除评分、相关性、租户隔离。全部确定性。随附推荐的全面覆盖策略和反休眠门，标记未覆盖的规则类型。 |
| `packages/eval-surface` | 确定性评估表面 — 治理决策精度/召回率（关闭漏过的秘密/PII）和来源完整性评估，在 CI 中作为命名门运行。 |
| `packages/store` | SQLite 持久层，通过 better-sqlite3 实现。WAL 模式，7 个仓库类，内存测试数据库助手。枚举成员资格后备 + `curated_memories` 上的 CHECK 约束；强制执行生命周期状态图。 |
| `packages/repo-resolver` | 多仓库上下文解析。确定项目/团队所有权并强制执行租户边界。 |
| `packages/common` | 共享实用程序：Result<T, E> 类型、SHA-256 内容哈希、路径安全验证、新鲜度评分和重新排名。 |
## 状态
**v0.7.0 — 具备生产就绪的平台，具备完整的 Intent Solutions 测试 SOP，在 CI 中强制执行。**
**v0.7.0 亮点：** 混合检索 — qmd 二进制文件与本地进程内 FTS5（BM25）后端通过互惠排名融合（RRF，k=60），根据新鲜度和类别重新排名，无模型 · 分层 Recall@10/nDCG@10 评估框架，控制 CI 中的排名更改 · MCP 工具表面（`teamkb_search` / `teamkb_status` / `teamkb_neighbors` 读取；`teamkb_propose` / `teamkb_transition` 写入，由管理员控制）支持本地和团队大脑模式 · 哈希链接的防篡改审计收据，带有外部链头锚。
所有核心子系统都已功能正常。1,900+ 个单元测试 + 基于 testcontainers 的 L4 集成套件（postgres 前向兼容）通过。每个 PR 的 CI（`ci.yml`）强制执行：格式 → 校验 → 类型检查 → 架构（依赖巡洋舰）→ 复杂度（CRAP）→ 策略工件哈希固定（`harness-pin --verify`）→ 单元测试 + 覆盖率（80% 行 / 70% 分支）→ 治理决策和来源完整性评估 → 检索棘轮（分层 Recall@10）→ L4 集成（testcontainers）。每周/每夜工作流（`security.yml`、`nightly.yml`）添加 gitleaks、Semgrep 和 npm 审计。策略工件通过 `scripts/harness-pin.sh` 进行哈希固定，因此测试 SOP 自我防御 AI 策略编辑。
亮点：
- **模式和领域模型** — Zod 模式、生命周期状态机、12 个枚举类型（第 1 阶段）
- **Claude 运行时捕获** — 会话捕获、本地 JSONL 卷、11 种模式秘密检测（第 2 阶段）
- **qmd 适配器** — CLI 包装器、仅限精选的默认搜索、租户隔离索引（第 3 阶段）
- **策略引擎** — 8 个确定性规则评估器，带有短路管道（第 4A 阶段）
- **SQLite 存储** — 5 个仓库、WAL 模式、内存测试支持（第 4B 阶段）
- **控制平面 API** — Fastify 5、候选人接收、内存生命周期、策略 CRUD、审计跟踪（第 4C 阶段）
- **整理引擎** — 卷接收、重复数据删除、Jaccard 替换检测、干运行模式（第 5 阶段）
- **Git 导出器** — 增量 Markdown 导出、YAML frontmatter、类别路由（第 6 阶段）
- **报告** — 生命周期分析、聚合器、格式化器（第 7 阶段）
- **安全强化** — API 中间件（速率限制器、身份验证、输入清理）、内容分类器、导出门控、路径安全（第 8 阶段）
- **仓库解析器** — 多仓库上下文解析，带有单体仓库检测、租户派生和缓存（第 9 阶段）
- **OpenAPI 文档** — 在 `/openapi.json` 和 `/docs` 处生成的 OpenAPI 3.1 规范和 Swagger UI（第 10 阶段）
- **供应链安全** — Cosign 无密钥签名 + SLSA 级别 3 容器镜像来源（第 10 阶段）
- **混合检索** — qmd 二进制文件与本地 FTS5（BM25）后端通过互惠排名融合（RRF，k=60），新鲜度和类别重新排名，以及分层 Recall@10/nDCG@10 评估框架，在 CI 中控制排名更改（语义 sqlite-vec 路径延迟在评估门后）
- **MCP 服务器** — 用于 Claude Code 的本地 + 团队大脑工具表面；读取工具始终注册，写入工具由管理员控制，团队模式通过 tailnet 将远程大脑代理到远程
- **治理强化** — 编写时枚举成员资格后备 + `curated_memories` 上的 CHECK 约束，生命周期状态图在写入路径上强制执行，敏感性在晋升时持久化并在读取时强制执行（精选搜索永远不会返回机密/受限记忆），导出类别映射失败关闭，卷 `schemaVersion` 验证，以及反休眠政策覆盖门
## 入门指南
### 先决条件
- Node.js 20+
- pnpm 9.15+
### 设置
```bash
# 克隆仓库
git clone https://github.com/jeremylongshore/qmd-team-intent-kb.git
cd qmd-team-intent-kb
# 安装依赖项
pnpm install
# 运行完整验证套件（格式、校验、类型检查、测试）
pnpm validate
```
### 可用脚本
| 脚本 | 描述 |
| ------------------- | --------------------------------------------- |
| `pnpm validate` | 运行所有检查：格式、校验、类型检查、测试 |
| `pnpm lint` | 运行 ESLint |
| `pnpm format:check` | 检查 Prettier 格式 |
| `pnpm typecheck` | 运行 TypeScript 编译器检查 |
| `pnpm test` | 运行 Vitest 测试套件 |
| `pnpm build` | 构建所有软件包（tsc -b 复合构建） |
| `pnpm clean` | 删除所有构建工件和 node_modules |
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解分支模型、提交约定、PR 期望和开发工作流程。
## 安全
参见 [SECURITY.md](./SECURITY.md)，了解漏洞报告、威胁模型和安全实践。
## 许可证
[Apache License 2.0](./LICENSE) -- Copyright 2026 Jeremy Longshore
连接信息
猜你喜欢
暂无推荐服务器