# 贡献、构建与发布

修改声明式源条目，让下载、索引和网页保持一致。

## 修改正确的源文件

每个条目在 data/entries/ 中有一个 JSON 文件。选择 bot-role 或 task-workflow，填写任务、输入、输出、步骤、前提、来源和许可。不放入脚本、凭据、聊天或私有记忆。

| 源字段 | 含义 | 检查重点 |
| --- | --- | --- |
| id / version | 稳定身份与模板版本 | 保留已发布版本字节 |
| collection | bot-role 或 task-workflow | 按职责或产物分类 |
| inputs / outputs / workflow | 材料、产物与步骤 | 能否写出可验收首任务 |
| requirements / references / license | 前提、来源和许可 | 不宣称未验证能力或官方身份 |

## CLI 只规划或导出

scripts/market.mjs 支持 help、list、info、plan、install。install 实际生成文件，必须给出 --out 和目标宿主版本，不会安装到运行中的 App。社区与未固定信任锚的接受标志由使用者明确选择。

```sh
npm run market -- help
npm run market -- list --query=research
npm run market -- info awesome/grok-researchy
# Replace 0.9.9 with the actual target host version.
npm run market -- plan awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned
npm run market -- install awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned --out=./researchy.fleet.json
```

独立 CLI 不提供升级或回滚补丁。Fleet 导入可能改名，必须由宿主先对账实际 Bot ID，再处理保留用户修改的升级。

## 核对生成的双语产物

1. 使用 Node.js 22+，先读贡献规范，再修改声明式条目。
2. 维护完整英文内容，中文回退不能当成翻译。
3. 运行生成与检查，审阅生成差异和单角色下载。
4. 只暂存准备公开的文件，再运行公共内容审计。

```sh
npm ci --ignore-scripts
npm run build
npm run check
npm run check:versions
npm test
npm run build:site
npm run audit:public
```

## 发布不可变版本

已发布模板版本和发布资产不能改写。指令修正使用新版本，并保留许可与历史摘要。CI 检查目录、导出和站点；Pages 工作流构建静态站点；版本标签须匹配 package.json。工作流存在不等于线上部署成功，发布后还需核对部署结果和页面。

```sh
npm run pack:release
# From the release download directory on macOS:
shasum -a 256 -c SHA256SUMS
```

- [贡献规范](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [发布细则](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)

## 理解 CLI 输出与失败

--json 只选择命令结果格式；信任检查仍可能向 stdout 写出警告。通过 npm run market 调用时，npm 也可能输出脚本 banner。因此不要对整段 stdout 直接 JSON.parse，也不要假设存在清理所有输出的专用标志。文件导出使用 --out=\<file\>，命令成功后读取该文件再解析；保留退出码和诊断输出。

install 是生成 Fleet 配置文件，不会把 Bot 写入运行中的 App。本包装器要求显式填写目标 --openbot，不会检测运行中宿主的版本。npm run market -- help 显示用法及 0.9.9 示例，不表示当前宿主或默认规划版本。重试前，从目标宿主自身的版本信息核实实际版本；若版本未知，先停止兼容规划，不猜填 0.9.9 或默认值。接受社区内容及未固定信任源须由使用者明确选择，不能靠修复参数错误自动增加接受标志。

| 失败或现象 | 真实含义与恢复 |
| --- | --- |
| plan / install 缺 --openbot | 报错以 Provide --openbot=\<target-version\> 开头。本包装器要求实际目标版本，不检测运行中宿主。先核对目标宿主自身的版本信息，再补 --openbot=\<target-version\> 重试；未知时停止兼容规划，不照抄帮助示例或猜默认值。 |
| install 缺 --out | 报错为 Provide --out=\<file\>; this command generates a configuration file and does not install into your App. 选择可写的新目标文件路径，补 --out=\<file\>，并保留正确的 --openbot。两者都缺时先遇到 --out 错误。 |
| --out= 或 --out 后无路径 | 报错为 --out requires a file path。给出非空文件路径；单独的标志不代表自动选择路径。 |
| stdout 在 JSON 前出现警告或 banner | 这是输出混合，不等于 Fleet 文件损坏。检查退出码，阅读警告；导出结果从 --out 文件读取，查看本包装器帮助用 npm run market -- help。 |

## 参考来源

来源核对日期: 2026-10-25

- [贡献规范](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [实际 CLI 包装器](https://github.com/Harzva/awesome-bot/blob/main/scripts/market.mjs)
- [CI 与发布规则](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)
- [完整条目实例](https://github.com/Harzva/awesome-bot/blob/main/data/entries/status-report-writer.json)