c0sogi/write-korean-meeting-minutes-hwpx

韩语会议记录 HWPX 编写

基于音频、视频或转录稿编写正式的韩语会议记录，并提供有效的 .hwpx 文件。如果没有转录稿，则首先使用 meetdown 生成 Markdown 转录稿。当前范围仅限 HWPX 生成，不执行 PDF 转换。

执行环境

• 使用文件系统和 Shell 执行权限。
• 使用 uv 和 uvx 执行 Python 命令和包。语音转录工具 meetdown==0.2.1 需要 Python 3.12 或更高版本。
• 语音转录需要网络连接以及 CLOVA Speech、OpenAI 或 Gemini 之一的认证信息。
• HWPX 编写使用内置模板和基于 Python 标准库的脚本。

必须遵守的原则

• 不要推测会议日期、地点、与会者、发言人真实姓名、负责人、截止日期、决定、数字和专有名词。
• meetdown 的 Created at 是转录稿的生成时间，而非会议时间。
• 诸如 A、B、[[SPEAKER_1]] 之类的标识不是真实姓名。只有在收到用户提供的发言人映射时才将其替换为真实姓名。
• 区分建议、顾虑、决定、后续行动和未决事项。
• 不要自动将多次出现的想法提升为决定。
• 如果初始意见与会议结束时的明确共识不同，则优先采用最后的共识或指示。
• 对于指向屏幕的发言（如“这里”、“这个图片”、“这边”），如果没有参考资料，则不要具体化。
• 不要将 API 密钥暴露在命令参数、日志、Markdown、JSON、HWPX 或最终回答中。
• 文档标题、章节标题和子章节标题使用粗体。
• 仅对重要的决定、结论和后续行动中的简短短语使用蓝色 #2F5597 和粗体进行强调。不要将大部分正文变成蓝色。

包含的资料

根据情况读取相应的资料。

• references/meetdown-guide.md：在没有转录稿或 meetdown 执行失败时读取。
• references/minutes-writing.md：在将转录内容重组为会议记录之前读取。
• references/hwpx-template.md：在创建、替换或修改 HWPX 模板时读取。
• references/installation.md：在提供安装位置或运维设置指导时读取。
• references/evaluation.md：在修改技能后设计回归测试时读取。
• assets/minutes.schema.json：minutes.json 结构的依据。
• assets/example-minutes.json：仅用作数据结构的示例，而非文本范本。
• assets/example-audit.json：证据链格式的示例。
• assets/meeting-minutes-template.hwpx：默认的会议记录模板。

使用的脚本

所有路径均基于技能根目录。

• scripts/transcribe.py：以非交互方式运行 meetdown 并保护秘密值。
• scripts/inspect_transcript.py：检查 meetdown Markdown 的结构和风险因素。
• scripts/validate_minutes.py：在生成 HWPX 之前验证 minutes.json。
• scripts/render_hwpx.py：将结构化内容应用到 HWPX 模板。
• scripts/validate_hwpx.py：检查 ZIP、XML、必要短语、粗体和蓝色强调。
• scripts/validate_skill.py：检查 Agent Skills 核心规则。
• scripts/self_test.py：在没有网络的情况下检查整个本地流程。

工作顺序

进度状态：

• 1. 分类输入文件和参考资料。
• 2. 如果没有转录稿，则使用 meetdown 进行转录。
• 3. 检查转录结构和质量。
• 4. 编写证据链。
• 5. 编写并验证 minutes.json。
• 6. 生成 HWPX。
• 7. 验证 HWPX 并修复错误。
• 8. 报告输出结果和待确认事项。

1. 输入资料分类

应用以下优先级。

1. 用户确认的会议元数据、发言人映射、术语标记和修正事项。
2. 实际会议中使用的议程表、演示资料、RFP、与会者名单等参考资料。
3. 包含时间戳和发言人的有效转录稿。
4. 没有时间戳的完整转录文本。
5. 仅在格式明确时使用文件名中的日期提示。

按输入类型处理：

• 如果有有效的转录 Markdown，则直接使用，不重新转录同一个录音。
• 如果只有音频/视频，则在编写会议记录前进行转录。
• 如果同时有转录稿和录音，优先使用转录稿。仅在转录稿为空、损坏或内容不符时才重新转录。
• 多个录音分别进行转录。仅当确认是同一会议连续录音时，才按文件顺序合并。
• 如果没有录音和转录稿，仅在会议笔记足够充分时编写审阅稿。如果证据不足，则不做编造。

2. 必要时进行转录

转录前先阅读 references/meetdown-guide.md。

韩语会议与 CLOVA Speech 的基本执行：

uv run scripts/transcribe.py "<录音文件>" \
  -o "<转录稿.md>" \
  --provider clova \
  --language ko-KR

仅当长文件的单次上传失败或提供者有明确限制时，才使用以下选项重试。

--chunk-duration 10m

默认压缩使用 smallest。仅在存在压缩导致转录质量下降的证据时，才使用 lossless 重试。对于多人参与的会议，除非有特殊原因，否则保留说话人分离。

转录后必须进行检查。

uv run scripts/inspect_transcript.py "<转录稿.md>" \
  -o "<转录稿.inspect.json>"

对于空文件、HTML 错误页面以及没有任何可用完整转录和时间戳段的文件，不编写会议记录。

3. 整理元数据

在确认的情况下记录以下值。

• 议程
• 日期时间
• 责任机构
• 地点
• 出席人数
• 主要议程
• 发言人映射
• 人物、机构、课题、产品、技术术语的确定标记

即使缺少非关键元数据，也不中断工作。编写审阅稿，在相应单元格中填写“需要确认”，并在 quality.missing_metadata 中记录。仅对需要完整最终版本且结果差异较大的信息做额外确认。

4. 编写证据链

在撰写最终文本之前，创建 minutes.audit.json。对于每个重要内容，使用以下格式。

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "规范化后的简短内容",
  "source": "转录稿或参考资料的 文件名",
  "speaker": "A 或确认后的真实姓名",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

分类标准：

• fact：会议中确认或解释的事实。
• proposal：建议、想法、选项。
• concern：反对意见、风险、制约因素。
• decision：明确同意、选择、确定、批准、指示。
• action：决定执行的具体任务。
• open_question：未得出结论的事项。

后续措施必须包含任务。仅在存在证据时填写负责人和截止日期。

5. 编写会议记录数据

遵循 references/minutes-writing.md 和 assets/minutes.schema.json。assets/example-minutes.json 仅参考其结构，不复制内容。

必须包含的文档结构：

• 会 议 记 录
• 顶部元数据表
• 会 议 内 容
  • 会议主旨
  • 2. 主要讨论
  • 2.1 之后的按主题讨论，通常 3 到 7 个
• 会 议 结 果
  • [摘要]
  • [后续措施]
  • 仅在必要时包含 [待确认事项]

使用简洁、中立的韩语商务文体。基本结尾词使用 -함、-하기로 함、-논의됨、-필요함、-판단됨。删除语气词、口吃、重复以及无关的闲聊，但保留作为决定依据的反对意见、技术限制、成本和日程安排。

需要以蓝色显示的短语，在 emphasis 数组中放入与正文完全相同的简短字符串。重要项目标记为 important: true。

验证：

uv run scripts/validate_minutes.py "<minutes.json>"

修复所有错误。同时检查缺失的元数据、正文中不存在的强调短语、过高的强调比例以及过长的段落警告。

6. 生成 HWPX

如果用户未提供兼容的模板，则使用默认模板。

uv run scripts/render_hwpx.py \
  --template assets/meeting-minutes-template.hwpx \
  --data "<minutes.json>" \
  --output "<最终会议记录.hwpx>"

渲染器保留表格结构和现有段落样式，将标题和子标题设为粗体，并使用 #2F5597 和粗体显示指定的核心短语。如果内容过长，不要过度缩小字体，应自然延续到下一页。

如果用户提供了差异很大的 HWPX 模板，不要盲目执行。首先根据 references/hwpx-template.md 确认表格单元格地址和正文段落结构，然后调整渲染器。

7. 验证 HWPX

uv run scripts/validate_hwpx.py "<最终会议记录.hwpx>" \
  --expect-data "<minutes.json>"

如果验证失败，则修改 JSON 或模板并重新生成。不交付以下状态的文件：

• mimetype 不是第一个 ZIP 条目或已压缩
• 必需的 XML 缺失或无法解析
• 缺少预期短语
• 文档标题或章节标题未加粗
• 请求了强调但缺少蓝色加粗样式
• 保留有未完成的占位符

如果可以访问 Hancom Office，直接打开文件检查表格边框、字体替换、页面流、截断的句子以及最后一段。如果没有实际打开，则不要说已经完成了视觉检查。

8. 输出与报告

根据情况生成以下内容：

• 如果进行了转录，则生成 transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• 如果存在未确定的项目，则生成 minutes.review.md
• 最终的 .hwpx

最终报告格式：

完成
- HWPX：<路径>
- 转录稿：<路径或使用了现有转录稿>
- 验证：通过 | 有警告
- 待确认：无 | 核心项目摘要

错误处理

• 如果没有认证信息，仅提示所需的环境变量名称，不要要求将秘密值输入到聊天中。
• 如果遇到容量或时间限制，使用 --chunk-duration 10m 重试。
• 如果转录可信度低，不要随意修正专有名词和数字，将其保留为待审查项目。
• 如果 HWPX 渲染失败，报告原因，不将损坏的文件作为输出。
• 如果被要求生成 PDF，说明这超出了当前技能范围，并告知需要单独的转换环境。

自检

安装技能后或修改脚本/模板后执行。

uv run scripts/self_test.py

此检查不调用语音识别 API，而是执行转录稿解析、JSON 验证、HWPX 生成和结构验证。