Public
/
MessageWeave
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
29 Commits 1 Branch 0 Tags 10 MiB
Commit Graph

4 Commits

Author SHA1 Message Date
anonsaber e502c40a9e docs: SPA 管理凭据 trust-root 同步（README/zh-CN/reference 三处措辞 + 锚点修正） 
承接 800d6e0（SPA 凭据改用 CONFIG_ENCRYPTION_KEY）：

- README.md §5、README.zh-CN.md §5：trust-root 段落补齐「配置密钥即管理密钥」
  的事实陈述，消除「Redis ACL 密码」的残留耦合叙述。
- docs/reference.md §3 Trust root：1:1 重写为配置密钥派生路径，移除不存在的
  "refresh loop" 叙述（实际为 refresh_business_config 单次调用 + guard）。
- docs/reference.md §3 锚点修正：expires_in 引用 notify.rs:700→:787
  （refresh_business_config 现位于 :717，expires_in 在 :787）。

交付方：文件规划助手（任务 01a0e379）。文档校验器 0 error，负向对照 4/4。
 2026-09-28 15:08:04 +08:00
anonsaber cc645020d9 docs: /ready 端到端就绪语义同步 + 删除 Redis 错误映射虚构断言 
两件事一批提交（全部 docs-only，无代码改动）：

① /ready 语义升级为端到端就绪（对应 commit c5bc7b8 的实际行为）
- ARCH-READY-BASELINE 从「配置完整性 + Redis 可达性」改为：配置完整性
  + Redis 可达 + JMAP session 探针 + Telegram getMe 探针，四者全过返 200
  与就绪报告，任一失败返 503 + 标准错误 envelope + Retry-After: 30
- 探针细节：各 PROBE_TIMEOUT 3000ms、tokio::join! 并行、最坏约 3s
  （先前文档写「串行 / 最坏 6s」是错的，已全量修正 10 处，含 AGENTS.md /
  design.md / deployment.md / roadmap.md / reference.md / README 中英）
- LB 探针超时下限从「> 6s」改为「> 3s（建议 >= 10s）」
- JMAP 探针实际行为：取 JMAP_SESSION_URL 的 origin 后 GET
  {origin}/.well-known/jmap 并带配置的 Basic 认证（不是打裸 session URL）；
  原因是裸 URL 不带认证会永远 not-ready，进而让 ingress 停止路由
- deployment.md 新增 /ready 出站 egress 硬依赖说明：egress 不通则长期 503，
  而 reqwest 以 default-features=false 编译不解析 HTTPS_PROXY
- reference.md Retry-After 规则改准：error_response 仅在 retry=true 时设置；
  error_response_with_id 无条件设置但仅用于 push register/disable 的
  push_state_unavailable / push_destroy_failed（恒 503）；503 错误码表补上
  这两个此前漏掉的码
- GATE-READY-DEPS 门禁已闭合，从 AGENTS.md 与 roadmap.md 删除该 ID

② 删除「Redis 错误映射」这条虚构断言（代码缺口 4 -> 3）
- roadmap.md 与 design.md:634 的同一条断言删除；design.md 脚注「4 条」->「3 条」
- 根因：消费入口是 HTTP handler worker（notify.rs），不是后台循环
  —— 全仓 src/ 零 select!、无信号处理、无常驻 worker 进程；read_batch 与
  retry_or_dlq 的 Err 均经 ? 上抛，调用方一律返 503 + retryable=true。
  原先描述的「循环不因单次失败退出」这个前提本身不成立
- retired.md 新增一条虚构断言记录，完整保留原始断言与推翻依据
- roadmap 验收待办同步：/ready 端到端探测转已完成，并注明两个探针是可复用
  纯函数、④ 远程 debug 应直接复用同一实现，不要另写一套

③ 顺手修正本轮代码移动导致的失效行号锚
- retired.md：refresh_business_config 628->704；lock:push-register 810-819->887-890；
  register_push 668->873；notify::push_handler 改引真实函数名 jmap_push /
  worker / reconcile（原行号 250/97/136 全错，且 push_handler 非真实函数名）；
  worker safelist fail-closed index.js:69-82 -> :77-92
- reference.md：router 1238-1265 -> 1250-1277；/worker 314 -> 326；
  路由表补上此前漏掉的 /、/assets/config.js、/assets/styles.css

基线：三处「验证基线」（roadmap.md:5、retired.md:7、reference.md:6）由
ed93358 更新为 c5bc7b8。

校验：8 个 md 代码块偶数、无行尾空格、无 CR；5 个文件全部表格列数一致
（剥掉 code span 后再计数）；相对链接与锚点全部可达。
Rust 门禁不受影响（无 src/ 改动），基线仍为 45 passed / 0 failed / 1 ignored。
 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