← 導覽之旅← Guided Tour AIS 系列 · 3 / 3 · 架構稽核AIS Series · 3 / 3 · Arch Audit
★ 技術稽核報告 TECHNICAL AUDIT REPORT ★

插件架構稽核 Plugin Architecture Audit

auto-claude-ideation-suite — 從 v1.0.0（壞的）到 v1.0.1（有效的）的完整技術分析。12 個問題，6 個根本原因，一個確定性修復。 auto-claude-ideation-suite — a complete technical breakdown from v1.0.0 (broken) to v1.0.1 (working). 12 issues, 6 root causes, one deterministic fix.

v1.0.0 → v1.0.1 P0 · 6 個關鍵問題 P0 · 6 CRITICAL ✓ 全部已修復 ✓ ALL RESOLVED commit f9e187c 2026-04-26
12
稽核問題Audit Issues
6
P0 關鍵P0 Critical
4
P1 規範P1 Compliance
2
P2 衛生P2 Hygiene
17
代理（全部修復）Agents (all patched)
4
新增斜線命令New Slash Commands

01修復前後對比Before / After Comparison

稽核識別出的問題分佈在三個嚴重性層級。最嚴重的（P0）直接造成功能靜默失效；P1 違反 Claude Code 插件規範；P2 留下維護債務。 The issues found by the audit fall across three severity levels. The most severe (P0) caused direct, silent functional failures; P1 violated Claude Code plugin spec; P2 left maintenance debt.

v1.0.0 — 損壞狀態 v1.0.0 — Broken State
  • 無 commands/ 資料夾 — 每個已記錄的斜線命令都不存在No commands/ folder — every documented slash command was fictional
  • MCP 伺服器用 npx tsx 啟動 — 需要 dev 環境MCP server started with npx tsx — required dev environment
  • 兩個競爭設定（.mcp.json + package.json）Two competing configurations (.mcp.json + package.json)
  • TypeScript import 用 .ts 後綴 — 編譯後損壞TypeScript imports with .ts suffix — breaks after compilation
  • 17 個代理缺少 YAML frontmatter — 無法按名稱呼叫17 agents missing YAML frontmatter — not addressable by name
  • Manifest 計數錯誤（16 vs 實際 17）Manifest count wrong (claimed 16 vs actual 17)
  • Skill 名稱：TitleCase with spaces（不符合慣例）Skill name: TitleCase with spaces (non-standard)
  • 編譯產物在 .gitignore — 安裝者需自行建置Build artifact in .gitignore — installer must build manually
  • 無 CI — 回歸靜默無聲No CI — regressions go unnoticed
v1.0.1 — 已修復狀態 v1.0.1 — Fixed State
  • 4 個真實命令：/auto-claude-ideation-suite、/ideation、/roadmap、/qa4 real commands: /auto-claude-ideation-suite, /ideation, /roadmap, /qa
  • MCP 伺服器用 node dist/mcp-server.js — 只需 NodeMCP server uses node dist/mcp-server.js — Node only
  • 單一真相來源：.mcp.jsonSingle source of truth: .mcp.json
  • 所有 import 後綴改為 .js — 編譯後正常All import suffixes changed to .js — correct after compilation
  • 17 個代理全部有 YAML frontmatter — 可按名稱呼叫All 17 agents have YAML frontmatter — fully addressable
  • Manifest 正確計數 17 + homepage + repo 欄位Manifest correctly counts 17 + homepage + repo fields
  • Skill 名稱：auto-claude-ideation-suite（kebab-case）Skill name: auto-claude-ideation-suite (kebab-case)
  • dist/ 已提交 — 安裝即用，無需建置dist/ committed — install and run, no build step
  • Mac Mini self-hosted CI — 每次 push 驗證結構 + 建置 + 冒煙Mac Mini self-hosted CI — validates structure + build + smoke on every push

02五層架構圖（修復後）Five-Layer Architecture (Post-Fix)

Claude Code 插件透過五個不同的機制擴展助手。每一層都必須正確連線，功能才能對使用者可見。修復後，所有五層都已連線。 A Claude Code plugin extends the assistant through five distinct mechanisms. Each layer must be wired correctly for the capability to be visible to the user. After the fix, all five layers are wired.

L1 確定性入口點 · commands/ Deterministic Entry · commands/ ← 修復前缺失 ← was missing
/auto-claude-ideation-suite /ideation /roadmap /qa <id> 每次都確定性觸發deterministic, fires every time
↓
L2 機率性補充 · skills/ Probabilistic Supplement · skills/ 名稱修復為 kebab-case name fixed to kebab-case
auto-claude-ideation-suite 9 步驟協定9-step protocol 關鍵字觸發keyword-triggered 補充 L1，不取代supplements L1, not replacing
↓
L3 專家子代理 · agents/ Specialist Sub-Agents · agents/ frontmatter 已新增至全部 17 個 frontmatter added to all 17
performance security code-quality documentation ui-ux roadmap-discovery roadmap-features qa-reviewer qa-fixer qa-orchestrator + 7 個更多 + 7 more
↓
L4 客製工具 · MCP 伺服器 Custom Tools · MCP Server 啟動修復為 node dist/ boot fixed to node dist/
scan_project validate_output merge_ideas get_task_state set_item_status save_insights generate_report list_agents + 2 個更多 + 2 more
↓
L5 插件 Manifest · .claude-plugin/ Plugin Manifest · .claude-plugin/ 計數 + 欄位修復 count + fields fixed
name: auto-claude-ideation-suite version: 1.0.1 agents: 17 homepage: ✓ repository: ✓

03完整問題清單（12 項）Complete Issue Register (12 Items)

# 等級Sev. 問題Issue 影響Impact 修復Fix
01 P0 缺少 commands/ 目錄Missing commands/ 每個已記錄的斜線命令（/auto-claude-ideation-suite、/ideation、/roadmap、/qa）都不存在。使用者呼叫回退到機率性 skill 匹配。 Every documented slash command (/auto-claude-ideation-suite, /ideation, /roadmap, /qa) did not exist. User invocations fell back to probabilistic skill matching. 已新增ADDED
02 P0 MCP 啟動用 npx tsxMCP boot via npx tsx .mcp.json 中的 command 欄位指定 npx tsx mcp-server.ts，需要 node_modules 存在。對非開發者安裝靜默失效。 command field in .mcp.json specified npx tsx mcp-server.ts, requiring node_modules to be present. Silent failure for non-developer installs. 已修復FIXED
03 P0 雙重設定衝突Duplicate config .mcp.json 和 package.json 各自定義 MCP 伺服器。Claude Code 只讀取 .mcp.json；package.json 塊是幽靈設定，製造混亂。 Both .mcp.json and package.json defined the MCP server. Claude Code reads only .mcp.json; the package.json block was a ghost config creating confusion. 已移除REMOVED
04 P0 TypeScript .ts import 後綴TS .ts import suffix 3 個 TypeScript 檔案引用了帶 .ts 後綴的模組，這在開發時有效但編譯後導致執行時 MODULE_NOT_FOUND 錯誤。 3 TypeScript files referenced modules with .ts suffixes, which works at dev time but causes runtime MODULE_NOT_FOUND errors post-compilation. 已修復FIXED
05 P0 Windows 路徑相容性Windows path compat 一個 path helper 使用了在 Windows 上有隱性問題的 Node API。在 path.resolve() 中使用 POSIX 分隔符假設，在 Win32 路徑解析中失效。 A path helper used a Node API with a subtle flaw on Windows. Implicit POSIX separator assumption in path.resolve() call breaks under Win32 path resolution. 已修復FIXED
06 P0 未宣告的 zod 相依Undeclared zod dep zod 在執行時被使用但未在 package.json 的 dependencies 中宣告，只透過傳遞依賴存在。新版本的相依可能移除它。 zod was used at runtime but not declared in package.json dependencies, only present transitively. A dep version bump could remove it. 已宣告DECLARED
07 P1 Manifest 計數不正確Manifest count wrong plugin.json 聲稱 16 個代理，實際上 17 個。 plugin.json claimed 16 agents; there were 17. 已更正CORRECTED
08 P1 缺少 Manifest 欄位Missing manifest fields homepage 和 repository 欄位在每個其他 Claude Code 插件中都存在，但在這裡缺失。 homepage and repository fields present in every other Claude Code plugin, absent here. 已新增ADDED
09 P1 非標準 Skill 名稱Non-standard skill name Skill 名稱為 Auto Claude Ideation Suite（TitleCase + 空格），而慣例是 kebab-case。 Skill named Auto Claude Ideation Suite (TitleCase + spaces); convention is kebab-case. 已重命名RENAMED
10 P1 代理缺少 YAML frontmatterAgents lack YAML frontmatter 17 個代理檔案都沒有 YAML frontmatter（name、description、tools）。在結構上它們只是文字，而非可按名稱呼叫的子代理。 None of the 17 agent files had YAML frontmatter (name, description, tools). Structurally they were text, not sub-agents addressable by name. 已新增ADDED
11 P2 dist/ 在 .gitignore 中dist/ in .gitignore 編譯後的 JavaScript 被排除在 git 之外。任何安裝插件的人在執行前必須先執行 npm run build。 Compiled JavaScript excluded from git. Anyone installing the plugin must run npm run build before it will work. 已提交COMMITTED
12 P2 無持續整合No CI 沒有工作流驗證建置健康、插件結構或冒煙啟動。回歸靜默通過。 No workflow validating build health, plugin structure, or smoke boot. Regressions pass silently. 已新增ADDED

04CI 管道（新增 Mac Mini Self-Hosted）CI Pipeline (New Mac Mini Self-Hosted)

新增的 CI 工作流在每次 push 和 pull request 上執行。它在一個 self-hosted Mac Mini runner 上運行（ARM64 12核心，24 GB），避免了跨平台驗證差異。 The new CI workflow runs on every push and pull request. It targets a self-hosted Mac Mini runner (ARM64 12-core, 24 GB), avoiding cross-platform validation discrepancies.

1
相依性安裝Dependency install
在乾淨狀態下執行 npm ci（不是 npm install）確保鎖定檔案決定版本，不允許靜默升級。 Run npm ci (not npm install) on a clean state to ensure the lockfile determines versions, no silent upgrades allowed.
npm ci
2
TypeScript 編譯TypeScript compile
如果 TypeScript 有類型錯誤或 import 路徑損壞，以非零退出碼失敗。這是 P0 問題的直接迴歸保護。 Fail with non-zero exit code if TypeScript has type errors or broken import paths. This is the direct regression guard against the P0 issues.
npm run build
3
建置產物驗證Build artifact check
斷言所有 6 個預期 JavaScript 檔案存在於 dist/ 下：mcp-server.js、tools.js、scanner.js、validator.js、state.js、utils.js。 Assert all 6 expected JavaScript files exist under dist/: mcp-server.js, tools.js, scanner.js, validator.js, state.js, utils.js.
test -f dist/mcp-server.js && ...
4
MCP 伺服器冒煙啟動MCP server smoke boot
以 timeout 3 啟動編譯後的伺服器，如果它崩潰則失敗（退出碼 1），如果它超時則通過（退出碼 124 = 健康的 stdio 伺服器）。 Start the compiled server with timeout 3, fail if it crashes (exit code 1), pass if it times out (exit code 124 = healthy stdio server).
timeout 3 node dist/mcp-server.js || [ $? -eq 124 ]
5
插件結構驗證Plugin structure validation
驗證：commands/ 有 ≥ 4 個檔案、agents/ 有恰好 17 個、.claude-plugin/plugin.json 存在、每個代理的第 1 行是 ---（YAML frontmatter）。 Assert: commands/ has ≥ 4 files, agents/ has exactly 17, .claude-plugin/plugin.json exists, every agent's line 1 is --- (YAML frontmatter).
ls commands/ | wc -l && head -1 agents/*.md | grep "^---"

05修復提交The Fix Commit

所有 12 個問題的修復都包含在一個原子 commit 中，以保持 git 歷史可讀。 All 12 fixes are contained in a single atomic commit to keep the git history readable. 

commit f9e187c
fix: align plugin to spec — slash commands, agent frontmatter, build pipeline

Changes:
+ commands/auto-claude-ideation-suite.md  (new — master slash command)
+ commands/ideation.md                    (new — /ideation entry)
+ commands/roadmap.md                     (new — /roadmap entry)
+ commands/qa.md                          (new — /qa <item-id> entry)
+ dist/*.js                               (new — committed build artifacts)
+ .github/workflows/ci.yml                (new — Mac Mini self-hosted CI)
  .mcp.json                                (fix — node dist/mcp-server.js)
  package.json                             (removed duplicate mcp config block)
  src/*.ts                                 (fix — .ts → .js import suffixes)
  src/utils.ts                             (fix — Windows path compat)
  package.json                             (fix — declare zod as dependency)
  skills/auto-claude-ideation-suite.md     (fix — rename to kebab-case)
  agents/*.md × 17                         (fix — add YAML frontmatter to all)
  .claude-plugin/plugin.json               (fix — 16→17, +homepage, +repository)
  .gitignore                               (fix — remove dist/ exclusion)

3 files changed (content), 6 files added, 0 files deleted
All CI checks passing on Mac Mini ARM64.

06關鍵原則Key Principles

建造時 When Building
  • 斜線命令是確定性的，skills 是機率性的。每個命名工作流都需要 commands/ 中的一個真實檔案。Slash commands are deterministic, skills are probabilistic. Every named workflow needs a real file in commands/.
  • 設定一個真相來源。如果 .mcp.json 和 package.json 都定義你的伺服器，其中一個是幽靈。One source of truth for config. If both .mcp.json and package.json define your server, one is a ghost.
  • 出貨已編譯的產物。使用者不是開發者。他們不應該執行建置步驟。Ship compiled artifacts. Users are not developers. They should not run a build step.
  • 使用 kebab-case 命名 skills 和命令。它是慣例且讓模糊匹配更可靠。Use kebab-case for skill and command names. It's the convention and makes fuzzy matching more reliable.
偵測時 When Debugging
  • 「偶爾有用」= 兩條路徑，其中一條壞了。 找到兩條路徑，移除損壞的那條。"Sometimes works" = two paths, one is broken. Find the two paths, remove the broken one.
  • 先列出資料夾。最根本的插件問題往往是缺少一個目錄。ls -la plugin/ 比閱讀程式碼更快。List folders first. The most fundamental plugin issues are often a missing directory. ls -la plugin/ is faster than reading code.
  • 將描述與現實比對。文件說 /foo 存在？ls commands/ 來確認。Check docs against reality. Documentation says /foo exists? Run ls commands/ to confirm.
  • 使用者是金絲雀，不是嫌疑人。如果有人說它壞了，它就壞了。The user is the canary, not the suspect. If someone says it's broken, it's broken.
核心洞察 Core Insight

「每次都有效」和「偶爾有效」之間的差距，幾乎完全是一個從未建立的資料夾。修復確定性層（commands/）將插件從完全依賴模型判斷的東西，變成了每次都轉動的旋鈕。 The gap between "works every time" and "sometimes works" was almost entirely a folder that had never been created. Fixing the deterministic layer (commands/) transformed the plugin from something entirely dependent on model judgement into a knob that turns every time.