c0sogi/meeting-minutes

韩语会议纪要 HWPX 编写

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

运行环境

• 使用文件系统和 Shell 执行权限。
• Python 命令和包的运行使用 uv 和 uvx。语音转录工具 meetdown==0.2.1 需要 Python 3.12 或更高版本。
• 语音转录需要网络连接以及 CLOVA Speech、OpenAI 或 Gemini 之一的认证信息。
• 认证信息通过环境变量提供。如果作为 Claude Code 插件安装，也可以在插件设置中输入；如果两者都有，优先使用插件设置。
• 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

如果可用工具有 transcribe_meeting，则调用此工具而不是上面的命令。在插件设置中输入的认证信息仅传递给此工具。input_path 和 output_path 使用绝对路径指定，以下选项通过等效参数（例如 chunk_duration）传递。

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

--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 缺失或无法解析
• 期望的短语缺失
• 文档标题或章节标题未加粗
• 请求了强调但没有蓝色粗体样式
• 存在未完成的占位符

验证通过检查文件的 ZIP、XML、内容、格式设置即可完成。不执行运行 Hancell Office、Computer Use 或通过屏幕截图进行屏幕检查。

8. 产物与报告

根据情况创建以下内容。

• 如果需要转录，创建 transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• 如果有未确定事项，创建 minutes.review.md
• 最终的 .hwpx

最终报告格式：

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

失败处理

• 如果没有认证信息，则告知所需的环境变量名称，在 Claude Code 中同时告知可以通过 /plugin 的 hwpx 插件设置输入。不要求用户将机密值输入到聊天中。
• 如果是容量/时间限制，则使用 --chunk-duration 10m 重试。
• 如果转录可信度低，则不随意修正专有名词和数字，将其留在待审查项目中。
• 如果 HWPX 渲染失败，则报告原因，并且不提供损坏文件作为产物。
• 如果收到 PDF 请求，则说明超出当前技能范围，并告知需要单独的转换环境。

自检

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

uv run scripts/self_test.py

此测试不调用语音识别 API，执行转录本解析、JSON 验证、HWPX 生成和结构验证。