Files
WebHooker/docs-plan.md

8.8 KiB
Raw Permalink Blame History

WebHooker 文档评估与优化计划

生成日期:2026-08-13 范围:docs/(VitePress,en+zh)、README.md / README.zh.md、AGENTS.md、config.example.yaml、.env.example


一、现状总览

文档 规模 状态
docs/(VitePress,en+zh 镜像) 11 页 ×2,约 75KB 结构完整但存在事实错误、覆盖缺失、信息架构混乱
README.md / README.zh.md 363 行 与 docs 大量重复(secrets、GitHub App 设置、部署),已出现漂移
AGENTS.md 222 行 基本同步,个别过时
config.example.yaml / .env.example — 良好,但 README/AGENTS 中 DOCS_URL 等变量名与代码不符(.env.example 正确)

二、事实错误(需修复)

  1. GITHUB_APP_ID / GITHUB_PRIVATE_KEY "未被代码使用"说法过时

    • server/lib/github/oauth.ts:27-69 已用它们生成 App JWT 查询安装账号(install 绑定流程)
    • 过时位置:configuration.md:18-21、README.md:60-61/198、deployment.md:40-44、getting-started.md:40-42(en/zh 共 8 处)
    • deployment.md 内部自相矛盾:40-44 行说"无需设置",125-127 行又要求生成私钥保存到 GITHUB_PRIVATE_KEY
  2. DOCS_URL / GITHUB_REPO_URL / LEGAL_CONTACT 变量名错误

    • README.md:74-76 与 AGENTS.md:218 使用旧名
    • 代码实际读取 NUXT_PUBLIC_DOCS_URL / NUXT_PUBLIC_REPO_URL / NUXT_PUBLIC_LEGAL_CONTACT(nuxt.config.ts + runtimeConfig,.env.example 正确)
  3. DELETE /auth/token/:userId 鉴权标注 "None"(api/overview.md:23)

    • 实际要求 admin session(oauth.ts:371-377),无 session 返回 401
  4. Generic fallback 描述过时(events/supported.md:60,en/zh)

    • 声称"原始 payload 代码块(截断 1000 字符)"
    • 实际 server/lib/formatters/generic.ts 只输出 title + color + author,无 payload 代码块
  5. 事件数量口径不一

    • "28"(docs/index、configuration、deployment、README)vs "29"(contributing.md、AGENTS.md:126)
    • 实际 server/lib/formatters/index.ts switch 有 29 个 case(含 custom)
    • 建议统一为:"28 种 GitHub/Gitea 事件 + custom"
  6. events/supported.md 事件表缺 custom 行(en/zh 都缺)

  7. src/formatters/colors.ts 旧路径残留(events/supported.md:40,en/zh;应为 server/lib/formatters/colors.ts)

  8. api/overview.md 端点表缺 9 个端点

    • POST/GET /admin/api/groups/:id/invites、DELETE /admin/api/invites/:token
    • GET /admin/api/audit、GET /admin/api/groups/:id/webhook、POST .../webhook/regenerate、DELETE .../webhook
    • GET /admin/logout、GET /admin/invite?token=
    • configuration.md 里反而齐全——两处清单已漂移
  9. providers 校验接受不存在的 gitlab 值(admin.ts:288)

    • 错误信息为 "github" | "gitea" | "gitlab",但无 gitlab provider 实现
    • 需决定:删掉(与文档 github/gitea 对齐)或保留(为未来扩展)

三、覆盖缺失

  1. KV 布局表缺 tenant:{groupId}(configuration.md:326-343,en/zh 都缺)

    • 租户态 dedup key delivery:{groupId}:{id} 只散见正文
  2. NUXT_PUBLIC_DOCS_URL / NUXT_PUBLIC_REPO_URL / NUXT_PUBLIC_LEGAL_CONTACT 未收录

    • configuration.md Secrets 表(en/zh)都未记录这三个变量
  3. bot 命令文档碎片化

    • Discord /gh 命令只在 README(Bot Commands 段落)
    • Telegram /gh 命令只在 deployment.md
    • 无独立页面,sidebar 无入口
  4. 无独立页面/章节:

    • 调度任务(cron */5:discord-sync / telegram-sync / audit-prune)
    • i18n 消息语言与 i18n:* KV 覆盖机制
    • 消息格式规范(只在 AGENTS.md,属开发内部文档)
    • 发送日志(send_logs)字段与错误码说明
    • FAQ / 故障排查
  5. 次要缺失:

    • 路由上限 200 / 分组上限 100(admin.ts:76,257)
    • X-Gitea-Delivery 头参与去重(providers/gitea/parse.ts:60)
    • install 选择页需要登录 session(oauth.ts:153-158)
    • logTarget 摘要消息只列前 10 条 route×target + "+N"(dispatch.ts:88-100)

四、结构问题("杂乱"的主因)

  1. configuration.md 是 356 行巨型文档

    • 密钥、提供方、Web UI、端点、自定义 webhook、租户隔离、路由、分组、角色、过滤器、KV/D1 布局全挤一页
  2. API 参考混乱

    • admin API 同时在 configuration.md(Web UI→端点表)、api/overview.md、README 出现三份,已开始漂移
  3. sidebar 信息架构

    • 只有 Guide / API / Events 三类
    • docs/contributing.md 不在 sidebar(孤儿页)
    • 无 Bot 命令、无 FAQ、无故障排查入口
  4. README 与 docs 严重重复

    • secrets 表、GitHub App 设置、Discord/Telegram bot 设置、部署步骤在 README 和 docs/deployment.md 各写一遍
  5. docs 配置引用不存在的 logo.svg

    • docs/.vitepress/config.ts 引用 /logo.svg(favicon + 主题 logo),文件不存在(404)
  6. footer copyright 仍写 2025(当前 2026)


五、中英一致性(zh 滞后)

严重度 文件 差异
高 guide/introduction.md zh 技术栈仍是"Nux3 静态 SPA",en 已为"Nuxt 4 (Vue 3 + Tailwind CSS v3)"
高 guide/getting-started.md zh 脚本表缺 bun run build、bun test 两行;bun run dev 描述不一致(wrangler vs Nuxt HMR)
中 api/overview.md zh 漏"or manage a group"准入条件;漏"空过滤器仅 fallback 路由允许"
低 guide/configuration.md 可选密钥表行序不同;keyword 示例 zh 多 *release-*;"manage everything" 译作"管理路由"
低 guide/filters.md zh 一处"/ 包裹"应为"// 包裹"(同文件其他处正确)
低 index.md 2 处 feature 描述中文略精简(未列签名头部、未列 slash commands and buttons)

完全一致的文件对:guide/deployment.md、api/actions.md、api/oauth.md、events/supported.md、contributing.md。


六、建议的重构方案

A 阶段:事实修正(低风险,必做)

  • 修复"二"中全部 9 项 + "三"的 KV/变量 2 项
  • 修复中英"高/中"级差异
  • logo.svg(补文件或从 config 移除引用)、footer 年份
  • 统一事件数量口径(28 + custom)

B 阶段:信息架构重构

建议新结构:

指南 Guide
  Introduction / Getting Started / Deployment(保留现状)
  核心概念(从 configuration.md 拆出):
    Routes & Targets
    Groups & Access Control(角色/邀请/自助注册)
    Webhook Ingress & Tenancy(全局/分组端点、custom、App 隔离)
  消息与命令(新):
    Discord /gh Commands(合并 README 的 Bot Commands 段落)
    Telegram /gh Commands
    Message Format & i18n(新页:标题规范、emoji 开关、语言覆盖)
  运维(新):
    Scheduled Tasks
    Storage Layout(KV / D1 布局)
    Send Logs & Audit Logs
    FAQ & 故障排查

参考 Reference
  API(拆分 Public API 与 Admin API,与 configuration 去重)
  Supported Events(补 custom 行、修 generic 描述)

配置(单一权威来源)→ configuration.md 瘦身为"完整参考"
README → 精简为 features + quick start + 命令摘要 + 指向 docs 的链接

C 阶段:README 瘦身

  • README 保留:简介、features、quick start、/gh 命令摘要、部署速览、License
  • 移除与 docs 重复的完整表格(secrets、GitHub App 设置、bot 设置细节),改为链接指向 docs

七、待用户确认的决策点

  1. 范围:只做 A?还是 A+B(重构结构)?或 A+B+C(含 README 瘦身)?
  2. configuration.md:按上述拆分成多个页面(改动大、导航清晰),还是保留单页只做内容修正?
  3. gitlab 校验值:代码放行但无实现——删掉(与文档对齐)还是保留(为未来扩展)?
  4. 新页面:Bot 命令页、i18n/消息格式页、FAQ 页是否都需要?