mirror of
https://github.com/ReCloudStudio/WebHooker.git
synced 2026-09-22 16:11:29 +00:00
docs: sync documentation with current codebase
- Update event formatter count 23 -> 28 (add ping, workflow_job, status, deployment, check_suite) - Document Telegram support end-to-end (routes, /gh commands, richheader, secrets) - Fix route schema to use targets array and group fields (owners, emoji) - Correct KV/D1 storage layout (msg:*, i18n:*, D1 links/send_logs) - Note GITHUB_APP_ID/GITHUB_PRIVATE_KEY are unused; drop legacy DISCORD_CHANNEL_ID/PORT/CONFIG_PATH - Remove stale Docker deployment section - Update color table, branch filter compatibility, admin API endpoints - AGENTS.md: add Documentation section requiring doc updates after functional changes
This commit is contained in:
wyf9
parent
68cda9f178
commit
afe19795b1
25 changed files with 621 additions and 398 deletions
|
|
@ -14,23 +14,25 @@ npm run dev # 启动本地开发服务器
|
|||
|
||||
```text
|
||||
src/
|
||||
├── index.ts # CF Workers 入口 (fetch + scheduled)，scheduled = 命令同步
|
||||
├── types.ts # Env、Config、Route、Filter、WebhookEvent、NeutralMessage
|
||||
├── index.ts # CF Workers 入口 (fetch + scheduled)，scheduled = Discord 命令同步 + Telegram webhook 同步
|
||||
├── types.ts # Env、Config、Route、Filter、Group、WebhookEvent、NeutralMessage
|
||||
├── config.ts # 从 KV 加载路由（未设置时返回 []），从 env 构建 Config
|
||||
├── server.ts # Hono 应用: /health、/webhook、/discord/interactions，挂载 /auth、/admin + /
|
||||
├── server.ts # Hono 应用: /health、/webhook、/discord/interactions、/telegram/webhook，挂载 /auth、/admin + /
|
||||
├── core/
|
||||
│ └── dispatch.ts # 平台中立分发：匹配路由 → formatEvent → getDriver().send
|
||||
├── events/ # GitHub webhook 事件流水线
|
||||
│ └── dispatch.ts # 平台中立分发：匹配路由 → formatEvent → getDriver().send/edit
|
||||
├── events/ # GitHub webhook 事件流水线（旧 src/webhook.ts 为死代码）
|
||||
│ ├── verify.ts # HMAC 签名验证 (Web Crypto，时间安全)
|
||||
│ ├── parse.ts # parseEvent (headers + body → WebhookEvent)
|
||||
│ └── match.ts # matchRoute、eventOwners、extractBranch、关键词过滤
|
||||
├── formatters/ # 平台中立格式化器（产出 NeutralMessage）
|
||||
│ ├── index.ts # formatEvent：24 事件 switch → NeutralMessage + re-export
|
||||
│ ├── index.ts # formatEvent：28 事件 switch → NeutralMessage + re-export
|
||||
│ ├── colors.ts # GITHUB_COLORS + WORKFLOW_CONCLUSION_EMOJI
|
||||
│ ├── helpers.ts # emojiPrefix、T、buildMessage
|
||||
│ └── *.ts # push、pull-request、issues、comments、workflow、release、repo 等
|
||||
│ └── *.ts # push、pull-request、issues、comments、workflow、release、create、repo、
|
||||
│ # check、review、commit-comment、deployment、member、label、milestone、
|
||||
│ # discussion、repository、security、generic、ping
|
||||
├── drivers/ # 平台驱动（可插拔推送目标）
|
||||
│ ├── types.ts # PlatformDriver 接口 + SendResult
|
||||
│ ├── types.ts # PlatformDriver 接口 + SendResult（send + edit）
|
||||
│ ├── index.ts # getDriver() 注册表（discord + telegram）
|
||||
│ ├── discord/ # index.ts (驱动)、render.ts (NeutralMessage → embed)、
|
||||
│ │ # rest.ts、interactions.ts、commands.ts
|
||||
|
|
@ -38,21 +40,24 @@ src/
|
|||
│ # rest.ts (chat_id + message_thread_id)、updates.ts (webhook 验签)、
|
||||
│ # commands.ts (/gh login|logout|comment|merge|close + 引用消息解析)
|
||||
├── github/ # GitHub OAuth + 以用户身份操作
|
||||
│ ├── oauth.ts # OAuth URL、回调 Token 交换、getUserOctokit、操作
|
||||
│ ├── oauth.ts # OAuth URL、回调 Token 交换、getUserOctokit、评论/合并/关闭操作
|
||||
│ └── store.ts # KV Token CRUD + D1 discord-link/telegram-link 映射
|
||||
├── web/ # HTTP UI/API 路由
|
||||
│ ├── oauth-routes.ts # GET /auth/github、回调、DELETE /token/:userId (KV 状态)
|
||||
│ ├── oauth-routes.ts # GET /auth/github、回调（管理员会话 / Discord 绑定 / Telegram 绑定）、DELETE /token/:userId
|
||||
│ ├── action-routes.ts # POST /api/comment|merge|close|react (通过 KV 查找进行 Bearer Token 鉴权)
|
||||
│ ├── admin-routes.ts # /admin API：路由、分组、me、日志（会话 + 权限范围鉴权）
|
||||
│ ├── session.ts # 管理员会话 CRUD (KV session:{id})、Cookie 辅助函数
|
||||
│ ├── groups.ts # 分组加载、分组管理员权限范围
|
||||
│ ├── home-routes.ts # 落地页路由
|
||||
│ └── legal-routes.ts # 法律页面路由
|
||||
│ ├── legal-routes.ts # 法律页面路由
|
||||
│ └── richheader-routes.ts # GET /api/richheader（Telegram 头像卡片）
|
||||
└── lib/ # 共享基础设施
|
||||
├── i18n.ts # 消息语言覆盖 (en/zh)
|
||||
├── send-log.ts # 发送日志 (D1 send_logs)
|
||||
├── log.ts # JSON 控制台日志 (info/warn/error/fatal)
|
||||
└── locales/ # en.ts、zh.ts 翻译字典
|
||||
|
||||
src/__tests__/ # 单元测试 (bun test)
|
||||
```
|
||||
|
||||
## 脚本
|
||||
|
|
@ -93,16 +98,17 @@ curl http://localhost:8787/health
|
|||
## 添加新事件格式化器
|
||||
|
||||
1. 将事件类型添加到 `src/formatters/colors.ts` 中的 `GITHUB_COLORS`（如果需要新颜色）
|
||||
2. 将操作标签添加到 `ACTION_LABELS`（如果有新操作）
|
||||
2. 将操作标签添加到 `src/lib/locales/en.ts` 与 `src/lib/locales/zh.ts` 的翻译字典（如果有新操作）
|
||||
3. 在 `src/formatters/` 中创建 `formatEventType` 函数
|
||||
4. 将 case 添加到 `src/formatters/index.ts` 中的 `formatEvent` switch 语句
|
||||
5. 如果事件包含分支信息，更新 `src/events/match.ts` 中的 `extractBranch`
|
||||
6. 将事件添加到 `docs/events/supported.md` 文档中
|
||||
7. 在 GitHub App 设置中订阅该事件
|
||||
6. 将事件添加到 `docs/events/supported.md` 与 `docs/zh/events/supported.md` 文档中
|
||||
7. 将事件添加到 README（`README.md` 与 `README.zh.md`）的事件表与 GitHub App 事件订阅列表中
|
||||
8. 在 GitHub App 设置中订阅该事件
|
||||
|
||||
## 拉取请求指南
|
||||
|
||||
- 保持变更聚焦且原子化
|
||||
- 为所有函数返回值包含类型注解
|
||||
- 提交前运行 `npm run typecheck && npm run lint && npm run format:check`
|
||||
- 添加功能时更新文档
|
||||
- 添加功能时更新文档（见 `AGENTS.md` → Documentation 的清单）：README（`README.md` / `README.zh.md`）、VitePress 文档（`docs/` 与 `docs/zh/`）以及示例配置文件
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue