@ganhaiapp/cli 0.0.1 → 0.2.0

package/README.md

@@ -1,9 +1,64 @@
 # @ganhaiapp/cli
 
-赶海 GanHai 命令行工具 —— **占位版本（0.0.1）**，仅用于占住包名。
+赶海 GanHai 命令行工具 —— 开放 API 客户端 + MCP 服务（0.2.0）。
 
-正式版随 93-P2 发布，规划能力：
+## 安装
 
-- `ganhai auth login` — device flow 设备码授权（Key 不经过对话/剪贴板）
-- `ganhai mcp serve` — 本地 stdio MCP 服务（tools 按 API Key scope 动态裁剪）
-- `ganhai mcp install` — 自动配置 Claude Desktop / Cursor / VS Code 的 MCP 设置
+```bash
+npm install -g @ganhaiapp/cli     # 主通道（自动安装当前平台分包）
+npx @ganhaiapp/cli <命令>         # 免安装直接用
+```
+
+## MCP 接入（AI 客户端）
+
+```bash
+ganhai mcp install                # 自动检测 Claude Desktop / Cursor / VS Code 并写入配置
+ganhai mcp serve                  # 或手动在客户端配置：{"mcpServers":{"ganhai":{"command":"ganhai","args":["mcp","serve"]}}}
+ganhai mcp status                 # 查看配置状态
+```
+
+tools 按 API Key 的 scope 动态裁剪——无权限的动作模型连名字都看不到。
+新增服务端端点后 MCP tools 自动获得（元数据驱动，客户端零更新）。
+
+主包不含二进制；平台二进制（win32/linux × x64/arm64、darwin × x64/arm64）经
+optionalDependencies 平台分包提供，npm 按 os/cpu 自动择包。
+
+## 快速开始
+
+```bash
+ganhai auth login --server https://app.example.com
+# → 浏览器打开 /connect?code=XXXX-XXXX 确认授权（Key 不经对话/剪贴板）
+
+ganhai shops list                # 店铺
+ganhai orders list               # 订单
+ganhai orders profit <订单号>     # 利润明细
+ganhai inventory list            # 库存
+ganhai finance summary           # 财务汇总
+ganhai docs                      # 当前 Key 可见的端点清单
+ganhai schema show GET /api/v1/open/erp/orders   # 端点参数/scope 内省
+ganhai whoami                    # 验证登录（org/scope/可用动作数）
+ganhai skill show agent-setup    # Agent 接入手册（教学包）
+```
+
+## Agent 友好（脚本/智能体场景）
+
+- **双渲染**：TTY 输出表格；管道/`--format json`/`GANHAI_FORMAT=json` 输出原样 JSON
+- **stdout 只出数据**，进度/告警走 stderr
+- **退出码**：0 成功 / 2 参数 / 3 认证 / 4 权限 / 5 限流 / 6 服务端 / 7 未订阅
+- **多组织**：`--profile <name>` 或 `GANHAI_PROFILE`（`~/.ganhai/profiles/<name>.json`，0600）
+- 错误消息含 next-command hint（防幻觉：错误后直接给出下一步命令）
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `GANHAI_SERVER` | auth login 默认服务端地址 |
+| `GANHAI_PROFILE` | 默认 profile 名 |
+| `GANHAI_FORMAT` | `json` 强制 JSON 输出 |
+| `GANHAI_HOME` | 配置根目录（默认 `~/.ganhai`，测试用） |
+| `GANHAI_BIN` | 直接指定二进制路径（bin 垫片调试用） |
+
+## 维护者
+
+平台分包构建与发布：`cd packages/cli-platforms && node pack.mjs <build|verify|publish>`
+（先发 5 个平台包，再发主包；Go 源码在仓库 `cli/` 目录）。

package/bin/ganhai.js

@@ -1,6 +1,73 @@
 #!/usr/bin/env node
-// 赶海 GanHai CLI — 占位包（0.0.1）
-// 目的：抢注 @ganhai/cli 包名，防止被占位（SellerPilot 教训）。
-// 正式版随 93-P2 发布：device flow 登录（ganhai auth login）+ MCP stdio（ganhai mcp serve）。
-console.log('赶海 GanHai CLI — 占位版本（0.0.1）')
-console.log('正式版随 93-P2 发布，届时本命令提供 auth/mcp 能力。')
+// ganhai — @ganhaiapp/cli 主包 bin 垫片（93-P2，npm 平台分包模式）
+//
+// 主包不含二进制；平台二进制经 optionalDependencies 按平台分包提供：
+//   @ganhaiapp/cli-win32-x64 / cli-linux-x64 / cli-darwin-x64 / cli-darwin-arm64
+// npm 安装时按 os/cpu 自动择包（装错平台包会被 os/cpu 字段挡下）。
+//
+// 解析顺序：
+//   1. GANHAI_BIN 环境变量 → 直接用该路径（本地开发/覆盖）
+//   2. require.resolve 平台包内的二进制 → spawn 透传
+//   3. 找不到 → 明确报错（含 npx/安装诊断提示）
+//
+// 纪律：垫片不解析参数、不翻译输出——纯 exec 透传（退出码原样返回）。
+
+'use strict'
+
+const { spawn } = require('child_process')
+const path = require('path')
+
+const PLATFORM_PACKAGES = {
+  'win32-x64': '@ganhaiapp/cli-win32-x64',
+  'linux-x64': '@ganhaiapp/cli-linux-x64',
+  'linux-arm64': '@ganhaiapp/cli-linux-arm64',
+  'darwin-x64': '@ganhaiapp/cli-darwin-x64',
+  'darwin-arm64': '@ganhaiapp/cli-darwin-arm64',
+}
+
+function binaryName() {
+  return process.platform === 'win32' ? 'ganhai.exe' : 'ganhai'
+}
+
+function resolveBinary() {
+  // 1. 环境变量显式覆盖（开发态：GANHAI_BIN=../../cli/ganhai.exe ganhai ...）。
+  if (process.env.GANHAI_BIN) {
+    return process.env.GANHAI_BIN
+  }
+  // 2. 平台分包。
+  const pkg = PLATFORM_PACKAGES[`${process.platform}-${process.arch}`]
+  if (pkg) {
+    try {
+      // 平台包 files 只含 bin/，package.json main 指向二进制本身。
+      return require.resolve(path.join(pkg, 'bin', binaryName()))
+    } catch {
+      // optionalDependencies 缺失（npm 老版本/镜像裁剪）→ 落到报错路径。
+    }
+  }
+  return null
+}
+
+function main() {
+  const bin = resolveBinary()
+  if (!bin) {
+    console.error('未找到当前平台的 ganhai 二进制。')
+    console.error(`  platform: ${process.platform}-${process.arch}`)
+    console.error('请尝试：npm install -g @ganhaiapp/cli（会自动安装对应平台分包）')
+    console.error('或用环境变量 GANHAI_BIN 指定二进制路径。')
+    process.exit(127)
+  }
+
+  const child = spawn(bin, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: true,
+  })
+  child.on('error', (err) => {
+    console.error('启动 ganhai 失败：', err.message)
+    process.exit(127)
+  })
+  child.on('close', (code) => {
+    process.exit(code === null ? 130 : code)
+  })
+}
+
+main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ganhaiapp/cli",
-  "version": "0.0.1",
-  "description": "赶海 GanHai CLI（占位包——正式版随 93-P2 发布，届时含设备码登录与 MCP stdio 服务）",
+  "version": "0.2.0",
+  "description": "赶海 GanHai CLI —— 开放 API 命令行客户端（设备码登录 / 只读命令 / MCP stdio 服务 / skill 教学包）",
   "bin": {
     "ganhai": "bin/ganhai.js"
   },
@@ -15,5 +15,12 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "optionalDependencies": {
+    "@ganhaiapp/cli-win32-x64": "0.2.0",
+    "@ganhaiapp/cli-linux-x64": "0.2.0",
+    "@ganhaiapp/cli-linux-arm64": "0.2.0",
+    "@ganhaiapp/cli-darwin-x64": "0.2.0",
+    "@ganhaiapp/cli-darwin-arm64": "0.2.0"
+  }
 }