@freelog-cli/cli2 0.5.4 → 0.5.6

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

@@ -44,6 +44,8 @@ freelog-cli type info RT006003 --env dev
 freelog-cli init . --artifact video.mp4 --env dev
 ```
 
+`type list` 和 `type search` 的每一行都是“类型 code + 根 / … / 叶子”的完整路径，不会只显示容易重名的叶子名称。它们固定每页 50 条：交互终端可选择上一页或下一页；脚本环境只显示首页并提示剩余数量，不需要也不支持分页参数。
+
 `type info` 会同时显示该最终叶子是否支持版本可选配置；只有显示“支持”时才可以在工作稿中使用 `version option add/set`。它不表示任意文件都能用于该类型：做可选配置真网验收时，仍要为该类型选择真实可上传的文件。
 
 通用 `init` 必须用 `--artifact` 指向已经存在的本地文件；交互模式只会帮你选类型，不会扫描或猜测文件。它只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。

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

@@ -63,14 +63,14 @@ freelog-cli resource recover --apply --yes --env dev
 
 ```powershell
 freelog-cli policy list --env dev
-freelog-cli policy template list --page 1 --page-size 20 --env dev
+freelog-cli policy template list --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 条），包含带交易事件的模板，不在 CLI 按免费/付费、事件或类型猜测过滤；后端修复后再恢复按类型请求。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板会先由平台重新编译，最终能否写入由平台判定；目前带事件或需要填写时间、金额等参数的模板可能受后端编译契约阻塞，CLI 不猜测转换。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
+`policy list` 只看当前资源已经添加的策略：一次输出全部策略，页头显示完整资源类型链，不分页。当前后端按资源类型筛选模板存在故障，`policy template list` 暂时列出平台返回的**全部**模板（固定每页 20 条；TTY 可上一页/下一页，非 TTY 输出首页和继续提示），包含带交易事件的模板，不在 CLI 按免费/付费、事件或类型猜测过滤；后端修复后再恢复按类型请求。交互执行 `policy template apply` 时可在每页选择、翻页或取消；脚本执行必须提供 `<templateId> --yes`。应用模板会先由平台重新编译，最终能否写入由平台判定；目前带事件或需要填写时间、金额等参数的模板可能受后端编译契约阻塞，CLI 不猜测转换。应用模板或 `policy apply` 都会新增一条**启用**的授权策略，但不会触发支付，也不会自动上架。
 
 `policy apply --from-file` 接受策略文本文件，或包含 `policyName` 与 `policyText` 的 JSON 文件；若文本文件或 JSON 未提供名称，非交互模式还必须传 `--name <策略名>`。策略语义最终由平台校验。
 

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

@@ -15,7 +15,8 @@
 | 线上已有发行版本 | `bind <资源ID或username/name> --artifact <文件或构建目录>`，再 `version draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
 | 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
 | 同一工程有多份资源身份 | 先用 `status --resource id:<资源ID>`、`name:<标识>` 或 `artifact:<文件>` 确认目标，再在后续命令沿用同一 `--resource` | 用 `--artifact` 上传参数、标题或状态文件顺序猜测目标。 |
-| 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
+| 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
+| 创建或管理合集 | 阅读[合集使用教程](./合集/README.md)，以线上已上架单资源作为单品 | 把本地素材、主题工程或单资源工作稿直接当作合集单品。 |
 
 ## 场景一：从空目录发行普通文件首版
 
@@ -123,7 +124,7 @@ freelog-cli update-version --bump patch --yes --env dev
 
 首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。文件分析变化出现待复核附加属性时，先 `version attr review`，逐项决定保留等待恢复或 `review discard <key>`。详情见 [版本工作稿](./04-版本工作稿.md)。
 
-展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
+展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集有独立的[使用教程](./合集/README.md)，不与单资源工作稿混用；批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。
 
 ## 场景九：只修改一个已发布版本的说明
 

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

@@ -1,6 +1,6 @@
 # 完整命令参考
 
-本页是发布包内的命令索引：列出当前 CLI 的全部公开命令、何时使用以及它会不会改变线上资源或本地文件。首次完成任务请优先看[按场景操作](./09-按场景操作.md)；执行已知命令、编写脚本或排查影响时以本页为准。
+本页是单资源命令索引：列出当前单资源 CLI 命令、何时使用以及它会不会改变线上资源或本地文件。合集命令和场景请查独立的[合集使用教程](./合集/README.md)；首次完成单资源任务请优先看[按场景操作](./09-按场景操作.md)。
 
 所有示例省略 `freelog-cli` 前缀后的公共参数。推荐每次显式传 `--env dev` 或 `--env test`。除 `login`、`logout`、`init`、`template`、`type`、新增/接续生命周期的 `create` / `bind`、批量 `resource sync` 与由未决记录固定目标的 `resource recover` 外，**本页每一条命令都接受并在多资源工程中需要** `--resource <selector>`。`--yes` 只跳过交互确认，不会放宽校验。详细选择规则见[首页](./README.md#多资源工程先选身份再给产物)。
 
@@ -38,10 +38,10 @@ freelog-cli --cli-version
 | `init theme <dir> [--template <id>]` | 从主题模板创建新工程。 | 固定主题类型 `RT001` 与默认构建目录 `dist`。 |
 | `init widget <dir> [--template <id>]` | 从插件模板创建新工程。 | 固定插件类型 `RT002` 与默认构建目录 `dist`。 |
 | `template list` | 查看可用于主题/插件初始化的模板。 | 只读。 |
-| `type list` | 列出全部可用最终叶子类型。 | 只读，需要登录。 |
-| `type search [关键词]` | 按名称筛选最终叶子类型。 | 只读，需要登录。 |
-| `type info <类型编号>` | 确认某个类型编号、名称链和可选配置能力。只有详情显示“可选配置：支持”时，版本工作稿才允许 add/set 配置。 | 只读，需要登录。 |
-| `type pick [--type <类型编号>]` | 以命令方式列出或确认一个最终叶子类型。通常 `init` 的交互选择已足够。 | 只读，需要登录。 |
+| `type list` | 列出全部可用最终叶子；每行显示 `code + 根 / … / 叶子`。固定每页 50 条，TTY 可翻页；非 TTY 输出首页和后续提示。 | 只读，需要登录。 |
+| `type search [关键词]` | 按名称筛选最终叶子，输出与 `type list` 相同的完整路径和分页体验。 | 只读，需要登录。 |
+| `type info <类型编号>` | 确认某个类型编号、从类型树取得的完整名称链和可选配置能力。只有详情显示“可选配置：支持”时，版本工作稿才允许 add/set 配置。 | 只读，需要登录。 |
+| `type pick [--type <类型编号>]` | 以命令方式列出或确认一个最终叶子类型；无 `--type` 时使用与 `type list` 相同的完整路径和分页。通常 `init` 的交互选择已足够。 | 只读，需要登录。 |
 
 ## 建立或接入资源身份
 
@@ -94,8 +94,8 @@ freelog-cli --cli-version
 | 命令 | 何时使用 | 影响 |
 |---|---|---|
 | `update [--title] [--intro] [--cover] [--tags] --yes [--resource <selector>]` | 只修改资源展示信息。 | 更新线上 listing；不发版、不改标识、不上下架。未传字段不改；`--intro ""`、`--tags ""` 清空对应字段；`--cover` 只能给工程内 JPG/PNG/静态 GIF（≤5MB），CLI 上传后写 URL，暂不支持清空封面。 |
-| `policy list [--resource <selector>]` | 查看当前资源的授权策略。 | 只读。 |
-| `policy template list [--page <n> --page-size <n>] [--resource <selector>]` | 查看当前取得的策略模板列表。当前临时请求全量模板，待后端修复按类型筛选契约后再恢复类型参数。 | 只读。 |
+| `policy list [--resource <selector>]` | 查看当前资源的全部授权策略；页头显示根到叶的资源类型链。 | 只读，不分页。 |
+| `policy template list [--resource <selector>]` | 查看当前取得的全部策略模板。固定每页 20 条，TTY 可上一页/下一页；非 TTY 输出首页和继续提示。当前临时请求全量模板，待后端修复按类型筛选契约后再恢复类型参数。 | 只读。 |
 | `policy template apply [templateId] [--name] [--resource <selector>]` | 套用一条平台模板并启用。交互可选择；脚本必须给 `<templateId> --yes`。 | 新增并启用一条策略；不付款、不上架。 |
 | `policy apply --from-file <路径> [--name] --yes [--resource <selector>]` | 从策略文本或 JSON 文件新增策略。 | 新增并启用一条策略；策略语义由平台校验。 |
 | `policy set --id <策略ID> --on|--off [--resource <selector>]` | 启用或停用某条策略。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |

package/dist/docs/README.md

@@ -1,8 +1,8 @@
 # Freelog CLI 使用手册
 
-这是一套面向**一个资源一次一条命令**的 CLI：支持普通文件、主题和插件。一个工程可以保存多份独立资源身份，但除 `resource sync` 外，一条涉及资源的命令只会处理其中一份。本手册以“先按场景完成工作，再按命令查准确行为”为组织原则；无需阅读设计文档或源码。
+这是一套面向**一个主体一次一条命令**的 CLI：单资源支持普通文件、主题和插件；合集有独立的实验性教程。一个工程可以保存多份独立资源或合集身份，但除 `resource sync` 外，一条命令只会处理其中一份。本手册以“先按场景完成工作，再按命令查准确行为”为组织原则；无需阅读设计文档或源码。
 
-不在本期范围：合集、批量发行、前端库模板、支付、session 与 studio 多账号。
+单资源手册不覆盖合集的独立流程；合集教程见下方。批量发行、前端库模板、支付、session 与 studio 多账号仍不在本期范围。
 
 ## 先安装 CLI
 
@@ -37,7 +37,8 @@ freelog-cli --help
 
 | 你的目标 | 阅读 |
 |---|---|
-| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 创建或管理合集（实验性，独立于单资源流程） | [合集使用教程](./合集/README.md) |
 | 先按自己所处的情形找到完整操作路径 | [按场景操作](./09-按场景操作.md) |
 | 创建、发新版本、接入已有资源 | [资源生命周期](./02-日常路径.md) |
 | 创建主题或插件并发布构建产物 | [主题与插件](./03-主题与插件.md) |

package/dist/docs//345/220/210/351/233/206/01-/351/246/226/346/254/241/345/217/221/350/241/214/344/270/216/345/217/221/345/270/203.md

@@ -0,0 +1,196 @@
+# 合集首次发行与发布
+
+本页把首次发行拆成可独立停止、重试的步骤。它不是一个“创建后自动发布”的事务：每一步只改变自己负责的事实。
+
+示例中的 `<...>` 都必须替换；建议先在隔离工程执行，并始终显式传入 `--env dev`。
+
+## 0. 准备条件
+
+1. 已安装 CLI 且 Node.js 为 20 或更高版本；安装与登录见[主手册](../README.md)。
+2. 已登录当前工程：
+
+   ```powershell
+   freelog-cli login --env dev
+   ```
+
+3. 要加入合集的单品已经各自完成“单资源创建版本 → 策略 → 上架”。合集不会替它们上传文件或创建版本。
+
+## 1. 创建合集壳
+
+创建时必须选择**合集最终叶子类型**，填写标题和授权标识短段：
+
+```powershell
+freelog-cli collection create `
+  --type <合集叶子类型编号> `
+  --title "我的合集标题" `
+  --name my-collection `
+  --cwd . `
+  --env dev `
+  --yes
+```
+
+不知道类型编号时，可省略 `--type`，在交互式终端中用层级选择、搜索或直接输入最终叶子类型编号。直接输入仍会由平台重新校验：父节点、停用节点和非合集类型都不能创建。
+
+标题用于展示和搜索，长度不能超过 100 个字符；授权标识在创建后不可修改。成功后 CLI 输出合集 ID，并在当前工程写入一份 `subject:"collection"` 的 `.freelog/N.json`。该文件没有 `filePath`，也不记录目录或版本历史。
+
+### 已有线上合集时用 bind
+
+不要再次 create。接入已有且属于当前账号的合集：
+
+```powershell
+freelog-cli collection bind <合集ID或username/name> --cwd . --env dev
+```
+
+后续示例假定本地只有这一份合集身份；多份时在每条命令追加：
+
+```powershell
+--resource id:<合集ID>
+```
+
+## 2. 添加线上单资源到目录草稿
+
+来源必须是当前账号已经上架的单资源。以下操作只增加服务端目录草稿，尚未改变已发布合集：
+
+```powershell
+freelog-cli collection item add `
+  id:<单资源ID-A> id:<单资源ID-B> `
+  --resource id:<合集ID> `
+  --cwd . --env dev --yes
+
+freelog-cli collection item list `
+  --resource id:<合集ID> `
+  --cwd . --env dev
+```
+
+若某个来源资源有上游授权缺口，脚本或 `--yes` 调用必须显式指定每个上游资源对应的启用策略：
+
+```powershell
+freelog-cli collection item add id:<单资源ID> `
+  --policy <上游资源ID>=<上游策略ID> `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+签约成功即可继续添加；付费不会由 CLI 支付，需在浏览器端完成支付。不要把 `policyId` 当作合同 ID，也不要期待添加单品会自动发布合集。
+
+## 3. 补充展示信息与收录规则（可选）
+
+标题、简介、封面和标签立即写线上 listing，但不会发布目录、表单或上架：
+
+```powershell
+freelog-cli collection update `
+  --title "我的合集标题" `
+  --intro "不超过 200 字的合集简介" `
+  --tag "设计" --tag "2026" `
+  --cover assets/cover.png `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+封面必须位于工程内，支持 JPG/JPEG、PNG 或静态 GIF，最大 5 MiB。CLI 不裁剪图片，上传前请自行确认构图。`--clear-tags` 可清空标签，不能与 `--tag` 一起使用。
+传入一个或多个 `--tag` 时，会将线上标签设置为这次给出的完整列表；要保留旧标签，请把要保留的标签也一并传入。
+
+如果需要自动收录，先发布当前手工目录，再开启规则；否则 CLI 会拒绝，防止自动模式吞掉未发布的手工目录。规则示例与日常维护见[发行后管理](./02-发行后管理与边界.md#收录规则与自动收录)。
+
+## 4. 建立本地表单操作稿（可选）
+
+属性、可选配置、描述、目录展示和直接依赖都通过完整 JSON 表单维护。先从已发布快照拉取为工程内文件：
+
+```powershell
+freelog-cli collection form pull `
+  --out collection-form.json `
+  --resource id:<合集ID> --cwd . --env dev
+```
+
+新合集会得到空基线。修改 `collection-form.json` 后完整写回本地操作稿：
+
+```powershell
+freelog-cli collection form edit `
+  --from collection-form.json `
+  --resource id:<合集ID> --cwd . --env dev
+
+freelog-cli collection form show `
+  --resource id:<合集ID> --cwd . --env dev
+```
+
+最小表单形状如下；不要添加未声明的顶层字段：
+
+```json
+{
+  "$schema": "freelog-cli.collection-form.v1",
+  "inputs": [],
+  "properties": [
+    { "key": "author", "name": "作者", "value": "Freelog", "description": "" }
+  ],
+  "options": [
+    { "key": "language", "name": "语言", "kind": "select", "values": ["中文", "English"], "description": "" }
+  ],
+  "description": "合集说明",
+  "display": {
+    "sort": "ascending",
+    "title": "resource-title",
+    "number": true,
+    "image": true,
+    "description": true,
+    "view": "list"
+  },
+  "dependencies": []
+}
+```
+
+可选配置仅在当前合集类型支持时可填写；不支持时带 `options` 发布会被拒绝。属性与配置的 `key`、名称、描述、值、数量和候选值均受校验，遇到错误请修改外部 JSON 后重新执行 `form edit`。
+
+### 添加合集自身的直接依赖（可选）
+
+必须先有本地表单操作稿。已有授权时无需 `--policy`；缺授权时在交互式终端选择，脚本中明确指定：
+
+```powershell
+freelog-cli collection dep add id:<依赖单资源ID> `
+  --range "^1.0.0" `
+  --policy <依赖策略ID> `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+这和“单品上游授权”不同：前者写入合集表单的 `dependencies`，后者只为某个目录单品准备授权排除映射。
+
+## 5. 发布目录与表单
+
+发布是唯一把目录草稿和本地表单操作稿提交到已发布合集快照的命令：
+
+```powershell
+freelog-cli collection publish `
+  --include-items auto `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+`--include-items` 的选择：
+
+| 参数 | 行为 |
+|---|---|
+| `auto`（默认） | 目录草稿与已发布目录不同则合并；相同则只发布表单。 |
+| `yes` | 强制要求存在目录差异并合并；没有差异会拒绝。 |
+| `no` | 只发布表单，不合并目录草稿。 |
+
+自动收录开启时不能合并手工目录草稿；请先关闭自动收录，或使用 `--include-items no` 只发布表单。发布后 CLI 会读取已发布表单和已发布目录；读回不一致时会保留本地 intent，不自动重发。
+
+若网络中断或结果不明确，先检查而不是再次发布：
+
+```powershell
+freelog-cli collection publish resume `
+  --resource id:<合集ID> --cwd . --env dev
+```
+
+## 6. 上架是最后的独立步骤
+
+`collection publish` 完成不代表对外可见。上架前必须同时满足：
+
+1. 合集已有已发布快照；
+2. 至少一条**合集自身**策略已启用；
+3. 合集未冻结，且不是 RSS 合集。
+
+当前 CLI 尚未提供 `collection policy` 管理命令。策略服务契约稳定前，需要在 Console 为该合集配置并启用策略，然后执行：
+
+```powershell
+freelog-cli collection online `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+成功后 CLI 会重读 `status:1`。如果没有启用策略，它会明确拒绝；不会替你创建策略、发布目录或绕过支付。下架使用 `collection offline`，不删除目录、表单、依赖、合同或本地身份。

package/dist/docs//345/220/210/351/233/206/02-/345/217/221/350/241/214/345/220/216/347/256/241/347/220/206/344/270/216/350/276/271/347/225/214.md

@@ -0,0 +1,158 @@
+# 合集发行后管理与边界
+
+合集的发行后管理仍由彼此独立的命令组成。先用稳定身份选中合集，再只执行要改变的那一类事实；不要因为要修改标题、目录或规则而重新发布整个合集。
+
+```powershell
+# 多合集工程中先固定目标；下文命令均可沿用此选择器。
+--resource id:<合集ID> --cwd <工程目录> --env dev
+```
+
+## 目录单品
+
+`collection item list` 读取的是**服务端目录草稿**，不是已发布目录。它适合确认即将通过下一次 publish 合并的内容：
+
+```powershell
+freelog-cli collection item list --search "关键词" --resource id:<合集ID> --cwd . --env dev
+```
+
+列表每行包含 `itemId`、来源 `resourceId`、合集内标题和来源授权标识。之后所有编辑使用 `itemId`，不能用可变标题或来源文件路径猜测。
+
+```powershell
+freelog-cli collection item rename <itemId> --title "合集内显示标题" --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection item move <itemId> --before <另一个itemId> --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection item remove <itemId> <itemId> --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection item sort --by title --asc --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+`--by` 可为 `added`、`title` 或 `resource-updated`；排序必须且只能给 `--asc` 或 `--desc`。删除只移除目录草稿项，不删除来源单资源。任何目录修改都要再次执行 `collection publish` 才进入已发布目录。
+
+可读取指定项的授权状态：
+
+```powershell
+freelog-cli collection item auth status <itemId> --resource id:<合集ID> --cwd . --env dev
+```
+
+当前没有 `auth resolve`。不要自行修改目录授权字段；该能力要等合同映射的完整平台读回契约确认后才会提供。
+
+## 展示信息
+
+以下命令立即修改线上 listing，但不发布目录、不修改表单、不会上架：
+
+```powershell
+freelog-cli collection update --title "新标题" --intro "新简介" --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection update --tag "标签一" --tag "标签二" --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection update --clear-tags --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection update --cover assets/cover.png --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+标题至多 100 字，简介至多 200 字；标签最多 20 个，每个最多 20 字且不能重复。封面只上传原图，不裁剪；只能使用工程内的 JPG/JPEG、PNG 或静态 GIF，最大 5 MiB。
+
+## 收录规则与自动收录
+
+先查看当前状态：
+
+```powershell
+freelog-cli collection collect-rules get --resource id:<合集ID> --cwd . --env dev
+```
+
+`serialize` 表示合集更新状态，`auto` 表示自动收录模式；它们可以独立修改：
+
+```powershell
+freelog-cli collection collect-rules set --serialize completed --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection collect-rules set --auto off --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+开启自动收录时必须提供工程内规则 JSON 文件，并选择“全部条件”或“任一条件”：
+
+```json
+[
+  { "field": "title", "operator": "INCLUDES", "value": "教程" },
+  { "field": "type", "operator": "EQUAL", "value": "<单资源最终叶子类型编号>" }
+]
+```
+
+```powershell
+freelog-cli collection collect-rules set `
+  --auto all `
+  --rules collection-rules.json `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+规则字段仅支持 `title`、`authIdentity`、`type`。`title` 与 `authIdentity` 支持 `INCLUDES`、`NOT_INCLUDES`、`STARTS_WITH`、`ENDS_WITH`；`type` 只支持 `EQUAL`。`authIdentity` 的 `STARTS_WITH` 值填写用户名后的短段，CLI 会按平台规则补上当前用户名。
+
+开启自动收录前，服务端目录草稿必须与已发布目录一致；有手工差异时先 publish。自动收录开启后，所有手工 `item add/rename/remove/move/sort` 和目录 merge 都被保护性拒绝。先 `--auto off` 并读回关闭成功，再恢复手工目录维护。
+
+## 本地表单、展示和直接依赖
+
+表单操作稿始终先拉取，再编辑或读取：
+
+```powershell
+freelog-cli collection form pull --out collection-form.json --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection form edit --from collection-form.json --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection form show --resource id:<合集ID> --cwd . --env dev
+```
+
+`form pull` 会覆盖已有本地表单操作稿时提示确认；`form edit` 从工程内完整 JSON 替换操作稿，仍不会发送发布请求。要只调整目录展示设置，可使用便捷入口：
+
+```powershell
+freelog-cli collection display set `
+  --sort descending --title resource-title `
+  --number true --image true --description false --view card `
+  --resource id:<合集ID> --cwd . --env dev
+```
+
+直接依赖只写本地操作稿；新增或改范围后必须 publish：
+
+```powershell
+freelog-cli collection dep list --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection dep range id:<资源ID> --range "^1.2.0" --policy <策略ID> --resource id:<合集ID> --cwd . --env dev --yes
+freelog-cli collection dep rm <资源ID> --resource id:<合集ID> --cwd . --env dev
+```
+
+若当前合集尚无本地表单操作稿，`dep` 和 `display` 会要求先执行 `collection form pull`。删除依赖不会取消已存在的线上合同。
+
+## 再次发布、上架与下架
+
+每次目录草稿或本地表单操作稿改变后，按需要发布：
+
+```powershell
+freelog-cli collection publish --include-items auto --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+发布后仍可独立下架：
+
+```powershell
+freelog-cli collection offline --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+上架只在已有发布快照和启用合集策略时可用：
+
+```powershell
+freelog-cli collection online --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+当前策略管理命令尚未可用；没有启用合集自身策略时，CLI 的上架拒绝是预期行为。单品自身的策略、合集直接依赖的签约、以及合集自身策略不能相互替代。
+
+## 日志与授权合约
+
+发行后可以只读观察，不会修改合集：
+
+```powershell
+freelog-cli collection log list --limit 50 --order desc --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection contract list --status active --all --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection contract show <contractId> --resource id:<合集ID> --cwd . --env dev
+```
+
+`collection contract` 固定查询“合集作为授权方”发出的合约，不能用它查看合集作为被授权方时，为单品上游授权或直接依赖签的合同。
+
+## 不能做什么，以及遇到问题怎么办
+
+| 情况 | 正确处理 |
+|---|---|
+| 已发布目录中看不到刚添加的单品 | 先确认 `collection item list` 中有该项，再运行 `collection publish --include-items auto`。发布成功也不等于上架。 |
+| 合集状态为下架 | 已发布目录可以仍有单品；配置并启用合集自身策略后，独立运行 `collection online`。 |
+| `collection online` 提示无策略 | 当前 CLI 不创建合集策略；先在 Console 完成该合集的策略配置和启用。 |
+| 想把本地文件夹或主题项目整体加入合集 | 先将每个文件分别发行、设置策略并上架为单资源，再用 `collection item add` 加入。 |
+| 自动收录开启后无法手工改目录 | 先 `collection collect-rules set --auto off`，读回关闭，再修改目录并 publish。 |
+| 发布网络中断或读回不一致 | 运行 `collection publish resume`；它只提供诊断，不自动重发。 |
+| RSS 合集 | 当前 CLI 只做防误写保护，不提供 RSS 维护、同步或上架能力。 |

package/dist/docs//345/220/210/351/233/206/README.md

@@ -0,0 +1,67 @@
+# 合集使用教程（实验性）
+
+合集是 `subjectType=4` 的独立线上主体。它收录的是**当前账号已经上架的线上单资源**，不是本地文件夹、主题工程或一组尚未发行的素材。
+
+本教程与单资源手册分开维护：合集仍在完善中，已经可用的命令和仍受平台契约限制的能力会明确标注。不要把 Console 的服务端草稿、单资源版本工作稿或本地文件当作合集目录的来源。
+
+## 从这里开始
+
+| 你的目标 | 阅读 |
+|---|---|
+| 第一次创建合集、添加单品、编辑表单并发布 | [首次发行](./01-首次发行与发布.md) |
+| 已发行合集的单品、信息、规则、表单、发布和观察 | [发行后管理](./02-发行后管理与边界.md) |
+| 安装 CLI、登录、环境与单资源发行 | [返回主手册](../README.md) |
+
+## 先理解三个独立事实
+
+```text
+线上合集身份 ── collection create / bind ──> .freelog/N.json（仅用于定位）
+服务端目录草稿 ── collection item ... ──────> 待发布单品目录
+本地表单操作稿 ── collection form / dep ───> 待发布属性、配置、描述、展示与依赖
+                                         \
+                                          collection publish
+                                               │
+                                  已发布合集快照 + 已发布目录
+                                               │
+                            collection online（另一步，且需要启用合集策略）
+```
+
+因此：
+
+1. `collection create` 只创建线上合集壳；不会上传文件、添加单品、发布或上架。
+2. `collection item add` 只改**服务端目录草稿**；单品只有经过 `collection publish` 才进入已发布目录。
+3. `collection form`、`collection dep` 和 `collection display` 只改本地表单操作稿；只有 `collection publish` 才提交这些改动。
+4. `collection publish` 不上架。上架是独立的 `collection online`，且当前必须已有一条启用的合集自身策略。
+
+## 当前可用范围
+
+| 能力 | 当前情况 |
+|---|---|
+| 创建、绑定、目录单品增删改排、listing、收录规则、表单、直接依赖、发布、下架、日志和授权合约只读查询 | 已实现；仍应按命令的实际读回结果判断成功。 |
+| `collection online` | 已实现门禁和状态读回；需要已发布合集与启用的合集自身策略。 |
+| 合集自身策略的创建、模板、编译、启停 | 暂未提供 CLI 命令，等待策略后端契约稳定。当前需要先在 Console 配置并启用策略，才可用 CLI 上架。 |
+| 已有目录单品的授权重处理（`collection item auth resolve`） | 暂未实现；只提供 `auth status` 查询。 |
+| RSS 合集、批量单资源发行、支付、从本地文件夹自动生成合集 | 当前不支持。 |
+
+所有示例使用 dev 环境。生产环境当前被 CLI 拦截；请每次显式带 `--env dev` 或 `--env test`。
+
+## 合集如何选择
+
+合集命令的 `--resource` 只选择目标合集，不接受 `artifact:`：
+
+```powershell
+--resource id:<合集ID>                 # 最稳定，推荐
+--resource name:<username/name>         # 完整授权标识
+--resource file:N.json                  # 当前工程本地合集身份
+```
+
+标题可变且可以重复，不能作为选择器。工程内恰有一份合集身份时可省略 `--resource`；零份或多份时必须明确指定。`--cwd <工程目录>` 决定从哪里读取登录选择器和 `.freelog/`，不会改变线上主体。
+
+## 使用时的底线
+
+- 合集单品只能是本人、当前环境、已上架且已有最新版本的线上单资源；本地是否有该资源的文件或 `N.json` 不影响资格。
+- 单品上游授权、合集直接依赖、合集自身策略是三件不同的事。不要把合同 ID、策略 ID 或依赖信息手工写进 JSON。
+- `collection form pull` 会以**已发布合集快照**刷新本地表单操作稿；它不会读取、覆盖或删除 Console 的服务端草稿。
+- 网络请求结果不明确时，用 `collection publish resume`、`collection item list`、`collection form show` 或 `status` 读回事实；不要反复盲目重发。
+
+发布包会递归携带本目录。安装后运行 `freelog-cli --help`，根据输出的本机手册路径打开 `合集/README.md` 即可。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freelog-cli/cli2",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Freelog CLI",
   "type": "module",
   "license": "MIT",