@freelog-cli/cli2 0.5.1 → 0.5.2

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

@@ -1,79 +1,81 @@
-# 本地文件参考
-
-CLI 的工程状态都在 `.freelog/`。身份和工作稿使用严格的 `schemaVersion: 1`；不要用旧文件、临时 JSON 或自定义字段替代它们。
-
-```text
-my-project/
-  .freelog/
-    auth                    # 非秘密账号选择器；不提交
-    1.json                  # 第 1 份资源身份
-    1.version.json          # 第 1 份未提交工作稿（存在时）
-    index.json              # filePath → 身份编号索引
-    .lock                   # 瞬时写锁
-    .txn.json               # 瞬时跨文件事务；异常中断后供 CLI 前滚恢复
-```
-
-## `N.json`：资源身份
-
-初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 id 和名称。
-
-```json
-{
-  "schemaVersion": 1,
-  "subject": "resource",
-  "resourceId": "6a9f...",
-  "name": "my-video",
-  "typeCode": "RT006003",
-  "filePath": "video.mp4",
-  "env": "dev"
-}
-```
-
-| 字段 | 说明 |
-|---|---|
-| `subject` | 本期恒为 `resource`。 |
-| `typeCode` | 普通资源是已验证的最终叶子；主题/插件固定为 `RT001` / `RT002`。 |
-| `resourceId` 与 `name` | 绑定后成对出现；未绑定 `init` 身份不应预写。 |
-| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件是构建目录，例如 `dist`；绝对路径与 `..` 越界路径不合法。 |
-| `env` | 非 prod 的已绑定资源会记录 `dev` 或 `test`。 |
-
-这里不保存标题、标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。
-
-## `N.version.json`：未提交工作稿
-
-工作稿始终包含资源 id、资源类型、稿类型（`initial` / `update`）、文件 SHA、分析 SHA、属性、可选配置、依赖及恒为空的兼容字段。它只在资源已创建或 bind 后出现。
-
-```json
-{
-  "schemaVersion": 1,
-  "draftKind": "update",
-  "resourceId": "6a9f...",
-  "resourceTypeCode": "RT006003",
-  "fromVersion": "1.0.0",
-  "fileSha1": "...",
-  "filename": "video.mp4",
-  "analyzedSha1": "...",
-  "description": "下一版说明",
-  "inputAttrs": [],
-  "orphanedInputAttrs": [],
-  "customPropertyDescriptors": [],
-  "dependencies": [],
-  "baseUpcastResources": [],
-  "authExcludedItems": []
-}
-```
-
-主题/插件在这里记录的是 CLI 临时 zip 的 `filename` / SHA1；身份里的 `filePath` 仍是构建目录。普通资源则记录原文件的 `filename` / SHA1。
-
-## `index.json`、`.lock` 与 `.txn.json`
-
-`index.json` 是 `filePath → N` 的查询索引，不是主数据；它与身份不一致时，CLI 以 `N.json` 为准修复。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
-
-需要同时改身份、索引和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
-
-## Git 建议
-
-- 永远忽略 `.freelog/auth`。
-- `N.json` 和版本工作稿不含秘密，适合随工程协作。
-- `N.version.json` 是未提交的工作内容；是否提交由团队协作流程决定，不能把它当成已发版本事实。
-- 不要提交 `.lock`、`.txn.json` 或临时 zip。
+# 本地状态文件参考
+
+本页解释 `.freelog/` 中每个文件的归属与恢复边界，不是手工编辑指南。身份和工作稿使用严格的 `schemaVersion: 1`；不要用旧文件、临时 JSON 或自定义字段替代它们。遇到状态损坏或需要丢弃状态，先看[故障恢复](./06-常见情况与报错.md)。
+
+```text
+my-project/
+  .freelog/
+    auth                    # 非秘密账号选择器；不提交
+    1.json                  # 第 1 份资源身份
+    1.version.json          # 第 1 份未提交工作稿（存在时）
+    index.json              # filePath → 身份编号索引
+    .lock                   # 瞬时写锁
+    .txn.json               # 瞬时跨文件事务；异常中断后供 CLI 前滚恢复
+```
+
+## `N.json`：资源身份
+
+初始化后的普通资源身份只有类型；创建或 bind 成功后才会同时拥有资源 id 和名称。
+
+```json
+{
+  "schemaVersion": 1,
+  "subject": "resource",
+  "resourceId": "6a9f...",
+  "name": "my-video",
+  "title": "我的视频",
+  "typeCode": "RT006003",
+  "filePath": "video.mp4",
+  "env": "dev"
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `subject` | 本期恒为 `resource`。 |
+| `typeCode` | 普通资源是已验证的最终叶子；主题/插件固定为 `RT001` / `RT002`。 |
+| `resourceId` 与 `name` | 绑定后成对出现；`name` 是当前账号命名空间内不可重复的短标识。未绑定 `init` 身份不应预写。 |
+| `title` | 创建、bind 或 `resource sync` 写入的本地展示/选择信息；标题可重复且会变化，不是线上写入依据。旧状态可缺少该字段，选择列表显示“未同步标题”。 |
+| `filePath` | 相对工程根目录、以 `/` 分隔。普通资源是文件路径；主题/插件是构建目录，例如 `dist`；绝对路径与 `..` 越界路径不合法。 |
+| `env` | 非 prod 的已绑定资源会记录 `dev` 或 `test`。 |
+
+这里不保存标签、策略、已发版本、SHA1、`artifactMode` 或秘密凭据；这些信息分别属于平台、工作稿或系统凭据库。标题是唯一例外：它作为可过期的本地选择/展示缓存保存，可由 `resource sync` 更新。
+
+## `N.version.json`：未提交工作稿
+
+工作稿始终包含资源 id、资源类型、稿类型（`initial` / `update`）、文件 SHA、分析 SHA、属性、可选配置、依赖及恒为空的兼容字段。它只在资源已创建或 bind 后出现。
+
+```json
+{
+  "schemaVersion": 1,
+  "draftKind": "update",
+  "resourceId": "6a9f...",
+  "resourceTypeCode": "RT006003",
+  "fromVersion": "1.0.0",
+  "fileSha1": "...",
+  "filename": "video.mp4",
+  "analyzedSha1": "...",
+  "description": "下一版说明",
+  "inputAttrs": [],
+  "orphanedInputAttrs": [],
+  "customPropertyDescriptors": [],
+  "dependencies": [],
+  "baseUpcastResources": [],
+  "authExcludedItems": []
+}
+```
+
+主题/插件在这里记录的是 CLI 临时 zip 的 `filename` / SHA1；身份里的 `filePath` 仍是构建目录。普通资源则记录原文件的 `filename` / SHA1。
+
+## `index.json`、`.lock` 与 `.txn.json`
+
+`index.json` 是 `filePath → N` 的查询索引，不是主数据；它与身份不一致时，CLI 以 `N.json` 为准修复。`.lock` 只在本地写入期间存在，用于阻止两个 CLI 同时修改同一工程。不要在另一个 CLI 仍在运行时删除它。
+
+需要同时改身份、索引和工作稿的操作会短暂写入 `.txn.json`。进程异常中断后，不要手动删改它；下一次对该工程的持锁写操作会先完成事务的前滚恢复。若文件持续存在且每次都恢复失败，保留 `.freelog/` 现场后再排查。
+
+## Git 建议
+
+- 永远忽略 `.freelog/auth`。
+- `N.json` 和版本工作稿不含秘密，适合随工程协作。
+- `N.version.json` 是未提交的工作内容；是否提交由团队协作流程决定，不能把它当成已发版本事实。
+- 不要提交 `.lock`、`.txn.json` 或临时 zip。

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

@@ -1,108 +1,138 @@
-# 按场景操作
-
-先判断资源是否已经在线上存在、是否已经发行过版本、当前工程是否已有 `.freelog/` 身份。不要把 `init`、`create`、`bind` 当成同义词：它们分别是立项、建线上资源壳、接入已有线上资源。
-
-所有例子以 `--env dev` 为例；多资源工程中，每一条涉及某资源的命令都补上该资源已记录的 `--file <path>`。
-
-## 先选入口
-
-| 你现在的情况 | 从这里开始 | 不要做 |
-|---|---|---|
-| 空目录，普通文件资源还未上线 | `init --type <最终叶子>`，再 `create` | 把父类型或类型名称交给 `--type`。 |
-| 已有普通文件工程、没有线上资源 | `create --type <最终叶子> --file <文件>` | 为了建壳强行覆盖工程执行 `init`。 |
-| 空目录，要从官方主题/插件模板开始 | `init theme|widget <目录> --template <id>` | 选择资源类型，或手工复制本地模板。 |
-| 已有主题/插件工程、没有线上资源 | `create --type RT001|RT002 --file <dist|build>` | 对非空工程再执行 `init`，或自己先打 zip。 |
-| 线上有自己的壳但没有发行版本 | `bind --file <文件或构建目录>`，再 `create-version` | 再次 `create`。 |
-| 线上已有发行版本 | `bind --file <文件或构建目录>`，再 `draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
-| 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
-| 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
-
-## 场景一：从空目录发行普通文件首版
-
-```powershell
-freelog-cli login --env dev
-freelog-cli init . --type RT006003 --yes --env dev
-freelog-cli create --title "我的视频" --name my-video --file video.mp4 --yes --env dev
-freelog-cli create-version --prepare --file video.mp4 --env dev
-freelog-cli version show --local --env dev
-freelog-cli create-version --yes --file video.mp4 --env dev
-```
-
-不知道最终叶子 code 时，先运行 `type search <关键词>`，或省略 `init` 的 `--type` 进入层级、搜索和直接输入 code 的选择器。首版固定为 `1.0.0`。
-
-## 场景二：已有普通文件工程，创建首版资源
-
-不需要也不能为了写状态覆盖已有工程。登录后直接明确类型与文件：
-
-```powershell
-freelog-cli login --env dev
-freelog-cli create --title "已有视频" --name existing-video --type RT006003 --file video.mp4 --yes --env dev
-freelog-cli create-version --file video.mp4 --prepare --env dev
-freelog-cli create-version --file video.mp4 --yes --env dev
-```
-
-`create` 只登记文件路径并创建资源壳；文件不存在、为空、过大或解析失败时，会在 `create-version` 停止，线上不会出现半个版本。
-
-## 场景三：从官方模板创建主题或插件并发行首版
-
-```powershell
-freelog-cli login --env dev
-freelog-cli template list
-freelog-cli init theme my-theme --template vite-react-ts --yes
-freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
-# 在工程自己的流程中运行构建，得到 dist/
-freelog-cli create-version --cwd my-theme --file dist --prepare --env dev
-freelog-cli create-version --cwd my-theme --file dist --yes --env dev
-```
-
-插件把 `theme` 换为 `widget`；它的固定类型是 `RT002`，主题是 `RT001`。模板初始化后的建壳不传 `--type`，固定类型已在身份中。
-
-## 场景四：已有主题或插件工程，创建首版资源
-
-既有非空工程不运行 `init`，也没有必要补造模板元数据。明确其固定类型和构建目录：
-
-```powershell
-freelog-cli login --env dev
-freelog-cli create --title "已有主题" --name existing-theme --type RT001 --file dist --yes --env dev
-# 自己完成构建后
-freelog-cli create-version --file dist --prepare --env dev
-freelog-cli create-version --file dist --yes --env dev
-```
-
-插件使用 `--type RT002`。`dist` / `build` 是目录；CLI 仅在提交前临时压缩其中内容，绝不把 zip 写进 `filePath`。
-
-## 场景五：自己的线上资源未发行，在本地补接后发首版
-
-```powershell
-freelog-cli login --env dev
-freelog-cli bind <resourceId或username/name> --file video.mp4 --env dev
-freelog-cli create-version --file video.mp4 --prepare --env dev
-freelog-cli create-version --file video.mp4 --yes --env dev
-```
-
-主题/插件把 `video.mp4` 换成 `dist` 或 `build`。`bind` 会从平台读取类型；对主题/插件，没有已记录目录时 `--file` 是必填项。
-
-## 场景六：自己的线上资源已发行，在本地接入并发新版本
-
-```powershell
-freelog-cli login --env dev
-freelog-cli bind <resourceId或username/name> --file dist --env dev
-freelog-cli version draft pull --env dev
-# 编辑属性、可选配置、依赖或说明
-freelog-cli update-version --file dist --bump patch --yes --env dev
-```
-
-普通文件把 `dist` 换成文件。使用 `--version 1.1.0` 也可以代替 `--bump patch`；两者不能同时传。若已有本地工作稿，先 `version show --local`，决定继续、`version draft discard`，或用 `version draft pull --yes` 明确覆盖。
-
-## 场景七：构建路径、工作稿或多资源工程发生变化
-
-- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --file dist --artifact build`。只更新记录，不上传也不提交。
-- 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
-- 一个工程中有多份身份：`create`、`bind`、`create-version`、`update-version`、`version draft pull` 都传对应的已记录 `--file`；发版要换产物时再传 `--artifact`。不传时 CLI 会停止，不会猜第一份。
-- 想从另一线上版本重新开始：`version draft pull --version <版本> --yes`；这会覆盖当前未提交工作稿，先看命令打印的摘要。
-
-## 场景八：版本表单、依赖和上线
-
-首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。详情见 [版本工作稿](./04-版本工作稿.md)。
-
-展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
+# 按场景操作
+
+本页是决策入口：先判断资源是否已经在线上存在、是否已经发行过版本、当前工程是否已有 `.freelog/` 身份，再复制对应路径。不要把 `init`、`create`、`bind` 当成同义词：它们分别是立项、建线上资源壳、接入已有线上资源。需要解释命令语义时回到专题页；需要完整参数和副作用时查[完整命令参考](./10-命令参考.md)。
+
+所有例子以 `--env dev` 为例；多资源工程中，每一条涉及某资源的命令都补上 `--resource <selector>`；产物始终用 `--artifact <path>`。
+
+## 先选入口
+
+| 你现在的情况 | 从这里开始 | 不要做 |
+|---|---|---|
+| 空目录，普通文件资源还未上线 | `init --type <最终叶子>`，再 `create` | 把父类型或类型名称交给 `--type`。 |
+| 已有普通文件工程、没有线上资源 | `create --type <最终叶子> --artifact <文件>` | 为了建壳强行覆盖工程执行 `init`。 |
+| 空目录，要从官方主题/插件模板开始 | `init theme|widget <目录> --template <id>` | 选择资源类型，或手工复制本地模板。 |
+| 已有主题/插件工程、没有线上资源 | `create --type RT001|RT002 --artifact <dist|build>` | 对非空工程再执行 `init`，或自己先打 zip。 |
+| 线上有自己的壳但没有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `create-version` | 再次 `create`。 |
+| 线上已有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `version draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
+| 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
+| 同一工程有多份资源身份 | 先用 `status --resource file:N.json` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact`、标题或状态文件顺序猜测目标。 |
+| 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
+
+## 场景一：从空目录发行普通文件首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli init . --type RT006003 --yes --env dev
+freelog-cli create --title "我的视频" --name my-video --artifact video.mp4 --yes --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli version show --local --env dev
+freelog-cli create-version --yes --env dev
+```
+
+不知道最终叶子 code 时，先运行 `type search <关键词>`，或省略 `init` 的 `--type` 进入层级、搜索和直接输入 code 的选择器。首版固定为 `1.0.0`。
+
+## 场景二：已有普通文件工程，创建首版资源
+
+不需要也不能为了写状态覆盖已有工程。登录后直接明确类型与文件：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --title "已有视频" --name existing-video --type RT006003 --artifact video.mp4 --yes --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+`create` 只登记文件路径并创建资源壳；文件不存在、为空、过大或解析失败时，会在 `create-version` 停止，线上不会出现半个版本。
+
+## 场景三：从官方模板创建主题或插件并发行首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli template list
+freelog-cli init theme my-theme --template vite-react-ts --yes
+freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
+# 在工程自己的流程中运行构建，得到 dist/
+freelog-cli create-version --cwd my-theme --prepare --env dev
+freelog-cli create-version --cwd my-theme --yes --env dev
+```
+
+插件把 `theme` 换为 `widget`；它的固定类型是 `RT002`，主题是 `RT001`。模板初始化后的建壳不传 `--type`，固定类型已在身份中。
+
+## 场景四：已有主题或插件工程，创建首版资源
+
+既有非空工程不运行 `init`，也没有必要补造模板元数据。明确其固定类型和构建目录：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
+# 自己完成构建后
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+插件使用 `--type RT002`。`dist` / `build` 是目录；CLI 仅在提交前临时压缩其中内容，绝不把 zip 写进 `filePath`。
+
+## 场景五：自己的线上资源未发行，在本地补接后发首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --artifact video.mp4 --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+主题/插件把 `video.mp4` 换成 `dist` 或 `build`。`bind` 会从平台读取类型；对主题/插件，没有已记录目录时须传 `--artifact`。
+
+## 场景六：自己的线上资源已发行，在本地接入并发新版本
+
+```powershell
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --artifact dist --env dev
+freelog-cli version draft pull --env dev
+# 编辑属性、可选配置、依赖或说明
+freelog-cli update-version --bump patch --yes --env dev
+```
+
+普通文件把 `dist` 换成文件。使用 `--version 1.1.0` 也可以代替 `--bump patch`；两者不能同时传。若已有本地工作稿，先 `version show --local`，决定继续、`version draft discard`，或用 `version draft pull --yes` 明确覆盖。
+
+## 场景七：构建路径、工作稿或多资源工程发生变化
+
+- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --resource file:N.json --artifact build`。只更新记录，不上传也不提交。
+- 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
+- 一个工程中有多份身份：`create-version`、`update-version`、`version draft pull` 等既有资源操作传对应的 `--resource`；不传时 TTY 可选择，非交互会停止，不会猜第一份。`create`、`bind` 例外：它们可在没有未绑定状态时新增 `N.json`；要接续某份未绑定状态时传 `--resource 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)。
+
+展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
+
+## 场景九：只修改一个已发布版本的说明
+
+不需要建立工作稿，也不会产生新版本号：
+
+```powershell
+freelog-cli version show --version 1.1.0 --env dev
+freelog-cli version description --version 1.1.0 --description "补充发布说明" --env dev
+```
+
+这与 `version draft description` 不同：后者只修改尚未提交的更新稿。多资源工程在两条命令上都传相同的 `--resource file:N.json`。
+
+## 场景十：更新稿过期，选择重建或继续旧底
+
+线上 latest 已变化而本地稿仍基于旧版本时，通常重建最安全：
+
+```powershell
+freelog-cli version show --local --env dev
+freelog-cli version draft pull --yes --env dev
+freelog-cli update-version --bump patch --yes --env dev
+```
+
+只有确认仍需按旧底提交时，才使用 `--reuse-version`，并让它与工作稿来源完全一致：
+
+```powershell
+freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
+```
+
+若工作稿本身不要了，可把前两步改为 `update-version --reset --bump patch --yes`；它会删除当前稿后重新建立，不要把它当成无损刷新。

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

@@ -0,0 +1,95 @@
+# 完整命令参考
+
+本页是发布包内的命令索引：列出当前 CLI 的全部公开命令、何时使用以及它会不会改变线上资源或本地文件。首次完成任务请优先看[按场景操作](./09-按场景操作.md)；执行已知命令、编写脚本或排查影响时以本页为准。
+
+所有示例省略 `freelog-cli` 前缀后的公共参数。推荐每次显式传 `--env dev` 或 `--env test`；多资源工程的**常规单资源命令**要传 `--resource file:N.json`（交互终端可选择）。`create` / `bind` 可新增或接续身份，`resource sync` 不传选择器时批量同步标题，它们不是这条规则的反例而是不同的生命周期语义。`--yes` 只跳过交互确认，不会放宽校验。详细选择规则见[首页](./README.md#多资源工程先选身份再给产物)。
+
+## 发现命令与获得帮助
+
+```powershell
+freelog-cli --help
+freelog-cli version --help
+freelog-cli policy template apply --help
+freelog-cli --cli-version
+```
+
+顶层 `--help` 会打印安装包内本手册的绝对路径；子命令 `--help` 显示该命令当前支持的选项。脚本不要从帮助文本解析业务结果；需要稳定错误结构时使用 `--json`。
+
+## 账号、工程和类型
+
+| 命令 | 何时使用 | 影响 |
+|---|---|---|
+| `login [--global]` | 登录当前工作区；脚本可用 `--login-name`、`--password-stdin --yes`。 | 将秘密写入系统凭据库，并写入工作区或全局选择器。 |
+| `logout [--global]` | 切换账号或清除本地登录选择。 | 只清选择器及明确孤立的凭据；不删除工程或线上资源。 |
+| `init [dir] [--type <叶子类型>]` | 在空目录创建普通资源的本地身份。 | 新建未绑定 `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 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`；不上传、不提交。 |
+
+`--name` 是当前账号命名空间中不可重复、创建后不可改的短标识；`--title` 是可修改且可重复的展示名称。创建后的标题用 `update --title` 修改；本地标题用 `resource sync` 对齐。
+
+## 版本：查看、工作稿与提交
+
+| 命令 | 何时使用 | 影响 |
+|---|---|---|
+| `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 draft pull`；首版要先 `create-version --prepare`。依赖在非交互模式还须明确 `--policy-id <策略ID> --yes`，CLI 不会代选对方策略。
+
+## 展示信息、策略与上下架
+
+| 命令 | 何时使用 | 影响 |
+|---|---|---|
+| `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` | 暂停线上可用状态。 | 只下架，不删除版本、策略、资源或本地文件。 |
+
+## 脚本最小安全模板
+
+脚本必须显式选择环境；工程有多份状态时也必须显式选择资源。先做只读检查，再执行写操作：
+
+```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
+```
+
+需要机器可读错误时追加 `--json`。不要在脚本中用 `title:<标题>` 作为唯一选择器，也不要依赖交互式选择。