AI 代理／自動化協作指南

本文件給 AI 編碼代理與 自動化流程 使用：如何在儲存庫內安全地修改、測試與回報，而不破壞擴充與 MCP 之間的契約。終端使用者請讀 README.md；架構細節請讀 PROJECT.md。

Git 與使用者同意（強制）

• 未經使用者明示同意，不得執行 git commit、git push、git push --force／--force-with-lease、改寫遠端歷史、git tag 推送，或任何等同「幫使用者擅自提交／發佈」的操作。
• 代理應以修改檔案、跑測試／建置、建議 commit 訊息與指令為主；若使用者要你代為提交，必須在對話中確認過（或使用者已給出當次明確授權）。
• 當使用者明確指定要把變更落在 main（例如說「上傳到 main／都在 main」）時，在取得同意後應優先將變更直接推進到 main（快進/重整以避免不必要的 merge commit），並在必要時關閉/刪除暫存分支與 PR。
• 例外的僅限：使用者自己設定且非代理操作的 CI／bot（與本條無關）。

指引原則

1. 單一事實來源：IPC 檔名、語意與 MESSENGER_DATA_DIR 行為以 PROJECT.md（流程章節與「資料夾裡的檔案」速查表）與程式碼為準；修改時同步更新 PROJECT.md 與相關型別（src/types/ipc-json.d.ts、mcp-server/index.ts）。
2. 小步提交：優先最小可行 diff；避免與議題無關的重構、大規模格式化。
3. 建置驗證：變更後在儲存庫根目錄執行 bun run compile；若動到打包或 package.json，執行 bun run package 確認可產出 .vsix。

環境與指令

套件管理器與版本見 package.json 的 packageManager 欄位。

修改邊界（常見陷阱）

• mcp-config.ts 與 mcp-server/index.ts：SERVER_KEY／MCP_DISPLAY_NAME／mcp.json 鍵名必須一致。
• Webview：UI 在 src/webview/main.ts；HTML 模板與 CSP／nonce 在擴充載入邏輯中。新 DOM id 需與 TS 中的選取器同步。
• 佇列與 XSS：側欄輸出視為不可信資料，維持既有的跳脫／安全插入模式。
• 授權：本專案為 AGPL-3.0；勿引入與其不相容之依賴而不標註。

透過本專案 MCP 與使用者協作時

當 Cursor 已載入 mcp-cursor-message MCP 伺服器且使用者依賴側欄佇列時：

• 每輪對使用者回覆後，應呼叫工具 check_messages（可附 reply 摘要），以利外掛與下一則佇列訊息銜接。
• 需阻斷式多選／問答時使用 ask_question；長步驟可穿插 send_progress。
• 建議預設策略：
  • 當任務會分成兩個以上步驟（例如「先分析、再修、再驗證」）時，在每個關鍵步驟完成後呼叫一次 send_progress，簡要說明已完成事項、目前狀態與下一步。
  • 當指令存在多種合理解讀，或需要使用者在幾個策略／風險取捨之間做決策時，優先呼叫 ask_question 讓使用者選擇，而不是自行假設。
• 具體參數 schema 以執行中 MCP 伺服器註冊為準（開發時可對照 mcps/.../tools/*.json 描述檔，若本機有同步產生）。

文件與 PR

• 使用者可見行為變更：更新 README.md。
• 架構／IPC／程序圖變更：更新 PROJECT.md。
• PR 描述請說明行為影響（擴充、MCP、或僅 CI／文件），無需贅字。

版本與發佈（Semantic Versioning）

package.json 的 version 採 SemVer MAJOR.MINOR.PATCH（例：9.0.0）。發 GitHub Release／打 tag 前，tag 名稱須與此版號一致（例：v9.0.1 對應 9.0.1），見 .github/workflows/package.yml。

發佈前檢查：bun run package 成功；若動到 IPC／工具，已更新 PROJECT.md 與相關型別，並在 Release note 註明升級提示。

參考連結

• README.md — 安裝與使用
• PROJECT.md — 運作流程與 IPC 速查
• esbuild.config.mjs — 建置進入點