> ## 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/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[Web 本地安装](https://supastack.dev/zh/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/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/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/docs/web/testing.md)

- 它声称跑过的测试真的跑了——要命令和输出，而不是结论。
- 机密仍只在服务端——新内容里没有 `NEXT_PUBLIC_` 或 `EXPO_PUBLIC_` 前缀，也没有密钥被打印进报告或提交。
- 每一次用户数据的读写都保持 `workspaceId` 作用域——没有任何查询信任浏览器发来的 id。
- 每个被改文件的 `.ai/` 镜像随代码一起更新。
- 发布、部署和付费提供商调用仍是你批准的独立步骤——代理从未自行合并、推送或部署。
- 某一步失败两次时，它停下来报告失败的命令，而不是绕过去自行发挥。


如果你想继续完成设置，可以阅读《[创建外部账户](https://supastack.dev/zh/docs/web/external-accounts.md)》。


## 下一篇

[创建外部账户](https://supastack.dev/zh/docs/web/external-accounts.md)