@freelog-cli/cli2 0.5.2 → 0.5.4

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

@@ -2,7 +2,20 @@
 
 本页是发布包内的命令索引：列出当前 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 recover` 外，**本页每一条命令都接受并在多资源工程中需要** `--resource <selector>`。`--yes` 只跳过交互确认，不会放宽校验。详细选择规则见[首页](./README.md#多资源工程先选身份再给产物)。
+
+## 公共资源匹配参数
+
+一个目录可有多个视频、图片或其它资源；用户不需要记住 `.freelog/2.json`。对任何常规单资源命令使用同一个参数：
+
+```powershell
+--resource id:<资源ID>                 # 最稳定，推荐
+--resource name:<username/name>         # 完整不可变标识，推荐
+--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,75 +34,83 @@ 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` | 查看可用于主题/插件初始化的模板。 | 只读。 |
 | `type list` | 列出全部可用最终叶子类型。 | 只读，需要登录。 |
 | `type search [关键词]` | 按名称筛选最终叶子类型。 | 只读，需要登录。 |
-| `type info <类型编号>` | 确认某个类型编号及其名称链。 | 只读，需要登录。 |
+| `type info <类型编号>` | 确认某个类型编号、名称链和可选配置能力。只有详情显示“可选配置：支持”时，版本工作稿才允许 add/set 配置。 | 只读，需要登录。 |
 | `type pick [--type <类型编号>]` | 以命令方式列出或确认一个最终叶子类型。通常 `init` 的交互选择已足够。 | 只读，需要登录。 |
 
 ## 建立或接入资源身份
 
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
-| `create --title <标题> --name <短标识> [--type <叶子类型>] [--artifact <路径>]` | 线上还没有该资源壳时创建它。已有唯一未绑定身份时会接续它；没有未绑定身份时新增一份本地状态。 | 创建线上资源壳并写入 `resourceId`；只记录产物路径，不上传、不发版、不上架。 |
-| `bind <资源ID或username/name> [--artifact <路径>] [--force --yes]` | 线上已有且属于当前账号的资源，需要接入本地工程。 | 从平台读取身份，写入或接续一份 `N.json`；不拉版本、不上传。 |
-| `status` | 想同时确认选中资源的本地身份、工作稿和线上状态。 | 只读。 |
-| `resource sync [--resource <selector>]` | 网页或其它机器改过标题，需要刷新本地标题。 | 不传选择器时批量按资源 ID 同步当前环境全部绑定身份的 `title`；传选择器时只同步一份。 |
-| `version set --artifact <路径>` | 文件改名、构建目录从 `dist` 变成 `build`，只想更新默认路径。 | 只改选中 `N.json.filePath`；不上传、不提交。 |
+| `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`；传选择器时只同步一份。 |
+| `resource recover` | 上次版本提交因网络或中断留下未决记录。 | `prepared` 显示尚未发送；`sending` 只读核验目标版本与文件 SHA；不重发。 |
+| `resource recover --apply --yes` | `resource recover` 显示“尚未发送”或“已确认”。 | 前者仅清未决记录并保留工作稿；后者原子清理工作稿和未决记录；未确认或 SHA 不同会拒绝。 |
+| `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 attr review [--resource <selector>]` | 查看文件分析变化后待复核的系统附加属性。 | 只读；有待复核项时不能提交。 |
+| `version attr review discard <key> [--yes] [--resource <selector>]` | 确认丢弃一项待复核系统附加属性。 | 仅影响该工作稿；同 key 后续重新出现会自动恢复，无需丢弃。 |
+| `version option add|set|rm|list [--resource <selector>]` | 维护工作稿的可选配置。 | add / set 只在资源类型允许时可用；rm 可清理遗留项；提交前再核类型。 |
+| `version dep add|range|rm|list [--resource <selector>]` | 维护工作稿中的依赖及版本范围。 | 写操作只改工作稿；首次签约可能产生独立平台授权动作。 |
+| `create-version --prepare [--artifact <路径>] [--resource <selector>]` | 尚无已发版本时上传分析并建立首版工作稿。 | 写工作稿，不提交线上版本。 |
+| `create-version --yes [--artifact <路径>] [--resource <selector>]` | 尚无已发版本时提交固定的 `1.0.0`。 | 上传并提交首版；确认成功后删除工作稿并回写有效产物路径。结果未知则保留稿并改走 `resource recover`。 |
+| `create-version --reset ... [--resource <selector>]` | 首版工作稿确认不要了，直接从空表重新走本次命令。 | 先校验路由和产物；有稿时确认后才丢弃。确认后的后续失败不会恢复旧稿。 |
+| `update-version --version <新号> --yes [--artifact <路径>] [--resource <selector>]` | 已有线上版本，指定后续版本号并提交。 | 上传并提交新版本；确认成功后删除工作稿。结果未知则保留稿并改走 `resource recover`。 |
+| `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；不发版、不改标识、不上下架。未传字段不改；`--intro ""`、`--tags ""` 清空对应字段；`--cover` 只能给工程内 JPG/PNG/静态 GIF（≤5MB），CLI 上传后写 URL，暂不支持清空封面。 |
+| `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`；标题只作展示，不能作为选择器，也不要依赖交互式选择。

package/dist/docs/README.md

@@ -52,7 +52,7 @@ freelog-cli --help
 ## 先判断你处于哪一条路径
 
 ```text
-普通文件：login → init . → create → create-version --prepare → create-version --yes
+普通文件：login → init . --type <最终叶子> --artifact <文件> → 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）
 ```
@@ -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>`、`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:`、`artifact:` 和 `file:N.json`；传 `--resource` 后重试。 |
 
-选择器优先级建议为 `file:N.json`（最稳定）→ `id:<资源ID>` → `name:<短标识或 username/name>`。`title:<标题>` 只能在标题唯一时使用：标题可改也可重复。`resource sync` 是唯一不传选择器就批量同步当前环境所有本地标题的资源命令。
+人工操作优先使用 `id:<资源ID>`、完整 `name:<username/name>`，或在同一素材目录中直接使用 `artifact:video.mp4`。标题可改、可重复、可与线上不同，只用于列表展示；不会触发隐式同步，也不能作为选择器。`file:N.json` 是本地状态文件的精确选择器，保留给 AI、脚本和故障恢复，不要求人工记住编号。`resource sync` 是唯一不传选择器就批量同步当前环境所有本地标题的资源命令。

package/package.json

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