@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：

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

macOS / Linux：

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：

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 命令通过全局参数声明当前宿主：

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。

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。