@freelog-cli/cli2 0.5.3 → 0.5.4

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

@@ -38,11 +38,13 @@ freelog-cli init . --type RT006003 --artifact video.mp4 --yes --env dev
 不知道 code 时先查询，或不传 `--type` 进入交互式层级选择：
 
 ```powershell
-freelog-cli type search 视频 --env dev
-freelog-cli type list --env dev
-freelog-cli type info RT006003 --env dev
-freelog-cli init . --artifact video.mp4 --env dev
-```
+freelog-cli type search 视频 --env dev
+freelog-cli type list --env dev
+freelog-cli type info RT006003 --env dev
+freelog-cli init . --artifact video.mp4 --env dev
+```
+
+`type info` 会同时显示该最终叶子是否支持版本可选配置；只有显示“支持”时才可以在工作稿中使用 `version option add/set`。它不表示任意文件都能用于该类型：做可选配置真网验收时，仍要为该类型选择真实可上传的文件。
 
 通用 `init` 必须用 `--artifact` 指向已经存在的本地文件；交互模式只会帮你选类型，不会扫描或猜测文件。它只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
 

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

@@ -82,7 +82,7 @@ freelog-cli version show --local --env dev
 
 ## `--artifact` 的含义
 
-一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `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` 用它指定本次文件或目录，发版产物也必须真实存在：
+一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时统一传 `--resource id:<资源ID>`、完整 `name:<username/name>`、`artifact:<已记录的相对文件或目录>`，或 AI/脚本精确使用的 `file:N.json`；不传时交互终端列出完整信息供选择，非交互会列出全部可复制候选并停止。标题可重复、可变化且可能落后线上，只在列表展示；人工和脚本使用稳定的 `id:` / `name:`，同一目录多文件可用 `artifact:`。新增本地身份的 `init` / `create` / `bind` 都用 `--artifact` 记录一个**当前已存在**的默认路径；接续已有合格身份时可复用其路径。`create-version` / `update-version` 用它指定本次文件或目录，发版产物也必须真实存在：
 
 | 场景 | 传入的路径 |
 |---|---|

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

@@ -7,7 +7,7 @@
 | 从官方模板初始化 | `init theme` | `init widget` | 不适用 |
 | 接入已有本地产物 | `init --type RT001 --artifact <文件或目录>` | `init --type RT002 --artifact <文件或目录>` | `init --type <最终叶子> --artifact <文件>` |
 | 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
-| 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
+| 初始 `filePath` | `dist` 目录 | `dist` 目录 | 接入或创建时必须记录一个工程内文件 |
 | 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
 | 发版输入 | 构建目录或单个文件 | 构建目录或单个文件 | 一个普通文件 |
 | 上传前处理 | 目录由 CLI 临时打 zip；文件直接上传 | 目录由 CLI 临时打 zip；文件直接上传 | 直接上传原文件 |
@@ -74,7 +74,7 @@ freelog-cli update-version --bump patch --yes --env dev
 
 也可以跳过 `init`，以 `create --type RT001 --artifact dist` 一步建壳；但无论哪条路径，状态写入前产物都必须已经存在。主题/插件既有项目可把 `dist` / `build` 记录为目录，也可记录已生成的单个文件；只有目录会在发版时临时压缩。不会补造元数据，也不会覆盖你的源码。
 
-## 创建主题或插件资源壳
+## 创建主题或插件资源壳
 
 初始化只建立本地工程，仍要登录并创建线上资源：
 
@@ -83,17 +83,26 @@ freelog-cli login --env dev
 freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
 ```
 
-不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
+不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
+
+模板初始化时默认将 `dist` 记录为这份未绑定身份的产物锚点。若你已经准备好另一个构建目录或 zip，先把**这份身份**的默认产物改过去，再创建资源壳：
+
+```powershell
+freelog-cli version set --cwd my-widget --artifact widget-artifact.zip
+freelog-cli create --cwd my-widget --title "我的插件" --name my-widget --yes --env dev
+```
+
+不要把上述两步合并成 `create --artifact widget-artifact.zip`。在已有 `dist` 未绑定身份时，那个不同路径表示“为另一份本地产物新建身份”；它不会暗中替换默认的 `dist`，非交互创建因而还需要显式 `--type RT002`，也会留下两份身份。确实要新建第二份资源时才这样做；若目标是接续模板初始化出来的那一份，就使用 `version set`。
 
 ## 先自行得到构建产物
 
-CLI 不运行包管理器或构建命令。你需要在工程自己的开发流程中产生 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
+CLI 不运行包管理器或构建命令。你需要先在工程自己的开发流程中产生真实存在的 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
 
 ```powershell
 freelog-cli version set --cwd my-theme --artifact build
 ```
 
-这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
+这条命令不上传、不压缩、不创建版本；它只接受工程内已经存在的文件或目录。目录在真正发版时还必须非空。
 
 ## 发布版本：目录自动压缩，文件直接上传
 
@@ -114,7 +123,7 @@ freelog-cli create-version --cwd my-theme --yes --env dev
 | 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
 | 一个 `.zip` 或普通文件 | 合法，直接上传；不会再次压缩。 |
 
-后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；目录会重新生成临时 zip，文件则直接上传。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
+后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；目录会重新生成临时 zip，文件则直接上传。可选配置不是主题/插件的固定能力；每次以后台资源类型详情中的 `resourceConfig.supportOptionalConfig === 2` 为准。先执行 `type info RT001 --env dev` 或 `type info RT002 --env dev`，显示“可选配置：支持”时才可使用 `version option`。
 
 ## 这不是两套版本系统
 

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

@@ -4,7 +4,7 @@
 
 工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
 
-多资源工程中，本页所有命令都加同一个 `--resource <selector>`：人工优先 `id:`、`name:` 或 `artifact:<当前文件>`，标题唯一时可用 `title:`；AI、脚本和恢复可用精确的 `file:N.json`。例如 `version draft pull --resource artifact:video.mp4` 是选择视频资源，不是上传文件。
+多资源工程中，本页所有命令都加同一个 `--resource <selector>`：人工优先 `id:`、完整 `name:` 或 `artifact:<当前文件>`；AI、脚本和恢复可用精确的 `file:N.json`。标题只展示，不能选择资源。例如 `version draft pull --resource artifact:video.mp4` 是选择视频资源，不是上传文件。
 
 | 要做什么 | 命令 | 是否提交线上版本 |
 |---|---|---|
@@ -58,8 +58,9 @@ freelog-cli version description --version 1.1.0 --description "补充发布说
 ```powershell
 freelog-cli version attr add "名称=作者 键=author 值=张三"
 freelog-cli version attr set "键=author 值=李四"
-freelog-cli version attr rm author
-freelog-cli version attr list
+freelog-cli version attr rm author
+freelog-cli version attr list
+freelog-cli version attr review
 
 freelog-cli version option add "名称=主题 键=theme 方式=文本 默认=dark"
 freelog-cli version option set "键=theme 默认=light"
@@ -67,7 +68,19 @@ freelog-cli version option rm theme
 freelog-cli version option list
 ```
 
-可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，所有 `version option` 写操作都会停止。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
+可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，`version option add` 和 `set` 会停止，`rm` 仍可用于清掉历史工作稿的遗留项。若遗留项没有清掉，首版和更新版提交前还会再次拒绝，绝不会悄悄送到平台。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
+
+如果换文件或重新分析后某个系统附加属性不再存在，CLI 会保留旧值并阻止提交，不会悄悄删除。先查看：
+
+```powershell
+freelog-cli version attr review --env dev
+```
+
+若下一次分析又出现同一 `key`，旧值会自动恢复。只有明确不再需要时，才逐项丢弃：
+
+```powershell
+freelog-cli version attr review discard <key> --yes --env dev
+```
 
 ## 编辑依赖
 
@@ -88,7 +101,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`。
 

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

@@ -20,18 +20,18 @@ freelog-cli policy list --resource id:<资源ID> --env dev
 ```powershell
 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
+freelog-cli update --resource id:<资源ID> --cover cover.png --yes --env dev
 ```
 
-`update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。
+`update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。`--intro ""` 会清空简介，`--tags ""` 会清空标签；封面只能传工程内 JPG/PNG/静态 GIF（≤5MB），CLI 先上传图片，再把平台返回 URL 写入资源。暂不支持清空封面。
 
 - 标题最多 100 个字符，简介最多 200 个字符。
-- 标签最多 20 个，每个最多 20 个字符；不能重复或包含 `#`。
+- 标签最多 20 个，每个最多 20 个字符，不能重复。输入 `#colour` 时，`#` 只是展示前缀，CLI 会写入 `colour`；只有 `#` 的空标签会被拒绝。
 - `--yes` 且没有任一修改字段会失败，不发送空更新。
 
 ## 同步本地标题
 
-资源标题可能在网页、另一台机器或其它工具中修改。多资源工程用标题选择时，应显式同步，而不是猜测旧标题：
+资源标题可能在网页、另一台机器或其它工具中修改。标题只用于展示，**从不用于选择资源**；需要刷新显示时显式同步：
 
 ```powershell
 # 当前环境的全部已绑定资源；这是唯一的批量资源命令
@@ -41,7 +41,23 @@ freelog-cli resource sync --env dev
 freelog-cli resource sync --resource id:<resourceId> --env dev
 ```
 
-同步只读取平台资源详情并回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
+同步只读取平台资源详情并在响应 `resourceId` 与本地身份完全相同时回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
+
+## 提交结果未知时恢复
+
+网络断开、超时或进程在版本提交附近中断时，CLI 不会猜测“失败”后再次提交。它会保留工作稿，并在 `.freelog/.pending-operation.json` 记录目标资源、版本、文件 SHA 和本地阶段。先查看：
+
+```powershell
+freelog-cli resource recover --env dev
+```
+
+若显示“请求尚未发送”，表示进程在允许 POST 前中断；执行下列明确收尾只会删掉未决记录，工作稿保留，随后可重新提交。若显示“结果未知”，CLI 才查询该资源的**目标版本**；只有版本存在且远端 `fileSha1` 与记录完全相同，才会显示“已确认”。此时下列收尾会删除工作稿和未决记录：
+
+```powershell
+freelog-cli resource recover --apply --yes --env dev
+```
+
+对“尚未发送”状态，这会原子删除未决记录、保留工作稿；对“已确认”状态，才会原子删除工作稿和未决记录。不会重发版本。若版本不存在、SHA 不同、环境不对或本地身份不一致，CLI 会保留两份文件并停止。未决记录存在时，除登录、退出、只读查看和 `resource recover` 外，新的业务写入都会被拦住。
 
 ## 管理授权策略
 
@@ -54,7 +70,7 @@ freelog-cli policy set --id <policyId> --on --env dev
 freelog-cli policy set --id <policyId> --off --env dev
 ```
 
-`policy template list` 按当前资源类型列出**全部**平台模板（默认每页 20 条），包含带交易事件的模板，不按免费/付费过滤。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
+当前后端按资源类型筛选模板存在故障，`policy template list` 暂时列出平台返回的**全部**模板（默认每页 20 条），包含带交易事件的模板，不在 CLI 按免费/付费、事件或类型猜测过滤；后端修复后再恢复按类型请求。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板会先由平台重新编译，最终能否写入由平台判定；目前带事件或需要填写时间、金额等参数的模板可能受后端编译契约阻塞，CLI 不猜测转换。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
 
 `policy apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
 

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,7 +10,7 @@
 | `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
 | `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
 | 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
-| `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会逐份列出可复制的 `id:`、`name:`、唯一 `title:`、`artifact:` 和 `file:N.json`。 |
+| `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、完整标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会逐份列出可复制的 `id:`、`name:`、`artifact:` 和 `file:N.json`。标题仅展示，不是选择器。 |
 | `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传 `--resource` 选身份，不能复用旧 SHA1。 |
 | `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
 | `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
@@ -20,7 +20,7 @@
 | 工作稿来源不是当前 latest | 线上已有新版本，而本地稿仍基于其它版本。 | 优先检查后用 `version draft pull --yes` 重建；确认要继续使用原底时，在 `update-version` 上明确传匹配的 `--reuse-version <版本>`。 |
 | `有未提交工作稿；请加 --yes 确认…` | 脚本试图丢弃或覆盖工作稿，却没有显式确认。 | 检查目标资源后重试并加 `--yes`；交互终端可阅读摘要后确认或取消。 |
 | 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`（TTY 确认；脚本加 `--yes`），最后执行下一步；`--reset` 会先校验再确认，确认后的后续失败不会恢复旧稿。 |
-| `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
+| `当前类型不支持可选配置` | 后台资源类型详情的 `resourceConfig.supportOptionalConfig` 不是 `2`；资源的文件形态、名称或主题/插件身份都不决定此能力。 | 不执行 `version option add` 或 `set`；若工作稿有历史遗留项可用 `version option rm <key>` 清理，否则提交也会被拒绝。 |
 | `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
 | 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
 | `上架须已有版本` / `上架须至少一条启用策略` | 上架条件不完整。 | 先发行版本、添加并启用策略，随后重试 `online`。 |

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

@@ -7,22 +7,23 @@ my-project/
   .freelog/
     auth                    # 非秘密账号选择器；不提交
     1.json                  # 第 1 份资源身份
-    1.version.json          # 第 1 份未提交工作稿（存在时）
-    index.json              # filePath → 身份编号索引
-    .lock                   # 瞬时写锁
+    1.version.json          # 第 1 份未提交工作稿（存在时）
+    .pending-operation.json # 已准备发送或已发送、但尚未完成本地收尾的版本提交（存在时）
+    .lock                   # 瞬时写锁
     .txn.json               # 瞬时跨文件事务；异常中断后供 CLI 前滚恢复
 ```
 
 ## `N.json`：资源身份
 
-初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 id 和名称。
+初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 ID、完整标识和短名称缓存。
 
 ```json
 {
   "schemaVersion": 1,
-  "subject": "resource",
-  "resourceId": "6a9f...",
-  "name": "my-video",
+  "subject": "resource",
+  "resourceId": "6a9f...",
+  "resourceName": "alice/my-video",
+  "name": "my-video",
   "title": "我的视频",
   "typeCode": "RT006003",
   "filePath": "video.mp4",
@@ -34,14 +35,14 @@ my-project/
 |---|---|
 | `subject` | 本期恒为 `resource`。 |
 | `typeCode` | 普通资源是已验证的最终叶子；主题/插件固定为 `RT001` / `RT002`。 |
-| `resourceId` 与 `name` | 绑定后成对出现；`name` 是当前账号命名空间内不可重复的短标识。未绑定 `init` 身份不应预写。 |
-| `title` | 创建、bind 或 `resource sync` 写入的本地展示/选择信息；标题可重复且会变化，不是线上写入依据。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
-| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件可以是构建目录（例如 `dist`）或单个文件（包括 zip）；绝对路径与 `..` 越界路径不合法。 |
+| `resourceId`、`resourceName` 与 `name` | 绑定后写入；`resourceName` 是完整不可变标识，`name` 是其短段展示缓存。旧状态可缺 `resourceName`，此时不得使用 `name:` 选择。 |
+| `title` | 创建、bind 或 `resource sync` 写入的本地展示缓存；标题可重复、可变化且可能落后线上，不参与资源选择。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
+| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件可以是构建目录（例如 `dist`）或单个文件（包括 zip）。绝对路径、`..` 越界路径和 `.freelog/` 内路径不合法；已存在路径即使表面在工程内，解析软链接后也不能逃到工程外。两份资源不能共享同一真实文件，主题/插件构建目录也不能与另一产物路径嵌套。 |
 | `env` | 非 prod 的已绑定资源会记录 `dev` 或 `test`。 |
 
-这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地选择/展示缓存保存，可由 `resource sync` 更新。
+这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地展示缓存保存，可由 `resource sync` 更新。
 
-`N.json` 不要求用户手工记编号。所有单资源命令可用 `--resource id:<资源ID>`、`name:<标识>`、唯一的 `title:<标题>` 或 `artifact:<filePath>` 选中它；`file:N.json` 是仍完整支持的精确状态文件形式，适合 AI、脚本和恢复。
+`N.json` 不要求用户手工记编号。所有单资源命令可用 `--resource id:<资源ID>`、完整 `name:<username/name>` 或 `artifact:<filePath>` 选中它；`file:N.json` 是仍完整支持的精确状态文件形式，适合 AI、脚本和恢复。标题只在列表显示。
 
 ## `N.version.json`：未提交工作稿
 
@@ -69,15 +70,17 @@ my-project/
 
 主题/插件使用目录时，这里记录 CLI 临时 zip 的 `filename` / SHA1；使用单个文件时记录原文件的 `filename` / SHA1。身份里的 `filePath` 保留用户选择的目录或文件。普通资源始终记录原文件的 `filename` / SHA1。
 
-## `index.json`、`.lock` 与 `.txn.json`
-
-`index.json` 是 `filePath → N` 的查询索引，不是主数据；它与身份不一致时，CLI 以 `N.json` 为准修复。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
+## `.pending-operation.json`、`.lock` 与 `.txn.json`
+
+`.pending-operation.json` 记录版本提交的本地阶段：`prepared` 表示已完成提交前检查、但 POST 尚未允许发出；`sending` 表示请求可能已经到达平台。旧记录一律按 `sending` 保守处理。它只记录资源 ID、本地编号、环境、目标版本和文件 SHA，不含 token、文件内容、完整版本提交体或版本历史。不要手工删除它：先运行 `resource recover --env <环境>`；`prepared` 由 `resource recover --apply --yes` 只清记录、保留工作稿，`sending` 只有 CLI 证明远端目标版本和 SHA 都相同后，才会清理它与对应工作稿。
+
+身份选择直接读取并校验 `N.json`，CLI 不维护 `index.json` 之类的派生索引。旧工程遗留的 `index.json` 不会被读取、重建或自动删除；可以保留，也可以在确认没有未完成旧版事务后自行移除。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
 
-需要同时改身份、索引和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
+需要同时改身份和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
 
 ## Git 建议
 
 - 永远忽略 `.freelog/auth`。
 - `N.json` 和版本工作稿不含秘密，适合随工程协作。
 - `N.version.json` 是未提交的工作内容；是否提交由团队协作流程决定，不能把它当成已发版本事实。
-- 不要提交 `.lock`、`.txn.json` 或临时 zip。
+- 不要提交 `.lock`、`.txn.json`、`.pending-operation.json` 或临时 zip。

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

@@ -58,7 +58,7 @@ 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` 从不承担资源选择职责。
+第二次 `create` 不会要求选择或覆盖 `1.json`：在没有未绑定状态时，它新增下一个编号。后续发版、状态、上下架等操作才用 `--resource` 精确选择其中一份；可用 `id:`、完整 `name:`、`artifact:` 或 AI/脚本使用的 `file:N.json`。标题仅展示，不能选择资源。`--artifact` 从不承担资源选择职责。
 
 ## 场景三：从官方模板创建主题或插件并发行首版
 
@@ -114,14 +114,14 @@ freelog-cli update-version --bump patch --yes --env dev
 
 ## 场景七：构建路径、工作稿或多资源工程发生变化
 
-- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --resource artifact:dist --artifact build`。只更新记录，不上传也不提交。
+- 构建输出从 `dist` 变成 `build`：主题/插件资源可用 `version set --artifact build`，因为目录是合法锚点；普通文件资源必须给实际文件，例如 `version set --artifact build/video.mp4`。多份资源先用 `--resource artifact:dist` 选择旧身份，再传新的 `--artifact`。只更新记录，不上传也不提交。
 - 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
 - 一个工程中有多份身份：`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`；这会覆盖当前未提交工作稿，先看命令打印的摘要。
 
 ## 场景八：版本表单、依赖和上线
 
-首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。详情见 [版本工作稿](./04-版本工作稿.md)。
+首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。文件分析变化出现待复核附加属性时，先 `version attr review`，逐项决定保留等待恢复或 `review discard <key>`。详情见 [版本工作稿](./04-版本工作稿.md)。
 
 展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
 

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

@@ -2,17 +2,16 @@
 
 本页是发布包内的命令索引：列出当前 CLI 的全部公开命令、何时使用以及它会不会改变线上资源或本地文件。首次完成任务请优先看[按场景操作](./09-按场景操作.md)；执行已知命令、编写脚本或排查影响时以本页为准。
 
-所有示例省略 `freelog-cli` 前缀后的公共参数。推荐每次显式传 `--env dev` 或 `--env test`。除 `login`、`logout`、`init`、`template`、`type`、新增/接续生命周期的 `create` / `bind` 与批量 `resource sync` 外，**本页每一条命令都接受并在多资源工程中需要** `--resource <selector>`。`--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/短标识>       # 最稳定，推荐
---resource title:<资源标题>             # 标题唯一时可用
---resource artifact:<相对文件或目录>    # 例如 artifact:video.mp4
+--resource id:<资源ID>                 # 最稳定，推荐
+--resource name:<username/name>         # 完整不可变标识，推荐
+--resource artifact:<相对文件或目录>    # 例如 artifact:video.mp4
 --resource file:N.json                 # AI、脚本、恢复时的精确状态文件
 ```
 
@@ -41,7 +40,7 @@ freelog-cli --cli-version
 | `template list` | 查看可用于主题/插件初始化的模板。 | 只读。 |
 | `type list` | 列出全部可用最终叶子类型。 | 只读，需要登录。 |
 | `type search [关键词]` | 按名称筛选最终叶子类型。 | 只读，需要登录。 |
-| `type info <类型编号>` | 确认某个类型编号及其名称链。 | 只读，需要登录。 |
+| `type info <类型编号>` | 确认某个类型编号、名称链和可选配置能力。只有详情显示“可选配置：支持”时，版本工作稿才允许 add/set 配置。 | 只读，需要登录。 |
 | `type pick [--type <类型编号>]` | 以命令方式列出或确认一个最终叶子类型。通常 `init` 的交互选择已足够。 | 只读，需要登录。 |
 
 ## 建立或接入资源身份
@@ -51,7 +50,9 @@ freelog-cli --cli-version
 | `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 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` 对齐。
@@ -69,13 +70,15 @@ freelog-cli --cli-version
 | `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 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`。 | 上传并提交首版；成功后删除工作稿并回写有效产物路径。 |
+| `create-version --yes [--artifact <路径>] [--resource <selector>]` | 尚无已发版本时提交固定的 `1.0.0`。 | 上传并提交首版；确认成功后删除工作稿并回写有效产物路径。结果未知则保留稿并改走 `resource recover`。 |
 | `create-version --reset ... [--resource <selector>]` | 首版工作稿确认不要了，直接从空表重新走本次命令。 | 先校验路由和产物；有稿时确认后才丢弃。确认后的后续失败不会恢复旧稿。 |
-| `update-version --version <新号> --yes [--artifact <路径>] [--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>]` | 当前更新稿确认不要了，要丢掉并按本次指定底重新拉取后继续。 | 先校验路由、新号和产物；有稿时确认后才删除。确认后的后续失败不会恢复旧稿。 |
@@ -90,9 +93,9 @@ freelog-cli --cli-version
 
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
-| `update [--title] [--intro] [--cover] [--tags] --yes [--resource <selector>]` | 只修改资源展示信息。 | 更新线上 listing；不发版、不改标识、不上下架。 |
+| `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 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>]` | 启用或停用某条策略。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |
@@ -110,4 +113,4 @@ freelog-cli version show --cwd <工程> --resource name:<username/短标识> --e
 freelog-cli update-version --cwd <工程> --resource artifact:video.mp4 --artifact video-v2.mp4 --bump patch --yes --env dev
 ```
 
-需要机器可读错误时追加 `--json`。脚本优先用 `id:`、`name:` 或 `file:N.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>` | 为常规单资源命令选择某一份本地身份：`id:<资源ID>`、`name:<短标识或username/name>`、`title:<标题>`、`artifact:<相对文件或构建目录>` 或 `file:N.json`。单份可省略；多份交互选择，非交互必须明确指定。`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" }`。 |
@@ -88,6 +88,6 @@ freelog-cli --help
 | 0 | 停止并提示先 `init`、`create` 或 `bind`。 |
 | 1 | 自动选择，无需传 `--resource`。 |
 | 多份，交互终端 | 显示文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态，选择后继续。 |
-| 多份，脚本/`--yes` | 停止并逐份列出可复制的 `id:`、`name:`、唯一 `title:`、`artifact:` 和 `file:N.json`；传 `--resource` 后重试。 |
+| 多份，脚本/`--yes` | 停止并逐份列出可复制的 `id:`、`name:`、`artifact:` 和 `file:N.json`；传 `--resource` 后重试。 |
 
-人工操作优先使用 `id:<资源ID>`、`name:<短标识或 username/name>`，或在同一素材目录中直接使用 `artifact:video.mp4`；`title:<标题>` 只能在标题唯一时使用，因为标题可改也可重复。`file:N.json` 是本地状态文件的精确选择器，保留给 AI、脚本和故障恢复，不要求人工记住编号。`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.3",
+  "version": "0.5.4",
   "description": "Freelog CLI",
   "type": "module",
   "license": "MIT",