pikasTech-HWLAB/skills/hwlab-code-agent/SKILL.md

name, description

name	description
hwlab-code-agent	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。

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 deepseek]
bun scripts/hwlab-code-agent-cli.ts spawn --message "..." --spec-path /path/to/hwpod-spec.yaml
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]

输出均为 JSON。spawn 创建 session + 提交 prompt，立即返回 sessionId + traceId。poll 阻塞轮询至 terminal 或超时。

hwpod spec 自动继承

子 agent 需要 .hwlab/hwpod-spec.yaml 才能使用 hwpod。spec 按优先级自动注入：

1. --spec-path <file> — 显式指定本地 spec 文件
2. CWD 下的 .hwlab/hwpod-spec.yaml — caserun 注入后自动检测
3. 环境变量 HWPOD_SPEC_CONTENT — yaml 或 base64

Caserun -> Leader -> Coder/Reviewer 继承链：

caserun 注入 .hwlab/hwpod-spec.yaml 到 Leader workspace
  -> Leader CWD 自动有该文件
    -> Leader 调用 spawn 时 auto-detect -> 注入子 agent workspaceFiles
      -> Coder/Reviewer 拿到相同 spec

---

外部管理 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:

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

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。

# 创建 session
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent session create \
  [--provider-profile deepseek|codex-api|minimax-m3]

# 查看状态
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

# 短消息
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 deepseek

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

---

Trace 查询

# 渲染 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 查询

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

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

---

Inspect

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（纠偏）

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

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

---

典型流程

CaseRun 失败调试

# 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>'

完整交互链路

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

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

# 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* 路径复现：

# 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-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 调度）