Skip to main content
策略包由附加到 GitHub 发布版本的三个文件组成。failproofai publish 从其前面的策略文件中生成这三个文件，创建发布版本并上传。

​
1. 编写策略

从已经可以正常运行的内容开始，而不是从空白模板开始：
该命令会询问策略包的名称，写入 <name>.mjs 文件后停止——不涉及网络、git，也不会发布任何内容。它生成的文件包含一条已经可以阻止 git push --force 的策略。如果文件已存在，它拒绝覆盖。 策略使用与任何自定义策略相同的 API。策略包有两个额外字段需要注意：
省略 defaultEnabled 时，默认值为 false。普通的 failproofai policies add 只会启用您标记过的策略——在无人值守的情况下安装陌生人的所有策略，不应由安装程序替用户做这个决定。 可以编写任意数量的文件；按类别一个文件读起来更清晰。目录中所有注册了策略的文件都会被打包成策略包所需的单一构件。
打包需要 bun。没有它，请只使用一个自包含的文件。无论哪种方式，发布的入口文件在安装时都不得导入本地文件：只有入口文件的摘要是固定的，因此引用兄弟文件的策略包无法诚实地声称摘要覆盖了实际运行的内容——publish 会拒绝此类情况，而不是发布一个它无法兑现的承诺。

​
2. 先在本地测试

在任何人看到之前，先在本机上执行该文件：
任意路径，任意文件名。让您的 Agent 尝试执行被阻止的操作，观察它被拒绝。此时什么都不会发布，也不会影响其他人。测试策略 涵盖了其余部分：必须允许的合法场景，以及会导致问题的输入。

​
3. 发布

它会自动确定发布位置、要打包的内容以及版本号，仅在仓库中找不到相关信息时才会询问。按顺序执行以下步骤，如果任何步骤出错则在创建发布版本前停止：
  1. 根据内容查找策略文件——即那些导入了 failproofai 并调用了 customPolicies.add 的文件——而非根据文件名，因此它能找到 guards.mjs 并忽略不相关的 policies.mjs。它不会递归进入子目录，所以测试夹具文件不会被意外收录。
  2. 从文件所在目录的 git remote get-url origin 读取仓库信息（而非您当前所在目录），并确定版本号。
  3. 查找您的凭证：GITHUB_TOKEN、GH_TOKEN 或 gh auth login。它只需要 release-write 权限，凭证内容不会被打印出来。
  4. 如果仓库不存在则创建仓库。此步骤在构建之前执行，因此若策略包在下一步被拒绝，可能会留下一个没有任何发布版本的新仓库。
  5. 构建三个资产，并使用加载器自身的规则进行验证——即决定什么可以安装到陌生人机器上的同一套代码——因此永远无法安装的策略包会在这里失败，此时您仍可以修复它。
  6. 创建或复用发布版本并上传，替换同名资产。
资产名称是固定的——消费方的 CLI 就是根据这些名称构建 URL 的，无需 API 调用，也无需服务发现。 构建时拒绝的情况包括：id 不符合 publisher/name 格式、策略名称包含 /、策略声明了 alwaysOn、缺少 description、category 或 match、入口文件没有注册任何策略，以及入口文件导入了本地文件。 覆盖自动确定的任何设置：
--id 在策略包 id 应与仓库不同时设置该 id，--tag 设置发布版本的标签，--notes 替换自动生成的发布说明——policies show --releases 从中读取每个发布版本的计数和提交信息——--out 指定资产写入位置（默认为 dist-pack），--dry-run 在不发布的情况下构建资产，无需凭证。 任何人现在都可以通过 failproofai policies add acme/support-agent 安装它。关于固定版本和只安装部分策略，请参阅策略包。

​
在策略中心上架

在 GitHub 仓库中添加 failproofai-policies 主题标签。无需提交表单，也没有审核队列：策略中心的爬虫会在下次扫描时自动收录该仓库。添加主题标签只是将其纳入考虑——真正使其上架的是一个发布版本，其清单能通过自身 SHA256SUMS 的验证，并能在 CLI 使用的相同规则下正确解析，而这正是 failproofai publish 所生成的内容。

​
版本号的确定方式

版本号就是您正在发布的提交——其短 sha，十二个字符：a1b2c3d4e5f6。无需选择，无需递增，版本号精确指向字节的来源，因此对同一份源代码发布两次会得到相同的版本号。 版本号从您面前的文件树中读取，从不从仓库的发布版本中读取，因此全新克隆和离线机器无需询问 GitHub 历史就能计算出相同的结果。 由于版本号指向一个提交，该提交必须存在。在终端中，publish 会替您完成这一步：在没有仓库时初始化仓库，并在构建前提交已变更的策略文件。在以下情况下它会拒绝执行，并提示 --version 作为解决方案：在没有终端的情况下运行（在 CI 运行器上创建的提交将不存在于其他地方）、除策略文件外还有其他文件未提交，或者在尚无任何提交的检出环境中。HEAD 上的标签优先于 sha——打了 v1.2.0 标签的人已经声明了这个发布版本的含义。 sha 本身没有顺序信息，因此使用 failproofai policies show <owner>/<repo> --releases 查看哪个发布版本在前——最新的在最上面。

​
发布新版本

提交更改并再次运行 failproofai publish——新提交即为新版本。消费者运行相同的 failproofai policies add。在没有终端的情况下，或使用了选择标志时，他们保留之前选择的子集，已关闭的策略保持关闭；在有终端且没有标志的情况下，选择器会以您的默认值预先勾选打开，他们的选择将替换之前的选择。 更改策略的名称是一项破坏性变更：之前关闭了该策略的机器正在关闭一个已不存在的名称，而新名称将以 defaultEnabled 所指定的状态出现。

​
您的用户在信任什么

SHA256SUMS 与构件存放在同一个发布版本中，因此它证明了字节是您发布的那些——但无法证明您是谁。任何能写入该仓库的人都可以同时修改这两个文件。用户的保护在于：摘要在安装时被固定，因此您发布的内容事后无法被替换。 请从您控制写入权限的仓库发布，并像发布软件包一样对待策略包发布。 仓库还必须是公开的。安装是匿名 HTTPS，没有凭证可以提供，因此已存在的私有仓库会在构建或上传任何内容之前被拒绝，publish 创建的仓库也出于同样原因是公开的。--allow-private 可以为通过其他方式交付这三个资产的场景覆盖此限制，并明确表示没有 policies add 能访问到它们。只有发布版本重要：安装读取的是 releases/download/<tag>/<asset>，从不接触您的 git 树。

​
观察模式优先于强制执行

清单可以声明 "effect": "observe"——通过 failproofai publish --effect observe 设置。这些策略会运行，其裁决会被记录并丢弃——不会阻止任何操作。这是在新规则影响任何人工作之前，针对真实流量进行测量的方式。