pikasTech-HWLAB/docs/reference/spec-v02-hwlab-agent-mgr.md

# v0.2 hwlab-agent-mgr 服务规格

`hwlab-agent-mgr` 是 agent runtime 管理服务，运行在 `hwlab-v02` namespace，内部端口 `7410`。当前实现是本地状态目录驱动的 runtime skeleton，不是 `hwlab-cloud-api` Code Agent 对话的主执行路径。

## 在系统中的职责划分

- 管理 agent session 生命周期模型：create、start、trace、finish、cleanup。
- 生成 workspace volume、worker session、trace event 和 evidence record 的结构化状态。
- 与 `hwlab-agent-worker`、`hwlab-agent-skills` 共同定义未来 session-scoped worker 执行边界。
- 不直接暴露给普通用户；用户态 Code Agent 请求必须先进入 `hwlab-cloud-api`。

## 内部架构

- `cmd/hwlab-agent-mgr/main.ts` 同时提供 CLI 和健康 HTTP server。
- `internal/agent/runtime.mjs` 负责文件系统状态、session lifecycle、trace/evidence 和 cleanup。
- `internal/agent/index.mjs` 定义 serviceId、session status 和 skills manifest 结构。
- `HWLAB_AGENT_RUNTIME_STATE_DIR` 可隔离状态目录；默认 `.state/agent-runtime` 只用于本地/测试状态。

## API 接口说明

| 接口 | 说明 |
| --- | --- |
| `GET /health`、`GET /health/live` | HTTP server 模式下返回 manager health、skills 注入状态和 build metadata。 |
| `GET /`、`GET /help` | 返回 CLI/服务用法。 |
| `bun run cmd/hwlab-agent-mgr/main.ts health` | 本地 JSON health。 |
| `create/status/trace/evidence/cleanup` | 本地 session lifecycle CLI；必须传 `--agent-session-id`，create 还需 `--project-id`。 |

## 测试规格

## T1

阅读 docs/reference/spec-v02-hwlab-agent-mgr.md，然后用 cli 手动测试以下内容：访问 v02 ClusterIP 或 pod 内 `/health/live`，确认 `serviceId=hwlab-agent-mgr`，并记录 skills missing/ready 状态。

## T2

阅读 docs/reference/spec-v02-hwlab-agent-mgr.md，然后用 cli 手动测试以下内容：在隔离 `--state-dir` 下执行 create、status、trace、evidence、cleanup，确认每步输出 JSON 且生命周期顺序稳定。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| HTTP health server | 已实现 | `server` 模式提供 `/health/live`。 |
| 本地 session lifecycle CLI | 已实现 | create/status/trace/evidence/cleanup 可用。 |
| skills commit/version readiness | 已实现 | health 会报告缺失字段；不静默 fallback。 |
| 调度真实 worker Job | 未完全实现 | 当前是 skeleton，本身不负责创建 Kubernetes worker Job。 |
| 接入 cloud-api 用户会话 | 未完全实现 | 当前 Code Agent 对话主要由 cloud-api 内部 Codex stdio manager 承担。 |