@freelog-cli/cli2 0.5.1 → 0.5.2

package/dist/docs/README.md

@@ -1,74 +1,93 @@
-# Freelog CLI 使用手册
-
-这套命令只处理**单资源**：普通文件资源、主题和插件。每份资源有独立的本地身份和版本工作稿；合集、批量发行、前端库模板、支付、session 与 studio 多账号不在本期范围。
-
-## 先安装 CLI
-
-CLI 要求 Node.js 20 或更高版本。确认版本后，用 npm 全局安装：
-
-```powershell
-node --version
-npm install --global @freelog-cli/cli2
-freelog-cli --cli-version
-```
-
-若最后一条提示找不到 `freelog-cli`，先重新打开终端；仍无效时，检查 npm 的全局可执行目录是否已经加入 `PATH`。不要以仓库内的 `node packages/...` 命令替代正常使用方式，那只用于本项目开发。
-
-安装完成后运行：
-
-```powershell
-freelog-cli --help
-```
-
-顶层帮助会打印这份本机手册的绝对路径。CLI 不会联网下载文档；发布包内自带完整手册。
-
-## 使用前先知道
-
-开始操作前请先明确两件事：
-
-1. 当前联调使用 `--env dev` 或 `--env test`；省略环境会按 `prod` 处理，而 prod 目前被 CLI 拦截。
-2. 所有命令都以 `--cwd <工程目录>`（或当前目录）定位工程和账号选择器；一个工程只能管理一个资源。
-
-文档仅供阅读，不会在执行命令时修改工程状态。
-
-## 从哪一篇开始
-
-| 你的目标 | 阅读 |
-|---|---|
-| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
-| 先按自己所处的情形找到完整操作路径 | [按场景操作](./09-按场景操作.md) |
-| 创建、发新版本、接入已有资源 | [日常操作](./02-日常路径.md) |
-| 创建主题或插件并发布构建产物 | [主题与插件](./03-主题与插件.md) |
-| 继续、覆盖或丢弃未提交的版本内容 | [版本工作稿](./04-版本工作稿.md) |
-| 修改展示信息、策略和上下架 | [资源管理](./05-资源管理.md) |
-| 命令失败后的处理方式 | [常见问题](./06-常见情况与报错.md) |
-| 环境、登录和本地文件 | [环境与账号](./07-环境与凭据.md) · [本地文件](./08-本地文件参考.md) |
-
-## 三条常用路径
-
-```text
-普通文件：login → init . → create → create-version --prepare → create-version --yes
-主题/插件：login → init theme|widget . --template <id> → create → 构建产物 → create-version --yes
-已有资源：login → bind →（无线上版本则 create-version；有线上版本则 draft pull → update-version）
-```
-
-`create` 只创建线上资源壳，`create-version` 才提交首个 `1.0.0`，`update-version` 才提交后续版本。`version show --local` 看的是未提交工作稿；不带 `--local` 的 `version show` 看的是线上已发版本。
-
-## 通用参数
-
-| 参数 | 含义 |
-|---|---|
-| `--env dev|test` | 选择联调环境。推荐每次显式传入。 |
-| `--cwd <dir>` | 工程目录；决定 `.freelog/` 与工作区账号选择器的位置。 |
-| `--artifact <path>` | 唯一的本地产物路径：`create` / `bind` 可记录默认路径；发版时表示本次上传路径；`version set` 只更新默认路径。 |
-| `--yes` | 不进行交互确认；不会放宽校验，也不会覆盖已有文件。 |
-| `--json` | 将 CLI 错误输出为 `{ "code", "message" }`。 |
-
-新脚本只使用 `--type`，不要使用 `--resource-type`；后者仅为迁移期兼容别名，CLI 会给出弃用警告。`--scaffold`、`artifactMode`、`publish` 和 `release` 不存在于当前命令面。
-
-## 先记住四条规则
-
-1. `init` 只创建本地身份，`create` 只创建线上资源壳，`bind` 只接入已有线上资源；三者都不会上传或发布版本。
-2. 无线上版本时只能用 `create-version` 发布固定的 `1.0.0`；已有线上版本时只能用 `update-version --version ...` 或 `--bump ...`。
-3. 每次真实发版都会从当前文件或构建目录重新上传、分析；工作稿里的旧 SHA1 不能替代已丢失的产物。
-4. 主题/插件传构建目录，CLI 临时压缩目录内容；普通资源传单个文件。两类资源都不需要、也不能由用户先手工打 zip。
+# Freelog CLI 使用手册
+
+这是一套面向**一个资源一次一条命令**的 CLI：支持普通文件、主题和插件。一个工程可以保存多份独立资源身份，但除 `resource sync` 外，一条涉及资源的命令只会处理其中一份。本手册以“先按场景完成工作，再按命令查准确行为”为组织原则；无需阅读设计文档或源码。
+
+不在本期范围：合集、批量发行、前端库模板、支付、session 与 studio 多账号。
+
+## 先安装 CLI
+
+CLI 要求 Node.js 20 或更高版本。确认版本后，用 npm 全局安装：
+
+```powershell
+node --version
+npm install --global @freelog-cli/cli2
+freelog-cli --cli-version
+```
+
+若最后一条提示找不到 `freelog-cli`，先重新打开终端；仍无效时，检查 npm 的全局可执行目录是否已经加入 `PATH`。不要以仓库内的 `node packages/...` 命令替代正常使用方式，那只用于本项目开发。
+
+安装完成后运行：
+
+```powershell
+freelog-cli --help
+```
+
+顶层帮助会打印这份本机手册的绝对路径。CLI 不会联网下载文档；发布包内自带完整手册。
+
+## 使用前先知道
+
+开始操作前请先明确两件事：
+
+1. 当前联调使用 `--env dev` 或 `--env test`；省略环境会按 `prod` 处理，而 prod 目前被 CLI 拦截。
+2. 所有命令都以 `--cwd <工程目录>`（或当前目录）定位工程和账号选择器；一个工程可管理多份独立资源状态。除 `create`、`bind` 和 `resource sync` 外，常规资源命令一次只操作一份：唯一状态可省略选择器，多份状态用 `--resource <selector>` 或 TTY 选择。`create` / `bind` 可以新增或接续身份，`resource sync` 不传选择器时批量同步标题。
+
+文档仅供阅读，不会在执行命令时修改工程状态。
+
+## 先按目标找入口
+
+| 你的目标 | 阅读 |
+|---|---|
+| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 先按自己所处的情形找到完整操作路径 | [按场景操作](./09-按场景操作.md) |
+| 创建、发新版本、接入已有资源 | [资源生命周期](./02-日常路径.md) |
+| 创建主题或插件并发布构建产物 | [主题与插件](./03-主题与插件.md) |
+| 继续、覆盖或丢弃未提交的版本内容 | [版本工作稿](./04-版本工作稿.md) |
+| 修改展示信息、策略和上下架 | [资源管理](./05-资源管理.md) |
+| 命令失败后的处理方式 | [故障恢复](./06-常见情况与报错.md) |
+| 环境、登录和本地文件 | [环境、登录与凭据](./07-环境与凭据.md) · [本地状态文件](./08-本地文件参考.md) |
+| 已知命令、参数或脚本需求，想查准确前置条件和影响 | [完整命令参考](./10-命令参考.md) |
+
+阅读方式：第一次使用先走“快速开始”；已经有工程或资源时先看“按场景操作”；不确定一条命令会读写什么、脚本该带哪些参数时，直接查“完整命令参考”。专题文章解释原因和边界，命令参考负责完整性，两者不互相替代。
+
+## 先判断你处于哪一条路径
+
+```text
+普通文件：login → init . → create → create-version --prepare → create-version --yes
+主题/插件：login → init theme|widget . --template <id> → create → 构建产物 → create-version --yes
+已有资源：login → bind →（无线上版本则 create-version；有线上版本则 version draft pull → update-version）
+```
+
+`init`、`create`、`bind` 不是同义词：`init` 只建本地身份，`create` 只建线上资源壳，`bind` 只接入已存在的线上资源。`create-version` 才提交首个 `1.0.0`，`update-version` 才提交后续版本。`version show --local` 看未提交工作稿；不带 `--local` 的 `version show` 看线上已发版本。
+
+## 通用参数
+
+| 参数 | 含义 |
+|---|---|
+| `--env dev|test` | 选择联调环境。推荐每次显式传入。 |
+| `--cwd <dir>` | 工程目录；决定 `.freelog/` 与工作区账号选择器的位置。 |
+| `--resource <selector>` | 为常规单资源命令选择某一份本地身份：`file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`。单份可省略；多份交互选择，非交互必须明确指定。`create` / `bind` 的新增或接续规则见下文。 |
+| `--artifact <path>` | 当前选中资源的产物路径：`create` / `bind` 可记录默认路径；发版时表示本次上传路径；`version set` 只更新默认路径，绝不选择身份。 |
+| `--yes` | 跳过交互确认；不会放宽校验。仅当命令明确支持时（如覆盖工作稿）才允许覆盖相应状态，绝不覆盖工程目录。 |
+| `--json` | 将 CLI 错误输出为 `{ "code", "message" }`。 |
+
+新脚本只使用 `--type`，不要使用 `--resource-type`；后者仅为迁移期兼容别名，CLI 会给出弃用警告。`--scaffold`、`artifactMode`、`publish` 和 `release` 不存在于当前命令面。
+
+## 先记住四条规则
+
+1. `init` 只创建本地身份，`create` 只创建线上资源壳，`bind` 只接入已有线上资源；三者都不会上传或发布版本。
+2. 无线上版本时只能用 `create-version` 发布固定的 `1.0.0`；已有线上版本时只能用 `update-version --version ...` 或 `--bump ...`。
+3. 每次真实发版都会从当前文件或构建目录重新上传、分析；工作稿里的旧 SHA1 不能替代已丢失的产物。
+4. 主题/插件传构建目录，CLI 临时压缩目录内容；普通资源传单个文件。两类资源都不需要、也不能由用户先手工打 zip。
+
+## 多资源工程：先选身份，再给产物
+
+资源身份与产物路径是两件不同的事。`--resource` 选择要操作的 `N.json`，`--artifact` 只提供该资源本次或默认的文件/构建目录，不能用路径代替资源选择。
+
+| 本地状态数量 | 常规资源命令（如 `status`、`update-version`、`policy list`） |
+|---|---|
+| 0 | 停止并提示先 `init`、`create` 或 `bind`。 |
+| 1 | 自动选择，无需传 `--resource`。 |
+| 多份，交互终端 | 显示文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态，选择后继续。 |
+| 多份，脚本/`--yes` | 停止并列出可复制的 `file:N.json`；传 `--resource` 后重试。 |
+
+选择器优先级建议为 `file:N.json`（最稳定）→ `id:<资源ID>` → `name:<短标识或 username/name>`。`title:<标题>` 只能在标题唯一时使用：标题可改也可重复。`resource sync` 是唯一不传选择器就批量同步当前环境所有本地标题的资源命令。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freelog-cli/cli2",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Freelog CLI",
   "type": "module",
   "license": "MIT",