Proposal: Team Context Assets Health — Skills / Rule... | Tencent/teamai-cli

关联

Parent proposal: #407
对应 #407 中的 Team Context → Context Quality / Context Maintenance
评估结果进一步进入 Team Improvement → Validating → Verified / Rejected

背景

TeamAI 已经能够通过 Git 管理和分发团队的 Skills、Rules、CLAUDE.md，并收集部分 Skill 使用、Recall、Session 和人工干预数据。

当前 Dashboard 的 KB Health 主要关注知识覆盖率、Recall 次数与趋势、热门和沉默知识以及维护候选；现有 skill-health.ts 则主要按照使用次数和最近使用时间评分。这些指标可以说明某项资产是否被使用，但不能回答：

Skill 本身写得是否清晰、完整、可执行？
Skill 是否在正确的任务中触发，是否产生误触发？
使用 Skill 后，任务成功率是否真的提高？
Rule 或 CLAUDE.md 是否正确进入目标 Agent 上下文？
多个 Skill、Rule、CLAUDE.md 之间是否重复或冲突？
某项资产是否已经过期、无人维护或产生过高上下文成本？
某次改进上线后，是否真实改善了团队 AI 执行效果？

因此建议在 Dashboard 中增加 Team Context Assets Health，对 Skills、Rules、CLAUDE.md 做多维度健康检查，并与 Team Improvement 的验证闭环连接。

产品定位

Assets Health 是 Team Context 下的资产治理能力：

Team Context
├── Inventory
├── Asset Health
│   ├── Skills
│   ├── Rules
│   └── CLAUDE.md
├── Usage & Adoption
└── Maintenance

Team Improvement
├── Detected Issues
├── Evaluation Runs
└── Verified Improvements

第一阶段不依赖 #407 完整导航重构，可以沿用现有 KB Health 模式：

GET /assets-report
GET /api/assets-summary
GET /api/assets-health

后续再挂载到 Team Context → Asset Health。

核心原则

1. 区分三类健康信号

Artifact Quality
资产本身是否规范、清晰、完整、安全、可维护

Effective Coverage
资产是否完成分发、解析并进入目标 Agent 的有效上下文

Execution Effect
资产是否改善了真实任务的成功率、稳定性和效率

三者不能混为一个指标。

2. 低使用不等于低质量

低频但关键的发布、安全、故障处理 Skill 仍可能非常重要。“从未使用”应作为维护信号，而不是直接判定为低质量。

3. 缺少数据不按零分处理

没有 Eval 或运行数据时应显示 Unknown / Not evaluated，不能把“没有评估”显示成“效果为零”。

4. 默认检查必须低成本

静态扫描无需 API Key。
打开 Dashboard 不同步执行 LLM Eval。
AI 评估和真实 Agent Eval 必须异步、可缓存、可手动触发。
Eval 结果按资产 hash、模型、Agent 和 evaluator 版本保存。

统一健康维度

维度	Skills	Rules	CLAUDE.md
规范完整性	frontmatter、目录、引用、依赖	frontmatter、glob、格式	文件结构、注入标记、作用域
生效覆盖	是否分发、解析和发现	是否转换并被目标 Agent 激活	是否进入目标指令链
内容质量	清晰度、边界、输入输出、异常处理	指令是否明确、可执行	内容是否简洁、层级清晰
使用与效果	采用率、成功率、Skill Lift	曝光后执行信号	生效后的执行信号
一致性	重名、职责重叠	重复和冲突规则	多层指令重复或覆盖冲突
新鲜度	最近修改、最近使用	关联代码和路径是否仍存在	项目变化后是否仍准确
可维护性	owner、contributors、eval、体积	owner、适用范围、例外说明	owner、结构、上下文成本
安全性	危险脚本、越权、敏感信息	高风险或模糊指令	全局危险指令、秘密信息

Skill 专项质量评估

Skill 需要比 Rules 和 CLAUDE.md 更完整的效果评估。

1. 规范与结构

确定性检查：

SKILL.md 是否存在。
YAML frontmatter 是否有效。
name 和 description 是否存在。
name 是否符合 Agent Skills 规范并与目录一致。
body 是否为空。
引用的 scripts、references、assets 是否存在。
script shebang、权限和依赖是否合理。
是否包含失效绝对路径。
是否存在目录逃逸或危险符号链接。
SKILL.md 和 description 是否过长。
agents/openai.yaml 等目标元数据是否与 SKILL.md 一致。

2. Trigger Quality

每个 Skill 可以携带正反例：

cases:
  - id: release-project
    prompt: 发布当前 npm 项目的新版本
    shouldTrigger: true

  - id: explain-semver
    prompt: 解释一下 semver 是什么
    shouldTrigger: false

评估指标：

Precision：触发后有多少是正确触发。
Recall：应该触发的任务中有多少成功触发。
F1。
False Positive / False Negative。
与相邻或重名 Skill 的选择冲突。

测试集至少包含显式调用、隐式调用、带噪声的真实任务、相邻但不应触发的负例，以及与其他 Skill 同时存在时的选择测试。

3. Instruction Quality

通过静态规则和结构化 LLM rubric 评估：

Clarity：步骤是否清晰。
Completeness：关键前置条件和异常分支是否完整。
Trigger precision：适用和不适用场景是否明确。
Scope coverage：是否覆盖声明的能力范围。
Verifiability：是否定义完成条件。
Progressive disclosure：详细材料是否合理下沉到 references。
Degree of freedom：脆弱流程是否有足够约束。
Anti-patterns：空泛指令、重复常识、互相矛盾、无意义格式要求。

LLM 必须返回结构化 findings，并附带证据位置，不能只返回一个主观分数。

4. Functional Eval

Skill 可以选择性携带：

skills/release/
├── SKILL.md
├── scripts/
└── evals/
    └── evals.yaml

示例：

version: 1

cases:
  - id: release-new-version
    prompt: 发布当前 npm 项目的 patch 版本
    shouldTrigger: true

    assertions:
      commands:
        - npm test
        - npm run build
      files:
        exists:
          - CHANGELOG.md
      exitCode: 0

    rubric:
      - 版本号与 changelog 一致
      - 发布前完成测试
      - 未修改无关文件

    compareBaseline: true
    runs: 3

优先使用确定性 assertions：文件是否创建或修改、命令是否执行、测试或构建是否通过、输出是否符合 schema、是否留下无关文件、是否出现额外权限升级。无法确定性判断的部分再使用 LLM-as-Judge。

5. Skill Lift

高价值 Skill 使用相同任务运行两组实验：

Baseline：不提供目标 Skill
Treatment：提供目标 Skill

固定 Agent、Model、Workspace、Task、Sandbox、Grader 和其他可用 Skills，计算：

Skill Lift = Treatment Score - Baseline Score

Dashboard 示例：

模式	成功率	Tokens	耗时	工具调用
无 Skill	55%	18k	210s	32
有 Skill	82%	13k	160s	21
Lift	+27pp	-28%	-24%	-34%

Skill Lift 比原始使用次数更能说明 Skill 是否产生实际价值。

Rules 专项评估

Rules 不一定产生显式调用，因此主要检查：

Markdown/frontmatter 是否有效。
paths 或 glob 是否合法并能匹配实际仓库文件。
是否范围过大，导致无关任务加载。
是否转换成目标 Agent 支持的格式并完成配置激活。
是否与其他 Rule 重复或冲突。
是否包含不可验证、模糊或绝对化指令。
是否存在已经失效的技术栈、路径、命令。
是否缺少例外或安全替代方案。
默认加载产生的上下文成本。
Rule 变更前后的 intervention、correction、tool error 信号。

Rule 被加载只代表 exposure，不代表 Agent 已遵守，Dashboard 必须区分：

Distributed → Loadable → Exposed → Effect unknown/observed

CLAUDE.md 专项评估

CLAUDE.md 应作为正式 Context Asset 纳入 #407，而不是普通 Doc。

检查内容：

team repo 中的 claudemd namespace 是否有效。
目标 Agent 是否支持对应指令文件。
TeamAI managed block 是否正确注入。
多层 CLAUDE.md / AGENTS.md 的优先级关系。
是否存在重复、冲突或被下级覆盖的指令。
是否超过目标 Agent 的读取限制。
默认注入 token 成本。
是否包含过多本应下沉到 Skill/Rule 的流程。
是否包含过时路径、命令或项目结构。
是否存在 owner。
最近修改时间和关联仓库活跃度。

开源方案参考

建议吸收现有开源方案的方法和数据格式，但不将某个实验性框架硬编码为 TeamAI 核心依赖。

Agent Skills specification
NVIDIA SkillEvaluator
- Tier 1：Validation / Security
- Tier 2：Deduplication / Semantic overlap
- Tier 3：Live Agent Evaluation
Microsoft Waza
- Clarity、Completeness、Trigger precision、Scope coverage、Anti-patterns
Anthropic skill-creator
- Trigger eval、description optimization、grader、blind comparator
OpenAI: Testing Agent Skills Systematically with Evals
- 正反例 prompt、JSONL execution trace、确定性 grader、结构化 rubric
NVIDIA SkillEvaluator / ACES methodology
- paired baseline、Skill Lift、跨 Agent trajectory evaluation

实现上建议建立 TeamAI evaluator adapter：

interface AssetEvaluator {
  id: string;
  version: string;
  supportedTypes: ContextAssetType[];
  evaluate(input: EvaluationInput): Promise<EvaluationResult>;
}

可支持 TeamAI built-in static evaluator、LLM rubric evaluator、Trigger evaluator、Agent runtime evaluator、NVIDIA SkillEvaluator JSON importer，以及团队自定义 evaluator。

数据模型

type ContextAssetType = 'skill' | 'rule' | 'claudemd';

interface ContextAsset {
  id: string;
  type: ContextAssetType;
  name: string;
  path: string;
  namespace?: string;
  hash: string;
  owner?: string;
  contributors: string[];
  lastModifiedAt?: string;
}

interface HealthSnapshot {
  assetId: string;
  assetHash: string;
  generatedAt: string;
  status: 'healthy' | 'warning' | 'critical' | 'unknown';
  dimensions: {
    validity?: DimensionScore;
    reachability?: DimensionScore;
    contentQuality?: DimensionScore;
    effectiveness?: DimensionScore;
    consistency?: DimensionScore;
    freshness?: DimensionScore;
    maintainability?: DimensionScore;
    security?: DimensionScore;
  };
  findings: HealthFinding[];
  evidence: HealthEvidence[];
}

interface EvalRun {
  id: string;
  assetId: string;
  assetHash: string;
  evaluator: string;
  evaluatorVersion: string;
  agent?: string;
  model?: string;
  datasetVersion?: string;
  startedAt: string;
  completedAt?: string;
  status: 'queued' | 'running' | 'passed' | 'failed' | 'error';
  result?: {
    triggerPrecision?: number;
    triggerRecall?: number;
    triggerF1?: number;
    taskSuccessRate?: number;
    baselineScore?: number;
    treatmentScore?: number;
    skillLift?: number;
    tokenDeltaPct?: number;
    durationDeltaPct?: number;
  };
}

健康问题使用稳定 code：

interface HealthFinding {
  code: string;
  severity: 'critical' | 'warning' | 'info';
  message: string;
  path?: string;
  evidence?: string;
  suggestion?: string;
  fixable: boolean;
}

例如：

SKILL_INVALID_FRONTMATTER
SKILL_NAME_MISMATCH
SKILL_BROKEN_REFERENCE
SKILL_TRIGGER_FALSE_POSITIVE
SKILL_NEGATIVE_LIFT
RULE_GLOB_MATCHES_NOTHING
RULE_NOT_ACTIVATED
RULE_CONFLICT
CLAUDEMD_CONTEXT_TOO_LARGE
CLAUDEMD_INSTRUCTION_SHADOWED
ASSET_WITHOUT_OWNER

Dashboard 页面

Overview

顶部展示 Skills / Rules / CLAUDE.md 数量、Critical / Warning 数量、未评估数量、无 owner 数量、过期资产数量、平均上下文成本，以及最近一次扫描和 Eval 时间。

资产矩阵示例：

类型	规范	生效覆盖	内容质量	效果	一致性	新鲜度	维护性
Skills	92	84	78	71	90	82	68
Rules	88	73	80	Unknown	64	75	79
CLAUDE.md	100	91	76	Unknown	70	62	55

Assets 列表

支持按 asset type、namespace / role / tag、repository、健康状态、使用状态、评估状态、owner、冲突和目标 Agent 过滤。

Asset 详情

展示各维度分数和证据、findings、Git 历史、使用趋势、目标 Agent 生效状态、Trigger Eval、Functional Eval、Skill Lift、效率变化、关联 session、关联 improvement 和历史版本对比。

Issues 工作台

Critical  skill/release       SKILL.md frontmatter 无法解析
Critical  rule/security      在 Codex 目标中未生效
Warning   skill/code-review  Trigger false-positive rate 35%
Warning   claudemd/common    与 rule/git-policy 重复
Warning   skill/deploy       180 天未使用且没有 owner
Info      rule/typescript    paths glob 未匹配当前仓库

评分和状态

不建议只提供一个总分。每个 Skill 至少展示：

Artifact Quality   86/100
Task Success       82%
Skill Lift         +27pp
Confidence         Medium · 12 cases × 3 runs

Critical：无法解析、无法加载、严重安全问题、关键 Eval 失败。
Warning：内容质量、覆盖范围、新鲜度、低置信度等问题。
Healthy：没有明确问题且关键检查已完成。
Unknown：缺少对应评估数据。

如需总体分数：Critical 存在时总分最高 59；缺失维度不按零分计算；必须同时展示数据完整度和 confidence；不使用评分做成员或作者排行榜。

计算与缓存

快速检查

Dashboard 加载或仓库 revision 变化时执行目录和 frontmatter、引用完整性、Git 新鲜度、owner/contributors、角色和 tag 覆盖、重名和确定性冲突、目标格式和配置状态检查，无需 API Key。

AI 内容审计

仅在资产 hash 变化、用户手动触发或定期维护任务触发时运行。

Trigger / Functional Eval

异步运行，不阻塞 Dashboard 请求。缓存键为：

asset hash
+ eval dataset version
+ evaluator version
+ agent
+ model
+ environment

原始 trace 默认保留在本机；团队仓库只保存脱敏摘要和聚合结果。

API 建议

GET  /api/assets-summary
GET  /api/assets-health
GET  /api/assets/:assetId
GET  /api/assets/:assetId/history
GET  /api/assets/:assetId/evals
POST /api/assets/:assetId/evals
GET  /api/eval-runs/:runId

第一阶段也可以采用现有 standalone report 方式：

GET /assets-report

与 Team Improvement 的连接

发现健康问题后可以创建 Improvement：

id: imp-2026-asset-001

source:
  type: asset-health
  assetId: skill/release
  findingCodes:
    - SKILL_TRIGGER_FALSE_NEGATIVE

proposal:
  type: skill
  description: 补充发布场景触发描述

status: validating

baseline:
  triggerRecall: 0.62
  taskSuccessRate: 0.70

after:
  triggerRecall: 0.88
  taskSuccessRate: 0.84

状态沿用 #407：

Detected → Proposed → Applied → Validating → Verified / Rejected

隐私与安全

默认不上传原始 prompt 和 AI output。
团队数据只包含资产 ID、hash、指标和脱敏 findings。
原始 Eval trace 默认保留本机。
不展示竞争性成员排行榜。
未信任 Skill 的 script-backed Eval 必须在沙箱运行。
Dashboard 不直接执行任意仓库脚本。
AI findings 必须附证据，并明确标注 evaluator/model/version。
LLM 评分不能单独成为 Critical 阻断条件。

分阶段实现

Phase 1：静态资产健康与 Dashboard

新增 Skills / Rules / CLAUDE.md 统一 scanner。
新增确定性 validators。
聚合 Git、contributors、roles、tags、现有 Skill usage。
新增 /assets-report、/api/assets-summary、/api/assets-health。
Dashboard 增加 Assets Health 入口。
支持列表、详情、过滤和 issues 工作台。
无需 API Key。
不运行真实 Agent Eval。

Phase 2：内容质量与 Trigger Eval

新增结构化 LLM rubric。
支持 evals/evals.yaml。
支持正例、负例和相邻 Skill 干扰测试。
计算 Precision、Recall、F1。
Eval 异步执行并按 hash 缓存。
记录 effective manifest，区分已分发、可解析和已加载。
首批支持 Claude Code 和 Codex，再扩展其他 Agent。

Phase 3：Functional Eval 与 Skill Lift

沙箱运行真实 Agent 任务。
捕获标准化 execution trace。
确定性 assertions + LLM rubric。
paired baseline：with Skill / without Skill。
计算 Task Success、Skill Lift、token 和耗时变化。
关联 session、asset revision 和 improvement。
支持版本回归检测和定期评估。
评估结果进入 Verified / Rejected 闭环。

验收标准

Phase 1

Dashboard 能列出团队仓库中全部 Skills、Rules、CLAUDE.md。
能检测 malformed frontmatter、缺失文件、引用失效、重名、无 owner、过期和目标格式问题。
能展示 Skill 使用数据，但不把低使用直接判为低质量。
未评估指标显示 Unknown。
相同仓库 revision 的扫描结果可复用。
Dashboard 加载不依赖 API Key 或外部模型。
所有 findings 包含稳定 code、证据和建议动作。
CLAUDE.md 作为 Context Asset 纳入统计。
Assets Health 可以独立运行，并可后续并入 #407 Team Context。

完整版本

Skill 可声明 Trigger 和 Functional Eval。
支持正反例与多次运行。
支持至少 Claude Code 和 Codex。
能显示 Task Success 和 Skill Lift。
能将健康问题关联到 Improvement。
能比较资产变更前后的评估结果。
不上传原始 prompt/output，除非用户明确启用。

非目标

第一阶段不建立中心化实时服务。
第一阶段不在 Dashboard 请求中运行 LLM。
不根据单一分数自动删除或下线资产。
不使用健康评分评价个人贡献者。
不把 usage、exposure 或 recall 当作因果效果证据。
不要求所有 Skill 第一阶段就提供 Eval。
不承诺一次性支持所有 Agent 的运行时评估。

实现建议

建议优先实现 TeamAI 自有的统一数据模型和确定性检查，再通过 adapter 兼容外部 evaluator。

这样可以：

保持 Dashboard 数据和 UX 稳定。
避免绑定单个实验性项目。
复用 NVIDIA SkillEvaluator、Waza、Anthropic/OpenAI Eval 方法。
允许团队按业务场景增加自定义 evaluator。
将静态健康、运行效果和持续改进统一到 #407 的产品闭环中。

Proposal: Team Context Assets Health — Skills / Rules / CLAUDE.md 多维质量与效果评估

Description

关联

背景