Team Knowledge Guardrails

约 1978 字大约 7 分钟

2026-06-08

Team knowledge 是 Aisee Plugin 的实验性能力，用于跨项目复用少量经审查的工程经验。当前适合本地试用和内部工作流验证，不建议作为公开稳定 contract 依赖。远程仓库同步、promote-batch 和本地 scaffold 已可用；PR 自动化和 MCP 服务仍未稳定。

定位

Team knowledge 提供 guardrail retrieval：在实现、review、verify 等阶段按需检索少量相关经验，提醒当前任务可能涉及的约定、风险或实践。

它不负责：

替代 OpenSpec specs、active changes 或 baseline；
保存完整项目 memory；
复制 docs/solutions/ 正文；
做通用知识问答；
作为向量库或缓存事实源。

OpenSpec/current change facts 的优先级始终高于 team knowledge。Team knowledge card 只能作为经审查的 guardrail，不能覆盖当前 change artifacts、source-map、tasks、contracts 或人工决策。

适用时机

Team knowledge 不需要在每个 change 中启用。它更适合用于风险面明确、历史经验可复用的场景：

时机	使用方式
实现前	查询与当前 schema、phase、surface、stack 相关的 guardrails，减少同类问题重复出现。
代码审查前	查询公开接口、路径读取、安全、CLI JSON、契约同步等容易漏检的规则。
verify 前	查询 evidence、accepted risk、archive guard 等归档前检查经验。
复盘后	将确实可跨项目复用的经验整理为 candidate，再进入 curate。

如果当前 change 范围很小、没有跨项目复用场景，或者已有 OpenSpec artifact 已经明确约束，则不需要额外查询 team knowledge。

仓库模型

Team knowledge 推荐使用独立仓库。可通过 aisee knowledge scaffold --dest <path> --json 生成初始骨架：

aisee-team-knowledge/
  AGENTS.md
  README.md
  knowledge/
    cards/
      frontend/
      backend/
      cli/
      openspec/
      security/
      testing/
    packs/
      web-app.yaml
      backend-service.yaml
      openspec.yaml
      aisee-plugin.yaml
    deprecated/
  schemas/
    knowledge-card.schema.json
    knowledge-pack.schema.json
  docs/
    authoring-guide.md
    review-policy.md
  indexes/
    lexical-index.json
    vector-index/

持久事实来源是 knowledge/cards/** 和 knowledge/packs/**。indexes/** 是可删除、可重建缓存，不能成为事实源。

Card 与 Pack

Team knowledge 由 card 和 pack 组成。card 记录一条可复用 guardrail；pack 选择某类项目或场景需要启用的 cards。

对象	作用	边界
Card	描述一个经审查的工程经验、适用条件、风险信号和使用限制。	不保存完整项目方案，不复制 solution 正文。
Pack	将一组 cards 组织成可 pin 的项目配置。	不代表强制规范，仍受当前项目 OpenSpec artifacts 约束。
Index	为查询构建 lexical 或可选 semantic cache。	可删除、可重建，不能成为事实源。

card 应能说明适用 phase、surface、stack、risk signals 和 evidence 来源。缺少边界条件的经验不适合提升为 team knowledge。

项目配置

业务项目通过 aisee/knowledge.yaml pin 需要的 packs：

repo: git@example.com:org/aisee-team-knowledge.git
path: .aisee/team-knowledge
ref: v0.1.0
packs:
  - web-app
retrieval:
  max_cards: 3
  include_project_candidates: true

V1 以本地 path 为主；repo 和 ref 记录来源与人工同步依据。当前 CLI 支持 aisee knowledge install --json 和 aisee knowledge update --json 同步本地 Git checkout；同步命令默认拒绝 dirty checkout，避免覆盖人工编辑的 card 或 pack。

当前可用能力

能力	说明
配置检查	通过 `aisee knowledge inspect`、`doctor`、`check` 检查本地配置、path 和 card / pack。
本地 scaffold	通过 `aisee knowledge scaffold --dest <path> --update-config --json` 创建 team knowledge 仓库骨架。
同步与索引	通过 `install`、`update`、`index` 同步或构建本地 cache。
查询	通过 `aisee knowledge query ... --json` 或 `--from-change <change>` 检索少量 guardrails。
Context pack 注入	通过 `aisee context pack --knowledge` 将少量 matches 注入实现上下文。
候选沉淀	通过 `aisee:reflect` 生成项目内 reusable knowledge candidates。
批量整理	通过 `aisee:knowledge-curate` 审查候选并生成 card drafts。
批量提升	通过 `aisee knowledge promote-batch` 将已审查 drafts 写入 team knowledge worktree。

读取模型

CLI 负责 retrieval 的边界控制：

读项目配置。
读 pack manifest。
读 pack 声明的 card frontmatter。
做 status、pack、schema、phase、surface、stack 硬过滤。
对通过过滤的候选做 lexical scoring。
按需做 semantic rerank。
执行 project-local / team knowledge 去重。
输出 top N guardrails。

Skill 和 AI 提示不得直接扫描 knowledge/cards/**/*.md。所有调用都应通过：

aisee knowledge query ...

默认输出最多 3 条 matches。Semantic matching 只能作用于硬过滤后的候选集，不能绕过 pack、status、phase、surface、stack 和 risk signals 做全库召回。

Match 的使用边界

查询结果应按 guardrail 处理，而不是按需求或任务处理：

输出	可做	不可做
匹配到的 card	作为实现、review 或 verify 的提醒。	覆盖当前 specs、contracts 或人工决策。
risk signal	提醒当前 change 可能需要额外检查。	自动扩大 change 范围。
suggested check	转成当前 change 的 review/test/evidence 项。	直接写入 baseline 或长期规范。
source/evidence	用于追溯 card 来源。	复制原项目上下文或敏感信息。

如果 match 与当前 OpenSpec change 冲突，应以当前 change 为准，并把冲突作为 review 或 follow-up 记录。

查询方式

查询前先检查配置：

aisee knowledge inspect --json
aisee knowledge doctor --json
aisee knowledge check --json

按阶段和场景查询：

aisee knowledge query --phase implementation --surface cli --query "public CLI JSON" --json

基于当前 change 查询：

aisee knowledge query --from-change <change> --for ce-work --json

在 context pack 中显式启用：

aisee context pack --change <change> --for ce-work --knowledge --json

沉淀流程

知识沉淀分三层：

aisee:reflect
  -> 生成项目内 reusable knowledge candidate
  -> aisee:knowledge-curate
  -> 批量去敏、泛化、去重、补边界并产出 card drafts
  -> 用户确认
  -> aisee knowledge promote-batch
  -> 写入本地 team knowledge worktree
  -> 人工 review diff

aisee knowledge promote-batch --curation <path> --team-path <path> --pack <id> --json 只负责把已审查 draft 写入本地 team knowledge worktree，并可幂等更新 pack。它不自动创建分支、commit、push、merge 或 PR。

写入 team knowledge repo、创建分支、提交、合并或 PR 前，需要用户再次明确授权。

Curate 要求

候选经验进入 card draft 前，应至少完成以下处理：

要求	说明
去敏	移除客户、用户、凭据、私有路径、内部 incident 细节和不可公开上下文。
泛化	把一次性项目经验改写为可跨项目复用的条件和约束。
去重	与已有 cards 比对，避免同一规则多次出现。
补边界	写清适用 phase、surface、stack、risk signals 和不适用场景。
保留证据	记录来源或 review 依据，但不复制完整 solution 正文。

未经 curate 的 reflect candidate 只能留在项目内候选区，不应直接写入 team knowledge repo。

与 Compound 的边界

ce-compound 继续记录具体工程问题和解决方案。Team knowledge card 可以引用 solution 作为 evidence，但不复制 solution 正文。

ce-compound-refresh 继续维护 docs/solutions/。Team knowledge refresh 是后续独立流程，不混入 Compound refresh。

不承担的职责

不自动把项目经验写入 team knowledge。
不自动创建分支、提交、合并或 PR。
不默认读取完整 card 正文。
不直接扫描 knowledge/cards/**/*.md 作为 AI 上下文。
不把 docs/solutions/、memory 或 reflect 文档整库迁移到其他项目。
不让索引、cache、向量检索或 AI 摘要成为事实源。

稳定性说明

外部 aisee-plugin 文档将该能力标记为实验性。公开稳定前仍需补齐更多真实 card packs、stale card refresh 工作流，以及可选的 semantic rerank 或 MCP 包装；这些能力不改变 Git + card / pack 的事实源模型。

文档站场景

对本站这类文档站 change，Team knowledge 通常不是必需步骤。只有当变更涉及长期写作规则、跨栏目导航约定、OpenSpec 文档基线或可复用的构建问题时，才适合在复盘后整理 candidate。

例如，单次修正文案不应进入 team knowledge；如果多次出现“文档栏目路由改名后旧入口未清理”的问题，可以在复盘后整理为一条 guardrail，要求后续文档站变更同时检查导航、侧边栏、正文内链、英文入口和 openspec/project-docs.md。

Team Knowledge Guardrails

关注 AISEE 公众号