morrislu-taipei/tigerai-n8n-skill-pack/code2n8n-pipeline

Code2n8n Pipeline — Path B Auto-Pilot Skill

🌐 English | 繁體中文

本 SKILL 是 Code2n8n Path B 的 end-to-end pipeline 自動化規格。當使用者丟一個 MIT GitHub 專案進來、要求自動化完成 Path B 的全套流程（從 Inventory 到上架），AI 必須依本 SKILL 的 12 階段、main/critic 雙 agent 架構執行。

受限 Agent 模式（Portal）

先看宿主有沒有放標記 [PORTAL-RESTRICTED-AGENT-MODE v1]（系統提示或工作階段上下文；規則見 `spec/agent-restricted-mode.md`）。沒有標記：本 Skill 全文照舊。有標記：下列調整優先於本檔其他內容。 這段文字只是提示，真正的強制在宿主的工具白名單；本 Skill 在此模式下的行為是「符合宿主的限制」。

本管線依賴 git、shell、live-roundtrip.mjs、對 n8n 的 import 與 activate，以及 main/critic 雙 agent；受限 Agent 沒有這些能力。因此在受限模式：

• 只支援縮減版：依使用者貼來的內容或宿主唯讀工具讀到的內容，做 Stage 1–3 的分析與 Stage 5 的 workflow JSON 產出。完整的 12 階段請在單機模式（沒有標記）執行，並如實告訴使用者「受限模式下本管線無法完整執行」。不降級成自我審查（§5 第 3 條不變）。
• Stage 4（寫程式與檔案）、Stage 6–9（需要 shell、腳本與 n8n）：不執行；以宿主的靜態檢查工具代替結構檢查，最多 N 輪（宿主設定），並說明 Layer 2 與執行期檢查尚未做。
• Stage 10（Activate to n8n）：停用，不 import、不 activate、不產生 ACTIVATION-LOG.md；寫入由宿主處理，啟用只由 n8n 管理員執行。
• Stage 11（完工報告）：不寫成檔案，不簽 sign-off；§1.6 的字詞規則照舊，不得宣稱「已通過」「安全」「可部署」「已啟用」。
• 憑證：只引用宿主提供的 credentialMap 內的名稱；禁止 STUB- 假憑證與杜撰名稱；缺的憑證寫進 Layer 3「待補憑證」。
• 收尾區塊：資安掃描結果是宿主檢查結果的如實轉述，沒執行就寫「未執行資安掃描：<原因>」。

1. 啟動條件

自動觸發 — 任一情境即啟動，不需使用者特地說 SKILL 名字：

(A) 使用者貼 GitHub repo URL（最常見入口）：

• 訊息含 github.com/<owner>/<repo> 或 https://github.com/... 並表達「做 / 跑 / 上架 / 接到 n8n」任一意圖
• 即便沒明說「Code2n8n」三個字 — 只要 GitHub URL + n8n / workflow 同時出現，自動套用本 SKILL

(B) 啟動命令觸發詞（任一即觸發）：

(C) 隱式觸發（須主動套用）：

• 使用者要求「驗證完整、做完上架、出報告」一條龍。
• 使用者引用 v0.28.0 SECURITY-REVIEW 模板 + v0.28.1 A2A directive，要求「未來案例都這樣跑」。
• 使用者使用 connector / plugin / sub-agent 三件套詞彙描述 Path B。

反向條件（不啟動）：

• 僅要求「規劃」/「估算」/「partition 建議」 — 改套 code-to-workflow（本 SKILL 是 pipeline，不是 plan）。
• 使用者明確要求只做部分階段 — 改用對應 SKILL：n8n-security-governance（只審查）、sticky-note-to-workflow（只生 workflow）。
• 非 MIT / 授權不明 — 立刻中止並回報 License gate failed，不啟動後續階段。

1.5 🚨 語言鎖定規則（所有 artefact 必遵）

規則：判定使用者啟動本 SKILL 時用的主要語言，然後所有後續 prose artefact 都用同一語言寫。

判定方式：

• 啟動該則訊息的主要語句語言 = pipeline 語言
• 若該訊息混語（如「跑 Code2n8n 這個 repo」中英混）→ 看主動詞（動詞 / 命令動作）的語言為準
• 啟動訊息為英文 → pipeline 語言 = English
• 啟動訊息為中文 → pipeline 語言 = 繁體中文（除非使用者明確用簡體）
• 其他語言（ja / ko / fr / de / es / vi / th / ms / id） → pipeline 語言 = 該語言

必須跟著語言走的 artefact：

不受規則約束（保持英文 / 國際標準）：

反例（禁止）：

• ❌ 使用者用英文啟動，但 sticky note 寫中文 → 違反規則
• ❌ 使用者用中文啟動，但 sticky note 寫英文 → 違反規則
• ❌ 使用者用日文啟動，但 sticky note 寫中文「以下是說明…」 → 違反規則

為何這條規則重要：sticky note 是 workflow 內給維護者讀的 prose。若使用者用中文發起 Code2n8n、結果產出英文 sticky notes，等於把 prose 交付給錯誤的讀者群 — 後續維護的人類 / AI 都會卡在語言錯配。語言一致 = 交付一致。

1.5.1 ⚠️ 沒有例外 — 包括 Pack 官方案例 workflow

v0.32.0 修訂紀錄：本節之前曾被誤寫成「案例 workflow 必須雙語」的例外條款。使用者明確反駁：「以後通則就是 — 跟啟動語言一致」。無例外。

即使是 ship 到 examples/<case>/workflows/ 的長期案例資產，sticky note 仍只用啟動語言。不要為了「兩個讀者群」雙語化 — 兩個讀者群應該透過 README / docs 而非單一 sticky note 內塞雙語。

v0.32.0 的 6 個 einvoice sticky notes 目前保留英文 + 中文兩段僅因該批次先寫了英文、使用者選擇「將錯就錯不殺掉」— 是 one-off 的歷史殘留，不是新規範。下一個案例（或這 6 個 sticky note 下一次大改）必須回到單語規則。

Critic enforcement：Stage 5（generate workflows）與 Stage 11（completion report）critic gate 必含「sticky-note 語言 ↔ 啟動語言」一致性檢查。不一致 → VETO。雙語 sticky note 亦違規（除非命中 v0.32.0 einvoice 那批歷史殘留豁免清單）。

1.5.2 🏷️ n8n 上架命名規則（加入於 v0.32.0）

每次 import workflow 到 n8n（含本地 localhost:5678）時，workflow name 必須符合以下格式：

[Claude #N v0.X.Y YYYY-MM-DD] <workflow-name>

範例：

• [Claude #1 v0.32.0 2026-06-19] einvoice-issue-from-order
• [Claude #4 v0.32.0 2026-06-19] einvoice-daily-reconcile (sim)

各欄位：

同時：

• Tag 仍為 claude-import-YYYY-MM-DD（不變）
• 該批次的 #1、#2、...、#N 必須連續且對應 import 順序

Critic enforcement：Stage 10 critic gate 必含命名規則檢查；任一 workflow name 不符合此格式 → VETO 回 Stage 10。

1.6 🚨 Lexical schema-before-claim rule（最強制條款 — 加入於 v0.30.3）

Why this section exists: v0.27.0 → v0.30.1 累積了 11 種語言 A2A directive、12 階段 SKILL、main/critic 雙 agent 架構、§10 V&V two-layer gate — 全部規範「不可宣稱驗證除非 evidence 在場」。然後 v0.30.2 修補 SEC-014/015/016 時，implementing AI 還是直接 scanner + roundtrip 就準備推 v0.30.2 為「修好」，差點再犯 v0.27.0 同一個錯。只因使用者推回「能不能跟我 n8n 真跑」smoke 才真的做。

結論：寫 directive ≠ 遵守 directive。前面所有規定都是 behavioural rule（要求 AI 行為符合 spec），AI 在 token 預算 / 上下文壓力 / 「看起來合理」的訊號下仍會繞過。本節新增一個 lexical rule（純文字位置規則）— 要不就有、要不就沒有，無法用判斷繞。

Rule

任何訊息（commit message、release notes、README、sticky note、CHANGELOG、回應 user、SECURITY-REVIEW、SKILL artefact）裡，emit 下列受限字眼之前，必須在同一條訊息更早的位置先 emit 完整的 evidence schema（依 A2A directive 格式）：

受限字眼（任一語言觸發限制）： validated · 驗證 / 驗證通過 / 已驗證 · 検証済み · 검증됨 · validé · validiert · validado · đã xác thực · ผ่านการตรวจสอบ · disahkan · tervalidasi · tested · 已測試 · テスト済み · 테스트됨 · testé · getestet · probado · đã test · ทดสอบแล้ว · diuji · X/X ok · 全綠 · 全件 OK · 전부 통과 · tout passe · alles grün · todo en verde · tất cả xanh · ผ่านทั้งหมด · semua hijau · production-ready · 可上線 · 正式可用 · 本番対応 · 운영 가능 · prêt pour la production · produktionsreif · listo para producción · sẵn sàng production · พร้อม production · sedia untuk pengeluaran · siap produksi

Evidence schema（強制格式，照搬 A2A directive）

## V&V evidence — gate v1 (this AI ran the gate)
 
### Layer 1 (structural)
- JSON parse: PASS / FAIL (N files)
- security-scan.mjs: <count> error / <count> warning  (warnings explained: yes / no)
- live-roundtrip.mjs: <X>/<Y> ok  (tag: <tag>)
 
### Layer 2 (runtime)
- npm install: PASS / FAIL  (`<one-line summary>`)
- npm audit (high+): PASS / FAIL  (<count> vulnerabilities)
- tsc --noEmit: PASS / FAIL  (<count> errors)
- /healthz 200: PASS / FAIL
- Unauthenticated /v1/* → 401: PASS / FAIL
- Negative test 1 (body limit): PASS / FAIL
- Negative test 2 (prototype dispatch): PASS / FAIL
- Negative test 3 (unknown enum): PASS / FAIL
- Workflow runtime contract (per-pattern): PASS / FAIL
- Cross-document parity: PASS / FAIL
- End-to-end runtime smoke: PASS / PENDING / FAIL  (tracked-as: <version>)

三條子規則

1. Layer 2.E 為 PENDING 時的 fallback：end-to-end smoke 是 PENDING → 只能說「Layer 1 + 2.A + 2.B PASS；2.E PENDING tracked-as v0.X.Y」。不能說「validated / tested」。
2. 不可省略：訊息中如果有受限字眼但沒 evidence schema → 該訊息整段重寫（不是補一段 schema 在後面，是訊息違規必須撤回重發）。
3. 不可改換用詞：用「應該可以」「看起來 OK」「跑通了」「成功了」「就 OK 了」等弱化詞或正面斷言繞過此規則，仍違規 — 任何暗示「已驗證」狀態的詞彙都受限。

Critic enforcement

Critic agent 在 Stage 11（completion report）以及任何 main agent 對外輸出（commit message draft、release notes draft、README claim、回 user 訊息）前必須跑 lexical scan：

• regex 掃描受限字眼
• 命中則往前找 evidence schema block
• 找不到 → VETO，要求 main 改寫該訊息

這條 critic check 比 §1.5 語言鎖更容易自動化（純 regex），critic agent 應優先跑這條。

為什麼 lexical 而不是 behavioural

Behavioural rule（「請判斷有沒有 evidence」）依賴 AI 的判斷力 — 在壓力下會被「我覺得這次足夠」掩蓋。Lexical rule（「字串 A 出現前字串 B 必須先出現」）不依賴判斷 — 要不就有、要不就沒有、grep 一秒鐘抓得到。這就是為什麼 SEC-014/015/016 之後加這條 — 防的是 AI 自己對自己的判斷力過度信任。

關聯 reflection：`examples/einvoice-n8n/REFLECTION.md` 的 2026-06-19 addendum 詳述為何加這條。

1.7 🧪 Twin-node test injection pattern（workflow 設計強制條款 — 加入於 v0.32.0）

Why this section exists: v0.27.0 → v0.31.0 期間，凡是要對 workflow 跑 runtime smoke 都要做兩個步驟之一：(a) 在 import 時 on-the-fly patch JSON（把 Google Sheets read 節點替換成 Code node 塞假資料），或 (b) 等真實 Sheet credential / 真實 Slack credential 才能跑。(a) 把 repo workflow JSON 跟「實際被 import 進 n8n 的版本」分裂、難對齊；(b) 把 runtime smoke 卡在外部依賴。

v0.32.0 起的設計約定：所有從外部「讀」的節點，workflow 設計時就並列 production 節點 + test 節點。runtime smoke 不需要 patch JSON、不需要外部 credential — toggle disable flag 即可。

Rule

對每個 workflow 內從外部讀取的節點（不限 Google Sheets read、Database read、HTTP GET fetch、Read Binary File、Webhook payload 解析等等），workflow JSON 設計時必須並列兩個節點：

兩者output 都接到同一個下游節點（在 connections{} 內兩個 entry 都指向同一個 target）。

n8n runtime 行為：node disabled 時不執行、output 被略過 — 所以永遠只有一個 active 的資料來源。

切換方式

平常（production mode）：
  Read Audit                  → disabled=false → 真讀 Sheet
  [TEST] Read Audit Code node → disabled=true  → 不執行
 
Runtime smoke / 沒外部 credential：
  Read Audit                  → disabled=true  → 不執行
  [TEST] Read Audit Code node → disabled=false → 回假資料

切換 = 改兩個 disabled flag、不動 workflow 結構、不動下游邏輯。

不適用對象（寫入節點直接 disable 即可）

• Google Sheets append / update / delete
• Slack chat.postMessage / Slack message update
• Email send
• HTTP POST/PUT/PATCH/DELETE 對外部資源
• Database write / DELETE

寫入節點要驗的是「workflow 有沒有走到 trigger 寫入這條路徑」，不是「寫入的內容對不對」。disable 它，看下游有沒有走到該分支，足夠。

Test Code node 的標準形狀

{
  "parameters": {
    "mode": "runOnceForAllItems",
    "language": "javaScript",
    "jsCode": "// [TEST] Hardcoded fake data for runtime smoke without external dependency.\n// Toggle this node's disabled flag to OFF and the sibling production node's disabled flag to ON to switch back to production.\nreturn [\n  { json: { /* fake row 1 fields */ } },\n  { json: { /* fake row 2 fields */ } }\n];"
  },
  "id": "test-<short-name>",
  "name": "[TEST] <production node name>",
  "type": "n8n-nodes-base.code",
  "typeVersion": 2,
  "position": [<x offset>, <y offset>],
  "disabled": true
}

注意：

• jsCode 含註解說明這是 test injection、怎麼切換
• 假資料結構必須跟 production 節點的真實 output schema 一致 — 包含欄位名、型別、巢狀深度
• disabled: true 是預設狀態

Critic enforcement

Stage 5（generate workflows）critic gate 必含下列檢查：

1. 對每個從外部讀取的節點，workflow 必須有對應的 [TEST] <名稱> Code node sibling
2. 兩個 sibling 的 output 在 connections{} 內必須都指向同一個下游
3. Production 節點預設 disabled: false；test 節點預設 disabled: true
4. Test 節點的 jsCode 必須含註解說明這是 test injection
5. Test 節點的假資料 schema 必須能被下游邏輯正確消費（這條由 runtime smoke 驗，不過用靜態 schema-match 也能做粗略檢查）

任一不過 → VETO 回 Stage 5。

與 §1.6 的關係

§1.6 lexical schema-before-claim rule 防的是「沒做就說做完」。§1.7 twin-node pattern 防的是「想做也做不了」 — 沒外部 credential 就沒辦法跑 runtime smoke、進而沒 evidence 可以 emit、進而連說的資格都沒有。Twin-node 讓 runtime smoke 永遠可以跑，不被外部 credential 卡住。

Worked example

v0.32.0 起 einvoice-n8n 案例的 einvoice-daily-reconcile.workflow.json 與 einvoice-monthly-audit-export.workflow.json 會 ship 雙節點版本：Read Audit（Google Sheets，預設 active）+ [TEST] Read Audit（Code node 塞 3-5 筆假 audit row，預設 disabled）。操作者要跑 runtime smoke 時 toggle 兩個 disabled flag 即可，不需要改 workflow JSON、不需要 Google Sheets credential。

1.8 🛡️ 外部依賴 ingestion 規則（加入於 v0.36.0）