From 8b09ecd7e48fc008f15541f418bb22f6aa8a9b8f Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 29 May 2026 08:59:54 +0800 Subject: [PATCH] docs: add v0.1 lane specs --- AGENTS.md | 16 ++- docs/reference/architecture.md | 6 +- docs/reference/spec-v01-cicd.md | 125 ++++++++++++++++++ .../spec-v01-documentation-governance.md | 55 ++++++++ docs/reference/spec-v01-services.md | 99 ++++++++++++++ 5 files changed, 293 insertions(+), 8 deletions(-) create mode 100644 docs/reference/spec-v01-cicd.md create mode 100644 docs/reference/spec-v01-documentation-governance.md create mode 100644 docs/reference/spec-v01-services.md diff --git a/AGENTS.md b/AGENTS.md index ad882c5..997573b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,15 +10,16 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 ## Critical Source Workspace Rule -- P0: 唯一长期 source workspace 是 `G14:/root/agentrun`，固定使用 `master` 分支，`origin` 固定为 `git@github.com:pikasTech/agentrun.git`。 -- P0: 每次开发、部署、恢复中断或上下文压缩后，都必须先从 UniDesk 执行 `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'`，确认路径、分支、remote 和 clean 状态。 -- P0: 固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规修改必须在 `/root/agentrun/.worktree/{pr_branch}` 中完成，并从最新 `origin/master` 创建。 +- P0: `v0.1` 长期 source workspace 是 `G14:/root/agentrun-v01`，固定使用 `v0.1` 分支，`origin` 固定为 `git@github.com:pikasTech/agentrun.git`。 +- P0: 每次开发、部署、恢复中断或上下文压缩后，都必须先从 UniDesk 执行 `tran G14:/root/agentrun-v01 script -- 'pwd; git status --short --branch; git remote -v'`，确认路径、分支、remote 和 clean 状态。 +- P0: 固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规修改必须在 `/root/agentrun-v01/.worktree/{pr_branch}` 中完成，并从最新 `origin/v0.1` 创建。 - P0: 不得把 UniDesk、HWLAB、D601 workspace、临时 clone、pod 内副本或 runner checkout 当作 AgentRun source truth。 -## Critical Runtime Target Rule +## Critical Versioned Lane Rule -- P0: 默认部署目标是 G14 原生 k3s namespace：`agentrun_dev` 和 `agentrun_prod`。 -- P0: Kubernetes 操作必须使用 UniDesk route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n agentrun_dev`。 +- P0: AgentRun 废弃 `dev/prod` 管理口径，后续按 `v0.1`、`v0.2`、`v0.3` 这种版本 lane 滚动；每条 lane 拥有独立 branch、workspace、namespace、GitOps desired state 和发布验收。 +- P0: `v0.1` 固定部署目标是 G14 原生 k3s namespace `agentrun-v01`；不得继续把 `agentrun_dev` 或 `agentrun_prod` 当作当前规格、验收或发布目标。 +- P0: Kubernetes 操作必须使用 UniDesk route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n agentrun-v01`。 - P0: 不得通过临时 NodePort、host port、pod IP、一次性 port-forward 或 provider-gateway 业务 HTTP proxy 固化 AgentRun 暴露路径。公网或跨服务入口必须通过本仓库审查后的变更引入。 ## Critical MVP Rule @@ -40,6 +41,9 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 ## 长期参考文档 +- `docs/reference/spec-v01-documentation-governance.md`：v0.1 文档治理、唯一入口、spec 权威和过程材料承载规则。 +- `docs/reference/spec-v01-services.md`：v0.1 服务总览、保留对象、deferred 对象和单服务规格索引。 +- `docs/reference/spec-v01-cicd.md`：v0.1 分支、workspace、namespace、GitOps、registry、CI/CD 和发布验收规格。 - `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。 - `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。 - `TEST.md`：随实现逐步补齐的人工验收场景。 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 20fb4cb..d343fb7 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -201,9 +201,11 @@ Event 是 append-only，并按 seq 分页： ## 部署方向 -默认运行目标是 G14 原生 k3s namespace `agentrun_dev` 和 `agentrun_prod`。Control-plane service 应是长驻服务；runner 应是短生命周期 Job 或受控 host-native process。Backend adapter 可以作为 pod 或 host-native service 运行，但必须通过 AgentRun 注册 capability 和 health，不能通过临时地址被 ad hoc 调用。 +AgentRun 从 `v0.1` 开始按版本 lane 滚动，废弃 `dev/prod` 管理口径。`v0.1` 的固定 source workspace 是 `G14:/root/agentrun-v01`，固定 source branch 是 `v0.1`，固定运行目标是 G14 原生 k3s namespace `agentrun-v01`。后续 `v0.2`、`v0.3` 必须拥有自己的 branch、workspace、namespace、GitOps branch、runtime path 和发布验收。 -广泛 tenant 使用前，需要先设计 namespace isolation、RBAC、Secret scope、NetworkPolicy 和 ResourceQuota。独立 cluster 是后续成熟选项；第一版应优先在 G14 k3s namespace 内证明服务，除非出现明确隔离 blocker。 +Control-plane service 应是长驻服务；runner 应是短生命周期 Job 或受控 host-native process。Backend adapter 可以作为 pod 或 host-native service 运行，但必须通过 AgentRun 注册 capability 和 health，不能通过临时地址被 ad hoc 调用。 + +广泛 tenant 使用前，需要先设计 namespace isolation、RBAC、Secret scope、NetworkPolicy 和 ResourceQuota。独立 cluster 是后续成熟选项；第一版应优先在 `agentrun-v01` namespace 内证明服务，除非出现明确隔离 blocker。`agentrun_dev` 和 `agentrun_prod` 不再作为当前架构规格或验收目标。 ## MVP 非目标 diff --git a/docs/reference/spec-v01-cicd.md b/docs/reference/spec-v01-cicd.md new file mode 100644 index 0000000..296d786 --- /dev/null +++ b/docs/reference/spec-v01-cicd.md @@ -0,0 +1,125 @@ +# v0.1 CI/CD 与版本 Lane 规格 + +本文是 AgentRun `v0.1` 独立 CI/CD、GitOps、namespace、registry 和发布验收规格。AgentRun 从 `v0.1` 开始废弃 `dev/prod` 管理口径，改为按 `v0.1`、`v0.2`、`v0.3` 版本 lane 滚动。 + +## 设计目标 + +- `v0.1` 是独立 lane，不复用 `agentrun_dev` 或 `agentrun_prod` 作为当前运行面。 +- 每条版本 lane 拥有独立 source branch、source workspace、GitOps branch、runtime namespace、artifact catalog、runtime path、CI pipeline 和发布验收。 +- `v0.1` 只能部署到 `agentrun-v01` namespace；`v0.2`、`v0.3` 后续使用自己的 namespace 和 GitOps 路径。 +- CI/CD 必须使用 G14 原生 k3s、Tekton/GitOps/Argo CD 或等价受控 lane；不得把 master server、D601 legacy、临时 clone、手工 Pod patch 或本地镜像当作发布真相。 +- 发布证据以 live runtime、Argo desired state、GitOps branch、Tekton 证据和干净 source workspace 顺序判断。 + +## 固定命名 + +| 对象 | v0.1 规格 | +| --- | --- | +| Source repo | `git@github.com:pikasTech/agentrun.git` | +| Source branch | `v0.1` | +| Source workspace | `G14:/root/agentrun-v01` | +| Worktree root | `G14:/root/agentrun-v01/.worktree/{task}` | +| Runtime namespace | `agentrun-v01` | +| GitOps branch | `v0.1-gitops` | +| Artifact catalog | `v0.1-gitops:deploy/artifact-catalog.v01.json` | +| Runtime path | `v0.1-gitops:deploy/gitops/g14/runtime-v01` | +| Tekton namespace | `agentrun-ci` | +| Tekton Pipeline | `agentrun-v01-ci-image-publish` | +| Branch poller | `agentrun-v01-branch-poller` | +| Control-plane reconciler | `agentrun-v01-control-plane-reconciler` | +| Tekton ServiceAccount | `agentrun-v01-tekton-runner` | +| PipelineRun prefix | `agentrun-v01-ci-poll-` | +| Argo CD AppProject | `argocd/agentrun-v01` | +| Argo CD Application | `argocd/agentrun-g14-v01` | + +公网入口暂不作为 `v0.1` 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。 + +## 真相源 + +`v0.1` 发布真相按以下顺序判断： + +1. Live runtime：`agentrun-v01` namespace 中 Deployment/Job/Pod ready、事件、日志和 service health。 +2. Argo desired state：`argocd/agentrun-g14-v01` 的 revision、sync、health、source branch 和 runtime path。 +3. GitOps branch：`v0.1-gitops` 中的 `deploy/artifact-catalog.v01.json` 与 `deploy/gitops/g14/runtime-v01/**`。 +4. Tekton 执行证据：`agentrun-v01-branch-poller`、PipelineRun、TaskRun result、image digest 和 promotion 终态。 +5. 干净 source workspace：`G14:/root/agentrun-v01`、`origin/v0.1`、render 脚本、deploy intent 和 `--no-write` 输出。 + +旧 `master` 记忆、`/root/agentrun` 固定工作区、`agentrun_dev`、`agentrun_prod`、D601 legacy 路径、临时 worktree 或本地容器只能作为线索，不能作为 `v0.1` 发布通过证据。 + +## Source 与 GitOps 分层 + +`v0.1` source branch 可以包含： + +- 源码、测试、长期参考文档、人写配置和模板。 +- `deploy/deploy.json` 或等价 lane intent。 +- Kubernetes 模板、render 脚本、CI/CD helper 和 catalog schema。 + +`v0.1` source branch 不得跟踪： + +- `deploy/artifact-catalog.v01.json`。 +- `deploy/gitops/g14/runtime-v01/**`。 +- Argo 实际消费的 rendered runtime desired state。 +- image digest、publish state、reuse evidence 或 CI 生成 rollout metadata。 + +`v0.1-gitops` branch 必须包含： + +- `deploy/artifact-catalog.v01.json`，记录 image tag、digest、source commit、service identity、publish/reuse 状态。 +- `deploy/gitops/g14/runtime-v01/**`，作为 Argo CD 消费的 desired state。 +- 必要 generated metadata，但不得包含 Secret 值。 + +首次初始化时，如果 `v0.1-gitops:deploy/artifact-catalog.v01.json` 尚不存在，只允许由 `v0.1` lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 `master`、`agentrun_dev`、`agentrun_prod` 或 source branch 生成物。 + +## CI/CD 链路 + +标准链路如下： + +1. `agentrun-v01-branch-poller` 轮询 `origin/v0.1`，按 source commit 创建 `agentrun-v01-ci-poll-` PipelineRun。 +2. `prepare-source` checkout `v0.1` source，并从 `v0.1-gitops` 读取上一版 `deploy/artifact-catalog.v01.json`。 +3. 原语校验 task 只覆盖文档治理、spec 链接、轻量语法和必要单元测试；旧 `dev/prod` gate 不进入 lane。 +4. Planner 根据组件输入判断 affected/reused services。 +5. Affected service 通过 BuildKit 发布到 G14 本地 registry；reused service 复用 catalog digest。 +6. Promotion 刷新 `deploy/artifact-catalog.v01.json`，render `deploy/gitops/g14/runtime-v01/**`，只推送到 `v0.1-gitops`。 +7. `agentrun-g14-v01` 从 `v0.1-gitops:deploy/gitops/g14/runtime-v01` 同步到 `agentrun-v01`。 +8. 验收只观察 `agentrun-v01` runtime 和对应 service health。 + +## Artifact 与镜像身份 + +- `v0.1` 镜像 tag 使用完整 40 位 source commitId。 +- Runtime manifest 必须使用 digest pin 作为部署身份。 +- Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。 +- 同一 source commit 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、RBAC 和 runtime config 中，不 bake 进镜像。 +- `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。 + +## Kubernetes 与 Argo 边界 + +- `agentrun-v01` namespace 只能由 `v0.1` GitOps lane 管理。 +- `argocd/agentrun-v01` AppProject destination 只能包含 `agentrun-v01`。 +- `argocd/agentrun-g14-v01` source 必须指向 `v0.1-gitops:deploy/gitops/g14/runtime-v01`，destination 必须是 `agentrun-v01`。 +- `v0.1` Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。 +- `agentrun_dev` 和 `agentrun_prod` 不得作为 `v0.1` namespace、Argo destination、Pipeline target 或验收目标。 + +## 手动和热修边界 + +- 只读诊断可以通过 UniDesk route `G14:k3s` 查询 `agentrun-v01`。 +- 写操作必须走 `v0.1` CI/CD、GitOps 或仓库内受控 CLI；不得长期使用手工 `kubectl apply/patch/delete` 维持运行态。 +- 任何需要临时 live hotfix 的情况，必须先记录 issue/PR，说明原因、影响范围、回滚方式和后续固化路径。 +- 不得在 master server 构建镜像、运行重型测试或把本地 Docker image 当作发布真相。 + +## 验收标准 + +- `G14:/root/agentrun-v01` 为 `v0.1...origin/v0.1` 且 clean。 +- `AGENTS.md` 和 `docs/reference/` 不得把 `agentrun_dev` 或 `agentrun_prod` 写成 `v0.1` 当前 namespace、Argo destination、Pipeline target 或验收目标；只允许在废弃说明和历史背景中提及。 +- `agentrun-v01` namespace 存在，且 `agentrun_dev`/`agentrun_prod` 不参与 `v0.1` 发布判定。 +- `v0.1-gitops` branch 和 `deploy/gitops/g14/runtime-v01` 成为 Argo desired state 来源。 +- Runtime manifest 使用 digest pin，catalog 记录完整 source commit 与 digest。 +- 发布完成后可通过 `G14:k3s` 读取 `agentrun-v01` Pod ready、service health 和对应 image digest。 + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| `v0.1` source branch | 已建立 | `origin/v0.1` 存在。 | +| `G14:/root/agentrun-v01` workspace | 已建立 | 固定工作区使用 `v0.1` 分支。 | +| `agentrun-v01` namespace | 未实现 | 需要后续初始化。 | +| `v0.1-gitops` branch | 未实现 | 需要后续初始化。 | +| Tekton/Argo lane | 未实现 | 需要后续按本文补齐。 | +| `dev/prod` 废弃口径 | 已定义 | 本文明确 `agentrun_dev` 和 `agentrun_prod` 不作为当前规格目标。 | diff --git a/docs/reference/spec-v01-documentation-governance.md b/docs/reference/spec-v01-documentation-governance.md new file mode 100644 index 0000000..3cc67f9 --- /dev/null +++ b/docs/reference/spec-v01-documentation-governance.md @@ -0,0 +1,55 @@ +# v0.1 文档治理规格 + +本文是 AgentRun `v0.1` 文档体系的长期规格。它定义仓库入口、长期规格位置、计划和过程材料的承载方式，以及旧 `dev/prod` 口径迁移规则。 + +## 设计目标 + +- `AGENTS.md` 是 agent、指挥官和 runner 进入 AgentRun 仓库的唯一顶级入口。 +- `docs/reference/spec-v01-*.md` 是 `v0.1` 微服务、CI/CD、CLI、运行面和系统能力的权威规格。 +- `docs/reference/` 只保存长期稳定、可复用的规格、边界、入口、判定标准和稳定 runbook。 +- 计划、阶段拆解、一次性排障、临时报告和执行证据进入 GitHub issue 或 PR 评论，不直接沉淀为仓库长期文档。 +- `docs/` 根目录不得堆放 Markdown 报告或 JSON dump；机器可消费契约应放入未来的 `protocol/`、`deploy/` 或源码相邻目录，临时输出放 `/tmp`、`.state` 或 CI artifact。 +- 旧 `dev/prod` 管理说法不再作为当前规格；AgentRun 从 `v0.1` 开始按 `v0.1`、`v0.2`、`v0.3` 版本 lane 滚动。 + +## 允许的文档形态 + +| 位置 | 允许内容 | 不允许内容 | +| --- | --- | --- | +| `AGENTS.md` | 顶级入口、一句话 P0 规则、长期参考链接 | 详细设计、阶段计划全文、临时结论、过程流水账 | +| `docs/reference/*.md` | 长期规格、稳定边界、判定标准、可复用 runbook | 日期化报告、一次性排障全文、临时 evidence、旧规格副本 | +| `docs/reference/spec-v01-*.md` | `v0.1` 当前权威规格 | 与 `v0.1` 无关的 `v0.2+` 计划全文、未蒸馏过程材料 | +| GitHub issue/PR | 计划、里程碑、过程记录、执行证据、实现任务 | 替代 `docs/reference` 成为长期唯一权威 | +| `/tmp` / `.state` / CI artifact | 临时输出、trace、日志、报告、截图 | 需要长期复用的规格或入口 | + +## Spec 命名规则 + +- `spec-v01-documentation-governance.md`：文档治理和旧口径迁移。 +- `spec-v01-services.md`：服务总览、保留和 deferred 对象。 +- `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。 +- 未来新增单服务规格必须使用 `spec-v01-.md`，例如 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`。 +- `v0.2` 或更高版本的规格不得写入 `spec-v01-*`；只能在对应版本 lane 中创建自己的 `spec-v02-*`、`spec-v03-*`。 + +## 迁移规则 + +1. 发现 `README.md`、`docs/*.md`、`docs/*.json` 或计划文档时，先判断是否有长期价值。 +2. 有长期价值的，只把稳定结论吸收到对应 `docs/reference/spec-v01-*.md`；不要整篇搬入 reference。 +3. 属于计划、里程碑、阶段迁移、报告、一次性排障或历史验收的，全文迁入 GitHub issue 或 PR 评论，再删除源文件。 +4. 与 `v0.1` 规格冲突的旧 `dev/prod`、`/root/agentrun` 默认工作区、`agentrun_dev`、`agentrun_prod` 说法必须删除或改为历史背景。 +5. 未实现规格必须在对应 spec 的“规格的实现情况”中明确写成 `未实现` 或 `未完全实现`，不要用散落 TODO 代替。 + +## v0.1 当前权威入口 + +- Source branch：`v0.1`。 +- Source workspace：`G14:/root/agentrun-v01`。 +- Worktree 根：`G14:/root/agentrun-v01/.worktree/{task}`。 +- Runtime namespace：`agentrun-v01`。 +- 发布和验收规格：[spec-v01-cicd.md](spec-v01-cicd.md)。 +- 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。 + +## 验收标准 + +- `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。 +- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md` 和 `spec-v01-cicd.md`。 +- `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前工作区、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。 +- `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。 +- 后续实现任务先更新或引用对应 `spec-v01-*`，再修改代码和测试。 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md new file mode 100644 index 0000000..8040297 --- /dev/null +++ b/docs/reference/spec-v01-services.md @@ -0,0 +1,99 @@ +# v0.1 服务总体规格 + +本文是 AgentRun `v0.1` 服务总览和取舍规格。它定义 `v0.1` lane 中哪些组件必须保留，哪些只作为 deferred 方向，以及单服务规格的后续拆分边界。 + +`docs/reference/spec-v01-*.md` 是 `v0.1` 服务、CLI、CI/CD 和系统能力的权威出处。代码开发和测试编写必须先对齐对应 spec，再修改实现或测试。 + +## 在系统中的职责划分 + +AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`v0.1` 只做最小纵向闭环，不替换 UniDesk Code Queue，也不替换 HWLAB 现有 Code Agent 路径。 + +- `agentrun-mgr` 是公共 RESTful API 和 durable facts authority，负责 run、command、event、runner、backend、lease 的持久状态和鉴权前置边界。 +- `agentrun-runner` 是短生命周期 per-run 或 per-attempt 执行者，必须从 manager claim run，并把 event、heartbeat 和 terminal status 写回 manager。 +- Backend adapter 隐藏具体 Agent 工具协议，`v0.1` 只要求一个真实 Agent backend 形成闭环；其他 backend 不进入第一波实现。 +- AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。 +- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。 + +## 内部架构 + +`v0.1` 的最小链路如下： + +```text +UniDesk or HWLAB client +-> agentrun-mgr REST API +-> durable run / command / event store +-> manual runner start +-> agentrun-runner +-> one backend adapter +-> normalized events / terminal status +-> agentrun-mgr +``` + +Runner inbound API 只允许本地或私有诊断，不作为业务客户端入口。业务客户端只能调用 `agentrun-mgr`。 + +## 服务总表 + +| 对象 | 类型 | v0.1 处理 | 说明 | 后续单独 spec | +| --- | --- | --- | --- | --- | +| `agentrun-mgr` | 长驻服务 | 保留，P0 | 公共 RESTful API、durable facts、idempotency、runner claim、event append 和 status authority。 | `spec-v01-agentrun-mgr.md` | +| `agentrun-runner` | 短生命周期执行入口 | 保留，P0 | per-run/per-attempt executor；claim run、poll command、调用 backend、写回 events/status。 | `spec-v01-agentrun-runner.md` | +| Backend adapter | 执行适配层 | 保留，P0 | 统一 backend capability、event normalization、error mapping 和 credential boundary。 | `spec-v01-backend-adapter.md` | +| First real backend | 具体 Agent backend | 保留，P0 | `v0.1` 必须至少证明一个真实 Agent backend；默认候选是 Codex。 | `spec-v01-backend-codex.md` | +| AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` | +| Durable store | 数据存储 | 保留，P0 | 保存 runs、commands、events、runners、backends、leases；具体存储可从 file/sqlite/Postgres 起步，但必须有迁移边界。 | `spec-v01-state-store.md` | +| Tenant policy boundary | 系统能力 | 保留，P0 | 显式承载 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy、traceSink。 | `spec-v01-tenant-policy.md` | +| Observability | 系统能力 | 保留，P1 | event、trace、log、redaction、terminal status 和 failure kind 统一观察。 | `spec-v01-observability.md` | +| `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` | +| 多 backend 路由 | 系统能力 | Deferred | `v0.1` 不做完整多 backend 调度，只保留 capability 模型。 | 后续版本 spec | +| UI | 前端 | Deferred | `v0.1` 不要求独立 UI；UniDesk/HWLAB canary 可通过 CLI/API 验证。 | 后续版本 spec | +| judge/retry 自动化 | 系统能力 | Deferred | `v0.1` 只定义基础 terminal 和 failure visibility，不实现复杂 judge。 | 后续版本 spec | + +## API 接口说明 + +Manager 公共 API 的 `v0.1` 初始范围： + +```http +POST /api/v1/runs +GET /api/v1/runs/:runId +GET /api/v1/runs/:runId/events?afterSeq=0&limit=100 +POST /api/v1/runs/:runId/commands +GET /api/v1/runs/:runId/commands/:commandId +GET /api/v1/backends +``` + +Runner 到 manager 的私有 API 的 `v0.1` 初始范围： + +```http +POST /api/v1/runners/register +POST /api/v1/runs/:runId/claim +PATCH /api/v1/runs/:runId/lease +GET /api/v1/runs/:runId/commands?afterSeq=0&limit=20 +POST /api/v1/runs/:runId/events +PATCH /api/v1/runs/:runId/status +POST /api/v1/commands/:commandId/ack +``` + +`v0.1` 禁止用 SSE、WebSocket、long-polling 或长同步 `turn` 请求替代 durable resource 模型。客户端通过分页轮询观察进度。 + +## MVP 分期 + +| 阶段 | 目标 | 验收重点 | +| --- | --- | --- | +| M0 | 契约骨架 | Run/Command/Event/Runner/Backend 资源模型和状态机可读。 | +| M1 | 最小 runner + 一个 backend | 一个 turn 经过真实 backend，assistant/output/error/terminal events 被归一化。 | +| M2 | manager + runner claim | run create/query durable，claim 拒绝双 owner，events append-only。 | +| M3 | 手动 dispatch CLI | CLI 快速返回 runner process/job identity、log path 和轮询命令。 | +| M4 | 自动 scheduler | Deferred；pending 自动派发和 stale lease recovery 进入后续实现。 | +| M5 | UniDesk/HWLAB canary | Deferred；只在核心生命周期稳定后接入窄范围 canary。 | + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| `v0.1` 服务总体规格 | 已定义 | 本文定义服务总览和取舍表。 | +| 文档治理规格 | 已定义 | 见 [spec-v01-documentation-governance.md](spec-v01-documentation-governance.md)。 | +| CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 | +| `agentrun-mgr` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | +| `agentrun-runner` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 | +| 第一真实 backend | 未实现 | 默认候选 Codex，需后续 backend spec。 | +| 自动 scheduler | Deferred | 不作为 `v0.1` 第一阶段验收目标。 |