# Awesome Bot 使用手册

为新手、团队与开发者提供从第一件小事到角色交接和版本发布的操作指南。先读懂配置，再用材料和验收把任务做实。

## 按你的目标阅读

### 新手：先交付一个结果

理解入口，完成虚构练习，再选择配置。

1. [完成第一件小事](https://harzva.github.io/awesome-bot/handbook-start.html?path=start)
2. [分清角色、任务和权限](https://harzva.github.io/awesome-bot/handbook-concepts.html?path=start)
3. [把需求写成可验收任务](https://harzva.github.io/awesome-bot/handbook-instructions.html?path=start)
4. [选择、下载与导入](https://harzva.github.io/awesome-bot/handbook-choose-import.html?path=start)
5. [按场景完成一件事](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=start)
6. [先定位问题在哪一层](https://harzva.github.io/awesome-bot/handbook-troubleshooting.html?path=start)

- [从一份虚构周报开始](https://harzva.github.io/awesome-bot/handbook-start.html?path=start#exercise)
- [再练：区分交付、测试与验收](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=start#practice-weekly-report)

#### 路径末章：人工验收

这是阅读位置，不代表任务已完成。请对照实际结果逐项检查；需要时返回相关章节或练习。

- [核对每项结论的来源，保留未知项；参考示例不必逐字照抄。](https://harzva.github.io/awesome-bot/handbook-start.html?path=start#accept)
- [针对一个具体缺口修订，再保存自己的任务、材料与结果。](https://harzva.github.io/awesome-bot/handbook-instructions.html?path=start#iterate)
- [能分清阅读、下载与宿主导入；如有导入，保留本次核对记录。](https://harzva.github.io/awesome-bot/handbook-choose-import.html?path=start#compare)

### 团队：明确职责与交接

用角色分工、任务卡和审阅人组织协作。

1. [分清角色、任务和权限](https://harzva.github.io/awesome-bot/handbook-concepts.html?path=team)
2. [让团队交接可追踪](https://harzva.github.io/awesome-bot/handbook-team.html?path=team)
3. [把需求写成可验收任务](https://harzva.github.io/awesome-bot/handbook-instructions.html?path=team)
4. [按场景完成一件事](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=team)
5. [让 Agent 按需读取角色](https://harzva.github.io/awesome-bot/handbook-agents.html?path=team)
6. [先定位问题在哪一层](https://harzva.github.io/awesome-bot/handbook-troubleshooting.html?path=team)

- [先练一次退回、修订与重新接收](https://harzva.github.io/awesome-bot/handbook-team.html?path=team#handoff)
- [接着交接事实表与会前简报](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=team#practice-customer-meeting)

#### 路径末章：人工验收

这是阅读位置，不代表任务已完成。请对照实际结果逐项检查；需要时返回相关章节或练习。

- [本次任务有明确的负责人、接收者和审阅人。](https://harzva.github.io/awesome-bot/handbook-team.html?path=team#owners)
- [能追踪退回原因、补齐材料和接受的版本；旧产物已重新核对。](https://harzva.github.io/awesome-bot/handbook-team.html?path=team#handoff)
- [交给下一角色的材料保留来源与未知项；事实表和最终简报分别验收。](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=team#practice-customer-meeting)

### 开发者：读取、校验和贡献

从本地快照校验与缺陷复验练习入手，再查贡献、排错和格式契约。

1. [分清角色、任务和权限](https://harzva.github.io/awesome-bot/handbook-concepts.html?path=developer)
2. [按场景完成一件事](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=developer)
3. [让 Agent 按需读取角色](https://harzva.github.io/awesome-bot/handbook-agents.html?path=developer)
4. [贡献、构建与发布](https://harzva.github.io/awesome-bot/handbook-contribute.html?path=developer)
5. [先定位问题在哪一层](https://harzva.github.io/awesome-bot/handbook-troubleshooting.html?path=developer)
6. [术语、许可与来源](https://harzva.github.io/awesome-bot/handbook-reference.html?path=developer)

- [运行本地快照正例与失败例](https://harzva.github.io/awesome-bot/handbook-agents.html?path=developer#local-lab)
- [练习编写有边界的复验计划](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=developer#practice-bug-retest)

#### 路径末章：人工验收

这是阅读位置，不代表任务已完成。请对照实际结果逐项检查；需要时返回相关章节或练习。

- [本地校验依次出现两行 PASS，退出码为 0；篡改副本被拒绝，原文件保持不变。](https://harzva.github.io/awesome-bot/handbook-agents.html?path=developer#local-lab)
- [能区分复验计划和真实测试结果，记录当前缺少的环境或证据。](https://harzva.github.io/awesome-bot/handbook-scenarios.html?path=developer#practice-bug-retest)
- [如有贡献，检查双语生成物与版本契约，并保存可复现的验证记录。](https://harzva.github.io/awesome-bot/handbook-contribute.html?path=developer#checks)

## 完成第一件小事

用虚构材料交付一份可检查的短报告。

### 选择学习路径

新手先做本章练习；团队读完基础概念后安排交接；开发者可直接进入本地快照实验。按路径阅读时，章末会接到本路径的下一章。无需下载整个目录。

- [新手：开始本章练习](https://harzva.github.io/awesome-bot/handbook-start.html?path=start#exercise)
- [团队协作](https://harzva.github.io/awesome-bot/handbook-team.html?path=team)
- [开发者：本地快照实验](https://harzva.github.io/awesome-bot/handbook-agents.html?path=developer#local-lab)

开始前：已有能处理文本的 Agent 就能练习，无需先购买账号。Copy for Agent 是复制上下文，下载是保存文件，导入是让宿主读取配置；三者是不同动作。导入入口以实际宿主为准。

### 用虚构材料写一次周报

先完整复制下方“练习任务与材料”，贴给当前能处理文本的 Agent，生成第一份周报草稿；这一步无需下载或导入，也不需要连接真实邮箱或项目账号。可选用“进度报告编辑”的角色资料，仍服从 Agent 的原有指令。

#### 练习任务与材料

```text
请根据虚构材料写一份不超过180字的周报草稿。
目标：周五交付报名页。
记录A（周三）：表单页面已完成，尚未测试。
记录B（周四）：桌面测试通过；手机测试未开始。
记录C（周四）：文案等待小林确认，预计周五上午回复。
产物：目标、已验证进展、待验收、阻塞、下一步五项。
验收：引用A/B/C；不把页面完成写成全部验收；缺负责人时标待确认。
边界：只出草稿，不发布、不联系任何人。
```

以下是预先编写的教学参考，不是实际 Bot 运行结果。措辞不必一致，但五项和证据边界应保留；编号对应原记录。

#### 教学参考节选

```text
目标：周五交付报名页。
已验证进展：表单完成[A]，桌面测试通过[B]。
待验收：手机测试未开始[B]。
阻塞：文案待小林确认，预计周五上午回复[C]。
下一步：补手机测试，负责人待确认；跟进文案，再验收。
```

错误句：“报名页已全部验收。”定点修订提示：“只修订这句：桌面已通过；手机未开始；文案待确认。引用B/C，不改其他已核对内容。”

### 检查结果并修订

1. 核对五项是否齐全，桌面和手机测试是否分开。
2. 每个完成声明都要有记录；删除无依据的句子或标为未知。
3. 只指出具体缺口，让 Agent 修订这份草稿，再保存任务和结果。

### 换成自己的材料

替换目标、记录与验收条件，再用少量脱敏材料试一次。读取真实文件或账号前，在宿主中确认工具与本次任务授权。一次练习成功不代表所有账号任务都已认证。

- [找进度报告编辑](https://harzva.github.io/awesome-bot/?bot=awesome%2Fstatus-report-writer)
- [选择与导入](https://harzva.github.io/awesome-bot/handbook-choose-import.html)

### 参考来源

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

- [首次使用指南](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)
- [练习角色来源](https://github.com/Harzva/awesome-bot/blob/main/data/entries/status-report-writer.json)

## 分清角色、任务和权限

认清入口和文件，才能选择正确的下一步。

### 本站有哪些资源

目录含 371 个配置：315 个角色与 56 个任务流程；另有 17044 条 Shared Bots 来源链接。数量表示覆盖范围，不是安装数量或任务成功率。

| 资源 | 用途 | 下一步 |
| --- | --- | --- |
| 角色配置 | 长期职责与方法 | 按职责选择 |
| 任务流程 | 围绕产物的步骤 | 提供材料发起任务 |
| Shared Bots | 原站或来源文件链接 | 到来源查看条件 |
| 项目参考 | 外部软件和架构资料 | 独立评估接入方式 |

### 文字不等于运行能力

配置描述角色与需求；模型负责生成和推理；宿主提供环境、工具和账号授权。“读取邮件”是资料需求，不会自动连接邮箱。

1. 查看输入、产物和前提。
2. 核对宿主实际模型、工具及账号。
3. 缺少能力时提供可用材料或列出缺口。

### 配置不会迁移私有状态

配置不包含聊天、已学记忆、模型密钥、真实账号连接或运行中的任务。普通导出关闭工具和容器标志；空库首个 Bot 可能被宿主选为主 Bot，按宿主规则具有管理能力。导入前应核对预览中的主身份与权限表现。

### 如何理解验证说明

来源核查回答内容从哪里来；格式与导出测试检查本仓契约；真实账号任务则需要单独的输入、执行与结果证据。本站没有逐项认证所有角色的账号任务。

- [接入契约](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)

### 参考来源

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

- [项目说明](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [宿主接入契约](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [市场整合说明](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

## 选择、下载与导入

先检查职责、来源和配置，再经过宿主预览与确认。

### 从需要的产物开始

1. 搜索会议准备、缺陷复测或周报等目标。
2. 打开详情，比较职责、输入、产物、技能、来源与权限需求。
3. 先选一个角色，需要第二个时再明确交接。
4. 检查正文语言与平台前提，尤其是英文来源适配。

按持续职责和方法选 bot-role；需要围绕产物的步骤模板时选 task-workflow，模板可按需要重复使用。两者都要在宿主预览确认，再核对工具、账号与人工交接；任务流程本身不提供自动编排或已验证的运行状态，验收仍看具体产物。

### 选对下载形式

| 情况 | 建议 |
| --- | --- |
| 初次使用 | 单角色或小场景下载 |
| 需要英文内容 | 在英文模式选择对应配置 |
| 大型合集 | 用发布分片，每个 Fleet 文件最多200个 Bot |
| 只让 Agent 参考方法 | 使用 Copy for Agent 或单角色资料 |

Shared Bots 是来源链接，不是本站可安装配置。名称相同不能证明同一身份，应核对作者、平台和地址。

### 在宿主预览与确认

1. 保存文件和角色 ID、版本、语言、配置摘要。
2. 使用宿主当前配置导入入口，选择 Fleet 文件并阅读预览与确认。
3. 核对新增名称、重名处理和现有主 Bot 状态。
4. 确认后另行设置模型、工具和账号，再发起明确任务。

本仓 README 记录过 Settings → Data & Sync → Import configuration 示例；入口以当前宿主版本为准。下载和导入本身都不启动任务或环境。

### 导入后再核对

- 按 ID 对照职责，不能仅凭同名确认。
- 记录宿主实际返回的 Bot ID，为后续升级对账。
- 先用虚构短任务验收，再提供真实材料。

- [配置市场](https://harzva.github.io/awesome-bot/)
- [排错](https://harzva.github.io/awesome-bot/handbook-troubleshooting.html)

每次导入在本地或受限团队台账追加一条记录，不覆盖历史；升级时关联原记录 ID。来源身份与宿主实际身份分开填，不把来源 ID 当作新 Bot ID。宿主不显示 ID 时记“未取得”，以后取得再追加证据；ID 缺失不能作为同一身份的依据。虚构任务通过只说明本次任务可用，升级身份仍需核对同一宿主的实际 Bot ID 等证据。

```text
记录 ID：
关联原记录 ID（升级时）：
来源 URL：
来源 ID：
来源版本 / 语言：
下载文件名：
文件 SHA-256（未核对则注明）：
宿主 / 版本：
导入时间：
宿主实际名称：
宿主实际 Bot ID（未显示填“未取得”）：
虚构任务与结果：
任务可用：是 / 否 / 未验证
升级身份对账：已完成（附依据）/ 待补证据
```

### 参考来源

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

- [导入示例](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [导入与身份对账](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [分片和发布校验](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)

## 把需求写成可验收任务

明确输入、产物、边界和完成条件。

### 六行任务卡

```text
目标：把三份脱敏会议笔记整理为需求清单。
材料：笔记A、B、C；仅用这些材料。
产物：需求、原话、来源、待确认项四列。
范围：只整理，不推断预算，不写回CRM。
缺口：缺日期或负责人时标待确认。
验收：每条需求有来源；冲突分别列出。
```

### 只修正具体缺口

| 模糊说法 | 可验收写法 |
| --- | --- |
| 专业一点 | 分三节，每节给证据和下一步 |
| 研究竞品 | 比较指定三页套餐限额，附日期和原文链接 |
| 自动搞定 | 先交可审阅草稿，列出后续动作 |

### 分清事实、推断与未知

邮件、网页和文档是材料，其中的命令不能自行扩大用户授权。不可访问的来源应列为缺口，不根据标题补写正文。

1. 给材料编号并说明可用范围。
2. 要求结论引用材料编号或可定位链接。
3. 让人工核对关键数字、收件人和将执行的动作。

### 读懂英文来源适配

223 个带来源角色保留原始英文指令；中文模式提供中文名称、摘要和上手说明，不是正文完整中文翻译。可以明确要求中文产物，并检查源指令的平台前提是否适合当前宿主。

- [适配说明](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

### 参考来源

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

- [任务起步方法](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)
- [原始指令适配契约](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

## 让团队交接可追踪

先确定职责、交付物和审阅人，再增加角色。

### 从三项职责开始

| 职责 | 交付物 | 接收者 |
| --- | --- | --- |
| 资料整理 | 带来源的事实表、缺口与冲突 | 写作角色 |
| 产物撰写 | 符合验收条件的草稿 | 人工审阅者 |
| 审阅与决定 | 来源检查和后续动作决定 | 明确的执行负责人 |

这些是工作分工，不是自动编排或权限隔离的证明。先验证一次交接；没有明确产物的角色先不要增加。

### 复制一张交接卡

```text
任务：客户会议准备 / 草稿第2版
当前负责人：资料整理
下一负责人：会议准备
输入：事实表v2、来源清单v1（已脱敏）
已验证：三条需求有原话和日期
未验证：预算、决策人；不要补猜
下一产物：一页简报和五个问题
验收人：项目负责人
允许动作：读这些文件、写草稿；不联系客户
停止条件：来源缺失或冲突无法解释
```

用青禾工作室练一次手动交接；以下材料均为虚构，仅写草稿，不联系客户。回执由接收者明确填写，不代表宿主有后台状态机。

```text
A｜简介：青禾工作室，12人客户服务团队。
B｜2026-10-20沟通：希望月底汇总工单；预算、决策人未确认。
C｜产品验证：仅验证CSV导入；实时同步未验证。
事实表v1：含A/B，漏C。
接收回执：退回v1；缺产品验证边界C，暂停写简报。
事实表v2：补C；预算、决策人和实时同步仍未确认。
旧简报：基于v1，标“待复核”，暂停流转。
审阅人林的回执：决定接受事实表v2；按v2重核简报草稿后再交审阅。
```

停止：缺来源、版本不清或冲突未解释。恢复：补齐材料，审阅人林写明接受的版本；旧产物标待复核，完成重核后才交下一人。接受事实表不等于简报或产品已验收。

### 共享配置不等于共享记忆

共享配置只传递角色定义和方法，不携带创作者的聊天、学习记忆、账号或密钥。项目背景使用有明确版本的脱敏资料包，注明可分享范围，由接收者在自己的授权环境中使用。

1. 把稳定方法放入配置，项目事实放入资料包。
2. 列出具体文件与版本，不假定对方已知背景。
3. 确认材料可读，审阅输出后再推进。

### 以 gitopsbot 为协作案例

gitopsbot 的双语手册讨论 GitHub 到飞书的路由、签名、去重、回执和恢复。先整理仓库、事件、目标群、发送方与权限缺口表。下载角色不会建立监听器、接入账号或授予群发送权。

- [打开 gitopsbot](https://harzva.github.io/awesome-bot/?bot=awesome%2Fgitopsbot)
- [部署与运维手册](https://github.com/Harzva/awesome-bot/blob/main/docs/gitopsbot-playbook.md)

### 参考来源

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

- [场景与人工交接](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [状态与权限契约](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [gitopsbot 运维方法](https://github.com/Harzva/awesome-bot/blob/main/docs/gitopsbot-playbook.en.md)

## 按场景完成一件事

用材料、步骤、产物和验收组织一次任务。

### 按产物选择场景

本站有 5 个中英对齐场景：客户会议、周报、缺陷复测、反馈转需求和产品发布。每个场景提供少量相关角色和可复制的首任务。

先看角色与原始任务，再用下面的虚构材料练一次。五份参考产物均为预先编写的教学示例，按证据核对，不要求措辞相同。

- [实战：从事实表到会前简报](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-customer-meeting)
- [实战：把交付、测试与验收分开](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-weekly-report)
- [实战：没有环境时先做复验计划](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-bug-retest)
- [实战：把重复与冲突反馈变成候选需求](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-feedback-to-requirements)
- [实战：证据不足时暂缓发布](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-product-launch)

### 场景材料与任务卡

#### 复现缺陷并安排复验

把问题反馈转成最小复现，再核对受影响的关键路径和上线阻塞。

##### 准备材料

- 问题描述、预期行为、发生频率和最小输入
- 指定代码或可测试版本、平台及环境信息
- 允许使用的测试环境、数据、账号与界面
- 核心用户任务、上线条件和已知修复

##### 预期交付

- 最小复现步骤、日志及环境信息
- 已证实情况与待验证的定位假设
- 关键路径检查记录、上线阻塞和复验顺序

##### 1. [缺陷复现工程师](https://harzva.github.io/awesome-bot/?scenario=bug-retest&bot=awesome%2Fbug-reproduction)

```text
请先帮助复现这个缺陷。问题与预期行为：[填写]；指定版本和平台：[填写]；最小输入或样本：[提供获准数据]；允许的测试环境与操作范围：[填写]。记录实际与预期差异，逐步缩减触发条件，保留日志和环境信息，区分已证实原因与假设。没有必要工具或环境时说明缺口，提供可由我执行的步骤，不声称已完成复现。
```

交接: 由我核对复现证据，把可重复步骤、影响范围和已确认修复交给创业产品质量检查员。

##### 2. [创业产品质量检查员](https://harzva.github.io/awesome-bot/?scenario=bug-retest&bot=awesome%2Fgrok-startup-qa-bot)

```text
基于以下已核对的缺陷复现和修复信息，检查受影响的核心用户路径并安排复验。复现与修复：[粘贴]；可测试版本和核心任务：[填写]；上线条件、测试账号与获准界面操作范围：[填写]。记录正常、空白和错误路径中的真实发现，列上线阻塞及逐项复验方法；未实际操作或未验证的项目明确标为待检查，不访问未授权环境。
```

交接: 由我和发布负责人审阅检查证据、阻塞与复验结果，决定是否满足上线条件。

[在市场中查看](https://harzva.github.io/awesome-bot/?scenario=bug-retest) · [下载场景配置](https://harzva.github.io/awesome-bot/exports/scenario-bug-retest.fleet.json) · [用虚构材料练习](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-bug-retest)

#### 准备客户会谈

先核对公司背景，再整理这次会谈的议程、证据和待确认问题。

##### 准备材料

- 目标公司、研究目的及产品适配条件
- 获准使用的公司资料、来源和历史沟通记录
- 会谈目标、参会人、产品资料和可承诺范围

##### 预期交付

- 注明来源与日期的公司研究简报
- 区分事实和假设的需求信号
- 一页会前简报、议程、问题清单和材料待办

##### 1. [客户研究专员](https://harzva.github.io/awesome-bot/?scenario=customer-meeting&bot=awesome%2Faccount-research-specialist)

```text
我要为客户会谈准备公司研究简报。目标公司与研究目的：[填写]；产品及适配条件：[填写]；获准资料与来源：[粘贴或提供已授权位置]。核对公司主体、业务和近期变化，注明来源与日期；把事实、需求信号和购买假设分开。资料不足时先列待补信息，不声称访问了未连接的来源。
```

交接: 由我核对简报，将已确认的背景、需求信号和待核实假设交给销售会前准备员。

##### 2. [销售会前准备员](https://harzva.github.io/awesome-bot/?scenario=customer-meeting&bot=awesome%2Fmeeting-prep-buddy)

```text
请结合以下已审阅的公司研究简报、历史沟通、参会人和会议目标，准备一页会前简报、议程、关键问题和材料待办。公司研究简报：[粘贴]；参会人及会议目标：[填写]；产品证据和可承诺范围：[填写]。区分客户事实、我们的假设和需要内部确认的承诺，不替我发送消息或安排会议。
```

交接: 由我审阅会前材料并确认承诺范围，再用于实际会谈。

[在市场中查看](https://harzva.github.io/awesome-bot/?scenario=customer-meeting) · [下载场景配置](https://harzva.github.io/awesome-bot/exports/scenario-customer-meeting.fleet.json) · [用虚构材料练习](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-customer-meeting)

#### 把反馈整理成需求

先识别反馈主题和用户影响，再归并成可追踪、待澄清的需求清单。

##### 准备材料

- 获准使用的反馈、工单及其时间和来源
- 产品与用户分组、已知问题和近期变更
- 已有需求库及需求关联信息

##### 预期交付

- 保留原始证据的反馈主题与用户任务
- 归并去重的需求清单和影响范围
- 验证建议与待澄清问题，不承诺开发排期

##### 1. [产品反馈分析员](https://harzva.github.io/awesome-bot/?scenario=feedback-to-requirements&bot=awesome%2Fproduct-feedback-analyst)

```text
请分析这批获准反馈。反馈记录及来源时间：[粘贴]；产品与用户分组：[填写]；已知问题和近期变更：[填写]。按用户情境、目标、阻碍和影响归并主题，保留原始证据与矛盾反馈，说明样本覆盖和缺失信息。给出可验证改进建议，不直接承诺开发排期。
```

交接: 由我检查主题与原始记录的对应关系，将已确认主题和证据交给功能请求跟踪员。

##### 2. [功能请求跟踪员](https://harzva.github.io/awesome-bot/?scenario=feedback-to-requirements&bot=awesome%2Ffeature-request-tracker)

```text
把以下已审阅的反馈主题与原始证据整理为需求清单。反馈主题与证据：[粘贴]；已有需求库：[提供获准记录]；客户和产品分组：[填写]。合并重复诉求并关联已有需求，保留具体问题场景、影响范围和待澄清问题。区分需求事实与优先级建议，不代替产品负责人承诺排期或更改需求库。
```

交接: 由我和产品负责人审阅需求、补充核实信息，再决定优先级与是否落库。

[在市场中查看](https://harzva.github.io/awesome-bot/?scenario=feedback-to-requirements) · [下载场景配置](https://harzva.github.io/awesome-bot/exports/scenario-feedback-to-requirements.fleet.json) · [用虚构材料练习](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-feedback-to-requirements)

#### 准备产品上市材料

从客户问题和产品证据组织定位，再倒排素材、审核和渠道发布日历。

##### 准备材料

- 目标客群、需求证据与替代方案
- 产品能力、限制和可以证明的差异
- 上市目标、截止时间、已有素材和渠道
- 制作、审核负责人及不可移动的节点

##### 预期交付

- 定位和价值表述、受众信息矩阵
- 上市内容需求及验证计划
- 营销日历、依赖冲突和检查点

##### 1. [产品定位与上市策划员](https://harzva.github.io/awesome-bot/?scenario=product-launch&bot=awesome%2Fgrok-product-marketer)

```text
请为产品上市准备定位草案。目标客群与需求证据：[填写]；产品能力、限制和差异证据：[填写]；上市目标与已有素材：[填写]。把客户任务、替代方案与可证明的价值对应，组织受众信息和内容需求；未证明的主张保留为假设，列出后续验证计划，不编造客户证言或效果数据。
```

交接: 由我审阅定位与证据，将已确认的受众信息、内容需求和验证计划交给营销排期管理员。

##### 2. [营销排期管理员](https://harzva.github.io/awesome-bot/?scenario=product-launch&bot=awesome%2Fmarketing-calendar-owner)

```text
请按以下已审阅的上市内容需求倒排营销日历。定位与内容需求：[粘贴]；上市目标及截止时间：[填写]；渠道与素材清单：[填写]；制作和审核负责人、固定节点：[填写]。标出制作、审核和渠道依赖、资源冲突与缺口，为每项记录负责人和检查点。仅准备可审阅计划，不替我发布内容、发送消息或承诺未确认日期。
```

交接: 由我和相关负责人确认日历、资源与审核安排，再按已授权流程执行发布。

[在市场中查看](https://harzva.github.io/awesome-bot/?scenario=product-launch) · [下载场景配置](https://harzva.github.io/awesome-bot/exports/scenario-product-launch.fleet.json) · [用虚构材料练习](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-product-launch)

#### 写一份有证据的周报

用一个 Bot 把项目产物、验证和阻塞整理成清楚的状态报告草稿。

##### 准备材料

- 本周报告周期、项目目标和里程碑
- 已完成产物、测试结果与验收记录
- 正在进行的事项、阻塞和计划变更
- 下阶段计划、待决策问题和负责人

##### 预期交付

- 区分已交付、待验收、进行中和受阻的周报草稿
- 有证据的风险说明与决策请求
- 下一阶段行动与负责人

##### 1. [进度报告编辑](https://harzva.github.io/awesome-bot/?scenario=weekly-report&bot=awesome%2Fstatus-report-writer)

```text
请根据以下项目事实写本周状态报告草稿。报告周期、目标与里程碑：[填写]；产物、测试和验收记录：[粘贴]；进行中事项、阻塞和计划变更：[填写]；下阶段行动与待决策问题：[填写]。分清已交付、待验收、进行中和受阻，给结论保留证据，明确偏差、风险和所需决策；没有证据的进展保留未知，不把测试通过写成业务已验收。
```

交接: 由我核对证据、负责人和决策请求，修改确认后再向相应读者发送。

[在市场中查看](https://harzva.github.io/awesome-bot/?scenario=weekly-report) · [下载场景配置](https://harzva.github.io/awesome-bot/exports/scenario-weekly-report.fleet.json) · [用虚构材料练习](https://harzva.github.io/awesome-bot/handbook-scenarios.html#practice-weekly-report)

### 实战：从事实表到会前简报

适合新手与团队交接。以下材料全部虚构；参考产物是预先编写的教学示例，不是 Bot 运行结果。复制材料，先做来源事实表，再整理一页会前简报及五个问题；仅出内部草稿，不作客户承诺。

#### 练习任务与材料

```text
任务：作为客户研究专员，只用以下虚构材料，整理供会前准备使用的事实表。
产物：事实、来源编号与日期、需求信号、待核实假设四列。未提供的日期、预算与决策人明确标未知；不得推断采购意向。
边界：仅写内部草稿；不联系客户、不报价、不承诺未经验证的能力。

虚构材料：
A｜公司简介，2026-10-19：青禾工作室是12人的客户服务团队。
B｜沟通记录，2026-10-20：希望月底汇总工单；预算、决策人未知。
C｜内部演示记录，2026-10-21：仅验证CSV导入；实时同步未验证。
D｜会谈目标，2026-10-23：澄清汇总口径、数据来源与试用条件。
E｜参会信息：我方客户经理；客户参会人和职责待确认。
F｜范围：仅用A—E；不得推断采购意愿、报价或承诺实时同步。
```

1. 把A—F交给客户研究专员（awesome/account-research-specialist）：按“事实／来源日期／需求信号／待核实假设”建表。
2. 人工核对每行后，将事实表、B/C原文及未知项交给销售会前准备员（awesome/meeting-prep-buddy）；要求一页简报，含议程、恰好五个问题和材料待办。
3. 人工审阅承诺范围后保存草稿；问题和待办由参会人确认，不自动发给客户。

#### 教学参考节选

```text
背景：青禾工作室，12人客户服务团队（A，2026-10-19）。
目标与议程：澄清月底工单汇总（B）；核对口径→数据→试用条件（D）。
能力边界：CSV导入已在虚构内部记录验证；实时同步待验证（C）；预算、决策人未知（B）。
五问题：汇总哪些字段？以哪个日期划月？数据从哪里导出？谁决定试用？预算与评估标准是什么？
材料待办：我方客户经理准备CSV样例与演示范围；客户参会人/职责待确认（C/E）。
```

1. 逐行保留材料编号；已有日期照录，未提供则标未提供。事实、需求信号、假设分列，不能把希望汇总写成采购意向。
2. 一页草稿含议程、五问题和材料待办；五问题覆盖口径、日期、来源、决策与预算。
3. 保留预算/决策人未知、实时同步未验证；没有对外承诺或已发送声明。

#### 修订要求

```text
只修缺口：保留已核对事实表。将“支持实时同步”改为“待验证（C）”；补齐缺失的来源或五问题中的缺项，仅返回受影响行和修订后简报，不补造客户信息。 审阅人若发现缺口，退回产出该内容的角色；人工复核修订后再交接或保存，不自动流转。
```

- [查看场景任务卡](https://harzva.github.io/awesome-bot/handbook-scenarios.html#scenario-customer-meeting)
- [在市场查看所需角色](https://harzva.github.io/awesome-bot/?scenario=customer-meeting)

### 实战：把交付、测试与验收分开

适合新手练习与团队汇报。以下材料全部虚构；参考产物是预先编写的教学示例，不是 Bot 运行结果。复制记录，写2026-10-19至2026-10-23周报草稿，保留证据编号；不得把旧成果或技术测试写成当周业务验收。

#### 练习任务与材料

```text
任务：作为进度报告编辑，只用以下虚构记录写2026-10-19至2026-10-23的周报草稿。
产物：本周交付、技术验证、业务待验收、旧成果、阻塞与下一步五项，每个状态附材料编号。缺失的负责人和日期标未知，并提出指派请求。
边界：不把技术测试写成业务验收，不把旧成果记作本周新交付；只写草稿，不发送。

虚构材料：
A｜本周目标：2026-10-23交付报名页草稿，业务验收另约。
B｜2026-10-20：小陈提交报名页v0.3草稿与交付记录。
C｜2026-10-21：技术记录显示桌面8项测试通过；手机测试未开始。
D｜2026-10-23：业务方尚未验收，未提供通过记录。
E｜2026-10-16：上周已完成报名字段表，不计本周新增交付。
F｜2026-10-22：法务文案待确认，尚无负责人及回复日期。
G｜下一步：小陈计划2026-10-26执行手机测试；文案责任人待指派。
```

1. 交给进度报告编辑（awesome/status-report-writer）：按本周交付、技术验证、业务待验收、旧成果、阻塞/下一步分组，每项附编号。
2. 由报告负责人核对周期与证据；把无人负责的文案列为“请求指派”，确认后再向相应读者发送。

#### 教学参考节选

```text
周期：2026-10-19—2026-10-23；报名页v0.3草稿已交付（A/B）。
技术验证：桌面8项通过；手机未测（C）。
业务状态：尚未验收（D）；不得标记项目全部完成。
旧成果：字段表于2026-10-16完成，仅作背景（E）。
阻塞/行动：文案负责人和回复日期待指派（F）；小陈计划2026-10-26测手机（G）。
```

1. 交付仅计B，E单独标上周；周期与下一步日期不混用。
2. 8项只属于桌面技术测试；手机和业务验收状态分别保留。
3. 每个状态有证据编号；F负责人/日期保持未知并提出指派请求，不擅填人名。

#### 修订要求

```text
只修缺口：保留已引用的交付记录。把“已全部验收”拆成C技术验证与D待验收；把E移到历史背景；为F补指派请求。仅返回修改的段落，不重写已通过项。 审阅人若发现缺口，退回产出该内容的角色；人工复核修订后再交接或保存，不自动流转。
```

- [查看场景任务卡](https://harzva.github.io/awesome-bot/handbook-scenarios.html#scenario-weekly-report)
- [在市场查看所需角色](https://harzva.github.io/awesome-bot/?scenario=weekly-report)

### 实战：没有环境时先做复验计划

适合开发者与团队交接。以下浏览器反馈、日志、版本均为虚构；参考产物是预先编写的教学示例，不是 Bot 运行结果。本练习无真实测试环境，只练计划与证据分类，所有执行状态为待执行，不能写已复现或已修复。

#### 练习任务与材料

```text
任务：作为缺陷复现工程师，只用以下虚构材料编写最小复现计划。当前没有真实测试环境，不执行测试。
产物：区分反馈、日志线索与修复假设；列单击对照、双击和重复试验，保留预期/实际、次数、版本、环境与证据的空白记录栏，并列缺失环境。
边界：执行项全部标待执行；两条日志不能直接证明根因，不声称已复现、已修复或可上线。

虚构材料：
A｜虚构反馈，2026-10-21：Chrome 129 / macOS 14，草稿版v0.3；点两次提交后看到两个报名条目。
B｜预期：同一提交意图只产生一个条目；反馈人称偶发，未统计频率。
C｜虚构日志：10:02:01 POST /signup 201；10:02:01 POST /signup 201；无请求ID。
D｜最小输入：姓名“测试甲”、邮箱 test@example.invalid；仅用于计划。
E｜开发备注：候选版v0.3.1增加提交中禁用按钮；没有修复验证记录。
F｜核心路径：正常、空白、失败重试；真实环境、账号、实际版本均未提供。
G｜上线条件：原版可重复证据、候选版同条件复验及三条路径记录经负责人审阅。
```

1. 交给缺陷复现工程师（awesome/bug-reproduction）：把A/B列为报告、C列为虚构日志线索、E列为修复假设；给出单击对照→双击→重复试验的最小计划，列明缺失环境。
2. 人工核对后，将计划、未验证假设和空白执行栏交给创业产品质量检查员（awesome/grok-startup-qa-bot），排正常/空白/失败重试与候选版复验顺序，全部标待执行。
3. 实际执行者另行取得获准环境后填记录；发布负责人按真实证据判定，不用这份虚构示例作为通过记录。

#### 教学参考节选

```text
分类：A/B为反馈，C为虚构日志线索，E为候选修复说明；均不证明原因。
计划：固定输入D；原版单击对照、双击并记录每轮结果；候选版按相同条件复验。
检查：正常→空白→失败重试；当前全部待执行（F）。
实际执行者填写：姓名___ 日期___ 版本/环境___ 次数___ 预期/实际___ 日志/截图位置___。
完成条件：原版可重复证据、候选版结果、三路径记录齐全，失败项关闭且发布负责人签核（G）。
```

1. 计划明确单击对照、双击、重复次数需记录；两条201日志不能直接证明双条目或根因。
2. 原版、候选版与三路径都有待执行项；保留实际执行者、日期、环境、版本、结果和证据栏。
3. 无真实运行时不出现已复现/已修复/可上线结论；真实完成须满足G并核对实际记录。

#### 修订要求

```text
只修缺口：保留已有计划。将无证据的“已复现/已修复”改为“待实际执行”；只补缺失的对照、路径或记录栏，并指出还需要哪份真实证据，不生成执行结果。 审阅人若发现缺口，退回产出该内容的角色；人工复核修订后再交接或保存，不自动流转。
```

- [查看场景任务卡](https://harzva.github.io/awesome-bot/handbook-scenarios.html#scenario-bug-retest)
- [在市场查看所需角色](https://harzva.github.io/awesome-bot/?scenario=bug-retest)

### 实战：把重复与冲突反馈变成候选需求

适合团队交接，新手可先核对来源。以下材料全部虚构；参考产物是预先编写的教学示例，不是 Bot 运行结果。复制记录，形成有追溯的需求候选及待确认优先级；少数样本不能推出多数需求，不承诺排期或直接写入需求库。

#### 练习任务与材料

```text
任务：作为产品反馈分析员，只用以下虚构记录整理反馈主题，供人工核对后再交给功能请求跟踪员。
产物：主题、用户任务、原始编号与原话、去重关系、冲突及样本缺口。A/B只计同一事件；C/E为同人不同事，分别保留。
边界：不把3人样本写成多数需求，不决定优先级、承诺排期或改写需求库。

虚构材料：
A｜工单T01，2026-10-19，用户U1/管理员：每周导出CSV太费步骤，想一键导出。
B｜邮件M01，2026-10-20，用户U1：再次转发T01，同一事件。
C｜工单T02，2026-10-20，用户U2/管理员：希望直接默认展示全部成员。
D｜访谈I01，2026-10-21，用户U3/普通成员：不要默认显示全部成员，担心暴露名单。
E｜工单T03，2026-10-22，用户U2：CSV导出找不到入口；与T02是不同问题。
F｜已有需求R07：简化CSV导出，状态待评审；近期仅调整导航名称。
G｜范围：3名用户、2种角色；总用户数、代表性、影响频次与优先级均未知。
```

1. 先交产品反馈分析员（awesome/product-feedback-analyst）：保留编号与原话，A/B归为同一事件；分别整理导出任务与成员可见性冲突，说明样本缺口。
2. 人工核对主题后交功能请求跟踪员（awesome/feature-request-tracker）：把A/E关联R07，不因同一用户而合并C/E；形成需求候选、来源、冲突、验证方法与待确认优先级。
3. 产品负责人核实影响与权限规则后决定优先级和是否落库；保留未决问题。

#### 教学参考节选

```text
去重：A/B同一事件，保留两来源，计1个事件；不能算两名用户。
候选R07补充：简化并明确CSV导出入口，证据A/E，2名用户；保留操作步骤与可发现性两类问题。
候选N02：澄清按角色的成员可见性，C要求全显、D反对；不能直接默认全显。
验证：走查导出任务；向两类角色核实可见范围与权限政策，补影响频次。
优先级：R07/N02均待产品负责人确认；3人样本不代表多数（G），不承诺开发日期。
```

1. A/B只计同一事件，仍可追溯两来源；C/E同人不同事，不能误去重。
2. 每条候选有编号、来源与验证方法；A/E关联R07而非无依据新增重复需求。
3. 保留C/D冲突、3人覆盖限制及待确认优先级；没有“多数用户需要”或已排期结论。

#### 修订要求

```text
只修缺口：保留已追溯候选；修正A/B计数，补C/D相反意见或缺失来源，把无依据优先级改为待确认。只返回受影响候选与去重说明，不重新编排已通过部分。 审阅人若发现缺口，退回产出该内容的角色；人工复核修订后再交接或保存，不自动流转。
```

- [查看场景任务卡](https://harzva.github.io/awesome-bot/handbook-scenarios.html#scenario-feedback-to-requirements)
- [在市场查看所需角色](https://harzva.github.io/awesome-bot/?scenario=feedback-to-requirements)

### 实战：证据不足时暂缓发布

适合团队交接与产品负责人审阅。以下材料全部虚构；参考产物是预先编写的教学示例，不是 Bot 运行结果。复制材料，准备定位草案与带依赖的日历；包含未通过项和未知指标，结论应是人工暂缓，不能制造已上线状态。

#### 练习任务与材料

```text
任务：作为产品定位与上市策划员，只用以下虚构材料写定位草案，供人工核对后再准备排期。
产物：目标客群、客户任务、可证明能力、价值假设、内容需求和待验证项；每个主张附材料编号，保留失败检查与人工暂缓状态。
边界：不编造指标、客户证言或已上线状态，不确认发布日、不执行发布。

虚构材料：
A｜目标客群：小型活动团队；3份访谈提到人工整理报名数据耗时，样本不具代表性。
B｜产品证据，2026-10-21：演示仅验证CSV导出；节省时间比例、转化率未知。
C｜质量记录，2026-10-22：手机失败重试检查未通过，复验结果尚无。
D｜目标日期：2026-10-28拟发布介绍页与邮件；日期未经确认，尚未上线。
E｜素材：介绍页草稿已备；邮件文案未完成，无客户证言授权。
F｜负责人：小林制作、小周审核；2026-10-27审核时间固定，邮件依赖介绍页审核通过。
G｜人工决定，2026-10-23：暂缓对外发布；恢复需C复验通过记录、素材审阅通过及负责人重新确认日期。
```

1. 先交产品定位与上市策划员（awesome/grok-product-marketer）：按A/B写面向客群的定位草案，区分可证明能力与价值假设；删除虚构比例和证言，保留C/G门槛。
2. 人工核对后交营销排期管理员（awesome/marketing-calendar-owner）：倒排制作、审核、渠道检查点，标明F固定节点与依赖；2026-10-28仅为待确认目标。
3. 人工按G维持暂缓；补齐真实证据后由负责人重新审阅日期，再依另行授权执行发布。

#### 教学参考节选

```text
定位草案：为小型活动团队提供CSV导出整理入口（A/B）；省时效果仍是假设。
文案边界：不写节省百分比、转化增长或客户证言（B/E）。
日历：小林完成邮件草稿→小周2026-10-27审核介绍页与邮件→渠道检查；邮件依赖介绍页批准（E/F）。
状态：人工暂缓（G）；手机失败重试未通过（C），2026-10-28待重新确认，尚未上线（D）。
恢复证据：C复验通过记录＋两素材批准记录＋负责人确认的新日期；未知效果指标另列验证计划。
```

1. 每个价值主张对应A/B或标假设；未知指标不能补造数字，未经授权证言不进入文案。
2. 日历有制作/审核负责人、2026-10-27固定检查点和邮件依赖；未确认目标不得写成承诺。
3. 明确C未通过、G人工暂缓及三类恢复证据；计划草稿不等于已上线。

#### 修订要求

```text
只修缺口：保留有证据定位与日历；删除无依据效果数值，补C/G门槛和缺失依赖。仅返回改动行及仍缺的恢复证据，不自行解除暂缓或改成已发布。 审阅人若发现缺口，退回产出该内容的角色；人工复核修订后再交接或保存，不自动流转。
```

- [查看场景任务卡](https://harzva.github.io/awesome-bot/handbook-scenarios.html#scenario-product-launch)
- [在市场查看所需角色](https://harzva.github.io/awesome-bot/?scenario=product-launch)

### 完成一次场景验收

1. 准备场景列出的最小材料，先用脱敏样例。
2. 把第一项任务交给对应角色，按场景条件验收。
3. 补齐缺口，把产物、来源和未知项连同交接卡传给下一位。
4. 保存最终产物与失败原因；场景下载不会自动执行流程。

### 参考来源

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

- [场景源数据](https://github.com/Harzva/awesome-bot/tree/main/data/scenarios)
- [场景起步说明](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)

## 让 Agent 按需读取角色

读取小索引和单角色资料，核对版本、语言和 SHA-256。

### 从小索引开始

团队读者重点理解按需发现角色、提供上下文和确认权限即可；不必先克隆仓库或安装 Node，也不要求每位协作者手动计算 SHA-256。继续阅读“读取与信任的边界”；“本地快照校验与失败练习”可留给开发者。

1. 读取 llms.txt，选择 zh 或 en 索引。
2. 按当前任务选择一个 ID，再读取其 JSON 或 Markdown。
3. 说明输入、输出、前提和需求，在 Agent 自身规则下处理任务。

- [读取指南](https://harzva.github.io/awesome-bot/llms.txt)
- [中文索引](https://harzva.github.io/awesome-bot/agents/zh/index.json)
- [英文索引](https://harzva.github.io/awesome-bot/agents/en/index.json)
- [读取与信任的边界](https://harzva.github.io/awesome-bot/handbook-agents.html#trust)

### 四种机器文件

| schema | 实际用途 |
| --- | --- |
| openbot.market.registry/1 | 发现版本、清单 URL 和完整性摘要 |
| openbot.market/1 | 规范角色清单：persona、技能和声明需求 |
| openbot.fleet/1 | 供宿主预览与确认的配置 |
| awesome.bot.agent/1 | 语言化角色上下文、来源和 configuration 字段 |

id、templateVersion、locale、contentRevision 定位上下文；configuration.bytes 和 configuration.sha256 定位下载字节。语言投影与规范清单可能字节不同，不可用中文清单摘要核对英文 Fleet。

下面是现有进度报告角色 Agent 卡的字段节选，不是可直接导入的完整文件。清单中的声明需求也不是已授予权限；以 Fleet 导出和宿主确认中的实际设置为准。

```json
{
  "schema": "awesome.bot.agent/1",
  "id": "awesome/status-report-writer",
  "templateVersion": "1.0.0",
  "locale": "en"
}
```

### 读取并核对 SHA-256

以下 Node.js 22+ 示例只读取和校验，不导入或执行配置。摘要不一致时停止，重新获取一致版本或带校验文件的发布快照。

```js
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
const base = 'https://harzva.github.io/awesome-bot/';
async function read(url) {
  const r = await fetch(url, { signal: AbortSignal.timeout(10000) });
  assert.equal(r.status, 200);
  return r;
}
const card = await (await read(base + 'agents/en/status-report-writer.json')).json();
assert.equal(card.schema, 'awesome.bot.agent/1');
assert.equal(card.id, 'awesome/status-report-writer');
assert.equal(card.locale, 'en');
const bytes = Buffer.from(await (await read(card.configuration.url)).arrayBuffer());
assert.equal(bytes.length, card.configuration.bytes);
assert.equal(createHash('sha256').update(bytes).digest('hex'), card.configuration.sha256);
console.log(card.id, card.templateVersion, card.locale, card.contentRevision);
```

### 读取与信任的边界

Copy for Agent 只复制提示，网站不会联系 Agent。无法读链接时，经 Agent 正常粘贴或附件入口提供对应 Markdown，并说明限制。SHA-256 匹配说明与元数据一致，不证明发布者身份；当前目录未签名。

理解上述边界后，团队读者可继续排错；实际接入、下载或升级仍须执行对应契约要求的完整性与信任核验，由负责接入的人或工具完成。

- [团队路径：继续排错](https://harzva.github.io/awesome-bot/handbook-troubleshooting.html?path=team)

### 本地快照校验与失败练习

准备 Node.js 22+，先从 GitHub clone 本仓库并进入仓库根目录，运行下方准备命令。clone、依赖安装和构建可能需要网络；只有后面的校验阶段完全读取本地文件。它不调用模型，也不表示模型可以离线运行。 命令使用macOS/Linux或Windows WSL的shell；其他终端可将JS标记之间的代码另存为.mjs，再用Node运行。

```sh
git clone https://github.com/Harzva/awesome-bot.git
cd awesome-bot
npm ci --ignore-scripts
npm run check
npm run build:site
```

已 clone 并完成 npm ci --ignore-scripts 时，从 npm run check 开始。检查失败先修复或重新取得同一份完整源快照，不跳过检查。随后在仓库根目录整体复制执行下面的 sh 块：它按 discovery → 英文索引 → 进度报告角色卡 → Fleet 字节读取，URL 必须匹配预期站点与路径，本地路径与符号链接也不能逃出 dist/site。

```sh
node --input-type=module <<'JS'
import assert from 'node:assert/strict';
import { readFile, realpath } from 'node:fs/promises';
import { resolve, sep } from 'node:path';
import { createHash } from 'node:crypto';
const root = await realpath(resolve('dist/site'));
const base = new URL('https://harzva.github.io/awesome-bot/');
async function bytesAt(url, expected) {
  assert.equal(url, new URL(expected, base).href, 'unexpected URL');
  const u = new URL(url);
  assert.equal(u.origin, base.origin);
  assert.equal(u.search + u.hash, '');
  assert.ok(u.pathname.startsWith(base.pathname));
  const relative = decodeURIComponent(u.pathname.slice(base.pathname.length));
  assert.ok(!relative.includes('\\') && !relative.includes('\0'));
  const path = resolve(root, relative);
  assert.ok(path.startsWith(root + sep), 'path escaped site root');
  const actual = await realpath(path);
  assert.ok(actual.startsWith(root + sep), 'symlink escaped site root');
  return readFile(actual);
}
async function jsonAt(url, expected) {
  return JSON.parse((await bytesAt(url, expected)).toString('utf8'));
}
const discovery = await jsonAt(new URL('agents/index.json', base).href, 'agents/index.json');
assert.equal(discovery.schema, 'awesome.bot.agent-discovery/1');
assert.equal(discovery.configurationFormat, 'openbot.fleet/1');
assert.ok(discovery.contentRevision);
const languages = discovery.languages.filter(x => x.locale === 'en');
assert.equal(languages.length, 1);
const index = await jsonAt(languages[0].url, 'agents/en/index.json');
assert.equal(index.schema, 'awesome.bot.agent-index/1');
assert.equal(index.locale, 'en');
assert.equal(index.contentRevision, discovery.contentRevision);
assert.equal(index.count, index.entries.length);
assert.equal(languages[0].count, index.count);
const matches = index.entries.filter(x => x.id === 'awesome/status-report-writer');
assert.equal(matches.length, 1);
const entry = matches[0];
const card = await jsonAt(entry.json, 'agents/en/status-report-writer.json');
assert.equal(card.schema, 'awesome.bot.agent/1');
assert.equal(card.id, entry.id);
assert.equal(card.locale, index.locale);
assert.equal(card.contentRevision, index.contentRevision);
assert.ok(entry.templateVersion);
assert.equal(card.templateVersion, entry.templateVersion);
assert.equal(card.configuration.format, 'openbot.fleet/1');
assert.equal(card.configuration.locale, card.locale);
assert.equal(card.configuration.grantsTools, false);
assert.equal(card.configuration.grantsContainer, false);
assert.equal(card.configuration.includesAccountsOrMemory, false);
assert.equal(card.configuration.importRequiresHostConfirmation, true);
const original = await bytesAt(card.configuration.url, 'exports/en/status-report-writer.fleet.json');
function verify(bytes) {
  assert.equal(bytes.length, card.configuration.bytes, 'byte length mismatch');
  assert.match(card.configuration.sha256, /^[0-9a-f]{64}$/);
  assert.equal(createHash('sha256').update(bytes).digest('hex'), card.configuration.sha256, 'SHA-256 mismatch');
}
verify(original);
const fleet = JSON.parse(original.toString('utf8'));
assert.equal(fleet.schema, card.configuration.format);
assert.equal(fleet.mode, 'config');
assert.equal(fleet.bots.length, 1);
const bot = fleet.bots[0];
assert.equal(bot.id, card.id.split('/')[1]);
assert.equal(bot.toolsEnabled, false);
assert.equal(bot.containerEnabled, false);
assert.deepEqual(bot.messages, []);
assert.deepEqual(bot.files, []);
assert.deepEqual(bot.channels, {});
assert.deepEqual(bot.memory, { profile: '', journal: [] });
assert.equal(bot.summary, null);
assert.deepEqual(fleet.shared, { skills: [], files: [] });
console.log('PASS original snapshot');
const altered = Buffer.from(original);
assert.ok(altered.length > 0);
altered[0] ^= 1;
assert.throws(() => verify(altered), { code: 'ERR_ASSERTION', message: /SHA-256 mismatch/ });
verify(original);
console.log('PASS altered copy rejected');
JS
```

完成判据是依次出现 PASS original snapshot 和 PASS altered copy rejected 两行，进程退出码为 0。版本和摘要取自当前快照，不需要改成某个写死的版本或 SHA。负例只翻转 Buffer 副本的一字节，以 assert.throws 证明摘要校验拒绝；源码和原始产物没有被写入。

schema 按每层的实际类型检查；id 与 templateVersion 在索引和角色卡间核对，locale 在索引、角色卡与 configuration 间核对，contentRevision 在 discovery、索引和角色卡间核对。Fleet 本身没有 locale、templateVersion 或 contentRevision 字段；这里核对其 schema、单 Bot 的 slug ID 与实际空结构，不臆造字段。

- ENOENT：确认当前目录是仓库根、Node.js 为 22+，并确认 npm run check 和 npm run build:site 成功；不要从其他版本手工拼入缺失文件。
- 版本、语言或 URL 断言失败：停止使用这份混合快照，从同一 Git 快照重新生成整个 dist/site 后重试，不放宽断言。
- 字节长度或 SHA-256 失败：保留失败记录，重新生成或重新取得完整一致快照；不要修改角色卡摘要让错误文件通过。

### 分清两种摘要

| 字段 | 计算对象与格式 | 比较边界 |
| --- | --- | --- |
| registry integrity | 规范清单的 canonicalJson：键递归排序、无格式空白；SHA-256 后使用 sha256-\<base64\>。 | 由 engine/src/manifest.mjs 的 integrityOf 定义；不是下载文件的原始字节摘要。 |
| Agent configuration.sha256 / bytes | configuration.url 指向的具体 Fleet 导出字节；SHA-256 为 64 位十六进制，bytes 为字节数。 | 由 scripts/agent-surface.mjs 读取产物计算；只与同一 URL、语言和快照的字节比较。 |

CLI 经 scripts/market.mjs 复用引擎导出，默认时间取当前 Date.now()；站点构建使用 metadata.updatedAt 的固定时间。exportedAt 和 Bot createdAt 因此可能不同；中文规范投影和英文站点投影的人设等文本也不同。即使角色 ID 和模板版本相同，这些导出的字节与摘要仍可能不同，不能混用 registry integrity、CLI 文件摘要、中文下载或英文下载摘要。

### 参考来源

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

- [Agent 读取与校验](https://github.com/Harzva/awesome-bot/blob/main/docs/agent-integration.md)
- [格式契约](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)

## 贡献、构建与发布

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

### 修改正确的源文件

每个条目在 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)

## 先定位问题在哪一层

保留材料和错误证据，选择低风险、可逆的排查动作。

### 常见问题速查

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 网站加载失败 | 网络与目录加载状态 | 重试相同筛选或读 GitHub 目录 |
| 下载后没有 Bot | 是否只完成网站下载 | 在宿主当前配置导入入口预览与确认 |
| 合集无法导入 | 单文件是否超过200个 Bot | 选单角色或发布分片，并查宿主总量限制 |
| 读不到邮件或文件 | 工具、账号授权与材料可读性 | 提供脱敏材料或补齐任务所需授权 |
| 中文模式有英文指令 | 是否为带来源适配 | 阅读适配说明，指定产物语言 |
| SHA-256 不匹配 | 卡片与下载是否同一发布 | 停止导入，获取一致版本或发布快照 |
| 产物完整但缺少证据 | 来源和验收条件是否齐全 | 补材料并列出未知、冲突 |

读不到文件时，把以下两行公开虚构文本直接贴给当前 Agent，请它只复述两条事实并标行号。不要放入客户资料。

```text
1｜虚构项目：纸飞机；目标周五交草稿。
2｜桌面测试通过；手机测试未开始。
```

若复述正确，记录“粘贴文本可读；原文件读取仍未验证”，保存这次结果。下一步只查原文件路径、格式或授权；若文本也失败，保留报错定位模型或会话问题。条件未变时不盲目重试，不重置已成功的步骤。

### 提交可复现反馈

```text
公开反馈（请脱敏）
页面或公开Bot ID：
模板版本 / 语言 / 内容修订：
宿主版本（涉及导入时）：
时间与最小步骤：
预期结果：
实际结果和错误码：
可公开小样例：
敏感资料处理状态（如适用，不写敏感值）：
不包含：账号、密钥、私有对话、客户材料
```

角色详情反馈入口会预填公开 Bot ID、模板版本和来源。提交前仍需检查自己添加的材料，不公开完整私有日志。

若已误贴敏感资料，先处理暴露：凭据在对应服务侧撤销或轮换，删除聊天不等于凭据失效；客户资料按实际服务删除或限制访问，并确认暴露范围。反馈只记录处理状态与必要的范围说明，不再次粘贴敏感值。

### 保留工作后再恢复

1. 保存草稿、下载文件和必要的脱敏错误信息。
2. 区分网站、格式、宿主导入、模型和账号问题。
3. 先重试读取或用小样例复现，避免用重置替代定位。
4. 运行实例按宿主当前文档处理，记录实际结果。

### 三个容易误解的问题

| 问题 | 回答 |
| --- | --- |
| 打开来源链接会安装吗？ | 不会，原站条件与操作另行适用。 |
| 能运行就代表账号任务认证吗？ | 不能，格式检查与真实账号验收不同。 |
| Bot 自动共享私有记忆吗？ | 配置不传记忆，使用明确授权资料包交接。 |

- [公开问题列表](https://github.com/Harzva/awesome-bot/issues)

### 参考来源

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

- [网站与反馈说明](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [导入与验证范围](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [摘要不一致处理](https://github.com/Harzva/awesome-bot/blob/main/docs/agent-integration.md)

## 术语、许可与来源

查清字段和来源，区分原创、英文适配与外部参考。

### 术语表

| 术语 | 本手册中的含义 |
| --- | --- |
| Agent | 在宿主中结合模型、指令和可用工具处理任务的执行者；能力取决于实际配置与授权 |
| Bot 角色 | 职责、方法和前提的配置 |
| 宿主 | 承载 Bot 或 Agent 的应用或运行环境，管理可用工具与账号授权 |
| 模型 | 提供生成与推理能力的组件；可用工具和账号权限由宿主另行配置 |
| 任务流程 | 围绕特定产物组织的步骤 |
| Fleet | 供宿主导入审阅的配置文件 |
| 规范清单 | 保留已发布版本字节的角色清单 |
| 语言投影 | 同一源角色的语言化内容与下载 |
| 配置摘要 | 识别具体下载字节的 SHA-256 |
| 信任锚 | 独立固定的发布者验证依据，本目录未捆绑 |
| 验收 | 按明确条件检查具体任务产物 |

### 查看许可与署名

315 个角色中包含 223 个带来源适配角色，另有 56 个任务流程。Shared Bots 仅为来源链接，不计入本站可导入配置；具体条目的许可与来源以 data/entries 中的 license / references 及适用许可文件为准。

本站原创内容和代码使用 MIT。223 个带来源角色中，mergisi/awesome-grokbot 使用 CC0-1.0，cobusgreyling/grok-bot-templates 和 PramodDutta/botskills 使用 MIT。适配保留原始指令、来源、摘要与适用许可；上游名称和品牌权利归各自所有者。

1. 在详情查看作者、源地址和模板版本。
2. 再分发前打开适用许可与第三方说明，保留要求的署名。
3. 外部项目逐项看许可；链接参考不代表获准复制软件或资产。

- [项目许可](https://github.com/Harzva/awesome-bot/blob/main/LICENSE)
- [第三方说明](https://github.com/Harzva/awesome-bot/blob/main/THIRD_PARTY_NOTICES.md)
- [适配来源清单](https://github.com/Harzva/awesome-bot/blob/main/data/imported-role-sources.json)

### 继续阅读

- [市场首页](https://harzva.github.io/awesome-bot/)
- [手册首页](https://harzva.github.io/awesome-bot/handbook.html)
- [Shared Bots 来源目录](https://harzva.github.io/awesome-bot/shared-bots.html)
- [项目与参考](https://harzva.github.io/awesome-bot/resources.html)
- [机器索引](https://harzva.github.io/awesome-bot/registry/index.json)
- [发布与校验文件](https://github.com/Harzva/awesome-bot/releases)

### 本手册如何使用来源

本手册借鉴 grokbot-guide 的学习路径、场景验收和分层排错结构，正文与练习为本站原创。Grok 的云电脑、例程、连接应用和审批菜单是其平台专属说明，不在这里作为 OpenBot 已接通功能介绍。本手册功能事实依据本仓文档与数据契约，具体账号任务仍需单独验收。

- [固定版本结构参考](https://github.com/anightmonarch/grokbot-guide/tree/65688ac52e2a14b160393688bdfb2734ecc6dcc7)

### 参考来源

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

- [本站许可](https://github.com/Harzva/awesome-bot/blob/main/LICENSE)
- [第三方署名和许可](https://github.com/Harzva/awesome-bot/blob/main/THIRD_PARTY_NOTICES.md)
- [适配与索引边界](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)
- [学习路径结构参考](https://github.com/anightmonarch/grokbot-guide/tree/65688ac52e2a14b160393688bdfb2734ecc6dcc7)