Codex
87 lines
7.0 KiB
Markdown
87 lines
7.0 KiB
Markdown
# v0.2 hwlab-agent-skills 服务规格
|
||
|
||
`hwlab-agent-skills` 是 v02 agent 技能包的部署可见服务，运行在 `hwlab-v02` namespace，内部端口 `7430`。它用于暴露预装 skills bundle 的构建/health 元数据，不应成为 `hwlab-cloud-api` 每次 Code Agent 对话的运行时必依赖。
|
||
|
||
Code Agent 第一版 skill 来源分为两类：预装 skill 读取镜像内只读目录 `/app/skills`；用户上传 skill 读取 `hwlab-cloud-api` 挂载的 PVC 目录 `/data/user-skills`。两类 skill 必须保持不同目录和不同来源标识，不做 checksum、sha256、content-addressed artifact、鉴权、校验、Postgres metadata、audit、GC、版本发布或 session 绑定。
|
||
|
||
## 在系统中的职责划分
|
||
|
||
- 证明当前 lane 中 skills bundle 随 source commit 发布，并为 live-build inventory 和 M4/M5 agent-loop 验收提供 health metadata。
|
||
- 与 `hwlab-agent-mgr` 和 `hwlab-agent-worker` 的 skills commit/version readiness 对齐。
|
||
- 预装 skill 只由镜像内 `/app/skills` 提供，不保存用户数据，不保存 Secret，不执行用户代码。
|
||
- 用户上传 skill 由 `hwlab-cloud-api` 管理，普通文件直接落到 PVC `/data/user-skills`，本服务不承载上传、预览或用户数据持久化 API。
|
||
|
||
## 内部架构
|
||
|
||
- artifact runtime 以 health-only server 方式运行，暴露 `/health` 和 `/health/live`。
|
||
- 镜像包含 `skills/` 目录，构建身份来自 `HWLAB_COMMIT_ID`、`HWLAB_IMAGE`、`HWLAB_IMAGE_TAG`。
|
||
- `HWLAB_SKILLS_COMMIT_ID` 由 GitOps render 注入；`HWLAB_SKILLS_VERSION` 是 skills manifest readiness 需要的稳定字段。
|
||
- `hwlab-cloud-api` 的 Code Agent skill discovery 必须同时扫描预装目录和用户上传目录。Linux runtime 推荐配置为 `HWLAB_CODE_AGENT_SKILLS_DIRS=/app/skills:/data/user-skills`；跨平台测试可使用现有 resolver 支持的逗号或分号分隔。
|
||
- `hwlab-cloud-api` 启动或上传后必须幂等维护 Codex 工作区聚合目录 `/workspace/hwlab/.agents/skills`，用 symlink 暴露两类 skill：预装 skill 使用 `preinstalled-<name>`，用户上传 skill 使用 `uploaded-<id>`。
|
||
- 聚合目录只作为 Codex 原生 skills discovery 入口，不改变 source truth：预装 source truth 仍是 `/app/skills`，用户上传 source truth 仍是 PVC `/data/user-skills`。
|
||
|
||
## 用户上传 skill 第一版边界
|
||
|
||
- 用户上传 skill 存储目录固定为 PVC 挂载路径 `/data/user-skills`，可通过 `HWLAB_USER_SKILLS_DIR` 显式配置。
|
||
- 预装 skill 目录固定为 `/app/skills`，可通过 `HWLAB_PREINSTALLED_SKILLS_DIR` 显式配置；PVC 不得挂载到 `/app/skills`。
|
||
- 上传目录按生成 ID 写入 `/data/user-skills/<generated-id>/`，例如 `skill-<timestamp>-<short-random>`；metadata 只写普通 JSON 文件，放在 PVC 中。
|
||
- 第一版 metadata 只用于列表和预览，不写入 Postgres，不做 migration，不依赖数据库恢复。
|
||
- 同名 skill 不覆盖、不合并、不校验拦截；API 和 Web 必须按 `source` 与 `id` 区分展示。
|
||
- HWLAB 自有 `skills.discover` 不得只按 skill name 去重；同名不同来源的 skill 必须保留。实现上至少使用 `name + sourceRoot + relativePath` 或 `source + id` 作为唯一 key。
|
||
- `SKILL.md` 预览只读取文本内容；二进制文件不内联展示。
|
||
- 第一版不把上传 skill 绑定到某个 Code Agent session，上传后作为全局可发现 skill 暴露。
|
||
|
||
## Code Agent 发现路径
|
||
|
||
- HWLAB 自有发现路径：`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 读取 `HWLAB_CODE_AGENT_SKILLS_DIRS`，扫描每个目录下直接或一级子目录中的 `SKILL.md`，并把 `Current skills discovery facts` 注入 Codex prompt。
|
||
- Codex 原生发现路径：Codex 会从工作区 `.agents/skills` 等标准位置加载 skill；因此 `hwlab-cloud-api` 必须准备 `/workspace/hwlab/.agents/skills` symlink 聚合目录，让 Codex 原生机制也能看到 `/app/skills` 与 `/data/user-skills` 中的 skill。
|
||
- 两条发现路径都必须保留来源信息；同名 skill 不能因为 HWLAB 侧去重而消失。
|
||
|
||
## API 接口说明
|
||
|
||
| 接口 | 说明 |
|
||
| --- | --- |
|
||
| `GET /health`、`GET /health/live` | 返回 service identity、revision、image/build metadata 和 skills 相关 env。 |
|
||
| `GET /help` | 返回 health-only runtime 的可用 route。 |
|
||
|
||
## 测试规格
|
||
|
||
## T1
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后用 cli 手动测试以下内容：访问 `hwlab-agent-skills:7430/health/live`，确认 `serviceId=hwlab-agent-skills`、revision 与 v02 source commit 对齐。
|
||
|
||
## T2
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后用 cli 手动测试以下内容：检查 Deployment env，确认 `HWLAB_SKILLS_COMMIT_ID` 存在；若 `HWLAB_SKILLS_VERSION` 缺失，必须在验收结果中标记未完全实现。
|
||
|
||
## T3
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后用 cli 手动测试以下内容：检查 `hwlab-cloud-api` Deployment env 和 volumeMount，确认 `HWLAB_CODE_AGENT_SKILLS_DIRS` 同时包含 `/app/skills` 与 `/data/user-skills`，用户上传 PVC 挂载到 `/data/user-skills`，且没有把 PVC 挂载到 `/app/skills`。
|
||
|
||
## T4
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后上传一个与预装 skill 同名的测试 skill，确认上传目录落在 `/data/user-skills/<generated-id>/`，`/app/skills` 不变，Web 列表按来源和 ID 分开展示两个同名 skill。
|
||
|
||
## T5
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后让 Code Agent 执行“列出你可用的 skills”，确认返回同时包含预装 skill 和用户上传 skill；同名不同来源的 skill 不被 `dedupeSkills()` 或等价逻辑吞掉。
|
||
|
||
## T6
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-agent-skills.md，然后检查 `/workspace/hwlab/.agents/skills`，确认存在指向 `/app/skills` 下预装 skill 和 `/data/user-skills` 下用户上传 skill 的 symlink 聚合入口。
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| health-only 服务 | 已实现 | Deployment/Service 存在，端口 7430。 |
|
||
| skills bundle 随镜像发布 | 已实现 | Dockerfile 复制 `skills/` 到 `/app/skills`。 |
|
||
| `HWLAB_SKILLS_COMMIT_ID` | 已实现 | v02 render 已注入 source commit。 |
|
||
| `HWLAB_SKILLS_VERSION` | 未完全实现 | 当前 render 未稳定注入 version，manager/worker readiness 仍可能报告缺失。 |
|
||
| 作为 Code Agent 运行时依赖 | 不采用 | Code Agent 读取镜像内 skills，不应每轮依赖该服务。 |
|
||
| 用户上传 skill PVC 持久化 | 未实现 | 第一版要求由 `hwlab-cloud-api` 写入 `/data/user-skills`，不使用 Postgres。 |
|
||
| 预装/上传双目录发现 | 未实现 | 第一版要求 `HWLAB_CODE_AGENT_SKILLS_DIRS=/app/skills:/data/user-skills` 或等价多目录配置。 |
|
||
| Codex `.agents/skills` 聚合入口 | 未实现 | 第一版要求在 `/workspace/hwlab/.agents/skills` 创建来源前缀 symlink。 |
|
||
| 同名 skill 不覆盖不合并 | 未实现 | 当前发现逻辑不得只按 skill name 去重，需保留同名不同来源。 |
|
||
|