report-writing

寫報告技能(report-writing)

產製正式技術報告 docx 交付物的可操作方法庫——特別針對繁體中文政府/招標交付。涵蓋從理解規格到驗證交付的全流程、內容策略、繁中排版、docx 生產工具鏈(真方程式、可點交互參照、目錄頁碼、圖)與驗證品保。

這是「主索引」。詳細操作在 references/ 子檔,按需讀取(progressive disclosure)。

何時用這個技能

• 要寫/改一份正式技術報告(尤其繁中、要交 docx)。
• 要把既有 docx 變專業:符號→真方程式、加可 Ctrl+點的引用/圖表參照、修目錄頁碼全是「1」、嵌/換圖。
• 要降低報告的「AI 味」(且不能動到數字/公式/引用)。
• 對齊招標工作項目、做規範追溯。

核心原則(先記住這幾條)

1. 先確認基準:多版迭代時,務必先問清「以哪個檔為內容基準、這版要改什麼」。版本/內容漂移是最大白工來源。
2. 「改寫」要先釐清語意:使用者說「每段改寫」可能是「改成某基準的逐字內容」,不是 rewrite 潤飾;說「100% 跟 X 一樣」=逐字零改寫,只可加格式層。先問再動。見 references/90-pitfalls.md。
3. 改任何文字後必跑確定性核對:數字/公式/引用/專名一字不動,改後逐項比對。見 references/70-verification.md。
4. 誠實揭露:政府交付、審查方熟悉自家標的;缺失/限制要寫明(語氣可官方,但不粉飾)。見 references/10-content-strategy.md。
5. 無證據不宣稱完成:跑驗證、看 PDF 再說「好了」。

端到端流程(五階段)

1. 理解規格:讀招標/RFP、參考文獻、既有素材;釐清交付物、語言、格式範本、截止/付款、比對基準(標的)。
2. 對齊結構:章節逐塊對齊招標工作項目;備規範追溯表。
3. 撰寫內容:內容策略 + 繁中寫作(對齊、誠實、降 AI 味、引用)。
4. 產製 docx:工具鏈 + 方程式 + 交互參照/目錄 + 圖。
5. 驗證交付:確定性核對 + 結構核對 + 對抗式審查 + PDF 目視。

詳見 references/00-workflow.md。

References 索引(何時讀哪篇)

子檔	何時讀
references/00-workflow.md	接到報告任務,先掌握全局與決策點
references/10-content-strategy.md	規劃章節、下筆、降 AI 味、引用、去識別
references/20-chinese-typography.md	標點(逗號/括號全半形)、字型、避免翻譯腔術語
references/21-style-corpus-standard.md	要讓行文像台灣正式技術報告:章節骨架、摘要/結論結構、連接詞、語氣、用字 do/don't(台灣開放語料實證)
references/22-terminology-table.md	查理工術語的台灣慣用譯名(語料 + 台/陸用字差異),補強 20 §3 地雷詞
references/23-english-ai-flavor.md	報告有英文內容、要抹除 AI 味:語料實證的 tell 詞/片語 + 結構紅旗(承轉密度、句長變異)
references/25-style-profiles.md	要讓行文/AI 味基準切到某特定來源(某期刊、某機關歷年報告、某作者)的專屬風格:用自己下載的語料建可切換 profile
references/30-docx-toolchain.md	開工產 docx 前:環境、python-docx、外科式改檔、檔案鎖
references/40-equations.md	把符號/公式做成真 Word 方程式(LaTeX→OMML)
references/50-cross-refs-toc.md	可點交互參照、目錄/圖表目錄、修頁碼
references/55-sections-pagefurniture.md	前置頁羅馬數字/正文阿拉伯數字重編頁碼、頁首自動帶當前章名、封面/章首頁不印頁碼、草稿浮水印(分節與頁面家具)
references/60-figures.md	產/換圖(matplotlib/MATLAB)、嵌入、防切圖
references/65-tables.md	做會跨頁的表格:表頭每頁重印、資料列不被切斷、欄寬固定、學術三線表/全框線
references/70-verification.md	宣稱完成前:核對、PDF 驗證、對抗式審查
references/90-pitfalls.md	遇到怪事或事前預防(檔案鎖、LibreOffice 重構、空書籤…)

環境速記

• uv 建 .venv(Python 3.12);裝 python-docx、lxml、Pillow、matplotlib、latex2mathml。
• 更新 docx 欄位/頁碼用 Word COM(PowerShell);LibreOffice 只拿來渲染 PDF 驗證,不可用來存 docx(會重構段落)。
• 語料庫本體在 repo 外:D:\56_corpus(繁中)、D:\56_corpus_en(英文);萃取 pipeline 在 corpus/、corpus_en/。
• 語料來源清單見 references/data/MANIFEST.sample.json;擴充計畫/spec 見 docs/superpowers/。
• 詳見 references/30-docx-toolchain.md、references/50-cross-refs-toc.md。

自動檢查(linter)

三支 linter 從技能根目錄(本 SKILL.md 所在目錄,以下記 <技能根目錄>)執行:

• 繁中術語:uv run --directory <技能根目錄> python -m corpus.lint_terms <檔案絕對路徑>
• 繁中 AI 味:uv run --directory <技能根目錄> python -m corpus.lint_zh_ai <檔案絕對路徑>
• 英文 AI 味:uv run --directory <技能根目錄> python -m corpus_en.lint_ai <檔案絕對路徑>

觸發:繁中交付改完文字後跑 lint_terms + lint_zh_ai;交付含英文內容再跑 lint_ai。退出碼:0 乾淨 / 1 有 error(1 的觸發級別可用 --fail-on 調整,預設 error)/ 2 環境錯誤(如缺字典)。判讀:error 需歸零,或逐項寫明豁免理由;warn 為語境相依,人工判定。

風格 profile(可切換基準):已設 profile 者,兩支 AI 味自動檢查(lint_zh_ai/lint_ai,含產出即審 hook)依當前 profile 的基準抽換,lint_terms(大陸用語)不隨切;手動跑可加 --profile <id>(或 --profile default 強制內建)。無設定時逐字同內建通則。機制與建置見 references/25-style-profiles.md。

專案 policy pack（可稽核基準）：宣告式專案可在 report.toml 的 [policies].pack 指到封閉 policy-pack.toml，同時抽換 terminology、繁中 AI、英文 AI 三套 QA 規則。這與上面的個人寫作 profile 不同：policy pack 是交付專案的一級輸入，必須有 id／version，manifest 與三份 JSON 都會被 hash、寫入 QA 並收入 release，適合固定機關／期刊正式門檻。樣板見 templates/policy-pack/。

產出即審(hook,plugin 安裝者自動生效):以 plugin 方式安裝本技能後,會註冊一個 PostToolUse hook(hooks/hooks.json → scripts/hooks/lint_gate.py)——Claude Code 每次以 Write/Edit/MultiEdit 產出 md/txt/docx/pptx/html/pdf 文檔,即自動過上列三支 linter 複審(共用 corpus_common.read_text 依副檔名抽取);有明確問題(error,exit 2 + stderr)會把逐條 found→suggest 回饋給模型自動修正,不靠模型自覺;warn 僅寫入 transcript 供人查看、不注入模型(不驅動模型修正)。技能安裝目錄內、或本技能 repo 的任何工作副本內(指紋兩檔偵測)、非文檔副檔名、大於 2MB 一律安靜放行;逃生門為環境變數 REPORT_WRITING_LINT_GATE=off。git clone(方式一)安裝者不會自動有此 hook,手動啟用(可複製的 settings.json 片段)見 README.md「產出即審」節。

交付前另可一鍵跑驗證腳本:uv run --directory <技能根目錄> python scripts/verify/verify_all.py <改寫前.txt> <改寫後.txt> <報告.docx> 一次串跑第 1 層(不變量核對)、第 2 層(結構核對)與標點風格核對,退出碼 0 全通過 / 1 有 FAIL / 2 環境錯誤,供 pre-commit / CI 掛載;四層驗證全貌與各層工具(scripts/verify/ 下 invariant_diff / structure_audit / check_links)見 references/70-verification.md。

多版／CI 專案用宣告式編譯、審查與 release(Phase 1–4):以 uv run --directory <技能根目錄> python -m report_project init <專案目錄> 建 report.toml、content.toml、traceability.toml 與空 evidence lock；python -m report_project build --config <專案>/report.toml 由內容模型原生產生 DOCX、反抽 candidate text 與帶來源／引擎／輸出 SHA-256 的 build manifest（真 OMML、span 書籤、內部 hyperlink、圖片 alt text、重印表頭固定欄寬三線表；亦可替換既有 DOCX 的唯一 {{REPORT_BODY}} 插槽）。review --format approval 產生綁定 baseline／candidate／段落 diff 三個 hash 的待審區塊；review.toml 的 open finding 或過期核准會阻擋 verify／release。verify 彙整不變量、內容／build provenance、需求證據、人工審查、結構、標點與三支 linter；release 只在全綠時封裝 DOCX、可選必備 PDF、全部證據與來源，verify-release 可離線驗 hash／缺檔／加檔／重複 entry。新增檔案證據後跑 lock-evidence，規範追溯表用 trace --format markdown（各命令同樣加完整 uv run --directory 前綴）。退出碼 0 通過 / 1 守門失敗 / 2 設定或環境錯誤。可直接跑的設定見 examples/report.toml；長期路線見 docs/roadmap-report-compiler.md。PDF 目視與必要人工簽核仍不可省略。

如何擴充這個技能

• 新增一篇:在 references/ 建 NN-topic.md(沿用兩位數編號分類:00 流程、10 內容、20 排版、30–60 生產、70 驗證、90 踩雷),並在上面「References 索引」表加一行;同時同步更新 references/00-workflow.md 開頭的路由表(防止路由漂移)。
• 補充既有篇:直接在對應子檔加小節;每篇末有「## 延伸/待補」可放新發現。
• 學到新踩雷→加進 90-pitfalls.md(症狀→根因→解法)。
• 重大變更記在下方變更紀錄。

變更紀錄

• v1:建立技能(9 篇 references)。
• v2:繁中語料標準 + 術語表 + lint_terms linter。
• v2.1:術語表對教育部/國教院學術名詞校準。
• v2.2:校準 variant 處理。
• v3:英文去 AI 味能力(23 + lint_ai)。
• v3.1:英文語料擴充。
• v3.2:兩支 linter P0 修復。
• v3.3:繁中去 AI 味能力(lint_zh_ai + zh-ai-tells.json,Claude+Codex 雙模型候選 × 122 篇語料頻率分級)。
• v3.4:驗證/排版腳本落地為實體工具(scripts/verify/ 不變量核對·結構核對·連結核對·verify_all 一鍵串跑,scripts/typography/ 標點轉換)+ pytest 鎖定;內容補五篇(55 分節頁面家具、65 跨頁表格、10 §9 審查意見回覆表、40 方程式編號、30 §1.1 交付 PDF 管線);英文語料 MANIFEST-en.sample.json(7,466 篇三來源可審計)。
• v3.4.1:收尾補全四項——examples/(生成器 + 迷你樣張 docx 四項賣點 + 三支 linter before/after 對照 + verify_all 實跑,test_examples.py 離線鎖定計數)、convert_punct 標點轉換擴及頁首/頁尾與註腳部件(與 verify_all 掃描對稱)、structure_audit 加 _Ref_ 反向孤兒書籤檢查、簡報對齊 v3.4;238 tests 綠。
• v3.5:產出即審自動化——corpus_common.read_text 抽取升級為六格式(md/txt/docx/pptx/html/pdf;pptx/html/pdf 以 zipfile+lxml/stdlib/pypdf 抽,不加 runtime 依賴)+ PostToolUse lint gate hook(hooks/hooks.json → scripts/hooks/lint_gate.py,標準路徑自動探索):plugin 安裝者每次以 Write/Edit/MultiEdit 寫出文檔即自動獲第一層審核,error 逐條回饋模型自動修正、warn 非阻斷、乾淨安靜放行,任何內部錯誤/缺相依/字典缺失一律友善放行不卡寫檔(逃生門 REPORT_WRITING_LINT_GATE=off);git clone 用戶依 README 手動啟用(可複製 settings.json 片段)。plugin 版本 3.4.1 → 3.5.0。
• v3.5.1:修 plugin hooks 重複載入——hooks/hooks.json 為標準路徑會自動探索,plugin.json 不得再顯式宣告(v3.5.0 實機觸發 Duplicate hooks file 致 hook 載入失敗);plugin 版本 3.5.1。
• v3.5.2:產出即審放行 ~/.claude 內部檔案(記憶/待辦非交付物,且記憶描述本技能字典時必然引用 tell 詞——實戰誤攔案例);plugin 版本 3.5.2。
• v3.6:可切換風格 profile——把自己下載的期刊/報告當語料建成可切換基準(corpus/build_profile.py 兩型產物、corpus/profile_config.py 設定解析),切換後兩支 AI 味 linter 與產出即審 hook 依當前 profile 抽換基準(--profile 旗標;lint_terms 不隨切、排版不隨切),無設定時逐字同內建通則;機制見 references/25-style-profiles.md;plugin 版本 3.6.0。
• v3.7:宣告式報告編譯器 Phase 1–4——report.toml 專案、需求／主張／證據追溯、evidence lock、原生 content.toml→DOCX build engine、範本插槽、三 hash 人工審查、交易式輸出與可離線自驗 release bundle。
• v4.0:產品化——可安裝 report-project CLI、wheel 內建驗證與 policy 資料、版本化專案 policy pack、status、CI／policy 樣板；Phase 1–5 完整收斂成同一 local-first 引擎。

詳見 CHANGELOG.md。