From a53f5b8a0d488c59c321e4fc7cf2f6ae5c58e05c Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 2 Jun 2026 19:59:49 +0800 Subject: [PATCH] docs: specify resource prompt and skill assembly --- AGENTS.md | 2 +- docs/reference/spec-v01-agentrun-runner.md | 27 ++++++- docs/reference/spec-v01-backend-codex.md | 10 ++- .../spec-v01-hwlab-manual-dispatch.md | 56 ++++++++++++- docs/reference/spec-v01-runtime-assembly.md | 78 +++++++++++++++++-- docs/reference/spec-v01-validation.md | 6 +- 6 files changed, 161 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fd78419..06dd6d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,7 +55,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、source worktree、git mirror、env reuse、namespace、GitOps、registry、CI/CD 和发布验收规格。 - `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。 - `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。 -- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、Git-only ResourceBundleRef 和 tool credential SecretRef scope。 +- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、Git-only ResourceBundleRef、resource-scoped `toolAliases`/`promptRefs`/`skillRefs` 和 tool credential SecretRef scope。 - `docs/reference/spec-v01-queue.md`：v0.1 AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 边界和验收规格。 - `docs/reference/spec-v01-hwlab-manual-dispatch.md`：v0.1 通过手动调度 API 为 HWLAB v0.2 提供 canary Code Agent 服务的目标、缺口和增强计划。 - `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。 diff --git a/docs/reference/spec-v01-agentrun-runner.md b/docs/reference/spec-v01-agentrun-runner.md index 314a902..1a76ed1 100644 --- a/docs/reference/spec-v01-agentrun-runner.md +++ b/docs/reference/spec-v01-agentrun-runner.md @@ -30,7 +30,25 @@ Runner Secret 只能通过 Kubernetes Secret projection、ServiceAccount/RBAC Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secret volume 只读挂在 `/var/run/agentrun/secrets/...`，`/home/agentrun` 由 `emptyDir` 提供可写空间，`CODEX_HOME` 指向当前 run/profile 的 writable runtime home，`AGENTRUN_CODEX_SECRET_HOME` 指向当前 `backendProfile` 对应的只读 projection。runner/backend 在启动 provider 前只复制授权文件，不打印内容。`codex`、`deepseek` 与 `minimax-m3` profile 不得共享同一个可写 runtime home，除非它们运行在不同的 per-run Kubernetes Job 且该目录由 Job 独占 emptyDir 提供。 -RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 已支持把 `repoUrl + full commitId` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。 +RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 已支持把 `repoUrl + full commitId` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。`toolAliases`、`promptRefs` 和 `skillRefs` 都属于该 Git-only bundle 的非敏感子资源：runner 必须在同一 checkout 中解析、校验和装配，不能从镜像默认目录、host path、旧 prompt 常量或用户长 prompt 中补齐。 + +### ResourceBundle 子资源装配 + +Runner materialize `ResourceBundleRef` 后必须按固定顺序处理子资源：先创建 `toolAliases` wrapper，再装配 `skillRefs` registry，最后读取 `promptRefs` 并生成当前 command 的 assembled initial prompt 摘要。任何子资源缺失或非法都必须按对应 failureKind 阻塞当前 command，不得继续运行后让模型自行猜测。 + +`skillRefs` 聚合规则： + +- 聚合目录默认在 materialized workspace 下的 `.agents/skills`，每个 skill 使用稳定目录名，例如 `.agents/skills//SKILL.md`。 +- Runner 必须把该聚合目录通过环境或 backend option 暴露给 Codex runtime；对于需要兼容 Codex skill discovery 的实现，应设置 `AGENTRUN_SKILLS_DIRS` 或等价字段，并可同步设置业务方约定的 `_CODE_AGENT_SKILLS_DIRS`。 +- 聚合只允许 symlink 或 copy 当前 bundle 内的 skill root，不允许引用 `/app/skills`、host path、Secret volume 或用户上传临时目录。 +- Event/result 只输出 skill name、manifest path 摘要、hash、bytes、version/commit metadata、required 和 aggregate target。 + +`promptRefs` 装配规则： + +- Runner 只读取当前 bundle 内的 prompt 文件，按数组顺序生成 `initialPrompt`。 +- 对没有 `threadId`、将执行 `thread/start` 的第一条 turn，runner/backend 必须把 `initialPrompt` 注入到该 turn 的输入前缀，并记录 `initialPromptInjected=true`。 +- 对已有 `SessionRef.threadId` 或 command `payload.threadId`、将执行 `thread/resume` 的 turn，runner/backend 不得重复注入 `initialPrompt`，必须记录 `initialPromptInjected=false` 和 `reason=thread-resume`。 +- `initialPrompt` 不得包含会话历史；用户本轮 message 仍来自 command payload 原文。 ## HWLAB v0.2 执行经验承接 @@ -42,6 +60,7 @@ Runner 承接的是 HWLAB v0.2 原有 Code Agent 的执行层经验，不承接 | cancel/interrupt | `internal/cloud/server-code-agent-http.ts`、`internal/cloud/codex-stdio-session.ts` | runner 必须轮询 manager cancel 状态并中止 backend；backend 不支持精确 interrupt 时终止受控进程组。 | | runnerTrace 事件可见性 | `internal/cloud/code-agent-trace-store.ts` | backend 输出必须转成 manager events；每个 terminal/错误/取消都要有事件和 final status。 | | workspace-write 边界 | `internal/cloud/code-agent-contract.ts` | runner 只使用 ResourceBundleRef materialized workspace，不猜 HWLAB Pod 的 `/workspace/hwlab` 或 host path。 | +| prompt/skill 装配 | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/codex-stdio-session-helpers.ts` | HWLAB 旧业务 prompt 与 skill discovery 经验迁入 ResourceBundleRef `promptRefs`/`skillRefs`；runner 只按 Git commit/path 装配，不内建 HWLAB 业务。 | | Secret 与 writable CODEX_HOME 分离 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | profile Secret 只读投影，复制到当前 run/profile writable runtime home；不同 profile 不共享 runtime home。 | | bounded stdout/stderr | `docs/reference/code-agent-chat-readiness.md` | `command_output` 记录摘要、字节数、截断标记和必要引用；不得把大输出直接塞进单个 event/result。 | @@ -142,6 +161,10 @@ HWLAB v0.2 原有 Code Agent 在 cloud-api 进程内执行，失败时依赖本 阅读本文和 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)，然后在同一 run 中提交两条 `turn` command，只启动一次 runner Job。确认第一条 completed 后 run 仍为 non-terminal，runner 在 idle timeout 内处理第二条 command，`resource-bundle-materialized` 只记录一次，两个 command result 按 commandId 独立返回 reply/terminal。 +### T7 Resource prompt/skill 装配 + +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后创建一个带 `ResourceBundleRef.promptRefs`、`skillRefs` 和 `toolAliases` 的真实或自测试 run。确认 runner 从同一 full commit checkout 装配 prompt、skill 和工具 alias；新 thread 首轮显示 `initialPromptInjected=true`，assistant 能看见 required skill 摘要；第二轮 resume 显示 `initialPromptInjected=false`，且没有拼接第一轮历史 prompt。删除 required skill 或 prompt 后，command 必须 blocked 为 `skill-unavailable` 或 `prompt-unavailable`。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 | @@ -151,7 +174,7 @@ HWLAB v0.2 原有 Code Agent 在 cloud-api 进程内执行，失败时依赖本 | host process runner | 已实现 | `runner start` 和 `src/runner/main.ts` 进入同一套 `runOnce`，可通过 manager register/claim/poll/report 执行自测试，并支持 `--one-shot` 或 idle timeout 控制。 | | claim/lease/report client | 已实现 | 已拆出 runner manager API client，覆盖 register、claim、lease heartbeat、poll command、ack、append event、command status 和必要 run status；live runtime 通过 manager 写入 Postgres durable store。 | | cancel observation | 已实现最小闭环 | runner 在 backend 执行期间轮询 run/command cancel，触发 AbortController 中止 Codex stdio backend，并按 `cancelled` 上报 command/run 终态。 | -| SessionRef/ResourceBundleRef 消费 | 已实现最小闭环 | runner 会使用 run 中的 SessionRef threadId 执行 resume，并 materialize Git-only ResourceBundleRef 到隔离 workspace 后再启动 backend。 | +| SessionRef/ResourceBundleRef 消费 | 已实现最小闭环/待 promptRefs 与 skillRefs | runner 会使用 run 中的 SessionRef threadId 执行 resume，并 materialize Git-only ResourceBundleRef 到隔离 workspace 后再启动 backend；`toolAliases` 已实现，`promptRefs` 和 `skillRefs` 装配按本规格待补齐。 | | 同 run/runner 多 turn | 已实现最小闭环 | runner 在同一 Job 中 materialize bundle 一次后循环 poll command；普通 turn completed 只终结 command，run 保持可继续接后续 turn，直到 idle timeout 或 run terminal。 | | runner redaction | 已实现主路径 | runner/backend event 和 Job 输出使用 redaction；复杂审计仍按 [spec-v01-validation.md](spec-v01-validation.md) 的人工验收抽查。 | | `deepseek` profile runner selection | 已实现/已通过主闭环 | Runner Job 和 host runner 已按 run `backendProfile` 选择 matching SecretRef、projection、`CODEX_HOME` 和 backend metadata；真实 Kubernetes Job 已完成 `codex -> deepseek -> codex` 切换联调。 | diff --git a/docs/reference/spec-v01-backend-codex.md b/docs/reference/spec-v01-backend-codex.md index ed1007b..4f17e1f 100644 --- a/docs/reference/spec-v01-backend-codex.md +++ b/docs/reference/spec-v01-backend-codex.md @@ -20,6 +20,8 @@ codex app-server --listen stdio:// Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行读取 JSON-RPC response 和 notification，stderr 只作为有界诊断日志。最小请求序列是 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；response 中必须提取 thread/turn identity，notification 和后续输出必须归一化为 `backend_status`、`assistant_message`、`tool_call`、`command_output`、`error` 和 `terminal_status` events。运行中 steer 使用同一 app-server 进程的 `turn/steer` JSON-RPC 方法，参数为 `threadId`、`expectedTurnId` 和文本 `input` 数组；取消/中断使用 `turn/interrupt`，参数为 `threadId` 和 `turnId`。已有 `SessionRef.threadId` 时只能执行 Codex stdio 原生 `thread/resume` 后接 `turn/start`；当 `thread/resume` 返回 `no rollout found for thread id` 或任何其他协议错误时，adapter 必须输出 `thread-resume-failed` 并终止当前 turn。adapter 不得启动替代 `thread/start`、拼接历史 prompt、回写新 threadId 或用其他上下文模拟继续会话。 +若 run 的 `ResourceBundleRef` 包含 `promptRefs` 或 `skillRefs`，Codex adapter 只能消费 runner 已装配好的有界 `initialPrompt`、skill summary 和 skill registry path。对新 thread，adapter 在首个 `turn/start` 中把 `initialPrompt` 和 skill facts 放在用户 message 之前；对 `thread/resume`，adapter 不重复注入 `initialPrompt`，只发送当前 command 的用户 message。当前 Codex app-server 若只有 `input: [{ type: "text", text }]`，允许使用结构化文本前缀承载 initial prompt；若后续 app-server 支持 developer/runtime instruction item，优先映射到该标准 item。无论哪种 wire shape，events 只记录 prompt/skill 的 path/hash/bytes/injected 状态，不输出全文。 + 不得把以下路径作为 `v0.1` Codex stdio backend 的正式实现或综合联调通过证据：直接 Responses HTTP 代理、OpenAI SDK wrapper、`codex exec` 一次性命令输出、fake provider、固定文本回复、只读 shortcut 或本地 shell 模拟。裸 HTTP 或 `codex exec --json` 可以作为 provider/upstream 诊断，但最终通过必须来自 app-server stdio turn。 实现必须参考成熟代码： @@ -35,6 +37,8 @@ Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行 这些参考用于协议和质量标准，不复制 UniDesk/HWLAB 的业务 prompt、硬件路径、tenant policy、hostPath Secret 做法或任何明文密钥。 +业务 prompt 与 skill 迁移必须通过 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 的 `ResourceBundleRef.promptRefs` 和 `skillRefs` 完成。Codex backend 不内建 HWLAB 或 UniDesk 的业务文本；缺少 required prompt/skill 时必须由 runner/manager 返回装配 blocker，不能落到 Codex 默认 skill 列表、用户长 prompt 或文本 fallback。 + ## v0.1 Profile 定义 | backendProfile | SecretRef | 配置来源 | 规则 | @@ -130,13 +134,17 @@ Run 的 `executionPolicy.secretScope` 应引用与 `backendProfile` 匹配的 pr 阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后构造一个带旧 `SessionRef.threadId` 的真实或 fake app-server run，使 `thread/resume` 返回 `no rollout found for thread id`。确认 adapter 输出 `thread-resume-failed` 并终止当前 turn；events/result/sessionRef 不得出现 `thread/resume:non-resumable`、替代 `thread/start`、新 threadId 回写或历史 prompt 拼接。确认 provider auth、rate limit、model config 或其他 protocol error 仍按各自 failureKind 直接失败，不走替代路径。 +### T8 Initial prompt and skill refs + +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 fake app-server 或真实 Codex stdio run 验证 `ResourceBundleRef.promptRefs` 与 `skillRefs`。首轮无 threadId 时，`turn/start` input 必须包含 initial prompt 与 skill facts，并记录 `initialPromptInjected=true`；第二轮带同一 `threadId` resume 时，`turn/start` input 只能包含当前用户 message，记录 `initialPromptInjected=false`，且不得拼接第一轮 prompt、assistant 回复或旧 skill facts。required prompt/skill 缺失时不得调用 Codex provider。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 | | --- | --- | --- | | Codex stdio backend/profile 规格 | 已定义 | 本文为 v0.1 Codex app-server stdio backend kind 和 profile 权威。 | | Codex Secret projection | 已实现/已通过主闭环 | runner Job 使用只读 Secret projection 和 writable `CODEX_HOME`，Codex 测试凭据来自 `agentrun-v01-provider-codex` 的 `auth.json`/`config.toml`。 | -| Codex adapter | 已实现/已通过主闭环 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stale rollout `thread-resume-failed`、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx/invalid tool-call availability failureKind，以及包含 retry error notification 的 fake app-server 自测试。 | +| Codex adapter | 已实现主路径/待 initial prompt 与 skill refs 接入 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stale rollout `thread-resume-failed`、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx/invalid tool-call availability failureKind，以及包含 retry error notification 的 fake app-server 自测试；`ResourceBundleRef.promptRefs` thread-start 注入和 `skillRefs` facts/registry 消费待实现。 | | 错误可观测与脱敏 | 已实现主路径 | child env、cwd、workspace 和 Codex home 只输出摘要；stderr tail 有界且标记截断；事件和 failure 统一走 redaction。 | | 真实 provider turn | 已通过主闭环 | 真实 Codex provider turn 已经通过 RESTful API 和 CLI 综合联调；每次发布仍按 [spec-v01-validation.md](spec-v01-validation.md) 手动复验。 | | `deepseek` profile | 已实现/已通过主闭环 | 代码已支持 `agentrun-v01-provider-deepseek`、独立 `CODEX_HOME`、同一 `codex app-server --listen stdio://` 协议和 profile metadata；真实 Kubernetes SecretRef、runner Job 和 Codex stdio turn 已通过主闭环。 | diff --git a/docs/reference/spec-v01-hwlab-manual-dispatch.md b/docs/reference/spec-v01-hwlab-manual-dispatch.md index 3a48f57..707448d 100644 --- a/docs/reference/spec-v01-hwlab-manual-dispatch.md +++ b/docs/reference/spec-v01-hwlab-manual-dispatch.md @@ -48,6 +48,8 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执 | 取消正在执行的 turn | `internal/cloud/server-code-agent-http.ts`、`internal/cloud/codex-stdio-session.ts` | durable run/command cancel、pending 阻止启动、running interrupt、terminal 幂等返回 | [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | conversation/session/thread 复用 | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/code-agent-session-registry.ts` | `SessionRef` 保存 session/thread 摘要；同一 run/runner Job 处理后续 command，不重新 materialize bundle；runner 内每 turn 有 thread 则 resume，无 thread 则 start | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | 固定 repo workspace 执行 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | `ResourceBundleRef` 使用 Git-only `repoUrl + full commitId` checkout 到隔离 workspace | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | +| 初始业务 prompt 注入 | `internal/cloud/codex-stdio-session.ts` 的 boundary instructions、`internal/cloud/codex-stdio-session-helpers.ts` 的 `buildCodexUserPrompt()` | HWLAB 把稳定业务 instruction 文件放入同一 Git bundle，并通过 `ResourceBundleRef.promptRefs` 指定；AgentRun 只在新 thread 首轮注入，resume 不重复注入 | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) | +| skill discovery 与 skill facts | `internal/cloud/skills-store.ts`、`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 和 `codexSidecarSkillsPrompt()` | HWLAB 把 required skill manifest 放入同一 Git bundle，并通过 `ResourceBundleRef.skillRefs` 指定；AgentRun 聚合到 runner workspace skill registry 并向 Codex 暴露有界 skill facts | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | provider profile 隔离和 Secret 不泄露 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | `ProfileRef/SecretRef` profile-scoped 投影、缺失为 `secret-unavailable`、禁止 fallback 和泄露值 | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) | | device-pod 短期会话 env 注入 | `internal/cloud/server-code-agent-http.ts` 的 `codeAgentDevicePodAuthEnv()` | `runner-jobs.transientEnv` 只在本次 Kubernetes Job env 中生效；只记录 name/count，不保存或输出 value | [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) | | UniDesk SSH passthrough | HWLAB Code Agent 通过 `tran` 访问 G14/D601/HWLAB/GitHub 维护面 | `toolCredentials[].tool=unidesk-ssh` 注入 `UNIDESK_SSH_CLIENT_TOKEN`，`transientEnv` 只注入非敏感 `UNIDESK_MAIN_SERVER_IP`；UniDesk frontend 负责 route allowlist | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) | @@ -85,11 +87,14 @@ HWLAB canary 创建 run 时应使用以下字段口径： | `providerId` | `G14`，只表示目标 provider，不授予 HWLAB 业务权限。 | | `backendProfile` | `deepseek`、`codex` 或 `minimax-m3`，由 HWLAB 或调度方显式选择；缺少 matching SecretRef 必须失败，不 fallback。 | | `workspaceRef` | 必须引用 ResourceBundleRef 中的 Git-only full commit；不得由 runner 猜 host path。 | +| `resourceBundleRef.promptRefs[]` | 用于承接 HWLAB 稳定初始 prompt，例如 `hwlab-v02-runtime`、device-pod/no-fallback policy；必须来自同一 full commit，`inject=thread-start`，新 thread 首轮注入，resume 不注入。 | +| `resourceBundleRef.skillRefs[]` | 用于承接 HWLAB required skills，例如 `device-pod-cli`；必须来自同一 full commit 的 `SKILL.md`，required skill 缺失时 blocked，不能让模型默认 skill 列表替代。 | +| `resourceBundleRef.toolAliases[]` | 用于暴露短入口，例如 `hwpod`；缺 alias 时修 runner/bundle，不改走长路径 wrapper。 | | `executionPolicy` | sandbox、network、timeout、secretScope 必须显式，不得由 HWLAB 扩大 AgentRun Secret 范围。 | | `executionPolicy.secretScope.toolCredentials[]` | 需要 UniDesk SSH passthrough 时必须声明 `tool=unidesk-ssh`、`purpose=ssh-passthrough`、SecretRef `agentrun-v01-tool-unidesk-ssh`、projection env `UNIDESK_SSH_CLIENT_TOKEN`；不得把 token 放入 command payload 或 runner-job transientEnv。 | | `traceSink` | 可指向 HWLAB trace adapter；为 `null` 时 HWLAB 仍可通过 AgentRun events 轮询。 | -Command 第一阶段要求 `type=turn` 和 `type=steer`。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、device internal token 或 Secret value 写入 payload。 +Command 第一阶段要求 `type=turn` 和 `type=steer`。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；稳定业务 prompt、skill 清单和工具入口不写入 command payload，而是通过 `ResourceBundleRef.promptRefs`、`skillRefs` 和 `toolAliases` 装配。`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、device internal token、Secret value、历史消息或大段 skill manifest 写入 payload。 ## 需要补齐的能力 @@ -120,6 +125,34 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs `ResourceBundleRef` 必须按 Git-only 模型落地：`repoUrl + full commitId` 是唯一内容身份。runner 只能 checkout 到允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。第一阶段支持 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef` 的最小字段即可。HWLAB canary 只需要 `pikasTech/HWLAB` 固定 full commit 的普通 checkout；用户上传文件和对象存储 artifact 不进入 `v0.1`。 +### P1 Resource prompt/skill assembly + +HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceBundleRef` 子资源，而不是继续依赖 cloud-api 进程内硬编码 prompt、`/app/skills` 镜像目录、用户长 prompt 或 Codex 默认 skill registry。HWLAB dispatcher 创建 run 时应指定： + +```json +{ + "resourceBundleRef": { + "kind": "git", + "repoUrl": "git@github.com:pikasTech/HWLAB.git", + "commitId": "", + "toolAliases": [ + { "name": "hwpod", "path": "tools/device-pod-cli.mjs", "kind": "node-script" } + ], + "promptRefs": [ + { "name": "hwlab-v02-runtime", "path": "internal/agent/prompts/hwlab-v02-runtime.md", "inject": "thread-start", "required": true }, + { "name": "device-pod-policy", "path": "internal/agent/prompts/device-pod-policy.md", "inject": "thread-start", "required": true } + ], + "skillRefs": [ + { "name": "device-pod-cli", "path": "skills/device-pod-cli/SKILL.md", "required": true, "aggregateAs": "device-pod-cli" } + ] + } +} +``` + +这些 prompt 文件只写稳定规则，例如 HWLAB Cloud Workbench Code Agent 身份、Device Pod/D601-F103-V2/Keil/build/download/UART/debug-probe 的标准 `hwpod` 路径、禁止 lease、禁止 Cloud Web device-pod API、禁止 session-token fallback、禁止长路径 wrapper，以及历史上下文只走 Codex stdio 原生 `thread/resume`。它们不写用户本轮任务、不写会话历史、不写 Secret 或一次性 issue 过程。 + +首轮新 thread 必须自动注入这些 prompt 和 skill facts，使 Web 简短 prompt 也能识别 HWLAB 标准能力。后续 turn/resume 不重复注入；若 resume 失败，按 AgentRun Codex stdio 规则失败，不拼接历史 prompt 模拟继续。 + ## 分阶段增强计划 | 阶段 | 目标 | 主要交付 | 验收重点 | @@ -128,8 +161,9 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs | 2 | trace/result 元语 | 标准 event 子集、terminal result envelope、bounded output metadata | HWLAB 可由 events 稳定生成 result/trace；partial 不误报 completed。 | | 3 | cancel 闭环 | durable cancel API、runner cancel poll、backend interrupt/process group stop | pending/running/terminal 后 cancel 均幂等且可见。 | | 4 | ResourceBundleRef materialization | Git-only checkout、workspace 前缀、commit/tree 摘要、failureKind | 使用 full commit；不接受 branch/tag/HEAD；不覆盖 Secret/session/runtime home。 | -| 5 | SessionRef 持久化与 runner 多 turn | session record/store、thread resume、runner command loop、TTL/GC、profile 隔离 | 同一 conversation 连续两轮复用同一 run/runner Job；第二轮不重新 materialize bundle；不同 profile 不污染。 | -| 6 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；device-pod 仍由 HWLAB 授权。 | +| 5 | Resource prompt/skill assembly | `promptRefs` thread-start 注入、`skillRefs` registry 聚合、required blocker、hash/bytes 可见 | 简短 HWLAB prompt 能看到业务 instruction 和 required skill；resume 不重复注入；缺失直接 blocked。 | +| 6 | SessionRef 持久化与 runner 多 turn | session record/store、thread resume、runner command loop、TTL/GC、profile 隔离 | 同一 conversation 连续两轮复用同一 run/runner Job；第二轮不重新 materialize bundle、不重复注入 initial prompt；不同 profile 不污染。 | +| 7 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；device-pod 仍由 HWLAB 授权。 | ## 测试规格 @@ -157,6 +191,20 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs 阅读本文和 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)，然后在同一 run 中先提交第一条 turn command 并启动一次 runner Job；第一条 command completed 后，在同一 run 中提交第二条 turn command。确认第二条由同一 runner Job 在 idle timeout 内处理，run 未因第一条 completed 而 terminal，events 中 `resource-bundle-materialized` 只出现一次，两个 command result 分别可查且 reply 不互相串联。 +### T7 HWLAB prompt/skill 装配 + +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 HWLAB canary `ResourceBundleRef` 指定 `promptRefs`、`skillRefs` 和 `toolAliases`。首轮 Web/CLI 简短 prompt 只写“编译 D601-F103-V2”或等价自然语言，确认 Codex turn 能看到 HWLAB runtime prompt、`device-pod-cli` skill facts 和 `hwpod` alias；第二轮 continuation 使用同一 thread resume，确认 `initialPromptInjected=false`，没有手工拼接历史；删除 required skill/prompt 后确认 blocked 而不是 fallback 到默认 Codex 5 个系统 skill。 + +### T8 DS 短 prompt 真实验收 + +阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 HWLAB `spec-v02-hwlab-cli.md`，然后必须用正式 HWLAB CLI/Web 等价短连接入口提交真实 `backendProfile=deepseek` 的短 prompt 到 AgentRun runtime，不允许用长提示词把规则补给模型。验收至少包含三条 prompt： + +1. “不调用工具的情况下，你可见的 skill 有哪些？”确认回复包含 `ResourceBundleRef.skillRefs` 中的 HWLAB required skill，例如 `device-pod-cli`，并且不只返回 Codex 默认 5 个系统 skill。 +2. “你当前 HWLAB 初始规则里，D601-F103-V2 应该走哪个标准入口？请只回答入口和禁止路径。”确认回复能说出 `hwpod`、Cloud API/assembled env、禁止 lease、禁止 Cloud Web device-pod API、禁止 session-token fallback 和禁止长路径 wrapper。 +3. “编译 D601-F103-V2。”确认短 prompt 能按注入规则触发 `hwpod`/Device Pod 标准路径，而不是要求用户补充长 prompt。 + +上述三条必须来自真实 DS/DeepSeek profile 的 Codex stdio `thread/start`/`turn/start` 和后续 `thread/resume` 事件；trace/result 必须显示 `initialPromptInjected=true` 的首轮、skill refs 摘要、真实 provider profile、terminal status，以及 continuation 时 `initialPromptInjected=false`。如果回复只列出 Codex 默认系统 skill、不能识别 HWLAB 初始规则或需要用户长 prompt 才能触发 `hwpod`，验收失败。 + ## 实现状态 | 能力 | v0.1 状态 | 说明 | @@ -165,6 +213,6 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs | trace/result 元语 | 已实现最小合同 | 新增 run/command result envelope，聚合 terminal status、reply、failureKind、event cursor、artifact summary、attempt、SessionRef 和 ResourceBundleRef 摘要。 | | cancel | 已实现最小闭环 | 已提供 run/command cancel API；pending cancel 会阻止新 runner Job，running runner 通过轮询触发 backend abort，终态写入 event、command state 和 run status。 | | SessionRef | 已实现最小持久化 | run 可携带 `sessionRef`，manager 保存 session/thread，runner 会按 threadId resume，result envelope 暴露脱敏 session 摘要；TTL/GC 仍按后续运维策略细化。 | -| ResourceBundleRef | 已实现 Git-only materialization | run 可携带 `repoUrl + full commitId`，runner checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace 摘要；上传文件和对象存储仍不进入 v0.1。 | +| ResourceBundleRef | 已实现 Git-only materialization/待 promptRefs 与 skillRefs | run 可携带 `repoUrl + full commitId`，runner checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace 摘要；`toolAliases` 已实现；上传文件和对象存储仍不进入 v0.1；HWLAB 初始 prompt 与 skill 注入按本规格待补齐。 | | 同 run/runner 多 turn | 已实现最小闭环 | runner Job 在 idle timeout 内持续 poll 同一 run 的后续 command；普通 turn completed 不终结 run，bundle 只 materialize 一次，command result 按 commandId 独立聚合。 | | HWLAB v0.2 canary | 待实现 | 需要 HWLAB dispatcher adapter 调 AgentRun 手动调度 API，并转换 result/trace。 | diff --git a/docs/reference/spec-v01-runtime-assembly.md b/docs/reference/spec-v01-runtime-assembly.md index 73abd38..dd1af90 100644 --- a/docs/reference/spec-v01-runtime-assembly.md +++ b/docs/reference/spec-v01-runtime-assembly.md @@ -2,7 +2,7 @@ 本文是 AgentRun `v0.1` runner/backend 启动前的权威装配 SPEC。所有会进入运行时容器、进程、文件系统或环境变量的执行输入，都必须先落到本文定义的装配模型，再由 manager/runner 渲染为受控 Job 输入；不得在 CLI、Queue、runner Job、issue 过程或临时热补丁中绕过装配模型直接拼接 credential、host path 或隐式环境。 -`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile/credential scope、哪份 session、哪份代码和工具 credential。`BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 仍是四个一等运行时要素；credential 注入不是第五个杂项要素，而是挂在 `ProfileRef`、`ResourceBundleRef` 或 tool scope 上的 SecretRef 装配引用。 +`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile/credential scope、哪份 session、哪份代码、初始 prompt、skill 和工具 credential。`BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 仍是四个一等运行时要素；credential 注入不是第五个杂项要素，而是挂在 `ProfileRef`、`ResourceBundleRef` 或 tool scope 上的 SecretRef 装配引用。初始 prompt 与 skill 注入也不是第五条运行时路径，它们属于 `ResourceBundleRef` 指向的 Git-only 非敏感内容。 ## 最简四要素 @@ -13,7 +13,7 @@ | `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 | | `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件、GitHub/业务工具 credential。 | | `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 | -| `ResourceBundleRef` | `repoUrl`、`commitId` | 初始代码/文件输入；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value。 | +| `ResourceBundleRef` | `repoUrl`、`commitId`，可选 `toolAliases`、`promptRefs`、`skillRefs` | 初始代码/文件输入，以及同一 commit 下的非敏感工具别名、初始 prompt 和 skill manifest；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史。 | P0 最小 JSON 形态： @@ -29,12 +29,15 @@ P0 最小 JSON 形态： "sessionRef": null, "resourceBundleRef": { "repoUrl": "git@github.com:pikasTech/unidesk.git", - "commitId": "" + "commitId": "", + "toolAliases": [], + "promptRefs": [], + "skillRefs": [] } } ``` -`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance、resource limit 和 tool credential scope 都不是新的运行时要素；它们分别挂在四要素或 run policy 上，并且必须能追溯到 SecretRef、配置引用或显式 null/deferred 状态。 +`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance、resource limit、tool credential scope、初始 prompt 装配和 skill 装配都不是新的运行时要素；它们分别挂在四要素或 run policy 上，并且必须能追溯到 SecretRef、Git commit/path/hash、配置引用或显式 null/deferred 状态。 ## 装配对象与 credential 归属 @@ -128,11 +131,66 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S - P0 固定 Git-only，由 `repoUrl + full commitId` 决定内容身份。 - `commitId` 必须是不可变 full commit sha，不能是 branch、tag 或 `HEAD`。 -- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`；默认不启用。 +- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`、`toolAliases`、`promptRefs`、`skillRefs`；默认不启用。 - `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。 - 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋或 inline env；后续需要时另写版本规格。 - 面向 HWLAB 手动调度 canary，runner materialization 必须把 Git-only bundle checkout 到允许 workspace 前缀，并在 event/result 中记录 repo、full commit、checkout path 和 tree 摘要；不得隐式使用 manager Pod、host path 或镜像内旧代码。 +#### toolAliases + +`toolAliases` 用于把 bundle 内的受控脚本暴露为 runner PATH 中的短命令。每个 alias 只能指向当前 checkout 内的相对路径，不能覆盖 runner 镜像里已有非 AgentRun wrapper 命令；materialization event 只输出 alias 名称、kind、目标 path hash 和 wrapper 摘要，不输出脚本全文。缺少 required 工具入口时必须返回 `resource-tool-unavailable` 或等价 blocker，不能要求业务 prompt 改走长路径 wrapper。 + +#### promptRefs + +`promptRefs` 用于按 `repoUrl + full commitId + path` 装配初始 prompt。它承载业务域稳定 runtime/developer instruction，例如某个项目的标准入口、禁止路径和工具使用纪律；它不承载用户本轮 message，也不承载历史会话。 + +最小形态： + +```json +{ + "name": "hwlab-v02-runtime", + "path": "internal/agent/prompts/hwlab-v02-runtime.md", + "inject": "thread-start", + "required": true +} +``` + +规则： + +- `path` 只能是 bundle 内相对路径，不能是绝对路径，不能包含 `..`。 +- `inject` 的 v0.1 默认和唯一正式语义是 `thread-start`：只有没有既有 `threadId`、runner 执行 `thread/start` 的第一条 turn 会注入；已有 `SessionRef.threadId` 或 command `payload.threadId` 并执行 `thread/resume` 时不得再次注入。 +- 多个 `promptRefs` 按数组顺序拼装；单个 prompt 和总 assembled prompt 必须有大小上限，超限返回 `prompt-unavailable` 或 `prompt-too-large`，不能静默截断成新语义。 +- prompt 文件内容进入 Codex turn input，但 event/result 只输出 `name`、`path`、`sha256`、`bytes`、`inject`、`required` 和 `injected=true/false`，不得默认输出全文。 +- `promptRefs` 不得读取 Secret、env、token、profile config 或 session 文件；需要 credential 的内容必须通过 `ProfileRef`、`toolCredentials` 或 `transientEnv` 的正式路径装配。 +- `promptRefs` 缺失且 `required=true` 时，run/command 必须 blocked；不得 fallback 到用户 prompt、旧硬编码 prompt、模型默认 system prompt 或历史上下文拼接。 + +#### skillRefs + +`skillRefs` 用于按同一 `ResourceBundleRef` checkout 装配 skill manifest。它只描述非敏感 skill 文件、聚合方式和 required 语义；运行时 credential 仍走 `toolCredentials` 或其他 SecretRef 路径。 + +最小形态： + +```json +{ + "name": "device-pod-cli", + "path": "skills/device-pod-cli/SKILL.md", + "required": true, + "aggregateAs": "device-pod-cli" +} +``` + +规则： + +- `path` 必须指向当前 checkout 内的 `SKILL.md`，或后续规格显式允许的 skill root；不能引用 runner 镜像、host path、ConfigMap 或外部 URL。 +- runner 必须把 skill 聚合到当前 workspace 的标准 skill registry，例如 `$WORKSPACE/.agents/skills//SKILL.md`，并设置 backend 可见的 skill dirs 环境或等价配置。 +- skill discovery fact 只输出 skill name、summary、manifest path、hash、version/commit metadata 和 count；不得输出大段 manifest 正文，除非 agent 在 turn 中按需读取文件。 +- `required=true` 的 skill 缺失、不可读或 manifest 无法解析时，run/command 必须 blocked 为 `skill-unavailable`，不能让模型凭默认 Codex skill registry 猜测，也不能把用户长 prompt 当作替代 skill。 +- `skillRefs` 与 `promptRefs` 必须来自同一 `repoUrl + commitId`，以避免业务 prompt、skill manifest 和工具 alias 版本漂移。 + +#### 初始 prompt 与 session 边界 + +初始 prompt 装配只发生在新 thread 的首轮 turn。后续 turn 的历史上下文必须由 Codex stdio 原生 `thread/resume` 恢复；AgentRun 不得为了补 prompt、补 skill facts 或修复 stale thread 而拼接旧用户消息、旧 assistant 回复、旧 skill 列表或旧业务事实。`thread/resume` 失败时按 [spec-v01-backend-codex.md](spec-v01-backend-codex.md) 直接失败，不启动替代 `thread/start`。 + ## 最简装配顺序 1. Manager 根据 run 解析四要素引用。 @@ -141,7 +199,8 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S 4. Runner materialize profile Secret 到 writable runtime home。 5. Runner materialize tool credential 到该 run 允许的 env/file projection；未实现的 tool scope 必须显式 failed/blocked，不能静默跳过后让 agent 自己猜凭据。 6. Runner materialize Git-only resource bundle 到 workspace；P0 未实现时必须显式记录为 deferred 或 null，不能猜测 host path。 -7. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl/commitId 的脱敏摘要。 +7. Runner 在 materialized bundle 内解析 `toolAliases`、`promptRefs` 和 `skillRefs`：创建工具 wrapper、聚合 skill registry、读取并校验 thread-start prompt，写入有界 assembly event。 +8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl/commitId、promptRefs 和 skillRefs 的脱敏摘要。 任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。 @@ -181,6 +240,8 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S - `commitId` 不是 branch/tag/HEAD。 - checkout 只能进入允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。 - run payload 不携带文件正文、env dump、Secret value 或大型 artifact。 +- 若提供 `promptRefs`，必须能看到每个 prompt 的 `name/path/sha256/bytes/inject`，新 thread 首轮 `initialPromptInjected=true`，resume turn `initialPromptInjected=false`。 +- 若提供 `skillRefs`，必须能看到 skill registry 聚合摘要、required skill 名称和 manifest hash；required skill 缺失必须 blocked，不能显示模型默认 skill 列表当作业务 skill。 ### A5 综合验收 @@ -190,7 +251,8 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S 2. 用哪一个 profile 和 SecretRef。 3. 是否使用 session；若不用，必须明确为 `null`/deferred。 4. 使用哪一个 Git repo 和 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。 -5. 是否装配 tool credential；若需要 GitHub PR 能力，必须能回答 tool、purpose、SecretRef 和 projection kind，不能只在运行时 shell 中偶然存在 token。 +5. 是否装配 tool aliases、初始 prompt 和 skill refs；若提供，必须能回答 name/path/hash/inject/required 和是否注入，不能只依赖模型默认 prompt 或默认 skill registry。 +6. 是否装配 tool credential；若需要 GitHub PR 能力，必须能回答 tool、purpose、SecretRef 和 projection kind，不能只在运行时 shell 中偶然存在 token。 ## 实现状态 @@ -199,5 +261,5 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S | `BackendImageRef` | 部分实现 | CI/CD 已使用 digest-pinned runtime image；当前 runner/backend 仍复用 agentrun 镜像。 | | `ProfileRef` | 已实现/待 MiniMax-M3 主闭环 | `codex` 与 `deepseek` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证；`minimax-m3` 已进入 profile/SecretRef 装配，需要完成真实 CLI 手动验收。 | | `SessionRef` | 已实现最小持久化 | manager 持久化 `sessionId/conversationId/threadId`，run 创建会解析既有 session，runner 按 threadId resume；session 不保存 credential 文件，TTL/GC 后续细化。 | -| `ResourceBundleRef` | 已实现 Git-only materialization | `repoUrl + full commitId` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 commit/tree/workspace 摘要。 | +| `ResourceBundleRef` | 已实现 Git-only materialization/待 promptRefs 与 skillRefs 实现 | `repoUrl + full commitId` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 commit/tree/workspace 摘要；`toolAliases` 已实现，`promptRefs` thread-start 注入和 `skillRefs` registry 聚合待实现。 | | `toolCredentials` | 已实现最小 env projection | GitHub PR 和 UniDesk SSH passthrough 等 agent shell/tool 授权通过装配 SPEC 的 SecretRef 进入 runner；v0.1 支持 `tool=github` 与 `tool=unidesk-ssh`、`projection.kind=env`，runner Job 使用 `valueFrom.secretKeyRef` 注入，不用 `transientEnv` 绕过。 | diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md index 07d140f..501f1bd 100644 --- a/docs/reference/spec-v01-validation.md +++ b/docs/reference/spec-v01-validation.md @@ -24,7 +24,7 @@ - Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。 - Secret 分发：SecretRef schema、missing secret failure、redaction。 - AgentRun Queue：task schema、attempt 状态机、summary/stats/read cursor、Queue 与 Session 引用边界、旧 MiniMax/OpenCode 直连入口废弃和 redaction。 -- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。 +- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类、`promptRefs`/`skillRefs` 装配和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。 自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。 @@ -59,7 +59,7 @@ 6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。 7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。 8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。 -9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace 摘要，不能由 runner 隐式猜测。 +9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace 摘要，不能由 runner 隐式猜测。若提供 `promptRefs` 或 `skillRefs`，必须能查到 name/path/hash/bytes/required/injected 摘要；required 缺失必须 blocked，不能 fallback 到模型默认 prompt 或默认 skill registry。 ### CLI 交互联调标准 @@ -105,6 +105,8 @@ CLI 与 RESTful API 可以复用同一个真实 run 做联调。若两者观察 | cancel | 对 pending/running/terminal 分别调用 cancel | cancel 幂等，pending 不再启动 runner，running 收敛为 cancelled 或既有 terminal，events/result 可见。 | | SessionRef | 连续两轮使用同一 sessionRef 或 conversation/session/thread 摘要 | 第二轮可 resume backend thread；session 不包含 credential 文件或完整 CODEX_HOME。 | | ResourceBundleRef | 使用 `repoUrl + full commitId` 启动 runner | runner checkout 到允许 workspace，event/result 能回答 repo、commit、workspace 摘要；不使用 branch/tag/HEAD 或 host path。 | +| Resource prompt/skill assembly | 使用同一 `ResourceBundleRef` 指定 `promptRefs`、`skillRefs` 和 `toolAliases` | 新 thread 首轮注入 initial prompt 和 skill facts；resume 不重复注入；required prompt/skill 缺失 blocked；不使用用户长 prompt、旧硬编码 prompt、镜像 `/app/skills` 或默认 Codex skill registry 替代。 | +| DS 短 prompt 探测 | 通过正式 CLI/Web 等价入口向真实 `backendProfile=deepseek` 发送短 prompt | “可见 skill”回复包含业务 `skillRefs` 而不只是 Codex 默认系统 skill；“当前 HWLAB 初始规则”能回答 hwpod/禁止路径；“编译 D601-F103-V2”能触发标准 Device Pod 路径。 | | ProfileRef/SecretRef | 分别验证 `codex`、`deepseek` 与 `minimax-m3` profile | 只使用当前 profile SecretRef；缺失时 `secret-unavailable`，不 fallback，不泄露 Secret 值。 | | bounded output | 触发工具/命令输出摘要 | result/event 只含摘要、字节数、截断标记和必要引用，不把大 stdout/stderr 塞入单个 JSON 响应。 |