@limecloud/cli 0.3.0 → 0.6.0

package/README.md

@@ -1,8 +1,57 @@
 # @limecloud/cli
 
-Lime Cloud 官方命令行客户端，提供 `limecloud-cli` 和 `limecloud` 两个命令。命令、参数、请求与响应来自本仓库的公共 OpenAPI，覆盖身份、开放平台、个人账户、运营和平台管理。要求 Node.js 22.12 或更高版本，无第三方运行时依赖，使用 Apache-2.0 许可证。
+Lime Cloud 官方命令行客户端，提供 `limecloud-cli` 和 `limecloud` 两个命令。命令、参数、请求与响应来自本仓库的公共 OpenAPI，覆盖身份、开放平台、个人账户、运营和平台管理。要求 Node.js 22.12 或更高版本，使用 i18next 处理本地消息，采用 Apache-2.0 许可证。
 
-本包参考官方 `@larksuite/cli@1.0.98` 的原生 REA 运行证据，采纳三层命令、Schema 自省、结构化输出、请求预览及设备授权流程，并按 Lime PRD 与实际公共 API 重组领域。不会将飞书办公业务、Bot 身份、DPoP、技能安装或自动创建应用混入 Lime 能力。
+本仓库新增的安装引导以本轮后续发布的新版本为准；npm 的实际版本和内容以 registry 为准，构建和测试不会自动发布。
+
+本包参考官方 `@larksuite/cli@1.0.98` 的 npm 安装器与原生 REA 证据，提供安装引导、三层命令、Schema 自省、结构化输出、请求预览和设备授权，并按 Lime 的实际公共 API 组织领域。
+
+## 安装与首次使用
+
+手动安装：
+
+```sh
+npx @limecloud/cli@latest install
+```
+
+Agent 自动安装：将以下指令发送给你的 AI 工具。
+
+```text
+帮我安装 LimeCloud CLI：https://open.limeai.run/docs/zh-CN/cli-installation-guide.md
+```
+
+英文机器可读指南为 <https://open.limeai.run/docs/cli-installation-guide.md>。
+
+`install` 使用 npm 将本次运行的精确包版本安装到用户目录 `~/.local`，然后引导配置已登记的公共 CLI 客户端。缺少 Client ID 时，CLI 从当前身份服务的 `/runtime/v1/cli` 读取公开部署配置；响应必须与本次 Issuer 一致，不发送令牌或 Secret。部署未开放元数据或获取失败时，配置保持 `pending`，按提示向部署管理员获取公共 CLI Client ID 后手动配置。显式 Client ID 和已有配置优先，`--dry-run` 不读取网络元数据。
+
+安装完成后返回可执行文件目录与 PATH 提示；不会改写 shell 配置。用户明确选择后才发起设备授权，终端返回用户码、浏览器确认链接和恢复命令，不自动批准授权。
+
+```sh
+# 自定义安装目录，可用于隔离环境
+npx @limecloud/cli@latest install --prefix "/YOUR/INSTALL/PREFIX"
+
+# 仅查看安装与配置计划，不联网、不安装、不保存
+npx @limecloud/cli@latest install --dry-run
+
+# 自动化安装：显式配置，保留用户授权步骤
+npx @limecloud/cli@latest install \
+  --client-id "YOUR_REGISTERED_PUBLIC_CLI_CLIENT_ID" \
+  --issuer "https://YOUR_AUTH_ORIGIN" \
+  --api-origin "https://YOUR_API_ORIGIN" \
+  --skip-login
+```
+
+也可用 `LIMECLOUD_INSTALL_PREFIX` 设置安装目录。Windows 的默认目录同样位于当前用户的 `.local`，请通过 npx 执行安装，以复用 npm 的 JavaScript 入口。非交互运行不会询问或自动发起授权；缺少客户端时，结果明确标记配置为 `pending`，按返回命令完成后续步骤。`--no-config` 仅安装，`--login` 显式发起非阻塞设备授权，不能与 `--no-config` 或 `--skip-login` 同用。
+
+```sh
+limecloud-cli config init
+limecloud-cli auth login
+limecloud-cli auth status
+limecloud-cli doctor --offline
+limecloud-cli schema
+```
+
+安装失败会返回 `installation_failed`，检查 npm 网络和目标目录权限后重试同一命令。安装与配置不创建平台应用、不授予业务权限；CLI 不安装全局 Agent Skills。
 
 ## 从仓库运行与分发
 
@@ -20,11 +69,23 @@ pnpm --filter @limecloud/cli test
 npm pack "./packages/cli" --pack-destination ".dev/releases"
 ```
 
-打包前需要存在 `.dev/releases/`。`prepack` 从 `contracts/openapi/identity.json` 和 `management.json` 生成随包合同、检查工作区版本，并复制根 `LICENSE`。分发包仅包含命令入口、实现、公开合同、README 和许可证，不包含凭据、研究产物或测试夹具。npm 包的实际发布状态以 npmjs 为准；本仓库的构建与打包步骤不会自动发布。
+打包前需要存在 `.dev/releases/`。`prepack` 从 `contracts/openapi/identity.json` 和 `management.json` 生成随包合同、检查工作区版本，从 `contracts/i18n/locales.json` 复制唯一语言登记并检查对应 CLI 消息资源，再复制根 `LICENSE`。分发包仅包含命令入口、实现、公开合同、语言登记和消息、README 与许可证，不包含凭据、研究产物或测试夹具。npm 包的实际发布状态以 npmjs 为准；本仓库的构建与打包步骤不会自动发布。
+
+## 输出语言
+
+```sh
+limecloud-cli --help --locale zh-CN
+limecloud-cli schema open.application.list --locale zh-CN
+LIMECLOUD_LOCALE=en limecloud-cli api list
+```
+
+每次命令按 `--locale`、`LIMECLOUD_LOCALE`、`LC_ALL`、`LC_MESSAGES`、`LANG`、英文默认值的顺序协商。显式不支持的 `--locale` 会在读取凭据或请求网络前报错；环境语言未知时回退英文。POSIX 环境中的编码/修饰后缀会被移除，语言别名与明确前缀按统一登记归一，不会将繁体中文模糊匹配为简体中文。
+
+帮助、本地错误、设备授权通知和合同提供的摘要/描述按本次语言输出；合同缺少翻译时回退英文。请求发送规范 `Accept-Language`，响应语言由服务端协商。命令、选项、JSON/CSV 字段、错误码、Scope 与路径保持稳定，不用翻译消息判断程序结果。语言协商不修改配置或用户偏好，并发命令各自持有独立 i18next 实例。
 
 ## 配置与登录
 
-先由平台明确登记公共 CLI 客户端，然后使用其 Client ID。CLI 不创建平台客户端、不保存客户端 Secret，也不会通过本地设置授予平台角色。
+先由平台明确登记公共 CLI 客户端，然后使用其 Client ID。交互式 `config init` 会询问身份服务、业务 API 来源和 Client ID；非交互运行可显式传参。CLI 不创建平台客户端、不保存客户端 Secret，也不会通过本地设置授予平台角色。
 
 ```sh
 limecloud-cli config init \
@@ -215,6 +276,7 @@ JSON 返回统一 Envelope；NDJSON 按记录逐行输出 Envelope；Table 与 C
 | `LIMECLOUD_CLIENT_SECRET` | 仅适用于显式机密/机器客户端身份协议 API；公共 CLI 登录不使用 |
 | `LIMECLOUD_CONFIG` | 私有凭据文件，默认 `~/.config/limecloud/credentials.json` |
 | `LIMECLOUD_SETTINGS` | 公共设置文件，默认与凭据同目录的 `config.json` |
+| `LIMECLOUD_INSTALL_PREFIX` / `install --prefix` | CLI 安装前缀，默认当前用户的 `~/.local` |
 
 显式 Flag 优先于环境变量，之后使用设置文件和匹配的登录记录。每份凭据文件保存一个上下文；多环境可分别设置 `LIMECLOUD_CONFIG` 和 `LIMECLOUD_SETTINGS`。
 

package/bin/limecloud-cli.mjs

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
 import { run } from "../src/cli.mjs";
+// 下游命令提前关闭管道时安静结束，继续执行 finally 以释放私有文件锁。
+process.stdout.on("error", error => { if (error.code !== "EPIPE") throw error; });
 await run(process.argv.slice(2));

package/dist/identity.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Lime Identity API",
-    "version": "0.3.0",
+    "version": "0.6.0",
     "description": "Implemented public OAuth 2.0 and OpenID Connect endpoints. Plain protocol responses; separate from authenticated management BFF APIs."
   },
   "servers": [

package/dist/locales.json

@@ -0,0 +1,17 @@
+{
+  "defaultLocale": "en",
+  "locales": [
+    {
+      "code": "en",
+      "nativeName": "English",
+      "aliases": ["en"],
+      "prefixes": ["en-"]
+    },
+    {
+      "code": "zh-CN",
+      "nativeName": "简体中文",
+      "aliases": ["zh", "zh-CN", "zh-SG", "zh-Hans"],
+      "prefixes": ["zh-Hans-"]
+    }
+  ]
+}