Codex Agent
42 lines
3.5 KiB
Markdown
42 lines
3.5 KiB
Markdown
---
|
|
name: hwpod-cli
|
|
description: Use HWLAB HWPOD from a code agent runner for hardware-development tasks. The hwpod-cli skill resolves an HWPOD by hwpod-id through the HWLAB runtime service, submits hwpod-node-ops through hwlab-api, and waits for hwpod-node results.
|
|
---
|
|
|
|
# hwpod-cli
|
|
|
|
This skill follows Skill(cli-spec). It is the standard task entry for operating an HWPOD from the HWLAB v0.2 Code Agent workspace.
|
|
|
|
## Standard Path
|
|
|
|
```text
|
|
hwpod from PATH
|
|
-> tools/hwpod-cli.ts
|
|
-> runtime HWPOD registry by hwpod-id
|
|
-> compiler-backed hwpod-node-ops plan
|
|
-> /v1/hwpod-node-ops on hwlab-api
|
|
-> hwpod-node on the host side
|
|
```
|
|
|
|
The HWPOD definition is runtime service state. The standard runner contract is `--hwpod-id <id>` plus `--workspace-path <run-worktree>` when the task is bound to a run-local workspace. A task may provide the complete `hwpodWorkspaceArgs` string; reuse it exactly. `--spec <path>` is only an explicit debug/import path for a local exported YAML, not the default runner contract.
|
|
|
|
## Commands
|
|
|
|
- Inspect the HWPOD path: `hwpod inspect --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`.
|
|
- Workspace search/read/edit: use `hwpod workspace ls|cat|read|rg|grep|search|apply-patch --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`. `read` is an alias for `cat`; `grep` and `search` are aliases for `rg`; `--file` and `--remote-path` are accepted as path aliases for file-oriented commands.
|
|
- For symbol lookup or ARM-2D header hunting, prefer `hwpod workspace rg <pattern> [path] --context 3 --hwpod-id d601-f103-v2 --workspace-path <run-worktree>` instead of `cat | grep`.
|
|
- Build/download/reset: use `hwpod build`, `hwpod download`, and `hwpod reset`; the compiler must translate these through existing file ops and `cmd.run` where possible.
|
|
- Keil async status: after build/download returns a job id, use separate short `hwpod job status <jobId> --hwpod-id d601-f103-v2 --workspace-path <run-worktree>` calls instead of shell polling wrappers such as `sleep &&`, `timeout`, `watch`, `head`, pipes, or loops.
|
|
- UART read: use `hwpod uart read --hwpod-id d601-f103-v2 --workspace-path <run-worktree> --port uart1`; the compiler runs the configured serial-monitor CLI through `cmd.run`.
|
|
|
|
## Boundaries
|
|
|
|
- Do not pass manual API URLs in locked AgentRun runtimes. Let `HWLAB_RUNTIME_API_URL` / `HWLAB_RUNTIME_NAMESPACE` select the current lane.
|
|
- Do not put full `hwpod-spec` on `hwpod-node`. The node only accepts `hwpod-node-ops`.
|
|
- Do not create, copy, restore, or repair runner-local `.hwlab/hwpod-spec.yaml` as a workaround. Use `hwpod-id` through the runtime service.
|
|
- Do not use deprecated workspace mutation commands (`workspace write`, `replace`, or `insert-after`) for normal source edits. Use `workspace apply-patch`.
|
|
- Treat `cmd.run` as the full-capability host execution op. Do not request new hwpod-node ops for build, download, job status, UART, PowerShell/cmd passthrough, or tool maintenance; improve `hwpod-compiler-cli` / `hwpod-cli` combinations first.
|
|
- Use workspace file operations for subject text edits. Do not use PowerShell/cmd heredocs for normal source edits unless debugging `cmd.run` itself.
|
|
- For multi-line edits, prefer `hwpod workspace apply-patch` with a Codex/UniDesk apply_patch v2 envelope from stdin or `--patch-content`. Put file paths in `*** Update File:` / `*** Add File:` / `*** Delete File:` headers. Do not pass raw unified diff (`---`, `+++`, `@@ -N`) as the whole patch; HWPOD deliberately rejects that format with a clear hint.
|
|
- If HWPOD returns a blocker, report and fix that blocker in this path.
|