@foxden-app/foxclaw 0.5.31 → 0.5.33

package/docs/zh/telegram-rich-messages.md

@@ -0,0 +1,125 @@
+# Telegram Rich Message 适配专项检查
+
+检查日期：2026-06-16。依据：Telegram Bot API Rich Messages 文档，尤其是 `RichMessage`、`sendRichMessage`、`sendRichMessageDraft` 与 Rich Message Formatting Options。
+
+官方入口：
+
+- https://core.telegram.org/bots/api#rich-message-formatting-options
+- https://core.telegram.org/bots/api#sendrichmessage
+- https://core.telegram.org/bots/api#sendrichmessagedraft
+
+## 结论
+
+FoxClaw 有明确收益，并已开始把 RichMessage 用在适合看效果、可安全回退的 Telegram 功能面。
+
+现在的策略是：Telegram 优先尝试 `sendRichMessage`，失败时回退到既有 Telegram HTML；微信继续使用 HTML/plain 回退。Bot API 10.1 的 Rich Message 先用于可观察的诊断和结构化长文本，再逐步扩展到状态、auth/quota 和 AI draft streaming。
+
+本次已先落地低风险增强：
+
+- 新增 `src/telegram/html.ts`，统一 Telegram HTML 转义和常用标签生成。
+- 新增 `src/telegram/rich.ts`，并在 `TelegramGateway` / `TelegramMessagingPort` / `BridgeMessagingRouter` 接入 `sendRichMessage` / rich HTML 发送链路。
+- 新增 `/rich` 诊断命令，用来在真实 Telegram 客户端查看 heading、table、details、pre/code、list 的 RichMessage 效果。
+- `/diff` 改为优先发送 RichMessage：标题用 heading，diff 内容放入 details + pre/code；rich 发送失败时回退到 HTML 加粗标题和可展开引用块。
+- 现有 CLI 观察消息和归档工具批次状态复用同一套 HTML helper。
+
+## 官方能力摘录
+
+Bot API 10.1 新增 Rich Messages：
+
+- `RichText*`：bold、italic、underline、strikethrough、spoiler、code、marked、math、url、email、phone、mention、hashtag、bot command、anchor/reference 等。
+- `RichBlock*`：paragraph、heading、pre、footer、divider、math block、anchor、list、blockquote、pullquote、collage、slideshow、table、details、map、photo/video/audio/animation/voice、thinking。
+- `sendRichMessage`：发送完整 rich message。
+- `sendRichMessageDraft`：在私聊里流式发送临时 rich draft；draft 是短暂预览，最终仍要用 `sendRichMessage` 发送完整消息。
+- `editMessageText` 新增 `rich_message` 参数，可编辑 rich message。
+
+Rich Message HTML 还支持 `<details>`、`<table>`、`<pre><code class="language-...">`、`<ul>/<ol>`、`<hr/>`、`<tg-math-block>`、`<tg-thinking>` 等标签。`RichBlockThinking` 只能用于 `sendRichMessageDraft`。
+
+## FoxClaw 现状
+
+当前 Telegram 发送层：
+
+- `src/telegram/gateway.ts`：`sendMessage`、`sendHtmlMessage`、`sendRichMessage`、`editMessage`、`editHtmlMessage`、`editRichMessage` 已接入；HTML 普通消息使用 `parse_mode=HTML`，rich 消息使用 `rich_message.html`。
+- `src/channels/telegram/telegram_messaging_port.ts`：对 controller 暴露 plain/html/rich-html send/edit 和 `sendDraft`。
+- `src/telegram/rendering.ts`：默认 `segmented_stream`；`draft_stream` 仍是旧 `sendMessageDraft` 文本 draft。
+- `src/controller/controller.ts`：状态卡、审批、工具批次、diff、auth、MCP、插件、文件等功能面都在这里汇总发送。
+- `src/controller/presentation.ts`：`/threads`、`/setup`、模型/权限面板已经使用 Telegram HTML。
+
+已经使用的格式能力：
+
+- `/threads`、`/setup` 等面板：加粗、code、HTML escape。
+- CLI 观察消息：`<pre>`。
+- 归档工具批次状态：`<blockquote expandable>`。
+- 本次增强后的 `/diff`：加粗标题和可展开引用块。
+
+已经接入：
+
+- `sendRichMessage`：Telegram rich HTML 发送链路。
+- `/rich`：RichMessage demo。
+- `/diff`：RichMessage details + diff pre/code，失败回退 HTML。
+
+尚未接入：
+
+- Rich table/status 面板、auth/quota 表格、MCP resource details、rich draft streaming。
+- `sendRichMessageDraft` 的 thinking block 和最终 rich message 持久化。
+
+## 功能面盘点
+
+| 功能面 | 现状 | 可用 rich 能力 | 建议 |
+| --- | --- | --- | --- |
+| 活动 turn 状态卡 | 普通短文本，频繁编辑 | heading、list、thinking draft | 保持普通状态卡稳定；私聊 draft streaming 后续用 `RichBlockThinking` |
+| Codex streaming 回复 | 分段纯文本为主 | rich draft、paragraph、pre、details | 先不默认切；需要 feature flag 和失败回退 |
+| 归档工具批次 | 已用 expandable blockquote | details、pre、list | 短期维持 HTML；后续 rich details 展开命令、文件、搜索结果 |
+| `/diff` | 已优先 RichMessage，失败回退 HTML | pre language、details | 已落地 |
+| 审批请求 | 多行纯文本 + inline keyboard | code、pre、spoiler、details | 命令、路径、patch 适合 code/pre/details；敏感参数可 spoiler |
+| `/status` / runtime 摘要 | 纯文本列表 | table、heading、footer | 多 bot、多 auth、多 quota 适合 rich table |
+| `/auth` / `/quota` | 紧凑纯文本 + 按钮 | table、marked、spoiler | quota 窗口适合 table；异常候选用 marked；隐藏敏感候选信息需谨慎 |
+| `/threads` / `/setup` | 已用 HTML 面板 | heading、list、anchor | 现状够用；rich message 价值中等 |
+| MCP resource / plugin skill | 纯文本长内容 | details、pre、anchor/reference | schema、resource 文本可放 details/pre，引用可用 anchor/reference |
+| 说明类消息 / help | 纯文本 | heading、list、code | 可转 rich list，但优先级低 |
+| 媒体附件反馈 | 纯文本摘要 | collage/slideshow/photo/video caption | 只在需要回显媒体结果时考虑，当前不是主路径 |
+
+## 落地路线
+
+### Phase 1：HTML 兼容增强
+
+目标：不改变 Bot API 主方法，先改善现有客户端体验。
+
+- 统一 Telegram HTML helper，禁止散落手写转义。
+- 长内容默认折叠：diff、工具日志、MCP resource、插件 skill 内容。
+- 命令、路径、模型、候选名使用 `<code>`。
+- 对可能包含 secret/token 的诊断内容使用 `<tg-spoiler>` 或直接不展示。
+
+已完成：HTML helper、`/diff` 折叠、现有 CLI/工具归档复用 helper。
+
+### Phase 2：Rich Message builder
+
+目标：让 rich message 作为可回退能力存在，而不是替换全部消息。
+
+已完成：
+
+- 新增 `src/telegram/rich.ts`，定义 `InputRichMessage` 的最小 HTML 输入。
+- `TelegramGateway` 增加 `sendRichMessage`、`editRichMessage`、`sendRichMessageDraft`。
+- `TelegramMessagingPort` 和 `BridgeMessagingRouter` 增加 rich HTML send/edit；微信 scope 自动用 fallback HTML。
+- `/rich` 和 `/diff` 先使用 rich 发送，失败回退到 HTML。
+
+下一步：
+
+- 把 `/status`、`/auth`、`/quota`、MCP resource 等结构消息迁移到 rich table/details。
+- 按真实客户端表现决定是否加入全局配置开关。
+
+### Phase 3：Rich draft streaming
+
+目标：私聊里的 AI 生成过程更自然。
+
+- 仅对 Telegram 私聊启用；群组、topic 默认继续走现有 segmented stream。
+- draft 中使用 `RichBlockThinking` 表示思考中，已生成文本用 paragraph/pre/details。
+- 生成完成后调用 `sendRichMessage` 发送完整消息，不能只依赖 ephemeral draft。
+- 保留旧 `sendMessageDraft` 和 plain segmented stream 回退。
+
+## 风险和注意点
+
+- Rich Messages 是 2026-06-11 Bot API 10.1 新能力，客户端兼容性需要通过 `/rich` 和 `/diff` 实测。
+- `sendRichMessageDraft` 只面向用户私聊；FoxClaw 的群组、topic、多 bot 场景必须保留旧路径。
+- Rich media block 需要 bot 具备对应发送权限，且媒体 URL/上传处理比文本复杂，暂不作为第一阶段目标。
+- 自动实体识别可能把路径、邮箱、URL、命令误识别；rich builder 应按消息类型决定是否设置 `skip_entity_detection`。
+- HTML/rich 格式必须集中 escape，不能让 Codex 输出或 shell 输出直接拼进标签。

package/docs/zh/troubleshooting.md

@@ -14,6 +14,13 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+如果 FoxClaw 是 macOS launchd 服务，再看：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 ## Doctor 检查失败
 
 | 现象 | 含义 | 处理方式 |
@@ -137,6 +144,13 @@ systemctl --user is-active foxclaw.service
 pgrep -af foxclaw
 ```
 
+macOS 上用：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+pgrep -af foxclaw
+```
+
 停掉多余进程或服务后，重启 FoxClaw：
 
 ```bash
@@ -201,12 +215,18 @@ tail -f ~/.foxclaw/logs/codex-app-server-bot<id>.log
 
 如果 Telegram 里看到 `ChatGPT backend 403 Forbidden`，或者 app-server 日志里出现 `Unable to load site`、`cf-ray`、`chatgpt.com/backend-api`，通常不是 `auth.json` 文件坏了，而是服务进程访问 ChatGPT 后端时没有走正确网络。
 
-常见原因是：你在 shell 里配置了代理，或者项目 `.env` 里有代理，但 systemd/launchd 服务实际读的是另一个 env 文件。先看服务用的是哪个 env：
+常见原因是：你在 shell 里配置了代理，或者项目 `.env` 里有代理，但 systemd/launchd 服务实际读的是另一个 env 文件。Linux 先看服务用的是哪个 env：
 
 ```bash
 systemctl --user cat foxclaw.service
 ```
 
+macOS 看 launchd plist 里的 `FOXCLAW_ENV`：
+
+```bash
+plutil -p ~/Library/LaunchAgents/app.foxden.foxclaw.plist | grep FOXCLAW_ENV -A1
+```
+
 `foxclaw init` 会检测当前 shell 里的代理环境变量，并询问是否保存到 FoxClaw `.env`。如果你跳过了这一步，`foxclaw doctor` 会在发现“shell 有代理，但 FoxClaw env 没有代理”时给出 `[WARN]`。
 
 确认 `Environment=FOXCLAW_ENV=...` 指向的文件里有你的代理配置，例如：
@@ -244,6 +264,8 @@ FoxClaw 会把 proxychains 写进主 service，并清理旧的 FoxClaw `ExecStar
 
 systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh` 或其它 shell 初始化脚本。无论你用 nvm、fnm、asdf、mise、Volta、Homebrew 还是系统 Node，原则都是：从 Node 24+ 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24+ 路径。
 
+macOS launchd 也是同样原则：plist 会记录执行 `foxclaw start` 时的 Node 绝对路径，不依赖登录 shell 初始化脚本。
+
 如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24+ 的 shell 重新安装。nvm 用户示例：
 
 ```bash
@@ -252,7 +274,15 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-状态输出里应该能看到 Node 24+ 的路径。`foxclaw doctor` 也会检查已安装服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
+macOS 用户示例：
+
+```bash
+nvm use 24
+foxclaw start
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+```
+
+状态输出里应该能看到 Node 24+ 的路径。`foxclaw doctor` 也会检查已安装 systemd/launchd 服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
 
 ## 重启后是否会自动运行
 

package/docs/zh/user-manual.md

@@ -145,7 +145,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-macOS 上 `foxclaw start` 会管理 launchd。前台排障时，先停后台服务，再运行：
+macOS 上 `foxclaw start` 会管理 launchd。查看 launchd 状态和启动日志：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
+前台排障时，先停后台服务，再运行：
 
 ```bash
 foxclaw stop
@@ -258,6 +265,10 @@ TG_ALLOWED_TOPIC_ID=42
 
 Telegram 会把 HTML 和按钮渲染出来。这里用等宽框模拟实际面板：
 
+Telegram Rich Message 能力的专项盘点和后续接入路线见 [Telegram Rich Message 适配专项检查](./telegram-rich-messages.md)。当前默认通道仍优先使用兼容性更稳的 Telegram HTML。
+
+可以发送 `/rich` 在当前 Telegram 客户端查看 RichMessage demo。`/diff` 也会优先用 RichMessage 展示 details 和 diff code block，失败时自动回退到 Telegram HTML。
+
 ```text
 会话偏好
 当前：gpt-5.5 · high · fast=off · default · Agent · Steer current turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.31",
+  "version": "0.5.33",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
@@ -48,6 +48,7 @@
     "install-systemd": "node dist/main.js install-systemd",
     "uninstall-systemd": "node dist/main.js uninstall-systemd",
     "install-launchd": "node dist/main.js install-launchd",
+    "uninstall-launchd": "node dist/main.js uninstall-launchd",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "node --test --import tsx $(find src -name '*.test.ts' -print)",

package/skills/foxclaw/SKILL.md

@@ -144,8 +144,8 @@ Use `--no-start` by default when preparing a second Mac before a unique bot toke
 
 After either bootstrap path:
 
-1. Run `node dist/main.js doctor` in the installed bridge repo.
-2. If launchd was installed, run `node dist/main.js status`.
+1. Run `node dist/main.js doctor` in the installed bridge repo.
+2. If launchd was installed, run `node dist/main.js status`, `launchctl print "gui/$(id -u)/app.foxden.foxclaw"`, and inspect `~/.foxclaw/logs/launchd.err.log` if either status check fails.
 3. Check `codex login status`. If authentication is missing, stop and tell the user exactly how to log in.
 4. If the bridge is expected to answer in a Telegram group, confirm:
    - `privacy mode` is disabled