For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/agents.md (or send Accept: text/markdown).
用编码代理构建
把任务交给编码代理：它要读的文件、可直接粘贴的提示词库、无人值守安装，以及让你始终掌控的审查方式。
初学者演练
先决条件：读完下面两篇初学者指南，完成 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. 发布、部署和付费提供商调用永远不属于任务提示词的一部分。把它们留作你明确批准的独立步骤。
你的代理要读的文件
存储库附带一小摞专为代理而写的文件，不只给人看。你永远不需要手工粘贴这些上下文——把代理指向 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——它驱动下文介绍的无人值守安装。
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 存储库里。
代理如何在会话之间记忆
代理在会话之间没有记忆——.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 退回去——你点出失败的检查时，代理修自己的活最快。对于它本不该擅自尝试的事，明确说一次就够；此后整个会话边界都成立。
- 它声称跑过的测试真的跑了——要命令和输出，而不是结论。
- 机密仍只在服务端——新内容里没有
NEXT_PUBLIC_或EXPO_PUBLIC_前缀，也没有密钥被打印进报告或提交。 - 每一次用户数据的读写都保持
workspaceId作用域——没有任何查询信任浏览器发来的 id。 - 每个被改文件的
.ai/镜像随代码一起更新。 - 发布、部署和付费提供商调用仍是你批准的独立步骤——代理从未自行合并、推送或部署。
- 某一步失败两次时，它停下来报告失败的命令，而不是绕过去自行发挥。
如果你想继续完成设置，可以阅读《创建外部账户》。