team-knowledge — Claude Code Plugin
把团队的"知识纪律"封装成 Claude Code 行为契约：查询走三级渐进索引，沉淀走 archiver，维护走 lint/promote，全程不污染主上下文、不破坏知识库主分支。
新成员日常使用看 USAGE.md（装一次 / 每天用 / 偶尔用 / 典型一天）。
本 README 面向 plugin 维护者，讲设计原理、组件、不变量。
1. 这个 plugin 是什么
它是一个 Claude Code Plugin，安装后会让团队所有成员的 Claude Code 在跟代码打交道时，自动按统一规则与一个共享的"团队知识库"交互。
它不包含知识本身。知识存在另一个独立的 Git 仓库（默认 clone 到 ~/.team-knowledge/），由团队共同维护。Plugin 只规定 Claude 怎么读、怎么写、怎么提示这个知识库。
两个 repo 的边界：
| Plugin（本仓库） | 知识库（独立 repo） |
|---|
| 本质 | 行为/UX 契约 | 内容 + schema + 校验工具 |
| 谁维护 | 工具作者 | 业务团队 |
| 更新频率 | 偶尔 | 高频（每周新条目） |
| 跨团队 | 一份给所有团队 | 每团队一份 |
| 分发 | /plugin install | git clone |
| 离开 Claude 还能用吗 | 不能 | 能（lint/promote 可裸跑） |
2. 工作原理：三个运行时回路
Plugin 把 Claude 与知识库的交互建模成三个独立但互相喂数据的回路。
回路 A：查询（每次任务自动触发）
用户提问
│
▼
[skill: team-knowledge] 自动激活（基于 description 匹配）
│
▼
Step 1. 读 knowledge-catalog.md (Layer A，≤80 行)
│ 告诉 Claude 该看哪个分类
▼
Step 2. 读对应 catalog.md (Layer B，每条一行)
│ 按 tags + maturity 过滤
▼
Step 3. 只读真正相关的 TK-*.md / BK-*.md (Layer C)
│ 50-200 行/条
▼
（如需大范围搜索）
│
▼
[subagent: knowledge-explorer] 多角度扫描，只回传摘要
│
▼
Claude 给出答案 + knowledgeReferences 字段
核心约束：永远不跳级，永远不在主上下文里 grep 整个知识库。Layer A 只 80 行 token 几乎为零；Layer C 按需懒读；大范围检索委托给 haiku 模型的 subagent，结果以摘要形式回传，避免污染主上下文。
回路 B：沉淀（任务完成后由用户触发）
任务完成，用户敲 /archive
│
▼
[command: /archive] → 调用 [subagent: archiver]
│
▼
archiver 扫描会话产物，按 5 种知识类型 (decision/pitfall/guideline/model/process)
判断有没有"对未来项目有价值"的内容
│
├── 有 → 生成 draft 条目 → 写到 contributions/pending/
│ 主对话里输出 review checklist + 提 PR 命令
│
└── 没有 → 输出"本次会话未发现可沉淀内容"，不硬凑
（archiver 永远不直接 commit 主分支）
核心约束：新条目永远 maturity: draft；contributions/pending/ 是唯一允许的写入目标；进主库必须经过 maintainer 的 PR review。这道闸防止 AI 自动产出污染共享数据。
回路 C：维护（maintainer 周期性触发）
maintainer 敲 /knowledge-lint
│
▼
[command: /knowledge-lint] →
cd $TEAM_KNOWLEDGE_REPO
python3 scripts/lint.py ← schema 一致性、孤儿、衰减、重复
python3 scripts/promote.py ← 评估 draft→verified→proven 候选
│
▼
Claude 解读输出，给 maintainer 优先级建议
（脚本本体在知识库 repo 内，不在 plugin 内 —— 因为它们 schema-bound）
回路 C 还有一个隐式分支：每次新会话启动时，hook 会自动 git pull 知识库，让团队成员的本地副本始终最新。
3. 组件详解
Plugin 的目录布局严格遵循 Claude Code Plugin 规范。每个文件都映射到 Claude Code 的一个原语（primitive）。
team-knowledge-plugin/
├── .claude-plugin/
│ └── plugin.json ← 元数据（name/version/description）
├── skills/team-knowledge/
│ └── SKILL.md ← 查询协议（auto-invoked）
├── agents/
│ ├── archiver.md ← 沉淀流程（sonnet）
│ └── knowledge-explorer.md ← 大范围检索（haiku）
├── commands/
│ ├── archive.md ← /archive
│ ├── knowledge-add.md ← /knowledge-add
│ ├── knowledge-lint.md ← /knowledge-lint
│ └── import-knowledge.md ← /import-knowledge
├── hooks/
│ └── hooks.json ← SessionStart + Stop
├── templates/
│ └── business-project-pr-template.md ← 业务项目 PR 模板（手动复制）
├── bootstrap.sh ← 一行命令装好整个环境
└── CLAUDE.md.template ← 业务项目接入片段
3.1 Skill：skills/team-knowledge/SKILL.md
类型：Skill（Claude 根据 description 自动激活）
触发：用户提问涉及架构决策、技术选型、调试已知问题、业务规则、领域模型等场景
职责：把 3 级渐进式查询协议作为系统级指令注入 Claude 的对话
包含的硬约束：
- Step 1 永远先读
knowledge-catalog.md，零成本
- Step 2 用 tags + maturity 过滤，优先
proven > verified > draft
- Step 3 只读真正相关的条目，不确定时读到第一个
## 二级标题就停
- Step 4（可选）沿
source_references 追溯原始 PR
- 大范围查询必须委托
@knowledge-explorer
- 任何使用知识的产出必须附
knowledgeReferences JSON 字段（驱动 last_referenced 更新和后续 promotion）
不要做的事（写在 SKILL 里，是运行时 gate）：
- 不要把整个 catalog.md 全读完（catalog 是给 lint 用的）
- 不要直接读 entry 文件（必须经 catalog 过滤）
- 不要主动写知识条目（用
/archive）
- 不要在主上下文里 grep 整个知识库（用
@knowledge-explorer）
- 不要 commit 到主分支（
contributions/pending/ 是唯一允许的写入位置）
3.2 Subagent：agents/archiver.md
类型：Subagent（model: sonnet，工具: Read/Write/Bash/Grep/Glob）
触发：/archive 命令调用，或 archiver 的 description 匹配（feature 交付、bug 修复、研究完成）
职责：从已结束的会话中提取可复用知识，生成 draft 条目到 contributions/pending/
工作流程：
- 扫描会话产物（用户需求、Claude 输出、用户反馈/修正）
- 按 5 种 MECE 知识类型识别可沉淀内容
- 去重检查（
grep ~/.team-knowledge/ 确认不重复）
- 判断归属：Layer 1（tech-wiki）/ Layer 2（biz-wiki/{domain}）/ Layer 3（项目内，不入团队库）
- 按类型模板生成 frontmatter + body，写入
contributions/pending/
- 在主对话输出条目摘要 + review checklist + 提 PR 的命令清单
核心纪律：宁缺毋滥；初始 maturity 一律 draft；不直接 commit 主分支。如果本次会话没有可沉淀内容，明确返回"未发现"而不硬凑。
3.3 Subagent：agents/knowledge-explorer.md
类型：Subagent（model: haiku，工具: Read/Grep/Glob）
触发：主 Claude 在需要做大范围知识检索时主动调用
职责：在知识库里多角度搜索，只回传 Top 3-5 条结构化摘要给主 Claude
为什么单独跑一个 subagent：
- 大范围 grep 可能命中几十个文件，全文返给主 Claude 会爆 token
- haiku 模型成本低，专门做"读 + 总结"
- 主 Claude 拿到的是经过排序和摘要的 Top 候选，不是原始 grep 结果
搜索策略（必须用至少 3 种）：
- grep 标题行
- grep tags 字段
- grep 全文找隐性提及
排序优先级：标题命中 > tags 命中 > 其他 frontmatter 命中 > 正文命中。pitfall 类型 + bug/error/故障 关键词时优先返回。
