Codex Agent
224 lines
8.2 KiB
Markdown
224 lines
8.2 KiB
Markdown
---
|
||
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 调度）
|