---
name: hwlab-code-agent
description: HWLAB Code Agent CLI — `hwlab-cli client agent` 的全部操作，包括 session 管理、send、trace/result/inspect、steer、Web 等价路径、auth；以及 spawn/poll/result/trace 直连 cloud-api。用户提到 code agent、hwlab-cli client agent、agent send、agent trace、agent result、agent inspect、agent session、agent steer、拉 trace、查 session、spawn agent、poll agent 时使用。
---

# HWLAB Code Agent CLI

Skill(cli-spec)

**Skill 根目录**: `~/.agents/skills/hwlab-code-agent/`
**CLI 入口**: `bun scripts/hwlab-code-agent-cli.ts`
**配置**: `config.json`（单一来源，启动校验）

## 直接客户端（master server 直连 cloud-api）

无需透传到 G14，自动识别 `HWLAB_API_KEY` 鉴权调用 HWLAB v0.2 cloud-api。

```bash
source /root/.config/hwlab-v02/master-server-admin-api-key.env
cd ~/.agents/skills/hwlab-code-agent

bun scripts/hwlab-code-agent-cli.ts spawn --message "say hello" --profile dsflash-go
HWLAB_CODE_AGENT_PROVIDER_PROFILE=dsflash-go bun scripts/hwlab-code-agent-cli.ts spawn --message "say hello from env"
bun scripts/hwlab-code-agent-cli.ts poll <traceId> [--timeout 600000]
bun scripts/hwlab-code-agent-cli.ts result <traceId>
bun scripts/hwlab-code-agent-cli.ts trace <traceId> [--full]
```

`spawn` 的 provider profile 解析权威见 `../../docs/reference/agentrun-code-agent-dispatch.md`：只认显式 `--profile` 或环境变量 `HWLAB_CODE_AGENT_PROVIDER_PROFILE`。未提供时直接返回 `provider_profile_required`，不从 `config.json`、workspace、session 默认值或 `deepseek` fallback 推断。

输出均为 JSON。`spawn` 创建 session + 提交 prompt，立即返回 `sessionId` + `traceId`，并暴露 `resolvedProviderProfile`、`profileSource`、`parentTraceId`。`poll` 阻塞轮询至 terminal 或超时。

### HWPOD spec 与 runtime assets

HWLAB v0.2 的工具和 skill 注入已经收敛到 AgentRun `ResourceBundleRef.kind="gitbundle"`，权威语义见 `../../docs/reference/agentrun-code-agent-dispatch.md`：repo `tools/` 复制到 runner workspace `tools/`，repo `skills/` 复制到 `.agents/skills`。旧 `workspaceFiles`、seed、`skillRefs` 和 tool alias 注入路径已经移除；不要再用 `--spec-path`、`HWPOD_SPEC_CONTENT` 或 CWD `.hwlab/hwpod-spec.yaml` 通过 direct helper 向子 agent 注入文件。

CaseRun/HWPOD spec 的启动前准备仍由 HWLAB #1011 跟踪。排障时优先使用 G14 workspace 的正式 `hwlab-cli client agent` Web-equivalent 路径，并从 trace/result 中确认 `resource-bundle-materialized.kind=gitbundle`、`bundles`、`tools`、`skillDirs` 和 `promptRefs`。

provider profile 继承语义不在本 skill 重复定义；排障时只检查 `spawn` JSON 中的 `resolvedProviderProfile`、`profileSource`、`parentTraceId`，再到 `../../docs/reference/agentrun-code-agent-dispatch.md` 对齐权威规则。

---

## 外部管理 CLI（G14 workspace 透传）

通过 G14 `/root/hwlab-v02` workspace 的 `hwlab-cli client agent` 管理 Code Agent 的 session、提交、trace 和纠偏。

**固定入口**: `bun tools/hwlab-cli/bin/hwlab-cli.ts client agent ...`
**锁定 env**:
```bash
export HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666
export HWLAB_RUNTIME_ENDPOINT_LOCKED=1
```
**API key**: `HWLAB_API_KEY` 从 `/root/.config/hwlab-v02/master-server-admin-api-key.env` 加载。

---

## Auth

```bash
bun tools/hwlab-cli/bin/hwlab-cli.ts client auth status
```

CLI 默认从 `HWLAB_API_KEY` 读取 key，发送 `Authorization: Bearer hwl_live_...`。不支持 `--api-key` / `--bearer-token` 别名。缺少 key 时返回 `api_key_required`。

---

## Session 管理

Code Agent session 是显式资源，必须先创建再发送 turn。

```bash
# 创建 session
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent session create \
  --provider-profile PROFILE

# 查看状态
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent session status <sessionId>

# 选择当前 workspace session
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent session select <sessionId>
```

输出直接暴露 `sessionId`、`conversationId`、`threadId`、`providerProfile`、`sessionStatus`。

---

## 发送 Turn

```bash
# 短消息
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \
  --session-id <sessionId> --message "Hello"

# 长 prompt（文件）
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \
  --session-id <sessionId> --message-file /tmp/prompt.md

# 从 trace 恢复上下文续跑
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \
  --from-trace <traceId>

# 显式 provider（优先于 session 默认）
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \
  --session-id <sessionId> --message "..." --provider-profile dsflash-go
```

必须携带显式 `--session-id` 或已 select 的 workspace session。未提供时返回 `session_required`。不传 `--provider-profile` 时继承 session 的 provider profile。

---

## Trace 查询

```bash
# 渲染 trace（与 Cloud Web 共享同一 renderer）
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent trace <traceId> --render web

# 完整 trace
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent trace <traceId> --render web --full
```

trace rows 包含 `role`（user/assistant/tool）、`status`、`text`。

---

## Result 查询

```bash
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent result <traceId>
```

返回 Agent 的 `assistantText`（最终回复）、`agentRun` 信息（runId/commandId/runnerId/namespace）、`traceSummary`。

---

## Inspect

```bash
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent inspect --trace-id <traceId>
```

从 Cloud Web `/v1/agent/chat/inspect` 读取 trace 所属的 `conversationId/sessionId/threadId`、session 状态和 `retryOf` 建议。session 缺失或 failed 时返回结构化 blocker。

---

## Steer（纠偏）

```bash
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent steer <traceId> --message "..."
```

向运行中的 Code Agent turn 注入纠偏指令。

---

## 典型流程

### CaseRun 失败调试

```bash
# 1. status 拿 sessionId/traceId
trans G14:/root/hwlab-v02 script -- \
  'hwlab-cli case run status <RUN_ID> --state-dir .state/hwlab-cli/caserun'

# 2. 拉 trace 分析 Agent 行为
trans G14:/root/hwlab-v02 script -- \
  'export HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666 HWLAB_RUNTIME_ENDPOINT_LOCKED=1 && \
   bun tools/hwlab-cli/bin/hwlab-cli.ts client agent trace <traceId> --render web'

# 3. 看 Agent 最终回复
trans G14:/root/hwlab-v02 script -- \
  'export HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666 HWLAB_RUNTIME_ENDPOINT_LOCKED=1 && \
   bun tools/hwlab-cli/bin/hwlab-cli.ts client agent result <traceId>'
```

### 完整交互链路

```bash
# 1. 登录
source /root/.config/hwlab-v02/master-server-admin-api-key.env

# 2. 显式创建 session
hwlab-cli client agent session create --provider-profile dsflash-go

# 3. 发送 turn（继承 session provider）
hwlab-cli client agent send --session-id <sessionId> --message "在吗?"

# 4. 等待完成，查 result
hwlab-cli client agent result <traceId>

# 5. 拉 trace 看详细过程
hwlab-cli client agent trace <traceId> --render web
```

### Web 等价验证

Web 暴露 Code Agent 问题后，先用 CLI 对同一 Cloud Web origin 和同一 `/v1/agent/chat*` 路径复现：

```bash
# inspect 取 session 上下文
hwlab-cli client agent inspect --trace-id <traceId>

# 从 trace 恢复上下文续跑
hwlab-cli client agent send --from-trace <traceId>
```

---

## 环境变量

| 变量 | 值 | 说明 |
|---|---|---|
| `HWLAB_API_KEY` | `hwl_live_...` | API key，从 key env 文件加载 |
| `HWLAB_RUNTIME_WEB_URL` | `http://74.48.78.17:19666` | v0.2 Cloud Web origin |
| `HWLAB_RUNTIME_API_URL` | `http://74.48.78.17:19667` | v0.2 Cloud API origin |
| `HWLAB_RUNTIME_ENDPOINT_LOCKED` | `1` | 锁定 endpoint，不自动探测 |
| `HWLAB_CODE_AGENT_PROVIDER_PROFILE` | `dsflash-go` 等 | runner 内 child `spawn` 的 env-only profile 继承来源 |
| `HWLAB_CODE_AGENT_PARENT_TRACE_ID` | `trc_...` | child trace/result 的父 trace 关联来源，不参与 profile 选择 |

## 相关文档

- **hwlab-cli 规格**: `docs/reference/spec-v02-hwlab-cli.md`（auth/session/Web 等价架构）
- **trace 规格**: `docs/reference/spec-v02-code-agent-trace.md`（共享 renderer 语义）
- **dispatch 规格**: `docs/reference/agentrun-code-agent-dispatch.md`（AgentRun 调度）
