@freelog-cli/cli2 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/dist/bin/index.js +1956 -923
  2. package/dist/bin/index.js.map +1 -1
  3. package/dist/docs/01-/345/277/253/351/200/237/344/270/212/346/211/213.md +10 -8
  4. package/dist/docs/02-/346/227/245/345/270/270/350/267/257/345/276/204.md +5 -5
  5. package/dist/docs/03-/344/270/273/351/242/230/344/270/216/346/217/222/344/273/266.md +28 -17
  6. package/dist/docs/04-/347/211/210/346/234/254/345/267/245/344/275/234/347/250/277.md +25 -10
  7. package/dist/docs/05-/350/265/204/346/272/220/347/256/241/347/220/206.md +30 -12
  8. 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 +5 -5
  9. package/dist/docs/08-/346/234/254/345/234/260/346/226/207/344/273/266/345/217/202/350/200/203.md +22 -17
  10. package/dist/docs/09-/346/214/211/345/234/272/346/231/257/346/223/215/344/275/234.md +33 -16
  11. package/dist/docs/10-/345/221/275/344/273/244/345/217/202/350/200/203.md +61 -40
  12. package/dist/docs/README.md +5 -5
  13. package/package.json +1 -1
package/dist/docs/01-/345/277/253/351/200/237/344/270/212/346/211/213.md CHANGED
@@ -32,19 +32,21 @@ freelog-cli --help
32
32
  普通资源要先登录，因为资源类型来自平台的当前类型树。已知最终叶子 code 时可直接初始化：
33
33
 
34
34
  ```powershell
35
- freelog-cli init . --type RT006003 --yes --env dev
35
+ freelog-cli init . --type RT006003 --artifact video.mp4 --yes --env dev
36
36
  ```
37
37
 
38
38
  不知道 code 时先查询，或不传 `--type` 进入交互式层级选择：
39
39
 
40
40
  ```powershell
41
- freelog-cli type search 视频 --env dev
42
- freelog-cli type list --env dev
43
- freelog-cli type info RT006003 --env dev
44
- freelog-cli init . --env dev
45
- ```
46
-
47
- `init` 只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
41
+ freelog-cli type search 视频 --env dev
42
+ freelog-cli type list --env dev
43
+ freelog-cli type info RT006003 --env dev
44
+ freelog-cli init . --artifact video.mp4 --env dev
45
+ ```
46
+
47
+ `type info` 会同时显示该最终叶子是否支持版本可选配置；只有显示“支持”时才可以在工作稿中使用 `version option add/set`。它不表示任意文件都能用于该类型：做可选配置真网验收时，仍要为该类型选择真实可上传的文件。
48
+
49
+ 通用 `init` 必须用 `--artifact` 指向已经存在的本地文件；交互模式只会帮你选类型，不会扫描或猜测文件。它只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
48
50
 
49
51
  上一步已在当前目录写入 `.freelog/auth` 也可以再执行 `init .`：CLI 会保留这一个账号选择器，并拒绝覆盖任何其它已有工程内容或资源身份。
50
52
 
package/dist/docs/02-/346/227/245/345/270/270/350/267/257/345/276/204.md CHANGED
@@ -10,8 +10,8 @@ login → init（可选）→ create → create-version → 配策略 / 上架
10
10
 
11
11
  | 阶段 | 命令 | 结果 |
12
12
  |---|---|---|
13
- | 选类型并立项 | `init [dir] --type <leaf-code>` | 写未绑定本地身份，不创建线上资源。 |
14
- | 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。 |
13
+ | 选类型并立项 | `init [dir] --type <leaf-code> --artifact <path>` | 用现存产物写未绑定本地身份，不创建线上资源。主题/插件模板 `init theme/widget` 自动创建并记录 `dist`，是例外。 |
14
+ | 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。新建本地状态时 `--artifact` 必填；接续已有未绑定状态时可复用其路径。 |
15
15
  | 仅准备首版 | `create-version --prepare` | 上传并解析文件，留下首版工作稿。 |
16
16
  | 提交首版 | `create-version --yes` | 提交 `1.0.0` 并清理成功的工作稿。 |
17
17
 
@@ -64,7 +64,7 @@ freelog-cli bind <resourceId 或 username/name> --artifact video.mp4 --env dev
64
64
  | 没有 `latestVersion` | `create-version --prepare` 后编辑并 `create-version --yes`，发行首版。 |
65
65
  | 已有 `latestVersion` | `version draft pull`，编辑工作稿后以 `update-version --version` 或 `--bump` 发新号。 |
66
66
 
67
- 主题/插件的 `<path>` 必须是构建目录（`dist` / `build`）；在尚无目录记录的既有项目中，`bind --artifact` 必填。
67
+ 主题/插件的 `<path>` 可以是构建目录（`dist` / `build`）或已生成的单个文件（包括 zip）；在尚无产物记录的既有项目中，`bind --artifact` 必填。
68
68
 
69
69
  - 已有相同资源 id 时，重复 `bind` 是幂等的。
70
70
  - 要将一份本地身份换绑到另一个资源，使用 `bind <id> --force --yes`；旧工作稿会被清理。
@@ -82,11 +82,11 @@ freelog-cli version show --local --env dev
82
82
 
83
83
  ## `--artifact` 的含义
84
84
 
85
- 一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时先传 `--resource file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`；不传时交互终端列出完整信息供选择，非交互会列出可复制的 `file:N.json` 示例并停止。标题可重复且会变化，脚本优先使用稳定的 `file:` 或 `id:`。`create` / `bind` 用 `--artifact` 记录将来默认使用的路径，路径可以暂时不存在；`create-version` / `update-version` 用它指定本次文件或目录，发版产物必须真实存在：
85
+ 一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时统一传 `--resource id:<资源ID>`、完整 `name:<username/name>`、`artifact:<已记录的相对文件或目录>`，或 AI/脚本精确使用的 `file:N.json`；不传时交互终端列出完整信息供选择，非交互会列出全部可复制候选并停止。标题可重复、可变化且可能落后线上，只在列表展示；人工和脚本使用稳定的 `id:` / `name:`，同一目录多文件可用 `artifact:`。新增本地身份的 `init` / `create` / `bind` 都用 `--artifact` 记录一个**当前已存在**的默认路径；接续已有合格身份时可复用其路径。`create-version` / `update-version` 用它指定本次文件或目录，发版产物也必须真实存在：
86
86
 
87
87
  | 场景 | 传入的路径 |
88
88
  |---|---|
89
89
  | 普通资源 `--artifact` | 一个实际文件。目录会被拒绝。 |
90
- | 主题 / 插件 `--artifact` | 一个构建产物目录，例如 `dist` 或 `build`。zip 文件会被拒绝。 |
90
+ | 主题 / 插件 `--artifact` | 一个构建产物目录（例如 `dist` / `build`）或已生成的单个文件（包括 zip）。目录由 CLI 临时压缩，文件直接上传。 |
91
91
 
92
92
  发版未传 `--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 CHANGED
@@ -4,12 +4,13 @@
4
4
 
5
5
  | 项目 | 主题 | 插件 | 普通文件资源 |
6
6
  |---|---|---|---|
7
- | 初始化 | `init theme` | `init widget` | `init --type <最终叶子>` |
7
+ | 从官方模板初始化 | `init theme` | `init widget` | 不适用 |
8
+ | 接入已有本地产物 | `init --type RT001 --artifact <文件或目录>` | `init --type RT002 --artifact <文件或目录>` | `init --type <最终叶子> --artifact <文件>` |
8
9
  | 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
9
- | 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
10
+ | 初始 `filePath` | `dist` 目录 | `dist` 目录 | 接入或创建时必须记录一个工程内文件 |
10
11
  | 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
11
- | 发版输入 | 构建产物目录 | 构建产物目录 | 一个普通文件 |
12
- | 上传前处理 | CLI 临时打 zip | CLI 临时打 zip | 直接上传原文件 |
12
+ | 发版输入 | 构建目录或单个文件 | 构建目录或单个文件 | 一个普通文件 |
13
+ | 上传前处理 | 目录由 CLI 临时打 zip；文件直接上传 | 目录由 CLI 临时打 zip；文件直接上传 | 直接上传原文件 |
13
14
 
14
15
  ## 从线上模板创建工程
15
16
 
@@ -41,11 +42,12 @@ my-theme/
41
42
 
42
43
  ## 接入已有主题或插件项目
43
44
 
44
- 非空的既有项目不能再运行 `init`。若它还没有线上资源壳，在项目根直接建壳，并显式记录构建目录：
45
+ 已有项目不运行模板子命令；可以先在项目根只建立本地状态，再创建线上资源壳：
45
46
 
46
47
  ```powershell
47
48
  freelog-cli login --env dev
48
- freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
49
+ freelog-cli init . --type RT001 --artifact dist --yes --env dev
50
+ freelog-cli create --title "已有主题" --name existing-theme --yes --env dev
49
51
  freelog-cli create-version --prepare --env dev
50
52
  freelog-cli create-version --yes --env dev
51
53
  ```
@@ -70,9 +72,9 @@ freelog-cli update-version --bump patch --yes --env dev
70
72
 
71
73
  不要在已发行资源上再运行 `create-version`，也不要在没有发行版本的资源上运行 `draft pull` / `update-version`。
72
74
 
73
- 主题/插件既有项目路径都会把 `dist` / `build` 记录为目录，并在发版时临时压缩；不会补造元数据，也不会覆盖你的源码。
75
+ 也可以跳过 `init`，以 `create --type RT001 --artifact dist` 一步建壳；但无论哪条路径，状态写入前产物都必须已经存在。主题/插件既有项目可把 `dist` / `build` 记录为目录，也可记录已生成的单个文件；只有目录会在发版时临时压缩。不会补造元数据，也不会覆盖你的源码。
74
76
 
75
- ## 创建主题或插件资源壳
77
+ ## 创建主题或插件资源壳
76
78
 
77
79
  初始化只建立本地工程，仍要登录并创建线上资源：
78
80
 
@@ -81,19 +83,28 @@ freelog-cli login --env dev
81
83
  freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
82
84
  ```
83
85
 
84
- 不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
86
+ 不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
87
+
88
+ 模板初始化时默认将 `dist` 记录为这份未绑定身份的产物锚点。若你已经准备好另一个构建目录或 zip，先把**这份身份**的默认产物改过去，再创建资源壳：
89
+
90
+ ```powershell
91
+ freelog-cli version set --cwd my-widget --artifact widget-artifact.zip
92
+ freelog-cli create --cwd my-widget --title "我的插件" --name my-widget --yes --env dev
93
+ ```
94
+
95
+ 不要把上述两步合并成 `create --artifact widget-artifact.zip`。在已有 `dist` 未绑定身份时，那个不同路径表示“为另一份本地产物新建身份”；它不会暗中替换默认的 `dist`，非交互创建因而还需要显式 `--type RT002`，也会留下两份身份。确实要新建第二份资源时才这样做；若目标是接续模板初始化出来的那一份，就使用 `version set`。
85
96
 
86
97
  ## 先自行得到构建产物
87
98
 
88
- CLI 不运行包管理器或构建命令。你需要在工程自己的开发流程中产生 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
99
+ CLI 不运行包管理器或构建命令。你需要先在工程自己的开发流程中产生真实存在的 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
89
100
 
90
101
  ```powershell
91
102
  freelog-cli version set --cwd my-theme --artifact build
92
103
  ```
93
104
 
94
- 这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
105
+ 这条命令不上传、不压缩、不创建版本；它只接受工程内已经存在的文件或目录。目录在真正发版时还必须非空。
95
106
 
96
- ## 发布版本：传目录，不传 zip
107
+ ## 发布版本：目录自动压缩，文件直接上传
97
108
 
98
109
  ```powershell
99
110
  freelog-cli create-version --cwd my-theme --prepare --env dev
@@ -101,7 +112,7 @@ freelog-cli version show --cwd my-theme --local --env dev
101
112
  freelog-cli create-version --cwd my-theme --yes --env dev
102
113
  ```
103
114
 
104
- 对于 `RT001` / `RT002`，CLI 会把 `dist` 的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。临时 zip 无论成功或失败都会删除，不写入工程，也不写入 `N.json` 或工作稿。
115
+ 对于 `RT001` / `RT002`，若路径是 `dist` 这类目录，CLI 会把目录的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。若路径是单个文件（包括用户已准备的 zip），CLI 直接计算该文件的 SHA1、上传和提交，不会再次压缩。临时 zip 无论成功或失败都会删除，不写入工程，也不写入工作稿。
105
116
 
106
117
  以下输入会停止：
107
118
 
@@ -110,15 +121,15 @@ freelog-cli create-version --cwd my-theme --yes --env dev
110
121
  | `dist` 不存在 | 要求先生成构建产物。 |
111
122
  | 空目录 | 要求先生成实际文件。 |
112
123
  | 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
113
- | 一个 `.zip` 或普通文件 | 拒绝；主题和插件只能交构建目录。 |
124
+ | 一个 `.zip` 或普通文件 | 合法，直接上传；不会再次压缩。 |
114
125
 
115
- 后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；只要传入的仍是构建目录，CLI 会重新生成临时 zip。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
126
+ 后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；目录会重新生成临时 zip，文件则直接上传。可选配置不是主题/插件的固定能力；每次以后台资源类型详情中的 `resourceConfig.supportOptionalConfig === 2` 为准。先执行 `type info RT001 --env dev` 或 `type info RT002 --env dev`，显示“可选配置：支持”时才可使用 `version option`。
116
127
 
117
128
  ## 这不是两套版本系统
118
129
 
119
130
  主题/插件和普通资源都使用同一份 `N.version.json` 工作稿，版本号规则、依赖签约规则、属性校验、成功清稿和失败保留规则完全一致；可选配置仅在类型详情允许时可用。唯一的文件层差异是：
120
131
 
121
132
  - 普通资源的 `filePath` 指向文件，文件 SHA1 即上传文件的 SHA1；
122
- - 主题/插件的 `filePath` 指向目录，文件 SHA1 与 `filename` 指向 CLI 临时 zip 的结果。
133
+ - 主题/插件的 `filePath` 可指向目录或文件：目录时 SHA1 与 `filename` 指向 CLI 临时 zip，文件时二者指向原文件。
123
134
 
124
- 因此不要手工把 zip 记进 `filePath`，也不要因为主题是目录而另建一套版本缓存。
135
+ 因此可以把已有 zip 记进 `filePath`，但不要因为主题/插件的产物形态而另建一套版本缓存。
package/dist/docs/04-/347/211/210/346/234/254/345/267/245/344/275/234/347/250/277.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
6
6
 
7
+ 多资源工程中，本页所有命令都加同一个 `--resource <selector>`：人工优先 `id:`、完整 `name:` 或 `artifact:<当前文件>`；AI、脚本和恢复可用精确的 `file:N.json`。标题只展示，不能选择资源。例如 `version draft pull --resource artifact:video.mp4` 是选择视频资源，不是上传文件。
8
+
7
9
  | 要做什么 | 命令 | 是否提交线上版本 |
8
10
  |---|---|---|
9
11
  | 看线上版本 | `version show [--version <ver>]` | 否 |
@@ -11,7 +13,7 @@
11
13
  | 从已发版本建立更新稿 | `version draft pull [--version <ver>]` | 否 |
12
14
  | 准备首版稿 | `create-version --prepare` | 否 |
13
15
  | 编辑稿 | `version attr` / `option` / `dep` / `version draft description` | 否；依赖签约是独立平台动作 |
14
- | 丢弃稿 | `version draft discard` | 否 |
16
+ | 丢弃稿 | `version draft discard [--yes]` | 否 |
15
17
  | 提交 | `create-version --yes` / `update-version --version <ver> --yes` | 是 |
16
18
  | 改已发布版本的说明 | `version description --version <ver> --description <文本>` | 是；仅更新该已发版本说明 |
17
19
 
@@ -32,12 +34,12 @@ freelog-cli create-version --yes --env dev
32
34
  已有版本时，以线上版本为底建立稿：
33
35
 
34
36
  ```powershell
35
- freelog-cli version draft pull --version 1.0.0 --env dev
36
- freelog-cli version draft description --description "本次更新说明" --env dev
37
- freelog-cli update-version --version 1.1.0 --yes --env dev
37
+ freelog-cli version draft pull --resource artifact:video.mp4 --version 1.0.0 --env dev
38
+ freelog-cli version draft description --resource artifact:video.mp4 --description "本次更新说明" --env dev
39
+ freelog-cli update-version --resource artifact:video.mp4 --version 1.1.0 --yes --env dev
38
40
  ```
39
41
 
40
- 已有本地稿时，`version draft pull` 默认不会覆盖。明确要重来时使用 `--yes`；命令会打印将被覆盖的来源、文件和条目摘要。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
42
+ 已有本地稿时，`version draft pull` 会先验证目标线上版本。TTY 显示旧稿摘要并以“否”为默认确认；脚本必须显式传 `--yes` 才能覆盖。`version draft discard` 同样先显示摘要并确认；脚本必须 `--yes`，没有工作稿时安全退出。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
41
43
 
42
44
  ## 两种“版本说明”不要混用
43
45
 
@@ -56,8 +58,9 @@ freelog-cli version description --version 1.1.0 --description "补充发布说
56
58
  ```powershell
57
59
  freelog-cli version attr add "名称=作者 键=author 值=张三"
58
60
  freelog-cli version attr set "键=author 值=李四"
59
- freelog-cli version attr rm author
60
- freelog-cli version attr list
61
+ freelog-cli version attr rm author
62
+ freelog-cli version attr list
63
+ freelog-cli version attr review
61
64
 
62
65
  freelog-cli version option add "名称=主题 键=theme 方式=文本 默认=dark"
63
66
  freelog-cli version option set "键=theme 默认=light"
@@ -65,7 +68,19 @@ freelog-cli version option rm theme
65
68
  freelog-cli version option list
66
69
  ```
67
70
 
68
- 可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，所有 `version option` 写操作都会停止。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
71
+ 可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，`version option add` 和 `set` 会停止，`rm` 仍可用于清掉历史工作稿的遗留项。若遗留项没有清掉，首版和更新版提交前还会再次拒绝，绝不会悄悄送到平台。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
72
+
73
+ 如果换文件或重新分析后某个系统附加属性不再存在，CLI 会保留旧值并阻止提交，不会悄悄删除。先查看：
74
+
75
+ ```powershell
76
+ freelog-cli version attr review --env dev
77
+ ```
78
+
79
+ 若下一次分析又出现同一 `key`，旧值会自动恢复。只有明确不再需要时，才逐项丢弃：
80
+
81
+ ```powershell
82
+ freelog-cli version attr review discard <key> --yes --env dev
83
+ ```
69
84
 
70
85
  ## 编辑依赖
71
86
 
@@ -86,7 +101,7 @@ CLI 列出的是对方资源的全部启用策略，不按免费/付费筛选。
86
101
 
87
102
  ## 文件变化与恢复
88
103
 
89
- 发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给构建目录。新脚本不要使用 `--file`。
104
+ 发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给文件或构建目录（仅目录会临时压缩）。主题/插件目录中的软链接不会被打进包，需先替换为实际构建文件。新脚本不要使用 `--file`。
90
105
 
91
106
  不要手工改 `N.version.json`。该文件有严格 schema，损坏、旧格式或身份不一致时 CLI 会保留原文件并停止；可明确丢弃工作稿，或从线上版本重新 `draft pull`。
92
107
 
@@ -105,4 +120,4 @@ freelog-cli update-version --reset --bump patch --yes --env dev
105
120
  freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
106
121
  ```
107
122
 
108
- `--reset` 会在后续准备、线上检查或提交之前立即删除选中资源的工作稿；即使后续步骤失败，旧稿也不会恢复。因此默认优先用可检查的两步：先 `version show --local`，再 `version draft discard`，确认成功后才执行下一条命令。只有已确认资源、命令路径和 `--resource`（多资源工程）都正确时，才使用 `--reset`。`--reuse-version` 不会重写工作稿，它只声明本次提交认可的线上底，必须与工作稿 `fromVersion` 一致。
123
+ `--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 CHANGED
@@ -2,13 +2,15 @@
2
2
 
3
3
  本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
4
4
 
5
+ 多资源工程中，本页除不带选择器即批量的 `resource sync` 外，每条命令都加 `--resource <selector>`。优先用 `id:`、`name:` 或 `artifact:<当前文件>`；`file:N.json` 保留给 AI、脚本和恢复。
6
+
5
7
  ## 查看现状
6
8
 
7
9
  ```powershell
8
- freelog-cli status --env dev
9
- freelog-cli version show --env dev
10
- freelog-cli version show --version 1.0.0 --env dev
11
- freelog-cli policy list --env dev
10
+ freelog-cli status --resource id:<资源ID> --env dev
11
+ freelog-cli version show --resource id:<资源ID> --env dev
12
+ freelog-cli version show --resource id:<资源ID> --version 1.0.0 --env dev
13
+ freelog-cli policy list --resource id:<资源ID> --env dev
12
14
  ```
13
15
 
14
16
  `status` 汇总本地身份、是否存在工作稿和线上 latest；`version show` 与 `policy list` 读取平台当前结果。若只想看本地未交内容，用 `version show --local`。
@@ -16,20 +18,20 @@ freelog-cli policy list --env dev
16
18
  ## 修改展示信息
17
19
 
18
20
  ```powershell
19
- freelog-cli update --title "新标题" --yes --env dev
20
- freelog-cli update --intro "一句话简介" --tags "教程,视频" --yes --env dev
21
- freelog-cli update --cover "<封面值>" --yes --env dev
21
+ freelog-cli update --resource id:<资源ID> --title "新标题" --yes --env dev
22
+ freelog-cli update --resource id:<资源ID> --intro "一句话简介" --tags "教程,视频" --yes --env dev
23
+ freelog-cli update --resource id:<资源ID> --cover cover.png --yes --env dev
22
24
  ```
23
25
 
24
- `update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。
26
+ `update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。`--intro ""` 会清空简介，`--tags ""` 会清空标签；封面只能传工程内 JPG/PNG/静态 GIF（≤5MB），CLI 先上传图片，再把平台返回 URL 写入资源。暂不支持清空封面。
25
27
 
26
28
  - 标题最多 100 个字符，简介最多 200 个字符。
27
- - 标签最多 20 个，每个最多 20 个字符；不能重复或包含 `#`。
29
+ - 标签最多 20 个，每个最多 20 个字符，不能重复。输入 `#colour` 时，`#` 只是展示前缀，CLI 会写入 `colour`；只有 `#` 的空标签会被拒绝。
28
30
  - `--yes` 且没有任一修改字段会失败，不发送空更新。
29
31
 
30
32
  ## 同步本地标题
31
33
 
32
- 资源标题可能在网页、另一台机器或其它工具中修改。多资源工程用标题选择时，应显式同步，而不是猜测旧标题：
34
+ 资源标题可能在网页、另一台机器或其它工具中修改。标题只用于展示，**从不用于选择资源**；需要刷新显示时显式同步：
33
35
 
34
36
  ```powershell
35
37
  # 当前环境的全部已绑定资源；这是唯一的批量资源命令
@@ -39,7 +41,23 @@ freelog-cli resource sync --env dev
39
41
  freelog-cli resource sync --resource id:<resourceId> --env dev
40
42
  ```
41
43
 
42
- 同步只读取平台资源详情并回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
44
+ 同步只读取平台资源详情并在响应 `resourceId` 与本地身份完全相同时回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
45
+
46
+ ## 提交结果未知时恢复
47
+
48
+ 网络断开、超时或进程在版本提交附近中断时，CLI 不会猜测“失败”后再次提交。它会保留工作稿，并在 `.freelog/.pending-operation.json` 记录目标资源、版本、文件 SHA 和本地阶段。先查看：
49
+
50
+ ```powershell
51
+ freelog-cli resource recover --env dev
52
+ ```
53
+
54
+ 若显示“请求尚未发送”，表示进程在允许 POST 前中断；执行下列明确收尾只会删掉未决记录，工作稿保留，随后可重新提交。若显示“结果未知”，CLI 才查询该资源的**目标版本**；只有版本存在且远端 `fileSha1` 与记录完全相同，才会显示“已确认”。此时下列收尾会删除工作稿和未决记录：
55
+
56
+ ```powershell
57
+ freelog-cli resource recover --apply --yes --env dev
58
+ ```
59
+
60
+ 对“尚未发送”状态，这会原子删除未决记录、保留工作稿；对“已确认”状态，才会原子删除工作稿和未决记录。不会重发版本。若版本不存在、SHA 不同、环境不对或本地身份不一致，CLI 会保留两份文件并停止。未决记录存在时，除登录、退出、只读查看和 `resource recover` 外，新的业务写入都会被拦住。
43
61
 
44
62
  ## 管理授权策略
45
63
 
@@ -52,7 +70,7 @@ freelog-cli policy set --id <policyId> --on --env dev
52
70
  freelog-cli policy set --id <policyId> --off --env dev
53
71
  ```
54
72
 
55
- `policy template list` 按当前资源类型列出**全部**平台模板（默认每页 20 条），包含带交易事件的模板，不按免费/付费过滤。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
73
+ 当前后端按资源类型筛选模板存在故障，`policy template list` 暂时列出平台返回的**全部**模板（默认每页 20 条），包含带交易事件的模板，不在 CLI 按免费/付费、事件或类型猜测过滤；后端修复后再恢复按类型请求。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板会先由平台重新编译，最终能否写入由平台判定；目前带事件或需要填写时间、金额等参数的模板可能受后端编译契约阻塞，CLI 不猜测转换。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
56
74
 
57
75
  `policy apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
58
76
 
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 CHANGED
@@ -10,17 +10,17 @@
10
10
  | `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
11
11
  | `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
12
12
  | 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
13
- | `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会列出可复制的 `file:N.json`，也可传 `id:<资源ID>`、`name:<标识符>`。 |
13
+ | `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、完整标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会逐份列出可复制的 `id:`、`name:`、`artifact:` 和 `file:N.json`。标题仅展示，不是选择器。 |
14
14
  | `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传 `--resource` 选身份，不能复用旧 SHA1。 |
15
15
  | `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
16
- | `主题/插件请指定构建产物目录，不要自己打 zip` | 主题/插件给了 zip 或普通文件。 | 传 `dist` / `build` 这类非空构建目录。 |
17
16
  | `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
18
17
  | 已经有发行版本，请用 `update-version` | 对已有版本的资源调用了 `create-version`。 | 用 `version draft pull` 后运行 `update-version`。 |
19
18
  | 还没有发行版本，请先 `create-version` | 对首版资源调用了 `update-version` 或 `draft pull`。 | 使用 `create-version --prepare` 或 `create-version --yes`。 |
20
19
  | 工作稿与身份不一致 / 不支持 schemaVersion=1 | 本地工作稿损坏、过期或属于另一资源。 | 保留原文件以便检查；明确 `version draft discard`，或从线上 `draft pull` 重建。 |
21
20
  | 工作稿来源不是当前 latest | 线上已有新版本，而本地稿仍基于其它版本。 | 优先检查后用 `version draft pull --yes` 重建；确认要继续使用原底时，在 `update-version` 上明确传匹配的 `--reuse-version <版本>`。 |
22
- | 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`，最后执行下一步；`--reset` 会在后续检查前立即丢弃工作稿，仅在已核对资源和命令路径后使用。 |
23
- | `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
21
+ | `有未提交工作稿；请加 --yes 确认…` | 脚本试图丢弃或覆盖工作稿，却没有显式确认。 | 检查目标资源后重试并加 `--yes`；交互终端可阅读摘要后确认或取消。 |
22
+ | 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`（TTY 确认；脚本加 `--yes`），最后执行下一步；`--reset` 会先校验再确认，确认后的后续失败不会恢复旧稿。 |
23
+ | `当前类型不支持可选配置` | 后台资源类型详情的 `resourceConfig.supportOptionalConfig` 不是 `2`；资源的文件形态、名称或主题/插件身份都不决定此能力。 | 不执行 `version option add` 或 `set`；若工作稿有历史遗留项可用 `version option rm <key>` 清理，否则提交也会被拒绝。 |
24
24
  | `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
25
25
  | 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
26
26
  | `上架须已有版本` / `上架须至少一条启用策略` | 上架条件不完整。 | 先发行版本、添加并启用策略，随后重试 `online`。 |
@@ -30,7 +30,7 @@
30
30
 
31
31
  - 不要只删除 `N.json` 或只删除 `N.version.json`。确需放弃一份本地状态时，先备份，再删除同号的完整状态单元（`N.json` 与 `N.version.json`）；未提交工作稿会永久丢失，之后可在空位重新 `bind`。
32
32
  - 不要复制或编辑 `.freelog/auth`；该文件不含可移植秘密，真正的凭据在当前操作系统的凭据库中。
33
- - 不要手工打 zip 后交给主题/插件发版；CLI 只接收构建目录。
33
+ - 主题/插件给目录时由 CLI 临时压缩；若已有 zip 或其它单个产物文件，可直接作为 `--artifact` 提交，不会再次压缩。
34
34
  - 不要在失败后重新运行 `create` 试图补救已有线上壳；先用 `bind` 接入已有资源。
35
35
  - 不要用旧命令参数 `--scaffold` 或把 `--resource-type` 当作常规接口；前者不存在，后者仅为弃用兼容。
36
36
 
package/dist/docs/08-/346/234/254/345/234/260/346/226/207/344/273/266/345/217/202/350/200/203.md CHANGED
@@ -7,22 +7,23 @@ my-project/
7
7
  .freelog/
8
8
  auth # 非秘密账号选择器；不提交
9
9
  1.json # 第 1 份资源身份
10
- 1.version.json # 第 1 份未提交工作稿（存在时）
11
- index.json # filePath → 身份编号索引
12
- .lock # 瞬时写锁
10
+ 1.version.json # 第 1 份未提交工作稿（存在时）
11
+ .pending-operation.json # 已准备发送或已发送、但尚未完成本地收尾的版本提交（存在时）
12
+ .lock # 瞬时写锁
13
13
  .txn.json # 瞬时跨文件事务；异常中断后供 CLI 前滚恢复
14
14
  ```
15
15
 
16
16
  ## `N.json`：资源身份
17
17
 
18
- 初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 id 和名称。
18
+ 初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 ID、完整标识和短名称缓存。
19
19
 
20
20
  ```json
21
21
  {
22
22
  "schemaVersion": 1,
23
- "subject": "resource",
24
- "resourceId": "6a9f...",
25
- "name": "my-video",
23
+ "subject": "resource",
24
+ "resourceId": "6a9f...",
25
+ "resourceName": "alice/my-video",
26
+ "name": "my-video",
26
27
  "title": "我的视频",
27
28
  "typeCode": "RT006003",
28
29
  "filePath": "video.mp4",
@@ -34,12 +35,14 @@ my-project/
34
35
  |---|---|
35
36
  | `subject` | 本期恒为 `resource`。 |
36
37
  | `typeCode` | 普通资源是已验证的最终叶子；主题/插件固定为 `RT001` / `RT002`。 |
37
- | `resourceId` 与 `name` | 绑定后成对出现；`name` 是当前账号命名空间内不可重复的短标识。未绑定 `init` 身份不应预写。 |
38
- | `title` | 创建、bind 或 `resource sync` 写入的本地展示/选择信息；标题可重复且会变化，不是线上写入依据。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
39
- | `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件是构建目录，例如 `dist`；绝对路径与 `..` 越界路径不合法。 |
38
+ | `resourceId`、`resourceName` 与 `name` | 绑定后写入；`resourceName` 是完整不可变标识，`name` 是其短段展示缓存。旧状态可缺 `resourceName`，此时不得使用 `name:` 选择。 |
39
+ | `title` | 创建、bind 或 `resource sync` 写入的本地展示缓存；标题可重复、可变化且可能落后线上，不参与资源选择。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
40
+ | `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件可以是构建目录（例如 `dist`）或单个文件（包括 zip）。绝对路径、`..` 越界路径和 `.freelog/` 内路径不合法；已存在路径即使表面在工程内，解析软链接后也不能逃到工程外。两份资源不能共享同一真实文件，主题/插件构建目录也不能与另一产物路径嵌套。 |
40
41
  | `env` | 非 prod 的已绑定资源会记录 `dev` 或 `test`。 |
41
42
 
42
- 这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地选择/展示缓存保存，可由 `resource sync` 更新。
43
+ 这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地展示缓存保存，可由 `resource sync` 更新。
44
+
45
+ `N.json` 不要求用户手工记编号。所有单资源命令可用 `--resource id:<资源ID>`、完整 `name:<username/name>` 或 `artifact:<filePath>` 选中它；`file:N.json` 是仍完整支持的精确状态文件形式，适合 AI、脚本和恢复。标题只在列表显示。
43
46
 
44
47
  ## `N.version.json`：未提交工作稿
45
48
 
@@ -65,17 +68,19 @@ my-project/
65
68
  }
66
69
  ```
67
70
 
68
- 主题/插件在这里记录的是 CLI 临时 zip 的 `filename` / SHA1；身份里的 `filePath` 仍是构建目录。普通资源则记录原文件的 `filename` / SHA1。
69
-
70
- ## `index.json`、`.lock` 与 `.txn.json`
71
+ 主题/插件使用目录时，这里记录 CLI 临时 zip 的 `filename` / SHA1；使用单个文件时记录原文件的 `filename` / SHA1。身份里的 `filePath` 保留用户选择的目录或文件。普通资源始终记录原文件的 `filename` / SHA1。
71
72
 
72
- `index.json` 是 `filePath → N` 的查询索引，不是主数据；它与身份不一致时，CLI 以 `N.json` 为准修复。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
73
+ ## `.pending-operation.json`、`.lock` 与 `.txn.json`
74
+
75
+ `.pending-operation.json` 记录版本提交的本地阶段：`prepared` 表示已完成提交前检查、但 POST 尚未允许发出；`sending` 表示请求可能已经到达平台。旧记录一律按 `sending` 保守处理。它只记录资源 ID、本地编号、环境、目标版本和文件 SHA，不含 token、文件内容、完整版本提交体或版本历史。不要手工删除它：先运行 `resource recover --env <环境>`；`prepared` 由 `resource recover --apply --yes` 只清记录、保留工作稿，`sending` 只有 CLI 证明远端目标版本和 SHA 都相同后，才会清理它与对应工作稿。
76
+
77
+ 身份选择直接读取并校验 `N.json`，CLI 不维护 `index.json` 之类的派生索引。旧工程遗留的 `index.json` 不会被读取、重建或自动删除；可以保留，也可以在确认没有未完成旧版事务后自行移除。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
73
78
 
74
- 需要同时改身份、索引和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
79
+ 需要同时改身份和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
75
80
 
76
81
  ## Git 建议
77
82
 
78
83
  - 永远忽略 `.freelog/auth`。
79
84
  - `N.json` 和版本工作稿不含秘密，适合随工程协作。
80
85
  - `N.version.json` 是未提交的工作内容；是否提交由团队协作流程决定，不能把它当成已发版本事实。
81
- - 不要提交 `.lock`、`.txn.json` 或临时 zip。
86
+ - 不要提交 `.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 CHANGED
@@ -2,27 +2,26 @@
2
2
 
3
3
  本页是决策入口：先判断资源是否已经在线上存在、是否已经发行过版本、当前工程是否已有 `.freelog/` 身份，再复制对应路径。不要把 `init`、`create`、`bind` 当成同义词：它们分别是立项、建线上资源壳、接入已有线上资源。需要解释命令语义时回到专题页；需要完整参数和副作用时查[完整命令参考](./10-命令参考.md)。
4
4
 
5
- 所有例子以 `--env dev` 为例；多资源工程中，每一条涉及某资源的命令都补上 `--resource <selector>`；产物始终用 `--artifact <path>`。
5
+ 所有例子以 `--env dev` 为例；多资源工程中，除新增或接续身份的 `create` / `bind` 外，每一条涉及某资源的命令都补上 `--resource <selector>`；产物始终用 `--artifact <path>`。
6
6
 
7
7
  ## 先选入口
8
8
 
9
9
  | 你现在的情况 | 从这里开始 | 不要做 |
10
10
  |---|---|---|
11
- | 空目录，普通文件资源还未上线 | `init --type <最终叶子>`，再 `create` | 把父类型或类型名称交给 `--type`。 |
12
- | 已有普通文件工程、没有线上资源 | `create --type <最终叶子> --artifact <文件>` | 为了建壳强行覆盖工程执行 `init`。 |
11
+ | 已有普通文件、资源还未上线 | `init --type <最终叶子> --artifact <文件>`，再 `create`；也可直接 `create --type … --artifact …` | 把父类型或类型名称交给 `--type`，或让状态没有产物路径。 |
13
12
  | 空目录，要从官方主题/插件模板开始 | `init theme|widget <目录> --template <id>` | 选择资源类型，或手工复制本地模板。 |
14
- | 已有主题/插件工程、没有线上资源 | `create --type RT001|RT002 --artifact <dist|build>` | 对非空工程再执行 `init`，或自己先打 zip。 |
13
+ | 已有主题/插件工程、没有线上资源 | `init --type RT001|RT002 --artifact <文件或目录>`，再 `create`；也可直接 `create` | 运行会复制模板的 `init theme/widget`，或让 CLI 再压已准备的 zip。 |
15
14
  | 线上有自己的壳但没有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `create-version` | 再次 `create`。 |
16
15
  | 线上已有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `version draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
17
16
  | 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
18
- | 同一工程有多份资源身份 | 先用 `status --resource file:N.json` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact`、标题或状态文件顺序猜测目标。 |
17
+ | 同一工程有多份资源身份 | 先用 `status --resource id:<资源ID>`、`name:<标识>` 或 `artifact:<文件>` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact` 上传参数、标题或状态文件顺序猜测目标。 |
19
18
  | 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
20
19
 
21
20
  ## 场景一：从空目录发行普通文件首版
22
21
 
23
22
  ```powershell
24
23
  freelog-cli login --env dev
25
- freelog-cli init . --type RT006003 --yes --env dev
24
+ freelog-cli init . --type RT006003 --artifact video.mp4 --yes --env dev
26
25
  freelog-cli create --title "我的视频" --name my-video --artifact video.mp4 --yes --env dev
27
26
  freelog-cli create-version --prepare --env dev
28
27
  freelog-cli version show --local --env dev
@@ -42,7 +41,24 @@ freelog-cli create-version --prepare --env dev
42
41
  freelog-cli create-version --yes --env dev
43
42
  ```
44
43
 
45
- `create` 只登记文件路径并创建资源壳；文件不存在、为空、过大或解析失败时，会在 `create-version` 停止，线上不会出现半个版本。
44
+ `create` 在建壳前确认 `--artifact` 指向工程内真实文件；它不上传文件。空文件、大小限制或内容解析等发行校验仍会在 `create-version` 停止，线上不会出现半个版本。
45
+
46
+ ### 同一素材目录连续发行多个独立资源
47
+
48
+ 不需要为每个视频、图片另建工程目录。一个素材目录可以依次为每个文件建立一份资源身份：
49
+
50
+ ```powershell
51
+ # media/ 下同时有 video.mp4 与 cover.jpg
52
+ freelog-cli create --title "视频" --name my-video --type <视频叶子code> --artifact video.mp4 --yes --env dev
53
+ # 写入 .freelog/1.json，filePath=video.mp4
54
+ freelog-cli create --title "封面图" --name my-cover --type <图片叶子code> --artifact cover.jpg --yes --env dev
55
+ # 写入 .freelog/2.json，filePath=cover.jpg
56
+
57
+ freelog-cli create-version --resource artifact:video.mp4 --prepare --env dev
58
+ freelog-cli create-version --resource artifact:cover.jpg --prepare --env dev
59
+ ```
60
+
61
+ 第二次 `create` 不会要求选择或覆盖 `1.json`：在没有未绑定状态时，它新增下一个编号。后续发版、状态、上下架等操作才用 `--resource` 精确选择其中一份；可用 `id:`、完整 `name:`、`artifact:` 或 AI/脚本使用的 `file:N.json`。标题仅展示，不能选择资源。`--artifact` 从不承担资源选择职责。
46
62
 
47
63
  ## 场景三：从官方模板创建主题或插件并发行首版
48
64
 
@@ -60,17 +76,18 @@ freelog-cli create-version --cwd my-theme --yes --env dev
60
76
 
61
77
  ## 场景四：已有主题或插件工程，创建首版资源
62
78
 
63
- 既有非空工程不运行 `init`，也没有必要补造模板元数据。明确其固定类型和构建目录：
79
+ 既有项目不运行会复制模板的 `init theme`，也没有必要补造模板元数据。先明确其固定类型和构建目录：
64
80
 
65
81
  ```powershell
66
82
  freelog-cli login --env dev
67
- freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
83
+ freelog-cli init . --type RT001 --artifact dist --yes --env dev
84
+ freelog-cli create --title "已有主题" --name existing-theme --yes --env dev
68
85
  # 自己完成构建后
69
86
  freelog-cli create-version --prepare --env dev
70
87
  freelog-cli create-version --yes --env dev
71
88
  ```
72
89
 
73
- 插件使用 `--type RT002`。`dist` / `build` 是目录；CLI 仅在提交前临时压缩其中内容，绝不把 zip 写进 `filePath`。
90
+ 插件在 init 使用 `--type RT002`。也可直接 `create --type RT001|RT002 --artifact dist` 一步建壳。`dist` / `build` 是目录时，CLI 仅在提交前临时压缩其中内容；若指定已有 zip 或其它文件，则直接上传并可记录到 `filePath`。
74
91
 
75
92
  ## 场景五：自己的线上资源未发行，在本地补接后发首版
76
93
 
@@ -81,7 +98,7 @@ freelog-cli create-version --prepare --env dev
81
98
  freelog-cli create-version --yes --env dev
82
99
  ```
83
100
 
84
- 主题/插件把 `video.mp4` 换成 `dist` 或 `build`。`bind` 会从平台读取类型；对主题/插件，没有已记录目录时须传 `--artifact`。
101
+ 主题/插件把 `video.mp4` 换成 `dist`、`build` 或已有 zip。`bind` 会从平台读取类型；对主题/插件，没有已记录产物时须传 `--artifact`。
85
102
 
86
103
  ## 场景六：自己的线上资源已发行，在本地接入并发新版本
87
104
 
@@ -97,14 +114,14 @@ freelog-cli update-version --bump patch --yes --env dev
97
114
 
98
115
  ## 场景七：构建路径、工作稿或多资源工程发生变化
99
116
 
100
- - 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --resource file:N.json --artifact build`。只更新记录，不上传也不提交。
117
+ - 构建输出从 `dist` 变成 `build`：主题/插件资源可用 `version set --artifact build`，因为目录是合法锚点；普通文件资源必须给实际文件，例如 `version set --artifact build/video.mp4`。多份资源先用 `--resource artifact:dist` 选择旧身份，再传新的 `--artifact`。只更新记录，不上传也不提交。
101
118
  - 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
102
- - 一个工程中有多份身份：`create-version`、`update-version`、`version draft pull` 等既有资源操作传对应的 `--resource`；不传时 TTY 可选择，非交互会停止，不会猜第一份。`create`、`bind` 例外：它们可在没有未绑定状态时新增 `N.json`；要接续某份未绑定状态时传 `--resource file:N.json`。发版要换产物时再传 `--artifact`。
119
+ - 一个工程中有多份身份：`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 <新路径>`。
103
120
  - 想从另一线上版本重新开始：`version draft pull --version <版本> --yes`；这会覆盖当前未提交工作稿，先看命令打印的摘要。
104
121
 
105
122
  ## 场景八：版本表单、依赖和上线
106
123
 
107
- 首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。详情见 [版本工作稿](./04-版本工作稿.md)。
124
+ 首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。文件分析变化出现待复核附加属性时，先 `version attr review`，逐项决定保留等待恢复或 `review discard <key>`。详情见 [版本工作稿](./04-版本工作稿.md)。
108
125
 
109
126
  展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
110
127
 
@@ -117,7 +134,7 @@ freelog-cli version show --version 1.1.0 --env dev
117
134
  freelog-cli version description --version 1.1.0 --description "补充发布说明" --env dev
118
135
  ```
119
136
 
120
- 这与 `version draft description` 不同：后者只修改尚未提交的更新稿。多资源工程在两条命令上都传相同的 `--resource file:N.json`。
137
+ 这与 `version draft description` 不同：后者只修改尚未提交的更新稿。多资源工程在两条命令上都传相同的 `--resource id:<资源ID>`、`name:<标识>` 或 `artifact:<文件>`。
121
138
 
122
139
  ## 场景十：更新稿过期，选择重建或继续旧底
123
140
 
@@ -135,4 +152,4 @@ freelog-cli update-version --bump patch --yes --env dev
135
152
  freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
136
153
  ```
137
154
 
138
- 若工作稿本身不要了，可把前两步改为 `update-version --reset --bump patch --yes`；它会删除当前稿后重新建立，不要把它当成无损刷新。
155
+ 若工作稿本身不要了，可把前两步改为 `update-version --reset --bump patch --yes`；它会先校验路径与版本号，确认后才删除当前稿并重新建立。TTY 可阅读摘要后确认；确认后的网络或提交失败不会恢复旧稿，不要把它当成无损刷新。