feat: TeamAI Improve — Recall 子 Agent 的团队小模型与自动路由

提案：TeamAI Improve——Recall 子 Agent 的团队小模型与自动路由

状态：Issue 提案
范围：仅设计，本文档不改变现有用户行为

摘要

新增 TeamAI Improve：将团队后训练的小模型作为可选智能层，接入现有 teamai-recall 子 Agent。小模型不替代 Claude、Codex 等主编码模型，而是承担围绕团队知识库、边界明确且可评测的任务：

• 判断当前任务是否需要团队知识；
• 将任务改写为更有效的检索 Query；
• 对本地检索出的候选知识进行重排；
• 将低置信度或复杂场景交还主 Agent；
• 将召回结果反馈给后续数据集和改进版本。

第一阶段重点解决如何使用一个已经部署好的模型服务。运行时链路和评测闭环证明有效后，再增加训练编排。

所有生命周期操作收拢到一个命令族 teamai improve 下。数据集构建、训练、评测、部署和回滚不再分别增加顶层命令。

为什么叫 Improve

model 描述的是实现手段，improve 描述的是用户目标。TeamAI 的改进闭环不只包含模型训练，还可能包含知识质量、Query 规则、索引参数、路由策略和评测集的优化。

因此：

• teamai recall 继续是稳定的运行时入口；
• teamai improve 管理召回能力如何被评测和持续改进；
• 小模型是 Improve 的一个可插拔执行组件，而不是新的产品中心。

背景与动机

TeamAI 已经具备团队小模型所需的大部分数据与反馈基础：

• learnings/、docs/、rules/、skills/ 和 teamwiki/ 中的 Git 原生知识；
• 支持领域权重和知识图谱增强的本地 BM25 检索；
• 由主编码 Agent 调用的 teamai-recall 子 Agent；
• recall hit、miss、top score、vote 和知识健康指标；
• session 级别的干预、纠正、拒绝和工具使用信号。

目前缺少的是：把这些资产安全地转化为“模型辅助召回闭环”。通用小模型不了解团队最新代码和流程；如果把持续变化的事实直接训练进权重，又会产生知识过期、难以修订和难以删除等问题。因此 TeamAI 应明确区分：

• 知识：当前事实继续保存在 Git 中，运行时检索。
• 行为：Query 生成、相关性判断、工具路由和团队工作模式等稳定能力，可以由小模型学习。

最终形态是小模型 + TeamAI 知识库 + 主 Agent，不是让小模型替代主 Agent。

目标

1. 提高召回精度、减少无关召回，同时不让 recall 强依赖模型服务。
2. 让所有已支持 Recall 子 Agent 的 AI 工具都能使用团队小模型。
3. 模型不可用时确定性回退到现有本地检索。
4. 通过 Provider 边界支持本机、团队托管或远程推理服务。
5. 打通 recall 反馈、数据集、评测、发布和回滚闭环。
6. 保持 CLI 命令面简洁。

非目标

• 替换 Claude Code、Codex、Cursor 等封闭客户端使用的基础模型。
• 在 TeamAI CLI 内实现 CUDA 训练引擎、推理引擎、对象存储或完整模型仓库。
• 把频繁变化的源码、制度或文档直接训练进模型权重。
• 默认上传原始对话或源码。
• 让模型服务成为 teamai recall 的必需依赖。
• 未通过评测门禁就自动发布新模型。

用户体验

配置

团队管理员在 teamai.yaml 中配置可选的 Improve 运行时：

improve:
  recall:
    enabled: true
    provider: openai-compatible
    endpoint: ${TEAMAI_RECALL_MODEL_URL}
    model: team-recall-v3
    timeoutMs: 1500
    tasks: [gate, rewrite, rerank]
    fallback: lexical

密钥继续通过环境变量提供，禁止写入 Git。teamai pull 像其他团队 Harness 一样分发声明式配置。

improve 配置块可选且默认关闭。成员可以通过本地覆盖关闭它，避免某个项目使用不合适或不可达的服务。

收拢后的 CLI

只增加一个顶层命令：

# 默认展示生效配置、服务健康、当前版本、近期质量和改进建议
teamai improve

# 执行配置好的完整流水线：数据构建 -> 训练 -> 评测
teamai improve run [recipe]

# 选择版本、停用 Improve，或回退到上一版本
teamai improve use <version|previous|off>

teamai improve run 是一条流水线命令。数据集导出、训练提交和评测是 recipe 决定的内部阶段，不再暴露更多命令空间。高级用户通过参数恢复或查看任务：

teamai improve run --resume <run-id>
teamai improve --run <run-id>

MVP 接入已有模型服务时只需要 teamai improve 和 teamai improve use；run 放到后续训练阶段。普通成员仍然只使用现有 teamai recall，无需直接操作模型。

运行时架构

主编码 Agent
     |
     v
teamai-recall 子 Agent
     |
     v
teamai recall
     |
     +---- Improve 关闭 / 不健康 / 超时 ----+
     |                                     |
     v                                     v
小模型 gate + Query 改写                 现有关键词 Query
     |                                     |
     +------------------+------------------+
                        v
                BM25 + 图谱候选检索
                        |
                        v
                  可选小模型重排
                        |
                        v
               带来源的知识摘要返回主 Agent

模型永远不是事实来源。候选文档必须来自本地 Git 知识索引，Recall 子 Agent 返回真实文件路径和引用，由主 Agent 完成最终推理。

自动路由

路由策略必须边界明确、过程可观测：

1. Skip：gate 判断任务与团队知识无关，跳过召回。
2. Recall：任务相关，改写 Query 后检索本地候选。
3. Rerank：已有足够候选且模型健康，仅对这些候选重排。
4. 交还主 Agent：没有足够相关的证据、任务复杂或模型置信度低。
5. Fallback：超时、非法响应、Provider 失败或配置错误时，立即走现有关键词召回。

小模型不得决定是否允许破坏性工具调用；现有 Agent 和 Hook 的安全边界仍然优先。

第一阶段模型职责

MVP 只开放三个窄任务：

任务	输入	输出	适合小模型的原因
gate	脱敏后的任务摘要	skip 或 recall，附置信度	小型分类问题
rewrite	任务摘要与可选项目元数据	一个或多个检索 Query	行为稳定、容易评测
rerank	Query 与候选标题、标签、摘要	排序后的候选 ID	上下文有界，不能凭空发明文档

答案生成仍由主 Agent 负责。只有引用忠实度能够单独评测后，才考虑让小模型生成最终知识摘要。

模型选择原则

Improve 的目标是让团队可以低成本、高频率地训练和部署，不追求用小模型替代主 Agent。MVP 的底模选择遵循以下约束：

• 参数规模优先选择 0.5B–3B；只有离线评测证明能力不足时才考虑更大的模型。
• 优先选择中英文能力均衡、指令遵循稳定、能可靠输出 JSON 等结构化结果的开源模型。
• 模型许可证必须允许团队内部使用、后训练和部署；训练数据与基础模型许可证必须分别审查。
• 默认采用 LoRA 或 QLoRA，不做全参数训练；单次迭代应能在团队可获得的单机训练资源上完成。
• 推理侧优先支持量化部署，目标是开发机或共享单卡服务可以运行，而不是依赖大型推理集群。
• MVP 使用同一个模型完成 gate、rewrite、rerank，通过 task prompt 区分任务，避免维护多个模型。
• 不根据参数规模或公开榜单直接选型，最终以 TeamAI 自有 golden cases 的召回增益、延迟和资源占用决定。

建议 recipe 显式记录模型与资源预算：

name: recall-small-v1
baseModel: <approved-small-model>
parameterBudget: 3B
method: qlora
tasks: [gate, rewrite, rerank]
maxContextTokens: 4096
deployment:
  quantization: 4bit
  target: single-device

如果一个 0.5B–3B 模型无法同时做好三个任务，优先尝试改进样本、Prompt 和评测集；仍不能达标时，再按顺序考虑拆出轻量 reranker、扩大上下文或提升模型规模。

Provider 边界

现有 AI Client 负责探测和调用已安装的编码 Agent CLI。模型接入应增加独立 Provider 合约，而不是继续往当前 CLI 探测列表里加特殊分支。

interface ModelProvider {
  health(): Promise<ModelHealth>;
  infer(request: ModelRequest): Promise<ModelResponse>;
}

interface TrainingProvider {
  submit(request: TrainingRequest): Promise<TrainingRun>;
  status(runId: string): Promise<TrainingRun>;
}

interface ArtifactStore {
  put(manifest: ArtifactManifest): Promise<ArtifactRef>;
  resolve(ref: ArtifactRef): Promise<ArtifactManifest>;
}

MVP 只需要 ModelProvider，先实现 OpenAI-compatible HTTP Provider。训练和产物 Provider 后续增加。GPU 基础设施保持在 CLI 之外，同时兼容本地或远程部署。

训练与数据闭环

训练应学习“如何召回”，而不是记住整个知识库。

知识版本 + recall Query + 候选集 + 使用结果
                    |
                    v
              脱敏 / 去重 / 过滤
                    |
                    v
       版本化 gate、rewrite、rerank 样本
                    |
                    v
             通过 Provider 训练
                    |
                    v
             与基线做离线评测
                    |
                    v
              通过门禁后才能发布

数据来源

• 知识文档提供标题、标签、摘要、路径和版本哈希。
• 成功召回提供 Query 与候选之间的相关关系。
• recall miss 和低分结果提供 hard negative 与知识缺口信号。
• 用户明确纠正和拒绝的数据，在脱敏且 opt-in 后可形成偏好样本。
• 可以由更强模型生成带引用的合成 Query/文档对，但必须验证后才能进入训练集。

自动 recall vote 只是弱信号，不等同于真正的正样本，不能在缺少其他成功证据时直接当作 ground truth。

隐私与数据血缘

每条样本必须记录：

• 来源文档 ID 与 Git revision；
• recipe 和生成器版本；
• 人工、遥测衍生或合成等来源类型；
• 脱敏状态与数据策略；
• 内容哈希与数据集 split；
• 适用的许可证或团队授权。

默认排除原始 session 对话和源码。大型数据集与模型权重存放在外部 Artifact Store；Git 只保存 recipe、manifest、评测用例、指标和当前版本指针。

评测与发布

候选模型必须与现有纯关键词基线对比；已有在线模型时，还要与当前版本对比。

必需指标包括：

• gate precision / recall；
• 固定 top-k 下 Query 改写带来的检索增益；
• MRR、nDCG 等重排质量；
• 端到端 recall hit rate；
• 无关召回率；
• fallback 和超时率；
• 延迟分位数与推理成本；
• 后续线上阶段的用户干预或纠正率。

发布门禁写在 run recipe 中。teamai improve run 可以生成候选版本，但任一关键指标超过允许的退化阈值时不得激活。teamai improve use previous 提供单命令回滚。

存储结构

建议 Git 只跟踪以下内容：

improve/
  recipes/
    recall-default.yaml
  evals/
    recall-golden.jsonl
  registry/
    team-recall.yaml

Registry manifest 保存版本、基础模型标识、数据集哈希、recipe 哈希、评测摘要、Artifact URI、创建时间和发布状态，不保存权重和密钥。

本机缓存遵循 TeamAI 的 scope-aware 数据目录设计，不写入用户的业务仓库。

实施阶段

Phase 1：运行时 MVP

• 增加可选的 improve.recall 配置和本地覆盖。
• 增加 ModelProvider 与 OpenAI-compatible 实现。
• 将 gate、rewrite、rerank 接入 teamai recall。
• 保留现有本地索引返回的路径和引用。
• 增加严格超时、响应校验、熔断和关键词回退。
• 增加 teamai improve 和 teamai improve use。
• 默认不记录原始 Prompt，只记录延迟、路由决策、fallback 原因和召回结果。

Phase 2：评测与 Registry

• 增加版本化 golden cases 与基线对比。
• 增加 registry manifest 和发布阈值。
• 在知识健康报告中展示 Improve 贡献和 fallback 率。
• 支持 teamai improve use previous 回滚。

Phase 3：训练流水线

• 增加带数据血缘和脱敏校验的 opt-in dataset recipe。
• 增加 TrainingProvider 与 ArtifactStore 接口。
• 将 teamai improve run 实现为“数据集 -> 训练 -> 评测”的完整流水线。
• 默认 recipe 使用 0.5B–3B 底模和 LoRA/QLoRA，并记录训练资源与产物大小。
• 候选版本必须通过评测门禁才能被选择。

Phase 4：反馈驱动改进

• 从 miss 和纠正后的召回中生成 hard negative。
• 增加 canary 灰度，对比当前版本与候选版本。
• 只有在明确、干净的反馈数据足够时才引入偏好训练。

运行时 MVP 验收标准

• 不配置 Improve 时，teamai recall 的行为与当前完全一致。
• 配置健康模型后，Recall 子 Agent 可以使用 gate、rewrite、rerank，且外部调用方式不变。
• 模型超时或返回非法响应时，在配置的时间预算内回退到关键词召回。
• 返回结果必须对应真实的本地知识来源；拒绝模型生成的未知文档 ID。
• 团队配置中不包含明文密钥。
• 用户可以通过 teamai improve 查看生效配置和健康状态。
• 用户可以通过 teamai improve use 选择版本或关闭 Improve。
• 自动化测试覆盖关闭、健康、超时、非法响应、低置信度和 fallback 路径。
• 默认开启前，端到端评测必须证明检索质量优于纯关键词基线。
• 首个训练 recipe 可以在约定的单机资源预算内复现，且无需全参数训练。

待讨论问题

1. 第一个 Provider 只支持团队托管 Endpoint，还是同时管理本地模型进程？
2. 除当前自动 vote 外，哪些信号能够认定一次 recall 真正成功？
3. Improve 配置只允许团队级设置，还是 project scope 可以选择不同版本？
4. 超过多大的延迟预算后应直接跳过 rerank？
5. 第一阶段部署环境可以使用哪个 Artifact Store？

Start by reviewing the existing teamai recall entry point and teamai.yaml configuration, then compare the proposed improve/recipes, improve/evals, and improve/registry structure with the current repository. The design is complete when the Phase 1 runtime boundaries, fallback behavior, CLI commands, configuration, and automated acceptance tests are defined well enough to split implementation work.