# @actionway/cli — 本地端壳（bin: `actionway`）

actionway CLI 的本地端壳（迁移文档 `docs/DL_TO_ACTIONWAY_CLI_MIGRATION.md` §3.2 / §3.4）：
终端用户在自己机器上的 Coding Agent（Codex / Claude Code / WorkBuddy）通过它调用 Actionway 能力。

## 安装

要求 Node.js 20 或更新版本；CI 覆盖 Node.js 20 和 22。Windows 使用 npm 生成的 `.cmd` 入口，避免 PowerShell
执行策略阻止 `.ps1` shim：

```powershell
npm.cmd install --global @actionway/cli@latest
actionway.cmd doctor
actionway.cmd init
```

macOS / Linux：

```bash
npm install --global @actionway/cli@latest
actionway doctor
actionway init
```

`doctor` 只输出脱敏后的 Node/npm、registry、global PATH、配置目录
和 OAuth discovery 检查；它不会修改 npm、代理、CA、PATH 或 PowerShell policy。

### Development 通道

成功合并并部署 `dev` 后，workflow 从同一 bundle 生成独立公共包 `@actionway/cli-dev`。它只暴露 `actionway-dev`，固定连接 `https://dev.actionway.ai`，使用 `${HOME}/.actionway-dev` 和 `actionway-dev` Skill；不会安装或覆盖正式 `actionway`：

```bash
npm install --global @actionway/cli-dev@latest
actionway-dev doctor
actionway-dev init
actionway-dev status
```

`actionway-dev update` 只读取和更新 `@actionway/cli-dev@latest`。每个 dev npm 版本包含不可变 source SHA 与 Actions run metadata；同一 tarball 也保存在私有 GitHub prerelease，后者仅用于内部审计和精确回滚，普通安装不需要 GitHub 账号。

本地 Agent 在每条 Actionway 命令通过全局参数声明当前宿主：

```bash
actionway --agent-host=codex tools search "generate a product image"
actionway --agent-host=claude_code tools search "generate a product image"
actionway --agent-host=workbuddy tools search "generate a product image"
```

不带 `--agent-host` 表示用户直接使用 CLI。该声明不写入共享凭据，所以同一个用户和全局 CLI 可以交替被多个 Agent 使用。CLI 同时从每次进程的 Node.js 运行环境识别 Windows、macOS、WSL 或 Linux；这些字段只作为 Site 侧产品分析事件属性，不参与鉴权、计费或 Gateway 路由。

- **auth 唯一途径：Clerk OAuth（PKCE）+ device 配对**。issuer / client_id 运行时从
  `{public origin}/api/auth/cli-config` 发现；登录不依赖本机浏览器回调——CLI 展示
  短码与 `{public origin}/cli/activate` 验证 URL，用户在任意设备的浏览器上登录并
  批准后 CLI 轮询取回一次性授权码并在本地完成 PKCE token 交换（远端 / headless /
  WSL 环境可直接使用，`--no-browser` 仅打印 URL 不尝试开浏览器）；
  fresh `actionway init` 会在 token 交换后的第一条账户请求中携带安装会话和本地
  客户端上下文，由服务端同时完成 CLI 首次建户、获客归因和安装连接；
  凭据存 `~/.actionway/credentials.json`（POSIX 上为 0600 owner-only 文件；
  Windows 上 chmod 无效，保密性依赖 `%USERPROFILE%` 的继承 ACL——不要把
  `ACTIONWAY_CONFIG_DIR` 指到共享目录）。CLI 从不打印或存储 OAuth client secret。
- **命令面 = 明码写出的注册表**（无 capability profile flag；production/development 只切换包、命令、状态、Skill、更新源与 Gateway）：
  - `tools search / inspect / call` 是长尾 capability 的规范发现与执行面；
  - 高频 typed command 继续提供参数与文件 UX，但投影到同一个 Tool Call；
  - `account invitation` 获取或首次创建当前账户的永久邀请码、链接和服务端本地化分享文案；
  - `account usage / wallet / transactions` 只读 Actionway Business 数据；
  - 本壳另有 `init` / `doctor` / `update` / `login` / `logout` / `whoami`，cli-core
  继续提供 wait/poll 与已冻结的共享 typed commands。

- **账户响应无本地换算**：`account` 响应同时保留精确整数 micros 与可直接展示的 USD 十进制字符串；钱包包含快照更新时间，交易包含状态、说明、完成时间和 signed balance delta。Usage/Transactions 支持 ISO 时间窗口、领域筛选和 opaque cursor，返回的 summary 覆盖完整筛选集合而非当前页。CLI 不自行换算资金，也不改变服务端返回的字段语义。
- **计费零逻辑**：报价、扣费、错误面裁剪全在 gateway；本壳只透传。旧
  stock download 直连 CDN、Gateway 无法观察结局，因此在阶段二的
  command-level 计费编排完成前明确 fail-closed，不把迁移缺口当免费能力。
- **版本三链路**（与 pi-mono dl 的 actionway profile 同构）：
  1. 输出注入 —— 每个成功 JSON 输出带 `cli_version` + `skill_source`，
     本地缓存显示有新版时追加 `notes` 更新提示（update 命令自身输出带
     `update_available` 时跳过，防更新循环）；
  2. HTTP header —— 请求捎带 `x-actionway-cli-version`，响应的
     `x-actionway-cli-latest` / `x-actionway-cli-min` 喂本地缓存；
  3. registry —— `actionway update --check` 查 npm（24h 缓存），
     `actionway update` 全局安装新版并 re-exec 刷新物化 skill。
- **skill 物化**：`actionway init` 把 `assets/skill/actionway` 拷到
  `~/.actionway/skill/actionway` 并把 CLI 版本盖进 SKILL.md frontmatter
  `metadata.version`；
  Agent 从该路径自取安装——CLI 从不写入任何 Agent 自己的配置目录。包内
  Skill 不复制 capability catalog；未知或长尾需求走 Search → Inspect → Call，
  `confirmation_required` 由用户确认后恢复同一个 `call_ref`（用户刚选定的
  选项与 Plan 一致时，该选择即确认）。

```bash
pnpm cli init            # 浏览器授权 + 物化 skill（首次安装入口）
pnpm cli whoami          # 用户友好登录摘要 + 本地凭据快照（不出网）
pnpm cli logout          # 删除本机凭据；重复执行也是成功的幂等操作
pnpm cli update --check  # 查新版（24h 缓存）
pnpm cli -- tools search "generate a product image"
pnpm cli -- tools inspect media.image.generate
pnpm cli -- account invitation --locale zh-cn
pnpm cli -- account usage
pnpm cli -- account usage --from 2026-08-01 --to 2026-09-01 --service generate-image
pnpm cli -- account transactions --from 2026-08-01 --kind top_up
pnpm cli -- generate-video --print-schema
```

发布 bundle 会把 cli-core 打进带 shebang 的 `dist/index.js`；`pnpm build`
生成该产物，`pnpm pack` 的 tarball 可由 Node 直接执行。手动发布由统一的
`.github/workflows/release.yml` 负责：勾选 `actionway_cli`（可单独选择，也可与 Worker 组合）并选择版本 bump 后，
workflow 以 npm 已发布的最高版本为基线生成下一版本，构建当前仓库的
tarball，验证真实 npm install 后的 `.bin/actionway`、`--help`、`--version`
和 `logout`，再发布到 `latest`。`@actionway/sandbox-cli` 继续独立于本地 CLI；
其 iLands rollout 尚未接入 Production Release，保留单独的手动发布 workflow。