> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 用編碼代理構建

把任務交給編碼代理：它讀取的檔案、附帶的技能，以及讓您保持掌控的審查。

## 初學者演練

先決條件：閱讀下面兩篇入門指南並完成 Desktop 本地安裝。編碼代理是一種 AI 工具——Cursor、Claude Code、Devin 或類似助手——它讀取您的專案、編輯檔案並執行命令。本頁內容適用於您使用的任意一種。

速查術語：提示詞（prompt）是你粘給代理的指令文本。diff 是它提出的檔案變更清單。儲存庫根目錄是包含 package.json 的最頂層資料夾——代理應始終從這裡開始。

1. 在儲存庫根目錄開啟 `.agents/skills/`，複製與您任務最接近的技能——`add-a-desktop-capability` 是不錯的第一選擇。

2. 把它貼上給代理並描述您的改動，然後加一行：在動程式碼之前先讀 `llms.txt`，再讀 `AGENTS.md`，再讀 `.ai/PROJECT_CONTEXT.md`。

3. 讓代理在動手前先列出它將改動的檔案和將執行的檢查。完成後審查 diff——你是在批准對產品的真實改動。

4. 釋出、安裝包發行和付費提供商呼叫永遠不屬於任務提示詞。把它們保留為您明確批准的單獨步驟。

[開始之前](https://supastack.dev/zh-tw/docs/desktop/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/desktop/terminal-basics.md)

[桌面本地設定](https://supastack.dev/zh-tw/docs/desktop/ship-in-5-minutes.md)


## 你的代理要讀的檔案

儲存庫附帶一小摞專為代理而寫的檔案，不只給人看。你永遠不需要手工貼上這些上下文——把代理指向 `llms.txt`，剩下的它自己會讀。

閱讀順序很重要：`llms.txt` 是地圖，`AGENTS.md` 劃定邊界，`.ai/PROJECT_CONTEXT.md` 承載此前會話的經驗。跳過邊界的代理會寫出你無法交付的程式碼。

| 檔案 | 它為代理提供什麼 |
|---|---|
| `llms.txt` | 儲存庫入口地圖，生成時只列出此 checkout 實際附帶的內容 |
| `AGENTS.md` | 不可協商的邊界：在您批准前只做本地工作，外殼絕不另起產品介面 |
| `.ai/PROJECT_CONTEXT.md` | 跨會話記憶——最近改了什麼、為什麼；改動程式碼前必讀 |
| `.ai/` 映象檔案 | 重要檔案旁配套的 .ai/<path>.md 筆記，記錄每個檔案的決策與未完成線索 |
| `.agents/skills/` | 為代理編寫的任務手冊——即下面列出的五個桌面技能 |
| `docs/agent-security.md` | 驗收清單——認證、工作區與許可權檢查，以及脫敏日誌 |
| `docs/desktop-updates.md` | 更新通道手冊——簽名金鑰、端點和釋出通道 |
| `.env.example` | 完整的環境變數清單——代理絕不會編造此檔案中不存在的變數名 |


## 附帶的技能

`.agents/skills/` 下的每個檔案都是一份完整的簡報：把它貼上給代理或讓代理自行閱讀，套件的規則會隨之傳遞——產品介面留在 web 應用中，只有作業系統行為進入 Rust。

可貼上的 `prompts/` 庫只在 Web 儲存庫中附帶；此 checkout 改為附帶技能。若要無人值守地完成安裝，請使用 agent-setup 指南中的現成提示詞。

[讓代理執行安裝](https://supastack.dev/zh-tw/docs/desktop/agent-setup.md)

- `add-a-desktop-capability`——視窗、托盤、快捷鍵、更新或構建改動
- `adding-a-dependency`——安全地新增、升級或移動 npm 依賴
- `reviewing-a-pr`——審查 diff 的正確性、工作區隔離和金鑰
- `upgrading-from-upstream`——把更新版本的套件拉入您的外殼
- `verify-changes`——在交接前選擇並執行正確的檢查


## 代理如何在會話之間記憶

代理在會話之間沒有記憶——`.ai/` 資料夾就是記憶。`.ai/PROJECT_CONTEXT.md` 記錄最近的改動及原因。旁邊的映象檔案，如 `.ai/apps/desktop/src-tauri/src/lib.md`，解釋了 `apps/desktop/src-tauri/src/lib.rs` 背後單憑程式碼看不出的決策。

契約很簡單：改檔案前先讀它的映象，改動落地時更新映象。Open Threads 條目記錄未完成的工作，讓下次會話接著做而不是從頭再來。過期的映象比沒有更糟——審查代理的 diff 時，檢查被改檔案的映象是否隨之更新。


## 誠實地審查代理的工作

完成的任務要看證據而不是總結。在保留代理的工作成果前，用 `docs/agent-security.md` 檢查部署的方式來檢查它：

哪裡不對就把 diff 退回去——你點出失敗的檢查時，代理修自己的活最快。對於它本不該擅自嘗試的事，明確說一次就夠；此後整個會話邊界都成立。

[驗證關卡與測試套件](https://supastack.dev/zh-tw/docs/desktop/testing.md)

- 它執行了它所聲稱的檢查——cargo test、cargo check 或釋出預檢——請要求看命令和它的輸出，而不是結論。
- 金鑰保持僅在伺服器端——沒有簽名金鑰或證書被列印到報告或提交中，外殼也仍然不含任何提供商憑據。
- 產品行為留在 web 應用中——diff 沒有新增用 Rust 實現的並行介面、認證或聊天邏輯。
- 每個被改檔案的 `.ai/` 映象隨程式碼一起更新。
- 釋出、安裝包發行和付費提供商呼叫保持為您批准的單獨步驟——代理絕不會自行合併、推送或發行。
- 某一步失敗兩次時，它停下來報告失敗的命令，而不是繞過去自行發揮。


如果你想繼續完成設定，可以閱讀《[建立桌面端釋出賬戶](https://supastack.dev/zh-tw/docs/desktop/external-accounts.md)》。


## 下一篇

[建立桌面端釋出賬戶](https://supastack.dev/zh-tw/docs/desktop/external-accounts.md)