version: "1.0.1" name: planning-with-files-zht description: 基於 Manus 風格的檔案規劃系統，用於組織和追蹤複雜任務的進度。建立 task_plan.md、findings.md 和 progress.md 三個檔案。當使用者要求規劃、拆解或組織多步驟專案、研究任務或需要超過5次工具呼叫的工作時使用。支援 /clear 後的自動會話恢復。觸發詞：任務規劃、專案計畫、制定計畫、分解任務、多步驟規劃、進度追蹤、檔案規劃、幫我規劃、拆解專案 user-invocable: true allowed-tools: "Read Write Edit Bash Glob Grep" hooks: UserPromptSubmit:

• hooks:
• type: command

command: "if [ -f task_plan.md ]; then echo '[planning-with-files-zht] 偵測到活躍計畫。如果你在本次對話中還沒有讀取 task_plan.md、progress.md 和 findings.md，請立即讀取。'; fi" PreToolUse:

• matcher: "Write|Edit|Bash|Read|Glob|Grep"

hooks:

• type: command

command: "if [ -f task_plan.md ]; then echo '===BEGIN PLAN DATA==='; cat task_plan.md 2>/dev/null | head -30; echo '===END PLAN DATA==='; fi" PostToolUse:

• matcher: "Write|Edit"

hooks:

• type: command

command: "if [ -f task_plan.md ]; then echo '[planning-with-files-zht] 請更新 progress.md 記錄你剛才做了什麼。如果某個階段已完成，請更新 task_plan.md 的狀態。'; fi" Stop:

• hooks:
• type: command

command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache///*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true" PreCompact:

• matcher: "*"

hooks:

• type: command

command: "if [ -f task_plan.md ]; then echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; ATTEST=''; if [ -f .planning/.active_plan ]; then AP=$(tr -d '[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && [ -f \".planning/$AP/.attestation\" ]; then ATTEST=$(tr -d '[:space:]' < \".planning/$AP/.attestation\" 2>/dev/null); fi; fi; if [ -z \"$ATTEST\" ] && [ -f .plan-attestation ]; then ATTEST=$(tr -d '[:space:]' < .plan-attestation 2>/dev/null); fi; if [ -n \"$ATTEST\" ]; then echo \"Plan-SHA256 at compaction: $ATTEST\"; fi; fi; exit 0" metadata:

version: "2.38.1"

檔案規劃系統

像 Manus 一樣工作：用持久化的 Markdown 檔案作為你的「磁碟工作記憶」。

第一步：恢復上下文（v2.2.0）

在做任何事之前，檢查規劃檔案是否存在並讀取它們：

1. 如果 task_plan.md 存在，立即讀取 task_plan.md、progress.md 和 findings.md。
2. 然後檢查上一個會話是否有未同步的上下文：

# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files-zht\scripts\session-catchup.py" (Get-Location)

如果恢復報告顯示有未同步的上下文：

1. 執行 git diff --stat 查看實際程式碼變更
2. 讀取目前規劃檔案
3. 根據恢復報告和 git diff 更新規劃檔案
4. 然後繼續任務

重要：檔案存放位置

• 範本在 ${CLAUDE_PLUGIN_ROOT}/templates/ 中
• 你的規劃檔案放在你的專案目錄中

快速開始

在任何複雜任務之前：

1. 建立 `task_plan.md` — 參考 templates/task_plan.md 範本
2. 建立 `findings.md` — 參考 templates/findings.md 範本
3. 建立 `progress.md` — 參考 templates/progress.md 範本
4. 決策前重新讀取計畫 — 在注意力視窗中重新整理目標
5. 每個階段完成後更新 — 標記完成，記錄錯誤

注意： 規劃檔案放在你的專案根目錄，不是技能安裝目錄。

核心模式

上下文視窗 = 記憶體（易失性，有限）
檔案系統 = 磁碟（持久性，無限）
 
→ 任何重要的內容都寫入磁碟。

檔案用途

關鍵規則

1. 先建立計畫

永遠不要在沒有 task_plan.md 的情況下開始複雜任務。沒有例外。

2. 兩步操作規則

"每執行2次查看/瀏覽器/搜尋操作後，立即將關鍵發現儲存到檔案中。"

這能防止視覺/多模態資訊遺失。

3. 決策前先讀取

在做重大決策之前，讀取計畫檔案。這會讓目標出現在你的注意力視窗中。

4. 行動後更新

完成任何階段後：

• 標記階段狀態：in_progress → complete
• 記錄遇到的任何錯誤
• 記下建立/修改的檔案

5. 記錄所有錯誤

每個錯誤都要寫入計畫檔案。這能累積知識並防止重複。

## 遇到的錯誤
| 錯誤 | 嘗試次數 | 解決方案 |
|------|---------|---------|
| FileNotFoundError | 1 | 建立了預設設定 |
| API 逾時 | 2 | 新增了重試邏輯 |

6. 永遠不要重複失敗

if 操作失敗:
    下一步操作 != 同樣的操作

記錄你嘗試過的方法，改變方案。

7. 完成後繼續

當所有階段都完成但使用者要求額外工作時：

• 在 task_plan.md 中新增階段（如階段6、階段7）
• 在 progress.md 中記錄新的會話條目
• 像往常一樣繼續規劃工作流程

三次失敗協定

第1次嘗試：診斷並修復
  → 仔細閱讀錯誤
  → 找到根本原因
  → 針對性修復
 
第2次嘗試：替代方案
  → 同樣的錯誤？換一種方法
  → 不同的工具？不同的函式庫？
  → 絕不重複完全相同的失敗操作
 
第3次嘗試：重新思考
  → 質疑假設
  → 搜尋解決方案
  → 考慮更新計畫
 
3次失敗後：向使用者求助
  → 說明你嘗試了什麼
  → 分享具體錯誤
  → 請求指導

讀取 vs 寫入決策矩陣

五問重啟測試

如果你能回答這些問題，說明你的上下文管理是完善的：

何時使用此模式

使用場景：

• 多步驟任務（3步以上）
• 研究任務
• 建構/建立專案
• 跨越多次工具呼叫的任務
• 任何需要組織的工作

跳過場景：

• 簡單問題
• 單檔案編輯
• 快速查詢

範本

複製這些範本開始使用：

• templates/task_plan.md — 階段追蹤
• templates/findings.md — 研究儲存
• templates/progress.md — 會話日誌

腳本

自動化輔助腳本：

• scripts/init-session.sh — 初始化所有規劃檔案
• scripts/check-complete.sh — 驗證所有階段是否完成
• scripts/session-catchup.py — 從上一個會話恢復上下文（v2.2.0）

安全邊界

此技能使用 PreToolUse 鉤子在每次工具呼叫前重新讀取 task_plan.md。寫入 task_plan.md 的內容會被反覆注入上下文，使其成為間接提示注入的高價值目標。

反模式