v1.20.0接入路径修复与全面文档化 (MCP 反代打通 · 接入总览 · 系统架构图)
一次「盘查 → 发现真问题 → 修 → 补文档 → 上防漂移门」的完整闭环。起点是一个朴素的问题: 「主站 / boss 到底能不能通过命令行访问?」 盘查下来发现: 官方主推的接入路径实际是坏的, 公开 API 文档停在两个月前的无认证时代, 而门槛最低的那条路根本没有文档。本版把这些一次性修完, 并给每处都加上防止再次漂移的自动化门。
① MCP 主协议经反代恒返回 421 —— 修好一条「文档说可用、实际走不通」的路
公开站教用户配一个文件即可接入, 但实测该端点恒定返回 421。逐层定位到根因: MCP SDK 在服务绑定本机时会自动开启 DNS-rebinding 防护, 而它的白名单硬编码只认本机地址 —— 经反向代理进来的请求, Host 头是公网域名, 于是一律被判死。
修法是加白名单, 不是关防护 (关掉等于对任意 Host 敞开):
- 新增域名白名单配置项; 未配置时行为完全不变, 交回 SDK 默认, 零回归风险
- 配置后防护保持开启, 白名单 = 本机默认 + 配置的域名 (同时放行带端口写法)
- 回归测试直接复现现网故障: 不配白名单 → 421; 配了 → 放行; 未列出的域名 → 仍被挡 (白名单不是敞开)
- 修复后从公网跑通完整 MCP 握手与工具列举, 三个工具全部可用
② 公开 API 文档脱漂 + 接口契约门
公开的集成手册仍写着「默认无认证」, 而实现早已是 Bearer 必填 + fail-close —— 外部集成方照抄示例必然失败。
- 认证章节重写: 真值表 + 401 与 503 的辨析 (前者是你 token 不对, 后者是服务端没配, 重试永远好不了) + 两套服务 token 不通用的说明
- 四处客户端示例 (curl / Python / 常驻 runtime / Agent 框架) 全部补上认证头; 端点表补齐遗漏路径并逐条标注是否需认证
- 接口规格此前是手工快照, 漂了近两个月 (九条路径只剩五条、认证信息全空)。改为从代码自动生成, 并把认证依赖归一成标准的安全方案声明 —— 归一规则纯由代码推导, 不会与实现脱节
- CI 加一道契约门: 路径集合 / 每个操作是否需认证 / 安全方案在位, 三项与代码不符即红。刻意不做逐字节比对 —— 那会因无关的依赖升级误红, 已用固定依赖版本实测确认
③ 接入总览页 —— 四条路径首次放在一起对比
四条接入路径此前散在三处文档 + 一条零文档, 没有任何一页把它们放一起比较, 新人不知道该走哪条。
- 决策树: 四张卡对号入座, 不必读完整页
- 四路对照表: 含「谁跑模型」这一关键列 —— 它决定要不要自备密钥、费用算谁的
- 两套服务澄清: 判断流水线与元数据服务是两个独立服务, token 不通用 —— 这是最常见的认证失败来源, 此前站上无一处讲清
- 错误码速查: 按「该谁修」排序, 标明哪些重试无用
- 排障速查: 把排查过程中真踩到的坑全部收录
④ 体验接口首次文档化
门槛最低、免凭证的那条路此前只在首页前端代码里出现, 靠读代码才能反推。现补齐: 五个端点 + 配额表 (全部从代码读出) + 三格式报告下载 + 公开判例库。并在显著位置写明提交内容会公开保留七天、请勿提交机密 —— 这条此前只活在代码注释里, 访客无从知晓。
⑤ BYOM 一条命令跑完流水线 (两个可下载脚本)
自带模型那条路的真实痛点是整套编排要自己写。给两个可直接下载的单文件脚本 (bash 与 Python), 把「起单 → 跑合成 → 逐评委打分 → 回传 → 聚合出报告」压成一条命令, 模型调用留在使用方自己的进程里。
- Python 版零第三方依赖, 评委并发, 支持两类模型网关; 换供应商只改一个函数
- 两者都在常见错误码上当场给提示, 不用回来翻文档
- 端到端验证: 让脚本跑通真实的服务端, 证明协议处理与契约一致 —— 哨兵确实被替换、每位评委独立打分 (提示词里不含他人评语)、宣称零依赖属实
权衡记录: 评估过发布成包的方案, 否决。四条路里三条本就不缺包 (一条 curl / 一个配置文件 / 另一条是不同技术栈且依赖本地数据), 真实收益只在这一条; 而单文件脚本能拿到同样收益, 又避开「公开发布不可撤回」与「与授权使用定位冲突」两个实际风险。
⑥ 系统如何运作 · 五层架构 (网页 + 手册文档)
此前没有任何一处讲清「整个系统怎么运作」—— 有项目进度图、有评委体系图、有方法论页, 唯独缺一张能一眼看懂全局的图。
新增分层架构页 (入口 / 知识 / 流水线 / 产出 / 回路), 用原生样式绘制、不引第三方库。每层配「解决什么问题 / 没有它会怎样 / 关键机制」三栏, 让设计动机可见; 另加「跟一次判断从头走到尾」时间线, 与四条设计取舍问答 (为什么要人工确认闸 / 为什么评委互相保密 / 为什么版本快照不能改 / 为什么知识库不吃判断产出)。手册同步一份文字版便于检索引用。
回路层被刻意画得最醒目 —— 它是最容易被省掉、也最不该省的一层: 没有它, 系统永远在重复同一类错误。
⑦ 顺带修补: 公开层安全闸的扫描面缺口
新增可下载脚本时发现: 公开层预检的文件类型白名单不含脚本类型, 意味着放在公开目录里的脚本完全不在扫描面上。补入后扫描面扩大, 并做负向验证 —— 往示例里塞入敏感内容, 闸门正确拦下。此缺口非本版引入, 只要有人往公开目录放脚本就会中招。
一句话: 从「能不能用命令行访问」这一个问题出发, 修好一条对外宣称可用却实际走不通的接入路径, 补齐两处严重过时与一处完全缺失的文档, 并给每一处都加上防止再次漂移的自动化门 —— 让「文档说的」和「代码做的」不再各走各的。
质量门
全量单测绿 (+44 条新增: MCP 白名单回归 / 接口契约门 / BYOM 端到端 / 页面守卫) · MCP 公网握手与工具列举实测通 · 接口契约门在固定依赖版本下实测通 · check_public_safe (含新扩的扫描面) + redact_check 0 命中 · sitemap 无死链 · handbook 构建通过 · CI unit/preflight/build/CF Pages 全绿