Codex Agent
8.2 KiB
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 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:
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 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
# 短消息
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 查询
# 渲染 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 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* 路径复现：
# 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 调度）