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 產生與結構驗證。