licell 0.10.6 → 0.10.12

package/README.en.md

@@ -2,7 +2,7 @@
 
 [中文 README](./README.md)
 
-Licell is an Alibaba Cloud deployment and operations CLI designed for both humans and AI agents.
+Licell is an Alibaba Cloud CLI for deployment and operations, designed for both humans and AI agents.
 
 It is not just a bag of cloud commands. It is organized around one primary delivery flow:
 
@@ -11,7 +11,7 @@ It is not just a bag of cloud commands. It is organized around one primary deliv
 - one set of atomic resource commands: `fn` / `oss` / `dns` / `domain`
 - one agent-facing surface: `--help` / `--output json` / `mcp` / `skills`
 
-Default region is `cn-hangzhou`. For agent automation, it is strongly recommended to use a dedicated test account or isolated region instead of sharing a production environment directly.
+Default region is `cn-hangzhou`. For agent automation, use a dedicated test account or isolated region instead of sharing a production environment directly. For team sharing, use the team auth distribution workflow described below.
 
 ---
 
@@ -91,22 +91,49 @@ That means command-surface changes can converge across help, MCP, skills, and do
 curl -fsSL https://github.com/agents-infrastructure/licell/releases/latest/download/install.sh | bash
 ```
 
-Then run:
+After installation, run:
 
 ```bash
 licell
 ```
 
-Running bare `licell` is the quickest way to enter the first-run flow.
+Running bare `licell` enters the first-run flow.
 
-### Other installation sources
+### Next step after install: finish auth first
 
-You can also use:
+After installation, complete auth first so Licell is ready to use.
 
-- npm installation, if you already manage CLI tools in a Node environment
-- GitHub Release standalone artifacts, if you want pinned binary distribution
+If you hold your own AK/SK credentials, run:
 
-Upgrade behavior depends on how Licell was installed.
+```bash
+licell login --bootstrap-ram
+```
+
+If auth is distributed by your SRE or platform team, run:
+
+```bash
+licell auth restore '<token>' '<passkey>' --yes
+```
+
+For team usage, see the [Team Auth Distribution](#team-auth-distribution) section below.
+
+### Other install sources and upgrades
+
+- npm global install and GitHub Release binaries are also supported
+- for upgrades, run `licell upgrade`
+- read the detailed upgrade rules below only when needed
+
+<details>
+<summary>Detailed install and upgrade behavior</summary>
+
+- `licell upgrade` follows the current installation source by default
+- if Licell was installed globally with `npm` / `pnpm` / `yarn` / `bun`, it will reuse that package manager for upgrade
+- if Licell is running from project-local dependencies, `node_modules/.bin/licell`, or a dev-linked checkout, it will not do a global self-upgrade by default
+- the install script and standalone binaries come from the same `releases/latest` source; Licell prefers prebuilt single-file executables and falls back to source installation when needed
+- passing `--repo` or `--script-url` forces the GitHub Release upgrade path
+- use `licell upgrade --dry-run` when you need to inspect the exact plan first
+
+</details>
 
 ---
 
@@ -149,6 +176,41 @@ Compatibility notes:
 - Licell still supports some legacy `~/.ali-cli/*` paths
 - current canonical global path is `~/.licell-cli/*`
 
+## Team Auth Distribution
+
+When only a small set of people in a team directly hold high-privilege AK/SK credentials, it is often cleaner to separate “authorization” from “daily usage”:
+
+- the SRE or platform team runs `licell login` on a controlled machine
+- then runs `licell auth export <passkey>`
+- shares the restore token with other team members
+- sends the `passkey` through a separate channel
+- other machines run `licell auth restore <token> <passkey>` without doing `login` again
+
+Example:
+
+```bash
+# SRE machine
+licell login --region cn-hangzhou
+licell auth export 'Team-Shared-Passkey'
+
+# team member machine
+licell auth restore 'licell-auth-v1....' 'Team-Shared-Passkey' --yes
+```
+
+Typical use cases:
+
+- distributing a ready-to-use Licell environment across a team
+- enabling contributors who should not directly hold high-privilege credentials
+- restoring the same environment on temporary machines, CI debug hosts, or collaboration devices
+
+Usage and security guidance:
+
+- send the `token` and `passkey` separately
+- treat the `restore token` as sensitive, even though it is not a plain-text credential
+- use a passkey with at least 12 characters
+- if a shared bundle should no longer be usable, delete the exported object or create a new export
+- after credential rotation, run `login` and `auth export` again instead of reusing older tokens
+
 ---
 
 ## Agent Interfaces

package/README.md

@@ -2,7 +2,7 @@
 
 [English README](./README.en.md)
 
-Licell 是一个面向阿里云、同时面向 AI Agent 的部署与运维 CLI。
+Licell 是一个面向阿里云的部署与运维 CLI，同时兼顾人类用户与 AI Agent。
 
 它不是把一堆云资源命令简单堆在一起，而是围绕一条主线工作流来设计：
 
@@ -11,7 +11,7 @@ Licell 是一个面向阿里云、同时面向 AI Agent 的部署与运维 CLI
 - 一套可组合的资源原子命令：`fn` / `oss` / `dns` / `domain`
 - 一套面向 Agent 的统一表面：`--help` / `--output json` / `mcp` / `skills`
 
-默认地域为 `cn-hangzhou`。用于 Agent 自动化时，建议使用独立测试账号或独立地域，不要直接共用生产环境。
+默认地域为 `cn-hangzhou`。用于 Agent 自动化时，建议使用独立测试账号或独立地域，不要直接共用生产环境。团队协作下，推荐采用后文的“团队授权分发”模式。
 
 ---
 
@@ -91,19 +91,40 @@ Licell 最新架构里，命令不再只是“能执行”，还要“能自我
 curl -fsSL https://github.com/agents-infrastructure/licell/releases/latest/download/install.sh | bash
 ```
 
-安装后建议立即执行：
+安装完成后，可直接运行：
 
 ```bash
 licell
 ```
 
-裸执行 `licell` 会进入更适合新手和 Agent 环境初始化的引导流程。
+裸执行 `licell` 会进入首次引导流程。
 
-### 也可以从 npm / release artifact 使用
+### 安装后下一步：先完成授权
 
-- npm 安装适合已有 Node 工具链环境
-- GitHub Release 中的 standalone artifact 适合固定版本分发
-- 不同安装来源，升级策略不同；下面的“安装与升级”区块会自动同步最新说明
+安装完成后，先完成授权即可开始使用。
+
+持有 AK/SK 时，可直接执行：
+
+```bash
+licell login --bootstrap-ram
+```
+
+如果由 SRE / 平台团队统一分发授权，可直接执行：
+
+```bash
+licell auth restore '<token>' '<passkey>' --yes
+```
+
+团队协作场景，可参考下方的[团队授权分发（推荐）](#团队授权分发推荐)。
+
+### 其他安装方式与升级
+
+- 也支持 npm 全局安装和 GitHub Release 二进制分发
+- 升级时直接运行 `licell upgrade`
+- 如需了解升级来源或升级渠道，再看下面这份说明
+
+<details>
+<summary>安装与升级的详细说明</summary>
 
 <!-- BEGIN GENERATED:README_UPGRADE_GUIDANCE -->
 - `licell upgrade` 会优先按“当前正在执行的安装来源”升级
@@ -114,6 +135,8 @@ licell
 - 可通过 `--channel auto|release|npm|pnpm|yarn|bun` 显式覆盖升级渠道；推荐先用 `licell upgrade --dry-run` 预览计划
 <!-- END GENERATED:README_UPGRADE_GUIDANCE -->
 
+</details>
+
 ---
 
 ## 3 分钟上手
@@ -155,6 +178,41 @@ Licell 有三类核心状态：
 - Licell 仍兼容历史上的 `~/.ali-cli/auth.json` 等旧路径
 - 当前主路径以 `~/.licell-cli/*` 为准
 
+## 团队授权分发（推荐）
+
+当团队中只有少数人直接持有高权限 AK/SK 时，可以把“授权”和“使用”分开：
+
+- SRE / 平台团队在受控机器上执行一次 `licell login`
+- 然后执行 `licell auth export <passkey>`
+- 把导出的 restore token 分发给团队成员
+- 把 `passkey` 通过另一条通道单独发送，不要和 token 放在同一条消息里
+- 其他机器直接执行 `licell auth restore <token> <passkey>`，不需要再次 `login`
+
+示例流程：
+
+```bash
+# SRE 机器
+licell login --region cn-hangzhou
+licell auth export 'Team-Shared-Passkey'
+
+# 成员机器
+licell auth restore 'licell-auth-v1....' 'Team-Shared-Passkey' --yes
+```
+
+适用场景：
+
+- 团队内部批量分发已授权的 `licell` 使用环境
+- 让不直接持有高权限凭证的成员快速开始使用
+- 给临时机器、CI 调试机、协作设备快速恢复环境
+
+使用与安全建议：
+
+- `token` 和 `passkey` 应分开发送，不要放在同一条消息里
+- `restore token` 虽然不是明文凭证，但仍应按敏感信息处理
+- `passkey` 至少 12 位，建议通过密码管理器或单独 IM 通道发送
+- 若需要失效某次分发，可删除对应导出对象，或重新导出新的 token
+- 若团队凭证轮换，应重新执行 `login` / `auth export`，不要继续分发旧 token
+
 ---
 
 ## 面向 Agent 的接口
@@ -490,6 +548,13 @@ licell e2e cleanup <runId>
 <!-- BEGIN GENERATED:README_QUICK_REFERENCE -->
 > 本节由 licell CLI 注册表自动生成；命令变更会同步到 README / docs/reference/agent-surfaces.md / Skills / MCP / Shell Completion。
 
+### Agent Contract
+
+- 原始 CLI JSON 流：过滤前缀 `@@LICELL_JSON@@`，再按 `kind=licell-cli-record` / `schemaVersion=1.0` / `type=event|result|error` 解析。
+- `licell <command> --help --output json`：先读取 `help.kind` / `help.schemaVersion`；当前为 `licell-help@1.0`。
+- `licell_command_catalog`：先读取 `kind` / `schemaVersion`；当前为 `licell-agent-command-catalog@1.0`。
+- MCP tools 的 `metadata.licell` 会显式声明 `schemas.help` / `schemas.commandCatalog`；当前为 `licell-help@1.0` / `licell-agent-command-catalog@1.0`。
+
 ### 命令总览
 
 #### Setup & Identity
@@ -499,7 +564,9 @@ licell e2e cleanup <runId>
 | 命令 | 说明 | 关键选项 |
 |------|------|----------|
 | `licell login` | 配置阿里云凭证 | `--account-id`, `--ak`, `--sk` |
+| `licell auth export [passkey]` | 加密打包当前 licell 全局凭证状态到私有 OSS，并生成 restore token | `--bucket`, `--expires-hours` |
 | `licell auth repair` | 修复凭证权限（推荐：用超级 AK/SK 自动补齐 licell 最小权限并继续使用） | `--account-id`, `--ak`, `--sk` |
+| `licell auth restore <token> [passkey]` | 使用 restore token + passkey 一键恢复 licell 全局凭证状态 | `--yes` |
 | `licell logout` | 清除本地凭证 | — |
 | `licell whoami` | 查看当前登录身份 | — |
 | `licell switch` | 切换默认 region | `--region` |