Report Creator

核心能力

kai-report-creator 是一款专注于高质量商业与研究报告生成的专业工具，其最大特色在于「计划-生成-审阅」的三阶段工作流。用户可通过 --plan 先构建结构化中间表示（IR），确认内容框架后再渲染为HTML；或直接通过 --generate 快速产出成品。

工具内置 corporate-blue、minimal、dark-tech、newspaper、data-story 等8种专业主题，能根据内容语义自动匹配（如周报自动选 regular-lumen，技术架构自动选 dark-tech）。所有输出均为零依赖的单文件HTML，内置响应式布局、打印优化、TOC导航、导出功能（PNG/打印/IM分享），无需任何外部服务器即可交付使用。

显著优点

1. 数据真实可信：严格遵循「用户提供数据，AI提供结构」原则，缺失数据处明确标注 [数据待填写]，杜绝AI幻觉
2. 专业可视化：统一采用 ECharts 图表引擎，支持 KPI 卡片、时间轴、对比表格、流程图等多种组件
3. 智能降级保护：当组件渲染失败时自动降级（如 chart → table，timeline → list），确保报告可用性
4. 完整性校验：内置多层级验证机制，包括 IR 语法检查、HTML 结构守卫、L2 Shell 检查，防止残缺输出
5. 多语言原生支持：中英文内容同等处理，自动识别语言并适配日期格式、标签文本

局限性与注意事项

• 非实时协作：单次生成模式，不支持多人实时编辑
• 图表复杂度上限：ECharts 配置需遵循预定义规则，高度定制图表需走自定义模板
• 数据隐私：生成过程在本地/封闭环境完成，但若使用 --bundle 内联CDN资源需注意网络依赖
• 图像导出依赖 Playwright：--export-image 需额外安装 Python 依赖，不可用时会静默跳过

适合人群

• 企业管理者：快速生成周报/月报、KPI仪表盘、季度业务回顾
• 咨询分析师：研究报告、竞品对比、白皮书的标准化产出
• 产品经理：项目进展汇报、数据驱动的产品决策文档
• 技术团队：系统架构文档、性能报告、API 文档可视化

常规风险提示

| 场景 | 风险 | 缓解措施 |

|------|------|---------|

| 数据敏感 | 生成文件包含原始数据 | 使用本地路径，避免上传至公共服务器 |

| 主题自动匹配偏差 | 语义关键词误判导致风格不符 | 显式指定 `--theme` 参数覆盖 |

| 复杂表格渲染 | 超宽表格移动端显示异常 | 优先使用横向滚动或拆分多个表格 |

| 历史版本追溯 | 单文件HTML不利于版本对比 | 保留 `.report.md` IR 源文件作为版本基准 |

使用建议

高价值报告务必使用 --plan 先生成 IR 文件，经人工确认关键结论（must_include、must_avoid）后再执行 --generate。对于周期性报告（周报/月报），建议建立模板化 .report.md 以提升复用效率。

核心用法

kai-report-creator 是一款面向 Claude Code 环境的智能报告生成技能，采用「中间表示（IR）+ 渲染引擎」的架构设计。用户可通过 /report 命令配合多种 flag 灵活调用：

• `--plan`：先生成 .report.md IR 文件，人工确认结构后再渲染，适合复杂或高 stakes 报告
• `--generate`：将 IR 文件渲染为自包含 HTML，支持从对话上下文中自动提取 IR
• `--review`：一键优化既有 HTML 报告的质量与可读性
• `--themes`：预览 8 种内置主题（corporate-blue、dark-tech、data-story 等）
• `--bundle`：将 CDN 资源内联，实现完全离线可用
• `--export-image`：调用 Playwright 生成 PNG 截图（桌面/移动端/IM 分享三种尺寸）

报告生成分三阶段执行：语言/主题自动检测 → 守卫验证与降级处理 → 组件渲染与 HTML 组装。IR 格式采用 YAML frontmatter + Markdown + 组件围栏（:::kpi、:::chart 等）的混合结构，既保证机器可读，又便于人工审阅。

显著优点

架构设计先进：SKILL.md 作为薄路由层，详细规则下沉至 references/ 目录，实现「渐进式披露」——简单场景快速执行，复杂场景按需加载深度文档。这种设计有效控制了上下文窗口占用，同时保证了功能完备性。

零依赖自包含：生成的 HTML 为单文件，内置 CSS/JS，无需后端服务。--bundle 模式可将 ECharts、Highlight.js 等 CDN 资源内联，满足离线、内网等严格网络环境需求。

专业视觉体系：8 种主题覆盖商务（corporate-blue）、技术（dark-tech）、数据叙事（data-story）、新闻（newspaper）等场景，自动适配中文/英文排版，支持 KPI、时间线、图表、表格等丰富组件。

数据安全机制：严格执行「用户提供数据，AI 提供结构」原则，缺失数据标记为 [数据待填写]，禁止 LLM 杜撰事实；IR 哈希校验确保渲染过程可追溯。

企业级合规：通过 GDPR/CCPA 隐私合规审计，不收集敏感用户数据，符合数据最小化原则。

潜在缺点与局限性

学习曲线存在：IR 中间表示、组件围栏语法、主题覆盖规则等概念对非技术用户有一定门槛，需要阅读 references/ 文档才能充分发挥高级功能。

图表引擎单一：所有图表强制使用 ECharts，虽功能强大但对于特定可视化需求（如 Observable Plot、D3 定制）缺乏灵活性。

Playwright 依赖外部化：图片导出功能依赖 Playwright 和 Chromium 浏览器，需额外安装且体积较大（约 100-200MB），在资源受限环境可能无法使用。

CDN 默认依赖：非 --bundle 模式下需联网加载 jsDelivr 资源，在严格防火墙环境可能受阻。

模板定制复杂：自定义 HTML 模板需理解 shell 模板机制、L2 守卫检查点（如 data-template、id 属性等），调试成本较高。

适合的目标群体

• 数据分析师与 BI 从业者：需要快速将原始数据转化为可分享的专业报告
• 产品经理与项目经理：周报/季报、项目进展汇报、竞品分析等场景
• 科研人员：研究报告、白皮书、调查分析等需要结构化呈现的文档
• 企业数字化团队：需要统一报告视觉标准、建立可复用报告模板的组织
• Claude Code 高级用户：愿意投入时间理解 IR 机制以换取生成质量与可控性的用户

使用风险

性能风险：大型数据集渲染时 ECharts 可能产生性能瓶颈，建议在 IR 阶段对数据进行预聚合；Playwright 截图大尺寸报告时内存占用较高。

依赖可用性风险：--bundle 模式会增加 HTML 文件体积（通常增加 500KB-2MB）；Playwright 下载源（Microsoft CDN）在部分区域可能访问受限。

版本兼容性风险：Skill 与 Claude Code 环境深度集成，版本更新（当前 1.21.2）可能引入 breaking changes，建议关注 GitHub releases 说明。

渲染一致性风险：不同浏览器对 CSS 动画、字体加载的处理存在差异，建议在目标受众常用环境中测试预览。

数据泄露风险（低）：虽然 Skill 本身符合隐私合规，但用户若在 IR 或生成的 HTML 中嵌入敏感数据，需自行承担数据安全责任，避免将含敏感信息的报告上传至公共 CDN 或代码仓库。