Run 生命周期

Run 是某个 task、Agent Profile、目标 Edge、workspace 和 runtime adapter 的一次执行尝试。生命周期之所以重要，是因为 AgentHub 承诺的是可见、可审查、可审计的 Agent 工作，而不是把终端 transcript 复制到网页里。

当前状态

Run lifecycle 词汇已契约已定。本地预览链路和 adapter event 现在即可开发验证；稳定公开 SDK 包、完整 Hub/Web 路由证据和 Remote/Cloud Edge lifecycle 证据仍在开发中。

生命周期地图

阶段	Owner	必须发生什么
Created	Hub 或 Desktop	Task、actor、project/workspace context、请求的 Agent Profile
Planned	Hub/Edge	Target Edge、workspace policy、runtime profile、approval policy
Accepted	Edge	Edge 确认可以尝试执行
Preparing	Edge	校验 workspace allowlist、runtime 可用性、凭据边界
Running	Runtime adapter	流式输出归一化 event、message、tool call、artifact
Needs approval	Edge + reviewer	暂停 write、shell、network、publish 或 apply action
Applying	Edge	执行已批准 action，并保留 audit 证据
Completed	Edge/Hub	Final response、artifact、diff state、metric、audit
Failed	Edge/Hub	稳定错误码、安全 details、恢复路径
Cancelled	Actor/Edge	显式取消并进入终态

UI 不应在没有事件证据时从 created 直接跳到 done。如果 runtime 无法输出足够事件，AgentHub 应把 run 标记为 degraded 或 failed，并给出具体原因。

状态机

mermaid

stateDiagram-v2
  [*] --> Created
  Created --> Planned
  Planned --> Accepted
  Accepted --> Preparing
  Preparing --> Running
  Preparing --> Failed
  Running --> NeedsApproval
  NeedsApproval --> Running: approved
  NeedsApproval --> Cancelled: rejected or cancelled
  Running --> Applying
  Applying --> Running
  Running --> Completed
  Running --> Failed
  Running --> Cancelled
  Completed --> [*]
  Failed --> [*]
  Cancelled --> [*]

Event Envelope

每个 event 都应能安全渲染到 Desktop、Web 和未来的集成入口。Raw runtime output 只有在不暴露 secret 时，才能作为 debug 附件保留。

JSON

{
  "id": "evt_01",
  "sequence": 12,
  "type": "run.message.delta",
  "runId": "run_01",
  "sessionId": "session_01",
  "agentId": "docs-agent",
  "timestamp": "2026-06-09T00:00:00.000Z",
  "payload": {
    "text": "Reading the public docs route map."
  }
}

字段	规则
`id`	唯一 event id，用于 replay 和 audit
`sequence`	每个 run 内单调递增，便于客户端恢复顺序
`type`	稳定命名，例如 `run.started`、`run.message.delta`、`run.diff.ready`
`runId`	生命周期、artifact、approval 和终态 event 必填
`sessionId`	event 进入 shared session 时必填
`payload`	可版本化、结构化、无 secret 的数据

核心 Event 分组

分组	示例	UI 用途
Lifecycle	`run.created`、`run.started`、`run.completed`、`run.failed`、`run.cancelled`	状态、timeline、audit
Message	`run.message.delta`、`run.message.completed`	Chat transcript
Tool	`run.tool.call`、`run.tool.result`	检查 runtime 做了什么
File/diff	`run.file.read`、`run.diff.ready`、`run.patch.proposed`	审查文件和候选变更
Artifact	`run.artifact.ready`、`run.preview.ready`	渲染文档、截图、预览
Approval	`run.approval.requested`、`run.approval.resolved`	暂停并恢复高风险动作
Runtime	`runtime.unavailable`、`runtime.timeout`、`schema.validation_failed`	故障分流

Approval Gate

AgentHub 应默认使用保守 approval gate：

动作	默认 gate
读取 allowlist 内 workspace	Allow 并记录
读取 workspace 外路径	Deny
文件写入或 patch apply	Ask
Shell 命令	Ask，展示命令预览和 workspace context
网络访问	Ask，除非 policy 明确允许
Commit、push、publish、deploy	Ask，并记录 actor
Secret access	Deny，除非由产品专用 server-side flow 承载

Approval 应是明确动作。当风险是 file write、shell、network、publish 或 deploy 时，不要把它藏在泛化的"continue"按钮里。

Artifact 与 Diff

Artifact 和 diff 是审查面，不代表变更已被接受。

项目	必要 metadata
Diff	base、target、相对 workspace 的 file path、change summary
Patch	affected files、apply status、approval id
File preview	相对 allowlisted workspace 的 path、读取时间
Screenshot	viewport、route、theme、language、privacy review
Generated docs	source route、language、build status

公开示例使用 docs/quickstart.md 这类合成路径，不使用私有绝对路径。

Failure Code

使用具体、可恢复的错误：

Code	含义	第一恢复动作
`runtime_unavailable`	CLI 缺失、未登录或 adapter 不可达	检查 runtime CLI 安装和鉴权
`workspace_outside_allowlist`	请求路径未被 Edge 批准	更新 allowlist 或选择其他 workspace
`permission_denied`	Policy 拒绝 read/write/shell/network action	调整 approval policy 或请求明确审批
`approval_rejected`	Reviewer 拒绝 pending action	停止或修改 run
`run_timeout`	Runtime 超过 timeout	缩小任务范围或调整 timeout policy
`schema_validation_failed`	Adapter 输出无效 event shape	先修 adapter mapping，再信任 UI 状态
`target_offline`	Edge target 不可达	重连 target 或使用 Desktop local mode

产品界面避免泛化文案"something went wrong"。用户应该能判断到底要修 CLI auth、workspace policy、target availability、approval 还是 adapter schema。

Runtime Adapter 职责

Runtime adapter 应该：

启动和停止底层 runtime 进程。
解析 stdout、stderr、JSONL、NDJSON 或协议 event。
归一化 message、tool call、file change、approval 和终态。
执行 timeout 和 cancellation hook。
避免记录 provider key、prompt secret、本地绝对路径和 raw private file content。
当 runtime 缺失、未鉴权或不兼容时输出稳定 failure event。

Adapter 负责进程细节；Agent Profile 负责产品侧的 capability、label、policy 和选择行为。

UI 要求

Desktop 和 Web 应一致渲染生命周期状态：

状态标签和最后 event 时间可见。
Running 状态不改变布局尺寸，也不在 hydration 后跳动。
Approval 状态清楚区分只读审查和 apply/write。
Failed 状态展示 code、安全 message 和下一步。
Completed 状态链接到 artifact、diff、transcript 和 audit evidence。
主题和语言切换不会重置 mock 或 preview 中的 run timeline。

校验

声明真实的 run lifecycle 能力前，需验证：

Run 从已知 actor 和 project 或 workspace 启动。
Edge 校验 workspace、runtime profile 和 approval policy。
Event 按顺序到达，刷新后可以 replay。
Diff、artifact 和 preview event 不暴露私有绝对路径。
Approval 会阻塞高风险动作，直到明确 resolve。
Completed、failed 和 cancelled 是稳定终态。
Search、docs 和 release note 使用同一套 lifecycle 词汇。