Repository navigation
CreateAgentTemplate
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 的转派,不需要为不同用途配置事件类型。
| 接口 | 用途 |
|---|---|
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。
- 验证同一回调能处理直接命令与 Planner 委托,任务说明没有丢失。
- 验证成功回复、失败回报、重复事件,以及没有任务时正常退出或继续等待。
- 涉及仓库修改时验证 PR 分支、已有人工提交和任务范围;需要审批的候选不得自行发布。
- 在 Agent Team 添加模板,选择范围和最小权限,部署后查看注册日志。
- 在 Issue 和普通 PR 中分别通过评论规划及
@Agent验证。
平台操作和注册错误处理见 Agent Team。Spec 和 Bugfix 是业务实现示例,新增 Agent 不需要复制它们的内部工作流。
Copyright ©Mengning Software 2024-2026 All rights reserved.