- source-repos/octo-server/modules/bot_api/bot_api.go（路由注册行 410-468，Go 源码路由事实）
- source-repos/octo-server/modules/bot_api/auth.go（register/heartbeat/auth 逻辑）
- source-repos/octo-server/modules/bot_api/events.go（事件轮询）
- source-repos/octo-server/modules/bot_api/card_profile.go（卡片能力查询）
- source-repos/octo-server/modules/bot_api/file.go（文件上传/预签名）
- source-repos/octo-server/modules/bot_api/groups.go（群组/成员）
- 00-inbox/product-bot-answers/2026-09-19-openclaw-channel-octo事件机制回答.md（message_id=2101009604581167104）
- 00-inbox/product-bot-answers/2026-09-19-openclaw-channel-octo交付前profile配置检查清单回答.md（message_id=2101150063836172288）
- 00-inbox/product-bot-answers/2026-09-20-P0-API鉴权-Q1回答.md（产品管家Q1：API体系全貌，2026-09-20）
- 01-product/模块说明/文档协同Docs模块.md v0.2（文档评论@Mention链路）
- 01-product/模块说明/Drive网盘模块.md v0.2（Drive Bot API待确认）
- 01-product/模块说明/语音Speech模块.md v0.3（语音纠错API）
- 01-product/模块说明/智能摘要Summary模块.md v0.3（Agent触发总结PR#850）
- 01-product/模块说明/全文搜索Search模块.md v0.3（Bot OBO搜索）
- 售前交付/openclaw-channel-octo卡片能力正式口径-v1.0.md（v1.0，卡片API边界）
Bot API 概览 v0.4
状态：`draft` / v0.3。 端点列表来自 `modules/bot_api/bot_api.go` 路由注册源码 + 产品管家 Q1-Q4（2026-09-20）API体系全貌确认。API体系、鉴权token、消息发送、群/Thread/成员/文件管理边界均已补完。
0. OCTO 对外 API 体系全貌（产品管家 Q1，2026-09-20）
| API类别 |
端点前缀 |
鉴权方式 |
状态 |
面向调用方 |
稳定性 |
| Bot API |
/v1/bot/* |
Bearer Bot Token（register/heartbeat 免鉴权） |
已开放 |
Bot/Agent（含OpenClaw插件） |
主推、对外首选 |
| OBO API |
/v1/obo/* + /v1/bot/obo-grant |
用户登录态授权 grant+scope |
已开放 |
Bot经用户授权后代发 |
GA |
| OpenAPI（OAuth） |
/v1/openapi/* |
authcode→access_token（OAuth授权码流） |
已开放 |
第三方应用以用户身份接入 |
GA |
| Incoming Webhook |
/v1/groups/{g}/incoming-webhooks/* + push端/v1/.../{webhook_id}/{token}/{github,gitlab,wecom,feishu,octo,multica} |
webhook_id+token |
已开放 |
外部系统单向推消息进群/子区 |
GA |
| Webhook（出站） |
/v1/webhook、/v2/webhook、/v1/webhook/github、/v1/webhook/message/notify |
HMAC-SHA256签名 |
已开放 |
接收IM事件回调的外部服务 |
GA |
| OIDC |
/v1/auth/oidc/{provider}/* |
OAuth/OIDC授权码 |
视部署配置（disabled时返回404） |
用户SSO |
按配置 |
| AgentMail Gateway |
/v1/mail-gateway/*（反代到上游/webapi/v0） |
标准登录UID+Space校验 |
已开放 |
agentmail网关代理 |
内部/网关 |
| Management/Admin |
无独立前缀，复用 /v1/*（前端经 /api 代理，nginx剥前缀）；Marketplace独立 /market/api/v1/* |
Manager登录session/token（axios+401拦截） |
已开放（面向管理后台自身） |
octo-admin管理控制台 |
未作为独立对外契约发布 |
- 需要「以用户身份」代操作 → OBO（Bot侧）或 OpenAPI OAuth（第三方应用侧）
- 外部系统单向推消息进群 → Incoming Webhook
- 接收IM事件回调 → Webhook（出站）
- Management/Admin API：没有独立
/admin 前缀，octo-admin前端直接调 /v1/*（经 /api 代理），鉴权是manager登录session（非长期静态token）；唯一独立前缀是marketplace（/market/api/v1/*→独立marketplace服务:8092）
- 售前口径：Admin API 未作为对外稳定契约发布，管理操作走后台UI，程序化对接首选 Bot API；技术上可用manager会话调/v1/*管理端点，但无独立CI/脚本token机制
- OpenAPI/Swagger spec：octo-server仓库没有 openapi.yaml/json/swagger规范文件；「openapi模块」是OAuth授权码接入，不是Swagger文档
- 普通客户端内部
/v1/* 接口不直接对第三方开放，正规用户身份接入走 /v1/openapi/* OAuth流
0.1 Bot 鉴权与身份模型（产品管家 Q2，2026-09-20）
| Token |
类型 |
用途 |
生命周期 |
bot_token（bf_/app_前缀） |
长期身份凭据（opaque，非JWT） |
调所有 /v1/bot/* 业务接口 |
长期，吊销即时生效（tombstone缓存） |
| IM token |
短期WuKongIM连接凭证 |
建长连接收发实时消息 |
短期，register刷，heartbeat保活（Redis TTL 60s） |
- bot_token 申请：管理后台/botfather侧创建（非API自助注册）；
/v1/bot/register不是申请token入口，是用已有token刷IM token
- 两种Bot：User Bot（
bf_前缀，落robot表）/ App Bot（app_前缀，落app_bot表，有scope约束如space）
- 身份模型：Bot默认以自己robotID身份发消息；OBO是额外授权（用户显式grant+scope后可代用户操作，App Bot受space约束fail-closed）
- 权限模型：Bot加群后是普通群成员，非超管；不能跨群任意操作（必须是群成员，否则ErrBotAPINotGroupMember）；GET /v1/bot/groups只返回自己加入的群；ACL=成员身份+路由scope（authtree守卫）双重约束
- 限流三桶（2026-08-05事故后改为按bot身份分桶）：business（业务如sendMessage，主配额）/ heartbeat（保活，独立自愈配额）/ register（换token，key=bot token指纹，鉴权前限）；heartbeat/register移出全局per-IP桶防连坐；阈值可配置（env如registerIPRPS/Burst），不硬编码
0.2 消息收发核心模型（产品管家 Q3，2026-09-20）
- 核心字段：
channel_id（必填）+ channel_type（uint8：DM=1/群=2/子区=5）+ payload（必填）+ 可选on_behalf_of/stream_no
- 最小文本：
{"channel_id":"","channel_type":2,"payload":{"type":1,"content":"你好"}}
- type=1 文本：
{"type":1,"content":"..."}（content支持富文本/Markdown，由客户端渲染）
- type=8 文件：
{"type":8,"url":"...","name":"...","size":123}（图片/文件/语音/视频都走文件类，用presigned上传拿url，不塞base64）
- 卡片：走sendMessage统一入口（非独立端点）——原始卡片带
card字段（cardmsg.Validate校验，render_profile=octo-chat-v1）；模板卡片带template_ref（服务端RenderPayloadForPrincipal渲染）；卡片提交回调从events收card_action_callback事件
- type全集不逐条断言；文本/文件/卡片三大类最稳
- 编辑：
POST /v1/bot/message/edit（只能改自己发的）
- typing：
POST /v1/bot/typing
- 已读：
POST /v1/bot/readReceipt
- 卡片能力探测：
GET /v1/bot/card/profile；卡片修订清墓碑：POST /v1/bot/message/card/revisions/clear
- 撤回：路由表未见独立recall端点，待确认；Bot不能编辑/撤回人类消息
- @提及：payload.mention（uids数组/mention.all=1@所有人，legacy @all不再触发bot）
- 引用回复：payload内带reply字段（字段名待确认）
- Thread回复：子区是独立channel，channel_type=5 + 子区channel_id（父群+short_id四下划线形式）
0.3 群/Thread/成员/文件管理边界（产品管家 Q4，2026-09-20）
| 能力 |
端点 |
状态 |
| 创建群 |
POST /v1/bot/createGroup |
✅已开放 |
| 更新群信息 |
PUT /v1/bot/groups/:group_no/info |
✅已开放 |
| 群公告/MD |
GET/PUT /v1/bot/groups/:group_no/md |
✅已开放（PUT经protectAIContainerMutation） |
| 解散群 |
无dissolve端点 |
❌暂不开放 |
| 群头像更新 |
未在路由单独核到 |
⚠️待确认 |
| Thread创建/列出/详情/删除 |
POST/GET/DELETE .../threads[/:short_id] |
✅已开放 |
| Thread成员列表/join/leave/archive/md |
.../threads/:short_id/{members,join,leave,archive,md} |
✅已开放（写操作过守卫） |
| 拉人进群 |
POST /v1/bot/groups/:group_no/members/add |
✅已开放 |
| 踢人 |
POST /v1/bot/groups/:group_no/members/remove |
✅已开放 |
| 改成员角色（群主/管理员） |
无角色变更端点 |
❌暂不开放 |
| 用户资料 |
GET /v1/bot/user/info / POST /v1/bot/users/batch |
✅已开放 |
| Space成员/主体 |
GET /v1/bot/space/members / GET /v1/bot/space/principals/:uid |
✅已开放 |
| 目标解析 |
GET /v1/bot/resolve/targets |
✅已开放 |
| 查任意用户所在群 |
无此端点（越权） |
❌不开放；GET /v1/bot/groups只返回bot自己加的群 |
- 上传：
POST /v1/bot/file/upload（别名/v1/bot/upload）
- 下载：
GET /v1/bot/file/download/*path / 代理302跳presigned GET /v1/botfile/*path
- 直传凭证：
GET /v1/bot/upload/credentials；预签名：GET /v1/bot/upload/presigned（大文件/客户端直传首选）
- 大小限制：默认100MB，可通过system_setting
file.max_size_kb配置，未配置回落100MB
- 类型校验：扩展名白名单+黑名单双重门 + 魔数（magic number）校验防伪造后缀；贴纸单文件1MB/512×512
Bot API 定位
鉴权与连接
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/register |
ANY |
Bot 注册/重连刷 IM token（限流豁免，保活"爬起来"能力） |
bot_api.go:362 + main.go 注释（2026-08-05 事故记录） |
/v1/bot/heartbeat |
ANY |
Bot 保活心跳（限流豁免，检测掉线） |
bot_api.go:326 + main.go 注释 |
/v1/bot/obo/grant |
— |
OBO（On-Behalf-Of）授权授予（用户代 Bot 操作场景） |
bot_api.go:468 |
/v1/botfile/* |
— |
Bot 文件子路由组（ba.authBot()） |
bot_api.go |
注：register/heartbeat 用 `r.Any` 而非 `r.POST`，因为全局限流豁免只看路径不看方法，必须盖住所有方法。这是生产事故（2026-08-05 同 IP Bot 互饿死锁）驱动的设计。（来源：main.go 注释 + bot_api.go:326/362）
消息发送与编辑
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/sendMessage |
POST |
发送消息（raw / card / template 三模式统一入口） |
bot_api.go:410 |
/v1/bot/message/edit |
POST |
编辑已发送消息（含卡片 template edit 路径） |
bot_api.go:452; card_p2_edit_im_test.go |
/v1/bot/typing |
POST |
发送 typing 指示器 |
bot_api.go:411 |
/v1/bot/readReceipt |
POST |
上报已读回执 |
bot_api.go:412 |
/v1/bot/messages/sync |
POST |
历史消息拉取（分页+方向控制，v1.1.2 新功能 #50） |
bot_api.go:415; octo-server changelog v1.1.2 |
/v1/bot/message/card/revisions/clear |
POST |
清除卡片修订（写墓碑，D10.6） |
bot_api.go:453 |
事件轮询（Agent 接收消息的入口）
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/events |
POST |
拉取事件（长轮询 long-poll；返回消息事件、card_action 回调等） |
bot_api.go:413; events.go; 产品管家 events-mechanism 回答 |
/v1/bot/events/:event_id/ack |
POST |
确认事件已处理（ACK 去重机制） |
bot_api.go:414 |
事件类型包括：消息（message）、卡片回调（card_action）、成员变更等；cursor/ACK/去重机制保障 at-least-once 投递。（来源：产品管家 events-mechanism 回答 message_id=2101009604581167104）
卡片能力协商
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/card/profile |
GET |
查询当前 Bot 的卡片能力 manifest（profiles/limits/card_version/templating 等） |
bot_api.go:454; card_profile.go |
这是"能力运行时以服务端 manifest 为准"的核心查询端点。插件启动后首先请求此端点决定展示/交互/进度卡是否启用及 limits 数值。（来源：产品管家 delivery-card-profile-checklist 回答 message_id=2101150063836172288）
群组与 Thread 管理
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/groups |
GET |
获取 Bot 所在群组列表 |
bot_api.go:416 |
/v1/bot/groups/:group_no |
GET |
获取群信息 |
bot_api.go:423 |
/v1/bot/groups/:group_no/members |
GET |
获取群成员列表 |
bot_api.go:424 |
/v1/bot/groups/:group_no/mention_pref |
GET |
群级免@偏好（octo-server#237） |
bot_api.go:425 |
/v1/bot/groups/:group_no/md |
GET/PUT |
获取/更新群 Markdown 公告/描述（PUT 经 protectAIContainerMutation） |
bot_api.go:426/427 |
/v1/bot/createGroup |
POST |
创建群 |
bot_api.go:430 |
/v1/bot/groups/:group_no/info |
PUT |
更新群信息 |
bot_api.go:431 |
/v1/bot/groups/:group_no/members/add |
POST |
添加群成员 |
bot_api.go:432 |
/v1/bot/groups/:group_no/members/remove |
POST |
移除群成员 |
bot_api.go:433 |
/v1/bot/groups/:group_no/threads |
POST |
创建 Thread（子区） |
bot_api.go:435 |
/v1/bot/groups/:group_no/threads |
GET |
列出 Thread |
bot_api.go:436 |
/v1/bot/groups/:group_no/threads/:short_id |
GET |
获取 Thread 信息 |
bot_api.go:437 |
/v1/bot/groups/:group_no/threads/:short_id |
DELETE |
删除 Thread |
bot_api.go:438 |
/v1/bot/groups/:group_no/threads/:short_id/members |
GET |
列出 Thread 成员 |
bot_api.go:439 |
/v1/bot/groups/:group_no/threads/:short_id/join |
POST |
加入 Thread |
bot_api.go:440 |
/v1/bot/groups/:group_no/threads/:short_id/leave |
POST |
离开 Thread |
bot_api.go:441 |
/v1/bot/groups/:group_no/threads/:short_id/archive |
POST |
归档 Thread |
bot_api.go:442 |
/v1/bot/groups/:group_no/threads/:short_id/md |
GET/PUT |
获取/更新 Thread Markdown |
bot_api.go:443/444 |
/v1/bot/groups/:group_no/incoming-webhooks |
— |
群 incoming webhook 管理子路由组 |
bot_api.go（g 路由组） |
/v1/bot/groups/:group_no/threads/:short_id/incoming-webhooks |
— |
Thread 级 incoming webhook 子路由组 |
bot_api.go（threadG 路由组） |
注：多个变更类端点（PUT/DELETE/POST 创建群/Thread/成员）经 `protectAIContainerMutation` 中间件保护，防止对 AI 容器类特殊会话进行未授权变更。（来源：bot_api.go 多处引用）
用户查询
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/user/info |
GET |
查询用户信息 |
bot_api.go:455 |
/v1/bot/users/batch |
POST |
批量查询用户（有 batchUsersIPLimit 限流） |
bot_api.go:422; batch_users.go |
/v1/bot/resolve/targets |
GET |
解析消息目标（@提及/会话目标解析） |
bot_api.go:417 |
/v1/bot/space/members |
GET |
查询 Space 成员列表 |
bot_api.go:428 |
/v1/bot/space/principals/:uid |
GET |
查询 Space 内 principal 信息 |
bot_api.go:429 |
文件上传与下载
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/file/upload / /v1/bot/upload |
POST |
文件上传（Bot 发送文件入口） |
bot_api.go:447/448; file.go |
/v1/bot/file/download/*path |
GET |
文件下载 |
bot_api.go:449 |
/v1/bot/upload/credentials |
GET |
获取上传凭据（presign 相关） |
bot_api.go:450 |
/v1/bot/upload/presigned |
GET |
获取预签名 URL（用于直接 PUT 到 MinIO） |
bot_api.go:451 |
文件分两种上传路径：走 octo-server 中转上传，或走 presigned URL 直接 PUT 到 S3/MinIO（SigV4 签名）。单端口部署下 presign URL 指向 nginx 同端口，bucket-name 路由不破签。（来源：049 部署形态总览 SigV4 不破签章节；卡片正式口径 v1.0 排障路径）
命令注册
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/setCommands |
POST |
注册 Bot 斜线命令列表（客户端展示 Bot 命令菜单） |
bot_api.go:445; commands.go |
语音（opt-in，speech profile 启用后）
| 端点 |
方法 |
用途 |
来源文件 |
/v1/bot/voice/context |
GET/PUT/DELETE |
语音上下文管理 |
bot_api.go:457-459 |
/v1/bot/voice/transcribe |
POST |
语音转写 |
bot_api.go:460 |
注：语音能力依赖 speech profile 启用（octo-speech 服务）+ 语音引擎（默认 qwen），属 opt-in 可选能力。（来源：049 部署形态总览 speech profile 章节）
内部版独有Bot相关能力（v0.4新增）
以下能力为OCTO内部版独有模块提供的Bot相关能力（开源版GitHub代码中未包含）。标注了确认状态——✅ 产品管家已确认、⚠️ 路由存在但能力待源码验证。
1. 文档评论@Mention链路（✅ 已确认）
- 用户在文档评论区 `@Bot`
- docs-backend存储评论 → 内部调用octo-server `POST /v1/internal/bot-mentions`（事件类型 `docCommentMentionEventType`）
- octo-server校验+幂等claim+入Redis bot_task队列
- openclaw-channel-octo插件收事件，隔离会话派发
- Bot使用octo-cli（bot自身token） 编辑文档正文并回复评论串
- ❌ Bot Token不能直接调
/v1/bot/docs 类接口（octo-server bot_api路由无此注册）
- ❌
/api/v1/docs 需登录态，Bot Token调不了
- ⚠️ 仅支持BotFather创建的User Bot（
bf_前缀），不支持App Bot（app_前缀）
- ⚠️ Bot必须先被加为该文档成员且拥有相应权限
- ⚠️ 有灰度门控
gate.Allows(DocID, SpaceID)，属MVP阶段
- ✅ PPT评论@Bot同链路（插件v1.5.0+）
2. Drive Bot API（⚠️ 路由存在，能力待源码验证）
- nginx路由存在
/v1/bot/drive/ → drive:8080（用户侧/v1/drive/、Bot侧/v1/bot/drive/均反代到octo-drive:8080）
/v1/bot/drive/ 实际暴露哪些Bot API端点（上传/下载/列表/分享/读内容？）- Bot能否读取/操作网盘文件给AI做知识库
- Bot能否上传文件到网盘
- 权限模型（Bot操作网盘文件的权限边界）
3. 语音纠错API（✅ 已确认）
| 端点 |
方法 |
用途 |
确认状态 |
/v1/bot/voice/context |
GET/PUT/DELETE |
Bot侧管理语音纠错上下文（人名/专有名词/术语） |
✅ 产品管家确认（Speech模块§1.7/§3.5） |
/v1/voice/context |
GET/PUT/DELETE |
用户侧语音上下文管理 |
✅ 部署配置+源码路由确认 |
4. Bot OBO（On-Behalf-Of）消息搜索（✅ 已确认）
| 端点 |
方法 |
用途 |
确认状态 |
POST /v1/botfather/messages/search |
POST |
以Bot主人身份搜索消息（OBO模式），权限等同Bot主人 |
✅ 产品管家确认 |
- Bot通过此API可以以Bot主人的身份和权限搜索消息（On-Behalf-Of模式）
- 权限等同owner（不是Bot自身权限，而是owner的权限）
- 使用方：octo-cli使用此API帮用户搜索消息
- 消息搜索尊重权限（解散状态authz校验）
5. Summary Agent触发（✅ 已确认）
| 能力 |
说明 |
确认状态 |
| Agent可触发/执行总结 |
Agent可以触发Summary生成总结任务，总结结果可供Agent引用 |
✅ 产品管家确认（PR#850，v2026.08.17） |
- Summary模块支持Agent驱动触发（v2026-08.17，PR#850）：Agent可触发/执行总结
- 总结结果可供Agent引用，作为AI协作上下文
- Agent触发总结的具体API端点路径待确认（是内部服务间调用还是经Bot API公开暴露？SM-08）
6. User Bot vs App Bot（内部版场景差异）
| 场景 |
User Bot（`bf_`前缀） |
App Bot（`app_`前缀） |
| 基础IM（发消息/收事件/卡片/文件/群管理） |
✅ |
✅（受space scope约束） |
| 文档评论@Mention链路（编辑文档正文） |
✅（MVP，需被加为文档成员） |
❌ 不支持（产品管家明确仅User Bot） |
| Bot OBO消息搜索 |
✅ |
待确认 |
| 语音纠错API |
✅ |
待确认 |
内部版Bot能力确认状态汇总
| 能力 |
Profile依赖 |
确认状态 |
售前可承诺 |
| 文档评论@Mention→Bot编辑正文 |
docs |
✅ 产品管家确认 |
✅（标注MVP/灰度/User Bot only） |
| docs-html Bot创建HTML文档 |
docs + docs-html |
✅ 产品管家确认（BOT_AUTH_ENABLED） |
✅（Bot创建HTML文档转发到聊天） |
| Drive Bot API（/v1/bot/drive/） |
drive |
⚠️ 路由存在，能力待D-05源码验证 |
❌ 待验证后承诺 |
| 语音纠错API（/v1/bot/voice/context） |
speech |
✅ 产品管家确认+源码路由 |
✅ |
| Bot OBO消息搜索 |
search |
✅ 产品管家确认 |
✅ |
| Bot文档/网盘OBO搜索 |
search + doc-index/drive-index |
⚠️ SR-07待验证 |
❌ 待验证 |
| Agent触发Summary |
summary |
✅ 产品管家确认（PR#850） |
⚠️ API端点路径待确认 |
后续待建设子页（骨架占位）
06-api-integration/Webhook与事件回调.md（待建设）：incoming-webhook 端点、card_action 回调、事件格式、ACK 机制、DLQ06-api-integration/卡片API详解.md（待建设）：raw card / template card 三模式 schema、profile 协商、降级、limits06-api-integration/文件上传API.md（待建设）：中转上传 vs presigned PUT、bucket 白名单、SigV4 签名要求、大小限制06-api-integration/群组与Thread API.md（待建设）：群组 CRUD、成员管理、Thread 生命周期、AI container 保护06-api-integration/用户与Space API.md（待建设）：用户查询、批量、space 成员、权限模型06-api-integration/错误码与限流.md（待建设）：全局 per-IP 令牌桶、per-Bot heartbeat/register 桶、4xx/429 处理06-api-integration/认证与安全.md（待建设）：bot_token 获取/刷新、register 流程、OBO 授权、签名
版本记录
- v0.1（骨架）：端点列表来自bot_api.go grep，骨架占位
- v0.2（Q1-Q4回填）：API体系全貌8套分类、双token鉴权模型、消息模型、群Thread管理边界
- v0.3（Q1-Q4收官）：端点表格补全来源文件行号、语音端点补充、Management/Admin补实
- v0.4（2026-09-21，P0扩展补漏）：新增「内部版独有Bot相关能力」章节，覆盖6项：文档评论@Mention链路(✅)、Drive Bot API(⚠️待验证)、语音纠错API(✅)、Bot OBO搜索(✅)、Summary Agent触发(✅)、User Bot vs App Bot内部版差异；新增内部版Bot能力确认状态汇总表；更新frontmatter增加模块文档来源；confidence维持high（开源API部分high，内部版能力标注确认状态）
v0.1 骨架边界与注意事项
- 本骨架端点列表仅来自
bot_api.go 路由注册行 grep，未精读每个 handler 的请求/响应格式、字段、权限检查。
/v1/obo/* 子路由组（OBO 授权）有独立路由但本文未展开，待 P2 精读。- incoming webhook 路由（群级和 Thread 级）的具体端点方法/路径未展开，待精读 incoming_webhook.go。
- 所有端点字段级 schema、默认值、错误码均为"待验证/待背书"，不得写成正式对外 API 文档。
- 本文不替代官方 API 文档；正式对外 API 文档需 octo-server 官方 API 文档或服务端负责人背书。
- 路由前缀均为
/v1/，版本前缀暗示未来可能有 /v2/，但当前未看到 v2 路由，待确认。