openbkn-ai 报告生成
公约：../_shared/contract.md
做什么
汇总 pipeline 各阶段产物，生成结构化报告并归档。
输入
pipeline：当前流程类型artifacts：各阶段产物（建模清单、绑定结果、测试结果、推送结果等）network_dir：归档目录
报告类型
| 类型 | 触发时机 | 内容 |
|---|---|---|
| 阶段报告 | pipeline 中间节点 | 当前阶段摘要 + 下一步 |
| 最终报告 | pipeline 完成 | 全流程回顾 + 产物清单 + 质量评分 |
| 测试报告 | bkn-test 完成后 | 测试结果 + 覆盖率 + 通过率 |
| 诊断报告 | validate pipeline 完成 | 检查结果 + 问题清单 + 修复建议 |
最终报告结构
1. 网络概览：名称、领域、对象数、关系数
2. 建模摘要：路径（A/B/C）、收敛轮数
3. 绑定摘要：绑定率、覆盖率、风险项
4. 对象类详情：每个对象的属性列表、主键、映射状态（关键内容）
5. 测试摘要：通过率、关键失败项
6. 业务规则：规则数、锚定对象数
7. Q&A 验证：通过率、验证路径
8. 问题与修复：pipeline 执行中遇到的问题及解决方案
9. 产物清单：文件路径列表
诊断报告结构
当 report_type: diagnosis 时生成，输出文件为 DIAGNOSIS_REPORT.md / DIAGNOSIS_REPORT.html：
1. 网络概览：名称、kn_id、来源（本地/pulled）、检查时间
2. 检查摘要：各阶段状态总览（pass/fail/skipped）
3. 门禁检查详情：每条门禁结果 + 不达标项明细
4. 预检详情：关系映射/动作绑定/concept_group 检查结果
5. 静态检查详情：schema_review 结果（如有）
6. 质量评分：综合分 + 各维度分 + 降级说明
7. 问题清单：按严重度排序的问题列表（critical/warning/info）
8. 修复建议：每条建议 + 目标 skill + 预估工作量
9. 后续行动：推荐路由（update/feedback）+ 用户可选路径
诊断报告输入来源：
pipeline_state.yaml中的validation_result字段- 各阶段检查结果（gate_check、prepush_validation、static_check、quality_score）
diagnosis字段中的问题清单和修复建议
输出
1. Markdown 报告（必须）
- 文件：
{network_dir}/reports/REPORT.md - 用途：版本控制友好、方便 diff
- 内容：完整报告（上述 1–9 节）
2. HTML 报告（可选）
- 生成条件：
references/report-template.html模板存在时生成，不存在时跳过 - 模板：
references/report-template.html - 文件：
{network_dir}/reports/REPORT.html - 用途：可视化展示、直接浏览器打开
- 生成方式：读取模板，替换
{{placeholder}}占位符 - 占位符映射：
| 占位符 | 数据来源 |
|---|---|
{{network_name}} |
network.bkn → name |
{{domain}} |
network_context.domain |
{{timestamp}} |
当前时间 |
{{trace_id}} |
ARCHIVE_ID |
{{quality_score}} |
bkn-review 评分（未执行写 N/A） |
{{verdict_class}} |
score >= 80 → pass, >= 60 → warn, < 60 → fail |
{{score_rows}} |
各维度评分行 <tr><td>维度</td><td>分数</td><td>权重</td></tr> |
{{object_count}} |
对象类数量 |
{{relation_count}} |
关系类数量 |
{{binding_rate}} |
绑定率 |
{{mapping_coverage}} |
映射覆盖率 |
{{object_detail_rows}} |
对象类属性详情（每对象一节，含属性表格 + Keys） |
{{test_rows}} |
测试结果行 |
{{rule_count}} |
业务规则数 |
{{anchor_count}} |
锚定对象数 |
{{qa_pass_rate}} |
Q&A 通过率 |
{{artifact_list}} |
产物路径 <li> 列表 |
诊断报告 HTML 占位符映射
当生成诊断报告（report_type: diagnosis）时，使用以下占位符：
| 占位符 | 数据来源 |
|---|---|
{{network_name}} |
network.bkn → name 或平台查询结果 |
{{kn_id}} |
network.bkn → kn_id 或平台查询结果 |
{{source}} |
pipeline_state.yaml → source（local / pulled_from_platform） |
{{check_timestamp}} |
检查执行时间 |
{{trace_id}} |
ARCHIVE_ID |
{{gate_status}} |
gate_check.status（pass/fail） |
{{gate_rows}} |
门禁检查结果行 |
{{prepush_status}} |
prepush_validation.status（pass/fail） |
{{prepush_errors}} |
预检错误列表 |
{{static_check_status}} |
static_check.status（pass/fail/blocked/skipped） |
{{quality_score}} |
bkn-review 评分 |
{{verdict_class}} |
score >= 80 → pass, >= 60 → warn, < 60 → fail |
{{score_rows}} |
各维度评分行 |
{{problem_rows}} |
问题清单行（按严重度排序） |
{{fix_rows}} |
修复建议行 |
{{routing_primary}} |
diagnosis.routing_suggestion.primary |
{{routing_reason}} |
diagnosis.routing_suggestion.reason |
{{object_detail_rows}} 生成格式
每个对象类生成如下 HTML 片段：
<div class="object-section">
<h3>{{object_name}} <small class="meta">{{存储位置}}</small></h3>
<table class="properties-table">
<tr><th>Name</th><th>Display Name</th><th>Type</th><th>Mapped Field</th><th>Status</th></tr>
<!-- 每个属性一行 -->
<tr><td>{{property_name}}</td><td>{{display_name}}</td><td>{{type}}</td><td>{{mapped_field}}</td><td class="{{status_class}}">{{status}}</td></tr>
</table>
<p class="keys">Primary Key: {{primary_key}} | Display Key: {{display_key}}</p>
</div>
字段说明：
| 字段 | 来源 |
|---|---|
{{object_name}} |
object_types/*.bkn → frontmatter.name |
{{存储位置}} |
对象清单 → 存储位置（platform / local），local 对象标注灰色 |
{{property_name}} |
Data Properties 表格 → Name 列 |
{{display_name}} |
Data Properties 表格 → Display Name 列 |
{{type}} |
Data Properties 表格 → Type 列 |
{{mapped_field}} |
Data Properties 表格 → Mapped Field 列（无映射写 -） |
{{status}} |
bkn-map 输出 → 映射状态（mapped / waived / blocked），仅 platform 对象显示 |
{{status_class}} |
mapped → pass, waived → warn, blocked → fail |
{{primary_key}} |
object_types/*.bkn → Keys → Primary Keys |
{{display_key}} |
object_types/*.bkn → Keys → Display Key |
local 对象处理：存储位置为 local 的对象，Mapped Field 列显示 -，Status 列不显示（无数据视图绑定），整体标注灰色样式。
约束
- 报告不编造数据，数值必须来自实际产物
- 归档路径遵循
_shared/contract.md中的归档规则 - Markdown 报告为必须产物；HTML 报告在模板可用时生成，不可用时跳过并在 Markdown 报告末尾注明
- HTML 报告必须基于
references/report-template.html模板生成，不可自行编写 HTML