From 31d4a9c47b22f3c7560c5b86be2281f90561a270 Mon Sep 17 00:00:00 2001 From: uncle6me-web Date: Thu, 2 Jul 2026 16:46:52 +0800 Subject: [PATCH] =?UTF-8?q?feat(sprint):=20T-loop1d=20=E4=BB=8A=E6=99=9A?= =?UTF-8?q?=E4=BB=BB=E5=8B=99=E2=80=94=E2=80=94=E9=9B=B2=E7=AB=AF=E5=81=9A?= =?UTF-8?q?=20Arcrun#3=20=E6=8E=A7=E5=88=B6=E5=8F=B0=E9=A0=81(=E7=AC=AC?= =?UTF-8?q?=E4=BA=8C=E6=AC=A1=E5=A3=93=E6=B8=AC,=E8=B7=A8=E5=A4=9Arepo)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- system-dev/wiki/cards/decisions/00-INDEX.md | 1 + .../wiki/cards/decisions/零件退役要清三源.md | 47 +++++++++++++++++++ system-dev/wiki/mistakes.md | 32 +++++++++++++ system-dev/wiki/status.md | 12 ++++- 4 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 system-dev/wiki/cards/decisions/零件退役要清三源.md diff --git a/system-dev/wiki/cards/decisions/00-INDEX.md b/system-dev/wiki/cards/decisions/00-INDEX.md index 3c1e513..c681fa3 100644 --- a/system-dev/wiki/cards/decisions/00-INDEX.md +++ b/system-dev/wiki/cards/decisions/00-INDEX.md @@ -11,6 +11,7 @@ - [[薄殼原則-能力長在API]] — CLI/MCP/lib 只暴露，齊的單位是「能力」不是「端點」 - [[薄殼規則晚於實作-MCP漂移是歷史債]] — 為何 MCP/CLI 不一致：紀律 2026-06-07 才補、補前漂移 - [[薄殼防複發-能力對照表加smoke]] — 防死端點假綠：對照清單 + 本機 smoke（非 CI），自驗能攔 +- [[零件退役要清三源]] — 退役/降級零件清示例+parts.ts+（validate是設計）；沒對應 recipe 留 TODO 不硬塞 id（issue #13） ## 串接 / 部署 diff --git a/system-dev/wiki/cards/decisions/零件退役要清三源.md b/system-dev/wiki/cards/decisions/零件退役要清三源.md new file mode 100644 index 0000000..d1f5b94 --- /dev/null +++ b/system-dev/wiki/cards/decisions/零件退役要清三源.md @@ -0,0 +1,47 @@ +--- +tags: [零件架構, 薄殼, 平台原則, 機制說明, 踩坑] +gloss: 退役/降級零件要同步清「AI 搜尋零件的三個源」（示例 yaml + parts.ts 硬編碼清單 + offline validate），只改一處會留殘留誤導下個 CC；沒對應 recipe 時誠實留 TODO 不硬塞語意不符的 canonical_id。 +--- +# 零件退役要清「AI 搜尋零件的三個源」 + +← [[decisions/00-INDEX]] + +**來源**：issue #13（telegram/gmail/sheets/line 從內建零件降級走 recipe、刪 ai_transform_compile/run） +**commit**：caa8e10（步驟1 示例 yaml）、764f657（步驟2 parts.ts） +**最後更新**：2026-06-28 + +## 摘要 +退役或降級一個零件（改成走 recipe、或直接刪）時，**AI/操盤手「能找到這零件」的來源不只一個**。 +只改一處就宣布退役 → 別處殘留會讓下個 CC 或 Haiku 誤判「這零件還在、還能用」（死代碼/殘留＝錯誤環境信號）。 +退役 SOP ＝同步清「AI 搜尋零件的三個源」，外加：沒對應 recipe 時誠實留 TODO，別硬塞語意不符的 canonical_id（假綠）。 + +## 重點 +- **三個源（退役必查）**： + 1. **示例 yaml**——workflow 範例裡的 `component: telegram` 之類。退役時改成 recipe canonical_id（`telegram_send`）。 + 2. **`cli/src/commands/parts.ts` 硬編碼清單**——手寫的「有哪些零件」常駐清單，**必然 stale**，是退役最易漏的源。 + 步驟2 已把 telegram/gmail/sheets/line 改 recipe canonical_id、移除已刪的 ai_transform_compile/run。 + 3. **offline validate**——**這個是設計不是殘留**：offline validate 刻意不連網、跳過遠端查零件， + 所以它「不檢查零件存不存在」是 by design。第三個污染源留 issue，**不當 bug 修**。 +- **gmail 讀取假綠（已避）**：gmail 的**讀取**（`fetch_unread` / `action: list`）**沒有對應 recipe**， + 硬指成 `gmail_send`（寄信 recipe）＝語意不符的假綠。正解＝**留 TODO 待 seed 補 `gmail_list`**，不硬塞。 + 「有個 canonical_id 可填」≠「這個 id 對」。 +- **parts.ts 必 stale**：它是手寫常駐清單，不是從 registry 動態生成 → 任何零件增刪它都不會自動跟上， + 退役 SOP 要把它列成「固定必清項」。 +- **退役 ≠ 宣告**：清殘留是實際動作（改/刪所有源），不是「改完一處說一聲完成」。 + +## 實體 +- **AI 搜尋零件的三個源**（示例 yaml / parts.ts / offline validate）— 操盤手判斷「零件存不存在」的依據來源；退役要逐源處理。 +- **parts.ts 硬編碼清單**（cli/src/commands/parts.ts）— 手寫常駐零件清單，必 stale，退役固定必清項。 +- **offline validate 跳過零件查**（by design）— 不連網驗證刻意不查零件存在性；是設計不是殘留，留 issue。 +- **硬塞 canonical_id 假綠**（gmail 讀取→gmail_send）— 沒對應 recipe 時填語意不符的 id 充數，違 mindset §7。 + +## 關聯 +### 內文知識關係 +- 零件退役 >> 必須清 >> AI 搜尋零件的三個源 +- parts.ts 硬編碼清單 >> 必然 >> stale +- offline validate 跳過零件查 >> 屬於 >> 設計（非殘留） +- 硬塞 canonical_id >> 是 >> 假綠 +- 沒對應 recipe >> 正解是 >> 留 TODO 補 seed +### 卡片關係 +- [[零件退役要清三源]] >> 落實 >> [[工作流是default零件是例外]] +- [[零件退役要清三源]] >> 同類於 >> [[薄殼規則晚於實作-MCP漂移是歷史債]]（都是「常駐清單/規則晚於實作 → 漂移殘留」） diff --git a/system-dev/wiki/mistakes.md b/system-dev/wiki/mistakes.md index 62ca597..0cca1c2 100644 --- a/system-dev/wiki/mistakes.md +++ b/system-dev/wiki/mistakes.md @@ -445,6 +445,36 @@ array-of-tables（`[[x]]`）不用 inline array。改 toml 後用 `wrangler --dr --- +## 22. 零件退役只改一處 → 殘留誤導下個 CC；硬塞 canonical_id 是假綠（2026-06-28，issue #13） + +**背景**：issue #13 收尾零件降級遺留。降級/退役某零件（telegram/gmail/sheets/line 等 +從「內建零件」改成「走 recipe」、ai_transform_compile/run 直接刪）時，**AI 搜尋零件的來源不只一個**， +只改一處 → 別處殘留會讓下個 CC（或 Haiku 操盤手）誤判「這零件還在/還能用」。 + +**錯誤模式 A（殘留誤導）**：以為「示例 yaml 改完就退役乾淨了」。實際 AI 找零件有**三個源**， +退役要三個一起清，否則殘留＝錯誤環境信號（同 [[死代碼是錯誤環境信號]] 精神）： +1. **示例 yaml**（`component: telegram` 之類）— 步驟1 已改成 recipe canonical_id（`telegram_send`）。 +2. **`cli/src/commands/parts.ts` 硬編碼清單** — 步驟2 已清（telegram/gmail/sheets/line 改 recipe canonical_id、 + 移除已刪的 ai_transform_compile/run）。**parts.ts 是手寫常駐清單，必然 stale** → 退役 SOP 要把它列進「必清的源」。 +3. **offline validate**（第三個污染源）— **這個是設計不是殘留**：offline validate 刻意跳過遠端查零件 + （不連網就能驗），所以它「不檢查零件存不存在」是 by design，留 issue 不當 bug 修。 + +**錯誤模式 B（硬塞 canonical_id ＝假綠）**：gmail **讀取**（`fetch_unread` / `action: list`） +**沒有對應 recipe**，把它硬指成 `gmail_send`（寄信 recipe）＝張冠李戴的假綠（mindset §7）。 +正解：**留 TODO 待 seed 補 `gmail_list` recipe**，不硬塞一個語意不符的 canonical_id 充數。 +「有個 canonical_id 可填」≠「這個 canonical_id 對」。 + +**正確做法**： +- 退役零件 → **同步清三源**（示例 / parts.ts / 任何硬編碼清單），別只改一處宣布完成。 +- 沒對應 recipe 時 → 誠實留 TODO + 發 issue 補 seed，**不硬塞語意不符的 id**。 +- 退役 SOP（[[死代碼是錯誤環境信號]] 的姊妹）寫進流程：清殘留 = 清「AI 搜尋零件的所有源」，不只宣告。 + +**通用教訓**：「改完一處＝退役完成」是錯覺；常駐硬編碼清單（parts.ts）必 stale，是退役必查項。 +連帶：這跟 #19「死端點假綠」、#15「假設 v3 route 還在」同類——**陳述「退役/遷移完成」前問「所有引用源都掃過了嗎」**。 +日期：2026-06-28。 + +--- + ## 快速檢查清單（做新功能前） - [ ] 這是工作流還是零件？問「有必要嗎？」 @@ -461,3 +491,5 @@ array-of-tables（`[[x]]`）不用 inline array。改 toml 後用 `wrangler --dr - [ ] 新增/改薄殼工具？grep 確認它打的 server route 真的存在，別假綠（#19）；宣稱對齊前跑 thin-shell-smoke.sh - [ ] 想用 git log 查某檔歷史？先 git check-ignore——gitignored 檔無 git 史，時間靠檔內註記（#20） - [ ] 改 wrangler.toml service binding？用 [[services]] 不用 inline services=[...]（[vars] 後會被吸走）；改完 wrangler --dry-run 驗 binding 真在（#21） +- [ ] 退役/降級某零件？同步清「AI 搜尋零件的三個源」＝示例 yaml + parts.ts 硬編碼清單 + （validate 跳過是設計）；別只改一處宣布完成（#22） +- [ ] 沒對應 recipe？誠實留 TODO + 發 issue 補 seed，別硬塞語意不符的 canonical_id 充數（假綠，#22） diff --git a/system-dev/wiki/status.md b/system-dev/wiki/status.md index b4524e5..4c882ce 100644 --- a/system-dev/wiki/status.md +++ b/system-dev/wiki/status.md @@ -3,7 +3,7 @@ name: status description: 當前進度、進行中 Phase、已知問題、下一步（動態文件，每 session 更新） metadata: type: project - last_updated: 2026-06-24 + last_updated: 2026-06-28 --- # 當前進度（動態） @@ -15,7 +15,15 @@ metadata: ## 📍 當前位置 -> **2026-06-27 本 session（issue #8 地基1 + wiki-init 補骨架）**： +> **2026-06-28 本 session（issue #13 零件退役殘留收尾，步驟1+2 done）**： +> - **issue #13 步驟1（merge caa8e10）**：3 個示例 yaml 的 `component: telegram` → recipe canonical_id `telegram_send`（commit a234201）。 +> - **issue #13 步驟2（merge 764f657）**：清 `cli/src/commands/parts.ts` 降級零件殘留——telegram/gmail/sheets/line 改 recipe canonical_id、移除已刪的 ai_transform_compile/run（commit 225aa9f）。 +> - **關鍵發現①（gmail 假綠避免）**：gmail **讀取**（`fetch_unread` / `action: list`）**無對應 recipe**，硬塞 `gmail_send`（寄信）＝語意不符的假綠 → **留 TODO 待 seed 補 `gmail_list`**，不硬塞。 +> - **關鍵發現②（第三污染源是設計非殘留）**：#13 提的「offline validate 不檢查零件」是 by design（offline 刻意跳過遠端查），**不當 bug 修，留 issue**。 +> - **教訓沉澱**：parts.ts 是手寫常駐清單必 stale → **退役 SOP 要同步清「AI 搜尋零件的三個源」**（示例 yaml / parts.ts / validate）。已記 mistakes #22 + card [[零件退役要清三源]]。 +> - **未 push/merge 由總管統一處理**（本 session 只 wiki-capture）。issue #13 步驟1+2 done；validate 缺口留 issue。 +> +> **2026-06-27 上個 session（issue #8 地基1 + wiki-init 補骨架）**： > - **wiki-init 補骨架**：wiki 已初始化過（push 檔活躍），補了從沒建的 pull 層——`cards/decisions/` 13 張決策原子卡（Haiku 改寫 11+範本 2，含 gloss/實體/typed-edge）、TAXONOMY 換成 arcrun 軸（子系統/形態）、principles 填 13 條、INDEX 真實視圖。raw source 0 異動，無真斷鏈。 > - **issue #8（[地基1] workflow description slot + search_workflow，北極星入口）**：新開 SDD `docs/3-specs/workflow-discovery/`（白名單已加）。leo 拍板 4 點（方案C雙寫/Q2 description 由操盤CC據實生成用戶可改/提示式回填/base通用entry_type filter）+ 方向①（MCP 改打 /webhooks/named）。 > - ✅ **已實作 tsc 全綠**：1.1 `/webhooks/named` 強制 description｜2.2+Q4 KBDB base 通用 entry_type filter（改4處：searchEntries/semanticSearch/route/proxy）｜2.1 部署雙寫 embeddable entry（注意 KBDB 用 metadata_json 字串）｜3.1 cypher `/workflows/search`｜3.2 MCP `u6u_search_workflows`｜4.1 `/workflows/backfill-search-entries`｜1.3b `GET /webhooks/named` 補 description/created_at 欄位。