qq-codex-bridge 0.1.2 → 0.1.4

package/README.md

@@ -7,444 +7,389 @@
 
 ![qq-codex-bridge README Hero](./output/readme-hero-nanobanana-productized-v1.png)
 
-一个把 **QQ 官方机器人会话** 桥接到 **Codex Desktop** 的开源实验项目。
+## 把 Codex / ChatGPT Desktop 变成你的 QQ / 微信私人 AI 助理
 
-它的核心目标很直接：
+**qq-codex-bridge** 是一个开源本地桥接工具，让你通过 **QQ** 或**微信**直接对话 **Codex Desktop** 或 **ChatGPT Desktop**——支持图片理解、语音提问、文件分析、AI 生图回传，私聊群聊都能用，同时支持多 Bot、多账号接入。
 
-- 在 QQ 私聊 / 群聊里接收用户消息
-- 按会话把消息映射到 Codex Desktop 线程
-- 用 CDP 驱动 Codex Desktop 发送消息、切线程、读取回复
-- 把 Codex 的文本、图片、文件、语音转写结果继续回送到 QQ
+---
 
-项目当前已经能跑真实链路，但仍然属于 **实验性可用** 阶段，更适合开发者联调、研究和二次改造，而不是直接当成稳定生产系统。
+## 你可以这样用
 
-## 文档导航
+### 发张图片，让 AI 帮你看
 
-- [快速开始](#快速开始)
-- [FAQ 与故障排查](./docs/faq.md)
-- [架构说明](./docs/architecture.md)
-- [在线 Wiki（GitNexus 自动生成）](https://gistcdn.githack.com/983033995/3206d28d1bd71323166bc511b8681620/raw/index.html#overview)
-- [测试说明](./docs/testing.md)
-- [变更记录](./CHANGELOG.md)
-- [贡献指南](./CONTRIBUTING.md)
-- [安全策略](./SECURITY.md)
+遇到截图、照片、产品图？直接发给机器人，AI 会结合图片内容给出分析。手机端 QQ、桌面端 QQ 均可使用。
 
----
+![图片理解](./output/截屏%202026-04-10%2021.33.09.png)
 
-## 项目特性
+### 语音提问，张口就来
 
-### 核心链路
+发一条语音，桥接会自动转写后发给 AI。双手不便打字时，直接说话就能问。
 
-- QQ 官方 Bot WebSocket gateway 入站
-- QQ 私聊 / 群聊会话隔离
-- Codex Desktop 启动检查与 CDP 连接
-- QQ 消息映射到 Codex 线程
-- Codex 回复增量采集并多次回传到 QQ
-- SQLite 持久化会话、入站记录、出站任务
+### Markdown 和代码，结构完整回传
 
-### 媒体与 STT
-
-- QQ 附件下载与上下文注入
-  - 图片
-  - 语音
-  - 视频
-  - 文件
-- 语音转文字
-  - QQ 自带 `asr_refer_text` 回退
-  - `openai-compatible`
-  - `volcengine-flash`
-  - 本地离线 `whisper.cpp`
-- QQ 媒体回传
-  - 图片
-  - 音频
-  - 视频
-  - 文件
-
-### Codex 回复处理
-
-- 富文本链接提取
-- 有序列表编号保留
-- 代码块序列化为 fenced markdown
-- 表格结构保留
-- 长耗时任务回复采集窗口延长
-- 同一轮回复中的媒体结果继续跟进，不再只截前几段文本
+AI 输出的列表、代码块、表格会尽量保留格式后再发到 QQ。写代码、看文档都清晰。
 
-### 线程管理
+![Markdown 渲染效果](./output/截屏%202026-04-10%2021.31.46.png)
 
-仅私聊可用：
+### AI 生成了图片？直接发回 QQ
 
-| 用途 | 完整命令 | 简写 |
-| --- | --- | --- |
-| 查看最近活跃线程 | `/threads` | `/t` |
-| 查看当前绑定线程 | `/thread current` | `/tc` |
-| 切换到指定线程 | `/thread use <序号>` | `/tu <序号>` |
-| 新建线程 | `/thread new <标题>` | `/tn <标题>` |
-| 基于最近对话 fork 线程 | `/thread fork <标题>` | `/tf <标题>` |
-| 查看帮助 | `/help` | - |
-
----
+Codex / ChatGPT 调用图片生成工具后，成品会自动回传到 QQ 对话里。创作结果一目了然。
 
-## 适用场景
+![AI 生图回传](./output/截屏%202026-04-10%2022.00.25.png)
 
-- 想直接在 QQ 里把 Codex 当成一个“会话型桌面代理”来用
-- 需要把图片、语音、文件上下文桥接给 Codex
-- 想研究 Codex Desktop 的 CDP 自动化与回复采集
-- 想复用 QQ 官方 Bot 能力，但不依赖 OpenClaw 宿主
+### 私聊线程管理，复杂任务不丢上下文
 
----
+在 QQ 私聊中直接查看、切换、新建 Codex / ChatGPT 对话线程。大型项目可以分线程讨论，每个线程独立记忆，互不干扰。
 
-## 项目效果
+![线程管理](./output/截屏%202026-04-10%2021.47.08.png)
 
-### Markdown 与代码回复
+---
 
-Codex 的列表、代码块、表格会尽量保留结构后再发给 QQ。
+## 工作原理
 
-![Markdown 渲染效果](./output/截屏%202026-04-10%2021.31.46.png)
+```text
+QQ Bot / 微信
+      │
+      ▼
+BridgeOrchestrator（本地 Node.js 进程）
+      │
+      ├── SessionStore / TranscriptStore（SQLite）
+      ├── Channel Sender（QQ / 微信）
+      │
+      ├── CodexDesktopDriver ──► Chrome DevTools Protocol ──► Codex Desktop
+      └── ChatgptDesktopDriver ──► macOS Accessibility API ──► ChatGPT Desktop
+```
 
-### 图片理解
+桥接运行在本地，通过 CDP 驱动 Codex Desktop，通过 macOS Accessibility API 驱动 ChatGPT Desktop，完成消息收发和上下文注入。每个私聊会话可以独立绑定对话线程，并通过 `/source` 命令随时切换 AI 源。
 
-发送图片给机器人，Codex 可以结合图片内容继续回答。
+---
 
-![图片理解](./output/截屏%202026-04-10%2021.33.09.png)
+## 快速开始
 
-### 线程管理
+### 第 0 步：创建 QQ 机器人，获取 AppID 和 AppSecret
 
-在 QQ 私聊中直接查看最近活跃线程，并快速切换。
+1. 打开 [QQ 开放平台](https://q.qq.com/qqbot/openclaw/index.html)，登录后点击「**创建机器人**」
+2. 填写机器人名称和简介，完成创建
+3. 进入机器人详情页，复制 **AppID** 和 **AppSecret**（点击"查看"可显示 AppSecret）
 
-![线程管理](./output/截屏%202026-04-10%2021.47.08.png)
+![QQ 开放平台机器人创建页面](https://minimax-algeng-chat-tts.oss-cn-wulanchabu.aliyuncs.com/ccv2%2F2026-04-13%2FMiniMax-M2.7%2F2022349168671990452%2F7e608ce17a900fa601a014dc957ef1314be87cff5a110e27615a5393bf2912d6..png?Expires=1776145198&OSSAccessKeyId=LTAI5tGLnRTkBjLuYPjNcKQ8&Signature=eM71QgFWMmELUyeGG2fLn3Onugk%3D)
 
-### AI 生图回传
+> 同一 AppID + AppSecret 可以同时在多个群聊和私聊中使用，无需重复创建。
 
-Codex 调用图片生成工具后，桥接会把成品图片继续回传到 QQ。
+### 第 1 步：生成配置文件
 
-![AI 生图回传](./output/截屏%202026-04-10%2022.00.25.png)
+推荐直接用 `npx`：
 
----
+```bash
+npx qq-codex-bridge init
+```
 
-## 技术架构
+或全局安装后使用：
 
-```text
-QQ Official Bot Gateway
-        │
-        ▼
-QqGatewayClient / QqGateway
-        │
-        ▼
-BridgeOrchestrator
-        │
-        ├── SessionStore / TranscriptStore (SQLite)
-        ├── QqSender / QqApiClient
-        └── CodexDesktopDriver
-                │
-                └── Chrome DevTools Protocol
-                        │
-                        └── Codex Desktop
+```bash
+npm i -g qq-codex-bridge
+qq-codex-bridge init
 ```
 
-更贴近实际运行时的链路是：
+这会将内置配置模板写入当前目录的 `.env`。
 
-```text
-QQ 消息
-  -> 归一化 / 附件下载 / STT
-  -> 构造成 Codex 入站上下文
-  -> 注入 Codex Desktop
-  -> 轮询最新 assistant unit
-  -> 增量 draft
-  -> QQ 文本 / 媒体发送
-  -> SQLite 记录入站与出站任务
-```
+### 第 2 步：填写 `.env`
 
----
+将上一步复制的 **AppID** 和 **AppSecret** 填入 `.env`：
 
-## 和官方项目的关系
+```env
+QQBOT_APP_ID=你的AppID
+QQBOT_CLIENT_SECRET=你的ClientSecret
+```
 
-这个项目参考了：
+`.env` 中其他常用变量：
 
-- [tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot)
-- [openclaw/openclaw](https://github.com/openclaw/openclaw)
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `CODEX_REMOTE_DEBUGGING_PORT` | Codex Desktop 远程调试端口 | `9229` |
+| `QQBOT_STT_*` | 语音转文字配置（可选，不填则用 QQ 内置 ASR） | — |
+| `QQBOT_MARKDOWN_SUPPORT` | 是否启用 QQ markdown 文本发送 | `false` |
 
-主要借鉴了这些思路：
+### 第 3 步：启动桥接
 
-- QQ gateway WebSocket 入站
-- 出站消息路由与媒体发送
-- 语音 / 文件处理方式
-- Markdown 分块发送思路
-- “增量回复 -> 分段回传”的设计方向
+```bash
+npx qq-codex-bridge
+```
 
-但两者仍然不同：
+正常启动后会看到类似日志：
 
-| 项目 | 运行位置 | 宿主 |
-| --- | --- | --- |
-| `openclaw-qqbot` | OpenClaw 插件 | OpenClaw |
-| `qq-codex-bridge` | 本地 Node.js 进程 | Codex Desktop |
+```text
+[qq-codex-bridge] codex desktop ready { launched: true|false, remoteDebuggingPort: 9229 }
+[qq-codex-bridge] ready { transport: 'qq-gateway-websocket', accountKeys: ['qqbot:default'], conversationProvider: 'codex-desktop' }
+```
 
-所以这个项目不是 OpenClaw 插件移植版，而是 **面向 Codex Desktop 的独立桥接实现**。
+> 桥接会先检查 Codex Desktop 是否已运行；若未运行，会尽量自动拉起后再继续。
 
----
+### 第 4 步：在 QQ 中联调
 
-## 项目结构
+建议按这个顺序测试：
 
-```text
-apps/bridge-daemon/
-  src/
-    main.ts
-    bootstrap.ts
-    config.ts
-    thread-command-handler.ts
-    debug-codex-workers.ts
-
-packages/adapters/qq/
-  src/
-    qq-gateway-client.ts
-    qq-gateway.ts
-    qq-api-client.ts
-    qq-sender.ts
-    qq-media-downloader.ts
-    qq-media-parser.ts
-    qq-stt.ts
-
-packages/adapters/codex-desktop/
-  src/
-    cdp-session.ts
-    codex-desktop-driver.ts
-    composer-heuristics.ts
-    reply-parser.ts
-
-packages/orchestrator/
-  src/
-    bridge-orchestrator.ts
-    media-context.ts
-    qq-outbound-draft.ts
-    qq-outbound-format.ts
-    qqbot-skill-context.ts
-
-packages/store/
-  src/
-    sqlite.ts
-    session-repo.ts
-    message-repo.ts
-```
+1. **普通文本** — 先确认消息收发正常
+2. **一条会让 AI 分阶段回答的问题** — 验证增量回复采集
+3. **一条语音** — 验证 STT 转写链路
+4. **一张图片** — 验证图片上下文注入
+5. **`/t` 与 `/tu 2`** — 验证线程管理命令
 
 ---
 
-## 环境要求
+## 微信通道
 
-- macOS
-- Node.js 20+
-- 已安装 Codex Desktop
-- Codex Desktop 可通过远程调试端口暴露 page target
-- QQ 官方机器人 `AppID` 和 `ClientSecret`
+仓库内置了一套**真实微信文本网关**，对接微信 long-poll 接口，把消息转发给 bridge，再把回复发回微信。
 
----
+### 最小配置
 
-## 快速开始
+在 `.env` 中补充：
 
-### 1. 生成当前目录配置
+```env
+WEIXIN_ENABLED=true
+WEIXIN_ACCOUNT_ID=default
+WEIXIN_WEBHOOK_PATH=/webhooks/weixin
+WEIXIN_EGRESS_BASE_URL=http://127.0.0.1:3200
+WEIXIN_EGRESS_TOKEN=your-token
+```
 
-推荐直接用 `npx`：
+### 首次扫码登录
 
 ```bash
-npx qq-codex-bridge init
+pnpm weixin:login
+# 或已安装发布包：
+qq-codex-weixin-gateway --weixin-login
 ```
 
-如果你更喜欢先全局安装：
+### 启动网关
 
 ```bash
-npm i -g qq-codex-bridge
-qq-codex-bridge init
-```
+# 源码开发模式（同时启动 bridge + 微信网关）：
+pnpm dev
 
-这一步会把包内置的模板写成当前目录下的 `.env`。
+# 或单独启动微信网关：
+pnpm start:weixin-gateway
+# 已安装发布包：
+qq-codex-weixin-gateway
+```
 
-### 2. 填写 `.env`
+完整说明见：[微信文本通道接入文档](./docs/weixin-text-gateway.md)
 
-最少需要配置这两个变量：
+---
 
-- `QQBOT_APP_ID`
-- `QQBOT_CLIENT_SECRET`
+## 多 Bot / 多账号接入
 
-### 3. 启动桥接
+### 多 QQ Bot
 
-临时运行：
+**方式 A：JSON 数组（推荐）**
 
-```bash
-npx qq-codex-bridge
+```env
+QQBOTS_JSON=[{"accountId":"main","appId":"AppID1","clientSecret":"Secret1","markdownSupport":false},{"accountId":"shop","appId":"AppID2","clientSecret":"Secret2","markdownSupport":false}]
 ```
 
-如果已经全局安装：
+**方式 B：ID 列表 + 分账号变量**
 
-```bash
-qq-codex-bridge
+```env
+QQBOT_ACCOUNT_IDS=main,shop
+QQBOT_MAIN_APP_ID=AppID1
+QQBOT_MAIN_CLIENT_SECRET=Secret1
+QQBOT_SHOP_APP_ID=AppID2
+QQBOT_SHOP_CLIENT_SECRET=Secret2
 ```
 
-默认端口仍然是：
+### 多微信账号
 
-- `CODEX_REMOTE_DEBUGGING_PORT=9229`
+每个微信账号需要一个独立的网关进程（监听不同端口）：
 
-正式 CLI 会先检查 Codex Desktop 的 CDP 端口；如果尚未启动，会尽量自动拉起 Codex Desktop 后再继续启动桥接。
+**方式 A：JSON 数组**
 
-正常启动日志类似：
+```env
+WEIXIN_ACCOUNTS_JSON=[{"accountId":"main","webhookPath":"/webhooks/weixin/main","egressBaseUrl":"http://127.0.0.1:3201","egressToken":"token-main"},{"accountId":"shop","webhookPath":"/webhooks/weixin/shop","egressBaseUrl":"http://127.0.0.1:3202","egressToken":"token-shop"}]
+```
 
-```text
-[qq-codex-bridge] codex desktop ready { launched: true|false, remoteDebuggingPort: 9229 }
-[qq-codex-bridge] ready { transport: 'qq-gateway-websocket', accountKey: 'qqbot:default' }
+**方式 B：ID 列表 + 分账号变量**
+
+```env
+WEIXIN_ACCOUNT_IDS=main,shop
+WEIXIN_MAIN_WEBHOOK_PATH=/webhooks/weixin/main
+WEIXIN_MAIN_EGRESS_BASE_URL=http://127.0.0.1:3201
+WEIXIN_MAIN_EGRESS_TOKEN=token-main
+WEIXIN_SHOP_WEBHOOK_PATH=/webhooks/weixin/shop
+WEIXIN_SHOP_EGRESS_BASE_URL=http://127.0.0.1:3202
+WEIXIN_SHOP_EGRESS_TOKEN=token-shop
 ```
 
-### 4. 在 QQ 中联调
+> 单 bot 单账号时保持旧配置（`QQBOT_APP_ID` + `QQBOT_CLIENT_SECRET`）即可，自动作为 `accountId=default` 处理，无需改动。
 
-建议先按这个顺序测试：
+---
 
-1. 普通文本
-2. 一条会让 Codex 分阶段回答的问题
-3. 一条语音
-4. 一张图片
-5. `/t` 与 `/tu 2`
+## 对话源切换（Codex / ChatGPT）
 
-### 5. 说明
+bridge 同时支持 **Codex Desktop** 和 **ChatGPT Desktop** 作为 AI 对话后端。每个私聊会话可以独立切换：
 
-- 这是“**无需源码启动**”，不是“**无依赖运行**”
-- 你仍然需要本机已经安装 **Codex Desktop**
-- 当前推荐平台仍然是 **macOS**
+```text
+/source          查看当前对话源
+/source codex    切换到 Codex Desktop
+/source chatgpt  切换到 ChatGPT Desktop
+```
+
+切换后，`/t`、`/tu`、`/tn` 等线程命令会自动路由到对应的 Desktop 应用。
 
-### 6. 开发者源码启动
+---
 
-如果你是要参与开发、调试源码或跑测试，再走下面这条路径：
+## 开发者源码启动
 
 ```bash
 git clone https://github.com/983033995/qq-codex-bridge.git
 cd qq-codex-bridge
 pnpm install
 cp .env.example .env
+# 填写 .env 中的 QQBOT_APP_ID 和 QQBOT_CLIENT_SECRET
 pnpm dev
 ```
 
 ---
 
-## STT 配置
-
-项目支持三层语音转写策略。
+## 项目特性
 
-### 1. 零配置模式
+### 核心能力
 
-不配置任何 `QQBOT_STT_*` 时：
+- QQ 官方 Bot WebSocket gateway 入站，支持多 bot 并行
+- 微信文本 long-poll 入站 / HTTP 文本出站，支持多账号
+- QQ 私聊 / 群聊会话隔离
+- 多通道会话隔离（QQ / 微信）
+- 双 AI 源：Codex Desktop（CDP）+ ChatGPT Desktop（macOS AX）
+- 每个私聊会话独立绑定线程，可随时切换 AI 源
+- SQLite 持久化会话、入站记录、出站任务
 
-- 优先使用 QQ 事件里的 `asr_refer_text`
-- 如果 QQ 没返回 ASR，再回退到附件占位
+### 媒体与语音
 
-这是最适合开源项目默认体验的模式。
+- QQ 附件下载与上下文注入（图片、语音、视频、文件）
+- 语音转文字：支持 QQ 内置 ASR / OpenAI 兼容 / 火山引擎 / 本地 whisper.cpp
+- QQ 媒体回传：图片、音频、视频、文件
+- ChatGPT Desktop 图片生成结果自动回传
 
-### 2. 云端 STT
+### 回复处理
 
-支持：
+- 富文本链接提取、有序列表编号保留
+- 代码块序列化为 fenced markdown、表格结构保留
+- 长耗时任务回复采集窗口延长
+- 同一轮回复中的媒体结果持续跟进
 
-- `openai-compatible`
-- `volcengine-flash`
+### 私聊命令（完整列表）
 
-适合需要更高转写稳定性的人。
+所有命令仅在**私聊**中有效；`/` 开头的命令由 bridge 拦截处理，不会直接发给 AI。
 
-### 3. 本地离线 STT
+**Codex Desktop 源下可用：**
 
-支持：
+| 用途 | 完整命令 | 简写 |
+| --- | --- | --- |
+| 查看最近活跃线程 | `/threads` | `/t` |
+| 查看当前绑定线程 | `/thread current` | `/tc` |
+| 切换到指定线程 | `/thread use <序号>` | `/tu <序号>` |
+| 新建线程 | `/thread new <标题>` | `/tn <标题>` |
+| 基于最近对话 fork 线程 | `/thread fork <标题>` | `/tf <标题>` |
+| 查看当前模型 | `/model` | `/m` |
+| 切换模型 | `/model use <名称>` | `/mu <名称>` |
+| 查看额度信息 | `/quota` | `/q` |
+| 查看当前运行状态 | `/status` | `/st` |
 
-- `local-whisper-cpp`
+**ChatGPT Desktop 源下可用：**
 
-适合重视隐私、不想依赖云端 API 的人。
+| 用途 | 完整命令 | 简写 |
+| --- | --- | --- |
+| 查看最近对话列表 | `/threads` | `/t` |
+| 查看当前绑定对话 | `/thread current` | `/tc` |
+| 切换到指定对话 | `/thread use <序号>` | `/tu <序号>` |
+| 新建对话 | `/thread new <标题>` | `/tn <标题>` |
 
-### STT 日志
+**两种源通用：**
 
-当前会输出这些 STT 日志：
+| 用途 | 命令 |
+| --- | --- |
+| 查看当前对话源 | `/source` |
+| 切换到 Codex Desktop | `/source codex` |
+| 切换到 ChatGPT Desktop | `/source chatgpt` |
+| 查看所有已接入账号 | `/accounts` |
+| 查看帮助 | `/help` 或 `/h` |
 
-- `qq stt started`
-- `qq stt completed`
-- `qq stt produced no transcript`
-- `qq stt fallback used`
-- `qq stt failed`
+---
 
-日志中会带：
+## 当前实现上的保护逻辑
 
-- `provider`
-- `file`
-- `extension`
-- `durationMs`
-- `hasAsrReferText`
-- `transcriptPreview`
+- **重复 QQ 入站抑制** — 短时间内同一会话、同一正文、同一媒体指纹的重复消息会被拦下
+- **长耗时任务回复采集窗口延长** — 图片生成、长搜索不再因默认超时被提前截断
+- **单条 draft 发送失败不再截断整轮回复** — 某一条 QQ 发送失败时，后续 draft 仍会继续尝试
+- **可恢复错误不会打断桥接** — `reply_timeout` 等可恢复错误不再直接把会话打成 `needs_rebind`
 
 ---
 
-## 当前实现上的一些保护逻辑
-
-这几个点是项目和“最小 demo”相比比较重要的部分：
+## 已知限制
 
-- **重复 QQ 入站抑制**  
-  短时间内同一会话、同一正文、同一媒体指纹的重复消息会被拦下，避免同一句话多次注入 Codex。
+- Codex Desktop 驱动依赖当前版本的 DOM 结构和 CDP 可见性，桌面端改版后可能需要跟着适配
+- ChatGPT Desktop 驱动依赖 macOS Accessibility API，macOS 系统权限变更可能影响使用
+- 对 AI 回复的增量采集是**基于页面快照的伪流式**，不是官方内部事件流
+- QQ 客户端的消息样式、Markdown 支持、媒体卡片展示不完全可控
+- 微信当前只开放了**文本通道**，还没有内置图片、语音、文件与真实提供方签名适配
+- 线程管理命令目前只在 **QQ 私聊** 中开放
 
-- **长耗时任务回复采集窗口延长**  
-  图片生成、长搜索、长工具执行不再因为默认 30 秒窗口被提前截断。
+---
 
-- **单条 draft 发送失败不再截断整轮回复**  
-  某一条 QQ 发送失败时，后续 draft 仍会继续尝试发送。
+## 环境要求
 
-- **可恢复错误不会把整个桥接打成不可用**  
-  比如 `reply_timeout` 这类错误会被当成可恢复错误记录，不再直接把会话打成 `needs_rebind`。
+- macOS
+- Node.js 20+
+- 已安装 Codex Desktop（使用 Codex 源时）
+- 已安装 ChatGPT Desktop（使用 ChatGPT 源时）
+- QQ 官方机器人 `AppID` 和 `ClientSecret`
 
 ---
 
-## 已知限制
+## 安全提醒
 
-- 核心能力依赖 Codex Desktop 当前版本的 DOM 结构和 CDP 可见性，桌面端改版后可能需要跟着适配。
-- 对 Codex 回复的增量采集仍然是 **基于页面快照的伪流式**，不是官方内部事件流。
-- QQ 客户端自己的消息样式、Markdown 支持、媒体卡片展示不完全可控。
-- 线程管理命令目前只在 **QQ 私聊** 中开放。
-- 某些极端场景下，如果 Codex Desktop 页面结构变化很大，线程定位与回复提取可能失效。
+- `.env` 里包含 QQ Bot、STT 等敏感密钥，**不要提交到仓库**（`.gitignore` 已默认排除 `.env`）
+- 如果你把项目分享给别人，请务必轮换已经暴露过的密钥
+- 本项目会处理用户消息、附件、语音与本地文件路径，联调时请注意隐私边界
 
 ---
 
 ## 调试建议
 
-### 查看类型检查
-
 ```bash
+# 类型检查
 pnpm run check
-```
-
-### 运行测试
 
-```bash
+# 运行测试
 pnpm test
-```
 
-### 调试 Codex page / worker
-
-```bash
+# 调试 Codex page / worker
 pnpm run debug:codex-workers -- --duration-ms 12000
 ```
 
 ---
 
-## 安全提醒
+## 文档导航
 
-- `.env` 里会包含 QQ Bot、STT 等敏感密钥，不要提交到仓库
-- 如果你把项目分享给别人，请务必轮换已经暴露过的密钥
-- 本项目会处理用户消息、附件、语音与本地文件路径，联调时请注意隐私边界
+- [FAQ 与故障排查](./docs/faq.md)
+- [架构说明](./docs/architecture.md)
+- [测试说明](./docs/testing.md)
+- [变更记录](./CHANGELOG.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [安全策略](./SECURITY.md)
+- [在线 Wiki（GitNexus 自动生成）](https://gistcdn.githack.com/983033995/e5715ad0d61605f039ca4e6055094083/raw/index.html#overview)
 
 ---
 
 ## 贡献
 
-欢迎 issue、讨论和 PR。
-
-在提交改动前，建议至少执行：
+欢迎 issue、讨论和 PR。在提交改动前，建议至少执行：
 
 ```bash
 pnpm run check
 pnpm test
 ```
 
-更多约定请看：
-
-- [CONTRIBUTING.md](./CONTRIBUTING.md)
-- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
-- [SECURITY.md](./SECURITY.md)
+更多约定请看 [CONTRIBUTING.md](./CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。
 
 ---
 

package/bin/chatgpt-desktop.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/apps/chatgpt-desktop-cli/src/cli.js";