--- 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 [--timeout 600000] bun scripts/hwlab-code-agent-cli.ts result bun scripts/hwlab-code-agent-cli.ts trace [--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 # 选择当前 workspace session bun tools/hwlab-cli/bin/hwlab-cli.ts client agent session select ``` 输出直接暴露 `sessionId`、`conversationId`、`threadId`、`providerProfile`、`sessionStatus`。 --- ## 发送 Turn ```bash # 短消息 bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \ --session-id --message "Hello" # 长 prompt（文件） bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \ --session-id --message-file /tmp/prompt.md # 从 trace 恢复上下文续跑 bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \ --from-trace # 显式 provider（优先于 session 默认） bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send \ --session-id --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 --render web # 完整 trace bun tools/hwlab-cli/bin/hwlab-cli.ts client agent trace --render web --full ``` trace rows 包含 `role`（user/assistant/tool）、`status`、`text`。 --- ## Result 查询 ```bash bun tools/hwlab-cli/bin/hwlab-cli.ts client agent result ``` 返回 Agent 的 `assistantText`（最终回复）、`agentRun` 信息（runId/commandId/runnerId/namespace）、`traceSummary`。 --- ## Inspect ```bash bun tools/hwlab-cli/bin/hwlab-cli.ts client agent inspect --trace-id ``` 从 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 --message "..." ``` 向运行中的 Code Agent turn 注入纠偏指令。 --- ## 典型流程 ### CaseRun 失败调试 ```bash # 1. status 拿 sessionId/traceId trans G14:/root/hwlab-v02 script -- \ 'hwlab-cli case run status --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 --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 ' ``` ### 完整交互链路 ```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 --message "在吗?" # 4. 等待完成，查 result hwlab-cli client agent result # 5. 拉 trace 看详细过程 hwlab-cli client agent trace --render web ``` ### Web 等价验证 Web 暴露 Code Agent 问题后，先用 CLI 对同一 Cloud Web origin 和同一 `/v1/agent/chat*` 路径复现： ```bash # inspect 取 session 上下文 hwlab-cli client agent inspect --trace-id # 从 trace 恢复上下文续跑 hwlab-cli client agent send --from-trace ``` --- ## 环境变量 | 变量 | 值 | 说明 | |---|---|---| | `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 调度）