anonsaber
afa6cec8ef
debug: 新增 /debug/* 远程联调面，双因子门禁默认绝对关闭（01a0e319）
...
新增 src/debug.rs：/debug/ping、/config、/redis、/jmap、/telegram、/worker 六个只读
探针 + POST /debug/notify 一条测试出站消息。
SAF-DEBUG-GATE 双因子，缺任一即完全不挂载路由（请求落到通用 404，无"未配置即放行"
降级）：
- 启动命令带 --debug（main.rs 最小 std::env::args 解析，未新增依赖）
- Secret 环境变量 DEBUG_TOKEN 非空
两层执行点：main.rs 推导 debug_token 并传入 router builder（None 则 debug_router 不被
merge）；debug.rs 侧 auth_token 缺失时直接返回空 Router。
SAF-DEBUG-AUTH：每个 handler 先做 Authorization: Bearer DEBUG_TOKEN 常数时间比较
（复用 worker_authorized），失败 401，鉴权通过前不产生任何副作用。
探针只读侧全部复用现成实现，不另写一套：Redis 走 is_enabled，JMAP 走
probe_jmap_session，Telegram 走 probe_telegram_get_me，出站走唯一构造点
business_client（notify.rs 新增 pub(crate)）到 send_text，/debug/notify 与
refresh_business_config 共用同一条客户端构造路径。
SAF-NO-SECRET-ECHO / SAF-LOG-PURITY：/debug/config 只回"是否配置"、计数与超时等
运行时参数，bot token / JMAP password / worker / webhook / reconcile token / LLM key
一律不出现在响应体；DEBUG_TOKEN 只在鉴权内部暴露，不回显、不入日志，日志仅一条
"debug endpoints enabled" 且不含令牌值。allowlist 用 chat_allowlist_snapshot 取生效值
（运行时业务配置优先、否则启动值），/debug/notify 显式 chat_id 不在 allowlist 则 403。
ARCH-LB-WORKER 白名单不含 /debug/*，该面仅供直连 origin 联调，公网入口不可达。
AGENTS.md 登记 4 个稳定 ID：MOD-DEBUG / SAF-DEBUG-GATE / SAF-DEBUG-AUTH /
REQ-DEBUG-ENDPOINTS（§2 第 19 条硬边界、§5 测试条、§7 索引 4 行）。
调试路由测试（4 项，notify.rs + debug.rs 内）：Bearer 放行 200、缺失/错误令牌 401、
未提供 DEBUG_TOKEN 因子时 /debug/* 完全不注册而落 404、/debug/notify POST 未认证 401。
门禁四段全绿（rust:1-slim-bookworm）：cargo fmt --all -- --check / cargo check --locked
/ cargo clippy --locked --all-targets -- -D warnings / cargo test --locked =
49 passed / 0 failed / 1 ignored。
2026-09-28 15:00:49 +08:00
anonsaber
cc645020d9
docs: /ready 端到端就绪语义同步 + 删除 Redis 错误映射虚构断言
...
两件事一批提交（全部 docs-only，无代码改动）：
① /ready 语义升级为端到端就绪（对应 commit c5bc7b8ed93358
2026-09-28 12:08:33 +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
anonsaber
24cfbb45b0
docs: 重构文档体系 — README 瘦身中英对等 + 新增 reference.md 权威事实表
...
- README.md / README.zh-CN.md 瘦身至 ~100 行，五节 1:1 对等（是什么/5分钟/配置入口/安全边界/去哪读更多）
- 新增 docs/reference.md：Redis 键+TTL+写者+读者、错误 envelope+Retry-After、后端路由与网关白名单矩阵、env 三层等单一权威表（顶部 verified against ed93358）
- 新增 docs/roadmap.md 取代 docs/todo.md（只放缺口/阻塞/阶段目标/待决策）
- docs/design.md 保留架构语义，可查表改引 reference.md；修正 /search 未实现、XAUTOCLAIM 阈值矛盾、teloxide 幽灵引用等 9 处标注
- docs/deployment.md §8.1 重写，删除依赖不存在子命令/curl 的必然失败 healthcheck 示例
- AGENTS.md §6 登记 reference.md/roadmap.md + 冲突仲裁「以 reference.md 为准」+ 中英同轮同步/公共 API 变更规则
2026-09-27 18:55:38 +08:00
anonsaber
ed93358e29
feat(notify): unify /ready not-ready 503 into the error envelope
...
- GET /ready: ready -> 200 + diagnostic report (unchanged success body);
not ready -> 503 + {"error":"service_unavailable","request_id":id}
+ Retry-After: 30, consistent with the other public entry points
- drop the legacy {"status":"not_ready"} diagnostic block from the 503 body
(backward compatibility not required)
- HTTP 200/503 semantics preserved, so Uptime Kuma HTTP(s) monitors
(status-code based) keep working
- sync docs: README.md, README.zh-CN.md, docs/design.md, docs/deployment.md,
AGENTS.md, docs/todo.md
2026-09-27 13:11:29 +08:00
anonsaber
a8fad19daa
docs: default README to English, reconcile docs, drop HANDOFF
...
- README.md is now English; add README.zh-CN.md with cross-links; both versions
cover the same 40 sections and the same key facts
- correct stale docs/design.md 10.5.1 and docs/todo.md to the current code
(XAUTOCLAIM threshold, malformed-entry ACK, error envelope now done)
- replace the temporary HANDOFF.md with docs/todo.md (unfinished work + blockers)
- adjust docs/deployment.md and AGENTS.md accordingly
2026-09-27 12:56:04 +08:00
anonsaber