@freelog-cli/cli2 0.5.2 → 0.5.3

package/dist/docs/01-/345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -32,7 +32,7 @@ freelog-cli --help
 普通资源要先登录，因为资源类型来自平台的当前类型树。已知最终叶子 code 时可直接初始化：
 
 ```powershell
-freelog-cli init . --type RT006003 --yes --env dev
+freelog-cli init . --type RT006003 --artifact video.mp4 --yes --env dev
 ```
 
 不知道 code 时先查询，或不传 `--type` 进入交互式层级选择：
@@ -41,10 +41,10 @@ freelog-cli init . --type RT006003 --yes --env dev
 freelog-cli type search 视频 --env dev
 freelog-cli type list --env dev
 freelog-cli type info RT006003 --env dev
-freelog-cli init . --env dev
+freelog-cli init . --artifact video.mp4 --env dev
 ```
 
-`init` 只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
+通用 `init` 必须用 `--artifact` 指向已经存在的本地文件；交互模式只会帮你选类型，不会扫描或猜测文件。它只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
 
 上一步已在当前目录写入 `.freelog/auth` 也可以再执行 `init .`：CLI 会保留这一个账号选择器，并拒绝覆盖任何其它已有工程内容或资源身份。
 

package/dist/docs/02-/346/227/245/345/270/270/350/267/257/345/276/204.md

@@ -10,8 +10,8 @@ login → init（可选）→ create → create-version → 配策略 / 上架
 
 | 阶段 | 命令 | 结果 |
 |---|---|---|
-| 选类型并立项 | `init [dir] --type <leaf-code>` | 写未绑定本地身份，不创建线上资源。 |
-| 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。 |
+| 选类型并立项 | `init [dir] --type <leaf-code> --artifact <path>` | 用现存产物写未绑定本地身份，不创建线上资源。主题/插件模板 `init theme/widget` 自动创建并记录 `dist`，是例外。 |
+| 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。新建本地状态时 `--artifact` 必填；接续已有未绑定状态时可复用其路径。 |
 | 仅准备首版 | `create-version --prepare` | 上传并解析文件，留下首版工作稿。 |
 | 提交首版 | `create-version --yes` | 提交 `1.0.0` 并清理成功的工作稿。 |
 
@@ -64,7 +64,7 @@ freelog-cli bind <resourceId 或 username/name> --artifact video.mp4 --env dev
 | 没有 `latestVersion` | `create-version --prepare` 后编辑并 `create-version --yes`，发行首版。 |
 | 已有 `latestVersion` | `version draft pull`，编辑工作稿后以 `update-version --version` 或 `--bump` 发新号。 |
 
-主题/插件的 `<path>` 必须是构建目录（`dist` / `build`）；在尚无目录记录的既有项目中，`bind --artifact` 必填。
+主题/插件的 `<path>` 可以是构建目录（`dist` / `build`）或已生成的单个文件（包括 zip）；在尚无产物记录的既有项目中，`bind --artifact` 必填。
 
 - 已有相同资源 id 时，重复 `bind` 是幂等的。
 - 要将一份本地身份换绑到另一个资源，使用 `bind <id> --force --yes`；旧工作稿会被清理。
@@ -82,11 +82,11 @@ freelog-cli version show --local --env dev
 
 ## `--artifact` 的含义
 
-一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时先传 `--resource file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`；不传时交互终端列出完整信息供选择，非交互会列出可复制的 `file:N.json` 示例并停止。标题可重复且会变化，脚本优先使用稳定的 `file:` 或 `id:`。`create` / `bind` 用 `--artifact` 记录将来默认使用的路径，路径可以暂时不存在；`create-version` / `update-version` 用它指定本次文件或目录，发版产物必须真实存在：
+一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时统一传 `--resource id:<资源ID>`、`name:<短标识或username/name>`、唯一的 `title:<标题>`、`artifact:<已记录的相对文件或目录>`，或 AI/脚本精确使用的 `file:N.json`；不传时交互终端列出完整信息供选择，非交互会列出全部可复制候选并停止。标题可重复且会变化，人工和脚本优先使用稳定的 `id:` / `name:`，同一目录多文件可用 `artifact:`。新增本地身份的 `init` / `create` / `bind` 都用 `--artifact` 记录一个**当前已存在**的默认路径；接续已有合格身份时可复用其路径。`create-version` / `update-version` 用它指定本次文件或目录，发版产物也必须真实存在：
 
 | 场景 | 传入的路径 |
 |---|---|
 | 普通资源 `--artifact` | 一个实际文件。目录会被拒绝。 |
-| 主题 / 插件 `--artifact` | 一个构建产物目录，例如 `dist` 或 `build`。zip 文件会被拒绝。 |
+| 主题 / 插件 `--artifact` | 一个构建产物目录（例如 `dist` / `build`）或已生成的单个文件（包括 zip）。目录由 CLI 临时压缩，文件直接上传。 |
 
 发版未传 `--artifact` 时，CLI 只会在已记录路径确实存在时采用它；`--yes` 遇到缺失路径会失败，要求显式给出 `--artifact`。不支持 `--file`；一个工程可管理多份独立资源身份。

package/dist/docs/03-/344/270/273/351/242/230/344/270/216/346/217/222/344/273/266.md

@@ -4,12 +4,13 @@
 
 | 项目 | 主题 | 插件 | 普通文件资源 |
 |---|---|---|---|
-| 初始化 | `init theme` | `init widget` | `init --type <最终叶子>` |
+| 从官方模板初始化 | `init theme` | `init widget` | 不适用 |
+| 接入已有本地产物 | `init --type RT001 --artifact <文件或目录>` | `init --type RT002 --artifact <文件或目录>` | `init --type <最终叶子> --artifact <文件>` |
 | 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
 | 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
 | 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
-| 发版输入 | 构建产物目录 | 构建产物目录 | 一个普通文件 |
-| 上传前处理 | CLI 临时打 zip | CLI 临时打 zip | 直接上传原文件 |
+| 发版输入 | 构建目录或单个文件 | 构建目录或单个文件 | 一个普通文件 |
+| 上传前处理 | 目录由 CLI 临时打 zip；文件直接上传 | 目录由 CLI 临时打 zip；文件直接上传 | 直接上传原文件 |
 
 ## 从线上模板创建工程
 
@@ -41,11 +42,12 @@ my-theme/
 
 ## 接入已有主题或插件项目
 
-非空的既有项目不能再运行 `init`。若它还没有线上资源壳，在项目根直接建壳，并显式记录构建目录：
+已有项目不运行模板子命令；可以先在项目根只建立本地状态，再创建线上资源壳：
 
 ```powershell
 freelog-cli login --env dev
-freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
+freelog-cli init . --type RT001 --artifact dist --yes --env dev
+freelog-cli create --title "已有主题" --name existing-theme --yes --env dev
 freelog-cli create-version --prepare --env dev
 freelog-cli create-version --yes --env dev
 ```
@@ -70,7 +72,7 @@ freelog-cli update-version --bump patch --yes --env dev
 
 不要在已发行资源上再运行 `create-version`，也不要在没有发行版本的资源上运行 `draft pull` / `update-version`。
 
-主题/插件既有项目路径都会把 `dist` / `build` 记录为目录，并在发版时临时压缩；不会补造元数据，也不会覆盖你的源码。
+也可以跳过 `init`，以 `create --type RT001 --artifact dist` 一步建壳；但无论哪条路径，状态写入前产物都必须已经存在。主题/插件既有项目可把 `dist` / `build` 记录为目录，也可记录已生成的单个文件；只有目录会在发版时临时压缩。不会补造元数据，也不会覆盖你的源码。
 
 ## 创建主题或插件资源壳
 
@@ -93,7 +95,7 @@ freelog-cli version set --cwd my-theme --artifact build
 
 这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
 
-## 发布版本：传目录，不传 zip
+## 发布版本：目录自动压缩，文件直接上传
 
 ```powershell
 freelog-cli create-version --cwd my-theme --prepare --env dev
@@ -101,7 +103,7 @@ freelog-cli version show --cwd my-theme --local --env dev
 freelog-cli create-version --cwd my-theme --yes --env dev
 ```
 
-对于 `RT001` / `RT002`，CLI 会把 `dist` 的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。临时 zip 无论成功或失败都会删除，不写入工程，也不写入 `N.json` 或工作稿。
+对于 `RT001` / `RT002`，若路径是 `dist` 这类目录，CLI 会把目录的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。若路径是单个文件（包括用户已准备的 zip），CLI 直接计算该文件的 SHA1、上传和提交，不会再次压缩。临时 zip 无论成功或失败都会删除，不写入工程，也不写入工作稿。
 
 以下输入会停止：
 
@@ -110,15 +112,15 @@ freelog-cli create-version --cwd my-theme --yes --env dev
 | `dist` 不存在 | 要求先生成构建产物。 |
 | 空目录 | 要求先生成实际文件。 |
 | 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
-| 一个 `.zip` 或普通文件 | 拒绝；主题和插件只能交构建目录。 |
+| 一个 `.zip` 或普通文件 | 合法，直接上传；不会再次压缩。 |
 
-后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；只要传入的仍是构建目录，CLI 会重新生成临时 zip。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
+后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；目录会重新生成临时 zip，文件则直接上传。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
 
 ## 这不是两套版本系统
 
 主题/插件和普通资源都使用同一份 `N.version.json` 工作稿，版本号规则、依赖签约规则、属性校验、成功清稿和失败保留规则完全一致；可选配置仅在类型详情允许时可用。唯一的文件层差异是：
 
 - 普通资源的 `filePath` 指向文件，文件 SHA1 即上传文件的 SHA1；
-- 主题/插件的 `filePath` 指向目录，文件 SHA1 与 `filename` 指向 CLI 临时 zip 的结果。
+- 主题/插件的 `filePath` 可指向目录或文件：目录时 SHA1 与 `filename` 指向 CLI 临时 zip，文件时二者指向原文件。
 
-因此不要手工把 zip 记进 `filePath`，也不要因为主题是目录而另建一套版本缓存。
+因此可以把已有 zip 记进 `filePath`，但不要因为主题/插件的产物形态而另建一套版本缓存。

package/dist/docs/04-/347/211/210/346/234/254/345/267/245/344/275/234/347/250/277.md

@@ -4,6 +4,8 @@
 
 工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
 
+多资源工程中，本页所有命令都加同一个 `--resource <selector>`：人工优先 `id:`、`name:` 或 `artifact:<当前文件>`，标题唯一时可用 `title:`；AI、脚本和恢复可用精确的 `file:N.json`。例如 `version draft pull --resource artifact:video.mp4` 是选择视频资源，不是上传文件。
+
 | 要做什么 | 命令 | 是否提交线上版本 |
 |---|---|---|
 | 看线上版本 | `version show [--version <ver>]` | 否 |
@@ -11,7 +13,7 @@
 | 从已发版本建立更新稿 | `version draft pull [--version <ver>]` | 否 |
 | 准备首版稿 | `create-version --prepare` | 否 |
 | 编辑稿 | `version attr` / `option` / `dep` / `version draft description` | 否；依赖签约是独立平台动作 |
-| 丢弃稿 | `version draft discard` | 否 |
+| 丢弃稿 | `version draft discard [--yes]` | 否 |
 | 提交 | `create-version --yes` / `update-version --version <ver> --yes` | 是 |
 | 改已发布版本的说明 | `version description --version <ver> --description <文本>` | 是；仅更新该已发版本说明 |
 
@@ -32,12 +34,12 @@ freelog-cli create-version --yes --env dev
 已有版本时，以线上版本为底建立稿：
 
 ```powershell
-freelog-cli version draft pull --version 1.0.0 --env dev
-freelog-cli version draft description --description "本次更新说明" --env dev
-freelog-cli update-version --version 1.1.0 --yes --env dev
+freelog-cli version draft pull --resource artifact:video.mp4 --version 1.0.0 --env dev
+freelog-cli version draft description --resource artifact:video.mp4 --description "本次更新说明" --env dev
+freelog-cli update-version --resource artifact:video.mp4 --version 1.1.0 --yes --env dev
 ```
 
-已有本地稿时，`version draft pull` 默认不会覆盖。明确要重来时使用 `--yes`；命令会打印将被覆盖的来源、文件和条目摘要。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
+已有本地稿时，`version draft pull` 会先验证目标线上版本。TTY 显示旧稿摘要并以“否”为默认确认；脚本必须显式传 `--yes` 才能覆盖。`version draft discard` 同样先显示摘要并确认；脚本必须 `--yes`，没有工作稿时安全退出。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
 
 ## 两种“版本说明”不要混用
 
@@ -86,7 +88,7 @@ CLI 列出的是对方资源的全部启用策略，不按免费/付费筛选。
 
 ## 文件变化与恢复
 
-发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给构建目录。新脚本不要使用 `--file`。
+发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给文件或构建目录（仅目录会临时压缩）。新脚本不要使用 `--file`。
 
 不要手工改 `N.version.json`。该文件有严格 schema，损坏、旧格式或身份不一致时 CLI 会保留原文件并停止；可明确丢弃工作稿，或从线上版本重新 `draft pull`。
 
@@ -105,4 +107,4 @@ freelog-cli update-version --reset --bump patch --yes --env dev
 freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
 ```
 
-`--reset` 会在后续准备、线上检查或提交之前立即删除选中资源的工作稿；即使后续步骤失败，旧稿也不会恢复。因此默认优先用可检查的两步：先 `version show --local`，再 `version draft discard`，确认成功后才执行下一条命令。只有已确认资源、命令路径和 `--resource`（多资源工程）都正确时，才使用 `--reset`。`--reuse-version` 不会重写工作稿，它只声明本次提交认可的线上底，必须与工作稿 `fromVersion` 一致。
+`--reset` 会先校验资源路由、版本路径和产物路径；有旧稿时，TTY 显示摘要并以“否”为默认确认，脚本必须带 `--yes`。取消、无效版本号、错误的首版/更新版路径或缺失产物时，旧稿保持不动。确认后才删除旧稿并继续；若之后网络、拉取或提交失败，旧稿不会恢复，因为你已经明确放弃它。因此默认仍推荐可检查的两步：先 `version show --local`，再 `version draft discard`，确认成功后才执行下一条命令。`--reuse-version` 不会重写工作稿，它只声明本次提交认可的线上底，必须与工作稿 `fromVersion` 一致。

package/dist/docs/05-/350/265/204/346/272/220/347/256/241/347/220/206.md

@@ -2,13 +2,15 @@
 
 本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
 
+多资源工程中，本页除不带选择器即批量的 `resource sync` 外，每条命令都加 `--resource <selector>`。优先用 `id:`、`name:` 或 `artifact:<当前文件>`；`file:N.json` 保留给 AI、脚本和恢复。
+
 ## 查看现状
 
 ```powershell
-freelog-cli status --env dev
-freelog-cli version show --env dev
-freelog-cli version show --version 1.0.0 --env dev
-freelog-cli policy list --env dev
+freelog-cli status --resource id:<资源ID> --env dev
+freelog-cli version show --resource id:<资源ID> --env dev
+freelog-cli version show --resource id:<资源ID> --version 1.0.0 --env dev
+freelog-cli policy list --resource id:<资源ID> --env dev
 ```
 
 `status` 汇总本地身份、是否存在工作稿和线上 latest；`version show` 与 `policy list` 读取平台当前结果。若只想看本地未交内容，用 `version show --local`。
@@ -16,9 +18,9 @@ freelog-cli policy list --env dev
 ## 修改展示信息
 
 ```powershell
-freelog-cli update --title "新标题" --yes --env dev
-freelog-cli update --intro "一句话简介" --tags "教程,视频" --yes --env dev
-freelog-cli update --cover "<封面值>" --yes --env dev
+freelog-cli update --resource id:<资源ID> --title "新标题" --yes --env dev
+freelog-cli update --resource id:<资源ID> --intro "一句话简介" --tags "教程,视频" --yes --env dev
+freelog-cli update --resource id:<资源ID> --cover "<封面值>" --yes --env dev
 ```
 
 `update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。

package/dist/docs/06-/345/270/270/350/247/201/346/203/205/345/206/265/344/270/216/346/212/245/351/224/231.md

@@ -10,16 +10,16 @@
 | `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
 | `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
 | 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
-| `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会列出可复制的 `file:N.json`，也可传 `id:<资源ID>`、`name:<标识符>`。 |
+| `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会逐份列出可复制的 `id:`、`name:`、唯一 `title:`、`artifact:` 和 `file:N.json`。 |
 | `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传 `--resource` 选身份，不能复用旧 SHA1。 |
 | `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
-| `主题/插件请指定构建产物目录，不要自己打 zip` | 主题/插件给了 zip 或普通文件。 | 传 `dist` / `build` 这类非空构建目录。 |
 | `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
 | 已经有发行版本，请用 `update-version` | 对已有版本的资源调用了 `create-version`。 | 用 `version draft pull` 后运行 `update-version`。 |
 | 还没有发行版本，请先 `create-version` | 对首版资源调用了 `update-version` 或 `draft pull`。 | 使用 `create-version --prepare` 或 `create-version --yes`。 |
 | 工作稿与身份不一致 / 不支持 schemaVersion=1 | 本地工作稿损坏、过期或属于另一资源。 | 保留原文件以便检查；明确 `version draft discard`，或从线上 `draft pull` 重建。 |
 | 工作稿来源不是当前 latest | 线上已有新版本，而本地稿仍基于其它版本。 | 优先检查后用 `version draft pull --yes` 重建；确认要继续使用原底时，在 `update-version` 上明确传匹配的 `--reuse-version <版本>`。 |
-| 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`，最后执行下一步；`--reset` 会在后续检查前立即丢弃工作稿，仅在已核对资源和命令路径后使用。 |
+| `有未提交工作稿；请加 --yes 确认…` | 脚本试图丢弃或覆盖工作稿，却没有显式确认。 | 检查目标资源后重试并加 `--yes`；交互终端可阅读摘要后确认或取消。 |
+| 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`（TTY 确认；脚本加 `--yes`），最后执行下一步；`--reset` 会先校验再确认，确认后的后续失败不会恢复旧稿。 |
 | `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
 | `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
 | 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
@@ -30,7 +30,7 @@
 
 - 不要只删除 `N.json` 或只删除 `N.version.json`。确需放弃一份本地状态时，先备份，再删除同号的完整状态单元（`N.json` 与 `N.version.json`）；未提交工作稿会永久丢失，之后可在空位重新 `bind`。
 - 不要复制或编辑 `.freelog/auth`；该文件不含可移植秘密，真正的凭据在当前操作系统的凭据库中。
-- 不要手工打 zip 后交给主题/插件发版；CLI 只接收构建目录。
+- 主题/插件给目录时由 CLI 临时压缩；若已有 zip 或其它单个产物文件，可直接作为 `--artifact` 提交，不会再次压缩。
 - 不要在失败后重新运行 `create` 试图补救已有线上壳；先用 `bind` 接入已有资源。
 - 不要用旧命令参数 `--scaffold` 或把 `--resource-type` 当作常规接口；前者不存在，后者仅为弃用兼容。
 

package/dist/docs/08-/346/234/254/345/234/260/346/226/207/344/273/266/345/217/202/350/200/203.md

@@ -36,11 +36,13 @@ my-project/
 | `typeCode` | 普通资源是已验证的最终叶子；主题/插件固定为 `RT001` / `RT002`。 |
 | `resourceId` 与 `name` | 绑定后成对出现；`name` 是当前账号命名空间内不可重复的短标识。未绑定 `init` 身份不应预写。 |
 | `title` | 创建、bind 或 `resource sync` 写入的本地展示/选择信息；标题可重复且会变化，不是线上写入依据。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
-| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件是构建目录，例如 `dist`；绝对路径与 `..` 越界路径不合法。 |
+| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件可以是构建目录（例如 `dist`）或单个文件（包括 zip）；绝对路径与 `..` 越界路径不合法。 |
 | `env` | 非 prod 的已绑定资源会记录 `dev` 或 `test`。 |
 
 这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地选择/展示缓存保存，可由 `resource sync` 更新。
 
+`N.json` 不要求用户手工记编号。所有单资源命令可用 `--resource id:<资源ID>`、`name:<标识>`、唯一的 `title:<标题>` 或 `artifact:<filePath>` 选中它；`file:N.json` 是仍完整支持的精确状态文件形式，适合 AI、脚本和恢复。
+
 ## `N.version.json`：未提交工作稿
 
 工作稿始终包含资源 id、资源类型、稿类型（`initial` / `update`）、文件 SHA、分析 SHA、属性、可选配置、依赖及恒为空的兼容字段。它只在资源已创建或 bind 后出现。
@@ -65,7 +67,7 @@ my-project/
 }
 ```
 
-主题/插件在这里记录的是 CLI 临时 zip 的 `filename` / SHA1；身份里的 `filePath` 仍是构建目录。普通资源则记录原文件的 `filename` / SHA1。
+主题/插件使用目录时，这里记录 CLI 临时 zip 的 `filename` / SHA1；使用单个文件时记录原文件的 `filename` / SHA1。身份里的 `filePath` 保留用户选择的目录或文件。普通资源始终记录原文件的 `filename` / SHA1。
 
 ## `index.json`、`.lock` 与 `.txn.json`
 

package/dist/docs/09-/346/214/211/345/234/272/346/231/257/346/223/215/344/275/234.md

@@ -2,27 +2,26 @@
 
 本页是决策入口：先判断资源是否已经在线上存在、是否已经发行过版本、当前工程是否已有 `.freelog/` 身份，再复制对应路径。不要把 `init`、`create`、`bind` 当成同义词：它们分别是立项、建线上资源壳、接入已有线上资源。需要解释命令语义时回到专题页；需要完整参数和副作用时查[完整命令参考](./10-命令参考.md)。
 
-所有例子以 `--env dev` 为例；多资源工程中，每一条涉及某资源的命令都补上 `--resource <selector>`；产物始终用 `--artifact <path>`。
+所有例子以 `--env dev` 为例；多资源工程中，除新增或接续身份的 `create` / `bind` 外，每一条涉及某资源的命令都补上 `--resource <selector>`；产物始终用 `--artifact <path>`。
 
 ## 先选入口
 
 | 你现在的情况 | 从这里开始 | 不要做 |
 |---|---|---|
-| 空目录，普通文件资源还未上线 | `init --type <最终叶子>`，再 `create` | 把父类型或类型名称交给 `--type`。 |
-| 已有普通文件工程、没有线上资源 | `create --type <最终叶子> --artifact <文件>` | 为了建壳强行覆盖工程执行 `init`。 |
+| 已有普通文件、资源还未上线 | `init --type <最终叶子> --artifact <文件>`，再 `create`；也可直接 `create --type … --artifact …` | 把父类型或类型名称交给 `--type`，或让状态没有产物路径。 |
 | 空目录，要从官方主题/插件模板开始 | `init theme|widget <目录> --template <id>` | 选择资源类型，或手工复制本地模板。 |
-| 已有主题/插件工程、没有线上资源 | `create --type RT001|RT002 --artifact <dist|build>` | 对非空工程再执行 `init`，或自己先打 zip。 |
+| 已有主题/插件工程、没有线上资源 | `init --type RT001|RT002 --artifact <文件或目录>`，再 `create`；也可直接 `create` | 运行会复制模板的 `init theme/widget`，或让 CLI 再压已准备的 zip。 |
 | 线上有自己的壳但没有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `create-version` | 再次 `create`。 |
 | 线上已有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `version draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
 | 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
-| 同一工程有多份资源身份 | 先用 `status --resource file:N.json` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact`、标题或状态文件顺序猜测目标。 |
+| 同一工程有多份资源身份 | 先用 `status --resource id:<资源ID>`、`name:<标识>` 或 `artifact:<文件>` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact` 上传参数、标题或状态文件顺序猜测目标。 |
 | 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
 
 ## 场景一：从空目录发行普通文件首版
 
 ```powershell
 freelog-cli login --env dev
-freelog-cli init . --type RT006003 --yes --env dev
+freelog-cli init . --type RT006003 --artifact video.mp4 --yes --env dev
 freelog-cli create --title "我的视频" --name my-video --artifact video.mp4 --yes --env dev
 freelog-cli create-version --prepare --env dev
 freelog-cli version show --local --env dev
@@ -42,7 +41,24 @@ freelog-cli create-version --prepare --env dev
 freelog-cli create-version --yes --env dev
 ```
 
-`create` 只登记文件路径并创建资源壳；文件不存在、为空、过大或解析失败时，会在 `create-version` 停止，线上不会出现半个版本。
+`create` 在建壳前确认 `--artifact` 指向工程内真实文件；它不上传文件。空文件、大小限制或内容解析等发行校验仍会在 `create-version` 停止，线上不会出现半个版本。
+
+### 同一素材目录连续发行多个独立资源
+
+不需要为每个视频、图片另建工程目录。一个素材目录可以依次为每个文件建立一份资源身份：
+
+```powershell
+# media/ 下同时有 video.mp4 与 cover.jpg
+freelog-cli create --title "视频" --name my-video --type <视频叶子code> --artifact video.mp4 --yes --env dev
+# 写入 .freelog/1.json，filePath=video.mp4
+freelog-cli create --title "封面图" --name my-cover --type <图片叶子code> --artifact cover.jpg --yes --env dev
+# 写入 .freelog/2.json，filePath=cover.jpg
+
+freelog-cli create-version --resource artifact:video.mp4 --prepare --env dev
+freelog-cli create-version --resource artifact:cover.jpg --prepare --env dev
+```
+
+第二次 `create` 不会要求选择或覆盖 `1.json`：在没有未绑定状态时，它新增下一个编号。后续发版、状态、上下架等操作才用 `--resource` 精确选择其中一份；可用 `id:`、`name:`、唯一 `title:`、`artifact:` 或 AI/脚本使用的 `file:N.json`。`--artifact` 从不承担资源选择职责。
 
 ## 场景三：从官方模板创建主题或插件并发行首版
 
@@ -60,17 +76,18 @@ freelog-cli create-version --cwd my-theme --yes --env dev
 
 ## 场景四：已有主题或插件工程，创建首版资源
 
-既有非空工程不运行 `init`，也没有必要补造模板元数据。明确其固定类型和构建目录：
+既有项目不运行会复制模板的 `init theme`，也没有必要补造模板元数据。先明确其固定类型和构建目录：
 
 ```powershell
 freelog-cli login --env dev
-freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
+freelog-cli init . --type RT001 --artifact dist --yes --env dev
+freelog-cli create --title "已有主题" --name existing-theme --yes --env dev
 # 自己完成构建后
 freelog-cli create-version --prepare --env dev
 freelog-cli create-version --yes --env dev
 ```
 
-插件使用 `--type RT002`。`dist` / `build` 是目录；CLI 仅在提交前临时压缩其中内容，绝不把 zip 写进 `filePath`。
+插件在 init 使用 `--type RT002`。也可直接 `create --type RT001|RT002 --artifact dist` 一步建壳。`dist` / `build` 是目录时，CLI 仅在提交前临时压缩其中内容；若指定已有 zip 或其它文件，则直接上传并可记录到 `filePath`。
 
 ## 场景五：自己的线上资源未发行，在本地补接后发首版
 
@@ -81,7 +98,7 @@ freelog-cli create-version --prepare --env dev
 freelog-cli create-version --yes --env dev
 ```
 
-主题/插件把 `video.mp4` 换成 `dist` 或 `build`。`bind` 会从平台读取类型；对主题/插件，没有已记录目录时须传 `--artifact`。
+主题/插件把 `video.mp4` 换成 `dist`、`build` 或已有 zip。`bind` 会从平台读取类型；对主题/插件，没有已记录产物时须传 `--artifact`。
 
 ## 场景六：自己的线上资源已发行，在本地接入并发新版本
 
@@ -97,9 +114,9 @@ freelog-cli update-version --bump patch --yes --env dev
 
 ## 场景七：构建路径、工作稿或多资源工程发生变化
 
-- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --resource file:N.json --artifact build`。只更新记录，不上传也不提交。
+- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --resource artifact:dist --artifact build`。只更新记录，不上传也不提交。
 - 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
-- 一个工程中有多份身份：`create-version`、`update-version`、`version draft pull` 等既有资源操作传对应的 `--resource`；不传时 TTY 可选择，非交互会停止，不会猜第一份。`create`、`bind` 例外：它们可在没有未绑定状态时新增 `N.json`；要接续某份未绑定状态时传 `--resource file:N.json`。发版要换产物时再传 `--artifact`。
+- 一个工程中有多份身份：`create-version`、`update-version`、`version draft pull` 等既有资源操作传对应的 `--resource id:<ID>`、`name:<标识>`、`artifact:<当前文件>` 或 AI/脚本使用的 `file:N.json`；不传时 TTY 可选择，非交互会停止，不会猜第一份。`create`、`bind` 例外：它们可在没有未绑定状态时新增 `N.json`；要接续某份未绑定状态时优先传 `--resource artifact:<当前文件>`，没有可用产物路径时才用 `file:N.json`。发版要换产物时再传独立的 `--artifact <新路径>`。
 - 想从另一线上版本重新开始：`version draft pull --version <版本> --yes`；这会覆盖当前未提交工作稿，先看命令打印的摘要。
 
 ## 场景八：版本表单、依赖和上线
@@ -117,7 +134,7 @@ freelog-cli version show --version 1.1.0 --env dev
 freelog-cli version description --version 1.1.0 --description "补充发布说明" --env dev
 ```
 
-这与 `version draft description` 不同：后者只修改尚未提交的更新稿。多资源工程在两条命令上都传相同的 `--resource file:N.json`。
+这与 `version draft description` 不同：后者只修改尚未提交的更新稿。多资源工程在两条命令上都传相同的 `--resource id:<资源ID>`、`name:<标识>` 或 `artifact:<文件>`。
 
 ## 场景十：更新稿过期，选择重建或继续旧底
 
@@ -135,4 +152,4 @@ freelog-cli update-version --bump patch --yes --env dev
 freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
 ```
 
-若工作稿本身不要了，可把前两步改为 `update-version --reset --bump patch --yes`；它会删除当前稿后重新建立，不要把它当成无损刷新。
+若工作稿本身不要了，可把前两步改为 `update-version --reset --bump patch --yes`；它会先校验路径与版本号，确认后才删除当前稿并重新建立。TTY 可阅读摘要后确认；确认后的网络或提交失败不会恢复旧稿，不要把它当成无损刷新。

package/dist/docs/10-/345/221/275/344/273/244/345/217/202/350/200/203.md

@@ -2,7 +2,21 @@
 
 本页是发布包内的命令索引：列出当前 CLI 的全部公开命令、何时使用以及它会不会改变线上资源或本地文件。首次完成任务请优先看[按场景操作](./09-按场景操作.md)；执行已知命令、编写脚本或排查影响时以本页为准。
 
-所有示例省略 `freelog-cli` 前缀后的公共参数。推荐每次显式传 `--env dev` 或 `--env test`；多资源工程的**常规单资源命令**要传 `--resource file:N.json`（交互终端可选择）。`create` / `bind` 可新增或接续身份，`resource sync` 不传选择器时批量同步标题，它们不是这条规则的反例而是不同的生命周期语义。`--yes` 只跳过交互确认，不会放宽校验。详细选择规则见[首页](./README.md#多资源工程先选身份再给产物)。
+所有示例省略 `freelog-cli` 前缀后的公共参数。推荐每次显式传 `--env dev` 或 `--env test`。除 `login`、`logout`、`init`、`template`、`type`、新增/接续生命周期的 `create` / `bind` 与批量 `resource sync` 外，**本页每一条命令都接受并在多资源工程中需要** `--resource <selector>`。`--yes` 只跳过交互确认，不会放宽校验。详细选择规则见[首页](./README.md#多资源工程先选身份再给产物)。
+
+## 公共资源匹配参数
+
+一个目录可有多个视频、图片或其它资源；用户不需要记住 `.freelog/2.json`。对任何常规单资源命令使用同一个参数：
+
+```powershell
+--resource id:<资源ID>                 # 最稳定，推荐
+--resource name:<username/短标识>       # 最稳定，推荐
+--resource title:<资源标题>             # 标题唯一时可用
+--resource artifact:<相对文件或目录>    # 例如 artifact:video.mp4
+--resource file:N.json                 # AI、脚本、恢复时的精确状态文件
+```
+
+`--resource artifact:video.mp4` 是**选择**已记录为 `video.mp4` 的资源；发行命令中的 `--artifact video-v2.mp4` 才是本次上传新文件。二者可以同时出现。单份状态自动选择；多份状态在 TTY 展示标题、标识符、ID、产物和工作稿供选择，非交互则列出上述可复制候选并停止。标题重复时使用 `id:`、`name:`、`artifact:` 或 `file:`。
 
 ## 发现命令与获得帮助
 
@@ -21,7 +35,7 @@ freelog-cli --cli-version
 |---|---|---|
 | `login [--global]` | 登录当前工作区；脚本可用 `--login-name`、`--password-stdin --yes`。 | 将秘密写入系统凭据库，并写入工作区或全局选择器。 |
 | `logout [--global]` | 切换账号或清除本地登录选择。 | 只清选择器及明确孤立的凭据；不删除工程或线上资源。 |
-| `init [dir] [--type <叶子类型>]` | 在空目录创建普通资源的本地身份。 | 新建未绑定 `N.json`，不创建线上资源。 |
+| `init [dir] [--type <叶子类型>] --artifact <路径>` | 用已存在的普通文件，或主题/插件的文件/目录，创建未绑定本地身份。 | 新建未绑定 `N.json`，不创建线上资源；不会扫描或猜测产物。 |
 | `init theme <dir> [--template <id>]` | 从主题模板创建新工程。 | 固定主题类型 `RT001` 与默认构建目录 `dist`。 |
 | `init widget <dir> [--template <id>]` | 从插件模板创建新工程。 | 固定插件类型 `RT002` 与默认构建目录 `dist`。 |
 | `template list` | 查看可用于主题/插件初始化的模板。 | 只读。 |
@@ -34,62 +48,66 @@ freelog-cli --cli-version
 
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
-| `create --title <标题> --name <短标识> [--type <叶子类型>] [--artifact <路径>]` | 线上还没有该资源壳时创建它。已有唯一未绑定身份时会接续它；没有未绑定身份时新增一份本地状态。 | 创建线上资源壳并写入 `resourceId`；只记录产物路径，不上传、不发版、不上架。 |
-| `bind <资源ID或username/name> [--artifact <路径>] [--force --yes]` | 线上已有且属于当前账号的资源，需要接入本地工程。 | 从平台读取身份，写入或接续一份 `N.json`；不拉版本、不上传。 |
-| `status` | 想同时确认选中资源的本地身份、工作稿和线上状态。 | 只读。 |
+| `create --title <标题> --name <短标识> [--type <叶子类型>] [--artifact <路径>] [--resource <selector>]` | 线上还没有该资源壳时创建它。已有唯一未绑定身份时会接续它；没有未绑定身份时新增一份本地状态。多份未绑定身份时用选择器指定要接续的那份。 | 创建线上资源壳并写入 `resourceId`；只记录产物路径，不上传、不发版、不上架。 |
+| `bind <资源ID或username/name> [--artifact <路径>] [--resource <selector>] [--force --yes]` | 线上已有且属于当前账号的资源，需要接入本地工程。 | 从平台读取身份，写入或接续一份 `N.json`；不拉版本、不上传。 |
+| `status [--resource <selector>]` | 想同时确认选中资源的本地身份、工作稿和线上状态。 | 只读。 |
 | `resource sync [--resource <selector>]` | 网页或其它机器改过标题，需要刷新本地标题。 | 不传选择器时批量按资源 ID 同步当前环境全部绑定身份的 `title`；传选择器时只同步一份。 |
-| `version set --artifact <路径>` | 文件改名、构建目录从 `dist` 变成 `build`，只想更新默认路径。 | 只改选中 `N.json.filePath`；不上传、不提交。 |
+| `version set --artifact <路径> [--resource <selector>]` | 文件改名、构建目录从 `dist` 变成 `build`，只想更新默认路径。 | 只改选中 `N.json.filePath`；不上传、不提交。 |
 
 `--name` 是当前账号命名空间中不可重复、创建后不可改的短标识；`--title` 是可修改且可重复的展示名称。创建后的标题用 `update --title` 修改；本地标题用 `resource sync` 对齐。
 
 ## 版本：查看、工作稿与提交
 
+本节每条命令均可加 `[--resource <selector>]`；多资源工程中不传时按上文公共规则选择或停止。
+
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
-| `version show [--version <已发号>]` | 查看线上 latest 或指定已发行版本。 | 只读，不覆盖本地工作稿。 |
-| `version show --local` | 查看未提交工作稿。 | 只读；没有工作稿会提示失败。 |
-| `version draft pull [--version <已发号>]` | 已有线上版本，基于 latest 或指定版本建立更新稿。 | 写入 `N.version.json`；已有稿默认拒绝覆盖。 |
-| `version draft pull --yes` | 明确放弃当前工作稿，重新拉取版本。 | 覆盖工作稿；先打印即将丢失的摘要。 |
-| `version draft discard` | 明确放弃当前工作稿。 | 删除选中资源的 `N.version.json`；没有稿时安全退出。 |
-| `version draft description --description <文本>` | 修改**更新工作稿**的版本说明。 | 只写工作稿；不发新版本。 |
-| `version description --version <已发号> --description <文本>` | 修改一个**已发布版本**的说明，而不创建新版本。 | 唯一直接更新线上版本信息的命令；不写工作稿。 |
-| `version attr add|set|rm|list` | 维护工作稿的自定义属性。 | 写操作只改工作稿；`list` 只读。 |
-| `version option add|set|rm|list` | 维护工作稿的可选配置。 | 写操作只改工作稿；仅资源类型允许时可用。 |
-| `version dep add|range|rm|list` | 维护工作稿中的依赖及版本范围。 | 写操作只改工作稿；首次签约可能产生独立平台授权动作。 |
-| `create-version --prepare [--artifact <路径>]` | 尚无已发版本时上传分析并建立首版工作稿。 | 写工作稿，不提交线上版本。 |
-| `create-version --yes [--artifact <路径>]` | 尚无已发版本时提交固定的 `1.0.0`。 | 上传并提交首版；成功后删除工作稿并回写有效产物路径。 |
-| `create-version --reset ...` | 首版工作稿确认不要了，直接从空表重新走本次命令。 | 会立即丢弃工作稿，再继续准备或提交；后续失败不会恢复旧稿。 |
-| `update-version --version <新号> --yes [--artifact <路径>]` | 已有线上版本，指定后续版本号并提交。 | 上传并提交新版本；成功后删除工作稿。 |
-| `update-version --bump patch|minor|major --yes` | 已有线上版本，按 latest 自动计算新版本号。 | 与上条相同；不能和 `--version` 同用。 |
-| `update-version --reuse-version <已发号> ...` | 工作稿的底不是当前 latest，且明确以该已发号为底提交。 | 只改变本次提交认可的底；工作稿来源必须匹配。 |
-| `update-version --reset ...` | 当前更新稿确认不要了，要丢掉并按本次指定底重新拉取后继续。 | 会立即删除现有工作稿，再继续更新流程；后续失败不会恢复旧稿。 |
-
-首版只能使用 `create-version`，已有版本只能使用 `update-version`。`--artifact` 在发行命令中是本次上传的真实文件/构建目录；普通资源必须是文件，主题/插件必须是非空构建目录。不要把 `version draft description` 与 `version description` 混用：前者改未提交更新稿，后者改已发布版本。
+| `version show [--version <已发号>] [--resource <selector>]` | 查看线上 latest 或指定已发行版本。 | 只读，不覆盖本地工作稿。 |
+| `version show --local [--resource <selector>]` | 查看未提交工作稿。 | 只读；没有工作稿会提示失败。 |
+| `version draft pull [--version <已发号>] [--resource <selector>]` | 已有线上版本，基于 latest 或指定版本建立更新稿。 | 写入 `N.version.json`；有旧稿时 TTY 默认不覆盖并确认，脚本须 `--yes`。 |
+| `version draft pull --yes [--resource <selector>]` | 明确放弃当前工作稿，重新拉取版本。 | 校验目标线上版本后覆盖工作稿；先打印即将丢失的摘要。 |
+| `version draft discard [--yes] [--resource <selector>]` | 明确放弃当前工作稿。 | TTY 显示摘要并默认不删；脚本须 `--yes`。确认后删除选中 `N.version.json`；没有稿时安全退出。 |
+| `version draft description --description <文本> [--resource <selector>]` | 修改**更新工作稿**的版本说明。 | 只写工作稿；不发新版本。 |
+| `version description --version <已发号> --description <文本> [--resource <selector>]` | 修改一个**已发布版本**的说明，而不创建新版本。 | 唯一直接更新线上版本信息的命令；不写工作稿。 |
+| `version attr add|set|rm|list [--resource <selector>]` | 维护工作稿的自定义属性。 | 写操作只改工作稿；`list` 只读。 |
+| `version option add|set|rm|list [--resource <selector>]` | 维护工作稿的可选配置。 | 写操作只改工作稿；仅资源类型允许时可用。 |
+| `version dep add|range|rm|list [--resource <selector>]` | 维护工作稿中的依赖及版本范围。 | 写操作只改工作稿；首次签约可能产生独立平台授权动作。 |
+| `create-version --prepare [--artifact <路径>] [--resource <selector>]` | 尚无已发版本时上传分析并建立首版工作稿。 | 写工作稿，不提交线上版本。 |
+| `create-version --yes [--artifact <路径>] [--resource <selector>]` | 尚无已发版本时提交固定的 `1.0.0`。 | 上传并提交首版；成功后删除工作稿并回写有效产物路径。 |
+| `create-version --reset ... [--resource <selector>]` | 首版工作稿确认不要了，直接从空表重新走本次命令。 | 先校验路由和产物；有稿时确认后才丢弃。确认后的后续失败不会恢复旧稿。 |
+| `update-version --version <新号> --yes [--artifact <路径>] [--resource <selector>]` | 已有线上版本，指定后续版本号并提交。 | 上传并提交新版本；成功后删除工作稿。 |
+| `update-version --bump patch|minor|major --yes [--resource <selector>]` | 已有线上版本，按 latest 自动计算新版本号。 | 与上条相同；不能和 `--version` 同用。 |
+| `update-version --reuse-version <已发号> ... [--resource <selector>]` | 工作稿的底不是当前 latest，且明确以该已发号为底提交。 | 只改变本次提交认可的底；工作稿来源必须匹配。 |
+| `update-version --reset ... [--resource <selector>]` | 当前更新稿确认不要了，要丢掉并按本次指定底重新拉取后继续。 | 先校验路由、新号和产物；有稿时确认后才删除。确认后的后续失败不会恢复旧稿。 |
+
+首版只能使用 `create-version`，已有版本只能使用 `update-version`。`--artifact` 在发行命令中是本次上传的真实文件/构建目录；普通资源必须是文件，主题/插件可以是文件或非空构建目录：目录临时压缩，文件（包括 zip）直接上传。不要把 `version draft description` 与 `version description` 混用：前者改未提交更新稿，后者改已发布版本。
 
 属性、配置和依赖的子命令都以工作稿为目标。没有工作稿时，已有线上版本先 `version draft pull`；首版要先 `create-version --prepare`。依赖在非交互模式还须明确 `--policy-id <策略ID> --yes`，CLI 不会代选对方策略。
 
 ## 展示信息、策略与上下架
 
+本节每条命令均可加 `[--resource <selector>]`；多资源工程中不传时按上文公共规则选择或停止。
+
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
-| `update [--title] [--intro] [--cover] [--tags] --yes` | 只修改资源展示信息。 | 更新线上 listing；不发版、不改标识、不上下架。 |
-| `policy list` | 查看当前资源的授权策略。 | 只读。 |
-| `policy template list [--page <n> --page-size <n>]` | 查看当前资源类型可套用的策略模板。 | 只读。 |
-| `policy template apply [templateId] [--name]` | 套用一条平台模板并启用。交互可选择；脚本必须给 `<templateId> --yes`。 | 新增并启用一条策略；不付款、不上架。 |
-| `policy apply --from-file <路径> [--name] --yes` | 从策略文本或 JSON 文件新增策略。 | 新增并启用一条策略；策略语义由平台校验。 |
-| `policy set --id <策略ID> --on|--off` | 启用或停用某条策略。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |
-| `validate --for online` | 上架前预检版本和策略条件。 | 只读。 |
-| `online` | 资源有已发版本和至少一条启用策略后上架。 | 更新线上可用状态。 |
-| `offline` | 暂停线上可用状态。 | 只下架，不删除版本、策略、资源或本地文件。 |
+| `update [--title] [--intro] [--cover] [--tags] --yes [--resource <selector>]` | 只修改资源展示信息。 | 更新线上 listing；不发版、不改标识、不上下架。 |
+| `policy list [--resource <selector>]` | 查看当前资源的授权策略。 | 只读。 |
+| `policy template list [--page <n> --page-size <n>] [--resource <selector>]` | 查看当前资源类型可套用的策略模板。 | 只读。 |
+| `policy template apply [templateId] [--name] [--resource <selector>]` | 套用一条平台模板并启用。交互可选择；脚本必须给 `<templateId> --yes`。 | 新增并启用一条策略；不付款、不上架。 |
+| `policy apply --from-file <路径> [--name] --yes [--resource <selector>]` | 从策略文本或 JSON 文件新增策略。 | 新增并启用一条策略；策略语义由平台校验。 |
+| `policy set --id <策略ID> --on|--off [--resource <selector>]` | 启用或停用某条策略。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |
+| `validate --for online [--resource <selector>]` | 上架前预检版本和策略条件。 | 只读。 |
+| `online [--resource <selector>]` | 资源有已发版本和至少一条启用策略后上架。 | 更新线上可用状态。 |
+| `offline [--resource <selector>]` | 暂停线上可用状态。 | 只下架，不删除版本、策略、资源或本地文件。 |
 
 ## 脚本最小安全模板
 
 脚本必须显式选择环境；工程有多份状态时也必须显式选择资源。先做只读检查，再执行写操作：
 
 ```powershell
-freelog-cli status --cwd <工程> --resource file:2.json --env dev
-freelog-cli version show --cwd <工程> --resource file:2.json --env dev
-freelog-cli update-version --cwd <工程> --resource file:2.json --bump patch --yes --env dev
+freelog-cli status --cwd <工程> --resource id:<资源ID> --env dev
+freelog-cli version show --cwd <工程> --resource name:<username/短标识> --env dev
+freelog-cli update-version --cwd <工程> --resource artifact:video.mp4 --artifact video-v2.mp4 --bump patch --yes --env dev
 ```
 
-需要机器可读错误时追加 `--json`。不要在脚本中用 `title:<标题>` 作为唯一选择器，也不要依赖交互式选择。
+需要机器可读错误时追加 `--json`。脚本优先用 `id:`、`name:` 或 `file:N.json`；不要用可能变化或重复的 `title:`，也不要依赖交互式选择。

package/dist/docs/README.md

@@ -65,7 +65,7 @@ freelog-cli --help
 |---|---|
 | `--env dev|test` | 选择联调环境。推荐每次显式传入。 |
 | `--cwd <dir>` | 工程目录；决定 `.freelog/` 与工作区账号选择器的位置。 |
-| `--resource <selector>` | 为常规单资源命令选择某一份本地身份：`file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`。单份可省略；多份交互选择，非交互必须明确指定。`create` / `bind` 的新增或接续规则见下文。 |
+| `--resource <selector>` | 为常规单资源命令选择某一份本地身份：`id:<资源ID>`、`name:<短标识或username/name>`、`title:<标题>`、`artifact:<相对文件或构建目录>` 或 `file:N.json`。单份可省略；多份交互选择，非交互必须明确指定。`create` / `bind` 的新增或接续规则见下文。 |
 | `--artifact <path>` | 当前选中资源的产物路径：`create` / `bind` 可记录默认路径；发版时表示本次上传路径；`version set` 只更新默认路径，绝不选择身份。 |
 | `--yes` | 跳过交互确认；不会放宽校验。仅当命令明确支持时（如覆盖工作稿）才允许覆盖相应状态，绝不覆盖工程目录。 |
 | `--json` | 将 CLI 错误输出为 `{ "code", "message" }`。 |
@@ -77,7 +77,7 @@ freelog-cli --help
 1. `init` 只创建本地身份，`create` 只创建线上资源壳，`bind` 只接入已有线上资源；三者都不会上传或发布版本。
 2. 无线上版本时只能用 `create-version` 发布固定的 `1.0.0`；已有线上版本时只能用 `update-version --version ...` 或 `--bump ...`。
 3. 每次真实发版都会从当前文件或构建目录重新上传、分析；工作稿里的旧 SHA1 不能替代已丢失的产物。
-4. 主题/插件传构建目录，CLI 临时压缩目录内容；普通资源传单个文件。两类资源都不需要、也不能由用户先手工打 zip。
+4. 主题/插件传构建目录时，CLI 临时压缩目录内容；传单个文件（包括 zip）时直接上传。普通资源传单个文件；只有普通资源不能传目录。
 
 ## 多资源工程：先选身份，再给产物
 
@@ -88,6 +88,6 @@ freelog-cli --help
 | 0 | 停止并提示先 `init`、`create` 或 `bind`。 |
 | 1 | 自动选择，无需传 `--resource`。 |
 | 多份，交互终端 | 显示文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态，选择后继续。 |
-| 多份，脚本/`--yes` | 停止并列出可复制的 `file:N.json`；传 `--resource` 后重试。 |
+| 多份，脚本/`--yes` | 停止并逐份列出可复制的 `id:`、`name:`、唯一 `title:`、`artifact:` 和 `file:N.json`；传 `--resource` 后重试。 |
 
-选择器优先级建议为 `file:N.json`（最稳定）→ `id:<资源ID>` → `name:<短标识或 username/name>`。`title:<标题>` 只能在标题唯一时使用：标题可改也可重复。`resource sync` 是唯一不传选择器就批量同步当前环境所有本地标题的资源命令。
+人工操作优先使用 `id:<资源ID>`、`name:<短标识或 username/name>`，或在同一素材目录中直接使用 `artifact:video.mp4`；`title:<标题>` 只能在标题唯一时使用，因为标题可改也可重复。`file:N.json` 是本地状态文件的精确选择器，保留给 AI、脚本和故障恢复，不要求人工记住编号。`resource sync` 是唯一不传选择器就批量同步当前环境所有本地标题的资源命令。

package/package.json

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