真能用的office辦公skill！
📖 技能介紹
name: office-git-init description: Use when first setting up a folder that contains Word/Excel/PowerPoint files (.docx/.xlsx/.doc/.xls/.pptx) for human-AI collaboration — a new document project, a folder with no git repo, or one where git diff shows only "Bin 35533 -> 35565 bytes" instead of what changed inside the document.
與人協同編輯 Office 文件
本 skill 是一次性的初始化工具。 跑完
init_workspace.py，協作紀律就寫進了 目標專案的CLAUDE.md（無條件載入，不依賴本 skill 觸發），日常工作照那份走即可， 不必再回來讀這裡。下面的內容是初始化會裝進專案的東西，以及為什麼這麼裝。
Overview
二進位制辦公文件（.docx/.xlsx）的協同有兩個特有陷阱，程式碼檔案上不存在：
- 看不見差異——git 只會說
Bin 35533 -> 35565 bytes，說不出改了哪一段、哪個單元格。 - 靜默覆蓋——文件開在 Word/WPS 裡時，你寫盤後用戶一儲存，記憶體裡的舊版本會整體覆蓋磁碟版本，幾百處改動瞬間歸零，沒有任何報錯。
核心原則：磁碟上的檔案是唯一事實；改前先看差異，改後立刻留痕。
When to Use
- 使用者或同事也在編輯同一個 Word/Excel 檔案
- 使用者說"我改了一些""你幫我看看他改了什麼"
- 目錄裡有
~$xxx.docx鎖檔案 - 需要知道二進位制文件內部改了什麼
不適用：純文本/程式碼檔案（git 原生可 diff）；只讀不改的場合。
工作區初始化（每個資料夾做一次）
接手任何放著 Office 文件的資料夾，第一件事就是跑這條。 沒有它，後面的
"先 diff"根本無從談起——git 對二進位制文件只會說 Bin 35533 -> 35565 bytes。
cd <目標資料夾>
python <本skill目錄>/init_workspace.py
冪等，重複跑安全。它會：git init → 裝 .gittools/office2txt.py 並配好 textconv
→ 寫 .gitattributes（Office 檔案掛 textconv）和 .gitignore（排除 ~$ 鎖檔案）
→ 把現有文件提交為"基線版本"。初始化前先查鎖，有文件開著會提示，避免把
半截狀態存成基線。
配好之後的效果：
$ git diff -- 季度總結.docx
-收入 100 萬元，支出 80 萬元。
+收入 120 萬元，支出 90 萬元。
$ git diff -- 明細表.xlsx
- A2=收入 | B2=100
+ A2=收入 | B2=150
已有歷史的資料夾：指令碼不會自動提交已存在的改動，只提示你確認後自行提交—— 避免把別人未完成的活當成基線。
每次改動的四步
這四步是一個整體，缺任何一步都會在協同時出事。
1. 查鎖——先分清"真佔用"還是"殭屍鎖"
ls ~$* 2>/dev/null # 有輸出 = 可能正開著
~$ 檔案常在 Office 異常退出後殘留，見到它先別停，做兩項判定：
try: # ① 能獨佔開啟 = 無程序持有
open(doc, "r+b").close(); free = True
except PermissionError:
free = False
② 查 Office 程序實際開著哪些檔案（視窗標題或命令列）。
- 兩項都表明無人佔用 → 是殘留鎖，可以改；改完提醒使用者刪掉它。
- 確有程序開著這份文件 → 停下，請使用者先關閉，不要硬寫。硬寫的兩種下場：
報
Device or resource busy（好情況，至少你知道失敗了），或寫成功但隨後被使用者 的儲存動作整體覆蓋（壞情況，無聲無息，幾百處改動瞬間歸零）。
2. 先 diff 再動手，並把使用者的改動報告給他
git status --short
git diff -- "<檔名>"
絕不拿自己早先的副本當"檔案現在的樣子"。 使用者隨時在改，你 scratchpad 裡的 副本在他碰檔案那一刻就過期了——它只能證明"我改過什麼"，不能證明"檔案現在是什麼"。
3. 改
用 python-docx / openpyxl 做定點修改；格式複雜的表格優先用 Office COM 原地改。 改之前先斷言原值，防止改錯行：
小蔥技能站7w4.net每天更新，海量AI技能等你發現。
assert "35 萬元" in para.text, "原值不符，已被他人改動，停止"
4. 立刻提交——這一步最容易被跳過
git add -A && git commit -m "誰改的 + 改了什麼 + 為什麼"
不提交的代價：使用者的手工改動和你的改動混成一團，無法區分、無法回滾到中間點。 基線測試中 3/3 的代理都完成了任務卻沒有一個提交，正是這個坑。
Quick Reference
| 你要做的事 | 命令 |
|---|---|
| 看文件現在什麼樣 | git diff -- "<檔案>"（已配 textconv） |
| 看某次改動 | git diff HEAD~1 HEAD -- "<檔案>" |
| 取出歷史版本另存（不覆蓋當前） | git show HEAD~2:"<檔案>" > 舊版.docx |
| 回滾到上一版（會覆蓋，慎用） | git checkout HEAD~1 -- "<檔案>" |
| 檔案被鎖又必須記錄版本 | git hash-object -w + update-index --cacheinfo + commit-tree |
Common Mistakes
| 做法 | 後果 | 正確做法 |
|---|---|---|
| 拿早先的副本當現狀判斷依據 | 把使用者的改動誤判成"資料丟失"，白排查半天 | 只認 git diff 和磁碟檔案 |
| 把備份存進會話臨時目錄 | 換個會話就沒了，等於沒備份（基線測試中 2/3 犯此錯） | 備份進專案目錄，或乾脆用 git commit 代替備份 |
| 文件開著照樣寫盤 | 使用者一儲存，你的改動全沒，無報錯 | 先讓使用者關閉 |
| 改完不提交 | 兩人的改動混在一起，無法區分和回滾 | 每個節點提交，資訊寫清依據 |
| 用 Office COM 開啟"只讀"看一眼就以為沒變 | COM 開啟即回寫（實測腳註 id 被重排） | 開啟驗證後重新提交快照 |
| 直接覆蓋單元格公式 | 破壞表內勾稽 | 先讀 data_only=False 看清是值還是公式 |
| 靠指令碼"全綠"就宣佈沒問題 | 指令碼只驗它寫死的那些項 | 指令碼 + git diff 逐字看，兩者都要 |
Windows / Office 環境坑
- WPS 常駐：十幾個
wps.exe是常態，鎖檔案殘留很普遍。殘留鎖（正文已移走/ 已關閉）可刪，刪前用獨佔開啟測一下：open(doc,'r+b')成功即無程序佔用。 .doc/.xls舊格式：python-docx/openpyxl 讀不了，只能用 Office COM。- 加密的 .xls：
xlrd報Workbook is encrypted，用 Excel COM 開啟並傳空密碼 （Password=""）避免彈模態框卡死。 - Word COM 的
SaveAs2會卡死：改用直接讀Paragraphs.Item(i).Range/Format。 - COM 呼叫返回
RPC_E_CALL_REJECTED：多半是 Office 彈了模態框（如首次執行的 "接受許可協議"）。列舉視窗找出來讓使用者點掉，不要盲目重試。 - 保全格式：改 xlsx 優先 Excel COM 原地改；openpyxl 會重寫整個檔案，僅在確認 工作簿是純單元格表格（無圖表/透視表/圖片）時使用。
Red Flags — 出現這些念頭就停下
- "我記得這個檔案是……" → 你不記得，去
git diff - "先改完再一起提交" → 現在就提交，混在一起就分不開了
- "鎖檔案應該是殘留吧" → 測一下再說，猜錯的代價是使用者的活白乾
- "改動很小，不用留痕" → 小改動混進大改動裡，出事時最難查
- "指令碼跑過了，沒問題" → 指令碼只驗它認識的項，diff 還得看
🤖 AI 評測
這是一個構思巧妙、做得很用心的工具——讓 AI 改文件變得"看得見、退得回"，文件質量高、說明寫得清楚，初始化一次後就能自動生效，同事也能輕鬆上手。不過在未安裝依賴時會直接報錯，缺少一步到位的提示，對新手不夠友好。核心功能紮實，但穩定性細節還需打磨。
