feat: 为 gitbundle 装配 required skills (#138)
* Add gitbundle required skills validation * fix: 限定 required skill blocked result 覆盖 --------- Co-authored-by: AgentRun Codex <agentrun@example.invalid> Co-authored-by: Codex <codex@pikas.tech>
This commit is contained in:
Lyon
@@ -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` | `kind="gitbundle"`、`repoUrl`、`bundles[]`、可选 `ref` / `commitId` / `promptRefs` | 初始代码/文件输入、工具目录、skill 目录和稳定初始 prompt；P0 固定 Git-only gitbundle，默认从 repo/ref 解析实际 commit。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史、旧 inline seed。 |
|
||||
| `ResourceBundleRef` | `kind="gitbundle"`、`repoUrl`、`bundles[]`、可选 `ref` / `commitId` / `promptRefs` / `requiredSkills` | 初始代码/文件输入、工具目录、skill 目录、required skill 校验和稳定初始 prompt；P0 固定 Git-only gitbundle，默认从 repo/ref 解析实际 commit。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史、旧 inline seed、inline skill manifest。 |
|
||||
|
||||
P0 最小 JSON 形态：
|
||||
|
||||
@@ -34,7 +34,8 @@ P0 最小 JSON 形态：
|
||||
{ "name": "tools", "subpath": "tools", "target_path": "tools" },
|
||||
{ "name": "skills", "subpath": "skills", "target_path": ".agents/skills" }
|
||||
],
|
||||
"promptRefs": []
|
||||
"promptRefs": [],
|
||||
"requiredSkills": [{ "name": "dad-dev" }]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -164,7 +165,8 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也
|
||||
- `subpath` 必须留在 checkout 内，`target_path` 必须留在 runner workspace 内；runner 按 `subpath -> target_path` 复制文件或目录。
|
||||
- `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。
|
||||
- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋、inline seed 或旧字段；旧 `toolAliases`、`skillRefs`、`workspaceFiles`、`subdir`、`sparsePaths` 输入必须直接 schema-invalid。
|
||||
- 面向 HWLAB 手动调度 canary，默认 bundle 把 repo 的 `tools/` 复制到 workspace `tools/`，把 `skills/` 复制到 workspace `.agents/skills/`；event/result 必须记录 repo、requested ref/commit、实际 materialized commit、checkout tree、bundle 列表、workspace 摘要、tools 和 skillDirs 摘要。
|
||||
- `requiredSkills[]` 只接受 `{ "name": "<skill-name>" }` 这类声明式元数据；runner 只能在 gitbundle 已复制的 `.agents/skills/<name>/SKILL.md` 中校验，不接受正文、host path、SecretRef、旧 `skillRefs` 或模型默认 skill fallback。
|
||||
- 面向 HWLAB 手动调度 canary，默认 bundle 把 repo 的 `tools/` 复制到 workspace `tools/`，把 `skills/` 复制到 workspace `.agents/skills/`；event/result 必须记录 repo、requested ref/commit、实际 materialized commit、checkout tree、bundle 列表、workspace 摘要、tools、skillDirs 和 requiredSkills 摘要。
|
||||
|
||||
#### tools 目录
|
||||
|
||||
@@ -198,7 +200,9 @@ AgentRun 自身仓库必须提供 `tools/tran` 与 `tools/trans`，用于承接
|
||||
|
||||
#### skill 目录
|
||||
|
||||
skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.md`。runner 发现直接子目录中的 `SKILL.md` 后，把 `.agents/skills` 暴露给 backend，并在 initial prompt 中加入有界 skill facts。多文件 skill 的 `references/`、`scripts/` 和后续新增文件跟随目录一起复制；event/result 只输出 skill name、manifest path 摘要、hash、bytes 和 summary，不输出大段 manifest 正文。runner 不读取镜像默认 skill、host path、ConfigMap、用户长 prompt 或旧 `skillRefs`。
|
||||
skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.md`。runner 发现直接子目录中的 `SKILL.md` 后，把 `.agents/skills` 暴露给 backend，并在 initial prompt 中加入有界 skill facts。多文件 skill 的 `references/`、`scripts/` 和后续新增文件跟随目录一起复制；event/result 只输出 skill name、manifest path 摘要、hash、bytes、summary 和来源 bundle 摘要，不输出大段 manifest 正文。
|
||||
|
||||
若调用方声明 `requiredSkills[]`，runner 必须在 backend 启动前逐项校验 `.agents/skills/<name>/SKILL.md` 已由 gitbundle 物化。缺失时 run/command blocked，failureKind 为 `required-skill-unavailable`，blocker details 至少包含 required、missing 和 available 摘要；不得读取镜像默认 skill、host path、ConfigMap、用户长 prompt 或旧 `skillRefs` 作为替代。
|
||||
|
||||
#### 初始 prompt 与 session 边界
|
||||
|
||||
@@ -212,8 +216,8 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
|
||||
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 `kind="gitbundle"` resource bundle 到 workspace；P0 未实现时必须显式 blocked，不能猜测 host path。
|
||||
7. Runner 按 `bundles[]` 复制目录或文件，准备 workspace `tools/`、发现 `.agents/skills`，读取并校验 `promptRefs`，写入有界 assembly event。
|
||||
8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl、requested ref/commit、materialized commit、bundles、promptRefs、tools 和 skillDirs 摘要。
|
||||
7. Runner 按 `bundles[]` 复制目录或文件，准备 workspace `tools/`、发现 `.agents/skills`，校验 `requiredSkills`，读取并校验 `promptRefs`，写入有界 assembly event。
|
||||
8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl、requested ref/commit、materialized commit、bundles、promptRefs、requiredSkills、tools 和 skillDirs 摘要。
|
||||
|
||||
任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。
|
||||
|
||||
@@ -256,7 +260,7 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
|
||||
- run payload 不携带文件正文、env dump、Secret value 或大型 artifact。
|
||||
- 若提供 `bundles[]`，必须能看到每个 `subpath -> target_path` 的复制摘要；旧字段输入必须 schema-invalid。
|
||||
- 若提供 `promptRefs`，必须能看到每个 prompt 的 `name/path/sha256/bytes/inject`，新 thread 首轮 `initialPromptInjected=true`，resume turn `initialPromptInjected=false`。
|
||||
- 若 bundle 复制了 `.agents/skills`，必须能看到 skillDirs 聚合摘要、skill 名称和 manifest hash；不能显示模型默认 skill 列表当作业务 skill。
|
||||
- 若 bundle 复制了 `.agents/skills`，必须能看到 skillDirs 聚合摘要、skill 名称、manifest hash/bytes 和来源 bundle；若提供 `requiredSkills`，必须看到成功路径的 requiredSkills hash/bytes，以及缺失路径的 `required-skill-unavailable` blocker。不能显示模型默认 skill 列表当作业务 skill。
|
||||
|
||||
### A5 综合验收
|
||||
|
||||
@@ -266,7 +270,7 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
|
||||
2. 用哪一个 profile 和 SecretRef。
|
||||
3. 是否使用 session；若不用，必须明确为 `null`/deferred。
|
||||
4. 使用哪一个 Git repo/ref，以及最终 materialized 到哪一个 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。
|
||||
5. 是否装配 gitbundle bundles、workspace tools、初始 prompt 和 skillDirs；若提供，必须能回答 name/path/hash/inject/required 和是否注入，不能只依赖模型默认 prompt 或默认 skill registry。
|
||||
5. 是否装配 gitbundle bundles、workspace tools、初始 prompt、skillDirs 和 requiredSkills；若提供，必须能回答 name/path/hash/bytes/inject/required 和是否注入，不能只依赖模型默认 prompt 或默认 skill registry。
|
||||
6. 是否装配 tool credential；若需要 GitHub PR 能力，必须能回答 tool、purpose、SecretRef 和 projection kind，不能只在运行时 shell 中偶然存在 token。
|
||||
|
||||
## 实现状态
|
||||
@@ -277,6 +281,6 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
|
||||
| `ProfileRef` | 已实现/待 dsflash-go 真实主闭环 | `codex`、`deepseek` 与 `minimax-m3` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证；MiniMax-M3 已通过 HWLAB 显式 session 原入口复测。`dsflash-go` 已补齐 SecretRef/model catalog 装配、自测试和 legacy key 归一，仍需完成真实 runtime 与 HWLAB 原入口复测；后续只允许作为 profile/config/SecretRef/model catalog 选择，不新增直连 backend。 |
|
||||
| `SessionRef` | 已实现最小持久化 | manager 持久化 `sessionId/conversationId/threadId`，run 创建会解析既有 session，runner 按 threadId resume；session 不保存 credential 文件，TTL/GC 后续细化。 |
|
||||
| `SessionRef` | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | manager 持久化 `sessionId/conversationId/threadId` + 每个 session 绑 RWO PVC（`agentrun-v01-session-<sessionId>`），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/<codex_rollout_subdir>`，codex app-server 自己落盘；runner pod 删除后 replacement runner 仍复用同一 SessionRef/PVC/thread，禁止 copy/restore、replacement threadId 和 fake resume。 |
|
||||
| `ResourceBundleRef` | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs 装配 | `repoUrl + ref/materialized commit + bundles[]` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 requested ref/commit、actual commit、tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入和 `.agents/skills` 目录发现已实现。 |
|
||||
| `ResourceBundleRef` | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs/requiredSkills 装配 | `repoUrl + ref/materialized commit + bundles[]` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 requested ref/commit、actual commit、tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入、`.agents/skills` 目录发现和 required skill 校验已实现。 |
|
||||
| `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` 绕过。 |
|
||||
| `transientEnv` | 已实现 per-job SecretRef 投影 | Queue dispatch 和 runner-job API 支持短期 runtime env；正式 Kubernetes Job 先创建本次 Job 专属 Secret，再用 `valueFrom.secretKeyRef` 注入 runner env，response/event/trace 只显示 env names、Secret metadata 和 `valuesPrinted=false`。 |
|
||||
|
||||
Reference in New Issue
Block a user