docs: 固化 OA 规格收编收尾规则
This commit is contained in:
Codex
+10
-13
@@ -1,6 +1,6 @@
|
||||
# AgentRun 开发与运维参考
|
||||
|
||||
本文只记录 UniDesk 侧对独立仓库 `pikasTech/agentrun` 的开发与运维约束。AgentRun 作为 HWLAB Agent 编排执行基础设施时，需求规格正文由 UniDesk OA 管理，入口是 [PJ2026-0102 Agent编排](../../project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md)。AgentRun 仓库内 `docs/reference/spec-v01-*.md` 只保留到 OA 规格的交叉引用 stub；实现细节、源码组织和仓库本地运行说明仍维护在 AgentRun 仓库自身。
|
||||
本文只记录 UniDesk 侧对独立仓库 `pikasTech/agentrun` 的开发与运维约束。AgentRun 作为 HWLAB Agent 编排执行基础设施时，需求规格正文由 UniDesk OA 管理，入口是 [PJ2026-0102 Agent编排](../../project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md)。AgentRun 仓库内 `docs/reference/spec-v01-*.md` 和 `docs/reference/architecture.md` 只保留到 OA 规格的交叉引用 stub；实现细节、源码组织和仓库本地运行说明仍维护在 AgentRun 仓库自身。
|
||||
|
||||
## 仓库与 Worktree
|
||||
|
||||
@@ -43,7 +43,7 @@ G14:/root/agentrun-v01/.worktree/{pr_branch}
|
||||
|
||||
## 文档落库规则
|
||||
|
||||
AgentRun 仓库内长期参考和 `spec-v01-*` 交叉引用 stub 变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.1`。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。
|
||||
AgentRun 仓库内长期参考、`spec-v01-*` 和 `architecture.md` 交叉引用 stub 变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.1`。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。
|
||||
|
||||
## 部署目标
|
||||
|
||||
@@ -114,19 +114,16 @@ UniDesk 是 AgentRun 的综合分布式开发和运维中心。UniDesk 可以记
|
||||
- G14 预检、route 语法和远程操作入口；
|
||||
- `v0.1` 固定 namespace 与后续版本 lane 规则；
|
||||
- 部署观察、受控 rollout 和运维入口；
|
||||
- AgentRun 仓库定义公共契约后，UniDesk 与 HWLAB 如何接入。
|
||||
- UniDesk OA 定义公共契约后，UniDesk 与 HWLAB 如何接入。
|
||||
|
||||
UniDesk 不能作为以下内容的事实来源：
|
||||
UniDesk reference 不能作为 AgentRun repo 内部实现细节的事实来源：
|
||||
|
||||
- AgentRun 服务架构；
|
||||
- MVP 阶段规划；
|
||||
- RESTful API 契约；
|
||||
- runner/backend 协议；
|
||||
- 数据库 schema；
|
||||
- tenant policy 模型；
|
||||
- backend adapter 设计。
|
||||
- 源码目录、模块组织和本地调试命令；
|
||||
- repo-owned helper、runner 启动脚本和 runbook 的参数细节；
|
||||
- 只服务 AgentRun 内部开发的一次性排障步骤；
|
||||
- 数据库 migration 文件内容、源码实现和内部测试夹具。
|
||||
|
||||
这些实现侧内容必须维护在 AgentRun 仓库自己的 `AGENTS.md` 和非 SPEC 长期参考中；HWLAB-facing 需求规格正文必须维护在 UniDesk OA。
|
||||
AgentRun 的产品边界、REST resource/API 语义、run/command/event/session/queue、backend adapter/profile、runtime assembly、发布流水、源码同步和 HWLAB 接入等面向 HWLAB/UniDesk 的需求规格维护在 UniDesk OA。AgentRun repo 的 reference 可以说明如何运行、调试和实现这些能力，但不能把需求规格正文重新写回 repo。
|
||||
|
||||
## AgentRun Queue 与旧 Code Queue 边界
|
||||
|
||||
@@ -136,7 +133,7 @@ UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|de
|
||||
|
||||
资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
|
||||
AgentRun 公网 HTTPS 入口、FRP/Caddy edge、direct REST base URL 和鉴权来源都由 UniDesk `config/agentrun.yaml` 声明。YAML-only lane 不允许把这些部署选择写回 AgentRun source branch 的 `deploy/deploy.json`；AgentRun source repo 只保留应用代码、构建输入和 AgentRun 自身契约。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责按 UniDesk YAML 补 edge 侧 allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
|
||||
AgentRun 公网 HTTPS 入口、FRP/Caddy edge、direct REST base URL 和鉴权来源都由 UniDesk `config/agentrun.yaml` 声明。YAML-only lane 不允许把这些部署选择写回 AgentRun source branch 的 `deploy/deploy.json`；AgentRun source repo 只保留应用代码、构建输入和 repo 内部实现文档。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责按 UniDesk YAML 补 edge 侧 allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
|
||||
|
||||
AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `unidesk-ssh`，长期契约以 UniDesk OA 的 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 和 [YAML运维](../../project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md) 为准：调用方通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `UNIDESK_SSH_CLIENT_TOKEN` SecretRef；非敏感 endpoint 由 runner-job `transientEnv` 显式提供，或由 manager 受控默认值自动补齐。UniDesk bridge 提交 Queue payload 时不得在 prompt、payload 或 `transientEnv` 中携带 token，也不得使用 HWLAB runtime Web 入口冒充 UniDesk frontend。若 dispatcher 已正确请求 `unidesk-ssh` 但 trace 的 `runner-job-created.transientEnv.names` 没有 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`，归为 AgentRun assembly 问题；若 endpoint env 已存在但 route denied/timeout，再按 UniDesk frontend/token scope 或 provider session 排查。
|
||||
|
||||
|
||||
@@ -25,6 +25,14 @@
|
||||
|
||||
`pikasTech/unidesk#20` 只记录 UniDesk 侧 commander、Code Queue、CLI 和 infra governance。HWLAB 用户反馈、Cloud Workbench、DEV-LIVE、M3 闭环和其他产品事项必须写入 `pikasTech/HWLAB` 的 issue；如果需要在 #20 出现，只能作为 UniDesk 侧调度、CLI guard、infra blocker 或验收治理 lane 的上下文，而不能作为 HWLAB 产品 row。
|
||||
|
||||
## 规格真相与仓库 Reference 边界
|
||||
|
||||
HWLAB 需求规格的唯一长期正文在 UniDesk OA `project-management/PJ2026-01/specs/`。L0 总规格、硬件池、Agent编排、HarnessRL、客户端、用户管理、平台运维及其 L2/L3 都从这里索引；HWLAB repo 的 issue、PR、runtime reference 和阶段验证 issue 只能承载执行讨论、证据和操作入口，不能重新定义需求。
|
||||
|
||||
HWLAB v0.2/v0.3 仓库内 `docs/reference/spec-*`，以及已收编的 `cloud-workbench.md`、`code-agent-chat-readiness.md`、`g14-gitops-cicd.md` / `node-gitops-cicd.md`、`dev-runtime-boundary.md`、`gateway-outbound-demo.md`、`MVP-e2e-acceptance.md`、`architecture.md` 只保留到 UniDesk OA 的交叉引用或历史 stub。repo-local runbook 可以继续说明命令、路径、lane 和调试入口，但不得把公开能力、CLI/API 语义、测试大纲、Gateway 主动出站或 AgentRun 接入要求写成第二份规格正文。
|
||||
|
||||
公开入口、FRP/Caddy/域名和 Web/API 可达性需求以 [PJ2026-010604 公开入口](../../project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md) 为权威；Prometheus、日志、trace、health、status 和运维监控需求以 [PJ2026-010605 可观测监控](../../project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md) 为权威。运行配置数值仍以 UniDesk YAML 和目标 HWLAB repo 的受控配置为准，长期 reference 只记录解析与验证方法。
|
||||
|
||||
## DEV 入口
|
||||
|
||||
- 退役 G14 DEV/PROD 前端/API 入口曾使用 `http://74.48.78.17:17666/`、`http://74.48.78.17:17667/health/live`、`http://74.48.78.17:18666/` 和 `http://74.48.78.17:18667/health/live`；这些端口不再作为当前 HWLAB runtime 证据。
|
||||
@@ -152,7 +160,7 @@ AgentRun `v0.1` 运行面物化对象是 `agentrun-v01` namespace 中的 `agentr
|
||||
|
||||
profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web dispatcher 路径创建 Code Agent session 并完成一轮真实 turn：`client agent session create --provider-profile <profile>`，再 `client agent send --session-id <sessionId> --provider-profile <profile>`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认终端状态和最终 assistant 文本。只看到 Secret 存在、AgentRun canary 通过、PipelineRun 成功或源码测试通过，都不能替代这一真实入口验收。对 profile-sensitive CaseRun 或 provider 修复，关闭证据还必须来自原入口 `case run`/Web 等价路径，结果中应同时显示 `requestedProviderProfile`、`resolvedBackendProfile`、AgentRun `backendProfile`、模型名和终端状态；涉及 ds-flash/Moon Bridge 时，还要确认 `deepseek-v4-flash`、1M context/model catalog 元数据生效，且归档中不再出现 `responses/compact 404` 或 `404 page not found`。当前 HY 凭据对的稳定 profile 名是 `hy`；复测时使用同一标准入口，不在任何长期文档或 issue 中记录凭据内容。
|
||||
|
||||
CaseRun 的 prompt 组装、tools-only resource bundle、skill/reference 读取边界、trace 归档和 case registry 证据形态属于 HWLAB 仓库内 `docs/reference/spec-hwpod-harness.md` 的权威范围；UniDesk 指挥侧只负责按 issue/CLI 选中的 node/lane 重新读取 HWLAB `AGENTS.md`、使用目标 workspace 原入口验证，并在关闭 issue 时记录 runId、traceId、provider profile、registry commit 和负向检索摘要。不要在 UniDesk reference 里复写 CaseRun prompt 细则或 `.agents/skills` 装配实现，避免与 HWLAB runtime lane 真相分叉。
|
||||
CaseRun 的 case/registry/aggregate、评价、回放、训练反馈和硬件证据闭环需求以 UniDesk OA 的 [PJ2026-0103 HarnessRL](../../project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md) 为权威；HWPOD 服务、AI 网关和 HWLAB 到 AgentRun 的装配接入分别以 [PJ2026-010103 HWPOD服务](../../project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md)、[PJ2026-010104 AI网关](../../project-management/PJ2026-01/specs/PJ2026-010104-ai-gateway.md) 和 [PJ2026-010205 HWLAB接入](../../project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md) 为权威。HWLAB 仓库内 `docs/reference/spec-hwpod-harness.md` 只保留历史交叉引用 stub；UniDesk 指挥侧按 issue/CLI 选中的 node/lane 重新读取 HWLAB `AGENTS.md`、使用目标 workspace 原入口验证，并在关闭 issue 时记录 runId、traceId、provider profile、registry commit 和负向检索摘要。不要在 UniDesk reference 里复写 CaseRun prompt 细则或 `.agents/skills` 装配实现。
|
||||
|
||||
CaseRun skill 交付边界按 `docs/reference/agentrun.md#agentrun--hwlab-协同职责边界` 判定：专用 skill 通过 AgentRun `gitbundle` 装配给 Code Agent，subject repo 不能携带 `.agents/skills` 副本。关闭要求涉及 skill 的 case 时，除 runId、traceId、provider profile 和 registry commit 外，还应记录 `resourceBundlePolicy`、实际装配的 skill 名、AgentRun/CaseRun 归档中的 skill 读取证据，以及 subject repo diff 或 artifact 中没有新增 `.agents/skills` 的负向检索结果。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user