@freelog-cli/cli2 0.5.0 → 0.5.2

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

@@ -0,0 +1,83 @@
+# 快速开始：发行一个普通文件
+
+本页是第一次使用的可执行教程：把 `video.mp4` 作为普通资源发成首版 `1.0.0`。以下示例以 dev 环境为例；不要把真实密码写进命令行参数或脚本文件。已有工程、已有线上资源或主题/插件不要套用本页，先到[按场景操作](./09-按场景操作.md)选入口。
+
+## 1. 安装、确认与登录
+
+CLI 要求 Node.js 20 或更高版本。尚未安装时，先执行：
+
+```powershell
+node --version
+npm install --global @freelog-cli/cli2
+freelog-cli --cli-version
+```
+
+如果 `freelog-cli` 找不到，重新打开终端；仍无法使用时，检查 npm 全局可执行目录是否已加入 `PATH`。以下统一写作 `freelog-cli`。
+
+首次使用推荐在交互终端直接登录；CLI 会安全地隐藏密码输入：
+
+```powershell
+freelog-cli login --env dev
+```
+
+```powershell
+# 登录成功后，可查看安装包内自带的完整手册路径
+freelog-cli --help
+```
+
+自动化或非交互终端需要同时传 `--login-name`、`--password-stdin`、`--yes`；由 CI 的保密输入把密码写入标准输入，绝不把密码写进命令行、脚本或环境变量。登录成功后，工程只保存账号选择器；token、Cookie 等秘密由系统凭据库保存。
+
+## 2. 建立工程身份
+
+普通资源要先登录，因为资源类型来自平台的当前类型树。已知最终叶子 code 时可直接初始化：
+
+```powershell
+freelog-cli init . --type RT006003 --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 . --env dev
+```
+
+`init` 只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
+
+上一步已在当前目录写入 `.freelog/auth` 也可以再执行 `init .`：CLI 会保留这一个账号选择器，并拒绝覆盖任何其它已有工程内容或资源身份。
+
+## 3. 创建线上资源壳
+
+```powershell
+freelog-cli create `
+  --title "我的视频" `
+  --name my-video `
+  --artifact video.mp4 `
+  --yes --env dev
+```
+
+因为工程已经通过 `init` 记录了类型，这里不必重复传 `--type`；CLI 会在提交前重新验证该类型。没有先 `init` 时也可以直接创建，但必须额外传入 `--type <最终叶子 code>`。
+
+此步只创建资源壳并回写 `resourceId`、`name`、环境和文件路径，**不会上传视频**。
+
+## 4. 上传、检查并提交首版
+
+最稳妥的做法是先准备工作稿：
+
+```powershell
+freelog-cli create-version --prepare --artifact video.mp4 --env dev
+freelog-cli version show --local --env dev
+freelog-cli create-version --yes --artifact video.mp4 --env dev
+```
+
+第一条会校验文件、计算 SHA1、上传并等待平台解析，但不提交版本。确认本地工作稿后，最后一条会再次从当前文件校验、上传和解析，再提交固定首版号 `1.0.0`。提交成功会删除工作稿；失败或中断会保留工作稿以便继续处理。
+
+## 5. 下一步
+
+- 要增加属性、可选配置或依赖：看 [版本工作稿](./04-版本工作稿.md)。
+- 要发布后续版本：看 [日常操作](./02-日常路径.md#发布新版本)。
+- 要给资源配置策略并上架：看 [资源管理](./05-资源管理.md)。
+- 要发行主题或插件：不要照本页的 `init`，改看 [主题与插件](./03-主题与插件.md)。
+- 要查任一命令的全部前置条件和影响：看 [完整命令参考](./10-命令参考.md)。

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

@@ -0,0 +1,92 @@
+# 资源生命周期：创建、接入与发版
+
+本页解释资源从“还不存在”到“后续持续发版”的日常路径。它回答该用 `init`、`create` 还是 `bind`，以及首版和更新版为何是两条命令。版本工作稿的字段编辑、恢复细节见[版本工作稿](./04-版本工作稿.md)；按你当前实际处境直接执行的方案见[按场景操作](./09-按场景操作.md)。
+
+## 创建新资源
+
+```text
+login → init（可选）→ create → create-version → 配策略 / 上架（可选）
+```
+
+| 阶段 | 命令 | 结果 |
+|---|---|---|
+| 选类型并立项 | `init [dir] --type <leaf-code>` | 写未绑定本地身份，不创建线上资源。 |
+| 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。 |
+| 仅准备首版 | `create-version --prepare` | 上传并解析文件，留下首版工作稿。 |
+| 提交首版 | `create-version --yes` | 提交 `1.0.0` 并清理成功的工作稿。 |
+
+`create-version` 只适用于尚无线上版本的资源。`--prepare` 与 `--yes` 都会以当前产物上传并等待解析；前者只保存可编辑的工作稿，后者才提交固定的 `1.0.0`。已经有版本时它会停止并提示使用 `update-version`。
+
+## 发布新版本
+
+```text
+version draft pull → 改工作稿 → update-version
+```
+
+先把已发版本作为新版本的底：
+
+```powershell
+freelog-cli version draft pull --version 1.0.0 --env dev
+freelog-cli version show --local --env dev
+freelog-cli update-version --version 1.1.0 --yes --env dev
+```
+
+也可以让 CLI 按规则递增版本号：
+
+```powershell
+freelog-cli update-version --bump patch --yes --env dev
+freelog-cli update-version --bump minor --yes --env dev
+freelog-cli update-version --bump major --yes --env dev
+```
+
+规则如下：
+
+- `--version` 必须是合法 semver，且严格大于提交瞬间的线上 latest。
+- `--version` 与 `--bump` 不能同时使用。
+- 提交更新版时，必须同时明确提供 `--version <新号>` 或 `--bump <方向>`，并带 `--yes`；CLI 不会擅自猜测版本号或执行提交。
+- `update-version` 不支持 `--prepare`；需要分阶段编辑时用 `version draft pull` 建稿。
+- 发版前改文件可附 `--artifact <文件或构建目录>`；成功确认后该路径会回写身份记录。多资源工程以 `--resource <selector>` 选择身份。
+
+## 接入已有资源
+
+当资源已在网页、另一台机器或别的工程中创建时，不要再运行 `create`：
+
+```powershell
+freelog-cli bind <resourceId 或 username/name> --artifact video.mp4 --env dev
+```
+
+`bind` 会读取平台详情，且只接入当前账号拥有的单资源。它不会下载文件、拉取版本工作稿或修改线上资源。
+
+接入后按线上是否已有版本分流：
+
+| 线上状态 | 下一步 |
+|---|---|
+| 没有 `latestVersion` | `create-version --prepare` 后编辑并 `create-version --yes`，发行首版。 |
+| 已有 `latestVersion` | `version draft pull`，编辑工作稿后以 `update-version --version` 或 `--bump` 发新号。 |
+
+主题/插件的 `<path>` 必须是构建目录（`dist` / `build`）；在尚无目录记录的既有项目中，`bind --artifact` 必填。
+
+- 已有相同资源 id 时，重复 `bind` 是幂等的。
+- 要将一份本地身份换绑到另一个资源，使用 `bind <id> --force --yes`；旧工作稿会被清理。
+
+## 查看与只读操作
+
+```powershell
+freelog-cli status --env dev
+freelog-cli version show --env dev
+freelog-cli version show --version 1.0.0 --env dev
+freelog-cli version show --local --env dev
+```
+
+前三条读取线上事实；`version show --local` 只读取未提交工作稿。它们不会覆盖、提交或删除工作稿。
+
+## `--artifact` 的含义
+
+一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时先传 `--resource file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`；不传时交互终端列出完整信息供选择，非交互会列出可复制的 `file:N.json` 示例并停止。标题可重复且会变化，脚本优先使用稳定的 `file:` 或 `id:`。`create` / `bind` 用 `--artifact` 记录将来默认使用的路径，路径可以暂时不存在；`create-version` / `update-version` 用它指定本次文件或目录，发版产物必须真实存在：
+
+| 场景 | 传入的路径 |
+|---|---|
+| 普通资源 `--artifact` | 一个实际文件。目录会被拒绝。 |
+| 主题 / 插件 `--artifact` | 一个构建产物目录，例如 `dist` 或 `build`。zip 文件会被拒绝。 |
+
+发版未传 `--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

@@ -0,0 +1,124 @@
+# 主题与插件
+
+本页只解释主题/插件相对普通文件的差异：模板初始化、固定类型、构建目录与临时压缩。它们仍是“一条资源一次一条命令”，并与普通文件共用登录、建壳、版本工作稿、属性、依赖、策略、管理和上下架流程；可选配置是否可编辑始终由当前类型详情决定。完整生命周期见[资源生命周期](./02-日常路径.md)，准确命令与参数见[完整命令参考](./10-命令参考.md)。
+
+| 项目 | 主题 | 插件 | 普通文件资源 |
+|---|---|---|---|
+| 初始化 | `init theme` | `init widget` | `init --type <最终叶子>` |
+| 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
+| 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
+| 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
+| 发版输入 | 构建产物目录 | 构建产物目录 | 一个普通文件 |
+| 上传前处理 | CLI 临时打 zip | CLI 临时打 zip | 直接上传原文件 |
+
+## 从线上模板创建工程
+
+先查看 CLI 固定的线上模板清单：
+
+```powershell
+freelog-cli template list
+```
+
+推荐先登录，再创建主题或插件工程：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli init theme my-theme --template vite-react-ts --yes
+freelog-cli init widget my-widget --template vite-vue-ts --yes
+```
+
+`init theme` / `init widget` 本身不需要登录，因为类型固定；但先登录能使随后 `create --cwd <工程>` 直接复用同一账号。它们从固定版本的线上 npm 模板包下载并只复制包内 `template/` 内容。CLI 不从 `packages/templates/` 复制，也不会执行模板脚本、渲染项目名/版本、安装依赖或执行构建。
+
+成功后会生成：
+
+```text
+my-theme/
+  .freelog/1.json             # typeCode=RT001，filePath=dist
+  ...模板文件
+```
+
+本期不保存模板元数据，也不渲染占位符。构建目录始终记录在 `N.json.filePath`。
+
+## 接入已有主题或插件项目
+
+非空的既有项目不能再运行 `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
+```
+
+若线上资源已经存在，先 `bind`。它是否已有发行版本决定后续路径：
+
+```powershell
+# 线上还没有 latestVersion：接入后发行首版
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --artifact dist --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+```powershell
+# 线上已有 latestVersion：接入、拉稿并提交新版本
+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
+```
+
+不要在已发行资源上再运行 `create-version`，也不要在没有发行版本的资源上运行 `draft pull` / `update-version`。
+
+主题/插件既有项目路径都会把 `dist` / `build` 记录为目录，并在发版时临时压缩；不会补造元数据，也不会覆盖你的源码。
+
+## 创建主题或插件资源壳
+
+初始化只建立本地工程，仍要登录并创建线上资源：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
+```
+
+不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
+
+## 先自行得到构建产物
+
+CLI 不运行包管理器或构建命令。你需要在工程自己的开发流程中产生 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
+
+```powershell
+freelog-cli version set --cwd my-theme --artifact build
+```
+
+这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
+
+## 发布版本：传目录，不传 zip
+
+```powershell
+freelog-cli create-version --cwd my-theme --prepare --env dev
+freelog-cli version show --cwd my-theme --local --env dev
+freelog-cli create-version --cwd my-theme --yes --env dev
+```
+
+对于 `RT001` / `RT002`，CLI 会把 `dist` 的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。临时 zip 无论成功或失败都会删除，不写入工程，也不写入 `N.json` 或工作稿。
+
+以下输入会停止：
+
+| 输入 | 结果 |
+|---|---|
+| `dist` 不存在 | 要求先生成构建产物。 |
+| 空目录 | 要求先生成实际文件。 |
+| 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
+| 一个 `.zip` 或普通文件 | 拒绝；主题和插件只能交构建目录。 |
+
+后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；只要传入的仍是构建目录，CLI 会重新生成临时 zip。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
+
+## 这不是两套版本系统
+
+主题/插件和普通资源都使用同一份 `N.version.json` 工作稿，版本号规则、依赖签约规则、属性校验、成功清稿和失败保留规则完全一致；可选配置仅在类型详情允许时可用。唯一的文件层差异是：
+
+- 普通资源的 `filePath` 指向文件，文件 SHA1 即上传文件的 SHA1；
+- 主题/插件的 `filePath` 指向目录，文件 SHA1 与 `filename` 指向 CLI 临时 zip 的结果。
+
+因此不要手工把 zip 记进 `filePath`，也不要因为主题是目录而另建一套版本缓存。

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

@@ -0,0 +1,108 @@
+# 版本工作稿
+
+本页是“尚未提交的下一版本”专题。工作稿是 `.freelog/N.version.json`：一份已绑定资源的、尚未提交的下一版本内容。它保存文件摘要、属性、可选配置、依赖和更新版描述。只想决定首版/更新版该走哪条路径，先看[资源生命周期](./02-日常路径.md)；想查精确子命令和参数，看[完整命令参考](./10-命令参考.md)。
+
+工作稿只能属于已 `create` 或 `bind` 的资源。未绑定工程不能先手工攒版本稿；请先创建或接入资源。
+
+| 要做什么 | 命令 | 是否提交线上版本 |
+|---|---|---|
+| 看线上版本 | `version show [--version <ver>]` | 否 |
+| 看本地工作稿 | `version show --local` | 否 |
+| 从已发版本建立更新稿 | `version draft pull [--version <ver>]` | 否 |
+| 准备首版稿 | `create-version --prepare` | 否 |
+| 编辑稿 | `version attr` / `option` / `dep` / `version draft description` | 否；依赖签约是独立平台动作 |
+| 丢弃稿 | `version draft discard` | 否 |
+| 提交 | `create-version --yes` / `update-version --version <ver> --yes` | 是 |
+| 改已发布版本的说明 | `version description --version <ver> --description <文本>` | 是；仅更新该已发版本说明 |
+
+## 首版工作稿
+
+资源还没有任何已发版本时：
+
+```powershell
+freelog-cli create-version --prepare --env dev
+freelog-cli version show --local --env dev
+freelog-cli create-version --yes --env dev
+```
+
+首版号固定为 `1.0.0`，首版描述为空。`create-version` 成功后删除工作稿；网络、解析或提交失败时保留它。
+
+## 更新工作稿
+
+已有版本时，以线上版本为底建立稿：
+
+```powershell
+freelog-cli version draft pull --version 1.0.0 --env dev
+freelog-cli version draft description --description "本次更新说明" --env dev
+freelog-cli update-version --version 1.1.0 --yes --env dev
+```
+
+已有本地稿时，`version draft pull` 默认不会覆盖。明确要重来时使用 `--yes`；命令会打印将被覆盖的来源、文件和条目摘要。不要通过修改 JSON 中的 `fromVersion` 换底，应该重新执行 `draft pull`。
+
+## 两种“版本说明”不要混用
+
+```powershell
+# 已有线上版本：修改尚未提交的更新稿说明
+freelog-cli version draft description --description "本次更新说明" --env dev
+
+# 已发布版本：直接修改该版本的线上说明，不创建新版本
+freelog-cli version description --version 1.1.0 --description "补充发布说明" --env dev
+```
+
+前者只作用于更新工作稿，且不会发版；后者不读取或修改工作稿，直接更新指定已发版本。想改首版或任一历史版本的线上说明时用后者。
+
+## 编辑属性和可选配置
+
+```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 option add "名称=主题 键=theme 方式=文本 默认=dark"
+freelog-cli version option set "键=theme 默认=light"
+freelog-cli version option rm theme
+freelog-cli version option list
+```
+
+可选配置是否可用由资源类型详情的 `supportOptionalConfig` 决定；当前类型不支持时，所有 `version option` 写操作都会停止。属性和配置的键创建后不可改；需要改键时删掉后重新添加。命令会在写入前显示预览，`--yes` 只跳过确认，不跳过字段校验。
+
+## 编辑依赖
+
+```powershell
+freelog-cli version dep add <resourceId> --range ^1.0.0
+freelog-cli version dep range <resourceId> --range ^1.1.0
+freelog-cli version dep rm <resourceId>
+freelog-cli version dep list
+```
+
+对方资源尚未授权时，交互模式会列出所有可签约且启用的策略供选择。脚本模式必须明确指定策略：
+
+```powershell
+freelog-cli version dep add <resourceId> --range ^1.0.0 --policy-id <policyId> --yes
+```
+
+CLI 列出的是对方资源的全部启用策略，不按免费/付费筛选。它以平台 `batchAuth` 返回的 `isAuth` 判断是否已授权；签约成功后才把依赖写入工作稿。支付、合约查询和上抛不属于本期 CLI，不能用它们推断授权状态。
+
+## 文件变化与恢复
+
+发版总是以当前存在的本地文件或构建目录为准；不能用旧工作稿 SHA1 代替丢失文件。换文件时在 `create-version` / `update-version` 上给新的 `--artifact`。一个工程有多份资源时，先用 `--resource <selector>` 选中身份，再用 `--artifact <新路径>`；普通资源给文件，主题/插件给构建目录。新脚本不要使用 `--file`。
+
+不要手工改 `N.version.json`。该文件有严格 schema，损坏、旧格式或身份不一致时 CLI 会保留原文件并停止；可明确丢弃工作稿，或从线上版本重新 `draft pull`。
+
+## 确认丢稿后的快捷重来
+
+优先使用显式步骤，因为它最容易检查：`version draft discard` 后再执行 `create-version --prepare` 或 `version draft pull`。如果确认当前稿完全不要，也可让发行命令在同一次操作中重置：
+
+```powershell
+# 无已发版本：删除首版稿，重新准备
+freelog-cli create-version --reset --prepare --env dev
+
+# 已有版本：删除更新稿，按 latest 重拉并提交新号
+freelog-cli update-version --reset --bump patch --yes --env dev
+
+# 工作稿本来以 1.0.0 为底，明确按该底提交，而非最新版本
+freelog-cli update-version --reuse-version 1.0.0 --version 1.1.0 --yes --env dev
+```
+
+`--reset` 会在后续准备、线上检查或提交之前立即删除选中资源的工作稿；即使后续步骤失败，旧稿也不会恢复。因此默认优先用可检查的两步：先 `version show --local`，再 `version draft discard`，确认成功后才执行下一条命令。只有已确认资源、命令路径和 `--resource`（多资源工程）都正确时，才使用 `--reset`。`--reuse-version` 不会重写工作稿，它只声明本次提交认可的线上底，必须与工作稿 `fromVersion` 一致。

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

@@ -0,0 +1,69 @@
+# 资源管理
+
+本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
+
+## 查看现状
+
+```powershell
+freelog-cli status --env dev
+freelog-cli version show --env dev
+freelog-cli version show --version 1.0.0 --env dev
+freelog-cli policy list --env dev
+```
+
+`status` 汇总本地身份、是否存在工作稿和线上 latest；`version show` 与 `policy list` 读取平台当前结果。若只想看本地未交内容，用 `version show --local`。
+
+## 修改展示信息
+
+```powershell
+freelog-cli update --title "新标题" --yes --env dev
+freelog-cli update --intro "一句话简介" --tags "教程,视频" --yes --env dev
+freelog-cli update --cover "<封面值>" --yes --env dev
+```
+
+`update` 只会发送明确给出的字段：标题、简介、封面和标签。它不会提交新版本、修改资源标识或上下架状态。
+
+- 标题最多 100 个字符，简介最多 200 个字符。
+- 标签最多 20 个，每个最多 20 个字符；不能重复或包含 `#`。
+- `--yes` 且没有任一修改字段会失败，不发送空更新。
+
+## 同步本地标题
+
+资源标题可能在网页、另一台机器或其它工具中修改。多资源工程用标题选择时，应显式同步，而不是猜测旧标题：
+
+```powershell
+# 当前环境的全部已绑定资源；这是唯一的批量资源命令
+freelog-cli resource sync --env dev
+
+# 只同步一份资源
+freelog-cli resource sync --resource id:<resourceId> --env dev
+```
+
+同步只读取平台资源详情并回写对应 `N.json.title`；不会改版本工作稿、产物路径或线上资源。部分失败时成功项已安全写入，失败项保持原值，命令以非零退出并列出失败的状态文件。`update --title` 成功时会立即回写当前选中身份的标题，无需再同步。
+
+## 管理授权策略
+
+```powershell
+freelog-cli policy list --env dev
+freelog-cli policy template list --page 1 --page-size 20 --env dev
+freelog-cli policy template apply <templateId> --yes --env dev
+freelog-cli policy apply --from-file .\free-policy.json --yes --env dev
+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 apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
+
+## 上架与下架
+
+```powershell
+freelog-cli validate --for online --env dev
+freelog-cli online --env dev
+freelog-cli offline --env dev
+```
+
+上架前必须已有至少一个已发版本和一条启用策略。`validate --for online` 只检查并说明缺失项；`online` 会再次检查后才写线上状态。`offline` 只改变可用状态，不删除资源、版本、策略、身份或工作稿。
+
+如果账号不是资源 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

@@ -0,0 +1,37 @@
+# 故障恢复与常见报错
+
+本页按“看到什么 → 为什么 → 下一步”处理失败；它不是命令清单。CLI 的错误不会自动丢弃工作稿或覆盖工程，只有用户显式执行 `discard` / `--reset` 才会丢稿。脚本调用可加 `--json` 获得稳定的 `{code,message}` 结构。找不到要执行的命令时先查[完整命令参考](./10-命令参考.md)。
+
+| 看到的情况 | 原因 | 应对方式 |
+|---|---|---|
+| `prod 暂未开放` | 未显式选择联调环境。 | 为本次命令加 `--env dev` 或 `--env test`。 |
+| `请先 login` | 当前目录向上没有可用账号选择器。 | 在工程运行 `login --env ...`，或使用全局账号选择器。 |
+| 凭据环境不一致 / 凭据库中不存在凭据 | 工作区选择器不能用于本次环境，或系统凭据被清除。 | `logout` 后在同一环境重新 `login`；不要手改 selector。 |
+| `目标目录不是空目录，拒绝覆盖` | `init` 不会合并或覆盖已有工程。 | 选新目录，或先人工整理目录内容。已先 `login` 的当前目录例外：只存在 `.freelog/auth` 时可执行 `init .`，该选择器会被保留。 |
+| `请选择资源类型` | 普通资源没有已验证类型，且未传 `--type`。 | 用 `type search` / 交互式 `init` 选择最终叶子，或传精确 code。 |
+| 主题/插件类型固定 | 在模板工程创建壳时试图以不同 `--type` 覆盖 `RT001` / `RT002`。 | 移除 `--type`；模板工程会使用记录的固定类型。 |
+| `当前工程有多份资源状态；请使用 --resource 指定资源` | 一个工程存在多份资源身份，CLI 无法猜测目标。 | 交互终端从显示的文件名、标题、短标识、资源 ID、类型、产物路径和工作稿状态中选择；非交互错误会列出可复制的 `file:N.json`，也可传 `id:<资源ID>`、`name:<标识符>`。 |
+| `本地文件不在` / `请 --artifact 指定本地文件或目录` | 记录的文件或构建目录不存在。 | 生成或找到实际产物，再传 `--artifact`；多资源时另传 `--resource` 选身份，不能复用旧 SHA1。 |
+| `不支持文件夹` | 普通资源给了目录。 | 传一个实际文件。 |
+| `主题/插件请指定构建产物目录，不要自己打 zip` | 主题/插件给了 zip 或普通文件。 | 传 `dist` / `build` 这类非空构建目录。 |
+| `构建产物是空的` | 目录内没有可压缩文件。 | 先完成工程自己的构建流程。 |
+| 已经有发行版本，请用 `update-version` | 对已有版本的资源调用了 `create-version`。 | 用 `version draft pull` 后运行 `update-version`。 |
+| 还没有发行版本，请先 `create-version` | 对首版资源调用了 `update-version` 或 `draft pull`。 | 使用 `create-version --prepare` 或 `create-version --yes`。 |
+| 工作稿与身份不一致 / 不支持 schemaVersion=1 | 本地工作稿损坏、过期或属于另一资源。 | 保留原文件以便检查；明确 `version draft discard`，或从线上 `draft pull` 重建。 |
+| 工作稿来源不是当前 latest | 线上已有新版本，而本地稿仍基于其它版本。 | 优先检查后用 `version draft pull --yes` 重建；确认要继续使用原底时，在 `update-version` 上明确传匹配的 `--reuse-version <版本>`。 |
+| 想重来但不想手工删 JSON | 当前首版稿或更新稿确认不要。 | 默认先 `version show --local`，再 `version draft discard`，最后执行下一步；`--reset` 会在后续检查前立即丢弃工作稿，仅在已核对资源和命令路径后使用。 |
+| `当前类型不支持可选配置` | 类型详情不允许可选配置；主题并不天然支持它。 | 不执行 `version option`；只编辑当前类型允许的字段。 |
+| `--yes` 缺少 title / name / type | 脚本模式没有提供必要输入。 | 无工程类型时给 `--type`；已有 init 身份时给 `--title`、`--name` 即可。 |
+| 依赖要求 `--policy-id` | 非交互依赖签约不能替你选择对方策略。 | 先列策略或在交互中选择，再传精确 `--policy-id`。 |
+| `上架须已有版本` / `上架须至少一条启用策略` | 上架条件不完整。 | 先发行版本、添加并启用策略，随后重试 `online`。 |
+| 改了版本说明但新版本没有变化 | 使用的是 `version description`。 | 该命令只改已发布版本说明；要写下一版说明应先建更新稿，再用 `version draft description`。 |
+
+## 不要用这些“修复”方式
+
+- 不要只删除 `N.json` 或只删除 `N.version.json`。确需放弃一份本地状态时，先备份，再删除同号的完整状态单元（`N.json` 与 `N.version.json`）；未提交工作稿会永久丢失，之后可在空位重新 `bind`。
+- 不要复制或编辑 `.freelog/auth`；该文件不含可移植秘密，真正的凭据在当前操作系统的凭据库中。
+- 不要手工打 zip 后交给主题/插件发版；CLI 只接收构建目录。
+- 不要在失败后重新运行 `create` 试图补救已有线上壳；先用 `bind` 接入已有资源。
+- 不要用旧命令参数 `--scaffold` 或把 `--resource-type` 当作常规接口；前者不存在，后者仅为弃用兼容。
+
+仍无法判断时，先运行 `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

@@ -0,0 +1,60 @@
+# 环境、登录与凭据
+
+本页说明命令在哪个环境运行、账号如何选择以及秘密存在哪里。它不处理资源身份或版本内容；这些分别见[本地文件参考](./08-本地文件参考.md)和[资源生命周期](./02-日常路径.md)。
+
+## 环境
+
+| 参数 | 用途 | 当前状态 |
+|---|---|---|
+| `--env dev` | 开发联调环境 | 可用 |
+| `--env test` | 测试环境 | 可用 |
+| `--env prod` | 正式环境 | 当前 CLI 明确拦截 |
+
+环境优先级为：命令行 `--env` → `FREELOG_ENV` → `prod`。因此联调时建议每条平台命令都显式带 `--env dev` 或 `--env test`。
+
+## 登录
+
+交互终端：
+
+```powershell
+freelog-cli login --env dev
+```
+
+自动化或非交互终端：
+
+自动化命令必须同时带 `--login-name <账号名>`、`--password-stdin` 和 `--yes`；由 CI 的保密输入将密码写入标准输入。不要用 PowerShell 变量、命令行文本、脚本文件或环境变量保存或传递密码。
+
+登录请求默认 15 秒超时；超时、网络错误、认证失败或系统凭据库不可用时，都不会写入账号选择器。
+
+切换账号或环境必须先退出再登录：
+
+```powershell
+freelog-cli logout --cwd <工程目录>
+freelog-cli login --cwd <工程目录> --env test
+```
+
+默认登录写工作区选择器；`--global` 写机器默认选择器：
+
+```powershell
+freelog-cli login --global --env dev
+freelog-cli logout --global
+```
+
+## 凭据保存位置
+
+| 内容 | 位置 | 是否可提交到 Git |
+|---|---|---|
+| 工作区账号选择器 | 最近的 `.freelog/auth` | 否 |
+| 全局账号选择器 | `~/.freelog/auth-default.json` | 否 |
+| token、Cookie 等秘密 | 操作系统凭据库 | 不适用 |
+
+`.freelog/auth` 和全局文件只保存 schema、环境、用户 id、用户名与凭据库 key；不保存密码、token 或 Cookie。运行命令时，CLI 从 `--cwd` 向上寻找最近的工作区选择器；一旦找到，即使它损坏或环境不符也不会回退到全局账号。
+
+旧式、含 `token` / `cookie` / `iv` 等字段的账号文件不会被解密或迁移。显式 `logout` 清除目标选择器后再 `login`。
+
+## 安全边界
+
+- 不要把密码写成 `--password`、命令行文本、环境变量、JSON 或 Git 文件。
+- 不要复制 `.freelog/auth` 到另一台机器；它不带秘密，另一台机器仍需重新登录。
+- `logout` 只删除账号选择器，不会删除 `.freelog/N.json` 或版本工作稿。
+- 平台返回认证失败时，CLI 停止当前操作；未提交版本稿仍然保留。

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

@@ -0,0 +1,81 @@
+# 本地状态文件参考
+
+本页解释 `.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。