@freelog-cli/cli2 0.5.5 → 0.5.7

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

@@ -82,6 +82,6 @@ freelog-cli create-version --yes --artifact video.mp4 --env dev
 
 - 要增加属性、可选配置或依赖：看 [版本工作稿](./04-版本工作稿.md)。
 - 要发布后续版本：看 [日常操作](./02-日常路径.md#发布新版本)。
-- 要给资源配置策略并上架：看 [资源管理](./05-资源管理.md)。
+- 要选择模板、填写参数并添加策略：看[单资源授权策略](./11-单资源授权策略.md)；之后按[资源管理](./05-资源管理.md)上架。
 - 要发行主题或插件：不要照本页的 `init`，改看 [主题与插件](./03-主题与插件.md)。
 - 要查任一命令的全部前置条件和影响：看 [完整命令参考](./10-命令参考.md)。

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

@@ -1,6 +1,6 @@
 # 资源管理
 
-本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
+本页管理已绑定资源的线上事实：展示信息、标题同步、授权策略和可用状态。它们不替代版本发行，也不会修改未提交版本工作稿。发版看[资源生命周期](./02-日常路径.md)，工作稿看[版本工作稿](./04-版本工作稿.md)，策略添加的完整操作见[单资源授权策略](./11-单资源授权策略.md)，所有命令的精确契约看[完整命令参考](./10-命令参考.md)。
 
 多资源工程中，本页除不带选择器即批量的 `resource sync` 外，每条命令都加 `--resource <selector>`。优先用 `id:`、`name:` 或 `artifact:<当前文件>`；`file:N.json` 保留给 AI、脚本和恢复。
 
@@ -59,20 +59,16 @@ freelog-cli resource recover --apply --yes --env dev
 
 对“尚未发送”状态，这会原子删除未决记录、保留工作稿；对“已确认”状态，才会原子删除工作稿和未决记录。不会重发版本。若版本不存在、SHA 不同、环境不对或本地身份不一致，CLI 会保留两份文件并停止。未决记录存在时，除登录、退出、只读查看和 `resource recover` 外，新的业务写入都会被拦住。
 
-## 管理授权策略
-
-```powershell
-freelog-cli policy list --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 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 <策略名>`。策略语义最终由平台校验。
+## 管理授权策略
+
+```powershell
+freelog-cli policy template list --resource id:<资源ID> --env dev
+freelog-cli policy list --resource id:<资源ID> --env dev
+freelog-cli policy set --id <策略ID> --off --resource id:<资源ID> --env dev
+freelog-cli policy set --id <策略ID> --on --resource id:<资源ID> --env dev
+```
+
+`policy template list` 在交互终端可以翻页、选择模板、修改参数、预览译文并确认添加；添加后策略默认启用。`policy list` 查看当前资源已添加的全部策略，不分页。非交互脚本不能只给模板 ID 和 `--yes`：还须提供当前模板指纹、策略名和每个参数编号的值。模板详情、`--json` 机器输出、脚本示例及失败恢复见[单资源授权策略](./11-单资源授权策略.md)。当前命令树没有旧版 `policy apply --from-file` 入口。
 
 ## 上架与下架
 

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)单独操作，其中选择模板、填写参数并添加策略见[单资源授权策略](./11-单资源授权策略.md)。合集有独立的[使用教程](./合集/README.md)和[合集授权策略](./合集/03-合集授权策略.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#多资源工程先选身份再给产物)。
 
@@ -95,10 +95,10 @@ 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 [--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>]` | 启用或停用某条策略。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |
+| `policy template list [--json] [--resource <selector>]` | TTY 每页 20 条，可翻页并直接选择模板、编辑参数、预览和创建；非 TTY 默认只打印首页；`--json` 一次输出全部 `normal` 模板及参数、指纹。当前请求服务端全量快照，再按编译主体筛选。 | 只读直到用户在 TTY 预览并确认创建；`--json` 始终只读。 |
+| `policy template info <templateId> [--json] [--resource <selector>]` | 查看模板全文、参数编号、默认值、选项和非交互命令骨架；`--json` 只输出这一条的机器描述。 | 只读。 |
+| `policy template apply <templateId> [--resource <selector>]` | TTY 逐项编辑、预览译文后创建；非交互或显式传参数时须同时给 `--template-fingerprint <值> --name <策略名> --param "编号=值"`（每个槽位各一项）和 `--yes`。详见[单资源授权策略](./11-单资源授权策略.md)。 | 平台编译并翻译后新增、启用一条策略；不付款、不上架。 |
+| `policy set --id <策略ID> --on` 或 `--off` | 二选一启用或停用当前资源的一条策略，可加 `--resource <selector>`。 | 更新线上策略状态；已上架资源不能停用到零条启用策略。 |
 | `validate --for online [--resource <selector>]` | 上架前预检版本和策略条件。 | 只读。 |
 | `online [--resource <selector>]` | 资源有已发版本和至少一条启用策略后上架。 | 更新线上可用状态。 |
 | `offline [--resource <selector>]` | 暂停线上可用状态。 | 只下架，不删除版本、策略、资源或本地文件。 |

package/dist/docs/11-/345/215/225/350/265/204/346/272/220/346/216/210/346/235/203/347/255/226/347/225/245.md

@@ -0,0 +1,72 @@
+# 单资源：添加和管理授权策略
+
+本页只操作**单资源自身的授权策略**。主题、插件、图片等单资源使用同一流程；合集自身策略请看[合集授权策略](./合集/03-合集授权策略.md)。添加策略不创建版本、不会上架资源，也不会替任何人付款或签约。
+
+以下命令以 dev 为例。先在工程中登录，并为目标资源创建线上资源壳或绑定已有资源；只运行 `init`、还没有线上资源 ID 时不能添加策略。工程有多份单资源身份时，每条命令都传 `--resource id:<资源ID>`；只有一份时可以省略。若工程不在当前目录，另加 `--cwd <工程目录>`。
+
+## 最短人工路径：列表中选模板并完成添加
+
+```powershell
+freelog-cli policy template list --resource id:<资源ID> --env dev
+```
+
+在交互式终端中，列表每页显示 20 个单资源模板及各自参数数量，可选择“下一页”“上一页”或“退出”。**选中模板后不会立即提交**：CLI 展示完整策略说明，并在可修改的位置标出 `[1]`、`[2]` 等参数编号；可以修改策略名称、逐项修改或恢复默认值，然后选择“预览并创建”。预览阶段先重新读取模板、校验参数，调用平台编译与翻译，展示最终策略译文和参数值；确认后才新增策略并启用。选择“取消”或预览校验失败不会写入策略。
+
+参数类型由当前模板决定：
+
+| 类型 | 如何输入 |
+|---|---|
+| 数字 `number` | 输入有限数字；下限和小数位以 `template info` 或 `--json` 显示的规则为准。 |
+| 选项 `select` | 人工操作从模板提供的选项中选择。 |
+| 时间 `datetime` | 使用 `YYYY-MM-DD HH:mm` 格式，例如 `2026-10-01 09:00`。 |
+
+模板可能没有可用默认值，此时必须填写相应参数；即使有默认值，也建议逐项核对最终译文。策略名称必须为 2–20 个字符，且不能与该资源现有策略重名。
+
+## 已知道模板 ID：先看完整说明，再进入编辑
+
+```powershell
+freelog-cli policy template info <模板ID> --resource id:<资源ID> --env dev
+freelog-cli policy template apply <模板ID> --resource id:<资源ID> --env dev
+```
+
+`info` 只读，展示模板全文、参数编号、默认值、选项及一条非交互命令骨架；骨架不会自动带上当前工程的 `--resource`、`--cwd` 和 `--env`，复制后请补齐。`apply <模板ID>` 在交互终端进入与列表选择相同的编辑、预览和确认流程。若只想从模板列表开始，不必先执行 `info`。
+
+## AI 或脚本：取得完整模板快照后精确提交
+
+```powershell
+freelog-cli policy template list --json --resource id:<资源ID> --env dev
+freelog-cli policy template info <模板ID> --json --resource id:<资源ID> --env dev
+```
+
+`list --json` 一次输出当前单资源可见的**全部**模板，不按 TTY 的 20 条分页；`info --json` 只输出指定模板。机器输出含模板 ID、整体说明、`fingerprint` 和每个参数的编号 `slot`、类型、默认值或必填标记、数字规则及选项 `value`。同一说明里重复出现的参数仍使用同一个编号。`fingerprint` 用于确认提交时的模板描述与查看时一致，**参数编号只对该模板的当前指纹有效**。
+
+从上述输出选定一个模板后，给它的**每一个参数编号**显式提供一个 `--param "编号=值"`，包括已有默认值的参数；零参数模板不需要 `--param`。例如，假设当前模板有两个参数：
+
+```powershell
+freelog-cli policy template apply <模板ID> `
+  --template-fingerprint <从当前JSON读取的fingerprint> `
+  --name "我的授权策略" `
+  --param "1=<第一个参数值>" `
+  --param "2=<第二个参数值>" `
+  --resource id:<资源ID> --env dev --yes
+```
+
+这只是命令形状，**不能照抄两个 `--param` 的数量或值**；以该模板的实际参数清单为准。选项参数传 `value`，不是显示用 `label`；时间使用上述格式。缺编号、重复编号、值不合规则或模板指纹已变化会停止，先重新运行 `list --json` / `info` 再提交。非交互运行或显式传入指纹、参数时，`--template-fingerprint`、`--name`、全部 `--param` 和 `--yes` 是必需的；**单独加 `--yes` 不足以让脚本自动补参数**。
+
+## 确认结果与启停
+
+```powershell
+freelog-cli policy list --resource id:<资源ID> --env dev
+freelog-cli policy set --id <策略ID> --off --resource id:<资源ID> --env dev
+freelog-cli policy set --id <策略ID> --on --resource id:<资源ID> --env dev
+```
+
+`policy list` 一次列出这个资源的全部已添加策略和启用状态，不分页；页头还会显示资源类型从根到叶的完整路径。添加成功后策略默认**启用**，CLI 会读回确认。启停只修改策略状态，不删除策略、不创建版本、不会触发付款；已上架资源不能停用最后一条启用策略。`set` 必须且只能给 `--on` 或 `--off`；交互终端会确认，脚本可加 `--yes`。
+
+资源上架仍是独立步骤：先确保已有已发版本和至少一条启用策略，再运行 `freelog-cli validate --for online ...`、`freelog-cli online ...`。策略模板与依赖签约是两件事：此处添加的是**自己资源对外提供的策略**；版本依赖要到[版本工作稿](./04-版本工作稿.md)维护。
+
+## 当前模板范围与失败处理
+
+当前模板接口请求完整列表；CLI 仅保留编译目标为 `normal` 的模板供单资源使用，**不按免费／付费或交易事件标签筛选**，也暂不按资源叶子类型请求缩小范围。列表中出现不适用的模板，并不保证它一定能为当前资源编译成功或被平台接受；最终以预览时的平台编译、翻译以及创建校验为准。平台若拒绝编译，CLI 不猜测修改事件、金额或日期语义。
+
+若提示“模板已变化”，重新查询并按新编号填写；若提示重名或正文重复，先用 `policy list` 核对现有策略。新增与启停均会读回线上状态；出现“创建结果未知”时 CLI 会退出当前编辑流程，先查列表，**不要盲目重复创建**。没有适用模板时列表正常显示为空；响应损坏才报错。CLI 不处理结算账户或支付，平台若拒绝编译或提交，则如实显示错误。目前命令树没有 `policy apply --from-file` 入口；本页的添加路径是策略模板，不要按旧文档中的手写文件示例执行。

package/dist/docs/README.md

@@ -1,8 +1,8 @@
 # Freelog CLI 使用手册
 
-这是一套面向**一个资源一次一条命令**的 CLI：支持普通文件、主题和插件。一个工程可以保存多份独立资源身份，但除 `resource sync` 外，一条涉及资源的命令只会处理其中一份。本手册以“先按场景完成工作，再按命令查准确行为”为组织原则；无需阅读设计文档或源码。
+这是一套面向**一个主体一次一条命令**的 CLI：单资源支持普通文件、主题和插件；合集有独立的实验性教程。一个工程可以保存多份独立资源或合集身份，但除 `resource sync` 外，一条命令只会处理其中一份。本手册以“先按场景完成工作，再按命令查准确行为”为组织原则；无需阅读设计文档或源码。
 
-不在本期范围：合集、批量发行、前端库模板、支付、session 与 studio 多账号。
+单资源手册不覆盖合集的独立流程；合集教程见下方。批量发行、前端库模板、支付、session 与 studio 多账号仍不在本期范围。
 
 ## 先安装 CLI
 
@@ -37,12 +37,14 @@ freelog-cli --help
 
 | 你的目标 | 阅读 |
 |---|---|
-| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 创建或管理合集（实验性，独立于单资源流程） | [合集使用教程](./合集/README.md) |
 | 先按自己所处的情形找到完整操作路径 | [按场景操作](./09-按场景操作.md) |
 | 创建、发新版本、接入已有资源 | [资源生命周期](./02-日常路径.md) |
 | 创建主题或插件并发布构建产物 | [主题与插件](./03-主题与插件.md) |
 | 继续、覆盖或丢弃未提交的版本内容 | [版本工作稿](./04-版本工作稿.md) |
-| 修改展示信息、策略和上下架 | [资源管理](./05-资源管理.md) |
+| 修改展示信息、策略和上下架 | [资源管理](./05-资源管理.md) |
+| 为单资源选择、填写并添加授权策略 | [单资源授权策略](./11-单资源授权策略.md) |
 | 命令失败后的处理方式 | [故障恢复](./06-常见情况与报错.md) |
 | 环境、登录和本地文件 | [环境、登录与凭据](./07-环境与凭据.md) · [本地状态文件](./08-本地文件参考.md) |
 | 已知命令、参数或脚本需求，想查准确前置条件和影响 | [完整命令参考](./10-命令参考.md) |
@@ -68,7 +70,7 @@ freelog-cli --help
 | `--resource <selector>` | 为常规单资源命令选择某一份本地身份：`id:<资源ID>`、完整 `name:<username/name>`、`artifact:<相对文件或构建目录>` 或 `file:N.json`。单份可省略；多份交互选择，非交互必须明确指定。标题只展示，不能选择身份。`create` / `bind` 的新增或接续规则见下文。 |
 | `--artifact <path>` | 当前选中资源的产物路径：`create` / `bind` 可记录默认路径；发版时表示本次上传路径；`version set` 只更新默认路径，绝不选择身份。 |
 | `--yes` | 跳过交互确认；不会放宽校验。仅当命令明确支持时（如覆盖工作稿）才允许覆盖相应状态，绝不覆盖工程目录。 |
-| `--json` | 将 CLI 错误输出为 `{ "code", "message" }`。 |
+| `--json` | 将 CLI 错误输出为 `{ "code", "message" }`；策略 `template list/info` 还会输出可供脚本读取的完整模板描述。 |
 
 新脚本只使用 `--type`，不要使用 `--resource-type`；后者仅为迁移期兼容别名，CLI 会给出弃用警告。`--scaffold`、`artifactMode`、`publish` 和 `release` 不存在于当前命令面。
 

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,205 @@
+# 合集首次发行与发布
+
+本页把首次发行拆成可独立停止、重试的步骤。它不是一个“创建后自动发布”的事务：每一步只改变自己负责的事实。
+
+示例中的 `<...>` 都必须替换；建议先在隔离工程执行，并始终显式传入 `--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 中直接选择合集自身的策略模板。交互终端运行下面的列表，翻页选中模板，修改名称及参数，预览最终译文后确认创建；成功后策略默认启用：
+
+```powershell
+freelog-cli collection policy template list `
+  --resource id:<合集ID> --cwd . --env dev
+freelog-cli collection policy list `
+  --resource id:<合集ID> --cwd . --env dev
+```
+
+脚本/AI 需先获取模板参数和指纹，并显式提供每个参数及 `--yes`，不能只给模板 ID。完整操作见[合集授权策略](./03-合集授权策略.md)。确认至少一条合集自身策略启用后，再单独上架：
+
+```powershell
+freelog-cli collection online `
+  --resource id:<合集ID> --cwd . --env dev --yes
+```
+
+成功后 CLI 会重读 `status:1`。如果没有启用策略，它会明确拒绝；`online` 本身不会替你创建策略、发布目录或绕过支付。下架使用 `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
+```
+
+没有启用合集自身策略时，上架拒绝是预期行为。可通过 `collection policy template list` 交互选择模板、填写参数并创建，再用 `collection policy list` 确认启用状态；已有策略的开关使用 `collection policy set --id <策略ID> --on|--off`。详细操作及非交互参数见[合集授权策略](./03-合集授权策略.md)。单品自身策略、合集直接依赖的签约、合集自身策略不能相互替代。
+
+## 日志与授权合约
+
+发行后可以只读观察，不会修改合集：
+
+```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` 提示无策略 | 先按[合集授权策略](./03-合集授权策略.md)在 CLI 中选择模板并添加、启用合集自身策略，再检查已发布快照后重试上架。 |
+| 想把本地文件夹或主题项目整体加入合集 | 先将每个文件分别发行、设置策略并上架为单资源，再用 `collection item add` 加入。 |
+| 自动收录开启后无法手工改目录 | 先 `collection collect-rules set --auto off`，读回关闭，再修改目录并 publish。 |
+| 发布网络中断或读回不一致 | 运行 `collection publish resume`；它只提供诊断，不自动重发。 |
+| RSS 合集 | 当前 CLI 只做防误写保护，不提供 RSS 维护、同步或上架能力。 |