> ## 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

# 用編碼代理構建

把任務交給編碼代理：它要讀的檔案、可直接貼上的提示詞庫、無人值守安裝，以及讓你始終掌控的審查方式。

## 初學者演練

先決條件：讀完下面兩篇初學者指南，完成 Web 本地安裝，並在編輯器中以根目錄開啟本儲存庫。編碼代理是一種 AI 工具——Cursor、Claude Code、Devin 或類似助手——它能讀你的專案、改檔案、跑命令。本頁所有內容適用於你使用的任何一個。

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

1. 開啟儲存庫根目錄的 `prompts/` 資料夾，複製最接近你任務的提示詞。`new-landing-page.md` 是個不錯的第一次嘗試。

2. 把它粘給你的代理並填好 `<placeholders>`：你要的路由、頁面或介面該做什麼、誰可以使用、成功長什麼樣。然後加一行：改動程式碼前，先讀 `llms.txt`，再讀 `AGENTS.md`，再讀 `.ai/PROJECT_CONTEXT.md`。

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

4. 釋出、部署和付費提供商呼叫永遠不屬於任務提示詞的一部分。把它們留作你明確批准的獨立步驟。

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

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

[Web 本地安裝](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)


## 你的代理要讀的檔案

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

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

| 檔案 | 它為代理提供什麼 |
|---|---|
| `llms.txt` | 倉庫入口地圖——所有值得一讀的檔案加上安全協議，按閱讀順序排列 |
| `AGENTS.md` | 不可協商的邊界：除非你批准更多，否則只做本地工作、workspaceId 作用域限定、金鑰只在服務端 |
| `.ai/PROJECT_CONTEXT.md` | 跨會話記憶——最近改了什麼、為什麼；改動程式碼前必讀 |
| `.ai/` 映象檔案 | 重要檔案旁配套的 .ai/<path>.md 筆記，記錄每個檔案的決策與未完成線索 |
| `docs/agent-setup.md` | 無人值守執行手冊——安裝、遷移和部署各階段，每個階段後都有驗證檢查點 |
| `prompts/` | 針對使用者最常交辦任務的可貼上提示詞 |
| `docs/agent-security.md` | 驗收清單——身份驗證、工作區與 RLS 檢查、脫敏日誌、部署證據 |
| `.env.example` | 完整的環境變數清單——代理絕不會編造此檔案中不存在的變數名 |


## 提示詞庫

`prompts/README.md` 是索引。每個檔案都是一份完整簡報：貼上它、填好 `<placeholders>`，套件的規則——用設計令牌而非硬編碼顏色、用套件區塊而非自創模式——會隨之一起生效。

從零到執行的路徑請改粘 `prompts/agent-setup.md`——它驅動下文介紹的無人值守安裝。

[讓代理替你跑安裝](https://supastack.dev/zh-tw/docs/web/agent-setup.md)

- `agent-setup.md`——用代理把套件搭起來並部署
- `pick-a-style.md`——為整個產品套用一種設計風格
- `new-landing-page.md`——用套件區塊搭出一個營銷頁面
- `new-app-screen.md`——在工作區應用外殼裡新增一個介面
- `restyle-product.md`——把已有頁面換到套件令牌上重新做主視覺
- `ui-audit.md`——對某個路由執行視覺與無障礙審計


## 讓代理安裝和部署

這套套件很大程度上能自我安裝。貼上 `prompts/agent-setup.md` 會讓代理逐階段執行 `docs/agent-setup.md`——隨附的執行手冊：預檢、環境檔案、安裝、啟動資料庫、遷移、啟動應用，以及可選的 VPS 部署。每個階段後它都執行該階段的驗證檢查點，並彙報真實輸出而不是口頭結論。

兩個助手保證這條路安全。`scripts/setup-env.mjs` 從 `.env.example` 引導生成環境檔案：只建立缺失的檔案、只生成缺失或佔位的機密，`--check` 模式只校驗不寫入。`docker-compose.dev.yml` 是完全容器化的開發環境——Postgres 加一個 Node 22 開發容器——因此代理不需要你的計算機上裝有 Node.js。

你收到的是哪個儲存庫在這裡很關鍵。Web 儲存庫和 All Platforms monorepo 附帶執行手冊、compose 檔案、`scripts/setup-env.mjs` 和 `prompts/`。獨立的 Mobile 和 Desktop 儲存庫附帶限定範圍的 `llms.txt`、`AGENTS.md`、`.ai/` 映象檔案以及包括 `docs/agent-security.md` 在內的精選檔案——但沒有安裝執行手冊和 compose 檔案，因為這些應用要連的後端住在 Web 儲存庫裡。

[走一遍代理驅動的安裝](https://supastack.dev/zh-tw/docs/web/agent-setup.md)


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

代理在會話之間沒有記憶——`.ai/` 資料夾就是記憶。`.ai/PROJECT_CONTEXT.md` 記錄最近改了什麼、為什麼。在它旁邊，像 `.ai/apps/web/src/reports.md` 這樣的映象檔案解釋 `apps/web/src/reports.ts` 背後那些僅憑程式碼看不出來的決策。

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


## 執行中應用自帶的代理介面

你部署的產品也會回應代理——這些端點存在於執行中的應用上，而不只是儲存庫裡。

- `GET /llms.txt`——應用提供自己的 llmstxt.org 索引：指南、公開頁面和公開端點，均帶絕對 URL。
- `POST /api/mcp`——暴露應用工具的無狀態 MCP 端點。只接受 `sk_` API key 作為 bearer token——瀏覽器 cookie 會話一律不適用。在 Settings → Developers 下建立金鑰。
- `GET /api/v1/openapi`——公開 REST API 的 OpenAPI 規範，供客戶端生成器和代理工具使用。
- `GET /api/health`——負載均衡器和可用性檢查呼叫的存活與依賴探針；它只報告提供商配置型別，絕不報告機密。
- `/status`——以人類可讀頁面報告各子系統的健康狀況。


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

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

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

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

- 它聲稱跑過的測試真的跑了——要命令和輸出，而不是結論。
- 機密仍只在服務端——新內容裡沒有 `NEXT_PUBLIC_` 或 `EXPO_PUBLIC_` 字首，也沒有金鑰被列印進報告或提交。
- 每一次使用者資料的讀寫都保持 `workspaceId` 作用域——沒有任何查詢信任瀏覽器發來的 id。
- 每個被改檔案的 `.ai/` 映象隨程式碼一起更新。
- 釋出、部署和付費提供商呼叫仍是你批准的獨立步驟——代理從未自行合併、推送或部署。
- 某一步失敗兩次時，它停下來報告失敗的命令，而不是繞過去自行發揮。


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


## 下一篇

[建立外部賬戶](https://supastack.dev/zh-tw/docs/web/external-accounts.md)