# Skill Overview v2 报告升级方案

## 结论

建议把 `reports/skill-overview.html` 从“Skill 概览页”升级为“Skill 生成审计报告”。它不只说明新 Skill 是什么，还要解释它为什么这样设计、质量如何、风险在哪里、后续怎么升级。

本版方案在上一版基础上做了三点修正：

1. 在最前面新增“技能概述”模块，让用户先读懂这个 Skill 的一句话定位、核心价值、适用对象和交付结果，再看指标和图表。
2. 将“总览指标”后移为第二模块，避免用户一打开页面就看到抽象分数，却还不知道这个 Skill 是什么。
3. 将报告定位从“好看的说明页”收紧为“可解释、可评估、可复盘的生成报告”，所有图表和分数都必须能从本地 Skill 文件或已有 reports 推导出来。

## 目标

每次创建一个全新 Skill 后，同时生成一份双语 HTML 报告：

- 默认中文简体，右上角可以切换英文。
- 白色背景，沿用 Kami 的长文档排版节奏。
- 顶部吸顶导航，每个一级模块保持四个汉字。
- 模块足够细，既能让普通用户理解 Skill，也能让维护者评估质量。
- 包含图表、矩阵、数字化指标和后续升级建议。
- 静态 HTML 可离线打开，不依赖外部图表库或在线资源。

## 非目标

- 不把报告做成复杂 Web App。
- 不引入外部 JS 图表库。
- 不让报告替代 `SKILL.md`、`README.md`、`agents/interface.yaml` 等源文件。
- 不用模型主观打分冒充事实评分；所有分数必须可解释。
- 不在报告里暴露用户私密原文，除非这些内容已经存在于 Skill 包体内且适合展示。

## 报告模块

顶部导航建议保留 9 个一级模块，全部四字：

1. 技能概述
2. 总览指标
3. 能力画像
4. 原理结构
5. 契约边界
6. 质量评估
7. 风险治理
8. 包体资产
9. 迭代路线

### 1. 技能概述

作用：让用户先用一分钟读懂这个新 Skill。

内容：

- Skill 名称、显示名称、创建时间、成熟度。
- 一句话定位：这个 Skill 主要解决什么重复任务。
- 核心价值：它能帮用户少做什么、稳定什么、交付什么。
- 适用对象：个人使用、团队复用、平台迁移或库级能力。
- 交付结果：最终生成哪些文件和报告。
- 使用提醒：最应该打开的文件和下一步建议。

图表：

- “Skill 名片”信息块。
- “从输入到交付”的三段式流程条：输入材料 -> Skill 包体 -> 可复用能力。

数据来源：

- `SKILL.md` frontmatter
- `README.md`
- `manifest.json`
- `agents/interface.yaml`
- `reports/intent-context.json`
- `reports/skill-overview.json`

### 2. 总览指标

作用：用数字化方式快速判断这个 Skill 的当前状态。

内容：

- 完整度分数
- 触发清晰度分数
- 证据充分度分数
- 可维护性分数
- 可迁移性分数
- 上下文成本估算

图表：

- 5 维雷达图。
- 指标卡片。
- “当前成熟度”状态条。

评分原则：

- 分数必须来自结构化规则，而不是主观判断。
- 每个分数旁边必须显示 1 到 3 条原因。
- 缺失数据时显示“未生成 / 证据不足”，而不是编造结论。

### 3. 能力画像

作用：说明这个 Skill 在能力地图中的位置。

内容：

- 它属于创建型、评审型、执行型、研究型、写作型还是工具型 Skill。
- 使用模式：Scaffold / Production / Library。
- 触发强度：显式调用、自然语言匹配、上下文辅助。
- 复用范围：个人、团队、跨项目、跨平台。

图表：

- 能力定位矩阵：横轴为“执行确定性”，纵轴为“知识密度”。
- 使用对象标签组。

数据来源：

- `manifest.json`
- `agents/interface.yaml`
- `reports/prompt-quality-profile.json`
- `reports/system-model.json`

### 4. 原理结构

作用：解释这个 Skill 为什么这样组织。

内容：

- 意图澄清
- 边界路由
- 资产分层
- 证据回路
- 漂移观察
- 杠杆升级

图表：

- 闭环流程图。
- 分层架构图：入口层、参考层、脚本层、评估层、报告层。
- 如果存在 system model，展示反馈回路。

数据来源：

- `SKILL.md`
- `references/`
- `scripts/`
- `evals/`
- `reports/system-model.json`

### 5. 契约边界

作用：说明什么时候该触发，输入输出是什么，边界在哪里。

内容：

- 触发描述
- 应触发场景
- 不应触发场景
- 输入材料
- 输出结果
- 排除项
- 失败或缺资料时的处理方式

图表：

- 输入输出矩阵。
- should-trigger / should-not-trigger 对照表。
- 边界卡片：Owned / Adjacent / Excluded。

数据来源：

- `SKILL.md` frontmatter
- `reports/intent-dialogue.json`
- `reports/intent-confidence.json`
- `evals/`
- `agents/interface.yaml`

### 6. 质量评估

作用：评估这个 Skill 是否可靠、清晰、可维护。

内容：

- `description` 是否清楚。
- `SKILL.md` 是否过重。
- `references/` 是否承担了长指导。
- `scripts/` 是否承担了确定性逻辑。
- `evals/` 是否覆盖触发和质量。
- prompt quality、artifact design、system model 摘要。

图表：

- 条形评分图。
- 质量证据表。
- “强项 / 缺口 / 建议”三列分析。

数据来源：

- `reports/prompt-quality-profile.json`
- `reports/artifact-design-profile.json`
- `reports/system-model.json`
- `reports/output-risk-profile.json`
- 包体文件统计

### 7. 风险治理

作用：让用户看到这个 Skill 当前最可能失败在哪里。

内容：

- 误触发风险
- 输出漂移风险
- 证据不足风险
- 包体膨胀风险
- 跨平台迁移风险
- 人工判断边界

图表：

- 风险热力图：影响程度 x 发生概率。
- 风险清单：风险、信号、应对方式、证据来源。

数据来源：

- `reports/output-risk-profile.json`
- `reports/system-model.json`
- `reports/intent-confidence.json`
- `reports/portability_score.json`

### 8. 包体资产

作用：让 reviewer 快速确认这个 Skill 的文件结构是否合理。

内容：

- `SKILL.md`
- `README.md`
- `agents/interface.yaml`
- `manifest.json`
- `references/`
- `scripts/`
- `evals/`
- `reports/`

图表：

- 包体树状图。
- 文件类型分布 donut。
- 资产状态表：存在、缺失、可选、过重、建议补充。

数据来源：

- 本地文件系统扫描
- `manifest.json`
- `agents/interface.yaml`

### 9. 迭代路线

作用：把下一步升级方向讲清楚，避免无序扩张。

内容：

- Top 3 下一步升级方向。
- 每个方向的原因、动作、收益和暂缓项。
- 哪些内容现在不应该做。
- 哪些前置条件满足后再升级。

图表：

- 优先级矩阵：价值 x 成本。
- 迭代时间线。

数据来源：

- `reports/iteration-directions.json`
- `reports/system-model.json`
- `reports/intent-confidence.json`

## 指标设计

### completeness_score

衡量关键资产是否齐全。

参考规则：

- `SKILL.md` 存在：基础分
- `agents/interface.yaml` 存在：加分
- `README.md` 存在：加分
- `manifest.json` 存在：加分
- `references/`、`scripts/`、`evals/`、`reports/` 根据成熟度判断是否加分

### trigger_score

衡量触发是否清晰。

参考规则：

- frontmatter `description` 是否存在
- 是否说明任务、输入、输出和非目标
- 是否有 should-trigger / should-not-trigger 样例
- 是否有 route eval

### evidence_score

衡量报告证据是否充分。

参考规则：

- 是否有 intent 报告
- 是否有 artifact design 报告
- 是否有 prompt quality 报告
- 是否有 system model 报告
- 是否有 iteration directions 报告

### maintainability_score

衡量是否容易维护。

参考规则：

- `SKILL.md` 不过长
- 长指导进入 `references/`
- 确定性逻辑进入 `scripts/`
- 测试或 eval 可随包体迁移
- 报告和 manifest 保持同步

### portability_score

衡量跨环境复用能力。

参考规则：

- `agents/interface.yaml` 是否完整
- `manifest.json` 是否声明目标平台
- 是否有降级策略
- 是否避免硬编码私有路径

### context_cost

估算上下文成本。

参考规则：

- `SKILL.md` 字数
- references 文件数量和总字数
- reports 是否只在需要时读取
- 是否把长说明放到入口文件

## 数据模型建议

建议生成一个中间报告模型：

```text
reports/skill-overview.json
```

核心结构：

```json
{
  "skill_summary": {},
  "scorecard": {},
  "capability_profile": {},
  "principle_model": {},
  "contract_boundary": {},
  "quality_review": {},
  "risk_governance": {},
  "package_assets": {},
  "iteration_roadmap": {},
  "report_contract": {}
}
```

HTML 只负责渲染这个模型，不直接到处读取文件。

## 实现拆分

建议把现有报告渲染器拆成四层：

```text
Skill package
  -> report model builder
  -> metrics calculator
  -> chart renderer
  -> HTML renderer
```

建议文件：

- `scripts/render_skill_overview.py`：保留 CLI 入口和编排。
- `scripts/skill_report_model.py`：汇总 Skill 数据和各模块内容。
- `scripts/skill_report_metrics.py`：计算分数和原因。
- `scripts/skill_report_charts.py`：生成内联 SVG 图表。
- `tests/verify_skill_overview.py`：验收 HTML 主结构。
- `tests/verify_skill_report_metrics.py`：验收分数规则。
- `tests/verify_skill_report_charts.py`：验收 SVG 图表和无外部依赖。

## 排版约束

- 背景保持纯白。
- 使用 ink-blue 作为强调色。
- 采用 Kami 式长文档节奏：先结论，再证据，再解释。
- 图表必须有 caption，caption 要说洞察，不只说图表名称。
- 不使用外部字体、外部图片或外部图表库。
- 顶部导航吸顶。
- 一级菜单全部四字。
- 默认中文简体，英文作为切换视图。
- 每个模块要能独立扫描，不依赖读者从头读到尾。

## 生成完成后的用户文案

创建 Skill 后，CLI / 输出摘要建议显示：

```text
Skill 已创建完成。

建议先打开总结报告：
<absolute-path>/reports/skill-overview.html

这份报告默认使用中文简体，右上角可切换英文。它会展示这个 Skill 的概述、指标、原理、触发边界、输入输出、质量评估、风险治理、包体资产和后续升级路线。
```

## 验收标准

功能验收：

- 新建 Skill 后自动生成 `reports/skill-overview.html` 和 `reports/skill-overview.json`。
- HTML 默认中文简体。
- 右上角可以切换英文。
- 顶部导航吸顶，一级菜单均为四字。
- 页面至少包含 9 个一级模块。
- 页面至少包含 4 类 SVG 图表：雷达图、流程图、风险热力图、资产分布图。
- 每个数字分数都有原因说明。
- 缺失数据时显示证据不足，不编造结论。

测试验收：

- `python3 tests/verify_skill_overview.py`
- `python3 tests/verify_yao_cli.py`
- `python3 tests/verify_skill_report_metrics.py`
- `python3 tests/verify_skill_report_charts.py`
- `make ci-test`

视觉验收：

- 桌面端顶部导航不遮挡正文。
- 移动端导航可以换行或紧凑展示，不溢出。
- 图表在白底上清晰可读。
- 中文默认视图没有大段英文占位。
- 报告可直接用浏览器打开。

## 风险与应对

### 风险一：报告变得过重

应对：模块多，但数据来源要轻。没有证据的模块显示“暂无证据”，不要额外生成大量报告。

### 风险二：分数看起来像主观评价

应对：每个分数绑定规则和原因，报告展示“为什么得这个分”。

### 风险三：渲染器继续膨胀

应对：先拆 model、metrics、charts，再扩 HTML。不要继续把所有逻辑塞进 `render_skill_overview.py`。

### 风险四：英文切换质量不足

应对：默认中文必须完整；英文可以先作为解释层，不要求每个用户原文都翻译，但不能影响中文体验。

## 推荐实施顺序

1. 定义 v2 `skill-overview.json` 数据结构。
2. 新增 metrics 计算器，先产出 scorecard 和原因。
3. 新增 chart renderer，生成内联 SVG。
4. 重构 HTML 为 9 个一级模块。
5. 更新 `init_skill.py` 和 `yao.py` 的报告输出文案。
6. 生成示例 Skill 报告，做视觉检查。
7. 跑专项测试和完整 CI。

## 最小可行版本

如果希望先小步迭代，第一版只做：

- 新增“技能概述”模块。
- 新增“总览指标”模块。
- 新增 5 维雷达图。
- 新增分数原因说明。
- 保留现有其他模块结构。

这能最快提升报告的第一屏价值，同时为后续 9 模块完整版本铺好数据结构。