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

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

[桌面本地设置](https://supastack.dev/zh/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/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/docs/desktop/testing.md)

- 它运行了它所声称的检查——cargo test、cargo check 或发布预检——请要求看命令和它的输出，而不是结论。
- 密钥保持仅在服务器端——没有签名密钥或证书被打印到报告或提交中，外壳也仍然不含任何提供商凭据。
- 产品行为留在 web 应用中——diff 没有新增用 Rust 实现的并行界面、认证或聊天逻辑。
- 每个被改文件的 `.ai/` 镜像随代码一起更新。
- 发布、安装包发行和付费提供商调用保持为您批准的单独步骤——代理绝不会自行合并、推送或发行。
- 某一步失败两次时，它停下来报告失败的命令，而不是绕过去自行发挥。


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


## 下一篇

[创建桌面端发布账户](https://supastack.dev/zh/docs/desktop/external-accounts.md)