# tasks-project-projection — Design > 狀態：草稿 v2（依總管 2026-06-27 設計修正改寫；待 leo 審核） > 建立：2026-06-27 | 最後更新：2026-06-27 > 負責人：leo（uncle6me-web） > 來源：issue #16（InkStoneCo 總管）；脈絡 InkStoneCo 北極星 §5.2 > > v2 變更：廢棄「`HAS_ARCRUN` 檔案指紋偵測」整條路（arcrun workflow 存遠端 KV、不需本地檔，掃檔會 false negative）。改為「裝/init 對話 + 能力查詢（cli/mcp）+ 一次性廣告 + 手動啟用入口」。兩個 🔴 blocker（安裝指紋路徑 / 專案層 `.arcrun.yaml`）連帶消失。 --- ## 一句話說明 把 `system-dev/docs/3-specs/*/tasks.md` **單向投影**成唯讀 GitHub Project（機器／dashboard 好抓）；md 永遠是唯一真相源。是否啟用＝**裝/init 時 AI 問用戶一句、查環境有沒有 arcrun 能力**（cli/mcp），不靠掃本地檔。沒 arcrun／用戶不要 → 純 md、完全 no-op，並做一次性溫和廣告，之後閉嘴。 --- ## 背景與問題 - 純 md 的 tasks.md 對人友善，但機器／dashboard 難抓進度（要 parse markdown checkbox、跨多組 SDD 聚合）。 - 想要 GitHub Project 的看板視圖，又**不想開第二個真相源**——人手動拖 Project 卡 ⇄ md 改字會兩邊打架。 - 既有自動化紅線：**禁定期輪詢、禁 Actions 因事件 fan-out**（避免被 GitHub flag）。任何投影方案不得違反。 - 目標用戶 low-code、只會叫 CC 做事 → 不能要求用戶手動建 Project、手動填 id、手動跑 sync。 → 解法限定為：**單向（md → Project）、md 當家、push 後本機觸發一次、optional 模組預設不逼**。 --- ## 範圍 ### 包含（In Scope） - 在 **template** 新增一個 optional 模組：arcrun 投影工作流（YAML 工作流骨架 + README 標「需 arcrun，`acr push` 啟用」）。 - **裝/init 對話**：安裝或第一次 init 時 AI 問一句白話「要不要把待辦同步到 GitHub」；答好 → 查環境有沒有 arcrun（自己的 mcp 設定 / `acr` 在不在 PATH）→ 有就設定、沒有就一次性廣告。 - **手動啟用入口**：用戶第一次答「不好」、之後想開，有路可走（叫 AI 啟用，不需重裝）。 - 單向同步邏輯設計：md → GitHub Project，按穩定 id 增量（非全量重寫），glob 掃多組 `tasks.md`。 - arcrun 唯一對 md 的寫入：新 task 首次同步時，把 `` 註解 append 到那一行末（不碰既有內容）。 ### 不包含（Out of Scope） - **反向同步**（Project → md）：永不做。Project 唯讀，避免雙真相源。 - 定期輪詢、GitHub Actions 觸發、cron：全部禁止（守 flag 紅線）。 - 不要同步的用戶任何行為改變：完全 no-op；除裝/init 那**一次**問句與沒裝時的**一次**廣告外，不再追問、不重複廣告。 - arcrun 本體的安裝／工作流引擎（那是 arcrun 的事，本模組只是「給 arcrun 跑的一份 YAML 工作流」）。 - 把投影邏輯實作成獨立輪詢 daemon 或 GitHub App。 - **掃本地檔判斷有沒有 arcrun**（廢棄）：arcrun workflow 存遠端 KV、`arcrun_push_workflow` 收字串不讀本地檔，一個專案可零 arcrun 檔卻在用 arcrun → 掃檔 false negative。判準改「能力（cli/mcp）」。 --- ## 設計 ### 架構概覽 ``` push 後本機觸發（單次，非輪詢） │ tasks.md（唯一真相源）──┘ *.md 多組 ──► git diff（只看改了哪幾行） │ ┌───────┴────────┐ │ 投影工作流 │（Arcrun workflow 格式） │ classify 四動作 │ └───────┬────────┘ ▼ gh issue create / close / edit / archive ▼ GitHub Project（唯讀投影，給 dashboard 抓） │ 新 task → 把 寫回 md 那一行（唯一回寫） ``` ### 啟用判準：對話 + 能力查詢（不掃檔，取代舊 `HAS_ARCRUN`） > ⚠️ 廢棄舊設計。原本想抄 `HAS_WIKI`／`HAS_SDD` 的「掃本地檔指紋」模式，但**對 arcrun 不成立**： > - `arcrun_push_workflow` 收 `yaml_content` 字串或 `graph` 物件，**不讀本地檔**（mcp/src/tools/arcrun_workflow_crud.ts:35-146）。 > - workflow 真身存**遠端 KV**（`{api_key}:wf:*`，webhooks-named.ts:52-104）；list/run/delete 全是 API。 > - → 一個專案可**零 arcrun 檔案**卻完全在用 arcrun。掃檔當指紋會 **false negative**。 > > 判準改為**「碰不碰得到 arcrun 能力（cli/mcp）」**，落地成一段對話，不是 shell 偵測。 **流程（裝/init 時跑一次）** ``` 安裝 或 第一次 init │ └─ AI 問白話一句：「您需要把本專案的待辦事項同步到 GitHub 嗎？」 │ ├─ 答「好」→ AI 查環境有沒有 arcrun（自己的 mcp 設定有沒有 arcrun tool / `acr` 在不在 PATH） │ ├─ 有 → 啟動同步設定（push 投影 workflow），完成。 │ └─ 沒有 → 一次性溫和廣告： │ 「抱歉，您還沒安裝 Arcrun，無法啟用。Arcrun 是免費的 AI-friendly │ 工作流套件——想裝直接跟 Claude 說就行。之後也可手動啟用同步。」 │ └─ 答「不好」→ 不做，且不再追問。 ``` **三個設計意圖（務必守住）** 1. **判準＝能力不是檔案**：沒設定檔／沒 readme ≠ 沒 arcrun。問「cli/mcp 裝了沒」。 2. **讓用戶知道有這東西**：非專家不知道「有 arcrun、有同步功能」→ 問一次＝自然揭露。 3. **一次廣告、不一直廣告**：沒裝時做**一次**溫和廣告（免費／跟 Claude 說就能裝／以後可手動啟用），之後閉嘴，別每次 install 都騷擾。 **手動啟用入口**：第一次答「不好」後想開 → 叫 AI 啟用（AI 重跑「查能力 → push workflow」那段），不需重裝。 （具體入口形態——slash command vs 純對話——待實作細化；low-code 用戶只需「跟 AI 說」。） **對齊北極星**：install 完即可用、單一 AI 入口、不留抽象前置步驟。用戶不碰任何 `HAS_*` 抽象檔，就是被 AI 問一句、答一句。 ### 穩定 id 與增量同步 - **id 埋在 md 行內**：`- [ ] 實作 X `。首次同步前無 id；create 後 Arcrun 回寫。 - **增量判準＝git diff**：push 後本機觸發拿 `git diff` 的前後版，只處理「動到的行」，不全量重掃（省 API、避免無謂 edit）。 - **四種動作**（issue 定案，照抄）： | md 狀態 | 動作 | |---------|------| | 有文字、無 id | `gh issue create` → 把 `` 寫回該行 | | 有 id 且 `[ ]→[x]` | `gh issue close` | | 有 id 且 文字／負責人／日期改 | `gh issue edit` | | id 在、但整行不見 | `gh issue close`／archive | ### 多組 SDD 全同步 - glob 掃 `system-dev/docs/3-specs/*/tasks.md`，每組獨立。 - 每組帶**子系統 label**（取 folder 名）分組，方便 Project 過濾。 - 新開 SDD folder → 新 `tasks.md` 首次 commit 即自動成新組，**無需手動登記**（守 low-code）。 ### 守紅線：觸發方式 - **本機 push 後觸發單次**（git post-push 類 hook 或 Arcrun 的 push 事件鉤子），**單一目標**。 - 明令禁止：cron／定期輪詢／GitHub Actions on push fan-out。 - 觸發後做完即止，不常駐、不重試輪詢。 ### 關鍵決策 | 決策 | 選擇 | 原因 | 放棄的選項 | |------|------|------|----------| | 同步方向 | 單向 md→Project | md 當家，杜絕雙真相源打架 | 雙向同步（會兩邊衝突） | | 真相源 | tasks.md | 人／CC 都只改 md，Project 唯讀 | Project 當真相源（low-code 用戶碰不到） | | 觸發 | push 後本機單次 | 守 flag 紅線 | 定期輪詢／Actions（踩紅線） | | 增量依據 | 行內穩定 id + git diff | 省 API、不全量重寫 | 全量 diff title 比對（脆、易撞名） | | 啟用判準 | 裝/init 對話 + 查 cli/mcp 能力 | 能力≠檔案；arcrun 存遠端 KV，掃檔 false negative | `HAS_ARCRUN` 檔案指紋（漏判用遠端沒落檔者，**廢棄**） | | 沒裝時 | 一次性溫和廣告 + 之後閉嘴 | 揭露功能存在又不騷擾 | 每次 install 都廣告（騷擾）／完全靜默（用戶不知有此功能） | | 腳本形態 | arcrun workflow（YAML：name/description/flow/config） | 守「什麼都叫 arcrun」；`acr push` 部署 | 獨立 daemon／App（多一套要維護） | | md 回寫 | 只在新 task 加 `` | 最小侵入，leo 已接受 | 在 md 維護更多 metadata（污染 md） | ### 介面 / 落點（待實作細化） - 工作流檔形態：arcrun YAML（`name/description/flow/config` 結構）。template 放 `workflows/<投影>.yaml`，README 標「需 arcrun，`acr push <檔>` 啟用」。（最終以 arcrun 端 SDD 定案為準。） - README：optional 模組區塊標「此功能需 arcrun；不要／沒裝則純 md no-op」。 - install/update：**不靠 `HAS_*` 分支裝檔**。改由裝/init 對話驅動——AI 在用戶答「好」且查到 arcrun 能力時，`acr push` 那份 workflow；workflow YAML 本身可隨 template 一起帶（留作記錄＋手動啟用素材），但帶檔 ≠ 啟用。 - 啟用＝遠端 push 了 workflow，不是本地有檔。 --- ## 風險與待解 | 項目 | 狀態 | |------|------| | ~~arcrun 安裝指紋路徑~~ | ✅ 消失（廢棄掃檔，改能力查詢） | | ~~arcrun workflow 檔標準落點 blocker~~ | ✅ 降級：慣例 `workflows/*.yaml` + `acr push`，最終以 arcrun 端 SDD 為準 | | 「查 arcrun 能力」的具體判準（mcp tool 名／`acr` PATH 偵測法） | 🟡 待 arcrun 端 template 對接定案 | | push 後本機觸發的具體掛載點（git hook vs arcrun 事件鉤） | 🟡 待 arcrun 觸發能力確認 | | id 回寫造成 working tree 變動（觸發後 md 有新 diff） | 🟡 需設計：回寫不應再觸發一輪（避免迴圈，§迴圈防護） | | 手動啟用入口形態（slash command vs 純對話） | 🟡 待實作細化 | > 不再有 🔴 blocker。施工順序：**leo 定調「等 arcrun 動工完再施工」**——等 arcrun 端把 template 對接 + 觸發/能力查詢定案，回來確認後再寫骨架。本 SDD 先把設計改成這版對話式、定案待審。 --- ## 與既有模式的對齊檢查 - ⚠️ **不沿用** `HAS_WIKI`／`HAS_SDD` 的掃檔指紋模式——對 arcrun 不成立（存遠端 KV）。改「能力查詢 + 對話」，這是與既有兩模組的**刻意分歧**，原因見上。 - ✅ optional 預設關：不要／沒裝 arcrun 完全 no-op（對齊「沒 wiki 就不裝 wiki hooks」的精神，只是判準從檔案換成能力+意願）。 - ✅ 守 flag 紅線（issue-handle skill 既有的避免被 flag 鐵律）：單向、push 後本機單次、禁輪詢/Actions。 - ✅ low-code 友善：被 AI 問一句答一句、自動建組、id 自動回寫，用戶不碰抽象前置步驟。 - ✅ 不騷擾：沒裝時一次廣告即止（對齊「不增加用戶負擔」）。 - ✅ 本 SDD 為內部記錄，落 `docs/3-specs/`（gitignore，不推 GitHub）。