qbarev/para-plugin

專案

專案是具有明確目標與終止狀態的努力事項 — 與「領域」這種持續進行的項目不同。一個專案是筆記庫中的一個資料夾，並與任務後端中的一個專案配對：資料夾存放專案的定義，後端存放其任務（tasks.md）。每個任務呼叫都是對 tasks.md 的操作，依據 TASKS 的轉接器執行。

基礎層

在行動之前，請先閱讀本技能基礎目錄下 ../../para/<file>.md 的檔案 — 這些檔案包含了共同規則，不要憑記憶複述：

• ../../para/paths.md — 一律讀取，包括「語言」：以下的字串來自 lang/<LANG>.md
• ../../para/tasks.md — 一律讀取：操作、配對方式、任務的定義
• ../../para/find-target.md — 用於 overview 和 task 子命令
• ../../para/note-format.md — 用於 create 子命令；也適用於每個子命令中的「舊版欄位」
• ../../para/project-id.md — 用於 create 子命令
• ../../para/dod.md — 用於 create 子命令（撰寫 project.dod 章節）和 overview 子命令
• ../../para/thresholds.md — 用於 list 和 overview 子命令：專案排序、停滯判斷、視野範圍、任務計數、輸出大小
• ../../para/confirm.md — create 和 task 子命令會寫入（第 1 級）；list 和 overview 子命令不寫入任何內容
• ../../para/move.md — 用於 create 子命令，在寫入可能發生衝突的資料夾之前

子命令

$ARGUMENTS 的第一個字決定子命令：list、create、overview、task。如果不是這些關鍵字，請根據語意判斷使用者意圖，並告知你選擇了哪個子命令。空的 $ARGUMENTS → 執行 list，然後詢問下一步。

每個子命令都可能遇到在任務後端建立之前就已存在的專案：這些專案帶有 status、Tasks/（note-format.md 會說明何時此為舊版格式），且沒有 tasks_ref 欄位。請按照 note-format.md「舊版欄位」所述的方式讀取它們 — 僅回報，絕不重寫。

---

create <描述> — 啟動一個專案

輸入：專案的內容、目標、截止日期、初步步驟。如果輸入為空 → 詢問專案的內容與目標。

1. 從磁碟讀取 Templates/Project.md，內容完全照搬。

2. 根據 note-format.md 推導出標題。此標題有三種用途：作為 title 和 H1 不帶 ID 前綴；以及 — 帶上前綴 — 作為資料夾名稱和總覽檔案名稱。提出 short 建議，遵循 note-format.md 的規範。

3. 根據 project-id.md 發出 ID。

4. 在 Projects/ 底下建立資料夾結構：

   PROJ-xxxx <標題>/
   ├── PROJ-xxxx <標題>.md      ← 總覽檔案，來自 Templates/Project.md
   ├── Notes/
   ├── Resources/
   └── Results/
   

   三個子資料夾都要建立，即使為空。不建立 Tasks/（當 TASKS = files 時，轉接器會在新增第一筆任務時自動建立）。

5. 根據 note-format.md 的專案列填寫 frontmatter。created 設為今天日期。deadline 僅在描述中有提供時才填入。tasks_ref 保持空白，直到第 7 步（在 pairing: none 的情況下，此欄位會被省略）。

6. 填寫主體：

   • project.goal 章節 — 目標 / 期望的最終狀態。必填。
   • project.value 章節 — 使用者能獲得的好處，必須是可衡量或明確的（請參考 note-format.md「關於成果的三個章節」）。必填。 如果此章節或 project.goal 章節的內容從輸入中無法明確得知，請在寫入前用一個問題同時詢問兩者（參考 confirm.md，第 1.5 級）。
   • project.problem 章節 — 觸發此專案的問題。
   • project.expected_result 章節 — 具體的產出及其存放位置。
   • project.scope 章節 — 僅包含使用者提及的項目。通常為空：研究任務會負責填寫（參考 tasks.md「研究任務」）。
   • project.dod 章節 — 依據 dod.md 的核取方塊。如果描述無法讓你推導出實際的檢查項目，請詢問 — 就像缺少 project.goal 時的做法一樣。
   • common.links 章節 — 指向明確相關筆記的 wikilinks，否則使用範本中的 -。

7. 根據 tasks.md「配對」建立配對：使用標題和 ID 呼叫 project.create。在 pairing: separate 的情況下，將回傳的 ref 寫入 tasks_ref:；如果呼叫失敗，請告知：資料夾會保留，但處於未配對狀態，稍後可透過 /projects task 來配對。在 pairing: none 的情況下，沒有配對，也沒有 tasks_ref：跳過此寫入步驟。

8. 在新專案中建立初始任務，不設定日期：

   • 研究任務，依照 tasks.md「研究任務」所述，一律建立，除非使用者已經明確說明了完整的範圍 — 此時改將範圍寫入 project.scope 章節；
   • 使用者明確提及的步驟，使用 task.add 新增，並依照「任務的定義」來措辭。無法被描述為一個動作的步驟，應歸類為研究問題，而非任務。

   絕不發明使用者未提及的步驟。

9. 回報資料夾路徑、ID、標題、short（並提供修改機會）、截止日期、目標、價值描述、後端專案名稱，以及已建立的任務。

如果輸入描述的是一個持續進行的責任，且沒有終止狀態，這就不是一個專案 — 請告知並建議使用 /areas create 代替。如果這是一個使用者尚未決定是否執行的想法，請說明這還不是一個專案（參考 tasks.md「配對」），並提議將其保留在收件匣中（inbox.name）。

---

task <專案> <任務> — 新增一個任務

1. 根據 find-target.md 找到專案，操作為「為專案新增任務」。目標也可能是來自 areas.md 中 AREA_TASK_PROJECTS 的領域專案 — 透過名稱匹配。
2. 解析去向：如果是領域專案 → 去向為 area；否則使用總覽檔案的 tasks_ref 作為 project_ref（在 pairing: none 的情況下，專案資料夾本身就是 ref，此步驟等同於直接取得專案）。
   • 若為 pairing: separate 但總覽檔案上沒有 tasks_ref → 顯示 task.unpaired 字串，並提議建立配對（即 create 的第 7 步）。如果使用者同意，則建立配對，然後繼續。絕不將任務寫入筆記庫作為替代方案。
3. 根據 tasks.md「任務的定義」來為任務措辭。如果使用者原本的措辭已經符合，則保留；否則在告知時提出改寫後的版本。如果無法轉換為一個動作，則詢問下一步（第 1.5 級）。
4. 使用 project_ref 或 area 呼叫 task.add（當 TASKS = files 時，已存在的基底名稱會造成衝突：請參考 note-format.md「名稱衝突」，需詢問使用者，不可默默加上後綴）：任務文字、較長的描述（如有需要）、duration（僅在使用者有提供時）。日期規則請參考 tasks.md「欄位」。
5. 回報任務與其所屬的專案。

---

overview <專案> — 檢視專案進度

唯讀。 不寫入任何內容 — 不寫入筆記庫，也不寫入後端。如果摘要中發現值得修正的問題，請告知並讓使用者決定。

1. 根據 find-target.md 找到專案，操作為「回報」。如果沒有參數，則列出專案並詢問。

2. 讀取總覽筆記：frontmatter 以及 project.goal、project.value、project.expected_result、project.dod、common.links 等章節。空白欄位應回報為空白，絕不憑推測填寫。

3. 讀取任務（使用 task.list，僅限開啟中的任務）：其日期與持續時間。根據 thresholds.md「任務計數」計算數量。在 pairing: separate 的情況下，如果沒有配對 → 跳過，並顯示 task.unpaired 字串。

4. 完整讀取 Notes/（以及 Results/，如果其中有內容），但受 thresholds.md 的上限限制 — 這裡是真正存放決策與風險的地方。

5. 舊版格式。 如果總覽檔案帶有 status / priority / value / estimate，或資料夾中有舊版的 Tasks/（請參考 note-format.md），則加入一行，使用 overview.legacy 字串並代入 {fields}，例如 status, Tasks/ (3 個檔案)（其中的資料夾計數使用 overview.legacy_tasks 字串），僅列出存在的項目。不讀取任務筆記來判斷進度；遷移過程會決定哪些內容需要保留。

6. 訊號 — 僅回報符合條件的項目：

   • 專案的 deadline 已過期，或落在 thresholds.md 定義的視野範圍內；
   • 逾期任務 — 告知逾期天數；
   • 在截止日期位於視野範圍內時，卻沒有任何排程任務；
   • 有日期的任務缺少持續時間；
   • 停滯時間超過 thresholds.md 中定義的專案閾值，計算方式如該文件所述（有配對時根據 project.activity，否則根據檔案修改時間 mtime，請參考 thresholds.md）；
   • common.links 章節中有懸空的 wikilinks；
   • 所有驗收標準都已勾選，但專案仍位於 Projects/ 中 — 表示已完成但尚未關閉。

7. 以 LANG 語言輸出到對話中。 標籤是 lang/<LANG>.md 中的字串，以下方範本中的大括弧 {} 作為鍵名；此處以英文顯示：

   ## PROJ-0001 · 專案 A
   
   **{overview.area}** 領域 A · **{overview.deadline}** 2026-10-31 — 14 天
   **{overview.tasks}** {count.scheduled} 3 · {count.overdue} 1 · {count.backlog} 6
   **{overview.acceptance}** ☑☐☐ 1/3
   
   ### {overview.essence}
   <目標，1-2 句話。>
   <預期成果 — 一行。>
   <價值 — 一行。>
   
   ### {overview.scheduled}
   - **寫信給供應商** — 週二 10-21，30 分鐘
   - **填寫表單** — 逾期 2 天，1 小時
   
   ### {overview.backlog}
   - 預約諮詢
   - …還有 3 項
   
   ### {overview.digest}
   - <來自 Notes/ 的關鍵決策或結論 — 用你自己的話描述。>
   
   ### {overview.signals}
   - 距離截止日期還有 14 天，沒有任何排程任務
   

   大括弧是鍵名，不是文字：請輸出每個鍵名所代表的字串。日期使用 common.date 格式（2026-10-31）；短格式 common.date_short 用於任務行（10-31），並搭配 common.weekdays 中的星期名稱；距離截止日期的天數使用 common.days；單位縮寫使用 common.unit.*；逾期任務帶有 task.overdue_by 字串；待辦事項列表的結尾使用 overview.backlog_more 字串（{n} 代表未顯示的任務數量）。overview.backlog 區塊顯示最舊的未註記日期任務，數量以 thresholds.md 的上限為準。移除任何為空的區塊或欄位。空的 Results/ 是正常狀態。

---

list — 列出專案

唯讀。 每個專案一行 — 這是指標，不是摘要：絕不開啟 Notes/ 讀取。

1. 列舉 Projects/ 下的直接子資料夾。已歸檔的專案不在此列 — 那是 /archive list 的職責。

2. 讀取總覽檔案的 frontmatter：id、title、area、deadline，以及在 pairing: separate 情況下的 tasks_ref。沒有 frontmatter 的資料夾是慣例之前的舊格式 — 以資料夾名稱顯示，並加上 common.no_metadata 字串。

3. 讀取每個有 ref 的專案的任務（使用 project_ref 呼叫 task.list，僅限開啟中的任務），並根據 thresholds.md「任務計數」進行計數。

4. 排序，根據 thresholds.md「專案順序」。

5. 以 LANG 語言輸出，使用 list.*、count.* 和 task.unpaired 等字串 — 每行內容較緊湊，因此待辦事項計數使用 count.backlog_short（標題使用 list.header，截止日期使用 list.until 搭配 common.date_short 格式的日期，如果落在 thresholds.md 的視野範圍內，則在日期後加上 (14 d)：表示剩餘天數與 common.unit.day）；此處以英文顯示：

   **專案 (4)**
   1. PROJ-0008 專案 A — 領域 A · 截止 10-31 (14 d) · 已排程 2 · 待辦 3
   2. PROJ-0020 專案 B — 截止 10-31 (14 d) · 已排程 0 · 待辦 3
   3. PROJ-0009 專案 C — 領域 B · 截止 02-28 · 任務管理器中無對應項目 · 舊格式
   4. PROJ-0027 專案 D — 待辦事項為空
   筆記庫中無對應項目：「專案 E」
   

   • 已過期的截止日期：使用 list.deadline_passed 字串。
   • 存在舊版欄位或舊版 Tasks/ 時：使用 list.legacy 字串。
   • 待辦事項為空的專案：使用 list.backlog_empty 字串。
   • 最後一行（list.orphans）列出沒有對應總覽檔案的後端專案，這些專案來自 tasks.md「表格注意事項」中 project.list 的回報。當此列表為空，或轉接器不支援 project.list 時，則省略此行。
   • 移除任何空白欄位，不要輸出佔位符號。空的 Projects/ 是一個有效的答案：直接說明即可。

已歸檔與慣例前的專案

Archive/ 中的專案可能早於現行慣例：沒有 frontmatter、沒有 PROJ-xxxx 前綴、沒有子資料夾。從筆記中讀取 project.goal 章節，跳過任務區塊和 overview.acceptance，並直接說明該專案已歸檔且為舊格式。

備註

• 計算，而非估算：天數、任務計數和逾期時間來自後端、檔案系統和今天的系統日期。如果某個欄位空白而無法計算，請說明其為空白，而不是自行猜測。
• 摘要是回報狀態，不是評判使用者。請使用「逾期 5 天」，而非「你荒廢了這個專案」。
• 所有內容，包括任務，都使用 LANG 語言。