agent-ai-coding

1# Agent AI Coding
2 
3## 适用范围
4 
5通过项目级 AI Coding 凭据完成受约束的 Agent 编排，不直接调用控制台 `/api/agents/**` 或 `/api/skills/**`，不直接写 `runtime_agent`、`runtime_agent_config_version` 或 Agent Skill 绑定表。
6 
7认证方式：每次请求都发送 `X-ReachAI-AiCoding-Key`。该 Key 只放在请求头，不得写入 URL、生成代码、日志、浏览器运行时代码或仓库文件。API Base URL 和 `projectId` 必须来自当前项目 handoff 或 `GET /api/ai-coding/projects/{projectId}/manifest`，不要猜测。
8 
9凡是 Agent 名称、描述、System Prompt、审计说明和返回给业务用户的内容，默认使用清晰的简体中文；`keySlug`、ID、枚举、路径和协议字段保持原样。
10 
11## 强制安全边界
12 
13- 只能读取或修改当前 `projectId` 与 `projectCode` 同时匹配的 Agent。
14- 创建的 Agent 固定为 `visibility=PROJECT`；不能通过 AI Coding 改写项目归属、`keySlug`、可见性或内部 ID。
15- 只能绑定精确的 `PUBLISHED` Skill 版本。可绑定范围为 `PUBLIC`、`SHARED`，或当前同项目的 `PROJECT` Skill；`PRIVATE` Skill 永远不可发现、不可绑定。
16- AI Coding 绑定的 Skill 始终使用 `scriptPolicy=DENY`。不能申请或伪造 `SANDBOX_REVIEWED`，也不能批准脚本执行。
17- AI Coding 不提供 Skill 包导入、评审、发布、撤回或删除能力。这些治理动作必须由控制台中的人完成。
18- AI Coding 不发布包含远程 A2A Agent 绑定的配置；出现 `AGENT_A2A_REQUIRES_CONSOLE` 时转交控制台人工处理。
19- 不提供 Agent 删除接口。停用 Agent 只能通过受约束的 identity update 设置 `enabled=false`。
20- Workflow 必须先通过 Workflow AI Coding 校验并发布，再通过项目级 Workflow-as-Tool attach 接口添加。
21 
22## 标准执行循环
23 
241. 下载本 Skill：`GET /api/ai-assist/skills/agent-ai-coding/latest.zip`。
252. 读取项目 manifest：`GET /api/ai-coding/projects/{projectId}/manifest`。
263. 列出 Agent：`GET /api/ai-coding/projects/{projectId}/agents`。
274. 新建 Agent，或读取目标 Agent 的完整上下文。
285. 修改前读取上下文的 `baseRevision` 和 `mutableBase.configVersionId`。配置保存、发布、Skill attach/detach 均必须携带 `baseRevision`；已有 DRAFT 时还须携带该 DRAFT id。版本 ID 不代表内容未变，不要覆盖未读草稿。
29…