docs: specify resource prompt and skill assembly
This commit is contained in:
Codex
@@ -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/<aggregateAs || name>/SKILL.md`。
|
||||
- Runner 必须把该聚合目录通过环境或 backend option 暴露给 Codex runtime；对于需要兼容 Codex skill discovery 的实现，应设置 `AGENTRUN_SKILLS_DIRS` 或等价字段，并可同步设置业务方约定的 `<PROJECT>_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` 切换联调。 |
|
||||
|
||||
Reference in New Issue
Block a user