背景

最近我在用 AI agent 开发一些审核、分析类 skill。它们能读文件、做判断、输出报告，但很快遇到一个工程化问题：

同一个 skill，在不同 AI agent 环境下运行，报告格式可能不一样；甚至在同一个环境里多跑几次，章节顺序、标题层级、表格列名也会发生变化。

这类问题在普通聊天里影响不大，但一旦报告要交付、归档、转发或用于管理决策，就会显得不专业，也很难复查。

我最初以为可以靠 prompt 约束，比如要求“请严格按照以下格式输出”。但实践下来发现，只靠 prompt 仍然不够稳定。于是我把这个问题抽象成一个工具：skill-report-template-hardener，专门用来审核和加固其他报告型 skill 的输出结构。

核心思路

这个工具的目标不是让报告文字更漂亮，而是让报告输出更稳定。

我把报告生成拆成两层：

1. 确定性脚本层
   负责数据读取、计算、排序、表格行、图表结构、模板替换和最终校验。

2. LLM 文案层
   只负责受限的文案槽位，比如执行摘要、关键发现、风险说明、建议文字。LLM 不直接写最终 HTML、Markdown、数字、表格结构或钻取数据。

这样做以后，报告结构由模板和脚本保证，AI 只在有限范围内提供表达能力。

工具能做什么

skill-report-template-hardener 目前提供三个命令。

1. audit：审核目标 skill

用于检查一个本地 skill 是否具备稳定报告输出能力。

示例：

python3 scripts/harden_report_skill.py audit ~/.codex/skills/<target-skill> --format markdown

它会识别：

• 是否输出 HTML 或 Markdown。
• 是否属于审核报告、分析报告、周报、交互式 HTML 看板。
• 是否有报告契约。
• 是否有模板资产。
• 是否有渲染脚本。
• 是否有验证测试。
• 是否定义了 LLM 与脚本的边界。

并给出成熟度判断：

• ad_hoc：基本靠模型自由输出。
• partial：有部分模板或脚本，但缺契约或验证。
• managed：模板、脚本、槽位和验证基本具备。
• hardened：契约、模板、脚本、测试、兜底行为和 LLM 边界都比较完整。

2. starter：生成报告契约和模板

当发现某个 skill 缺少稳定输出结构时，可以生成 starter 文件：

python3 scripts/harden_report_skill.py starter ~/.codex/skills/<target-skill> --formats html,markdown

它会生成类似下面的文件：

references/report_contract.md
templates/report_skeleton.html
templates/report_skeleton.md

report_contract.md 用来明确：

• 报告类型。
• 输出格式。
• 必备章节。
• 固定表格列。
• 结构化槽位。
• LLM 文案槽位。
• 数据不足时的兜底行为。
• 最终验证命令。

3. verify-output：验证最终报告

这是我觉得最关键的部分。因为报告是否稳定，最终要看产物，而不是只看 prompt 写得好不好。

示例：

python3 scripts/harden_report_skill.py verify-output \
  --html /path/to/report.html \
  --markdown /path/to/report.md \
  --required-section "总体结论" \
  --required-section "Checklist 明细" \
  --required-table-header "序号|检查项|判定|问题|建议" \
  --raw-html-text "<系统异常>" \
  --format json

它会检查：

• HTML/Markdown 文件是否存在。
• 是否有未替换的 {{PLACEHOLDER}}。
• 关键章节是否完整。
• 表格表头是否符合契约。
• Markdown 是否只有一个 H1。
• HTML 中是否出现未转义的原始输入文本。
• 必要时可检查转义后的文本是否存在。

这让报告型 skill 可以形成一个可重复执行的验收门槛。

为什么不用纯 prompt

纯 prompt 有两个问题。

第一，模型对“格式”的服从不是强约束。报告越长、信息越复杂，越容易出现小漂移。

第二，报告里的数字、表格、证据、排序和 HTML 安全转义不应该交给模型自由处理。它们更适合由脚本生成和验证。

所以我的经验是：

Prompt 适合约束表达风格，报告契约和渲染脚本适合约束结构。

一个典型加固流程

实际使用时，我一般按这个流程做：

1. 先对目标 skill 执行 audit。
2. 看它缺少契约、模板、脚本还是测试。
3. 用 starter 生成初始报告契约和骨架。
4. 让目标 skill 的渲染逻辑改成“脚本生成结构，LLM 填文案槽位”。
5. 渲染一个真实或 fixture 报告。
6. 用 verify-output 验证最终 HTML/Markdown。
7. 把验证命令写进目标 skill 的说明或测试里。

适用场景

这个工具适合：

• AI 审核报告。
• 故障复盘报告。
• 数据分析报告。
• 周报/月报。
• Markdown 状态报告。
• HTML 交互式看板。
• 需要归档、转发、复查的自动化报告。

不适合：

• 纯聊天型回答。
• 完全开放式创作。
• 不需要固定结构的短文本生成。

下载与使用

CSDN 资源下载：Skill Report Template Hardener：AI Agent 报告输出模板化加固工具

资源包里包含：

skill-report-template-hardener/
  SKILL.md
  README.md
  LICENSE
  agents/
  assets/templates/
  examples/
  references/
  scripts/harden_report_skill.py
  tests/test_harden_report_skill.py

安装到本地 Codex skills 目录：

mkdir -p ~/.codex/skills
cp -R skill-report-template-hardener ~/.codex/skills/

运行测试：

cd ~/.codex/skills/skill-report-template-hardener
python3 -m unittest tests/test_harden_report_skill.py

小结

AI agent 做报告类任务时，真正难的不是“写出一份报告”，而是“每次都稳定地产出同一种专业结构的报告”。

我的结论是：报告输出要工程化。把结构交给契约、模板和脚本，把表达交给 LLM，再用验证命令检查最终产物。

skill-report-template-hardener 就是围绕这个思路做的一个小工具。它不替代业务 skill 的专业判断，但可以显著提升报告输出的一致性、可验证性和可复用性。