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

# 用编码代理构建

把任务交给编码代理：它读取的文件、附带的技能，以及让您保持掌控的审查。

## 初学者演练

先决条件：阅读下面两篇入门指南并完成 Mobile 本地安装。编码代理是一种 AI 工具——Cursor、Claude Code、Devin 或类似助手——它读取您的项目、编辑文件并运行命令。本页内容适用于您使用的任意一种。

速查术语：提示词（prompt）是你粘给代理的指令文本。diff 是它提出的文件变更清单。存储库根目录是包含 package.json 的最顶层文件夹——代理应始终从这里开始。

1. 在存储库根目录打开 `.agents/skills/`，复制与您任务最接近的技能——`add-a-mobile-screen` 是不错的第一选择。

2. 把它粘贴给代理并描述您的改动，然后加一行：在动代码之前先读 `llms.txt`，再读 `AGENTS.md`，再读 `.ai/PROJECT_CONTEXT.md`。

3. 让代理在动手前先列出它将改动的文件和将运行的检查。完成后审查 diff——你是在批准对产品的真实改动。

4. 发布、提交商店和付费提供商调用永远不属于任务提示词。把它们保留为您明确批准的单独步骤。

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

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

[手机本地设置](https://supastack.dev/zh/docs/mobile/ship-in-5-minutes.md)


## 你的代理要读的文件

存储库附带一小摞专为代理而写的文件，不只给人看。你永远不需要手工粘贴这些上下文——把代理指向 `llms.txt`，剩下的它自己会读。

阅读顺序很重要：`llms.txt` 是地图，`AGENTS.md` 划定边界，`.ai/PROJECT_CONTEXT.md` 承载此前会话的经验。跳过边界的代理会写出你无法交付的代码。

| 文件 | 它为代理提供什么 |
|---|---|
| `llms.txt` | 存储库入口地图，生成时只列出此 checkout 实际附带的内容 |
| `AGENTS.md` | 不可协商的边界：除非你批准更多，否则只做本地工作、workspaceId 作用域限定、密钥只在服务端 |
| `.ai/PROJECT_CONTEXT.md` | 跨会话记忆——最近改了什么、为什么；改动代码前必读 |
| `.ai/` 镜像文档 | 重要文件旁配套的 .ai/<path>.md 笔记，记录每个文件的决策与未完成线索 |
| `.agents/skills/` | 为代理编写的任务手册——即下面列出的六个移动端技能 |
| `docs/agent-security.md` | 验收清单——认证、工作区与权限检查，以及脱敏日志 |
| `docs/mobile-store-submission.md` | 商店发布手册——账户、构建、审核备注和提交顺序 |
| `.env.example` | 完整的环境变量清单——代理绝不会编造此文件中不存在的变量名 |


## 附带的技能

`.agents/skills/` 下的每个文件都是一份完整的简报：把它粘贴给代理或让代理自行阅读，套件的规则会随之传递——服务器优先的数据、包内无密钥、离线仅作为网络错误的回退。

可粘贴的 `prompts/` 库只在 Web 存储库中附带；此 checkout 改为附带技能。若要无人值守地完成安装，请使用 agent-setup 指南中的现成提示词。

[让代理执行安装](https://supastack.dev/zh/docs/mobile/agent-setup.md)

- `add-a-mobile-screen`——新增或修改界面及其数据流和离线行为
- `adding-a-dependency`——安全地添加、升级或移动 npm 依赖
- `reviewing-a-pr`——审查 diff 的正确性、工作区隔离和密钥
- `upgrading-from-upstream`——把更新版本的套件拉入您的应用
- `verify-changes`——在交接前选择并运行正确的检查
- `writing-unit-tests`——用 Vitest 覆盖新逻辑


## 代理如何在会话之间记忆

代理在会话之间没有记忆——`.ai/` 文件夹就是记忆。`.ai/PROJECT_CONTEXT.md` 记录最近的改动及原因。旁边的镜像文档，如 `.ai/apps/mobile/src/ideas/index.md`，解释了 `apps/mobile/src/ideas/index.ts` 背后单凭代码看不出的决策。

契约很简单：改文件前先读它的镜像，改动落地时更新镜像。Open Threads 条目记录未完成的工作，让下次会话接着做而不是从头再来。过期的镜像比没有更糟——审查代理的 diff 时，检查被改文件的镜像是否随之更新。


## 诚实地审查代理的工作

完成的任务要看证据而不是总结。在保留代理的工作成果前，用 `docs/agent-security.md` 检查部署的方式来检查它：

哪里不对就把 diff 退回去——你点出失败的检查时，代理修自己的活最快。对于它本不该擅自尝试的事，明确说一次就够；此后整个会话边界都成立。

[验证关卡与测试套件](https://supastack.dev/zh/docs/mobile/testing.md)

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


如果你想继续完成设置，可以阅读《[原生认证](https://supastack.dev/zh/docs/mobile/authentication.md)》。


## 下一篇

[原生认证](https://supastack.dev/zh/docs/mobile/authentication.md)