dsh-line-bot 0.7.2 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,69 @@
+# dsh-line-bot：給 DSH Agent 的除錯指南
+
+這份檔案是給「在這台電腦上除錯 LINE Bot」的 DSH Agent 看的。遇到使用者說「Bot 沒回」「叫他傳表情包沒傳」「圖片顯示不出來」時，照下面的順序做，不要先改程式。
+
+## 0. 先跑診斷
+
+```bash
+node bin/cli.mjs doctor --json      # 或 npx dsh-line-bot doctor --json
+```
+
+- 伺服器在跑時，doctor 會打本機 `http://127.0.0.1:8791/doctor`，檢查：伺服器、Cloudflare Tunnel、公開網址健康、LINE webhook、dsh-meme 圖庫、表情包設定、轉圖工具、模型、圖片可送達測試、最近錯誤。
+- 伺服器沒跑時會退成離線檢查（設定檔、憑證、dsh-meme、轉圖工具、日誌）。
+- `--fix` 會做安全修復：重啟 tunnel、重設 webhook、重新讀 bot 資訊；不會改設定、不會刪資料。
+
+也可以直接看：
+
+```bash
+curl -s http://127.0.0.1:8791/doctor | jq .
+curl -s http://127.0.0.1:8791/health
+```
+
+## 1. 症狀對照表
+
+| 症狀 | 先看哪個 check | 常見原因 | 安全修法 |
+| --- | --- | --- | --- |
+| 完全沒回覆 | `server`、`tunnel`、`webhook` | webhook 指到舊 tunnel；LINE「Use webhook」沒開；伺服器沒啟動 | `doctor --fix`；面板「套用 Webhook」；到 LINE console 開 Use webhook |
+| 有回文字但沒圖片 | `dsh-meme`、`meme-config`、`public-url`、`media`、`converters` | 沒裝 dsh-meme；`stickers.enabled=false`；公開網址還沒就緒；GIF/webp 沒有轉圖工具 | 面板「表情包」開啟並看圖庫；`doctor --fix`；安裝 ffmpeg |
+| 回覆出現 `[[meme:…]]`、`<meme#18>` 文字 | 版本 | 舊版不認得標記格式 | 升級到 0.6.1+（目前 0.8.x） |
+| 貼圖看不懂 | `model` | 目前模型不吃圖（`inputModalities` 沒有 image） | 面板「模型與接口來源」換成有 `text+image` 的模型 |
+| 群組不回 | 面板「群組」 | 沒被 @／引用、擲骰沒中、群組功能關閉 | 看面板回覆機率與開關 |
+| 主動訊息沒出現 | 面板「主動傳訊」 | 機率、每日／每月上限、靜音時段、冷卻、沒有 session 的使用者 | 看 `status.nudge` 與日誌 |
+| 餘額提醒沒出現 | `balance` | provider 不是 `deepseek-account`、餘額高於門檻、冷卻中、靜音 | 面板「DeepSeek 餘額」看 `applicable`、`lastAskAt` |
+| Windows 安裝失敗 | CLI | 找不到 DSH 內建 pnpm；舊版 spawn `.cmd` 失敗 | 用面板安裝，或升級 CLI；必要時 `npm i -g pnpm` |
+| npm `ETARGET` | — | registry／CDN 還沒傳播 | 等 1–5 分鐘再試 |
+
+## 2. 圖片沒送出的排查順序
+
+1. `dsh-meme` 是否可用、`count > 0`：`curl -s localhost:8791/doctor`。
+2. 面板「表情包」是否開啟、`maxPerReply >= 1`。
+3. `public-url` 與 `media` 是否 OK：`media` 會真的組一則 Flex 圖片並抓 `/media/<token>`。
+4. 看日誌關鍵字：`找不到表情包`、`表情包格式不支援`、`公開網址尚未就緒`、`LINE 400`。
+5. 轉圖工具：macOS 有 `sips`；GIF／APNG 需要 `ffmpeg`；Windows 沒有 `sips`，webp／gif 需要 `ffmpeg`。
+6. 模型有沒有照格式輸出？面板「測試 Agent 回覆」或 `meme-preview` 可驗證；支援標記：`[[meme:描述]]`、`[[meme:#編號]]`、`<meme#編號>`、`[表情: 描述]`。
+
+## 3. 檔案與端點
+
+- `lib/host.mjs`：主要流程（webhook 事件、回覆、tunnel、人設、記憶、表情包、診斷）。
+- `lib/line-api.mjs`：LINE API（reply/push/loading/webhook endpoint）。
+- `lib/tunnel.mjs`：cloudflared 管理。
+- `lib/meme-source.mjs`：讀 dsh-meme。
+- `lib/chat-import.mjs`：LINE 匯出聊天解析。
+- `lib/diagnostics.mjs`：doctor 用的檢查工具。
+- `bin/cli.mjs`：安裝／`doctor`。
+- HTTP：`/api/line-bot/status|config|action|doctor`（webServer）、`http://127.0.0.1:<port>/doctor|health|media/<id>|webhook`（外掛自己的伺服器）。
+- 資料：`$DSH_HOME/line-bot/`（config.json 600、state.json、memories.json、logs、personas、cache、users）。
+
+## 4. 安全規則
+
+- 不要把 `config.json`、state、token、userId 貼進回覆或 commit；doctor 輸出已避開秘密。
+- 不要手改 `~/.dsh/profiles/*`；要改設定用面板或 `POST /api/line-bot/config`。
+- 不要在未經使用者確認時清空記憶、群組或工作資料夾。
+- `doctor --fix` 只會重連 tunnel／重設 webhook；其他修復請照 check 的 `fix` 指示。
+- 改程式後：`node --check`，再 `POST /api/line-bot/dev/reload`（等 tunnel 換網址後重新套 webhook），最後再跑一次 `doctor` 驗證。
+
+## 5. 修好後要回報什麼
+
+- 哪個 check 從 fail/warn 變成 ok。
+- 做了哪個安全修復（例如「重設 webhook 到新 tunnel」）。
+- 若需要使用者操作（LINE console 開 Use webhook、安裝 ffmpeg、換模型），明確列出來。

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.8.0
+
+- 內建診斷：`GET /doctor`、`npx dsh-line-bot doctor [--fix] [--json]`，檢查伺服器／tunnel／公開網址／webhook／dsh-meme／表情包設定／轉圖工具／模型／圖片可送達／最近錯誤。
+- 面板「進階設定」新增「執行診斷」與「自動修復（安全）」。
+- 修正：Flex 圖片訊息（`hero.url`）在診斷中會被正確辨識；表情包描述改用圖庫樣本比對，長描述也能命中。
+- 新增 `AGENTS.md`（給 DSH Agent 的除錯流程）與 `TROUBLESHOOTING.md`（症狀對照）。
+
 ## 0.7.2
 
 - 匯入聊天時若成員還沒對應到 LINE 帳號，先用「名字」記住；本人第一次在群組發言時，這些記憶也會一起帶入。

package/README.en.md

@@ -206,6 +206,11 @@ The persona can attach a sticker to a text reply, or reply with just an image. I
 - The panel's "Memes" card can disable the feature, limit images per reply (1–3), and preview library samples. To add or re-tag images, use dsh-meme's own settings.
 - When a LINE sticker arrives, the bot fetches the sticker image and shows it to the model (vision-capable models read the image; otherwise the bot falls back to the keywords LINE provides), so the persona can react to the mood. Turn "Understand stickers" off in the LINE credentials card to use keywords only.
 - Without dsh-meme installed, the feature stays off and replies are text only.
+## Diagnostics
+- Panel → Advanced → Run diagnostics checks the server, tunnel, public URL, webhook, dsh-meme library, image converters, model, and recent errors; Safe repair only reconnects the tunnel and re-applies the webhook.
+- CLI: `npx dsh-line-bot doctor`, `doctor --fix`, `doctor --json`.
+- Agent playbook: `AGENTS.md`; symptom table: `TROUBLESHOOTING.md`.
+
 ## Troubleshooting
 
 - **The panel says "cannot connect to the LINE Bot runtime"**: webServer may not be ready yet; refresh. If it still fails, look for `[line-bot]` messages in the DSH logs.

package/README.ja.md

@@ -206,6 +206,11 @@ Bot がグループ（または複数人のルーム）に追加されたとき
 - パネルの「表情パック」カードでオンオフ、1 回あたりの上限（1〜3）、ライブラリのサンプル表示ができます。画像の追加や分類の変更は dsh-meme 側の設定で行います。
 - LINE スタンプを受信すると、スタンプ画像を取得してモデルに見せます（画像対応モデルはそのまま読み、非対応なら LINE のキーワードを使います）。「LINE 認証情報」カードの「スタンプを理解する」でオフにできます。
 - dsh-meme がインストールされていない場合、この機能は無効になりテキストのみ返します。
+## 診断
+- パネルの「詳細設定 → 診断を実行」でサーバー、Tunnel、公開 URL、webhook、dsh-meme 図庫、画像変換ツール、モデル、最近のエラーを確認できます。「安全な修復」は tunnel 再接続と webhook 再設定だけを行います。
+- CLI：`npx dsh-line-bot doctor`、`doctor --fix`、`doctor --json`。
+- Agent 向け手順は `AGENTS.md`、症状別は `TROUBLESHOOTING.md`。
+
 ## トラブルシューティング
 
 - **パネルに「LINE Bot ランタイムに接続できません」と出る**：webServer がまだ準備できていない可能性があります。再読み込みしてください。それでも失敗する場合は DSH ログの `[line-bot]` を確認します。

package/README.ko.md

@@ -206,6 +206,11 @@ Bot이 그룹(또는 다인 룸)에 추가되면:
 - 패널의 「이모티콘」 카드에서 켜고 끄기, 답장당 최대 장수(1~3), 라이브러리 샘플 미리보기를 할 수 있습니다. 이미지 추가나 분류 변경은 dsh-meme 설정에서 하세요.
 - LINE 스티커를 받으면 스티커 이미지를 가져와 모델에 보여 줍니다(이미지 지원 모델은 바로 읽고, 아니면 LINE 키워드로 대체). 「LINE 자격 증명」 카드에서 「스티커 이해」를 끌 수 있습니다.
 - dsh-meme이 설치되어 있지 않으면 이 기능은 꺼지고 텍스트만 답장합니다.
+## 진단
+- 패널의 "고급 설정 → 진단 실행"에서 서버, Tunnel, 공개 URL, webhook, dsh-meme 라이브러리, 이미지 변환 도구, 모델, 최근 오류를 확인할 수 있습니다. "안전 복구"는 tunnel 재연결과 webhook 재설정만 수행합니다.
+- CLI: `npx dsh-line-bot doctor`, `doctor --fix`, `doctor --json`.
+- Agent용 절차는 `AGENTS.md`, 증상별 안내는 `TROUBLESHOOTING.md`.
+
 ## 문제 해결
 
 - **패널에 "LINE Bot 런타임에 연결할 수 없습니다"**: webServer가 아직 준비되지 않았을 수 있습니다. 새로 고침하세요. 그래도 실패하면 DSH 로그의 `[line-bot]` 메시지를 확인합니다.

package/README.md

@@ -206,6 +206,11 @@ Bot 被加進群組（或多人聊天室）後：
 - 面板「表情包」卡可以開關、限制一次最多幾張（1～3），並預覽圖庫樣本。要新增圖片或改分類，請用 dsh-meme 自己的設定。
 - 收到 LINE 貼圖時，會抓貼圖圖片交給模型看（支援圖片的模型直接讀圖，否則用 LINE 提供的關鍵字），角色才接得住貼圖的情緒。可在「LINE 憑證」卡關閉「看得懂貼圖」。
 - 沒安裝 dsh-meme 時這個功能會自動停用，只回文字。
+## 診斷與修復
+- 面板「進階設定 → 執行診斷」會檢查伺服器、Tunnel、公開網址、webhook、表情包圖庫、轉圖工具、模型與最近錯誤；「自動修復（安全）」只會重連 tunnel、重設 webhook。
+- 終端機：`npx dsh-line-bot doctor`、`npx dsh-line-bot doctor --fix`、`doctor --json`。
+- 給 Agent 的除錯流程在 `AGENTS.md`，症狀對照在 `TROUBLESHOOTING.md`。
+
 ## 疑難排解
 
 - **面板顯示「無法連線到 LINE Bot 執行期」**：webServer 可能還沒就緒，重新整理即可；仍失敗就看 DSH 日誌裡 `[line-bot]` 的訊息。

package/README.zh-CN.md

@@ -206,6 +206,11 @@ Bot 被加入群组（或多人聊天室）后：
 - 面板「表情包」卡可以开关、限制每次最多几张（1～3），并预览图库样本。要新增图片或改分类，请用 dsh-meme 自己的设置。
 - 收到 LINE 贴图时，会抓贴图图片交给模型看（支持图片的模型直接读图，否则用 LINE 提供的关键词），角色才能接住贴图的情绪。可在「LINE 凭证」卡关闭「看得懂贴图」。
 - 没安装 dsh-meme 时该功能会自动停用，只回文字。
+## 诊断与修复
+- 面板「高级设置 → 执行诊断」会检查服务器、Tunnel、公开网址、webhook、表情包图库、转图工具、模型与最近错误；「自动修复（安全）」只会重连 tunnel、重设 webhook。
+- 终端：`npx dsh-line-bot doctor`、`npx dsh-line-bot doctor --fix`、`doctor --json`。
+- 给 Agent 的调试流程在 `AGENTS.md`，症状对照在 `TROUBLESHOOTING.md`。
+
 ## 疑难排解
 
 - **面板显示「无法连接到 LINE Bot 运行时」**：webServer 可能还没就绪，刷新即可；仍失败就看 DSH 日志里 `[line-bot]` 的消息。

package/TROUBLESHOOTING.md

@@ -0,0 +1,55 @@
+# 疑難排解
+
+先跑一次診斷，把結果貼給 DSH 的 Agent，它就能照 `AGENTS.md` 的流程修：
+
+```bash
+npx dsh-line-bot doctor
+npx dsh-line-bot doctor --fix   # 安全修復：重連 tunnel、重設 webhook
+```
+
+面板「進階設定」也有「執行診斷」與「自動修復（安全）」。
+
+## 常見症狀
+
+### Bot 完全沒回
+- 檢查 `server`、`tunnel`、`webhook` 三個檢查。
+- LINE console → Messaging API → Webhook 設定要開「Use webhook」。
+- quick tunnel 每次重啟會換網址；`doctor --fix` 會把 webhook 指到目前網址。
+- LINE 不會重送失敗的 webhook，斷線期間的訊息會直接遺失。
+
+### 回文字但沒有圖片
+- 面板「表情包」要開啟，且偵測到 `dsh-meme` 圖庫（`count > 0`）。
+- `public-url`、`media` 檢查要 OK；quick tunnel 剛換網址的前幾秒 LINE 抓不到圖，會先不附圖。
+- GIF／webp 需要轉圖：macOS 內建 `sips`，GIF／APNG 與 Windows 建議裝 `ffmpeg`。
+- 日誌關鍵字：`找不到表情包`、`表情包格式不支援`、`公開網址尚未就緒`。
+- 用面板「測試 Agent 回覆」或 `meme-preview` 確認模型有輸出標記。
+
+### 回覆裡出現 `[[meme:…]]` 或 `<meme#18>`
+- 舊版不認得標記格式；升級到 0.6.1 以上（目前 0.8.x）。
+
+### 貼圖看不懂
+- 需要模型支援圖片（`inputModalities` 含 `image`）。面板「模型與接口來源」可換模型。
+- 模型不支援時仍會用貼圖關鍵字，不會壞掉。
+
+### APNG 不會動
+- LINE 不播放 APNG，只顯示第一幀。保持 `stickers.apng=false` 即可。
+
+### Windows 安裝失敗
+- 優先用 DSH 面板「設定 → 外掛 → 安裝 bundle」。
+- 或用新版 CLI（0.3.1+）並先 `npm install -g pnpm`；沒有 `sips` 時裝 ffmpeg。
+
+### 群組不回
+- 面板「群組」：被 @／引用一定回；其他訊息依機率擲骰（預設 15%）。
+- 群組要開「在群組裡運作」。
+
+### 主動訊息沒出現
+- 面板「主動傳訊」：機率、每日／每月上限、靜音時段、閒置分鐘、冷卻。
+- 沒有對話過的使用者不會被主動找。
+
+### 餘額提醒沒出現
+- 只有 `provider = deepseek-account` 才適用。
+- 餘額要高於門檻才會提醒；冷卻（預設 12 小時）與靜音時段會跳過。
+- 面板「DeepSeek 餘額」可看 `applicable`、`lastAskAt`、`nextCheckAt`。
+
+### npm 安裝出現 ETARGET
+- registry／CDN 傳播延遲，等 1–5 分鐘；必要時 `npm cache clean --force`。

package/bin/cli.mjs

@@ -5,6 +5,7 @@
 //   npx dsh-line-bot install [--profile <名稱>] [--version <版本>] [--dry-run]
 //   npx dsh-line-bot uninstall [--profile <名稱>] [--dry-run]
 //   npx dsh-line-bot status [--profile <名稱>]
+//   npx dsh-line-bot doctor [--fix] [--json]
 //
 // 它做的事和 DSH 面板的「安裝 bundle」一樣：
 //   1. 用 DSH 內建的 pnpm 把套件加進 profile；
@@ -21,6 +22,8 @@ import readline from 'node:readline/promises'
 const IS_WIN = process.platform === 'win32'
 import { fileURLToPath } from 'node:url'
 
+import { whichCommand, scanLogForErrors, summarizeChecks, check } from '../lib/diagnostics.mjs'
+
 const PKG = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const NAME = PKG.name || 'dsh-line-bot'
 
@@ -40,7 +43,7 @@ function fail(message) {
 }
 
 function parseArgs(argv) {
-  const options = { command: '', profile: '', version: '', spec: '', dryRun: false, enable: true, companions: 'ask' }
+  const options = { command: '', profile: '', version: '', spec: '', dryRun: false, enable: true, companions: 'ask', fix: false, json: false }
   const rest = [...argv]
   options.command = (rest.shift() || 'help').toLowerCase()
   for (let index = 0; index < rest.length; index += 1) {
@@ -68,6 +71,10 @@ function parseArgs(argv) {
       options.companions = 'yes'
     } else if (arg === '--no-companions') {
       options.companions = 'no'
+    } else if (arg === '--fix') {
+      options.fix = true
+    } else if (arg === '--json') {
+      options.json = true
     } else if (arg === '--help' || arg === '-h') {
       options.command = 'help'
     } else {
@@ -289,6 +296,85 @@ async function setupCompanions(profile, options) {
   out('✔ 搭配外掛安裝完成。')
 }
 
+
+async function httpJson(url, timeout = 45000) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeout) })
+  const body = await res.json().catch(() => null)
+  if (!res.ok || !body?.ok) throw new Error(body?.error || `HTTP ${res.status}`)
+  return body.value
+}
+
+function offlineDoctor(dataDir, reason) {
+  const checks = []
+  const configPath = path.join(dataDir, 'config.json')
+  let config = null
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')) } catch { /* ignore */ }
+  checks.push(check('config', '設定檔', config ? 'ok' : 'fail', config ? configPath : `找不到 ${configPath}`, config ? '' : '先在 DSH 面板安裝並啟動 dsh-line-bot'))
+  if (config) {
+    const line = config.line || {}
+    checks.push(check('line-config', 'LINE 憑證', line.channelSecret || line.accessToken ? 'ok' : 'fail',
+      line.channelSecret ? '已設定 Channel Secret' : line.accessToken ? '已設定 Access Token' : '沒有憑證',
+      line.channelSecret || line.accessToken ? '' : '面板「LINE 憑證」填入 Channel ID／Secret 或 Access Token'))
+    checks.push(check('server', 'Webhook 伺服器', 'warn', `無法連線（${reason}）`, '確認 DSH 正在執行、外掛已啟動；面板「狀態總覽」可看伺服器狀態'))
+  }
+  const home = dshHome()
+  let memeFound = false
+  try {
+    for (const entry of fs.readdirSync(path.join(home, 'profiles'))) {
+      const candidate = path.join(home, 'profiles', entry, 'node_modules', 'dsh-meme', 'package.json')
+      if (fs.existsSync(candidate)) { memeFound = true; break }
+    }
+  } catch { /* ignore */ }
+  checks.push(check('dsh-meme', 'dsh-meme 圖庫', memeFound ? 'ok' : 'fail',
+    memeFound ? '已安裝' : '沒有在 profile 裡找到 dsh-meme',
+    memeFound ? '' : 'npx dsh-line-bot install --with-companions'))
+  const sips = whichCommand('sips')
+  const ffmpeg = whichCommand('ffmpeg')
+  checks.push(check('converters', '轉圖工具', (sips || ffmpeg) ? 'ok' : 'warn',
+    `sips=${sips ? '有' : '無'} ffmpeg=${ffmpeg ? '有' : '無'}`,
+    ffmpeg ? '' : '安裝 ffmpeg 以支援 GIF／webp 表情包'))
+  const today = new Date().toISOString().slice(0, 10)
+  const recent = scanLogForErrors(path.join(dataDir, 'logs', `${today}.log`))
+  checks.push(check('logs', '最近錯誤', recent.length ? 'warn' : 'ok',
+    recent.length ? recent[recent.length - 1].slice(0, 240) : '沒有最近錯誤',
+    recent.length ? `看完整日誌：${path.join(dataDir, 'logs', `${today}.log`)}` : ''))
+  return { version: PKG.version, at: Date.now(), offline: true, summary: summarizeChecks(checks), checks }
+}
+
+async function commandDoctor(options) {
+  const home = dshHome()
+  const dataDir = path.join(home, 'line-bot')
+  let config = null
+  try { config = JSON.parse(fs.readFileSync(path.join(dataDir, 'config.json'), 'utf8')) } catch { /* ignore */ }
+  const port = Number(config?.server?.port) || 8791
+  const url = `http://127.0.0.1:${port}/doctor${options.fix ? '?repair=1' : ''}`
+  let result = null
+  let reason = ''
+  try {
+    result = await httpJson(url)
+  } catch (error) {
+    reason = error?.message || String(error)
+    result = offlineDoctor(dataDir, reason)
+  }
+  if (options.json) {
+    out(JSON.stringify(result, null, 2))
+    process.exitCode = result.summary?.fail ? 1 : 0
+    return
+  }
+  const icon = { ok: '✅', warn: '⚠️ ', fail: '❌' }
+  out(`dsh-line-bot ${result.version || PKG.version} 診斷${result.offline ? '（離線）' : ''}`)
+  for (const item of result.checks) {
+    out(`${icon[item.status] || '•'} ${item.title}：${item.detail}`)
+    if (item.fix) out(`   → ${item.fix}`)
+  }
+  const summary = result.summary || summarizeChecks(result.checks)
+  out(`\n結果：${summary.ok} 正常、${summary.warn} 提醒、${summary.fail} 失敗`)
+  if (result.offline) {
+    out('提示：伺服器在執行時，doctor 會自動測公開網址、webhook 與圖片可送達；修復請用 npx dsh-line-bot doctor --fix。')
+  }
+  process.exitCode = summary.fail ? 1 : 0
+}
+
 async function commandInstall(options) {
   const profile = pickProfile(options.profile)
   const { dir, file, manifest } = readManifest(profile)
@@ -410,6 +496,10 @@ switch (options.command) {
   case 'remove':
     commandUninstall(options)
     break
+  case 'doctor':
+  case 'diagnose':
+    await commandDoctor(options)
+    break
   case 'status':
   case 'list':
     commandStatus(options)

package/client.js

@@ -357,6 +357,7 @@ window.__ModuleLoader__.load({
       const [memoryData, setMemoryData] = useState(null)
       const [modelCatalog, setModelCatalog] = useState(null)
       const [importGroup, setImportGroup] = useState('')
+      const [doctorResult, setDoctorResult] = useState(null)
       const importInput = useRef(null)
       const [localEdit, setLocalEdit] = useState({ id: '', name: '', text: '' })
 
@@ -516,6 +517,22 @@ window.__ModuleLoader__.load({
         await loadMemory({ quiet: true })
       }
 
+      async function runDoctor(repair) {
+        setBusy('diagnose')
+        try {
+          const value = await jpost('/action', { action: 'diagnose', payload: { repair: repair === true } })
+          const result = value?.result || null
+          setDoctorResult(result)
+          if (value?.status) { setStatus(value.status); setDraft(stripSecrets(value.status.config || {})); }
+          const summary = result?.summary || {}
+          setToast({ kind: summary.fail ? 'err' : 'ok', text: `診斷完成：${summary.ok || 0} 正常、${summary.warn || 0} 提醒、${summary.fail || 0} 失敗。` })
+        } catch (error) {
+          setToast({ kind: 'err', text: error?.message || String(error) })
+        } finally {
+          setBusy('')
+        }
+      }
+
       async function importChatFile(event) {
         const file = event.target.files && event.target.files[0]
         event.target.value = ''
@@ -1305,7 +1322,19 @@ window.__ModuleLoader__.load({
           h('div', { style: S.row },
             h(Btn, { onClick: () => act('logs-clear'), disabled: !!busy, tone: 'danger' }, '清除日誌'),
             h(Btn, { onClick: devReload, disabled: !!busy }, '重新載入 host 模組（開發用）'),
+            h(Btn, { onClick: () => runDoctor(false), disabled: !!busy }, busy === 'diagnose' ? '診斷中…' : '執行診斷'),
+            h(Btn, { onClick: () => runDoctor(true), disabled: !!busy }, '自動修復（安全）'),
           ),
+          doctorResult
+            ? h('div', { style: S.panelBox },
+                h('div', { style: S.fieldTitle }, `診斷結果（${(doctorResult.summary && doctorResult.summary.ok) || 0} 正常 / ${(doctorResult.summary && doctorResult.summary.warn) || 0} 提醒 / ${(doctorResult.summary && doctorResult.summary.fail) || 0} 失敗）`),
+                (doctorResult.checks || []).map((item) => h('div', { key: item.id, style: { padding: '6px 0', borderTop: '1px solid var(--dsw-alias-border-l2)' } },
+                  h('div', { style: { fontSize: 13 } }, `${item.status === 'ok' ? '✅' : item.status === 'warn' ? '⚠️' : '❌'} ${item.title}：${item.detail}`),
+                  item.fix ? h('div', { style: { ...S.hint, marginTop: 2 } }, `→ ${item.fix}`) : null,
+                )),
+              )
+            : h('div', { style: S.hint }, '「執行診斷」會檢查伺服器、tunnel、公開網址、webhook、表情包圖庫、轉圖工具、模型與最近錯誤；「自動修復」只做重連 tunnel、重設 webhook 這類安全動作。'),
+          h('div', { style: S.label }, '即時日誌'),
           h(KV, {
             rows: [
               ['資料夾', status.paths?.dataDir || '—'],

package/lib/diagnostics.mjs

@@ -0,0 +1,61 @@
+// 診斷工具：把「為什麼圖片沒送出去」這類問題變成可讀的檢查清單。
+// 只讀取本機狀態，不修改設定；repair 由 host 另外執行安全修復。
+import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+export function whichCommand(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which'
+  try {
+    const result = spawnSync(cmd, [name], { encoding: 'utf8', timeout: 5000, windowsHide: true })
+    if (result.status !== 0) return ''
+    return String(result.stdout || '')
+      .split(/\r?\n/)
+      .map((item) => item.trim())
+      .find(Boolean) || ''
+  } catch {
+    return ''
+  }
+}
+
+export function check(id, title, status, detail, fix = '') {
+  return { id, title, status, detail: String(detail || ''), fix: String(fix || '') }
+}
+
+export function summarizeChecks(checks) {
+  const counts = { ok: 0, warn: 0, fail: 0 }
+  for (const item of checks) counts[item.status] = (counts[item.status] || 0) + 1
+  const status = counts.fail > 0 ? 'fail' : counts.warn > 0 ? 'warn' : 'ok'
+  return { status, ...counts, total: checks.length }
+}
+
+export function scanLogForErrors(file, { limit = 8, maxBytes = 200000 } = {}) {
+  try {
+    const stat = fs.statSync(file)
+    if (!stat.size) return []
+    const start = Math.max(0, stat.size - maxBytes)
+    const fd = fs.openSync(file, 'r')
+    const buffer = Buffer.alloc(stat.size - start)
+    fs.readSync(fd, buffer, 0, buffer.length, start)
+    fs.closeSync(fd)
+    const lines = buffer.toString('utf8').split(/\r?\n/).filter(Boolean)
+    const hits = []
+    const seen = new Set()
+    for (const line of lines) {
+      if (!/\[(warn|error)\]/.test(line)) continue
+      const key = line.replace(/^\S+\s+/, '').slice(0, 160)
+      if (seen.has(key)) continue
+      seen.add(key)
+      hits.push(line.trim())
+    }
+    return hits.slice(-limit)
+  } catch {
+    return []
+  }
+}
+
+export function formatChecks(checks) {
+  const icon = { ok: '✅', warn: '⚠️ ', fail: '❌' }
+  return checks
+    .map((item) => `${icon[item.status] || '•'} ${item.title}：${item.detail}${item.fix ? `\n   → ${item.fix}` : ''}`)
+    .join('\n')
+}

package/lib/host.mjs

@@ -19,6 +19,7 @@ const nudgeMod = await import(withVersion('./nudge.mjs'))
 const tiebaSyncMod = await import(withVersion('./tieba-sync.mjs'))
 const localPersonasMod = await import(withVersion('./local-personas.mjs'))
 const chatImport = await import(withVersion('./chat-import.mjs'))
+const diagnosticsMod = await import(withVersion('./diagnostics.mjs'))
 const tiebaContextMod = await import(withVersion('./tieba-context.mjs'))
 const balanceMod = await import(withVersion('./deepseek-balance.mjs'))
 const memoryMod = await import(withVersion('./memory.mjs'))
@@ -42,7 +43,7 @@ const { createMemeSource } = memeSourceMod
 const { createStickerImages } = stickerImageMod
 const { chunkText, clip, inQuietWindow, jsonFail, jsonOk, maskSecret, readJsonBody, safeArray, sleep } = utilMod
 
-export const VERSION = '0.7.2'
+export const VERSION = '0.8.0'
 
 // 環境變數提供的 Cloudflare API Token（方便用 shell 注入、不用把 token 寫進設定檔）。
 // 設定檔裡的 token 優先；兩者都沒有時才用環境變數。
@@ -1289,6 +1290,25 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
     }
   }
 
+  function findMemeChoice(desc, choices = runtime.memeChoices || []) {
+    const query = String(desc || '').trim()
+    if (!query || choices.length === 0) return null
+    const exact = choices.find((item) => item.caption === query)
+    if (exact) return exact
+    const contained = choices.find((item) => item.caption && (item.caption.includes(query) || query.includes(item.caption)))
+    if (contained) return contained
+    const tokens = query.split(/[，,。.!！?？、\s]+/).filter((item) => item.length >= 2)
+    let best = null
+    let bestScore = 0
+    for (const item of choices) {
+      const caption = item.caption || ''
+      let score = 0
+      for (const token of tokens) if (caption.includes(token)) score += token.length
+      if (score > bestScore) { bestScore = score; best = item }
+    }
+    return bestScore >= 2 ? best : null
+  }
+
   async function buildOutgoingMessages(text) {
     const cfg = store.get()
     const parsed = splitStickerMarkers(text)
@@ -1300,7 +1320,7 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
       for (const desc of parsed.memes.slice(0, max)) {
         const indexMatch = /^#?(\d{1,3})$/.exec(String(desc).trim())
         const index = indexMatch ? Number(indexMatch[1]) - 1 : -1
-        let file = index >= 0 ? (sample[index]?.path || '') : ''
+        let file = index >= 0 ? (sample[index]?.path || '') : (findMemeChoice(desc, sample)?.path || '')
         if (!file) {
           const picked = memes.pick({ query: desc })
           file = picked?.ok && picked.path ? picked.path : ''
@@ -1521,7 +1541,7 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
   const stickerImages = createStickerImages({ ctx, logger, dir })
   const mediaTokens = new Map()
 
-  const server = createWebhookServer({ getConfig: () => store.get(), logger, dispatch: handleEvent, getMedia })
+  const server = createWebhookServer({ getConfig: () => store.get(), logger, dispatch: handleEvent, getMedia, getDoctor: (options) => runDiagnostics(options) })
 
   const tunnel = createTunnelManager({
     getConfig: () => withEnvCloudflare(store.get()),
@@ -1681,6 +1701,126 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
     return buildStatus()
   }
 
+  async function runDiagnostics({ repair = false } = {}) {
+    const cfg = store.get()
+    const checks = []
+    const check = diagnosticsMod.check
+    if (repair) {
+      try {
+        const tunnelState = await tunnel.status()
+        if (cfg.tunnel?.autoStart && tunnelState.phase !== 'running' && tunnelState.phase !== 'external') await tunnel.start()
+        await refreshBotInfo()
+        await reconcileWebhook({ force: true })
+      } catch (error) {
+        logger.warn(`診斷修復失敗：${errorText(error)}`)
+      }
+    }
+    const serverState = server.status()
+    checks.push(check('server', 'Webhook 伺服器', serverState.running ? 'ok' : 'fail',
+      serverState.running ? `127.0.0.1:${serverState.port}` : (serverState.lastError || '沒有啟動'),
+      serverState.running ? '' : '面板按「啟動伺服器」，或執行 npx dsh-line-bot doctor --fix'))
+    const tunnelState = await tunnel.status().catch((error) => ({ phase: 'error', error: errorText(error) }))
+    const phaseOk = tunnelState.phase === 'running' || tunnelState.phase === 'external'
+    checks.push(check('tunnel', 'Cloudflare Tunnel', phaseOk ? 'ok' : 'fail',
+      `${tunnelState.phase}${tunnelState.url ? `：${tunnelState.url}` : ''}${tunnelState.error ? `（${tunnelState.error}）` : ''}`,
+      phaseOk ? '' : '檢查 tunnel.mode、cloudflared 路徑或 API Token，然後重啟 tunnel'))
+    const base = publicBaseSync()
+    checks.push(check('public-url', '公開網址', base ? 'ok' : 'fail', base || '沒有公開網址，LINE 抓不到圖片',
+      base ? '' : '啟動 tunnel，或設定 tunnel.publicUrl'))
+    if (base) {
+      let reachable = false
+      let detail = ''
+      try {
+        const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(6000) })
+        reachable = res.ok
+        detail = `HTTP ${res.status}`
+      } catch (error) {
+        detail = errorText(error)
+      }
+      checks.push(check('public-health', '公開網址健康檢查', reachable ? 'ok' : 'warn', detail || '無法連線',
+        reachable ? '' : 'quick tunnel 換網址後 LINE 可能還抓不到舊圖；重啟 tunnel 並重設 webhook'))
+    }
+    try {
+      const token = await getToken()
+      const endpoint = await lineApi.getWebhookEndpoint(token)
+      const expected = base ? `${base}/webhook` : ''
+      const matches = expected && String(endpoint?.endpoint || '') === expected
+      checks.push(check('webhook', 'LINE Webhook', endpoint?.active && matches ? 'ok' : 'fail',
+        `active=${!!endpoint?.active} endpoint=${endpoint?.endpoint || '（未設定）'}`,
+        endpoint?.active && matches ? '' : '面板按「套用 Webhook」，或執行 doctor --fix'))
+    } catch (error) {
+      checks.push(check('webhook', 'LINE Webhook', 'warn', errorText(error), '確認 Channel Access Token 與網路'))
+    }
+    let memeStats = { available: false, count: 0 }
+    try {
+      memeStats = memes.stats()
+      checks.push(check('dsh-meme', 'dsh-meme 圖庫', memeStats.available && memeStats.count > 0 ? 'ok' : 'fail',
+        `available=${!!memeStats.available} count=${memeStats.count || 0}`,
+        memeStats.available ? '' : '安裝 dsh-meme 外掛（npx dsh-line-bot install --with-companions）'))
+    } catch (error) {
+      checks.push(check('dsh-meme', 'dsh-meme 圖庫', 'fail', errorText(error), '安裝 dsh-meme 外掛'))
+    }
+    const stickerCfg = cfg.stickers || {}
+    checks.push(check('meme-config', '表情包設定', stickerCfg.enabled === false ? 'warn' : 'ok',
+      `enabled=${stickerCfg.enabled !== false} maxPerReply=${stickerCfg.maxPerReply || 1} apng=${!!stickerCfg.apng}`,
+      stickerCfg.enabled === false ? '面板「表情包」打開「允許角色使用表情包」' : ''))
+    const sips = diagnosticsMod.whichCommand('sips')
+    const ffmpeg = diagnosticsMod.whichCommand('ffmpeg')
+    checks.push(check('converters', '轉圖工具', (sips || ffmpeg) ? (process.platform === 'win32' && !ffmpeg ? 'warn' : 'ok') : 'warn',
+      `sips=${sips ? '有' : '無'} ffmpeg=${ffmpeg ? '有' : '無'}（GIF／APNG 需要 ffmpeg；webp 需要 sips 或 ffmpeg）`,
+      process.platform === 'win32' && !ffmpeg ? 'Windows 建議安裝 ffmpeg，否則 GIF／webp 表情包會送不出去' : '安裝 ffmpeg（brew install ffmpeg）可轉 GIF／APNG'))
+    try {
+      const selected = modelSelection()
+      const info = await ctx.get?.('llm')?.resolveModelInfo?.(selected.provider, selected.model)
+      const modalities = info?.inputModalities || []
+      checks.push(check('model', '回覆模型', 'ok',
+        `${selected.provider}/${selected.model}${modalities.length ? `（${modalities.join('+')}）` : ''}`,
+        modalities.includes('image') ? '' : '這個模型不吃圖；貼圖理解會退回關鍵字，但不影響送表情包'))
+    } catch (error) {
+      checks.push(check('model', '回覆模型', 'warn', errorText(error), '在面板「模型與接口來源」重新選模型'))
+    }
+    if (memeStats.available && base) {
+      try {
+        const sample = memes.sample({ limit: 1 })[0]
+        if (sample) {
+          const marker = `測試 [[meme:${sample.caption || sample.tag || ''}]]`
+          const built = await buildOutgoingMessages(marker)
+          let imageUrl = ''
+          for (const item of built.messages) {
+            if (item.type === 'image') imageUrl = item.originalContentUrl
+            else if (item.type === 'flex') {
+              const contents = item.contents || {}
+              if (contents.type === 'bubble') imageUrl = contents.hero?.url || ''
+              else if (contents.type === 'carousel') imageUrl = contents.contents?.[0]?.hero?.url || ''
+            }
+            if (imageUrl) break
+          }
+          if (imageUrl) {
+            const res = await fetch(imageUrl, { signal: AbortSignal.timeout(8000) })
+            checks.push(check('media', '圖片可送達測試', res.ok ? 'ok' : 'fail',
+              res.ok ? `HTTP ${res.status} ${imageUrl}` : `HTTP ${res.status}`,
+              res.ok ? '' : '公開網址或 /media 路由有問題，重啟 tunnel 後再試'))
+          } else {
+            checks.push(check('media', '圖片可送達測試', 'fail',
+              `組不出圖片訊息（caption=${String(sample.caption || '').slice(0, 30)}，messages=${built.messages.length}，markers=${built.parsed.memes.length}）`,
+              '確認 dsh-meme 圖庫與公開網址'))
+          }
+        }
+      } catch (error) {
+        checks.push(check('media', '圖片可送達測試', 'warn', errorText(error), '重試或查看日誌'))
+      }
+    }
+    try {
+      const today = new Date().toISOString().slice(0, 10)
+      const recent = diagnosticsMod.scanLogForErrors(path.join(dir, 'logs', `${today}.log`))
+      checks.push(check('logs', '最近錯誤', recent.length ? 'warn' : 'ok',
+        recent.length ? recent[recent.length - 1].slice(0, 240) : '沒有最近錯誤',
+        recent.length ? `看完整日誌：${path.join(dir, 'logs', `${today}.log`)}` : ''))
+    } catch { /* ignore */ }
+    const summary = diagnosticsMod.summarizeChecks(checks)
+    return { version: VERSION, at: Date.now(), summary, checks }
+  }
+
   // ── 狀態快照 ────────────────────────────────────────────────────────────
   async function buildStatus() {
     const cfg = store.get()
@@ -2126,6 +2266,9 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
         }
         return { userId, personaId, personaName: picked.name || '', personaSource: picked.source || 'dafeiyu' }
       }
+      case 'diagnose':
+        return runDiagnostics({ repair: payload.repair === true })
+
       case 'group-import': {
         const groupId = String(payload.groupId || '').trim()
         const text = String(payload.text || '')
@@ -2228,6 +2371,10 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
         jsonOk(res, await buildStatus())
         return
       }
+      if (req.method === 'GET' && sub === '/doctor') {
+        jsonOk(res, await runDiagnostics({ repair: url.searchParams.get('repair') === '1' }))
+        return
+      }
       if (req.method === 'GET' && sub.startsWith('/media/')) {
         const media = getMedia(decodeURIComponent(sub.slice('/media/'.length)))
         if (!media || !media.bytes) {

package/lib/webhook-server.mjs

@@ -17,7 +17,7 @@ function verifySignature(secret, raw, signature) {
   }
 }
 
-export function createWebhookServer({ getConfig, logger, dispatch, getMedia }) {
+export function createWebhookServer({ getConfig, logger, dispatch, getMedia, getDoctor }) {
   let server = null
   let port = 0
   let startedAt = 0
@@ -60,6 +60,17 @@ export function createWebhookServer({ getConfig, logger, dispatch, getMedia }) {
     const url = new URL(req.url || '/', 'http://127.0.0.1')
     lastRequestAt = Date.now()
 
+    if (req.method === 'GET' && url.pathname === '/doctor') {
+      if (typeof getDoctor !== 'function') return jsonFail(res, '診斷功能尚未載入', 503)
+      try {
+        const repair = url.searchParams.get('repair') === '1'
+        const result = await getDoctor({ repair })
+        return jsonOk(res, result)
+      } catch (error) {
+        return jsonFail(res, error?.message || String(error), 500)
+      }
+    }
+
     if (req.method === 'GET' && url.pathname === '/health') {
       jsonOk(res, {
         ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-line-bot",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "把 LINE 官方帳號（Messaging API）接進 DeepSeek Harness 的插件：內建 Cloudflare Tunnel、人設選擇（大肥魚或插件自訂）、主動傳訊與完整設定面板。",
   "type": "module",
   "main": "index.js",
@@ -23,7 +23,9 @@
     "README.*.md",
     "bin",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "TROUBLESHOOTING.md",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=22",