@freelog-cli/cli2 0.5.1 → 0.5.3

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 (14) hide show
  1. package/dist/bin/index.js +818 -545
  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 +83 -81
  4. package/dist/docs/02-/346/227/245/345/270/270/350/267/257/345/276/204.md +92 -90
  5. package/dist/docs/03-/344/270/273/351/242/230/344/270/216/346/217/222/344/273/266.md +126 -124
  6. package/dist/docs/04-/347/211/210/346/234/254/345/267/245/344/275/234/347/250/277.md +110 -78
  7. package/dist/docs/05-/350/265/204/346/272/220/347/256/241/347/220/206.md +71 -55
  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 +37 -34
  9. package/dist/docs/07-/347/216/257/345/242/203/344/270/216/345/207/255/346/215/256.md +60 -58
  10. package/dist/docs/08-/346/234/254/345/234/260/346/226/207/344/273/266/345/217/202/350/200/203.md +83 -79
  11. package/dist/docs/09-/346/214/211/345/234/272/346/231/257/346/223/215/344/275/234.md +155 -108
  12. package/dist/docs/10-/345/221/275/344/273/244/345/217/202/350/200/203.md +113 -0
  13. package/dist/docs/README.md +93 -74
  14. package/package.json +1 -1
package/dist/docs/04-/347/211/210/346/234/254/345/267/245/344/275/234/347/250/277.md CHANGED
@@ -1,78 +1,110 @@
1
- # 版本工作稿
2
-
3
- 工作稿是 `.freelog/N.version.json`：一份已绑定资源的、尚未提交的下一版本内容。它保存文件摘要、属性、可选配置、依赖和更新版描述。
4
-
5
- 工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
6
-
7
- | 要做什么 | 命令 | 是否提交线上版本 |
8
- |---|---|---|
9
- | 看线上版本 | `version show [--version <ver>]` | 否 |
10
- | 看本地工作稿 | `version show --local` | 否 |
11
- | 从已发版本建立更新稿 | `version draft pull [--version <ver>]` | 否 |
12
- | 准备首版稿 | `create-version --prepare` | 否 |
13
- | 编辑稿 | `version attr` / `option` / `dep` / `version draft description` | 否；依赖签约是独立平台动作 |
14
- | 丢弃稿 | `version draft discard` | 否 |
15
- | 提交 | `create-version --yes` / `update-version --version <ver> --yes` | 是 |
16
-
17
- ## 首版工作稿
18
-
19
- 资源还没有任何已发版本时：
20
-
21
- ```powershell
22
- freelog-cli create-version --prepare --file video.mp4 --env dev
23
- freelog-cli version show --local --env dev
24
- freelog-cli create-version --yes --file video.mp4 --env dev
25
- ```
26
-
27
- 首版号固定为 `1.0.0`，首版描述为空。`create-version` 成功后删除工作稿；网络、解析或提交失败时保留它。
28
-
29
- ## 更新工作稿
30
-
31
- 已有版本时，以线上版本为底建立稿：
32
-
33
- ```powershell
34
- freelog-cli version draft pull --version 1.0.0 --env dev
35
- freelog-cli version draft description --description "本次更新说明" --env dev
36
- freelog-cli update-version --version 1.1.0 --yes --env dev
37
- ```
38
-
39
- 已有本地稿时，`version draft pull` 默认不会覆盖。明确要重来时使用 `--yes`；命令会打印将被覆盖的来源、文件和条目摘要。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
40
-
41
- ## 编辑属性和可选配置
42
-
43
- ```powershell
44
- freelog-cli version attr add "名称=作者 键=author 值=张三"
45
- freelog-cli version attr set "键=author 值=李四"
46
- freelog-cli version attr rm author
47
- freelog-cli version attr list
48
-
49
- freelog-cli version option add "名称=主题 键=theme 方式=文本 默认=dark"
50
- freelog-cli version option set "键=theme 默认=light"
51
- freelog-cli version option rm theme
52
- freelog-cli version option list
53
- ```
54
-
55
- 可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，所有 `version option` 写操作都会停止。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
56
-
57
- ## 编辑依赖
58
-
59
- ```powershell
60
- freelog-cli version dep add <resourceId> --range ^1.0.0
61
- freelog-cli version dep range <resourceId> --range ^1.1.0
62
- freelog-cli version dep rm <resourceId>
63
- freelog-cli version dep list
64
- ```
65
-
66
- 对方资源尚未授权时，交互模式会列出所有可签约且启用的策略供选择。脚本模式必须明确指定策略：
67
-
68
- ```powershell
69
- freelog-cli version dep add <resourceId> --range ^1.0.0 --policy-id <policyId> --yes
70
- ```
71
-
72
- CLI 列出的是对方资源的全部启用策略，不按免费/付费筛选。它以平台 `batchAuth` 返回的 `isAuth` 判断是否已授权；签约成功后才把依赖写入工作稿。支付、合约查询和上抛不属于本期 CLI，不能用它们推断授权状态。
73
-
74
- ## 文件变化与恢复
75
-
76
- 发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--file <已记录路径>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给构建目录。新脚本不要把 `--file` 当作换产物参数。
77
-
78
- 不要手工改 `N.version.json`。该文件有严格 schema，损坏、旧格式或身份不一致时 CLI 会保留原文件并停止；可明确丢弃工作稿，或从线上版本重新 `draft pull`。
1
+ # 版本工作稿
2
+
3
+ 本页是“尚未提交的下一版本”专题。工作稿是 `.freelog/N.version.json`：一份已绑定资源的、尚未提交的下一版本内容。它保存文件摘要、属性、可选配置、依赖和更新版描述。只想决定首版/更新版该走哪条路径，先看[资源生命周期](./02-日常路径.md)；想查精确子命令和参数，看[完整命令参考](./10-命令参考.md)。
4
+
5
+ 工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
6
+
7
+ 多资源工程中，本页所有命令都加同一个 `--resource <selector>`：人工优先 `id:`、`name:` 或 `artifact:<当前文件>`，标题唯一时可用 `title:`；AI、脚本和恢复可用精确的 `file:N.json`。例如 `version draft pull --resource artifact:video.mp4` 是选择视频资源，不是上传文件。
8
+
9
+ | 要做什么 | 命令 | 是否提交线上版本 |
10
+ |---|---|---|
11
+ | 看线上版本 | `version show [--version <ver>]` | 否 |
12
+ | 看本地工作稿 | `version show --local` | 否 |
13
+ | 从已发版本建立更新稿 | `version draft pull [--version <ver>]` | 否 |
14
+ | 准备首版稿 | `create-version --prepare` | 否 |
15
+ | 编辑稿 | `version attr` / `option` / `dep` / `version draft description` | 否；依赖签约是独立平台动作 |
16
+ | 丢弃稿 | `version draft discard [--yes]` | 否 |
17
+ | 提交 | `create-version --yes` / `update-version --version <ver> --yes` | 是 |
18
+ | 改已发布版本的说明 | `version description --version <ver> --description <文本>` | 是；仅更新该已发版本说明 |
19
+
20
+ ## 首版工作稿
21
+
22
+ 资源还没有任何已发版本时：
23
+
24
+ ```powershell
25
+ freelog-cli create-version --prepare --env dev
26
+ freelog-cli version show --local --env dev
27
+ freelog-cli create-version --yes --env dev
28
+ ```
29
+
30
+ 首版号固定为 `1.0.0`，首版描述为空。`create-version` 成功后删除工作稿；网络、解析或提交失败时保留它。
31
+
32
+ ## 更新工作稿
33
+
34
+ 已有版本时，以线上版本为底建立稿：
35
+
36
+ ```powershell
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
40
+ ```
41
+
42
+ 已有本地稿时，`version draft pull` 会先验证目标线上版本。TTY 显示旧稿摘要并以“否”为默认确认；脚本必须显式传 `--yes` 才能覆盖。`version draft discard` 同样先显示摘要并确认；脚本必须 `--yes`，没有工作稿时安全退出。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
43
+
44
+ ## 两种“版本说明”不要混用
45
+
46
+ ```powershell
47
+ # 已有线上版本：修改尚未提交的更新稿说明
48
+ freelog-cli version draft description --description "本次更新说明" --env dev
49
+
50
+ # 已发布版本：直接修改该版本的线上说明，不创建新版本
51
+ freelog-cli version description --version 1.1.0 --description "补充发布说明" --env dev
52
+ ```
53
+
54
+ 前者只作用于更新工作稿，且不会发版；后者不读取或修改工作稿，直接更新指定已发版本。想改首版或任一历史版本的线上说明时用后者。
55
+
56
+ ## 编辑属性和可选配置
57
+
58
+ ```powershell
59
+ freelog-cli version attr add "名称=作者 键=author 值=张三"
60
+ freelog-cli version attr set "键=author 值=李四"
61
+ freelog-cli version attr rm author
62
+ freelog-cli version attr list
63
+
64
+ freelog-cli version option add "名称=主题 键=theme 方式=文本 默认=dark"
65
+ freelog-cli version option set "键=theme 默认=light"
66
+ freelog-cli version option rm theme
67
+ freelog-cli version option list
68
+ ```
69
+
70
+ 可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，所有 `version option` 写操作都会停止。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
71
+
72
+ ## 编辑依赖
73
+
74
+ ```powershell
75
+ freelog-cli version dep add <resourceId> --range ^1.0.0
76
+ freelog-cli version dep range <resourceId> --range ^1.1.0
77
+ freelog-cli version dep rm <resourceId>
78
+ freelog-cli version dep list
79
+ ```
80
+
81
+ 对方资源尚未授权时，交互模式会列出所有可签约且启用的策略供选择。脚本模式必须明确指定策略：
82
+
83
+ ```powershell
84
+ freelog-cli version dep add <resourceId> --range ^1.0.0 --policy-id <policyId> --yes
85
+ ```
86
+
87
+ CLI 列出的是对方资源的全部启用策略，不按免费/付费筛选。它以平台 `batchAuth` 返回的 `isAuth` 判断是否已授权；签约成功后才把依赖写入工作稿。支付、合约查询和上抛不属于本期 CLI，不能用它们推断授权状态。
88
+
89
+ ## 文件变化与恢复
90
+
91
+ 发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给文件或构建目录（仅目录会临时压缩）。新脚本不要使用 `--file`。
92
+
93
+ 不要手工改 `N.version.json`。该文件有严格 schema，损坏、旧格式或身份不一致时 CLI 会保留原文件并停止；可明确丢弃工作稿，或从线上版本重新 `draft pull`。
94
+
95
+ ## 确认丢稿后的快捷重来
96
+
97
+ 优先使用显式步骤，因为它最容易检查：`version draft discard` 后再执行 `create-version --prepare` 或 `version draft pull`。如果确认当前稿完全不要，也可让发行命令在同一次操作中重置：
98
+
99
+ ```powershell
100
+ # 无已发版本：删除首版稿，重新准备
101
+ freelog-cli create-version --reset --prepare --env dev
102
+
103
+ # 已有版本：删除更新稿，按 latest 重拉并提交新号
104
+ freelog-cli update-version --reset --bump patch --yes --env dev
105
+
106
+ # 工作稿本来以 1.0.0 为底，明确按该底提交，而非最新版本
107
+ freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
108
+ ```
109
+
110
+ `--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
@@ -1,55 +1,71 @@
1
- # 资源管理
2
-
3
- 这些命令管理已绑定资源的线上事实。它们不替代版本发行，也不会修改未提交版本工作稿。
4
-
5
- ## 查看现状
6
-
7
- ```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
12
- ```
13
-
14
- `status` 汇总本地身份、是否存在工作稿和线上 latest；`version show` 与 `policy list` 读取平台当前结果。若只想看本地未交内容，用 `version show --local`。
15
-
16
- ## 修改展示信息
17
-
18
- ```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
22
- ```
23
-
24
- `update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。
25
-
26
- - 标题最多 100 个字符，简介最多 200 个字符。
27
- - 标签最多 20 个，每个最多 20 个字符；不能重复或包含 `#`。
28
- - `--yes` 且没有任一修改字段会失败，不发送空更新。
29
-
30
- ## 管理授权策略
31
-
32
- ```powershell
33
- freelog-cli policy list --env dev
34
- freelog-cli policy template list --page 1 --page-size 20 --env dev
35
- freelog-cli policy template apply <templateId> --yes --env dev
36
- freelog-cli policy apply --from-file .\free-policy.json --yes --env dev
37
- freelog-cli policy set --id <policyId> --on --env dev
38
- freelog-cli policy set --id <policyId> --off --env dev
39
- ```
40
-
41
- `policy template list` 按当前资源类型列出**全部**平台模板（默认每页 20 条），包含带交易事件的模板，不按免费/付费过滤。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
42
-
43
- `policy apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
44
-
45
- ## 上架与下架
46
-
47
- ```powershell
48
- freelog-cli validate --for online --env dev
49
- freelog-cli online --env dev
50
- freelog-cli offline --env dev
51
- ```
52
-
53
- 上架前必须已有至少一个已发版本和一条启用策略。`validate --for online` 只检查并说明缺失项；`online` 会再次检查后才写线上状态。`offline` 只改变可用状态，不删除资源、版本、策略、身份或工作稿。
54
-
55
- 如果账号不是资源 owner、资源被冻结或环境不匹配，平台写操作会失败。CLI 不会因此删除本地工程或未提交工作稿；修正登录账号或环境后可继续。
1
+ # 资源管理
2
+
3
+ 本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
4
+
5
+ 多资源工程中，本页除不带选择器即批量的 `resource sync` 外，每条命令都加 `--resource <selector>`。优先用 `id:`、`name:` 或 `artifact:<当前文件>`；`file:N.json` 保留给 AI、脚本和恢复。
6
+
7
+ ## 查看现状
8
+
9
+ ```powershell
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
14
+ ```
15
+
16
+ `status` 汇总本地身份、是否存在工作稿和线上 latest；`version show` 与 `policy list` 读取平台当前结果。若只想看本地未交内容，用 `version show --local`。
17
+
18
+ ## 修改展示信息
19
+
20
+ ```powershell
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 "<封面值>" --yes --env dev
24
+ ```
25
+
26
+ `update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。
27
+
28
+ - 标题最多 100 个字符，简介最多 200 个字符。
29
+ - 标签最多 20 个，每个最多 20 个字符；不能重复或包含 `#`。
30
+ - `--yes` 且没有任一修改字段会失败，不发送空更新。
31
+
32
+ ## 同步本地标题
33
+
34
+ 资源标题可能在网页、另一台机器或其它工具中修改。多资源工程用标题选择时，应显式同步，而不是猜测旧标题：
35
+
36
+ ```powershell
37
+ # 当前环境的全部已绑定资源；这是唯一的批量资源命令
38
+ freelog-cli resource sync --env dev
39
+
40
+ # 只同步一份资源
41
+ freelog-cli resource sync --resource id:<resourceId> --env dev
42
+ ```
43
+
44
+ 同步只读取平台资源详情并回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
45
+
46
+ ## 管理授权策略
47
+
48
+ ```powershell
49
+ freelog-cli policy list --env dev
50
+ freelog-cli policy template list --page 1 --page-size 20 --env dev
51
+ freelog-cli policy template apply <templateId> --yes --env dev
52
+ freelog-cli policy apply --from-file .\free-policy.json --yes --env dev
53
+ freelog-cli policy set --id <policyId> --on --env dev
54
+ freelog-cli policy set --id <policyId> --off --env dev
55
+ ```
56
+
57
+ `policy template list` 按当前资源类型列出**全部**平台模板（默认每页 20 条），包含带交易事件的模板，不按免费/付费过滤。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
58
+
59
+ `policy apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
60
+
61
+ ## 上架与下架
62
+
63
+ ```powershell
64
+ freelog-cli validate --for online --env dev
65
+ freelog-cli online --env dev
66
+ freelog-cli offline --env dev
67
+ ```
68
+
69
+ 上架前必须已有至少一个已发版本和一条启用策略。`validate --for online` 只检查并说明缺失项；`online` 会再次检查后才写线上状态。`offline` 只改变可用状态，不删除资源、版本、策略、身份或工作稿。
70
+
71
+ 如果账号不是资源 owner、资源被冻结或环境不匹配，平台写操作会失败。CLI 不会因此删除本地工程或未提交工作稿；修正登录账号或环境后可继续。
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
@@ -1,34 +1,37 @@
1
- # 常见情况与报错
2
-
3
- CLI 的错误不会自动丢弃工作稿或覆盖工程。脚本调用可加 `--json` 获得稳定的 `{code,message}` 结构。
4
-
5
- | 看到的情况 | 原因 | 应对方式 |
6
- |---|---|---|
7
- | `prod 暂未开放` | 未显式选择联调环境。 | 为本次命令加 `--env dev` 或 `--env test`。 |
8
- | `请先 login` | 当前目录向上没有可用账号选择器。 | 在工程运行 `login --env ...`，或使用全局账号选择器。 |
9
- | 凭据环境不一致 / 凭据库中不存在凭据 | 工作区选择器不能用于本次环境，或系统凭据被清除。 | `logout` 后在同一环境重新 `login`；不要手改 selector。 |
10
- | `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
11
- | `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
12
- | 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
13
- | `一夹多条必须指定 --file` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 传该资源已记录的 `--file`。 |
14
- | `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传已记录的 `--file` 选身份，不能复用旧 SHA1。 |
15
- | `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
16
- | `主题/插件请指定构建产物目录，不要自己打 zip` | 主题/插件给了 zip 或普通文件。 | 传 `dist` / `build` 这类非空构建目录。 |
17
- | `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
18
- | 已经有发行版本，请用 `update-version` | 对已有版本的资源调用了 `create-version`。 | 用 `version draft pull` 后运行 `update-version`。 |
19
- | 还没有发行版本，请先 `create-version` | 对首版资源调用了 `update-version` 或 `draft pull`。 | 使用 `create-version --prepare` 或 `create-version --yes`。 |
20
- | 工作稿与身份不一致 / 不支持 schemaVersion=1 | 本地工作稿损坏、过期或属于另一资源。 | 保留原文件以便检查；明确 `version draft discard`，或从线上 `draft pull` 重建。 |
21
- | `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
22
- | `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
23
- | 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
24
- | `上架须已有版本` / `上架须至少一条启用策略` | 上架条件不完整。 | 先发行版本、添加并启用策略，随后重试 `online`。 |
25
-
26
- ## 不要用这些“修复”方式
27
-
28
- - 不要删除 `N.json` 来取消绑定；身份与工作稿可能因此失去关联。
29
- - 不要复制或编辑 `.freelog/auth`；该文件不含可移植秘密，真正的凭据在当前操作系统的凭据库中。
30
- - 不要手工打 zip 后交给主题/插件发版；CLI 只接收构建目录。
31
- - 不要在失败后重新运行 `create` 试图补救已有线上壳；先用 `bind` 接入已有资源。
32
- - 不要用旧命令参数 `--scaffold` 或把 `--resource-type` 当作常规接口；前者不存在，后者仅为弃用兼容。
33
-
34
- 仍无法判断时，先运行 `status`、`version show --local` 和 `version show`，分别确认本地身份/工作稿、未提交内容与线上 latest。不要在未确认目标资源时使用 `--force`。
1
+ # 故障恢复与常见报错
2
+
3
+ 本页按“看到什么 → 为什么 → 下一步”处理失败；它不是命令清单。CLI 的错误不会自动丢弃工作稿或覆盖工程，只有用户显式执行 `discard` / `--reset` 才会丢稿。脚本调用可加 `--json` 获得稳定的 `{code,message}` 结构。找不到要执行的命令时先查[完整命令参考](./10-命令参考.md)。
4
+
5
+ | 看到的情况 | 原因 | 应对方式 |
6
+ |---|---|---|
7
+ | `prod 暂未开放` | 未显式选择联调环境。 | 为本次命令加 `--env dev` 或 `--env test`。 |
8
+ | `请先 login` | 当前目录向上没有可用账号选择器。 | 在工程运行 `login --env ...`，或使用全局账号选择器。 |
9
+ | 凭据环境不一致 / 凭据库中不存在凭据 | 工作区选择器不能用于本次环境，或系统凭据被清除。 | `logout` 后在同一环境重新 `login`；不要手改 selector。 |
10
+ | `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
11
+ | `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
12
+ | 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
13
+ | `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会逐份列出可复制的 `id:`、`name:`、唯一 `title:`、`artifact:` 和 `file:N.json`。 |
14
+ | `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传 `--resource` 选身份，不能复用旧 SHA1。 |
15
+ | `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
16
+ | `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
17
+ | 已经有发行版本，请用 `update-version` | 对已有版本的资源调用了 `create-version`。 | 用 `version draft pull` 后运行 `update-version`。 |
18
+ | 还没有发行版本，请先 `create-version` | 对首版资源调用了 `update-version` 或 `draft pull`。 | 使用 `create-version --prepare` 或 `create-version --yes`。 |
19
+ | 工作稿与身份不一致 / 不支持 schemaVersion=1 | 本地工作稿损坏、过期或属于另一资源。 | 保留原文件以便检查；明确 `version draft discard`，或从线上 `draft pull` 重建。 |
20
+ | 工作稿来源不是当前 latest | 线上已有新版本，而本地稿仍基于其它版本。 | 优先检查后用 `version draft pull --yes` 重建；确认要继续使用原底时，在 `update-version` 上明确传匹配的 `--reuse-version <版本>`。 |
21
+ | `有未提交工作稿；请加 --yes 确认…` | 脚本试图丢弃或覆盖工作稿，却没有显式确认。 | 检查目标资源后重试并加 `--yes`；交互终端可阅读摘要后确认或取消。 |
22
+ | 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`（TTY 确认；脚本加 `--yes`），最后执行下一步；`--reset` 会先校验再确认，确认后的后续失败不会恢复旧稿。 |
23
+ | `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
24
+ | `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
25
+ | 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
26
+ | `上架须已有版本` / `上架须至少一条启用策略` | 上架条件不完整。 | 先发行版本、添加并启用策略，随后重试 `online`。 |
27
+ | 改了版本说明但新版本没有变化 | 使用的是 `version description`。 | 该命令只改已发布版本说明；要写下一版说明应先建更新稿，再用 `version draft description`。 |
28
+
29
+ ## 不要用这些“修复”方式
30
+
31
+ - 不要只删除 `N.json` 或只删除 `N.version.json`。确需放弃一份本地状态时，先备份，再删除同号的完整状态单元（`N.json` 与 `N.version.json`）；未提交工作稿会永久丢失，之后可在空位重新 `bind`。
32
+ - 不要复制或编辑 `.freelog/auth`；该文件不含可移植秘密，真正的凭据在当前操作系统的凭据库中。
33
+ - 主题/插件给目录时由 CLI 临时压缩；若已有 zip 或其它单个产物文件，可直接作为 `--artifact` 提交，不会再次压缩。
34
+ - 不要在失败后重新运行 `create` 试图补救已有线上壳；先用 `bind` 接入已有资源。
35
+ - 不要用旧命令参数 `--scaffold` 或把 `--resource-type` 当作常规接口；前者不存在，后者仅为弃用兼容。
36
+
37
+ 仍无法判断时，先运行 `status`、`version show --local` 和 `version show`，分别确认本地身份/工作稿、未提交内容与线上 latest。不要在未确认目标资源时使用 `--force`。
package/dist/docs/07-/347/216/257/345/242/203/344/270/216/345/207/255/346/215/256.md CHANGED
@@ -1,58 +1,60 @@
1
- # 环境与账号
2
-
3
- ## 环境
4
-
5
- | 参数 | 用途 | 当前状态 |
6
- |---|---|---|
7
- | `--env dev` | 开发联调环境 | 可用 |
8
- | `--env test` | 测试环境 | 可用 |
9
- | `--env prod` | 正式环境 | 当前 CLI 明确拦截 |
10
-
11
- 环境优先级为：命令行 `--env` → `FREELOG_ENV` → `prod`。因此联调时建议每条平台命令都显式带 `--env dev` 或 `--env test`。
12
-
13
- ## 登录
14
-
15
- 交互终端：
16
-
17
- ```powershell
18
- freelog-cli login --env dev
19
- ```
20
-
21
- 自动化或非交互终端：
22
-
23
- 自动化命令必须同时带 `--login-name <账号名>`、`--password-stdin` 和 `--yes`；由 CI 的保密输入将密码写入标准输入。不要用 PowerShell 变量、命令行文本、脚本文件或环境变量保存或传递密码。
24
-
25
- 登录请求默认 15 秒超时；超时、网络错误、认证失败或系统凭据库不可用时，都不会写入账号选择器。
26
-
27
- 切换账号或环境必须先退出再登录：
28
-
29
- ```powershell
30
- freelog-cli logout --cwd <工程目录>
31
- freelog-cli login --cwd <工程目录> --env test
32
- ```
33
-
34
- 默认登录写工作区选择器；`--global` 写机器默认选择器：
35
-
36
- ```powershell
37
- freelog-cli login --global --env dev
38
- freelog-cli logout --global
39
- ```
40
-
41
- ## 凭据保存位置
42
-
43
- | 内容 | 位置 | 是否可提交到 Git |
44
- |---|---|---|
45
- | 工作区账号选择器 | 最近的 `.freelog/auth` | 否 |
46
- | 全局账号选择器 | `~/.freelog/auth-default.json` | 否 |
47
- | token、Cookie 等秘密 | 操作系统凭据库 | 不适用 |
48
-
49
- `.freelog/auth` 和全局文件只保存 schema、环境、用户 id、用户名与凭据库 key；不保存密码、token 或 Cookie。运行命令时，CLI 从 `--cwd` 向上寻找最近的工作区选择器；一旦找到，即使它损坏或环境不符也不会回退到全局账号。
50
-
51
- 旧式、含 `token` / `cookie` / `iv` 等字段的账号文件不会被解密或迁移。显式 `logout` 清除目标选择器后再 `login`。
52
-
53
- ## 安全边界
54
-
55
- - 不要把密码写成 `--password`、命令行文本、环境变量、JSON 或 Git 文件。
56
- - 不要复制 `.freelog/auth` 到另一台机器；它不带秘密，另一台机器仍需重新登录。
57
- - `logout` 只删除账号选择器，不会删除 `.freelog/N.json` 或版本工作稿。
58
- - 平台返回认证失败时，CLI 停止当前操作；未提交版本稿仍然保留。
1
+ # 环境、登录与凭据
2
+
3
+ 本页说明命令在哪个环境运行、账号如何选择以及秘密存在哪里。它不处理资源身份或版本内容；这些分别见[本地文件参考](./08-本地文件参考.md)和[资源生命周期](./02-日常路径.md)。
4
+
5
+ ## 环境
6
+
7
+ | 参数 | 用途 | 当前状态 |
8
+ |---|---|---|
9
+ | `--env dev` | 开发联调环境 | 可用 |
10
+ | `--env test` | 测试环境 | 可用 |
11
+ | `--env prod` | 正式环境 | 当前 CLI 明确拦截 |
12
+
13
+ 环境优先级为：命令行 `--env` → `FREELOG_ENV` → `prod`。因此联调时建议每条平台命令都显式带 `--env dev` 或 `--env test`。
14
+
15
+ ## 登录
16
+
17
+ 交互终端：
18
+
19
+ ```powershell
20
+ freelog-cli login --env dev
21
+ ```
22
+
23
+ 自动化或非交互终端：
24
+
25
+ 自动化命令必须同时带 `--login-name <账号名>`、`--password-stdin` 和 `--yes`；由 CI 的保密输入将密码写入标准输入。不要用 PowerShell 变量、命令行文本、脚本文件或环境变量保存或传递密码。
26
+
27
+ 登录请求默认 15 秒超时；超时、网络错误、认证失败或系统凭据库不可用时，都不会写入账号选择器。
28
+
29
+ 切换账号或环境必须先退出再登录：
30
+
31
+ ```powershell
32
+ freelog-cli logout --cwd <工程目录>
33
+ freelog-cli login --cwd <工程目录> --env test
34
+ ```
35
+
36
+ 默认登录写工作区选择器；`--global` 写机器默认选择器：
37
+
38
+ ```powershell
39
+ freelog-cli login --global --env dev
40
+ freelog-cli logout --global
41
+ ```
42
+
43
+ ## 凭据保存位置
44
+
45
+ | 内容 | 位置 | 是否可提交到 Git |
46
+ |---|---|---|
47
+ | 工作区账号选择器 | 最近的 `.freelog/auth` | 否 |
48
+ | 全局账号选择器 | `~/.freelog/auth-default.json` | 否 |
49
+ | token、Cookie 等秘密 | 操作系统凭据库 | 不适用 |
50
+
51
+ `.freelog/auth` 和全局文件只保存 schema、环境、用户 id、用户名与凭据库 key；不保存密码、token 或 Cookie。运行命令时，CLI 从 `--cwd` 向上寻找最近的工作区选择器；一旦找到，即使它损坏或环境不符也不会回退到全局账号。
52
+
53
+ 旧式、含 `token` / `cookie` / `iv` 等字段的账号文件不会被解密或迁移。显式 `logout` 清除目标选择器后再 `login`。
54
+
55
+ ## 安全边界
56
+
57
+ - 不要把密码写成 `--password`、命令行文本、环境变量、JSON 或 Git 文件。
58
+ - 不要复制 `.freelog/auth` 到另一台机器；它不带秘密，另一台机器仍需重新登录。
59
+ - `logout` 只删除账号选择器，不会删除 `.freelog/N.json` 或版本工作稿。
60
+ - 平台返回认证失败时，CLI 停止当前操作；未提交版本稿仍然保留。