Bkn Report

报告生成

公约：../_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 字段
• 各阶段检查结果（gatecheck、prepushvalidation、staticcheck、qualityscore）
• 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}} | networkcontext.domain | | {{timestamp}} | 当前时间 | | {{trace_id}} | ARCHIVEID | | {{quality_score}} | bkn-review 评分（未执行写 N/A） | | {{verdict_class}} | score >= 80 → pass, >= 60 → warn, 维度分数权重 | | {{objectcount}} | 对象类数量 | | {{relationcount}} | 关系类数量 | | {{bindingrate}} | 绑定率 | | {{mappingcoverage}} | 映射覆盖率 | | {{objectdetailrows}} | 对象类属性详情（每对象一节，含属性表格 + Keys） | | {{testrows}} | 测试结果行 | | {{rulecount}} | 业务规则数 | | {{anchorcount}} | 锚定对象数 | | {{qapassrate}} | Q&A 通过率 | | {{artifactlist}} | 产物路径 ` 列表 |

诊断报告 HTML 占位符映射

当生成诊断报告（report_type: diagnosis）时，使用以下占位符：

| 占位符 | 数据来源 | |--------|---------| | {{network_name}} | network.bkn → name 或平台查询结果 | | {{kn_id}} | network.bkn → knid 或平台查询结果 | | {{source}} | pipelinestate.yaml → source（local / pulledfromplatform） | | {{check_timestamp}} | 检查执行时间 | | {{trace_id}} | ARCHIVEID | | {{gate_status}} | gatecheck.status（pass/fail） | | {{gate_rows}} | 门禁检查结果行 | | {{prepush_status}} | prepushvalidation.status（pass/fail） | | {{prepush_errors}} | 预检错误列表 | | {{static_check_status}} | staticcheck.status（pass/fail/blocked/skipped） | | {{quality_score}} | bkn-review 评分 | | {{verdict_class}} | score >= 80 → pass, >= 60 → warn, {{object_name}} {{存储位置}}

NameDisplay NameTypeMapped FieldStatus

{{propertyname}}{{displayname}}{{type}}{{mapped_field}}{{status}}

Primary Key: {{primarykey}} | Display Key: {{displaykey}}

字段说明：

| 字段 | 来源 |
|------|------|
| `{{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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kweaver-ai](https://github.com/kweaver-ai)
- **Source:** [kweaver-ai/kweaver-dip](https://github.com/kweaver-ai/kweaver-dip)
- **License:** Apache-2.0
- **Homepage:** https://kweaver.ai

Install and usage instructions live in the source repository linked above.