@freelog-cli/cli2 0.5.5 → 0.5.7

package/dist/docs//345/220/210/351/233/206/03-/345/220/210/351/233/206/346/216/210/346/235/203/347/255/226/347/225/245.md

@@ -0,0 +1,70 @@
+# 合集：添加和管理自身授权策略
+
+本页只操作**合集自身对外提供的授权策略**。合集目录单品的上游授权、合集表单中的直接依赖以及单资源自身策略是另外三件事；不要用这里的策略 ID 代替依赖所需的上游策略或合同 ID。单资源教程单独见[单资源授权策略](../11-单资源授权策略.md)。
+
+以下以 dev 环境为例。先 `freelog-cli login --env dev`，并已通过 `collection create` 或 `collection bind` 拥有可维护的线上合集。策略添加只需要合集线上身份；它不发布目录或表单，也不会自动上架。多合集工程中每条命令都传 `--resource id:<合集ID>`；也可用完整 `name:<username/name>` 或 `file:N.json`。合集选择器**不接受 `artifact:`**；没有本地合集状态时，可直接指定当前账号拥有的线上 `id:` 或 `name:`。工程目录另用 `--cwd <工程目录>`。
+
+## 最短人工路径：从合集模板列表完成添加
+
+```powershell
+freelog-cli collection policy template list --resource id:<合集ID> --env dev
+```
+
+在交互式终端中，合集模板固定每页 20 个并显示各自参数数量，可以选择“下一页”“上一页”或“退出”。选择模板后，CLI 展示完整策略说明与 `[1]`、`[2]` 等参数编号；可修改策略名称、逐项输入或选择参数、恢复默认值，再“预览并创建”。预览会重新读取模板并校验指纹与参数，调用平台进行合集策略编译和翻译，展示最终策略译文和参数值；确认后才向合集新增并启用策略。取消或预览失败不会写入。
+
+参数可以是数字、选项或时间。数字下限和精度、可选 `value`、默认值均取自当前模板；时间格式为 `YYYY-MM-DD HH:mm`。没有可用默认值的参数必须填写。策略名称为 2–20 个字符，同一合集不能出现同名或相同正文的策略。
+
+## 指定模板 ID 或供 AI 查阅
+
+```powershell
+freelog-cli collection policy template info <模板ID> --resource id:<合集ID> --env dev
+freelog-cli collection policy template apply <模板ID> --resource id:<合集ID> --env dev
+```
+
+`info` 只读，列出全文、参数编号、默认值、选项及非交互命令骨架；复制骨架后还要补上本次的 `--resource`、`--cwd` 和 `--env`。`apply <模板ID>` 在交互终端进入与 `template list` 选择后相同的编辑、预览、确认流程；它不是“看到 ID 就不校验直接创建”。
+
+脚本或 AI 先获取机器可读的完整合集模板快照：
+
+```powershell
+freelog-cli collection policy template list --json --resource id:<合集ID> --env dev
+freelog-cli collection policy template info <模板ID> --json --resource id:<合集ID> --env dev
+```
+
+`list --json` 输出当前合集可见的**全部**模板，不受人工界面每页 20 条的限制；`info --json` 只输出一个模板。机器输出含模板 ID、报告、`fingerprint` 与每个参数的 `slot`、类型、默认值或必填标记、数字规则、选项。脚本须使用**刚查看的指纹**，并给该模板的**每个**编号传 `--param "编号=值"`，包括有默认值的参数；零参数模板不传 `--param`。选项填 `value` 而不是显示名称。
+
+例如当前选中模板恰有两个参数时，命令形状为：
+
+```powershell
+freelog-cli collection policy template apply <模板ID> `
+  --template-fingerprint <从当前JSON读取的fingerprint> `
+  --name "合集授权策略" `
+  --param "1=<第一个参数值>" `
+  --param "2=<第二个参数值>" `
+  --resource id:<合集ID> --env dev --yes
+```
+
+**参数个数和值只是占位示例**，必须以该模板实际清单替换。非交互运行或显式传入指纹、参数时，`--template-fingerprint`、`--name`、每个参数的 `--param` 和 `--yes` 缺一不可；单独的 `apply <ID> --yes` 不会替脚本补齐参数。参数缺失、重复、无效或模板指纹变化会停止，重新查询模板后再执行。
+
+## 查询结果、启停与上架
+
+```powershell
+freelog-cli collection policy list --resource id:<合集ID> --env dev
+freelog-cli collection policy set --id <策略ID> --off --resource id:<合集ID> --env dev
+freelog-cli collection policy set --id <策略ID> --on --resource id:<合集ID> --env dev
+```
+
+`collection policy list` 一次列出该合集自身的全部策略 ID、名称和 `on/off`，不分页。模板添加成功后默认**启用**，CLI 会读回确认；它不会发布目录、表单或上架合集，也不替使用方付款。`set` 必须且只能指定 `--on` 或 `--off`，交互时会确认，脚本可加 `--yes`；已上架合集不能停用最后一条启用策略，冻结合集也不能修改策略。
+
+合集上架还需要**已发布快照**。完成[首次发行](./01-首次发行与发布.md)的目录／表单发布后，确认至少一条合集自身策略启用，再执行：
+
+```powershell
+freelog-cli collection online --resource id:<合集ID> --env dev --yes
+```
+
+上架不是策略添加的副作用；下架也不删除策略、已发布目录或已有合同。
+
+## 当前范围及失败后恢复
+
+当前模板接口请求完整列表；CLI 仅保留编译目标为 `collection` 的模板供合集使用，**不按免费／付费或事件标签筛选**，也暂不按合集叶子类型请求缩小范围。因此列表出现某模板不保证它一定能为当前合集编译或创建成功；预览时的平台编译、翻译及最终写入校验仍会把关。CLI 不自行改写支付、金额、时间或事件语义。
+
+若模板指纹变化，重新运行 `template list --json` 或 `template info`，按新编号和值填写；若名称或正文重复，先用 `collection policy list` 核对。出现“创建结果未知”时 CLI 会退出当前编辑流程，先读回列表，不要盲目再添加。没有适用模板时列表正常显示为空；响应损坏才报错。CLI 不处理结算账户或支付，平台若拒绝编译或提交，则如实显示错误。当前合集 CLI 只提供模板添加、列表和启停；没有 `collection policy apply --from-file` 手写策略入口。

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

@@ -0,0 +1,68 @@
+# 合集使用教程（实验性）
+
+合集是 `subjectType=4` 的独立线上主体。它收录的是**当前账号已经上架的线上单资源**，不是本地文件夹、主题工程或一组尚未发行的素材。
+
+本教程与单资源手册分开维护：合集仍在完善中，已经可用的命令和仍受平台契约限制的能力会明确标注。不要把 Console 的服务端草稿、单资源版本工作稿或本地文件当作合集目录的来源。
+
+## 从这里开始
+
+| 你的目标 | 阅读 |
+|---|---|
+| 第一次创建合集、添加单品、编辑表单并发布 | [首次发行](./01-首次发行与发布.md) |
+| 已发行合集的单品、信息、规则、表单、发布和观察 | [发行后管理](./02-发行后管理与边界.md) |
+| 选择模板、填写参数并添加合集自身策略 | [合集授权策略](./03-合集授权策略.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` | 已实现门禁和状态读回；需要已发布合集与启用的合集自身策略。 |
+| 合集自身策略的模板列表、参数编辑、创建、列表和启停 | 已提供 `collection policy template list/info/apply`、`collection policy list/set`；添加后默认启用。交互与脚本路径见[合集授权策略](./03-合集授权策略.md)。当前没有手写策略文件入口。 |
+| 已有目录单品的授权重处理（`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.5",
+  "version": "0.5.7",
   "description": "Freelog CLI",
   "type": "module",
   "license": "MIT",