 anonsaber
|
399b26918e
|
docs: ④ /debug/* 配套文档 + 全量锚点重锚 + AGENTS v3 版本基线（01a0e6de）
## 锚点重锚（afa6cec 之后）
④ 对 notify.rs 的编辑使一批 `notify.rs:N` 引用整体失效。全量重扫 8 个 md、
165 个 src 锚点，0 硬错误（越界 / 区间全空 / 单行指空行三类全查）。修正要点：
- reference.md（30+ 处）：dedup/committed/inflight/ratelimit 键调用点、
error_response 320-328、error_response_with_id 1087-1093、readiness 161、
router 1275 + routes 1304-1318、worker 330、main.rs 40/50/34/78-81、
NoopWorker 由 notify.rs 更正为 worker.rs:142-144、
PROBE_TIMEOUT 73 与 tokio::join! 147、state.rs 639。
- deployment.md：149-152→227-230、159/172→239/252、index.js 40-55→45-60。
- retired.md：704→717、887-890→897-900、326→330、873→884。
- roadmap.md：95→175；design.md：main.rs 109→128。
- cloudflare-worker 侧 4 处 stale：ROUTE_METHODS 45-60、404 77-78、
405 80-83、503 85-93。
## /debug/* 文档
- deployment.md 新增 §2.1：双因子门禁、7 条路由状态码表、/debug/config 字段清单、
三条部署约束、生产建议；§5 env 表补 --debug / DEBUG_TOKEN。
- README.md / README.zh-CN.md 各加一段「远程联调面（可选，默认关闭）」，指向 §2.1。
- design.md 新增 §7.6「为何默认绝对关闭」：双因子挂载、404 而非 401
（401 会泄漏路由存在性）、无默认开启回退、不在网关白名单内 fail-closed。
## 文档纠错（与任务书相反，已按源码核实）
- /debug/worker 是 GET 不是 POST（debug.rs:79）。
- /debug/config 不是「只出布尔」：明文回 jmap.{session_url,username}、
telegram.chat_id、llm.{base_url,model} 与全部 timeout/retry，
仅 5 个凭据字段出 *_configured。文档措辞改为「不含凭据，不是全脱敏」。
- 门禁位置更正：--debug 读 main.rs:99、DEBUG_TOKEN 读 main.rs:100-103、
merge 在 notify.rs:1320-1321（无 DEBUG_BASE 常量，路径为字面量）。
## AGENTS.md
- 版本基线 v3（代码 afa6cec / 文档 e502c40），三处文档基线号 c5bc7b8→afa6cec。
- 新增 2 个 ID：SAF-DEBUG-ORIGIN-ONLY（不在网关 14 条白名单，Worker 404
route not forwarded，只能直连 origin）、SAF-DEBUG-ALLOWLIST。
- §6 deployment.md 行、§7 六行 ID 定义点回填文档位置。
## 未决项登记
- roadmap.md 新增：SAF-DEBUG-ALLOWLIST —— debug.rs:232-235 的白名单判定
「非空且不含」导致业务白名单为空时 /debug/notify 的 chat_id 不拦截。
本轮不改代码（该面默认关闭且需 Bearer，空白名单下主产品本就接受任意 chat）；
若要收紧需改为「空白名单则拒绝」+ 补测试 + 跑 gate。
## 校验
文档校验器 0 error；负向对照断链/死锚点/奇数反引号/页内锚点 4 类注入全命中。
48 张 markdown 表 0 处单元格数不符。行数合计 2415。纯文档，未触碰 src/ web/
cloudflare-worker/。代码基线仍 afa6cec，gate 49 passed / 0 failed / 1 ignored。
|
2026-09-28 16:20:18 +08:00 |
|
anonsaber
|
e35cc64ce3
|
docs: 清理废弃/虚构条目，新增 retired.md 独立废弃记录
新增 docs/retired.md（114 行）作为唯一废弃/虚构条目登记处：
- 12 条未采用的路线（teloxide / feature 集 / teloxide-core 回退 /
grammers / BotError 六个未落地变体 / 速率桶+429 分支 / 多步 FSM /
模块子树拆分 / telegram_dispatch 测试 / docker healthcheck 示例）
- 原 teloxide 候选对比评估记录 + FSM 五态状态表（保留决策依据，非当前事实）
- 24 条虚构条目（文档曾写、src/ 从未有）：幽灵模块树、delivery:pending 键、
check_config_reload、PushVerification、CancellationToken、Preview、
LlmErr、四个不存在的 LLM 环境变量、llm.call span、熔断/半开设计等
- 2 条已删除文档（docs/todo.md、HANDOFF.md，后者从未进入 git 历史）
- 3 步重启流程
docs/design.md 850 → 764 行：17 处目标形态改写为可核实的当前事实。
重点：§4 压缩并指向 retired.md；§5.2 补 Channel/Notifier/MessageAdapter
三 trait 零实现；§6 树改为真实 12 文件结构；§8.1 换成真实 src/error.rs
（原目标形态 6 变体整体移至 retired.md）；§8.3 明标无 tracing/metrics/
优雅关闭；§10.0 GATE-P0 已过；§10.5 明标 notify.rs 平铺单文件；
§11.4-11.7 的 17 条 Q 收敛为一节（均已由已实现代码回答）；
§12 全节重写（LlmClient 非 AiClient、AiError 3 变体、无熔断、
无附件、无长邮件保护、read_email 实取全文送 LLM）；§12.8/§12.9 合并。
docs/reference.md：删 delivery:pending:{stream} 换真实 stalwart:{jmap,telegram}
流名；删 cloudflare-worker/src/commands.rs 论断；键锚点校正；补网关
fail-closed 无开关说明。
AGENTS.md：§6 注册 retired.md；新增 §6.3 幽灵名规则（文档出现的模块/函数/
键必须是 src/ 真实存在，要留不存在的名字必须同时登记 retired.md）；
teloxide 专属措辞通用化为「渠道层不引入第三方 Bot 框架类型」；
保留「不得声称使用未引入依赖」约束。
docs/roadmap.md：item 2/26 按真实数字重写（18 条路由 12 条经 Worker 转发，
不转发的 6 条中仅 2 条需业务直连）；决策待定补处置建议。
README / README.zh-CN 阅读表加 retired.md，保持 1:1 对等。
待决策项收敛结论：真剩 2 项（Q-DEP-A Worker 白名单、Q-DEP-B 平台选型），
均为上线时运维选择，不影响代码结构与门禁，可挂起不产生技术债。
src/、web/、cloudflare-worker/ 零改动。基线仍 45 passed / 0 failed / 1 ignored。
|
2026-09-27 21:53:58 +08:00 |