交付 Bot：按交付链路说明
按真实交付顺序：建群归集 → 进群欢迎 → 对接答疑 → 主网上线收尾 → 钱包入库 → 飞书日报。 Telegram 侧只跑一个交付号（@Roy4by4 / python -m bot.main）； 钱包地址由 Google Form + Apps Script 独立回写飞书。
按交付顺序阅读
从前到后即一条完整交付路径；权限与口令紧挨「上线收尾」。配置以生产 config/config.yaml 为准。
从建群到收钱包，一条链路
生产仅保留一份交付号会话（systemd：botchain-qa）。 下图按交付时间顺序排列；后文各页与此一一对应。
标题匹配归入 Botchain 夹；入群即时欢迎
交付号Folder 内自动答疑；测试号 absorb 沉淀知识
交付号操作员发「项目已上线」→ 改状态 · 发表单 · Logo
交付号项目方填 Google Form → Apps Script 写飞书
Google每日 00:00（上海）汇总前一日钱包表
交付号- Folder、欢迎、FAQ、absorb
- 操作员口令与上线收尾
- Webhook / 约 60s 状态侦测（5 分钟轮询关闭）
- 飞书钱包日报；按需交付周报
- Google Apps Script onFormSubmit
- 表单 → 飞书「项目方钱包地址搜集」
- 交付号停机时仍可写入
- 地址不向 Telegram 群广播
Folder 归集与即时欢迎
Folder 归属影响 FAQ 等群内自动能力。操作员上线口令不强制要求群已在 Folder， 但群名仍须能匹配飞书项目名。欢迎语入群即发，无需等待群内先有消息。
- 标题含 botchain / bot chain 即纳入
- 归入 Botchain #1、#2…（单夹容量约 100）
- 满容后按前缀自动新建编号
- 入群、启动扫描、每 2 分钟补扫
- 与试点名单无关，全局生效
- min_messages_before_welcome: 0
- 优先依据近期消息识别语言，其次群标题；默认英文
- 中/英各三条：自我介绍、集成文档、引导继续提问
- 状态文件防重复；已 baseline 群不会被扫描回刷
- 试点关闭后：标题匹配即欢迎
FAQ、absorb 与 Agent 词条
对外答疑以本地 knowledge/（含 learned）为主。Wiki 同步文件默认不参与检索。
- 仅 Folder 内；@ 或问句形态触发
- 跟随用户语言回复；资料不足则不答
- 文档、帮助中心、表单链接可附带时附带
- 不反问澄清；多选项一次列全
- FAQ 附页脚；欢迎与工作流消息不附
- 触发词：absorb
- 先写本地 knowledge/learned/
- 成功后 upsert 飞书 Agent 表
- 表：tblP28CyWdY5ml8r
- base：Kb6rbLenJa4FzWsi6pzlTkdjg0e
- 报价、合同、排期等敏感题自动拒答
- 同群同用户约 120 秒冷却；发送前约 10 秒延迟
- Wiki 仅为内部备份，不作对外 FAQ 主源
- 进程停机时 FAQ 与 absorb 同步不可用
FAQ 与交付口令分轨管理
FAQ 面向 Folder 内项目方。状态变更、发表单、拉取周报等口令仅 操作员白名单可用。口令明细见下一页；配置说明见 docs/delivery-operator-whitelist.md。
- 配置项：workflow.operators
- 交付号：@Roy4by4（始终可用）
- 操作员：@Josh_0zh、@Xuanxi_zhao
- QA：@Trent_one（qa_testers.yaml）
- 未列入账号：口令无效
- 标记主网上线：改飞书状态 + 发表单 + 抓 Logo
- 仅发送上线表单（不改状态）
- 拉取 交付周报 / /stats
- 口令不要求群已在 Folder（群名仍须对齐飞书项目名）
- whitelist.yaml → ignore_users：FAQ 黑名单
- operators：交付口令白名单
- 交付同学入白名单后，宜同步移出 ignore
- FAQ / 欢迎 / Folder 规则独立，不依赖 operators
口令须整句精确匹配
交付日常可仅在 Telegram 发送口令完成上线收尾：更新飞书状态、发送表单、尝试抓取 Logo。 钱包地址仍由项目方填表收集，口令不会自动抓取地址。
- 项目已上线
- 上线完成
- /mark_live
- mark live
- 在对应项目群发送；按群名匹配飞书「项目名称」
- 仅发表单：/send_form · 发送上线表单 · send form
- 短版周报：交付周报 · 交付报告 · /report
- 明细统计：交付统计 · /stats
- 周报为按需回复，无定时推送
- 群口令：即时（交付主路径）
- 飞书 Webhook：状态变更后秒级（自动化就绪时）
- 状态侦测：约 60 秒，补齐 Webhook 漏网
- 表单 / Logo 具备去重，避免重复刷群
- 进入项目对接群（群名与飞书项目名对齐）
- 上线收尾发送：项目已上线
- 仅需表单时发送：发送上线表单
- 查看周数据：私聊 @Roy4by4 发送 交付周报
- 当前可操作：@Josh_0zh · @Xuanxi_zhao · 交付号本人
增删操作员：更新服务器 config.yaml → workflow.operators，执行 systemctl restart botchain-qa。 若账号仍在 whitelist.yaml 的 ignore_users，交付角色通常应同步移除。 完整说明：docs/delivery-operator-whitelist.md。
表单发送与 Logo 补全
统一动作：匹配项目群、发送 Google Form、尽量补全 Logo。 交付主路径为操作员群口令；飞书改状态依赖 Webhook， 漏网由约 60s 状态侦测补齐。5 分钟全量轮询已关闭； 启动补扫关闭；群名无法匹配时使用 /send_form 向当前群直发。
- 以群标题模糊匹配飞书「项目名称」
- 匹配成功后发送 Google Form 文案与链接
- 有官网 / 已上线链接则抓取 Logo，写入「项目logo」
- 本地状态去重；首次 baseline 不会对存量 Live 全量群发
- 无匹配或多匹配：跳过；人工对齐群名，或使用路径 ⑤
- Logo 抓取失败即停止，不自动重试
- Webhook 未通时：飞书改 Live 依赖路径 ③，或直接使用路径 ①
- 状态侦测与 Webhook 均要求服务器交付号进程在线
地址仅写入飞书
钱包地址只进入飞书多维表格。Telegram 内部群广播已关闭。零点日报由交付号进程按上海时区推送。
- Apps Script onFormSubmit
- 表：项目方钱包地址搜集
- 按项目名 upsert
- 交付号停机时仍可写入
- 表单字段变更时需同步更新脚本映射
- wallet_notify_enabled: false
- 财务 / 运营 / 技术 TG 群均不接收地址
- 查阅地址请前往飞书表格
- 每日 00:00 Asia/Shanghai
- 统计前一自然日：新增条数、地址填写情况
- 推送至配置的固定飞书群
- 交付号当日未运行则日报缺失
生产配置一览（运维附录）
以服务器 /opt/botchain-qa-tg-bot/config/config.yaml 为准。 变更开关后需重启 botchain-qa。
7×24 运行需部署于服务器并以 systemd 常驻。本机休眠将中断扫描、Webhook 与日报调度。 飞书秒级推送依赖稳定公网 HTTPS（见 scripts/LARK_LIVE_WEBHOOK.md）； 临时隧道仅适合联调，不宜作为长期生产入口。交付主路径以操作员群口令为准。
主路径可用，以下事项需人工关注
自动化无法覆盖全部边界场景。下列项为当前主要限制与运维约束。
- 匹配依赖群标题与飞书「项目名称」相似
- 差异过大或一对多时跳过，避免误发
- 人工对齐群名，或在目标群使用 /send_form
- 本机 :8787/workflow/live 与 /health 正常
- 飞书外网回调需稳定 HTTPS（域名或长期 Tunnel）
- 联调完成前：交付以群口令为主，飞书改状态依赖约 60s 侦测
- 生产：云服务器，服务名 botchain-qa
- 禁止本机与服务器同时登录同一交付号
- 迁移需携带：代码、.env、Session、config、data/*.json
- Logo 抓取需外网及 Playwright 环境
按交付顺序记住这些
- ① 进群：标题匹配进 Folder，即时欢迎（默认英文）。
- ② 对接：Folder 内 FAQ；absorb 写入 learned 并同步 Agent 表。
- ③ 上线：操作员整句发「项目已上线」；Webhook + 约 60s 侦测托底；5 分钟轮询关闭。
- ④ 表单 / Logo：匹配失败用 /send_form；Logo 失败不重试。
- ⑤ 钱包：Google Form → 飞书；TG 不广播；零点日报启用。
- 操作员：@Josh_0zh、@Xuanxi_zhao；完整手册见后文附录（同源 docs/delivery-operator-whitelist.md）。
- 周报 / 统计按需口令拉取；生产单进程常驻服务器。
「白名单」指什么，谁能操作
面向交付同学：谁能触发交付动作、发什么口令、与「BD 忽略名单」有何区别。 生产交付号：@Roy4by4（systemd：botchain-qa）。 完整文档：docs/delivery-operator-whitelist.md。
- 配置路径：服务器 /opt/botchain-qa-tg-bot/config/config.yaml
- 键名：workflow.operators
- 未列入账号发口令：无效
- 交付号本人始终可用，无需写入 operators
| Telegram | 说明 |
|---|---|
| @Josh_0zh | 交付操作员 |
| @Xuanxi_zhao | 交付操作员 |
| @Roy4by4 | 交付号本人（始终可用） |
| @Trent_one | QA（qa_testers.yaml，权限类似） |
| 能力 | 说明 |
|---|---|
| 标记主网上线 | 改飞书「项目状态」→ 主网上线，并触发 Google 表单 + Logo 抓取 |
| 仅发上线表单 | 不改飞书状态，只在当前群发送 Google 表单 |
| 交付周报 / 统计 | 拉取管理层短版周报或运维明细 |
| 不强制 Folder | 任意群可发口令；群名仍须能匹配飞书项目名 |
须整句完全一致，勿加减字
多出的字（如「请项目已上线」）不会触发。钱包地址不会被口令自动抓取，仍由项目方填表。
- 在对应项目群发送上述任一整句
- 按当前群名匹配飞书「项目名称」
- 状态设为：BOT主网上线 Live on BOT Chain Mainnet
- 立即发表单；尝试抓 Logo（失败不重试）
- 匹配失败会回复，不会乱改其他行
- 只向当前群发表单，不改飞书状态
| 口令 | 内容 |
|---|---|
| 交付周报 / 交付报告 / /report | 管理层短版 |
| 交付统计 / /stats | 运维明细长版 |
周报无定时推送，仅口令触发。可私聊交付号或在其所在群发送。
上线触发路径，以及与 BD 忽略名单的区别
同一套结果（Live → 表单 + Logo）可多入口并存、互相去重。交付日常可只在 Telegram 发口令，不必再手动改飞书。
| 入口 | 谁触发 | 延迟 |
|---|---|---|
| 群口令（主路径） | 操作员在项目群发关键词 | 立刻 |
| 飞书改状态 → Webhook | 进度表改为主网上线 | 秒级（自动化就绪时） |
| 状态侦测 | 表上已是 Live，但 Webhook 未打到 | 约 1 分钟内 |
- 文件：config/whitelist.yaml → ignore_users
- 文件名含 whitelist，实际是黑名单
- 作用：这些人发言时，Bot 不做 FAQ 自动回复
- 常见于 BD / 内部拉群账号，避免刷屏式答疑
- 文件：config.yaml → workflow.operators
- 作用：交付口令权限（上线 / 表单 / 周报）
- 若某人既要口令、又曾在 ignore：应加入 operators，并视需要移出 ignore
- 示例：@Xuanxi_zhao 已按此处理
如何增删操作员，以及可转发的最短说明
增删需服务器权限；改完后重启服务生效。
- 编辑 /opt/botchain-qa-tg-bot/config/config.yaml
- 维护 workflow.operators
- 执行 systemctl restart botchain-qa
- 日志应出现：Workflow operator @xxx -> user_id=...
若需其发言可被 FAQ 处理，请同步从 ignore_users 删除后重启。
- 用你的号进项目对接群（群名尽量与飞书一致）
- 上线收尾时单独发一行：项目已上线
- Bot 会改飞书状态、发表单、尝试填 Logo
- 只要表单时发：发送上线表单
- 看周数据：私聊 @Roy4by4 发 交付周报
当前可操作：@Josh_0zh、@Xuanxi_zhao，以及交付号本人。
| 项 | 路径 |
|---|---|
| 操作员 / 口令 | config.yaml → operators / mark_live_commands / manual_commands |
| BD 忽略名单 | whitelist.yaml → ignore_users |
| QA 测试号 | qa_testers.yaml |
| 飞书 Webhook | scripts/LARK_LIVE_WEBHOOK.md |
| 服务状态 | systemctl status botchain-qa |