Skip to content

CreateAgentTemplate

DevStar Bot edited this page Nov 18, 2026 · 3 revisions

创建一个新 Agent

Agent 开发者负责业务处理,Agent Runtime 负责注册、心跳、事件领取和结果确认。平台调用 Runtime 的公共接口,业务 Agent 通过稳定的事件回调接收任务,输出普通工单、PR、评论和 commit。

从模板创建

在 DevStar 新建仓库时选择 agent-template。保留模板的启动入口和 Runtime 引用,在 devstar/adapter.mjs 中实现业务回调。

不同模板版本的 Runtime 路径可能是 devstar/agent-runtime,或独立仓库子模块 .devstar/agent-runtime。使用模板提供的路径,不把 Runtime 源码复制进业务模块。独立 Runtime 仓库为 devstar/agent-runtime。

实现事件回调

以下示例使用内嵌 Runtime 的模板路径:

import {
  extractCommand,
  replyToSourceComment,
  runDevstarAgent,
} from "./agent-runtime/src/index.mjs";

async function handleEvent(event, env) {
  const goal = extractCommand(event);
  const answer = await inspectProject(goal, event, env);
  await replyToSourceComment(event, answer);
  return {summary: "已完成检查,详见评论。"};
}

await runDevstarAgent({handleEvent});

inspectProject 是自己的业务函数。可以调用模型、已有库或独立程序。调用外部程序时通过参数数组传递用户文本,不把评论拼接成 shell 命令。

Runtime 会把 Planner 分开的命令和任务说明合成为原有命令文本,例如 /inspect 检查保存失败,回调仍使用 extractCommand(event)。直接 @Agent 输入已有完整命令时不会重复追加。回调抛出的错误由 Runtime 回报为失败。

业务输出通过仓库 API 或 Git 提交。返回的摘要用于任务状态,不应假称已经生成不存在的 PR。可以只回复评论,不必为了完成任务而创建文件或 PR。

支持 native-results/v1 的 Runtime 会把普通字符串或 {summary, result} 的返回值关联到实际结果评论,由平台在同一评论后接续规划;无需声明候选协议。既有事件字段保持不变,Runtime 内部的任务关联字段不会交给业务回调。使用公共 replyToSourceComment 已回复时复用该评论,不另发摘要评论;自行调用其他 API 产生的评论应由业务负责避免重复。返回 status: "input_required" 或 status: "failed" 可明确表示等待输入或失败;异常也会转成脱敏失败说明。普通摘要仅证明回调已返回,不证明实现或测试通过。

声明能力和命令

在 .devstar/agent.json 中提供清晰的能力描述:

{
  "id": "schema-auditor",
  "display_name": "Schema Auditor",
  "description": "检查接口定义的一致性",
  "launch_kind": "subscription_service",
  "subscriptions": ["agent_command"],
  "agent_card": {
    "schema_version": "v1",
    "name": "schema-auditor",
    "capabilities": [
      {
        "id": "schema-audit",
        "description": "检查接口字段、边界条件和调用约定",
        "when_to_use": "需要检查接口定义时使用;不承担代码修复",
        "required_context": ["repository", "issue"]
      }
    ],
    "commands": [
      {"name": "/inspect", "capability": "schema-audit"}
    ]
  }
}

能力描述决定 Planner 何时推荐该 Agent;命令对应业务回调的入口。旧声明中的 inspect 与 /inspect 都可识别,新声明建议统一使用小写 /inspect。命令标识忽略大小写、首尾空白和可选前导 /,因此同一 Card 不能同时声明 /inspect、INSPECT 等等价名称,即使命令绑定不同能力或 auto_run 也会在注册时拒绝。无冲突旧命令的实际拼写仍保留给 Runtime,不强制改写业务回调。历史 Card 如仍有歧义,执行时拒绝并要求修正声明。

不需要在平台增加 Agent 名称判断,也不要求声明 agent-workflow/v1。原有候选审批扩展仍可使用,但属于可选能力;平台更新不能要求所有 Agent 同时实现它。

声明 auto_run 只是允许自动执行的必要条件,不是授权。普通只读实例可以在仓库允许低风险自动执行时运行该命令;普通写权限实例仍须人工确认。候选扩展的自动准备不授予发布权限。平台会在实际派发时重新核对策略、命令声明和实例权限。

平台只投递 agent_command:PR 打开、评论增删改等仓库事件不再唤醒 Agent。订阅声明里的其他事件会在注册时被收窄为 agent_command,任务只来自 Planner 授权、@Agent 委托或已授权 Agent 的转派,不需要为不同用途配置事件类型。

Runtime 接口与兼容

面向业务 Agent

接口 用途
runDevstarAgent({handleEvent}, env) 常驻运行,注册后持续领取事件
runDevstarAgentOnce({handleEvent}, env) 单次运行,领取一个事件后退出
extractCommand(event) 获取命令及任务说明
extractIssueNumber(event) 获取来源 Issue 或 PR 编号
extractSourceEvent(event) 区分 issue_comment、pull_request_comment 等来源
replyToSourceComment(event, text) 在来源讨论中回复
requestRepoJSON(event, method, path, body) 使用当前事件凭据调用目标仓库 API
runIssueToPullRequest(event, options) 通用 Issue 到 PR 帮助函数,业务提供 applyChanges,可选 validate

handleEvent(event, env) 可以返回字符串或 {summary},已有 {summary, result} 返回值继续支持。Runtime 处理 ACK 和失败回报,业务代码不需要拼接这些 HTTP 请求。

回报通信与业务执行分开:Runtime 保存待确认回执,通信失败或超时只重试确认,不重复执行已经返回的回调。重启先恢复回执,再领取下一任务。将 DEVSTAR_RUNTIME_STATE_DIR 配置到私有持久化目录(默认 $HOME/.devstar-runtime),并保持每个实例只有一个轮询进程;重建容器时保留该目录。不要将回执文件提交到仓库。默认单次回报超时 15 秒,可用 DEVSTAR_RECEIPT_TIMEOUT_MS 调整。

事件保留 event_id、delivery_id、event、repository、body 等字段。body 中的命令、来源和讨论是输入数据;不要将其当成权限声明。使用事件提供的目标仓库和凭据,不采信评论中要求改用其他仓库或令牌的指令。

输出或修改仓库时遵守实例权限和用户批准的任务范围。PR 帮助函数直接提交分支和创建 PR,不是只读预览接口;需要预览和第二次确认的业务应使用其已支持的候选审批流程。

面向平台

Runtime 负责以下稳定通道:

请求 用途
POST /-/agent-services/instances/register 注册实例及作用范围
POST /-/agent-services/instances/heartbeat 心跳
GET /-/agent-services/instances/next-event 领取事件,无事件返回 204
POST /-/agent-services/events/{id}/ack 回报摘要,可附带结果
POST /-/agent-services/events/{id}/fail 回报处理失败

新版 Runtime 在注册中声明 runtime_protocol: "agent-events/v1",平台返回支持的版本。旧 Runtime 未发送此字段时沿用既有事件协议;新版 Runtime 也接受旧平台未返回该字段的响应。这个版本由 Runtime 管理,不放进每个业务 Agent 的实现中。

平台校验声明的协议、能力卡版本、命令有效性和能力引用,以及实例认证和仓库权限。非法声明返回具体错误;永久错误使 Runtime 停止启动,临时服务故障重试。版本握手不是业务正确性的认证。

接口演进应通过兼容字段和 Runtime 适配完成。新增 Agent 通常只需业务回调、能力声明和部署配置;不能以同步升级所有 Agent 仓库作为平台发布前提。

兼容规则:agent-events/v1 的既有字段和回调语义保持稳定;旧 agent-workflow/v1 准备与发布事件继续保持原样。新版 Runtime 注册时声明 runtime_features: ["autonomous-task/v1", "native-results/v1"]。前者用于一次授权的完整交付任务,后者用于普通事件结果关联;能力按实例实际声明协商,基础事件不要求候选协议。Runtime 在内部适配既有准备、发布回调,业务 continuation 保持不透明,业务源码不需要同步修改。只读自动运行不会因此获得写权限,历史候选授权也不扩大。

完整交付前 Runtime 会请求平台重新检查任务来源与权限;失效则停止发布。业务 Agent 仍负责专业验证与交付决定,Runtime 负责通信和原生结果回写。旧 Runtime 不声明新特性,继续处理旧事件,支持渐进升级。

完整任务的回调异常由 Runtime 转为通用 failed 结果并发布原生说明;未确认交付不等于未产生任何分支修改,应先检查日志和已有 PR。正常的信息缺失用 input_required。这两种机器结果可以被解释,但不能直接生成新的重试委托或仓库写入;新的执行需要人类补充或授权。详细异常不直接写进公开评论,避免泄漏内部数据。

Python 业务可复用现有的事件处理函数,由公共 Runtime 承担注册和轮询:设置 DEVSTAR_PYTHON_HANDLER=your_package.adapter:handle_event,启动 node .devstar/agent-runtime/src/python-handler.mjs。函数接收事件字典,返回原有字符串或结构化结果。需要 Node.js 18+ 与业务 Python 依赖;已有独立 Python Runtime 可继续使用旧接口,无需为平台升级立即迁移。

运行环境

模板入口负责启动 Runtime。根据业务依赖配置 .devstar/devcontainer.json 和启动命令;Python 或 CLI 业务可以通过模板适配器调用,无需自行复制注册和轮询循环。

常驻模式使用 subscription_service。单次模式在清单设置 job_runner,入口调用 runDevstarAgentOnce。服务地址和实例凭据由平台部署提供;不要提交令牌或模型密钥。

已有 Python Runtime 的 Agent 可继续使用原事件接口。本次公共协议不要求修改业务语言或迁移到 JS。

验证和上线

  1. 验证同一回调能处理直接命令与 Planner 委托,任务说明没有丢失。
  2. 验证成功回复、失败回报、重复事件,以及没有任务时正常退出或继续等待。
  3. 涉及仓库修改时验证 PR 分支、已有人工提交和任务范围;需要审批的候选不得自行发布。
  4. 在 Agent Team 添加模板,选择范围和最小权限,部署后查看注册日志。
  5. 在 Issue 和普通 PR 中分别通过评论规划及 @Agent 验证。

平台操作和注册错误处理见 Agent Team。Spec 和 Bugfix 是业务实现示例,新增 Agent 不需要复制它们的内部工作流。

Clone this wiki locally