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、內容、格式設定來完成。不執行 Hancom 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 產生與結構驗證。