agent-ai-coding

Agent AI Coding

适用范围

通过项目级 AI Coding 凭据完成受约束的 Agent 编排，不直接调用控制台 /api/agents/** 或 /api/skills/**，不直接写 runtime_agent、runtime_agent_config_version 或 Agent Skill 绑定表。

认证方式：每次请求都发送 X-ReachAI-AiCoding-Key。该 Key 只放在请求头，不得写入 URL、生成代码、日志、浏览器运行时代码或仓库文件。API Base URL 和 projectId 必须来自当前项目 handoff 或 GET /api/ai-coding/projects/{projectId}/manifest，不要猜测。

凡是 Agent 名称、描述、System Prompt、审计说明和返回给业务用户的内容，默认使用清晰的简体中文；keySlug、ID、枚举、路径和协议字段保持原样。

强制安全边界

• 只能读取或修改当前 projectId 与 projectCode 同时匹配的 Agent。
• 创建的 Agent 固定为 visibility=PROJECT；不能通过 AI Coding 改写项目归属、keySlug、可见性或内部 ID。
• 只能绑定精确的 PUBLISHED Skill 版本。可绑定范围为 PUBLIC、SHARED，或当前同项目的 PROJECT Skill；PRIVATE Skill 永远不可发现、不可绑定。
• AI Coding 绑定的 Skill 始终使用 scriptPolicy=DENY。不能申请或伪造 SANDBOX_REVIEWED，也不能批准脚本执行。
• AI Coding 不提供 Skill 包导入、评审、发布、撤回或删除能力。这些治理动作必须由控制台中的人完成。
• AI Coding 不发布包含远程 A2A Agent 绑定的配置；出现 AGENT_A2A_REQUIRES_CONSOLE 时转交控制台人工处理。
• 不提供 Agent 删除接口。停用 Agent 只能通过受约束的 identity update 设置 enabled=false。
• Workflow 必须先通过 Workflow AI Coding 校验并发布，再通过项目级 Workflow-as-Tool attach 接口添加。

标准执行循环

1. 下载本 Skill：GET /api/ai-assist/skills/agent-ai-coding/latest.zip。
2. 读取项目 manifest：GET /api/ai-coding/projects/{projectId}/manifest。
3. 列出 Agent：GET /api/ai-coding/projects/{projectId}/agents。
4. 新建 Agent，或读取目标 Agent 的完整上下文。
5. 修改前读取 mutableBase.configVersionId。若已有 DRAFT，后续写请求必须显式携带该 DRAFT id；不要覆盖未读草稿。
6. 修改 Supervisor 字段、绑定 Skill、解绑 Skill或附加 Workflow。
7. 默认让 Skill attach/detach 直接发布；若 publish=false，完成全部修改后再显式发布 DRAFT。
8. 重新读取 Agent，确认 ACTIVE 配置、Skill 精确版本和 Workflow Tool 白名单。

API

列出与读取 Agent

GET /api/ai-coding/projects/{projectId}/agents
GET /api/ai-coding/projects/{projectId}/agents/{agentId}

第二个接口返回 agent、configVersions 和 mutableBase。必须用真实返回的内部 agent.id 调用后续 Agent authoring 接口。

创建 Agent

POST /api/ai-coding/projects/{projectId}/agents
Content-Type: application/json

{
  "keySlug": "orders-assistant",
  "name": "订单助手",
  "description": "处理订单查询与协作任务",
  "enabled": true,
  "allowedRoles": ["ORDER_OPERATOR"],
  "supervisorConfig": {
    "modelInstanceId": "从平台返回值中选择的 ACTIVE LLM id",
    "systemPrompt": "你是订单助手，只使用已允许的 Skill 和 Workflow。",
    "maxPlanSteps": 6,
    "maxWorkflowCalls": 4,
    "maxReplans": 2,
    "policyProfile": "DEV_ALLOW_ALL"
  },
  "activate": true,
  "requestedBy": "Codex"
}