dsh-hooks 0.3.0 → 0.5.0

package/README.md

@@ -4,17 +4,19 @@ Config-driven lifecycle hooks plugin for [DeepSeek Harness](https://github.com/d
 
 Declare `event -> command` hooks directly in your profile's `cordis.patch.yml` — like Codex CLI / OpenCode hooks, but for dsh. No plugin code required.
 
-[中文文档](README.zh.md) | [Design](#design) | [Feishu example](examples/notify-feishu.mjs) | [Web GUI 面板](packages/dsh-hooks-ui/README.md)
+[中文文档](README.zh.md) | [Design](#design) | [Feishu example](examples/notify-feishu.mjs) | [Web GUI](#web-gui)
 
 ## Install
 
+One package ships everything (hook engine + Web GUI settings page):
+
 ```sh
 dsh plugin --profile web add dsh-hooks           # from npm
 # or straight from git:
 dsh plugin --profile web add github:PeterBon/dsh-hooks
 ```
 
-Restart `dsh web`.
+Restart `dsh web`. The settings panel gains a "Hooks" section (see [Web GUI](#web-gui)).
 
 ## Configure
 
@@ -141,7 +143,7 @@ The URL may also live in the dsh process environment as `DSH_HOOKS_WEBHOOK_URL`
 
 ## Execution history
 
-Every hook trigger is recorded into an in-memory ring buffer (default 500 entries) and best-effort appended to `~/.dsh/dsh-hooks/history.jsonl` (0600) — for future UIs and debugging. Records never contain secrets (env vars never enter records):
+Every hook trigger is recorded into an in-memory ring buffer (default 500 entries) and best-effort appended to `~/.dsh/dsh-hooks/history.jsonl` (0600) — for future UIs and debugging. The ring buffer seeds from the JSONL at startup and live-syncs new appends on every web-panel read (including appends from other dsh processes sharing the file, e.g. a task-board Host), so history survives restarts. Records never contain secrets (env vars never enter records):
 
 ```yaml
 - id: dsh-hooks
@@ -172,6 +174,17 @@ dsh-hooks dry-run tool/call --tool ssh_exec --execute   # end-to-end: actually r
 
 `dry-run` reads the profile's `cordis.patch.yml` (the `id: dsh-hooks` block) and validates the config (bad regexes fail here).
 
+## Web GUI
+
+After install, the dsh web settings panel gains a "Hooks" section (beside General and Plugins):
+
+- **Status badges**: plugin version, hook count, history count
+- **Manual tester**: pick an event (14 kinds) + reason/tool; "Simulate" shows the per-hook match report, "Execute" really triggers the matching hooks
+- **Feishu connect**: scan-to-connect inside the panel — the QR code renders inline (with expiry countdown and a cancel button); after the scan the app is created, credentials + hook config are written, and the connected summary offers a one-click test card, an inline truncation-length editor (50–5000 chars, default 300), and a re-connect flow
+- **Execution-history timeline**: at the bottom of the card, **collapsed by default** (an "expand" toggle opens the latest 30 triggers: time / event / command / outcome / stderr tail), refreshed every 5s
+
+CLI/headless environments are unaffected: the browser half loads only in the web GUI and the core has no UI runtime dependencies.
+
 ## Web profile HTTP routes
 
 In the web profile (when the shared webServer service exists) dsh-hooks registers loopback-only `/dsh-hooks/*` routes — CLI/headless environments never see them:
@@ -181,12 +194,28 @@ In the web profile (when the shared webServer service exists) dsh-hooks register
 | `/dsh-hooks/status` | GET | plugin version, hook count, history count |
 | `/dsh-hooks/history?n=50` | GET | the latest N execution records (JSON envelope) |
 | `/dsh-hooks/test` | POST | simulate an event: `{"event":"tool/call","tool":"ssh_exec","execute":false}` returns a per-hook match report; `execute: true` actually runs the matching hooks |
+| `/dsh-hooks/feishu/status` | GET | Feishu connection summary (app id / target masked, secret never leaves the server) + the scan-session snapshot + the truncation length |
+| `/dsh-hooks/feishu/setup` | POST | start a scan session: `{"profile":"web","resultMaxChars":800}`; returns the QR URL / PNG data URL / expiry (409 while one is pending) |
+| `/dsh-hooks/feishu/cancel` | POST | cancel the pending scan session (aborts the registerApp wait) |
+| `/dsh-hooks/feishu/config` | POST | update the card truncation length: `{"resultMaxChars":800}` (50–5000); effective immediately, credentials preserved |
+| `/dsh-hooks/feishu/test` | POST | send a test card with the stored credentials |
 
 Security matches dsh-aionui-panel: loopback-only, POSTs require `application/json` (blocks cross-site form CSRF). The web profile also gets a systemPrompt section announcing the plugin to agents.
 
 ## Feishu notification example
 
-The fastest path is the one-shot setup CLI — it creates the Feishu app for you via a QR-code scan and writes all hook config:
+Two ways to connect — the **Web GUI scan** (recommended, no terminal) or the one-shot setup CLI. Both create the Feishu app via a QR-code scan and write the same hook config.
+
+### Option 1: scan in the Web GUI
+
+Open the dsh web settings → "Hooks" section → "Feishu connect", fill in the profile (default `web`) and press the connect button:
+
+1. The panel shows the Feishu authorization QR code inline (with expiry countdown)
+2. Scanning creates an app named 「DSH 通知机器人」 (only the `im:message:send_as_bot` permission); the scanning user becomes the notification target
+3. The connected summary offers "send test card", an inline truncation-length editor (50–5000 chars, default 300, effective immediately), and "re-connect" (swap the bound app)
+4. Restart `dsh web` for the hooks to take effect
+
+### Option 2: setup CLI
 
 ```sh
 dsh-hooks feishu-setup                 # default profile: web
@@ -194,11 +223,13 @@ dsh-hooks feishu-setup --profile work  # another profile
 dsh-hooks feishu-test                  # send a test card with the stored credentials
 ```
 
-`feishu-setup` prints a QR code (and opens it in your browser), waits for you to scan it with Feishu, then creates an app named 「DSH 通知机器人」 with message-send permission and writes:
+`feishu-setup` prints a QR code (and opens it in your browser), waits for you to scan it with Feishu, then creates an app named 「DSH 通知机器人」 with message-send permission.
+
+Both options write the same files:
 
 | File | Purpose |
 | --- | --- |
-| `~/.dsh/dsh-hooks/feishu-config.json` | app id/secret + your open_id as the notification target (0600, never committed); `result_max_chars` sets the card content truncation (default 300) |
+| `~/.dsh/dsh-hooks/feishu-config.json` | app id/secret + your open_id as the notification target (0600, never committed); `result_max_chars` sets the card content truncation (default 300, editable in the Web GUI) |
 | `~/.dsh/dsh-hooks/notify-feishu.mjs` | stable copy of the notify script the hooks reference |
 | `~/.dsh/profiles/<profile>/cordis.patch.yml` | dsh-hooks block: `turn/end` (completed/error/aborted) + `approval/asked` + `agent/error` card hooks |
 
@@ -206,7 +237,7 @@ Restart `dsh web` afterwards — you will get cards when turns finish, approvals
 
 ![Feishu card example](assets/screenshot-1.jpg)
 
-### Manual configuration
+### Option 3: manual configuration
 
 Prefer wiring it by hand? See [`examples/notify-feishu.mjs`](examples/notify-feishu.mjs) — a zero-dependency script that posts turn-completion / approval notices through the Feishu **app API** (works without a group custom bot). Configure it like:
 

package/README.zh.md

@@ -8,13 +8,15 @@
 
 ## 安装
 
+一个包搞定全部（hook 引擎 + Web GUI 设置页）：
+
 ```sh
 dsh plugin --profile web add dsh-hooks           # 从 npm 安装
 # 或直接从 git 安装：
 dsh plugin --profile web add github:PeterBon/dsh-hooks
 ```
 
-重启 `dsh web` 生效。
+重启 `dsh web` 生效。安装后设置面板里会出现「Hooks」分区（见 [Web GUI](#web-gui)）。
 
 ## 配置
 
@@ -123,7 +125,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 
 ## 执行历史
 
-每次 hook 触发都会记入内存环形缓冲（默认 500 条），并 best-effort 追加到 `~/.dsh/dsh-hooks/history.jsonl`（权限 0600）——供未来 UI 与调试使用。记录不含 secret（环境变量从不入记录）：
+每次 hook 触发都会记入内存环形缓冲（默认 500 条），并 best-effort 追加到 `~/.dsh/dsh-hooks/history.jsonl`（权限 0600）——供未来 UI 与调试使用。环形缓冲在启动时从 JSONL 回填，且 Web 面板每次读取时增量同步磁盘上新增的记录（包括其他 dsh 进程的追加，如任务看板 Host），因此重启后历史不会消失。记录不含 secret（环境变量从不入记录）：
 
 ```yaml
 - id: dsh-hooks
@@ -154,6 +156,17 @@ dsh-hooks dry-run tool/call --tool ssh_exec --execute   # 端到端真跑匹配
 
 `dry-run` 直接读 profile 的 `cordis.patch.yml`（`id: dsh-hooks` 配置块），配置校验（非法正则等）会在这一步报错。
 
+## Web GUI
+
+安装后，dsh web 的设置面板里会出现「Hooks」分区（与「通用」「插件」平级）：
+
+- **状态徽章**：插件版本、hook 数、历史条数
+- **手动测试**：选事件（14 类）+ reason/tool，「模拟」看逐 hook 匹配报告，「执行」真实触发
+- **飞书通知**：网页内扫码连接飞书——显示二维码（含有效期倒计时、可取消），扫码后自动创建应用、写入凭据与 hook 配置；已连接后显示应用摘要，可一键发送测试卡片、调整卡片截断长度（50–5000 字符，默认 300）或重新扫码换绑
+- **执行历史时间线**：位于分区底部、**默认折叠**（标题旁「展开」查看最近 30 条触发：时间 / 事件 / 命令 / 结果 / stderr 尾部），5 秒自动刷新
+
+CLI/headless 环境完全不受影响：浏览器半只在 web 加载，核心零 UI 运行时依赖。
+
 ## Web profile HTTP 路由
 
 web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 loopback-only 的 `/dsh-hooks/*` 路由——CLI/headless 环境完全无感：
@@ -163,6 +176,11 @@ web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 loop
 | `/dsh-hooks/status` | GET | 插件版本、hook 数、历史条数 |
 | `/dsh-hooks/history?n=50` | GET | 最近 N 条执行历史（JSON envelope） |
 | `/dsh-hooks/test` | POST | 模拟事件评估：`{"event":"tool/call","tool":"ssh_exec","execute":false}` 返回逐 hook 匹配报告；`execute: true` 真跑匹配的 hook |
+| `/dsh-hooks/feishu/status` | GET | 飞书连接摘要（app id / 目标均已打码，绝不返回 secret）+ 扫码会话快照 + 截断长度 |
+| `/dsh-hooks/feishu/setup` | POST | 启动扫码会话：`{"profile":"web","resultMaxChars":800}`，返回二维码 URL / PNG data URL / 有效期；进行中时再次请求返回 409 |
+| `/dsh-hooks/feishu/cancel` | POST | 取消进行中的扫码会话（中止 registerApp 等待） |
+| `/dsh-hooks/feishu/config` | POST | 更新卡片截断长度：`{"resultMaxChars":800}`（50–5000），即时生效，保留凭据 |
+| `/dsh-hooks/feishu/test` | POST | 用已存凭据发送测试卡片 |
 
 安全约定与 dsh-aionui-panel 一致：仅回环地址可达、POST 必须 `application/json`（防跨站表单 CSRF）。同时 web profile 下会向 agent 注入一段 systemPrompt 公告，说明插件存在与协作方式。
 
@@ -186,7 +204,18 @@ URL 也可放在 dsh 进程环境的 `DSH_HOOKS_WEBHOOK_URL`（不要写进配
 
 ## 飞书通知示例
 
-最快的方式是一步到位的 setup CLI——扫码自动创建飞书应用并写好全部 hook 配置：
+两种接入方式任选：**Web GUI 扫码**（推荐，无需终端）或 **setup CLI**——扫码自动创建飞书应用并写好全部 hook 配置。
+
+### 方式一：Web GUI 扫码
+
+打开 dsh web 设置 → 「Hooks」分区 → 「飞书通知」，填好 profile（默认 `web`）点「扫码连接飞书」：
+
+1. 面板内显示飞书授权二维码（含有效期倒计时）
+2. 用飞书扫码，自动创建名为「DSH 通知机器人」的应用（仅 `im:message:send_as_bot` 权限），扫码者本人为通知接收人
+3. 连接完成后显示应用摘要，可「发送测试卡片」验证、直接修改卡片截断长度（50–5000 字符，默认 300，即时生效），「重新连接」可换绑新应用
+4. 重启 `dsh web` 生效
+
+### 方式二：setup CLI
 
 ```sh
 dsh-hooks feishu-setup                 # 默认 profile：web
@@ -194,11 +223,13 @@ dsh-hooks feishu-setup --profile work  # 指定其他 profile
 dsh-hooks feishu-test                  # 用已存凭据发送测试卡片验证
 ```
 
-`feishu-setup` 会打印二维码（并在浏览器中打开），等你用飞书扫码后，自动创建名为「DSH 通知机器人」的应用（带消息发送权限），并写入：
+`feishu-setup` 会打印二维码（并在浏览器中打开），等你用飞书扫码后，自动创建名为「DSH 通知机器人」的应用（带消息发送权限）。
+
+两种方式写入的文件相同：
 
 | 文件 | 用途 |
 | --- | --- |
-| `~/.dsh/dsh-hooks/feishu-config.json` | app id/secret 与你的 open_id（通知目标），权限 0600，严禁提交；`result_max_chars` 控制卡片内容截断长度（默认 300） |
+| `~/.dsh/dsh-hooks/feishu-config.json` | app id/secret 与你的 open_id（通知目标），权限 0600，严禁提交；`result_max_chars` 控制卡片内容截断长度（默认 300，可在 Web GUI 中修改） |
 | `~/.dsh/dsh-hooks/notify-feishu.mjs` | hook 引用的通知脚本稳定副本 |
 | `~/.dsh/profiles/<profile>/cordis.patch.yml` | dsh-hooks 配置块：`turn/end`（completed/error/aborted）+ `approval/asked` + `agent/error` 卡片 hook |
 
@@ -206,7 +237,7 @@ dsh-hooks feishu-test                  # 用已存凭据发送测试卡片验证
 
 ![飞书卡片示例](assets/screenshot-1.jpg)
 
-### 手动配置
+### 方式三：手动配置
 
 想自己接线？见 [`examples/notify-feishu.mjs`](examples/notify-feishu.mjs)——零依赖脚本，通过飞书**应用 API**（不需要群自定义机器人）发送回合完成 / 审批通知。配置示例：
 

package/bin/dsh-hooks.mjs

@@ -19,22 +19,36 @@
  *                                              turn/end + approval/asked +
  *                                              agent/error card hooks
  *
- * Requires Node >= 22. Dependencies: @larksuiteoapi/node-sdk (registerApp),
- * qrcode (terminal QR), yaml (patch merge). Credentials never enter argv or
- * the environment beyond the setup process itself.
+ * Requires Node >= 22. The shared setup logic lives in lib/feishu.js (also
+ * used by the web GUI's /dsh-hooks/feishu routes); this CLI half only adds
+ * the terminal QR rendering, the browser opener, and the argument parsing.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
 import { spawn } from 'node:child_process'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { registerApp } from '@larksuiteoapi/node-sdk'
 import QRCode from 'qrcode'
-import YAML from 'yaml'
-import { run as notifyRun } from '../examples/notify-feishu.mjs'
 import { runDryRun } from '../lib/dry-run.js'
-
-const CONFIG_DIR = join(homedir(), '.dsh', 'dsh-hooks')
-export const CONFIG_PATH = join(CONFIG_DIR, 'feishu-config.json')
+import {
+  FEISHU_CONFIG_PATH,
+  mergePatchYaml,
+  notifyScriptPath,
+  patchPath,
+  runFeishuSetup,
+  runFeishuTest,
+  setupHooks,
+  stableScriptPath,
+  writeConfig,
+} from '../lib/feishu.js'
+
+/** Backward-compatible alias (feishu-notify parity). */
+export const CONFIG_PATH = FEISHU_CONFIG_PATH
+
+export {
+  mergePatchYaml,
+  notifyScriptPath,
+  patchPath,
+  setupHooks,
+  stableScriptPath,
+  writeConfig,
+}
 
 /** Open a URL in the default browser (best-effort, never throws). */
 export function openInBrowser(url) {
@@ -54,127 +68,24 @@ export function openInBrowser(url) {
   })
 }
 
-/** Profile patch file for a profile name. */
-export function patchPath(profile) {
-  return join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml')
-}
-
-/** Which hooks the setup installs into the profile. */
-export function setupHooks(scriptPath) {
-  return [
-    { on: 'turn/end', when: 'completed', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
-    { on: 'turn/end', when: 'error', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
-    { on: 'turn/end', when: 'aborted', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
-    { on: 'approval/asked', run: `node ${JSON.stringify(scriptPath)} --approval`, timeoutMs: 30000 },
-    { on: 'agent/error', run: `node ${JSON.stringify(scriptPath)}`, timeoutMs: 30000 },
-  ]
-}
-
-/** Absolute path of the shipped notify script (where it lives now). */
-export function notifyScriptPath() {
-  return new URL('../examples/notify-feishu.mjs', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
-}
-
-/**
- * Resolve the stable notify-script location hooks should reference.
- * The npx cache (where this CLI often runs from) is ephemeral, so the
- * setup copies the zero-dependency script next to feishu-config.json:
- * ~/.dsh/dsh-hooks/notify-feishu.mjs. Re-copies on every setup so the
- * stable copy tracks the installed CLI version.
- */
-export function stableScriptPath(paths = {}) {
-  return paths.notifyScript ?? join(CONFIG_DIR, 'notify-feishu.mjs')
-}
-
-/**
- * Write the credential file with 0600 perms (owner-only), matching the
- * feishu-notify security posture: secrets stay out of the repo and argv.
- */
-export function writeConfig(configPath, { appId, appSecret, targetType = 'open_id', targetId, resultMaxChars = 300 }) {
-  mkdirSync(join(configPath, '..'), { recursive: true, mode: 0o700 })
-  const doc = JSON.stringify(
-    {
-      app_id: appId,
-      app_secret: appSecret,
-      target_type: targetType,
-      target_id: targetId,
-      result_max_chars: resultMaxChars,
-    },
-    null,
-    2,
-  )
-  writeFileSync(configPath, doc + '\n', 'utf8')
-  try {
-    chmodSync(configPath, 0o600)
-  } catch {
-    // Windows: ACL-based protection; the file lives under the user profile.
-  }
-}
-
-/**
- * Merge the dsh-hooks config block into a profile's cordis.patch.yml:
- * existing dsh-hooks entries keep unrelated config and get their hooks
- * replaced with `setupHooks`; other entries stay untouched. Idempotent.
- */
-export function mergePatchYaml(existingText, { scriptPath }) {
-  let entries
-  try {
-    entries = YAML.parse(existingText || '[]\n')
-  } catch {
-    throw new Error('profile 的 cordis.patch.yml 解析失败，请先修复该文件')
-  }
-  if (!Array.isArray(entries)) throw new Error('cordis.patch.yml 顶层必须是 YAML 数组')
-
-  const hooks = setupHooks(scriptPath)
-  let found = false
-  for (const entry of entries) {
-    if (entry && typeof entry === 'object' && entry.id === 'dsh-hooks') {
-      entry.name = 'dsh-hooks'
-      entry.config = { hooks }
-      found = true
-      break
-    }
-  }
-  if (!found) entries.push({ id: 'dsh-hooks', name: 'dsh-hooks', config: { hooks } })
-  return YAML.stringify(entries)
-}
-
 /**
- * Full setup flow. `deps` is injectable for tests:
- *   registerAppFn — the official registerApp (default)
- *   print/printErr — output sinks
- *   openUrl — browser opener (no-op by default in tests)
- *   paths — { configPath, patchFile, notifyScript }
- * Returns the created app facts (without the secret in logs).
+ * CLI front for the shared setup flow: print the terminal QR and open the
+ * authorization URL in the default browser when the code is ready.
  */
 export async function setupFeishu({
   profile = 'web',
-  registerAppFn = registerApp,
+  registerAppFn,
   print = console.log,
   printErr = console.error,
   openUrl = openInBrowser,
   paths = {},
 } = {}) {
-  const configPath = paths.configPath ?? CONFIG_PATH
-  const patchFile = paths.patchFile ?? patchPath(profile)
-  const notifyScript = stableScriptPath(paths)
-
-  print('dsh-hooks feishu-setup')
-  print('1/4 正在生成飞书「一键创建应用」二维码…')
-
-  const result = await registerAppFn({
-    source: 'dsh-hooks',
-    createOnly: true,
-    appPreset: {
-      name: 'DSH 通知机器人',
-      desc: 'DeepSeek Harness 会话事件通知（dsh-hooks）',
-    },
-    addons: {
-      preset: false,
-      scopes: {
-        tenant: ['im:message:send_as_bot'],
-      },
-    },
+  return runFeishuSetup({
+    profile,
+    print,
+    printErr,
+    paths,
+    ...(registerAppFn !== undefined ? { registerAppFn } : {}),
     onQRCodeReady: (authorization) => {
       print('')
       print(`请用飞书扫码（${authorization.expireIn} 秒内有效），或在浏览器打开：`)
@@ -190,82 +101,11 @@ export async function setupFeishu({
       void Promise.resolve(openUrl(authorization.url)).catch(() => undefined)
     },
   })
-
-  const appId = result.client_id
-  const appSecret = result.client_secret
-  const ownerOpenId = result.user_info?.open_id
-  if (!appId || !appSecret) throw new Error('扫码创建未完成，未拿到应用凭证')
-  if (!ownerOpenId) throw new Error('扫码结果缺少 open_id，请重试')
-
-  print('')
-  print(`2/4 应用创建成功：${appId}（机器人将私聊通知你）`)
-
-  writeConfig(configPath, {
-    appId,
-    appSecret,
-    targetType: 'open_id',
-    targetId: ownerOpenId,
-    resultMaxChars: 300,
-  })
-  print(`3/4 凭据已写入 ${configPath}（权限 0600，勿提交到仓库）`)
-
-  // Copy the notify script to its stable location so hooks never
-  // reference the ephemeral npx cache.
-  if (!paths.notifyScript) {
-    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 })
-    writeFileSync(notifyScript, readFileSync(notifyScriptPath(), 'utf8'), 'utf8')
-  }
-
-  const existing = existsSync(patchFile) ? readFileSync(patchFile, 'utf8') : '[]\n'
-  const merged = mergePatchYaml(existing, { scriptPath: notifyScript })
-  writeFileSync(patchFile, merged, 'utf8')
-  print(`4/4 hook 配置已写入 ${patchFile}`)
-
-  print('发送欢迎卡片验证…')
-  try {
-    await notifyRun({
-      appId,
-      appSecret,
-      to: ownerOpenId,
-      event: 'agent/created',
-      sessionId: 'dsh-hooks-setup',
-      cwd: process.cwd(),
-      timestamp: new Date().toISOString(),
-    })
-    print('✅ 欢迎卡片已发送。请重启 dsh web 使 hooks 生效。')
-  } catch (error) {
-    printErr(`⚠ 欢迎卡片发送失败（配置已就绪，可稍后用 feishu-test 重试）：${error instanceof Error ? error.message : String(error)}`)
-  }
-
-  return { appId, ownerOpenId }
 }
 
-/** Test credentials and send a test card to the configured target. */
+/** CLI front for the shared test-card flow. */
 export async function testFeishu({ print = console.log, paths = {} } = {}) {
-  const configPath = paths.configPath ?? CONFIG_PATH
-  if (!existsSync(configPath)) {
-    throw new Error(`未找到配置文件 ${configPath}，请先运行 feishu-setup`)
-  }
-  let file
-  try {
-    file = JSON.parse(readFileSync(configPath, 'utf8'))
-  } catch {
-    throw new Error(`配置文件 ${configPath} 解析失败，请重新运行 feishu-setup`)
-  }
-  if (!file.app_id || !file.app_secret || !file.target_id) {
-    throw new Error('配置文件不完整，请重新运行 feishu-setup')
-  }
-  await notifyRun({
-    appId: file.app_id,
-    appSecret: file.app_secret,
-    to: file.target_id,
-    event: 'agent/status',
-    status: 'connected',
-    sessionId: 'feishu-test',
-    cwd: process.cwd(),
-    timestamp: new Date().toISOString(),
-  })
-  print('✅ 测试卡片已发送')
+  return runFeishuTest({ print, paths })
 }
 
 const [, , command, ...args] = process.argv

package/examples/notify-feishu.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Typed surface of the shipped zero-dependency notify script
+ * (`examples/notify-feishu.mjs`) for the TypeScript half. The `.mjs` module
+ * resolves this `.d.mts` as its declaration, so lib code can import `run`
+ * without allowJs. Only the `run` entry the setup flow uses is declared.
+ */
+
+/** Loose hook-context-like input the notify script merges with the config file. */
+export interface NotifyFeishuContext {
+  appId?: string
+  appSecret?: string
+  to?: string
+  event?: string
+  sessionId?: string
+  sessionName?: string
+  cwd?: string
+  turn?: number | string
+  reason?: string
+  tool?: string
+  status?: string
+  error?: string
+  content?: string
+  timestamp?: string
+  [key: string]: unknown
+}
+
+export declare function run(
+  ctx: NotifyFeishuContext,
+  args?: string[],
+  configPath?: string,
+): Promise<{ kind: 'card' | 'text'; card?: unknown; text?: string }>