@miphamai/cli 0.50.0 → 0.51.0

package/src/i18n-core/locales/zh-CN.json

@@ -612,6 +612,129 @@
     },
     "schedule": {
       "failed": "调度检查失败: {error}"
+    },
+    "crsi_critique": {
+      "not_init": "SelfCritique 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "on_title": "## 🔍 Self-Critique: 已开启",
+      "on_desc1": "AI 现在会在每次工具调用执行前自我批判。",
+      "on_desc2": "每次目标工具调用前都会执行安全 + 正确 + 必要性检查。",
+      "on_hint": "💡 `/crsi critique off` 关闭 | `/crsi critique status` 查看当前配置",
+      "off_title": "## 🔍 Self-Critique: 已关闭\n\n工具调用将不再执行预检批判。",
+      "status_title": "## 🔍 Self-Critique 状态",
+      "state": "状态: **{state}**",
+      "model": "模型: **{model}**",
+      "threshold": "阈值: **{pct}%**",
+      "threshold_detail": "阈值: **{pct}%**（低于此 → 纠正或拦截）",
+      "target_tools": "目标工具: **{tools}**",
+      "timeout": "超时: **{ms}ms**",
+      "status_on_hint": "🔍 `/crsi critique on` — 启用自我批判",
+      "status_off_hint": "🔍 `/crsi critique off` — 禁用自我批判",
+      "inspired": "*灵感来自 Anthropic RLAIF — AI 在执行前批判自己的行为。*"
+    },
+    "crsi_interpret": {
+      "title": "## 🧠 CRSI 工具调用可解释性",
+      "no_sigs_for_tool": "工具 `{tool}` 没有错误签名。该工具的 CRSI 免疫记忆是干净的。",
+      "no_sigs": "没有活跃的错误签名。CRSI 免疫记忆是干净的。",
+      "sigs_title": "### 🛡️ 错误签名{tool}",
+      "sig_success": "  成功率: {bar} {pct}% | {occurrences}次 | {strategy}",
+      "sig_fix": "  修复: `{fix}`",
+      "sigs_more": "... 还有 {count} 条签名",
+      "reflection_title": "### 📊 CRSI 反思摘要",
+      "reflections": "已分析的轮次反思: **{count}**",
+      "usage_title": "### 💰 Token 用量",
+      "api_in": "API 输入 tokens:  {count}",
+      "api_out": "API 输出 tokens: {count}",
+      "est_tokens": "估算 tokens:  {count}",
+      "health_title": "### 🏥 系统健康",
+      "overall": "总体: {bar} **{score}/100**",
+      "assessment": "评估: {assessment}",
+      "constitution_title": "### ⚖️ 宪法",
+      "principles": "原则: **{total}** (🚫 {block} 拦截 | ⚠️ {warn} 警告 | 🔄 {auto} 自动)",
+      "version": "版本: v{version}",
+      "empty": "_开始使用工具以填充 CRSI 可解释性数据。_",
+      "filter_hint": "🔍 按工具过滤: `/crsi interpret <工具名>` (例如 `/crsi interpret Bash`)"
+    },
+    "crsi_red_team": {
+      "not_init": "Red-Team 需要 ConstitutionLoader 和 PreFlightChecker 均已初始化。",
+      "title": "## 🔴 CRSI 红队报告",
+      "score": "总体得分: **{score}/100**",
+      "metric": "| 指标 | 数量 |",
+      "metric_sep": "|------|------|",
+      "total_attacks": "| 总攻击数 | {count} |",
+      "blocked": "| 🛡️ 正确拦截 | {count} |",
+      "passed_through": "| 🔴 穿透（缺口） | {count} |",
+      "false_positives": "| ⚠️ 误报 | {count} |",
+      "by_principle": "### 按原则",
+      "gaps_title": "### 🔴 安全缺口（本应被拦截）",
+      "gap_tool": "  工具: `{tool}` → 参数: `{params}`",
+      "blocked_title": "### 🛡️ 成功拦截",
+      "caught_by": "{principle}: {desc} → 由 **{caught}** 捕获",
+      "all_blocked": "🎉 **所有攻击均被拦截！** SIS 自免疫系统完全正常运转。",
+      "good_coverage": "⚠️ 覆盖良好。请审查上述缺口，并向 `ai-guardrails.yml` 添加审计模式。",
+      "critical": "🔴 **检测到严重缺口。** 优先修复上述穿透的攻击。"
+    },
+    "dream": {
+      "not_init": "DreamEngine 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "no_history": "🌙 尚未运行过 Auto-Dream。使用 `/dream` 手动触发首次梦境整合。",
+      "history_title": "## 🌙 Auto-Dream 历史",
+      "history_entry": "- **{time}**: {total} 行动 ({applied} 自动应用, {flagged} 标记审查)",
+      "done_title": "## 🌙 Auto-Dream 完成",
+      "integrate": "记忆整合: {before} → {after}",
+      "dedup": "- 去重: {count} 条",
+      "contradiction": "- 矛盾冲突: {count} 处 (需人工裁决)",
+      "merge": "- 合并: {count} 组",
+      "solidify": "- 模糊标记: {count} 条 (建议固化)",
+      "prune": "- 清理过期: {count} 条",
+      "review_hint": "⚠️  {count} 项待审查。使用 `/dream --aggressive` 自动应用所有操作。",
+      "clean": "✅ 记忆干净，无需整理。"
+    },
+    "constitution": {
+      "not_init": "ConstitutionLoader 未初始化。请确认 Mipham Code 版本 >= v0.34.0。",
+      "reload_title": "## ⚖️ 宪法已重新加载",
+      "version": "版本: **v{version}**",
+      "principles": "原则: **{count}**",
+      "path": "路径: `{path}`",
+      "view_title": "## ⚖️ Mipham 宪法",
+      "view_summary": "版本: **v{version}** | 原则: **{count}** | 路径: `{path}`",
+      "scope": "  作用域: `{scope}`",
+      "tools": "  工具: {tools}",
+      "reload_hint": "🔧 `/constitution reload` — 重新加载（修改 ai-guardrails.yml 后使用）",
+      "edit_hint": "📝 编辑: `vi ~/.mipham/ai-guardrails.yml`",
+      "reset_hint": "🗑️  重置: 删除 `~/.mipham/ai-guardrails.yml` 后执行 `/constitution reload`",
+      "inspired": "*灵感来自 Anthropic 宪法 AI。Mipham 在运行时强制执行这些原则 — 每次行动都可审计。*"
+    },
+    "bug_report": {
+      "title": "## 🐛 Bug 报告",
+      "hint": "> 复制下面的报告并粘贴到你的 GitHub Issue 中。",
+      "env_title": "### 环境",
+      "mipham": "- **Mipham Code**: v{version}",
+      "session": "- **会话**: {id}",
+      "node": "- **Node**: {version}",
+      "platform": "- **平台**: {platform} {arch}",
+      "os": "- **操作系统**: {os}",
+      "provider": "- **提供商**: {provider}",
+      "model": "- **模型**: {model}",
+      "sigs_title": "### 活跃错误签名",
+      "sig_entry": "- `{id}`: {pattern} ({category}, {occurrences}次, {pct}% 成功率)",
+      "disabled_hooks": "### 已禁用的 Hooks",
+      "hook_entry": "- `{key}`: {failures} 次失败, 于 {time} 禁用",
+      "last_dream": "### 最近一次 Auto-Dream",
+      "ran_at": "- **运行于**: {time}",
+      "actions": "- **行动**: {total} ({applied} 已应用)",
+      "steps_title": "### 复现步骤",
+      "expected": "### 预期行为",
+      "actual": "### 实际行为",
+      "generated": "🤖 由 Mipham Code v{version} 生成"
+    },
+    "changelog": {
+      "title": "## 📋 变更日志",
+      "no_tags": "未找到版本标签。",
+      "current": "当前: **v{version}**",
+      "current_marker": " ← 当前",
+      "release_only": "  _(仅发布标签)_",
+      "details_unavailable": "  _(详情不可用)_",
+      "no_git": "无法读取 git 历史。请确认你位于 Mipham Code 仓库中。",
+      "full_history": "完整历史: `git log --oneline`"
     }
   },
   "ui": {

package/src/index.tsx

@@ -524,6 +524,12 @@ export async function runApp(options: RunOptions): Promise<void> {
     engine.getPermission().setRestrictions(config.permissionRestrictions)
   }
 
+  // Apply user-defined permission rules (allow/deny) — wire the rule system into runtime
+  if (config.permissionRules) {
+    for (const rule of config.permissionRules.allow ?? []) engine.getPermission().allow(rule)
+    for (const rule of config.permissionRules.deny ?? []) engine.getPermission().deny(rule)
+  }
+
   // Initialize agent registry and load plugin agents/skills/MCP/hooks
   const agentRegistry = new AgentRegistry()
   agentRegistry.loadUserAgents()

package/src/shared/package-info.ts

@@ -9,7 +9,7 @@
 export const PACKAGE_NAME = '@miphamai/cli' as const
 
 /** 当前发布版本 */
-export const PACKAGE_VERSION = '0.50.0' as const
+export const PACKAGE_VERSION = '0.51.0' as const
 
 /** npm install 全局安装命令 */
 export const NPM_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}` as const

package/src/shared/types.ts

@@ -133,6 +133,8 @@ export interface MiphamConfig {
   permission: ToolPermission
   /** Org-level permission restrictions (forbiddenModes, maxAllowedMode). */
   permissionRestrictions?: PermissionRestrictions
+  /** User-defined permission rules (allow/deny patterns), wired into the runtime PermissionSystem. */
+  permissionRules?: { allow?: string[]; deny?: string[] }
   providers: ProviderConfig[]
   skills?: { paths: string[]; mcpServers: McpServerConfig[] }
   marketplace?: {

package/src/skills/bundled-skill-assets.ts

@@ -10,10 +10,10 @@ export interface BundledSkillAsset {
 
 export const BUNDLED_SKILL_ASSETS: Record<string, BundledSkillAsset[]> = {
   "web-access": [
-    { path: "references/cdp-api.md", content: "# CDP Proxy API 参考\n\n## 基础信息\n\n- 地址：`http://localhost:3456`\n- 启动：`node ~/.claude/skills/web-access/scripts/cdp-proxy.mjs &`\n- 启动后持续运行，不建议主动停止（重启需 Chrome 重新授权）\n- 强制停止：`pkill -f cdp-proxy.mjs`\n\n## API 端点\n\n### GET /health\n\n健康检查，返回连接状态。\n\n```bash\ncurl -s http://localhost:3456/health\n```\n\n### GET /targets\n\n列出所有已打开的页面 tab。返回数组，每项含 `targetId`、`title`、`url`。\n\n```bash\ncurl -s http://localhost:3456/targets\n```\n\n### GET /new?url=URL\n\n创建新后台 tab，自动等待页面加载完成。返回 `{ targetId }`.\n\n```bash\ncurl -s \"http://localhost:3456/new?url=https://example.com\"\n```\n\n### GET /close?target=ID\n\n关闭指定 tab。\n\n```bash\ncurl -s \"http://localhost:3456/close?target=TARGET_ID\"\n```\n\n### GET /navigate?target=ID&url=URL\n\n在已有 tab 中导航到新 URL，自动等待加载。\n\n```bash\ncurl -s \"http://localhost:3456/navigate?target=ID&url=https://example.com\"\n```\n\n### GET /back?target=ID\n\n后退一页。\n\n```bash\ncurl -s \"http://localhost:3456/back?target=ID\"\n```\n\n### GET /info?target=ID\n\n获取页面基础信息（title、url、readyState）。\n\n```bash\ncurl -s \"http://localhost:3456/info?target=ID\"\n```\n\n### POST /eval?target=ID\n\n执行 JavaScript 表达式，POST body 为 JS 代码。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/eval?target=ID\" -d 'document.title'\n```\n\n### POST /click?target=ID\n\nJS 层面点击（`el.click()`），POST body 为 CSS 选择器。自动 scrollIntoView 后点击。简单快速，覆盖大多数场景。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/click?target=ID\" -d 'button.submit'\n```\n\n### POST /clickAt?target=ID\n\nCDP 浏览器级真实鼠标点击（`Input.dispatchMouseEvent`），POST body 为 CSS 选择器。先获取元素坐标，再模拟鼠标按下/释放。算真实用户手势，能触发文件对话框、绕过部分反自动化检测。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/clickAt?target=ID\" -d 'button.upload'\n```\n\n### POST /setFiles?target=ID\n\n给 file input 设置本地文件路径（`DOM.setFileInputFiles`），完全绕过文件对话框。POST body 为 JSON。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/setFiles?target=ID\" -d '{\"selector\":\"input[type=file]\",\"files\":[\"/path/to/file1.png\",\"/path/to/file2.png\"]}'\n```\n\n### GET /scroll?target=ID&y=3000&direction=down\n\n滚动页面。`direction` 可选 `down`（默认）、`up`、`top`、`bottom`。滚动后自动等待 800ms 供懒加载触发。\n\n```bash\ncurl -s \"http://localhost:3456/scroll?target=ID&y=3000\"\ncurl -s \"http://localhost:3456/scroll?target=ID&direction=bottom\"\n```\n\n### GET /screenshot?target=ID&file=/tmp/shot.png\n\n截图。指定 `file` 参数保存到本地文件；不指定则返回图片二进制。可选 `format=jpeg`。\n\n```bash\ncurl -s \"http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png\"\n```\n\n## /eval 使用提示\n\n- POST body 为任意 JS 表达式，返回 `{ value }` 或 `{ error }`\n- 支持 `awaitPromise`：可以写 async 表达式\n- 返回值必须是可序列化的（字符串、数字、对象），DOM 节点不能直接返回，需要提取属性\n- 提取大量数据时用 `JSON.stringify()` 包裹，确保返回字符串\n- 根据页面实际 DOM 结构编写选择器，不要套用固定模板\n\n## 错误处理\n\n| 错误                        | 原因                       | 解决                                                           |\n| --------------------------- | -------------------------- | -------------------------------------------------------------- |\n| `Chrome 未开启远程调试端口` | Chrome 未开启远程调试      | 提示用户打开 `chrome://inspect/#remote-debugging` 并勾选 Allow |\n| `attach 失败`               | targetId 无效或 tab 已关闭 | 用 `/targets` 获取最新列表                                     |\n| `CDP 命令超时`              | 页面长时间未响应           | 重试或检查 tab 状态                                            |\n| `端口已被占用`              | 另一个 proxy 已在运行      | 已有实例可直接复用                                             |\n", mode: 420 },
-    { path: "scripts/cdp-proxy.mjs", content: "#!/usr/bin/env node\n// CDP Proxy - 通过 HTTP API 操控用户日常 Chrome\n// 要求：Chrome 已开启 --remote-debugging-port\n// Node.js 22+（使用原生 WebSocket）\n\nimport http from 'node:http'\nimport { URL } from 'node:url'\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport os from 'node:os'\nimport net from 'node:net'\n\nconst PORT = parseInt(process.env.CDP_PROXY_PORT || '3456')\nlet ws = null\nlet cmdId = 0\nconst pending = new Map() // id -> {resolve, timer}\nconst sessions = new Map() // targetId -> sessionId\nconst managedTabs = new Map() // targetId -> { lastAccessed: number }\nconst TAB_IDLE_TIMEOUT = parseInt(process.env.CDP_TAB_IDLE_TIMEOUT || '900000') // 15 min default\nconst CLEANUP_INTERVAL = 60000 // sweep every 60s\n\n// --- WebSocket 兼容层 ---\nlet WS\nif (typeof globalThis.WebSocket !== 'undefined') {\n  // Node 22+ 原生 WebSocket（浏览器兼容 API）\n  WS = globalThis.WebSocket\n} else {\n  // 回退到 ws 模块\n  try {\n    WS = (await import('ws')).default\n  } catch {\n    console.error('[CDP Proxy] 错误：Node.js 版本 < 22 且未安装 ws 模块')\n    console.error('  解决方案：升级到 Node.js 22+ 或执行 npm install -g ws')\n    process.exit(1)\n  }\n}\n\n// --- 自动发现 Chrome 调试端口 ---\nasync function discoverChromePort() {\n  // 1. 尝试读 DevToolsActivePort 文件\n  const possiblePaths = []\n  const platform = os.platform()\n\n  if (platform === 'darwin') {\n    const home = os.homedir()\n    possiblePaths.push(\n      path.join(home, 'Library/Application Support/Google/Chrome/DevToolsActivePort'),\n      path.join(home, 'Library/Application Support/Google/Chrome Canary/DevToolsActivePort'),\n      path.join(home, 'Library/Application Support/Chromium/DevToolsActivePort'),\n    )\n  } else if (platform === 'linux') {\n    const home = os.homedir()\n    possiblePaths.push(\n      path.join(home, '.config/google-chrome/DevToolsActivePort'),\n      path.join(home, '.config/chromium/DevToolsActivePort'),\n    )\n  } else if (platform === 'win32') {\n    const localAppData = process.env.LOCALAPPDATA || ''\n    possiblePaths.push(\n      path.join(localAppData, 'Google/Chrome/User Data/DevToolsActivePort'),\n      path.join(localAppData, 'Chromium/User Data/DevToolsActivePort'),\n    )\n  }\n\n  for (const p of possiblePaths) {\n    try {\n      const content = fs.readFileSync(p, 'utf-8').trim()\n      const lines = content.split('\\n')\n      const port = parseInt(lines[0])\n      if (port > 0 && port < 65536) {\n        const ok = await checkPort(port)\n        if (ok) {\n          // 第二行是带 UUID 的 WebSocket 路径（如 /devtools/browser/xxx-xxx）\n          // 非显式 --remote-debugging-port 启动时，Chrome 可能只接受此路径\n          const wsPath = lines[1] || null\n          console.log(\n            `[CDP Proxy] 从 DevToolsActivePort 发现端口: ${port}${wsPath ? ' (带 wsPath)' : ''}`,\n          )\n          return { port, wsPath }\n        }\n      }\n    } catch {\n      /* 文件不存在，继续 */\n    }\n  }\n\n  // 2. 扫描常用端口\n  const commonPorts = [9222, 9229, 9333]\n  for (const port of commonPorts) {\n    const ok = await checkPort(port)\n    if (ok) {\n      console.log(`[CDP Proxy] 扫描发现 Chrome 调试端口: ${port}`)\n      return { port, wsPath: null }\n    }\n  }\n\n  return null\n}\n\n// 用 TCP 探测端口是否监听——避免 WebSocket 连接触发 Chrome 安全弹窗\n// （WebSocket 探测会被 Chrome 视为调试连接，弹出授权对话框）\nfunction checkPort(port) {\n  return new Promise((resolve) => {\n    const socket = net.createConnection(port, '127.0.0.1')\n    const timer = setTimeout(() => {\n      socket.destroy()\n      resolve(false)\n    }, 2000)\n    socket.once('connect', () => {\n      clearTimeout(timer)\n      socket.destroy()\n      resolve(true)\n    })\n    socket.once('error', () => {\n      clearTimeout(timer)\n      resolve(false)\n    })\n  })\n}\n\nfunction getWebSocketUrl(port, wsPath) {\n  if (wsPath) return `ws://127.0.0.1:${port}${wsPath}`\n  return `ws://127.0.0.1:${port}/devtools/browser`\n}\n\n// --- WebSocket 连接管理 ---\nlet chromePort = null\nlet chromeWsPath = null\n\nlet connectingPromise = null\nasync function connect() {\n  if (ws && (ws.readyState === WS.OPEN || ws.readyState === 1)) return\n  if (connectingPromise) return connectingPromise // 复用进行中的连接\n\n  if (!chromePort) {\n    const discovered = await discoverChromePort()\n    if (!discovered) {\n      throw new Error(\n        'Chrome 未开启远程调试端口。请用以下方式启动 Chrome：\\n' +\n          '  macOS: /Applications/Google\\\\ Chrome.app/Contents/MacOS/Google\\\\ Chrome --remote-debugging-port=9222\\n' +\n          '  Linux: google-chrome --remote-debugging-port=9222\\n' +\n          '  或在 chrome://flags 中搜索 \"remote debugging\" 并启用',\n      )\n    }\n    chromePort = discovered.port\n    chromeWsPath = discovered.wsPath\n  }\n\n  const wsUrl = getWebSocketUrl(chromePort, chromeWsPath)\n  if (!wsUrl) throw new Error('无法获取 Chrome WebSocket URL')\n\n  return (connectingPromise = new Promise((resolve, reject) => {\n    ws = new WS(wsUrl)\n\n    const onOpen = () => {\n      cleanup()\n      connectingPromise = null\n      console.log(`[CDP Proxy] 已连接 Chrome (端口 ${chromePort})`)\n      resolve()\n    }\n    const onError = (e) => {\n      cleanup()\n      connectingPromise = null\n      ws = null\n      chromePort = null\n      chromeWsPath = null\n      const msg = e.message || e.error?.message || '连接失败'\n      console.error('[CDP Proxy] 连接错误:', msg, '（端口缓存已清除，下次将重新发现）')\n      reject(new Error(msg))\n    }\n    const onClose = () => {\n      console.log('[CDP Proxy] 连接断开')\n      ws = null\n      chromePort = null // 重置端口缓存，下次连接重新发现\n      chromeWsPath = null\n      sessions.clear()\n      managedTabs.clear()\n    }\n    const onMessage = (evt) => {\n      const data = typeof evt === 'string' ? evt : evt.data || evt\n      const msg = JSON.parse(typeof data === 'string' ? data : data.toString())\n\n      if (msg.method === 'Target.attachedToTarget') {\n        const { sessionId, targetInfo } = msg.params\n        sessions.set(targetInfo.targetId, sessionId)\n      }\n      // 拦截页面对 Chrome 调试端口的探测请求（反风控）\n      if (msg.method === 'Fetch.requestPaused') {\n        const { requestId, sessionId: sid } = msg.params\n        sendCDP('Fetch.failRequest', { requestId, errorReason: 'ConnectionRefused' }, sid).catch(\n          () => {},\n        )\n      }\n      if (msg.id && pending.has(msg.id)) {\n        const { resolve, timer } = pending.get(msg.id)\n        clearTimeout(timer)\n        pending.delete(msg.id)\n        resolve(msg)\n      }\n    }\n\n    function cleanup() {\n      ws.removeEventListener?.('open', onOpen)\n      ws.removeEventListener?.('error', onError)\n    }\n\n    // 兼容 Node 原生 WebSocket 和 ws 模块的事件 API\n    if (ws.on) {\n      ws.on('open', onOpen)\n      ws.on('error', onError)\n      ws.on('close', onClose)\n      ws.on('message', onMessage)\n    } else {\n      ws.addEventListener('open', onOpen)\n      ws.addEventListener('error', onError)\n      ws.addEventListener('close', onClose)\n      ws.addEventListener('message', onMessage)\n    }\n  }))\n}\n\nfunction sendCDP(method, params = {}, sessionId = null) {\n  return new Promise((resolve, reject) => {\n    if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) {\n      return reject(new Error('WebSocket 未连接'))\n    }\n    const id = ++cmdId\n    const msg = { id, method, params }\n    if (sessionId) msg.sessionId = sessionId\n    const timer = setTimeout(() => {\n      pending.delete(id)\n      reject(new Error('CDP 命令超时: ' + method))\n    }, 30000)\n    pending.set(id, { resolve, timer })\n    ws.send(JSON.stringify(msg))\n  })\n}\n\n// 已启用端口拦截的 session 集合（避免重复启用）\nconst portGuardedSessions = new Set()\n\nasync function ensureSession(targetId) {\n  if (sessions.has(targetId)) return sessions.get(targetId)\n  const resp = await sendCDP('Target.attachToTarget', { targetId, flatten: true })\n  if (resp.result?.sessionId) {\n    const sid = resp.result.sessionId\n    sessions.set(targetId, sid)\n    // 启用调试端口探测拦截\n    await enablePortGuard(sid)\n    return sid\n  }\n  throw new Error('attach 失败: ' + JSON.stringify(resp.error))\n}\n\n// 拦截页面对 Chrome 调试端口的探测（反风控）\n// 只拦截 127.0.0.1:{chromePort} 的请求，不影响其他任何本地服务\nasync function enablePortGuard(sessionId) {\n  if (!chromePort || portGuardedSessions.has(sessionId)) return\n  try {\n    await sendCDP(\n      'Fetch.enable',\n      {\n        patterns: [\n          { urlPattern: `http://127.0.0.1:${chromePort}/*`, requestStage: 'Request' },\n          { urlPattern: `http://localhost:${chromePort}/*`, requestStage: 'Request' },\n        ],\n      },\n      sessionId,\n    )\n    portGuardedSessions.add(sessionId)\n  } catch {\n    /* Fetch 域启用失败不影响主流程 */\n  }\n}\n\n// --- 闲置 Tab 自动清理 ---\nfunction touchTab(targetId) {\n  const entry = managedTabs.get(targetId)\n  if (entry) entry.lastAccessed = Date.now()\n}\n\nasync function cleanupIdleTabs() {\n  if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) return\n  const now = Date.now()\n  for (const [targetId, info] of managedTabs) {\n    if (now - info.lastAccessed < TAB_IDLE_TIMEOUT) continue\n    try {\n      await sendCDP('Target.closeTarget', { targetId })\n    } catch {\n      /* tab may already be closed */\n    }\n    sessions.delete(targetId)\n    managedTabs.delete(targetId)\n    console.log(`[CDP Proxy] Auto-closed idle tab: ${targetId}`)\n  }\n}\n\nasync function closeAllManagedTabs() {\n  if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) return\n  const targets = [...managedTabs.keys()]\n  for (const targetId of targets) {\n    try {\n      await sendCDP('Target.closeTarget', { targetId })\n    } catch {\n      /* ignore */\n    }\n    sessions.delete(targetId)\n    managedTabs.delete(targetId)\n  }\n  if (targets.length) console.log(`[CDP Proxy] Shutdown: closed ${targets.length} managed tab(s)`)\n}\n\n// --- 等待页面加载 ---\nasync function waitForLoad(sessionId, timeoutMs = 15000) {\n  // 启用 Page 域\n  await sendCDP('Page.enable', {}, sessionId)\n\n  return new Promise((resolve) => {\n    let resolved = false\n    const done = (result) => {\n      if (resolved) return\n      resolved = true\n      clearTimeout(timer)\n      clearInterval(checkInterval)\n      resolve(result)\n    }\n\n    const timer = setTimeout(() => done('timeout'), timeoutMs)\n    const checkInterval = setInterval(async () => {\n      try {\n        const resp = await sendCDP(\n          'Runtime.evaluate',\n          {\n            expression: 'document.readyState',\n            returnByValue: true,\n          },\n          sessionId,\n        )\n        if (resp.result?.result?.value === 'complete') {\n          done('complete')\n        }\n      } catch {\n        /* 忽略 */\n      }\n    }, 500)\n  })\n}\n\n// --- 读取 POST body ---\nasync function readBody(req) {\n  let body = ''\n  for await (const chunk of req) body += chunk\n  return body\n}\n\n// --- HTTP API ---\nconst server = http.createServer(async (req, res) => {\n  const parsed = new URL(req.url, `http://localhost:${PORT}`)\n  const pathname = parsed.pathname\n  const q = Object.fromEntries(parsed.searchParams)\n  if (q.target) touchTab(q.target)\n\n  res.setHeader('Content-Type', 'application/json; charset=utf-8')\n\n  try {\n    // /health 不需要连接 Chrome\n    if (pathname === '/health') {\n      const connected = ws && (ws.readyState === WS.OPEN || ws.readyState === 1)\n      res.end(\n        JSON.stringify({\n          status: 'ok',\n          connected,\n          sessions: sessions.size,\n          managedTabs: managedTabs.size,\n          chromePort,\n        }),\n      )\n      return\n    }\n\n    await connect()\n\n    // GET /targets - 列出所有页面\n    if (pathname === '/targets') {\n      const resp = await sendCDP('Target.getTargets')\n      const pages = resp.result.targetInfos.filter((t) => t.type === 'page')\n      res.end(JSON.stringify(pages, null, 2))\n    }\n\n    // GET /new?url=xxx - 创建新后台 tab\n    else if (pathname === '/new') {\n      const targetUrl = q.url || 'about:blank'\n      const resp = await sendCDP('Target.createTarget', { url: targetUrl, background: true })\n      const targetId = resp.result.targetId\n      managedTabs.set(targetId, { lastAccessed: Date.now() })\n\n      // 等待页面加载\n      if (targetUrl !== 'about:blank') {\n        try {\n          const sid = await ensureSession(targetId)\n          await waitForLoad(sid)\n        } catch {\n          /* 非致命，继续 */\n        }\n      }\n\n      res.end(JSON.stringify({ targetId }))\n    }\n\n    // GET /close?target=xxx - 关闭 tab\n    else if (pathname === '/close') {\n      const resp = await sendCDP('Target.closeTarget', { targetId: q.target })\n      sessions.delete(q.target)\n      managedTabs.delete(q.target)\n      res.end(JSON.stringify(resp.result))\n    }\n\n    // GET /navigate?target=xxx&url=yyy - 导航（自动等待加载）\n    else if (pathname === '/navigate') {\n      const sid = await ensureSession(q.target)\n      const resp = await sendCDP('Page.navigate', { url: q.url }, sid)\n\n      // 等待页面加载完成\n      await waitForLoad(sid)\n\n      res.end(JSON.stringify(resp.result))\n    }\n\n    // GET /back?target=xxx - 后退\n    else if (pathname === '/back') {\n      const sid = await ensureSession(q.target)\n      await sendCDP('Runtime.evaluate', { expression: 'history.back()' }, sid)\n      await waitForLoad(sid)\n      res.end(JSON.stringify({ ok: true }))\n    }\n\n    // POST /eval?target=xxx - 执行 JS\n    else if (pathname === '/eval') {\n      const sid = await ensureSession(q.target)\n      const body = await readBody(req)\n      const expr = body || q.expr || 'document.title'\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: expr,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      if (resp.result?.result?.value !== undefined) {\n        res.end(JSON.stringify({ value: resp.result.result.value }))\n      } else if (resp.result?.exceptionDetails) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: resp.result.exceptionDetails.text }))\n      } else {\n        res.end(JSON.stringify(resp.result))\n      }\n    }\n\n    // POST /click?target=xxx - 点击（body 为 CSS 选择器）\n    // POST /click?target=xxx — JS 层面点击（简单快速，覆盖大多数场景）\n    else if (pathname === '/click') {\n      const sid = await ensureSession(q.target)\n      const selector = await readBody(req)\n      if (!selector) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: 'POST body 需要 CSS 选择器' }))\n        return\n      }\n      const selectorJson = JSON.stringify(selector)\n      const js = `(() => {\n        const el = document.querySelector(${selectorJson});\n        if (!el) return { error: '未找到元素: ' + ${selectorJson} };\n        el.scrollIntoView({ block: 'center' });\n        el.click();\n        return { clicked: true, tag: el.tagName, text: (el.textContent || '').slice(0, 100) };\n      })()`\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      if (resp.result?.result?.value) {\n        const val = resp.result.result.value\n        if (val.error) {\n          res.statusCode = 400\n          res.end(JSON.stringify(val))\n        } else {\n          res.end(JSON.stringify(val))\n        }\n      } else {\n        res.end(JSON.stringify(resp.result))\n      }\n    }\n\n    // POST /clickAt?target=xxx — CDP 浏览器级真实鼠标点击（算用户手势，能触发文件对话框、绕过反自动化检测）\n    else if (pathname === '/clickAt') {\n      const sid = await ensureSession(q.target)\n      const selector = await readBody(req)\n      if (!selector) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: 'POST body 需要 CSS 选择器' }))\n        return\n      }\n      const selectorJson = JSON.stringify(selector)\n      const js = `(() => {\n        const el = document.querySelector(${selectorJson});\n        if (!el) return { error: '未找到元素: ' + ${selectorJson} };\n        el.scrollIntoView({ block: 'center' });\n        const rect = el.getBoundingClientRect();\n        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, tag: el.tagName, text: (el.textContent || '').slice(0, 100) };\n      })()`\n      const coordResp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      const coord = coordResp.result?.result?.value\n      if (!coord || coord.error) {\n        res.statusCode = 400\n        res.end(JSON.stringify(coord || coordResp.result))\n        return\n      }\n      await sendCDP(\n        'Input.dispatchMouseEvent',\n        {\n          type: 'mousePressed',\n          x: coord.x,\n          y: coord.y,\n          button: 'left',\n          clickCount: 1,\n        },\n        sid,\n      )\n      await sendCDP(\n        'Input.dispatchMouseEvent',\n        {\n          type: 'mouseReleased',\n          x: coord.x,\n          y: coord.y,\n          button: 'left',\n          clickCount: 1,\n        },\n        sid,\n      )\n      res.end(\n        JSON.stringify({ clicked: true, x: coord.x, y: coord.y, tag: coord.tag, text: coord.text }),\n      )\n    }\n\n    // POST /setFiles?target=xxx — 给 file input 设置本地文件（绕过文件对话框）\n    // body: JSON { \"selector\": \"input[type=file]\", \"files\": [\"/path/to/file1.png\", \"/path/to/file2.png\"] }\n    else if (pathname === '/setFiles') {\n      const sid = await ensureSession(q.target)\n      const body = JSON.parse(await readBody(req))\n      if (!body.selector || !body.files) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: '需要 selector 和 files 字段' }))\n        return\n      }\n      // 获取 DOM 节点\n      await sendCDP('DOM.enable', {}, sid)\n      const doc = await sendCDP('DOM.getDocument', {}, sid)\n      const node = await sendCDP(\n        'DOM.querySelector',\n        {\n          nodeId: doc.result.root.nodeId,\n          selector: body.selector,\n        },\n        sid,\n      )\n      if (!node.result?.nodeId) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: '未找到元素: ' + body.selector }))\n        return\n      }\n      // 设置文件\n      await sendCDP(\n        'DOM.setFileInputFiles',\n        {\n          nodeId: node.result.nodeId,\n          files: body.files,\n        },\n        sid,\n      )\n      res.end(JSON.stringify({ success: true, files: body.files.length }))\n    }\n\n    // GET /scroll?target=xxx&y=3000 - 滚动\n    else if (pathname === '/scroll') {\n      const sid = await ensureSession(q.target)\n      const y = parseInt(q.y || '3000')\n      const direction = q.direction || 'down' // down | up | top | bottom\n      let js\n      if (direction === 'top') {\n        js = 'window.scrollTo(0, 0); \"scrolled to top\"'\n      } else if (direction === 'bottom') {\n        js = 'window.scrollTo(0, document.body.scrollHeight); \"scrolled to bottom\"'\n      } else if (direction === 'up') {\n        js = `window.scrollBy(0, -${Math.abs(y)}); \"scrolled up ${Math.abs(y)}px\"`\n      } else {\n        js = `window.scrollBy(0, ${Math.abs(y)}); \"scrolled down ${Math.abs(y)}px\"`\n      }\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n        },\n        sid,\n      )\n      // 等待懒加载触发\n      await new Promise((r) => setTimeout(r, 800))\n      res.end(JSON.stringify({ value: resp.result?.result?.value }))\n    }\n\n    // GET /screenshot?target=xxx&file=/tmp/x.png - 截图\n    else if (pathname === '/screenshot') {\n      const sid = await ensureSession(q.target)\n      const format = q.format || 'png'\n      const resp = await sendCDP(\n        'Page.captureScreenshot',\n        {\n          format,\n          quality: format === 'jpeg' ? 80 : undefined,\n        },\n        sid,\n      )\n      if (q.file) {\n        fs.writeFileSync(q.file, Buffer.from(resp.result.data, 'base64'))\n        res.end(JSON.stringify({ saved: q.file }))\n      } else {\n        res.setHeader('Content-Type', 'image/' + format)\n        res.end(Buffer.from(resp.result.data, 'base64'))\n      }\n    }\n\n    // GET /info?target=xxx - 获取页面信息\n    else if (pathname === '/info') {\n      const sid = await ensureSession(q.target)\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression:\n            'JSON.stringify({title: document.title, url: location.href, ready: document.readyState})',\n          returnByValue: true,\n        },\n        sid,\n      )\n      res.end(resp.result?.result?.value || '{}')\n    } else {\n      res.statusCode = 404\n      res.end(\n        JSON.stringify({\n          error: '未知端点',\n          endpoints: {\n            '/health': 'GET - 健康检查',\n            '/targets': 'GET - 列出所有页面 tab',\n            '/new?url=': 'GET - 创建新后台 tab（自动等待加载）',\n            '/close?target=': 'GET - 关闭 tab',\n            '/navigate?target=&url=': 'GET - 导航（自动等待加载）',\n            '/back?target=': 'GET - 后退',\n            '/info?target=': 'GET - 页面标题/URL/状态',\n            '/eval?target=': 'POST body=JS表达式 - 执行 JS',\n            '/click?target=': 'POST body=CSS选择器 - 点击元素',\n            '/scroll?target=&y=&direction=': 'GET - 滚动页面',\n            '/screenshot?target=&file=': 'GET - 截图',\n          },\n        }),\n      )\n    }\n  } catch (e) {\n    res.statusCode = 500\n    res.end(JSON.stringify({ error: e.message }))\n  }\n})\n\n// 检查端口是否被占用\nfunction checkPortAvailable(port) {\n  return new Promise((resolve) => {\n    const s = net.createServer()\n    s.once('error', () => resolve(false))\n    s.once('listening', () => {\n      s.close()\n      resolve(true)\n    })\n    s.listen(port, '127.0.0.1')\n  })\n}\n\nasync function main() {\n  // 检查是否已有 proxy 在运行\n  const available = await checkPortAvailable(PORT)\n  if (!available) {\n    // 验证已有实例是否健康\n    try {\n      const ok = await new Promise((resolve) => {\n        http\n          .get(`http://127.0.0.1:${PORT}/health`, { timeout: 2000 }, (res) => {\n            let d = ''\n            res.on('data', (c) => (d += c))\n            res.on('end', () => resolve(d.includes('\"ok\"')))\n          })\n          .on('error', () => resolve(false))\n      })\n      if (ok) {\n        console.log(`[CDP Proxy] 已有实例运行在端口 ${PORT}，退出`)\n        process.exit(0)\n      }\n    } catch {\n      /* 端口占用但非 proxy，继续报错 */\n    }\n    console.error(`[CDP Proxy] 端口 ${PORT} 已被占用`)\n    process.exit(1)\n  }\n\n  server.listen(PORT, '127.0.0.1', () => {\n    console.log(`[CDP Proxy] 运行在 http://localhost:${PORT}`)\n    // 启动时尝试连接 Chrome（非阻塞）\n    connect().catch((e) =>\n      console.error('[CDP Proxy] 初始连接失败:', e.message, '（将在首次请求时重试）'),\n    )\n  })\n\n  // 定时清理闲置 tab\n  const cleanupTimer = setInterval(cleanupIdleTabs, CLEANUP_INTERVAL)\n  cleanupTimer.unref()\n\n  const shutdown = async (sig) => {\n    console.log(`[CDP Proxy] ${sig}, cleaning up...`)\n    clearInterval(cleanupTimer)\n    await closeAllManagedTabs()\n    process.exit(0)\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n}\n\n// 防止未捕获异常导致进程崩溃\nprocess.on('uncaughtException', (e) => {\n  console.error('[CDP Proxy] 未捕获异常:', e.message)\n})\nprocess.on('unhandledRejection', (e) => {\n  console.error('[CDP Proxy] 未处理拒绝:', e?.message || e)\n})\n\nmain()\n", mode: 493 },
-    { path: "scripts/check-deps.mjs", content: "#!/usr/bin/env node\n// 环境检查 + 确保 CDP Proxy 就绪（跨平台，替代 check-deps.sh）\n\nimport { spawn } from 'node:child_process'\nimport fs from 'node:fs'\nimport net from 'node:net'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')\nconst PROXY_SCRIPT = path.join(ROOT, 'scripts', 'cdp-proxy.mjs')\nconst PROXY_PORT = Number(process.env.CDP_PROXY_PORT || 3456)\n\n// --- Node.js 版本检查 ---\n\nfunction checkNode() {\n  const major = Number(process.versions.node.split('.')[0])\n  const version = `v${process.versions.node}`\n  if (major >= 22) {\n    console.log(`node: ok (${version})`)\n  } else {\n    console.log(`node: warn (${version}, 建议升级到 22+)`)\n  }\n}\n\n// --- TCP 端口探测 ---\n\nfunction checkPort(port, host = '127.0.0.1', timeoutMs = 2000) {\n  return new Promise((resolve) => {\n    const socket = net.createConnection(port, host)\n    const timer = setTimeout(() => {\n      socket.destroy()\n      resolve(false)\n    }, timeoutMs)\n    socket.once('connect', () => {\n      clearTimeout(timer)\n      socket.destroy()\n      resolve(true)\n    })\n    socket.once('error', () => {\n      clearTimeout(timer)\n      resolve(false)\n    })\n  })\n}\n\n// --- Chrome 调试端口检测（DevToolsActivePort 多路径 + 常见端口回退） ---\n\nfunction activePortFiles() {\n  const home = os.homedir()\n  const localAppData = process.env.LOCALAPPDATA || ''\n  switch (os.platform()) {\n    case 'darwin':\n      return [\n        path.join(home, 'Library/Application Support/Google/Chrome/DevToolsActivePort'),\n        path.join(home, 'Library/Application Support/Google/Chrome Canary/DevToolsActivePort'),\n        path.join(home, 'Library/Application Support/Chromium/DevToolsActivePort'),\n      ]\n    case 'linux':\n      return [\n        path.join(home, '.config/google-chrome/DevToolsActivePort'),\n        path.join(home, '.config/chromium/DevToolsActivePort'),\n      ]\n    case 'win32':\n      return [\n        path.join(localAppData, 'Google/Chrome/User Data/DevToolsActivePort'),\n        path.join(localAppData, 'Chromium/User Data/DevToolsActivePort'),\n      ]\n    default:\n      return []\n  }\n}\n\nasync function detectChromePort() {\n  // 优先从 DevToolsActivePort 文件读取\n  for (const filePath of activePortFiles()) {\n    try {\n      const lines = fs.readFileSync(filePath, 'utf8').trim().split(/\\r?\\n/).filter(Boolean)\n      const port = parseInt(lines[0], 10)\n      if (port > 0 && port < 65536 && (await checkPort(port))) {\n        return port\n      }\n    } catch (_) {}\n  }\n  // 回退：探测常见端口\n  for (const port of [9222, 9229, 9333]) {\n    if (await checkPort(port)) {\n      return port\n    }\n  }\n  return null\n}\n\n// --- CDP Proxy 启动与等待 ---\n\nfunction httpGetJson(url, timeoutMs = 3000) {\n  return fetch(url, { signal: AbortSignal.timeout(timeoutMs) })\n    .then(async (res) => {\n      try {\n        return JSON.parse(await res.text())\n      } catch {\n        return null\n      }\n    })\n    .catch(() => null)\n}\n\nfunction startProxyDetached() {\n  const logFile = path.join(os.tmpdir(), 'cdp-proxy.log')\n  const logFd = fs.openSync(logFile, 'a')\n  const child = spawn(process.execPath, [PROXY_SCRIPT], {\n    detached: true,\n    stdio: ['ignore', logFd, logFd],\n    ...(os.platform() === 'win32' ? { windowsHide: true } : {}),\n  })\n  child.unref()\n  fs.closeSync(logFd)\n}\n\nasync function ensureProxy() {\n  const targetsUrl = `http://127.0.0.1:${PROXY_PORT}/targets`\n\n  // /targets 返回 JSON 数组即 ready\n  const targets = await httpGetJson(targetsUrl)\n  if (Array.isArray(targets)) {\n    console.log('proxy: ready')\n    return true\n  }\n\n  // 未运行或未连接，启动并等待\n  console.log('proxy: connecting...')\n  startProxyDetached()\n\n  // 等 proxy 进程就绪\n  await new Promise((r) => setTimeout(r, 2000))\n\n  for (let i = 1; i <= 15; i++) {\n    const result = await httpGetJson(targetsUrl, 8000)\n    if (Array.isArray(result)) {\n      console.log('proxy: ready')\n      return true\n    }\n    if (i === 1) {\n      console.log('⚠️  Chrome 可能有授权弹窗，请点击「允许」后等待连接...')\n    }\n    await new Promise((r) => setTimeout(r, 1000))\n  }\n\n  console.log('❌ 连接超时，请检查 Chrome 调试设置')\n  console.log(`  日志：${path.join(os.tmpdir(), 'cdp-proxy.log')}`)\n  return false\n}\n\n// --- main ---\n\nasync function main() {\n  checkNode()\n\n  const chromePort = await detectChromePort()\n  if (!chromePort) {\n    console.log(\n      'chrome: not connected — 请确保 Chrome 已打开，然后访问 chrome://inspect/#remote-debugging 并勾选 Allow remote debugging',\n    )\n    process.exit(1)\n  }\n  console.log(`chrome: ok (port ${chromePort})`)\n\n  const proxyOk = await ensureProxy()\n  if (!proxyOk) {\n    process.exit(1)\n  }\n\n  // 列出已有站点经验\n  const patternsDir = path.join(ROOT, 'references', 'site-patterns')\n  try {\n    const sites = fs\n      .readdirSync(patternsDir)\n      .filter((f) => f.endsWith('.md'))\n      .map((f) => f.replace(/\\.md$/, ''))\n    if (sites.length) {\n      console.log(`\\nsite-patterns: ${sites.join(', ')}`)\n    }\n  } catch {}\n}\n\nawait main()\n", mode: 420 },
-    { path: "scripts/find-url.mjs", content: "#!/usr/bin/env node\n// find-url - 从本地 Chrome 书签/历史中检索 URL\n// 用于定位公网搜索覆盖不到的目标（组织内部系统、SSO 后台、内网域名等）。\n//\n// 用法：\n//   node find-url.mjs [关键词...] [--only bookmarks|history] [--limit N] [--since 1d|7h|YYYY-MM-DD]\n//\n//   <关键词>            空格分词、多词 AND，匹配 title + url；可省略\n//   --only <source>     限定数据源（bookmarks / history），默认两者都查\n//   --limit N           条数上限，默认 20；0 = 不限\n//   --since <window>    时间窗（仅作用于历史）。1d / 7h / 30m 或 YYYY-MM-DD\n//   --sort recent|visits  历史排序：按最近访问 / 按访问次数，默认 recent\n//\n// 示例：\n//   node find-url.mjs 财务小智\n//   node find-url.mjs agent skills\n//   node find-url.mjs github --since 7d --only history\n//   node find-url.mjs --since 7d --only history --sort visits   # 最近一周高频网站\n//   node find-url.mjs --since 2d --only history --limit 0\n\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport os from 'node:os'\nimport { execFileSync } from 'node:child_process'\n\n// --- 参数解析 -----------------------------------------------------------\nfunction parseArgs(argv) {\n  const a = { keywords: [], only: null, limit: 20, since: null, sort: 'recent' }\n  for (let i = 0; i < argv.length; i++) {\n    const v = argv[i]\n    if (v === '--only') a.only = argv[++i]\n    else if (v === '--limit') a.limit = parseInt(argv[++i], 10)\n    else if (v === '--since') a.since = parseSince(argv[++i])\n    else if (v === '--sort') a.sort = argv[++i]\n    else if (v === '-h' || v === '--help') {\n      printUsage()\n      process.exit(0)\n    } else if (v.startsWith('--')) die(`未知参数: ${v}`)\n    else a.keywords.push(v)\n  }\n  if (a.only && !['bookmarks', 'history'].includes(a.only)) die(`--only 仅支持 bookmarks|history`)\n  if (!['recent', 'visits'].includes(a.sort)) die(`--sort 仅支持 recent|visits`)\n  if (Number.isNaN(a.limit) || a.limit < 0) die('--limit 需为非负整数')\n  return a\n}\n\nfunction parseSince(s) {\n  if (!s) die('--since 需要值')\n  const m = s.match(/^(\\d+)([dhm])$/)\n  if (m) {\n    const n = parseInt(m[1], 10)\n    const ms = { d: 86400000, h: 3600000, m: 60000 }[m[2]]\n    return new Date(Date.now() - n * ms)\n  }\n  const d = new Date(s)\n  if (Number.isNaN(d.getTime())) die(`无效 --since 值: ${s}（用 1d / 7h / 30m / YYYY-MM-DD）`)\n  return d\n}\n\nfunction die(msg) {\n  console.error(msg)\n  process.exit(1)\n}\nfunction printUsage() {\n  console.error(\n    fs\n      .readFileSync(new URL(import.meta.url))\n      .toString()\n      .split('\\n')\n      .slice(1, 19)\n      .map((l) => l.replace(/^\\/\\/ ?/, ''))\n      .join('\\n'),\n  )\n}\n\n// --- Chrome 用户数据目录（跨平台） ---------------------------------------\nfunction getChromeDataDir() {\n  const home = os.homedir()\n  switch (os.platform()) {\n    case 'darwin':\n      return path.join(home, 'Library/Application Support/Google/Chrome')\n    case 'linux':\n      return path.join(home, '.config/google-chrome')\n    case 'win32':\n      return path.join(process.env.LOCALAPPDATA || '', 'Google/Chrome/User Data')\n    default:\n      return null\n  }\n}\n\n// --- Profile 枚举 -------------------------------------------------------\nfunction listProfiles(dataDir) {\n  try {\n    const state = JSON.parse(fs.readFileSync(path.join(dataDir, 'Local State'), 'utf-8'))\n    const info = state?.profile?.info_cache || {}\n    const list = Object.keys(info).map((dir) => ({ dir, name: info[dir].name || dir }))\n    if (list.length) return list\n  } catch {\n    /* 回退 */\n  }\n  return [{ dir: 'Default', name: 'Default' }]\n}\n\n// --- 书签检索 -----------------------------------------------------------\nfunction searchBookmarks(profileDir, profileName, keywords) {\n  const file = path.join(profileDir, 'Bookmarks')\n  if (!fs.existsSync(file)) return []\n  let data\n  try {\n    data = JSON.parse(fs.readFileSync(file, 'utf-8'))\n  } catch {\n    return []\n  }\n  if (!keywords.length) return [] // 书签无时间维度，无关键词不返回\n\n  const needles = keywords.map((k) => k.toLowerCase())\n  const out = []\n  function walk(node, trail) {\n    if (!node) return\n    if (node.type === 'url') {\n      const hay = `${node.name || ''} ${node.url || ''}`.toLowerCase()\n      if (needles.every((n) => hay.includes(n))) {\n        out.push({\n          profile: profileName,\n          name: node.name || '',\n          url: node.url || '',\n          folder: trail.join(' / '),\n        })\n      }\n    }\n    if (Array.isArray(node.children)) {\n      const sub = node.name ? [...trail, node.name] : trail\n      for (const c of node.children) walk(c, sub)\n    }\n  }\n  for (const root of Object.values(data.roots || {})) walk(root, [])\n  return out\n}\n\n// --- 历史检索（SQLite 运行时锁定，需 copy 到 tmp） ------------------------\nconst WEBKIT_EPOCH_DIFF_US = 11644473600000000n // 1601→1970 微秒差\n\nfunction searchHistory(profileDir, profileName, keywords, since, limit, sort) {\n  const src = path.join(profileDir, 'History')\n  if (!fs.existsSync(src)) return []\n  const tmp = path.join(os.tmpdir(), `chrome-history-${process.pid}-${Date.now()}.sqlite`)\n  try {\n    fs.copyFileSync(src, tmp)\n    const conds = ['last_visit_time > 0']\n    for (const kw of keywords) {\n      const esc = kw.toLowerCase().replace(/'/g, \"''\")\n      conds.push(`LOWER(title || ' ' || url) LIKE '%${esc}%'`)\n    }\n    if (since) {\n      const webkitUs = BigInt(since.getTime()) * 1000n + WEBKIT_EPOCH_DIFF_US\n      conds.push(`last_visit_time >= ${webkitUs}`)\n    }\n    const limitClause = limit === 0 ? -1 : limit\n    const orderBy =\n      sort === 'visits' ? 'visit_count DESC, last_visit_time DESC' : 'last_visit_time DESC'\n    const sql = `SELECT title, url,\n      datetime((last_visit_time - 11644473600000000)/1000000, 'unixepoch', 'localtime') AS visit,\n      visit_count\n      FROM urls WHERE ${conds.join(' AND ')}\n      ORDER BY ${orderBy} LIMIT ${limitClause};`\n\n    const raw = execFileSync('sqlite3', ['-separator', '\\t', tmp, sql], {\n      encoding: 'utf-8',\n      maxBuffer: 50 * 1024 * 1024,\n    })\n    return raw\n      .trim()\n      .split('\\n')\n      .filter(Boolean)\n      .map((line) => {\n        const [title, url, visit, visit_count] = line.split('\\t')\n        return { profile: profileName, title, url, visit, visit_count: parseInt(visit_count, 10) }\n      })\n  } catch (e) {\n    if (e.code === 'ENOENT')\n      die(\n        '未找到 sqlite3 命令。macOS/Linux 通常自带；Windows 可用 `winget install sqlite.sqlite` 或从 https://sqlite.org/download.html 下载后加入 PATH。',\n      )\n    return []\n  } finally {\n    try {\n      fs.unlinkSync(tmp)\n    } catch {}\n  }\n}\n\n// --- 输出格式化 ---------------------------------------------------------\n// 用 `|` 作字段分隔符；字段内含 `|` 的替换成 `│`（全宽竖线）避免歧义\nconst clean = (s) =>\n  String(s ?? '')\n    .replaceAll('|', '│')\n    .trim()\n\nfunction printBookmarks(items, multiProfile) {\n  console.log(`[书签] ${items.length} 条`)\n  for (const b of items) {\n    const segs = [clean(b.name) || '(无标题)', clean(b.url)]\n    if (b.folder) segs.push(clean(b.folder))\n    if (multiProfile) segs.push('@' + clean(b.profile))\n    console.log('  ' + segs.join(' | '))\n  }\n}\n\nfunction printHistory(items, multiProfile, sortLabel) {\n  console.log(`[历史] ${items.length} 条（${sortLabel}）`)\n  for (const h of items) {\n    const segs = [clean(h.title) || '(无标题)', clean(h.url), h.visit]\n    if (h.visit_count > 1) segs.push(`visits=${h.visit_count}`)\n    if (multiProfile) segs.push('@' + clean(h.profile))\n    console.log('  ' + segs.join(' | '))\n  }\n}\n\n// --- main ---------------------------------------------------------------\nconst args = parseArgs(process.argv.slice(2))\n\nconst dataDir = getChromeDataDir()\nif (!dataDir || !fs.existsSync(dataDir)) die('未找到 Chrome 用户数据目录')\n\nconst profiles = listProfiles(dataDir)\nconst doBookmarks = args.only !== 'history'\nconst doHistory = args.only !== 'bookmarks'\n\nconst bookmarks = []\nconst history = []\nfor (const p of profiles) {\n  const pDir = path.join(dataDir, p.dir)\n  if (!fs.existsSync(pDir)) continue\n  if (doBookmarks) bookmarks.push(...searchBookmarks(pDir, p.name, args.keywords))\n  if (doHistory)\n    history.push(\n      ...searchHistory(\n        pDir,\n        p.name,\n        args.keywords,\n        args.since,\n        args.limit === 0 ? 0 : args.limit * 2,\n        args.sort,\n      ),\n    )\n}\n\n// 历史跨 profile 合并后按指定 sort 重排 + 切顶\nif (args.sort === 'visits') {\n  history.sort(\n    (a, b) =>\n      (b.visit_count || 0) - (a.visit_count || 0) || (b.visit || '').localeCompare(a.visit || ''),\n  )\n} else {\n  history.sort((a, b) => (b.visit || '').localeCompare(a.visit || ''))\n}\nconst bookmarksOut = args.limit === 0 ? bookmarks : bookmarks.slice(0, args.limit)\nconst historyOut = args.limit === 0 ? history : history.slice(0, args.limit)\n\n// 仅当结果真的横跨多个 profile 时，才输出 @profile 标注（空 profile 不算）\nconst seenProfiles = new Set([...bookmarksOut, ...historyOut].map((x) => x.profile))\nconst showProfile = seenProfiles.size > 1\n\nconst sortLabel = args.sort === 'visits' ? '按访问次数' : '按最近访问'\nif (doBookmarks) printBookmarks(bookmarksOut, showProfile)\nif (doBookmarks && doHistory) console.log()\nif (doHistory) printHistory(historyOut, showProfile, sortLabel)\n\nif (!args.keywords.length && doBookmarks && !doHistory) {\n  console.error('\\n提示：书签无时间维度，无关键词查询无意义。加关键词或切换 --only history。')\n}\n", mode: 420 },
-    { path: "scripts/match-site.mjs", content: "#!/usr/bin/env node\n// 根据用户输入匹配站点经验文件（跨平台，替代 match-site.sh）\n// 用法：node match-site.mjs \"用户输入文本\"\n// 输出：匹配到的站点经验内容，无匹配则静默\n\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')\nconst PATTERNS_DIR = path.join(ROOT, 'references', 'site-patterns')\nconst query = (process.argv[2] || '').trim()\n\nif (!query || !fs.existsSync(PATTERNS_DIR)) {\n  process.exit(0)\n}\n\nfor (const entry of fs.readdirSync(PATTERNS_DIR, { withFileTypes: true })) {\n  if (!entry.isFile() || !entry.name.endsWith('.md')) continue\n\n  const domain = entry.name.replace(/\\.md$/, '')\n  const raw = fs.readFileSync(path.join(PATTERNS_DIR, entry.name), 'utf8')\n\n  // 提取 aliases\n  const aliasesLine = raw.split(/\\r?\\n/).find((l) => l.startsWith('aliases:')) || ''\n  const aliases = aliasesLine\n    .replace(/^aliases:\\s*/, '')\n    .replace(/^\\[/, '')\n    .replace(/\\]$/, '')\n    .split(',')\n    .map((v) => v.trim())\n    .filter(Boolean)\n\n  // 构建匹配模式\n  const escaped = (t) => t.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n  const pattern = [domain, ...aliases].map(escaped).join('|')\n  if (!new RegExp(pattern, 'i').test(query)) continue\n\n  // 跳过 frontmatter，输出正文\n  const fences = [...raw.matchAll(/^---\\s*$/gm)]\n  const body =\n    fences.length >= 2\n      ? raw.slice(fences[1].index + fences[1][0].length).replace(/^\\r?\\n/, '')\n      : raw\n\n  process.stdout.write(`--- 站点经验: ${domain} ---\\n`)\n  process.stdout.write(body.trimEnd() + '\\n\\n')\n}\n", mode: 420 },
+    { path: "references/cdp-api.md", content: "# CDP Proxy API 参考\n\n## 基础信息\n\n- 地址：`http://localhost:3456`\n- 启动：`node ~/.mipham/skills/web-access/scripts/cdp-proxy.mjs &`\n- 启动后持续运行，不建议主动停止（重启需 Chrome 重新授权）\n- 强制停止：`pkill -f cdp-proxy.mjs`\n- 鉴权：除 `/health` 外，所有端点要求请求头 `X-CDP-Token`，值 = `~/.mipham/skills/web-access/.cdp-token` 的内容（下方示例省略此头）\n\n## API 端点\n\n### GET /health\n\n健康检查，返回连接状态。\n\n```bash\ncurl -s http://localhost:3456/health\n```\n\n### GET /targets\n\n列出所有已打开的页面 tab。返回数组，每项含 `targetId`、`title`、`url`。\n\n```bash\ncurl -s http://localhost:3456/targets\n```\n\n### GET /new?url=URL\n\n创建新后台 tab，自动等待页面加载完成。返回 `{ targetId }`.\n\n```bash\ncurl -s \"http://localhost:3456/new?url=https://example.com\"\n```\n\n### GET /close?target=ID\n\n关闭指定 tab。\n\n```bash\ncurl -s \"http://localhost:3456/close?target=TARGET_ID\"\n```\n\n### GET /navigate?target=ID&url=URL\n\n在已有 tab 中导航到新 URL，自动等待加载。\n\n```bash\ncurl -s \"http://localhost:3456/navigate?target=ID&url=https://example.com\"\n```\n\n### GET /back?target=ID\n\n后退一页。\n\n```bash\ncurl -s \"http://localhost:3456/back?target=ID\"\n```\n\n### GET /info?target=ID\n\n获取页面基础信息（title、url、readyState）。\n\n```bash\ncurl -s \"http://localhost:3456/info?target=ID\"\n```\n\n### POST /eval?target=ID\n\n执行 JavaScript 表达式，POST body 为 JS 代码。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/eval?target=ID\" -d 'document.title'\n```\n\n### POST /click?target=ID\n\nJS 层面点击（`el.click()`），POST body 为 CSS 选择器。自动 scrollIntoView 后点击。简单快速，覆盖大多数场景。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/click?target=ID\" -d 'button.submit'\n```\n\n### POST /clickAt?target=ID\n\nCDP 浏览器级真实鼠标点击（`Input.dispatchMouseEvent`），POST body 为 CSS 选择器。先获取元素坐标，再模拟鼠标按下/释放。算真实用户手势，能触发文件对话框、绕过部分反自动化检测。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/clickAt?target=ID\" -d 'button.upload'\n```\n\n### POST /setFiles?target=ID\n\n给 file input 设置本地文件路径（`DOM.setFileInputFiles`），完全绕过文件对话框。POST body 为 JSON。\n\n```bash\ncurl -s -X POST \"http://localhost:3456/setFiles?target=ID\" -d '{\"selector\":\"input[type=file]\",\"files\":[\"/path/to/file1.png\",\"/path/to/file2.png\"]}'\n```\n\n### GET /scroll?target=ID&y=3000&direction=down\n\n滚动页面。`direction` 可选 `down`（默认）、`up`、`top`、`bottom`。滚动后自动等待 800ms 供懒加载触发。\n\n```bash\ncurl -s \"http://localhost:3456/scroll?target=ID&y=3000\"\ncurl -s \"http://localhost:3456/scroll?target=ID&direction=bottom\"\n```\n\n### GET /screenshot?target=ID&file=/tmp/shot.png\n\n截图。指定 `file` 参数保存到本地文件；不指定则返回图片二进制。可选 `format=jpeg`。\n\n```bash\ncurl -s \"http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png\"\n```\n\n## /eval 使用提示\n\n- POST body 为任意 JS 表达式，返回 `{ value }` 或 `{ error }`\n- 支持 `awaitPromise`：可以写 async 表达式\n- 返回值必须是可序列化的（字符串、数字、对象），DOM 节点不能直接返回，需要提取属性\n- 提取大量数据时用 `JSON.stringify()` 包裹，确保返回字符串\n- 根据页面实际 DOM 结构编写选择器，不要套用固定模板\n\n## 错误处理\n\n| 错误                        | 原因                       | 解决                                                           |\n| --------------------------- | -------------------------- | -------------------------------------------------------------- |\n| `Chrome 未开启远程调试端口` | Chrome 未开启远程调试      | 提示用户打开 `chrome://inspect/#remote-debugging` 并勾选 Allow |\n| `attach 失败`               | targetId 无效或 tab 已关闭 | 用 `/targets` 获取最新列表                                     |\n| `CDP 命令超时`              | 页面长时间未响应           | 重试或检查 tab 状态                                            |\n| `端口已被占用`              | 另一个 proxy 已在运行      | 已有实例可直接复用                                             |\n", mode: 420 },
+    { path: "scripts/cdp-proxy.mjs", content: "#!/usr/bin/env node\n// CDP Proxy - 通过 HTTP API 操控用户日常 Chrome\n// 要求：Chrome 已开启 --remote-debugging-port\n// Node.js 22+（使用原生 WebSocket）\n\nimport http from 'node:http'\nimport { URL, fileURLToPath } from 'node:url'\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport os from 'node:os'\nimport net from 'node:net'\nimport crypto from 'node:crypto'\n\nconst PORT = parseInt(process.env.CDP_PROXY_PORT || '3456')\nlet ws = null\nlet cmdId = 0\nconst pending = new Map() // id -> {resolve, timer}\nconst sessions = new Map() // targetId -> sessionId\nconst managedTabs = new Map() // targetId -> { lastAccessed: number }\nconst TAB_IDLE_TIMEOUT = parseInt(process.env.CDP_TAB_IDLE_TIMEOUT || '900000') // 15 min default\nconst CLEANUP_INTERVAL = 60000 // sweep every 60s\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')\nconst TOKEN_FILE = path.join(ROOT, '.cdp-token')\n\n// --- 共享密钥鉴权 ---\n// 防御浏览器 CSRF 到 localhost：恶意网页能 fetch 127.0.0.1:3456，但读不到本文件。\nlet authToken = null\nfunction readToken() {\n  try {\n    const t = fs.readFileSync(TOKEN_FILE, 'utf-8').trim()\n    if (t) return t\n  } catch {\n    /* 尚未生成 */\n  }\n  return null\n}\nfunction ensureToken() {\n  const existing = readToken()\n  if (existing) {\n    authToken = existing\n    return existing\n  }\n  authToken = crypto.randomBytes(32).toString('hex')\n  try {\n    fs.writeFileSync(TOKEN_FILE, authToken, { mode: 0o600 })\n  } catch {\n    /* 无写权限时仅内存持有，进程存活期内仍可鉴权 */\n  }\n  return authToken\n}\n\n// --- 窄 SSRF 防护 ---\n// 本工具用途即访问组织内网（SSO 后台/内部系统），故不做私有网段全量屏蔽；\n// 仅挡云元数据端点与非 http(s)/about 协议。完整 rebinding 防护见 src/security/url.ts。\nfunction validateNavUrl(rawUrl) {\n  let u\n  try {\n    u = new URL(rawUrl)\n  } catch {\n    return { ok: false, reason: 'invalid URL' }\n  }\n  if (u.protocol !== 'http:' && u.protocol !== 'https:' && u.protocol !== 'about:') {\n    return { ok: false, reason: `unsupported protocol: ${u.protocol}` }\n  }\n  const host = u.hostname.toLowerCase()\n  if (host === '169.254.169.254' || host === 'metadata.google.internal') {\n    return { ok: false, reason: 'blocked: cloud metadata endpoint' }\n  }\n  return { ok: true }\n}\n\n// --- WebSocket 兼容层 ---\nlet WS\nif (typeof globalThis.WebSocket !== 'undefined') {\n  // Node 22+ 原生 WebSocket（浏览器兼容 API）\n  WS = globalThis.WebSocket\n} else {\n  // 回退到 ws 模块\n  try {\n    WS = (await import('ws')).default\n  } catch {\n    console.error('[CDP Proxy] 错误：Node.js 版本 < 22 且未安装 ws 模块')\n    console.error('  解决方案：升级到 Node.js 22+ 或执行 npm install -g ws')\n    process.exit(1)\n  }\n}\n\n// --- 自动发现 Chrome 调试端口 ---\nasync function discoverChromePort() {\n  // 1. 尝试读 DevToolsActivePort 文件\n  const possiblePaths = []\n  const platform = os.platform()\n\n  if (platform === 'darwin') {\n    const home = os.homedir()\n    possiblePaths.push(\n      path.join(home, 'Library/Application Support/Google/Chrome/DevToolsActivePort'),\n      path.join(home, 'Library/Application Support/Google/Chrome Canary/DevToolsActivePort'),\n      path.join(home, 'Library/Application Support/Chromium/DevToolsActivePort'),\n    )\n  } else if (platform === 'linux') {\n    const home = os.homedir()\n    possiblePaths.push(\n      path.join(home, '.config/google-chrome/DevToolsActivePort'),\n      path.join(home, '.config/chromium/DevToolsActivePort'),\n    )\n  } else if (platform === 'win32') {\n    const localAppData = process.env.LOCALAPPDATA || ''\n    possiblePaths.push(\n      path.join(localAppData, 'Google/Chrome/User Data/DevToolsActivePort'),\n      path.join(localAppData, 'Chromium/User Data/DevToolsActivePort'),\n    )\n  }\n\n  for (const p of possiblePaths) {\n    try {\n      const content = fs.readFileSync(p, 'utf-8').trim()\n      const lines = content.split('\\n')\n      const port = parseInt(lines[0])\n      if (port > 0 && port < 65536) {\n        const ok = await checkPort(port)\n        if (ok) {\n          // 第二行是带 UUID 的 WebSocket 路径（如 /devtools/browser/xxx-xxx）\n          // 非显式 --remote-debugging-port 启动时，Chrome 可能只接受此路径\n          const wsPath = lines[1] || null\n          console.log(\n            `[CDP Proxy] 从 DevToolsActivePort 发现端口: ${port}${wsPath ? ' (带 wsPath)' : ''}`,\n          )\n          return { port, wsPath }\n        }\n      }\n    } catch {\n      /* 文件不存在，继续 */\n    }\n  }\n\n  // 2. 扫描常用端口\n  const commonPorts = [9222, 9229, 9333]\n  for (const port of commonPorts) {\n    const ok = await checkPort(port)\n    if (ok) {\n      console.log(`[CDP Proxy] 扫描发现 Chrome 调试端口: ${port}`)\n      return { port, wsPath: null }\n    }\n  }\n\n  return null\n}\n\n// 用 TCP 探测端口是否监听——避免 WebSocket 连接触发 Chrome 安全弹窗\n// （WebSocket 探测会被 Chrome 视为调试连接，弹出授权对话框）\nfunction checkPort(port) {\n  return new Promise((resolve) => {\n    const socket = net.createConnection(port, '127.0.0.1')\n    const timer = setTimeout(() => {\n      socket.destroy()\n      resolve(false)\n    }, 2000)\n    socket.once('connect', () => {\n      clearTimeout(timer)\n      socket.destroy()\n      resolve(true)\n    })\n    socket.once('error', () => {\n      clearTimeout(timer)\n      resolve(false)\n    })\n  })\n}\n\nfunction getWebSocketUrl(port, wsPath) {\n  if (wsPath) return `ws://127.0.0.1:${port}${wsPath}`\n  return `ws://127.0.0.1:${port}/devtools/browser`\n}\n\n// --- WebSocket 连接管理 ---\nlet chromePort = null\nlet chromeWsPath = null\n\nlet connectingPromise = null\nasync function connect() {\n  if (ws && (ws.readyState === WS.OPEN || ws.readyState === 1)) return\n  if (connectingPromise) return connectingPromise // 复用进行中的连接\n\n  if (!chromePort) {\n    const discovered = await discoverChromePort()\n    if (!discovered) {\n      throw new Error(\n        'Chrome 未开启远程调试端口。请用以下方式启动 Chrome：\\n' +\n          '  macOS: /Applications/Google\\\\ Chrome.app/Contents/MacOS/Google\\\\ Chrome --remote-debugging-port=9222\\n' +\n          '  Linux: google-chrome --remote-debugging-port=9222\\n' +\n          '  或在 chrome://flags 中搜索 \"remote debugging\" 并启用',\n      )\n    }\n    chromePort = discovered.port\n    chromeWsPath = discovered.wsPath\n  }\n\n  const wsUrl = getWebSocketUrl(chromePort, chromeWsPath)\n  if (!wsUrl) throw new Error('无法获取 Chrome WebSocket URL')\n\n  return (connectingPromise = new Promise((resolve, reject) => {\n    ws = new WS(wsUrl)\n\n    const onOpen = () => {\n      cleanup()\n      connectingPromise = null\n      console.log(`[CDP Proxy] 已连接 Chrome (端口 ${chromePort})`)\n      resolve()\n    }\n    const onError = (e) => {\n      cleanup()\n      connectingPromise = null\n      ws = null\n      chromePort = null\n      chromeWsPath = null\n      const msg = e.message || e.error?.message || '连接失败'\n      console.error('[CDP Proxy] 连接错误:', msg, '（端口缓存已清除，下次将重新发现）')\n      reject(new Error(msg))\n    }\n    const onClose = () => {\n      console.log('[CDP Proxy] 连接断开')\n      ws = null\n      chromePort = null // 重置端口缓存，下次连接重新发现\n      chromeWsPath = null\n      sessions.clear()\n      managedTabs.clear()\n    }\n    const onMessage = (evt) => {\n      const data = typeof evt === 'string' ? evt : evt.data || evt\n      const msg = JSON.parse(typeof data === 'string' ? data : data.toString())\n\n      if (msg.method === 'Target.attachedToTarget') {\n        const { sessionId, targetInfo } = msg.params\n        sessions.set(targetInfo.targetId, sessionId)\n      }\n      // 拦截页面对 Chrome 调试端口的探测请求（反风控）\n      if (msg.method === 'Fetch.requestPaused') {\n        const { requestId, sessionId: sid } = msg.params\n        sendCDP('Fetch.failRequest', { requestId, errorReason: 'ConnectionRefused' }, sid).catch(\n          () => {},\n        )\n      }\n      if (msg.id && pending.has(msg.id)) {\n        const { resolve, timer } = pending.get(msg.id)\n        clearTimeout(timer)\n        pending.delete(msg.id)\n        resolve(msg)\n      }\n    }\n\n    function cleanup() {\n      ws.removeEventListener?.('open', onOpen)\n      ws.removeEventListener?.('error', onError)\n    }\n\n    // 兼容 Node 原生 WebSocket 和 ws 模块的事件 API\n    if (ws.on) {\n      ws.on('open', onOpen)\n      ws.on('error', onError)\n      ws.on('close', onClose)\n      ws.on('message', onMessage)\n    } else {\n      ws.addEventListener('open', onOpen)\n      ws.addEventListener('error', onError)\n      ws.addEventListener('close', onClose)\n      ws.addEventListener('message', onMessage)\n    }\n  }))\n}\n\nfunction sendCDP(method, params = {}, sessionId = null) {\n  return new Promise((resolve, reject) => {\n    if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) {\n      return reject(new Error('WebSocket 未连接'))\n    }\n    const id = ++cmdId\n    const msg = { id, method, params }\n    if (sessionId) msg.sessionId = sessionId\n    const timer = setTimeout(() => {\n      pending.delete(id)\n      reject(new Error('CDP 命令超时: ' + method))\n    }, 30000)\n    pending.set(id, { resolve, timer })\n    ws.send(JSON.stringify(msg))\n  })\n}\n\n// 已启用端口拦截的 session 集合（避免重复启用）\nconst portGuardedSessions = new Set()\n\nasync function ensureSession(targetId) {\n  if (sessions.has(targetId)) return sessions.get(targetId)\n  const resp = await sendCDP('Target.attachToTarget', { targetId, flatten: true })\n  if (resp.result?.sessionId) {\n    const sid = resp.result.sessionId\n    sessions.set(targetId, sid)\n    // 启用调试端口探测拦截\n    await enablePortGuard(sid)\n    return sid\n  }\n  throw new Error('attach 失败: ' + JSON.stringify(resp.error))\n}\n\n// 拦截页面对 Chrome 调试端口的探测（反风控）\n// 只拦截 127.0.0.1:{chromePort} 的请求，不影响其他任何本地服务\nasync function enablePortGuard(sessionId) {\n  if (!chromePort || portGuardedSessions.has(sessionId)) return\n  try {\n    await sendCDP(\n      'Fetch.enable',\n      {\n        patterns: [\n          { urlPattern: `http://127.0.0.1:${chromePort}/*`, requestStage: 'Request' },\n          { urlPattern: `http://localhost:${chromePort}/*`, requestStage: 'Request' },\n        ],\n      },\n      sessionId,\n    )\n    portGuardedSessions.add(sessionId)\n  } catch {\n    /* Fetch 域启用失败不影响主流程 */\n  }\n}\n\n// --- 闲置 Tab 自动清理 ---\nfunction touchTab(targetId) {\n  const entry = managedTabs.get(targetId)\n  if (entry) entry.lastAccessed = Date.now()\n}\n\nasync function cleanupIdleTabs() {\n  if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) return\n  const now = Date.now()\n  for (const [targetId, info] of managedTabs) {\n    if (now - info.lastAccessed < TAB_IDLE_TIMEOUT) continue\n    try {\n      await sendCDP('Target.closeTarget', { targetId })\n    } catch {\n      /* tab may already be closed */\n    }\n    sessions.delete(targetId)\n    managedTabs.delete(targetId)\n    console.log(`[CDP Proxy] Auto-closed idle tab: ${targetId}`)\n  }\n}\n\nasync function closeAllManagedTabs() {\n  if (!ws || (ws.readyState !== WS.OPEN && ws.readyState !== 1)) return\n  const targets = [...managedTabs.keys()]\n  for (const targetId of targets) {\n    try {\n      await sendCDP('Target.closeTarget', { targetId })\n    } catch {\n      /* ignore */\n    }\n    sessions.delete(targetId)\n    managedTabs.delete(targetId)\n  }\n  if (targets.length) console.log(`[CDP Proxy] Shutdown: closed ${targets.length} managed tab(s)`)\n}\n\n// --- 等待页面加载 ---\nasync function waitForLoad(sessionId, timeoutMs = 15000) {\n  // 启用 Page 域\n  await sendCDP('Page.enable', {}, sessionId)\n\n  return new Promise((resolve) => {\n    let resolved = false\n    const done = (result) => {\n      if (resolved) return\n      resolved = true\n      clearTimeout(timer)\n      clearInterval(checkInterval)\n      resolve(result)\n    }\n\n    const timer = setTimeout(() => done('timeout'), timeoutMs)\n    const checkInterval = setInterval(async () => {\n      try {\n        const resp = await sendCDP(\n          'Runtime.evaluate',\n          {\n            expression: 'document.readyState',\n            returnByValue: true,\n          },\n          sessionId,\n        )\n        if (resp.result?.result?.value === 'complete') {\n          done('complete')\n        }\n      } catch {\n        /* 忽略 */\n      }\n    }, 500)\n  })\n}\n\n// --- 读取 POST body ---\nasync function readBody(req) {\n  let body = ''\n  for await (const chunk of req) body += chunk\n  return body\n}\n\n// --- HTTP API ---\nconst server = http.createServer(async (req, res) => {\n  const parsed = new URL(req.url, `http://localhost:${PORT}`)\n  const pathname = parsed.pathname\n  const q = Object.fromEntries(parsed.searchParams)\n  if (q.target) touchTab(q.target)\n\n  res.setHeader('Content-Type', 'application/json; charset=utf-8')\n\n  try {\n    // /health 不需要连接 Chrome\n    if (pathname === '/health') {\n      const connected = ws && (ws.readyState === WS.OPEN || ws.readyState === 1)\n      res.end(\n        JSON.stringify({\n          status: 'ok',\n          connected,\n          sessions: sessions.size,\n          managedTabs: managedTabs.size,\n          chromePort,\n        }),\n      )\n      return\n    }\n\n    // 鉴权：非 /health 端点要求 X-CDP-Token（防浏览器 CSRF 到 localhost）\n    const provided = req.headers['x-cdp-token'] || ''\n    if (!authToken || provided !== authToken) {\n      res.statusCode = 401\n      res.end(JSON.stringify({ error: 'unauthorized: missing or invalid X-CDP-Token' }))\n      return\n    }\n\n    await connect()\n\n    // GET /targets - 列出所有页面\n    if (pathname === '/targets') {\n      const resp = await sendCDP('Target.getTargets')\n      const pages = resp.result.targetInfos.filter((t) => t.type === 'page')\n      res.end(JSON.stringify(pages, null, 2))\n    }\n\n    // GET /new?url=xxx - 创建新后台 tab\n    else if (pathname === '/new') {\n      const targetUrl = q.url || 'about:blank'\n      const check = validateNavUrl(targetUrl)\n      if (!check.ok) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: check.reason }))\n        return\n      }\n      const resp = await sendCDP('Target.createTarget', { url: targetUrl, background: true })\n      const targetId = resp.result.targetId\n      managedTabs.set(targetId, { lastAccessed: Date.now() })\n\n      // 等待页面加载\n      if (targetUrl !== 'about:blank') {\n        try {\n          const sid = await ensureSession(targetId)\n          await waitForLoad(sid)\n        } catch {\n          /* 非致命，继续 */\n        }\n      }\n\n      res.end(JSON.stringify({ targetId }))\n    }\n\n    // GET /close?target=xxx - 关闭 tab\n    else if (pathname === '/close') {\n      const resp = await sendCDP('Target.closeTarget', { targetId: q.target })\n      sessions.delete(q.target)\n      managedTabs.delete(q.target)\n      res.end(JSON.stringify(resp.result))\n    }\n\n    // GET /navigate?target=xxx&url=yyy - 导航（自动等待加载）\n    else if (pathname === '/navigate') {\n      const check = validateNavUrl(q.url || '')\n      if (!check.ok) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: check.reason }))\n        return\n      }\n      const sid = await ensureSession(q.target)\n      const resp = await sendCDP('Page.navigate', { url: q.url }, sid)\n\n      // 等待页面加载完成\n      await waitForLoad(sid)\n\n      res.end(JSON.stringify(resp.result))\n    }\n\n    // GET /back?target=xxx - 后退\n    else if (pathname === '/back') {\n      const sid = await ensureSession(q.target)\n      await sendCDP('Runtime.evaluate', { expression: 'history.back()' }, sid)\n      await waitForLoad(sid)\n      res.end(JSON.stringify({ ok: true }))\n    }\n\n    // POST /eval?target=xxx - 执行 JS\n    else if (pathname === '/eval') {\n      const sid = await ensureSession(q.target)\n      const body = await readBody(req)\n      const expr = body || q.expr || 'document.title'\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: expr,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      if (resp.result?.result?.value !== undefined) {\n        res.end(JSON.stringify({ value: resp.result.result.value }))\n      } else if (resp.result?.exceptionDetails) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: resp.result.exceptionDetails.text }))\n      } else {\n        res.end(JSON.stringify(resp.result))\n      }\n    }\n\n    // POST /click?target=xxx - 点击（body 为 CSS 选择器）\n    // POST /click?target=xxx — JS 层面点击（简单快速，覆盖大多数场景）\n    else if (pathname === '/click') {\n      const sid = await ensureSession(q.target)\n      const selector = await readBody(req)\n      if (!selector) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: 'POST body 需要 CSS 选择器' }))\n        return\n      }\n      const selectorJson = JSON.stringify(selector)\n      const js = `(() => {\n        const el = document.querySelector(${selectorJson});\n        if (!el) return { error: '未找到元素: ' + ${selectorJson} };\n        el.scrollIntoView({ block: 'center' });\n        el.click();\n        return { clicked: true, tag: el.tagName, text: (el.textContent || '').slice(0, 100) };\n      })()`\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      if (resp.result?.result?.value) {\n        const val = resp.result.result.value\n        if (val.error) {\n          res.statusCode = 400\n          res.end(JSON.stringify(val))\n        } else {\n          res.end(JSON.stringify(val))\n        }\n      } else {\n        res.end(JSON.stringify(resp.result))\n      }\n    }\n\n    // POST /clickAt?target=xxx — CDP 浏览器级真实鼠标点击（算用户手势，能触发文件对话框、绕过反自动化检测）\n    else if (pathname === '/clickAt') {\n      const sid = await ensureSession(q.target)\n      const selector = await readBody(req)\n      if (!selector) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: 'POST body 需要 CSS 选择器' }))\n        return\n      }\n      const selectorJson = JSON.stringify(selector)\n      const js = `(() => {\n        const el = document.querySelector(${selectorJson});\n        if (!el) return { error: '未找到元素: ' + ${selectorJson} };\n        el.scrollIntoView({ block: 'center' });\n        const rect = el.getBoundingClientRect();\n        return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, tag: el.tagName, text: (el.textContent || '').slice(0, 100) };\n      })()`\n      const coordResp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n        sid,\n      )\n      const coord = coordResp.result?.result?.value\n      if (!coord || coord.error) {\n        res.statusCode = 400\n        res.end(JSON.stringify(coord || coordResp.result))\n        return\n      }\n      await sendCDP(\n        'Input.dispatchMouseEvent',\n        {\n          type: 'mousePressed',\n          x: coord.x,\n          y: coord.y,\n          button: 'left',\n          clickCount: 1,\n        },\n        sid,\n      )\n      await sendCDP(\n        'Input.dispatchMouseEvent',\n        {\n          type: 'mouseReleased',\n          x: coord.x,\n          y: coord.y,\n          button: 'left',\n          clickCount: 1,\n        },\n        sid,\n      )\n      res.end(\n        JSON.stringify({ clicked: true, x: coord.x, y: coord.y, tag: coord.tag, text: coord.text }),\n      )\n    }\n\n    // POST /setFiles?target=xxx — 给 file input 设置本地文件（绕过文件对话框）\n    // body: JSON { \"selector\": \"input[type=file]\", \"files\": [\"/path/to/file1.png\", \"/path/to/file2.png\"] }\n    else if (pathname === '/setFiles') {\n      const sid = await ensureSession(q.target)\n      const body = JSON.parse(await readBody(req))\n      if (!body.selector || !body.files) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: '需要 selector 和 files 字段' }))\n        return\n      }\n      // 获取 DOM 节点\n      await sendCDP('DOM.enable', {}, sid)\n      const doc = await sendCDP('DOM.getDocument', {}, sid)\n      const node = await sendCDP(\n        'DOM.querySelector',\n        {\n          nodeId: doc.result.root.nodeId,\n          selector: body.selector,\n        },\n        sid,\n      )\n      if (!node.result?.nodeId) {\n        res.statusCode = 400\n        res.end(JSON.stringify({ error: '未找到元素: ' + body.selector }))\n        return\n      }\n      // 设置文件\n      await sendCDP(\n        'DOM.setFileInputFiles',\n        {\n          nodeId: node.result.nodeId,\n          files: body.files,\n        },\n        sid,\n      )\n      res.end(JSON.stringify({ success: true, files: body.files.length }))\n    }\n\n    // GET /scroll?target=xxx&y=3000 - 滚动\n    else if (pathname === '/scroll') {\n      const sid = await ensureSession(q.target)\n      const y = parseInt(q.y || '3000')\n      const direction = q.direction || 'down' // down | up | top | bottom\n      let js\n      if (direction === 'top') {\n        js = 'window.scrollTo(0, 0); \"scrolled to top\"'\n      } else if (direction === 'bottom') {\n        js = 'window.scrollTo(0, document.body.scrollHeight); \"scrolled to bottom\"'\n      } else if (direction === 'up') {\n        js = `window.scrollBy(0, -${Math.abs(y)}); \"scrolled up ${Math.abs(y)}px\"`\n      } else {\n        js = `window.scrollBy(0, ${Math.abs(y)}); \"scrolled down ${Math.abs(y)}px\"`\n      }\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression: js,\n          returnByValue: true,\n        },\n        sid,\n      )\n      // 等待懒加载触发\n      await new Promise((r) => setTimeout(r, 800))\n      res.end(JSON.stringify({ value: resp.result?.result?.value }))\n    }\n\n    // GET /screenshot?target=xxx&file=/tmp/x.png - 截图\n    else if (pathname === '/screenshot') {\n      const sid = await ensureSession(q.target)\n      const format = q.format || 'png'\n      const resp = await sendCDP(\n        'Page.captureScreenshot',\n        {\n          format,\n          quality: format === 'jpeg' ? 80 : undefined,\n        },\n        sid,\n      )\n      if (q.file) {\n        fs.writeFileSync(q.file, Buffer.from(resp.result.data, 'base64'))\n        res.end(JSON.stringify({ saved: q.file }))\n      } else {\n        res.setHeader('Content-Type', 'image/' + format)\n        res.end(Buffer.from(resp.result.data, 'base64'))\n      }\n    }\n\n    // GET /info?target=xxx - 获取页面信息\n    else if (pathname === '/info') {\n      const sid = await ensureSession(q.target)\n      const resp = await sendCDP(\n        'Runtime.evaluate',\n        {\n          expression:\n            'JSON.stringify({title: document.title, url: location.href, ready: document.readyState})',\n          returnByValue: true,\n        },\n        sid,\n      )\n      res.end(resp.result?.result?.value || '{}')\n    } else {\n      res.statusCode = 404\n      res.end(\n        JSON.stringify({\n          error: '未知端点',\n          endpoints: {\n            '/health': 'GET - 健康检查',\n            '/targets': 'GET - 列出所有页面 tab',\n            '/new?url=': 'GET - 创建新后台 tab（自动等待加载）',\n            '/close?target=': 'GET - 关闭 tab',\n            '/navigate?target=&url=': 'GET - 导航（自动等待加载）',\n            '/back?target=': 'GET - 后退',\n            '/info?target=': 'GET - 页面标题/URL/状态',\n            '/eval?target=': 'POST body=JS表达式 - 执行 JS',\n            '/click?target=': 'POST body=CSS选择器 - 点击元素',\n            '/scroll?target=&y=&direction=': 'GET - 滚动页面',\n            '/screenshot?target=&file=': 'GET - 截图',\n          },\n        }),\n      )\n    }\n  } catch (e) {\n    res.statusCode = 500\n    res.end(JSON.stringify({ error: e.message }))\n  }\n})\n\n// 检查端口是否被占用\nfunction checkPortAvailable(port) {\n  return new Promise((resolve) => {\n    const s = net.createServer()\n    s.once('error', () => resolve(false))\n    s.once('listening', () => {\n      s.close()\n      resolve(true)\n    })\n    s.listen(port, '127.0.0.1')\n  })\n}\n\nasync function main() {\n  // 检查是否已有 proxy 在运行\n  const available = await checkPortAvailable(PORT)\n  if (!available) {\n    // 验证已有实例是否健康\n    try {\n      const ok = await new Promise((resolve) => {\n        http\n          .get(`http://127.0.0.1:${PORT}/health`, { timeout: 2000 }, (res) => {\n            let d = ''\n            res.on('data', (c) => (d += c))\n            res.on('end', () => resolve(d.includes('\"ok\"')))\n          })\n          .on('error', () => resolve(false))\n      })\n      if (ok) {\n        console.log(`[CDP Proxy] 已有实例运行在端口 ${PORT}，退出`)\n        process.exit(0)\n      }\n    } catch {\n      /* 端口占用但非 proxy，继续报错 */\n    }\n    console.error(`[CDP Proxy] 端口 ${PORT} 已被占用`)\n    process.exit(1)\n  }\n\n  // 只有成功绑定端口的实例才生成/复用 token（避免多实例竞态）\n  ensureToken()\n\n  server.listen(PORT, '127.0.0.1', () => {\n    console.log(`[CDP Proxy] 运行在 http://localhost:${PORT}`)\n    // 启动时尝试连接 Chrome（非阻塞）\n    connect().catch((e) =>\n      console.error('[CDP Proxy] 初始连接失败:', e.message, '（将在首次请求时重试）'),\n    )\n  })\n\n  // 定时清理闲置 tab\n  const cleanupTimer = setInterval(cleanupIdleTabs, CLEANUP_INTERVAL)\n  cleanupTimer.unref()\n\n  const shutdown = async (sig) => {\n    console.log(`[CDP Proxy] ${sig}, cleaning up...`)\n    clearInterval(cleanupTimer)\n    await closeAllManagedTabs()\n    process.exit(0)\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n}\n\n// 防止未捕获异常导致进程崩溃\nprocess.on('uncaughtException', (e) => {\n  console.error('[CDP Proxy] 未捕获异常:', e.message)\n})\nprocess.on('unhandledRejection', (e) => {\n  console.error('[CDP Proxy] 未处理拒绝:', e?.message || e)\n})\n\nmain()\n", mode: 493 },
+    { path: "scripts/check-deps.mjs", content: "#!/usr/bin/env node\n// 环境检查 + 确保 CDP Proxy 就绪（跨平台，替代 check-deps.sh）\n\nimport { spawn } from 'node:child_process'\nimport fs from 'node:fs'\nimport net from 'node:net'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')\nconst PROXY_SCRIPT = path.join(ROOT, 'scripts', 'cdp-proxy.mjs')\nconst PROXY_PORT = Number(process.env.CDP_PROXY_PORT || 3456)\nconst TOKEN_FILE = path.join(ROOT, '.cdp-token')\n\n// --- Node.js 版本检查 ---\n\nfunction checkNode() {\n  const major = Number(process.versions.node.split('.')[0])\n  const version = `v${process.versions.node}`\n  if (major >= 22) {\n    console.log(`node: ok (${version})`)\n  } else {\n    console.log(`node: warn (${version}, 建议升级到 22+)`)\n  }\n}\n\n// --- TCP 端口探测 ---\n\nfunction checkPort(port, host = '127.0.0.1', timeoutMs = 2000) {\n  return new Promise((resolve) => {\n    const socket = net.createConnection(port, host)\n    const timer = setTimeout(() => {\n      socket.destroy()\n      resolve(false)\n    }, timeoutMs)\n    socket.once('connect', () => {\n      clearTimeout(timer)\n      socket.destroy()\n      resolve(true)\n    })\n    socket.once('error', () => {\n      clearTimeout(timer)\n      resolve(false)\n    })\n  })\n}\n\n// --- Chrome 调试端口检测（DevToolsActivePort 多路径 + 常见端口回退） ---\n\nfunction activePortFiles() {\n  const home = os.homedir()\n  const localAppData = process.env.LOCALAPPDATA || ''\n  switch (os.platform()) {\n    case 'darwin':\n      return [\n        path.join(home, 'Library/Application Support/Google/Chrome/DevToolsActivePort'),\n        path.join(home, 'Library/Application Support/Google/Chrome Canary/DevToolsActivePort'),\n        path.join(home, 'Library/Application Support/Chromium/DevToolsActivePort'),\n      ]\n    case 'linux':\n      return [\n        path.join(home, '.config/google-chrome/DevToolsActivePort'),\n        path.join(home, '.config/chromium/DevToolsActivePort'),\n      ]\n    case 'win32':\n      return [\n        path.join(localAppData, 'Google/Chrome/User Data/DevToolsActivePort'),\n        path.join(localAppData, 'Chromium/User Data/DevToolsActivePort'),\n      ]\n    default:\n      return []\n  }\n}\n\nasync function detectChromePort() {\n  // 优先从 DevToolsActivePort 文件读取\n  for (const filePath of activePortFiles()) {\n    try {\n      const lines = fs.readFileSync(filePath, 'utf8').trim().split(/\\r?\\n/).filter(Boolean)\n      const port = parseInt(lines[0], 10)\n      if (port > 0 && port < 65536 && (await checkPort(port))) {\n        return port\n      }\n    } catch {}\n  }\n  // 回退：探测常见端口\n  for (const port of [9222, 9229, 9333]) {\n    if (await checkPort(port)) {\n      return port\n    }\n  }\n  return null\n}\n\n// --- CDP Proxy 启动与等待 ---\n\nfunction readToken() {\n  try {\n    const t = fs.readFileSync(TOKEN_FILE, 'utf8').trim()\n    if (t) return t\n  } catch {\n    /* proxy 尚未生成 token */\n  }\n  return null\n}\n\nfunction httpGetJson(url, timeoutMs = 3000) {\n  const token = readToken()\n  return fetch(url, {\n    signal: AbortSignal.timeout(timeoutMs),\n    headers: token ? { 'X-CDP-Token': token } : {},\n  })\n    .then(async (res) => {\n      try {\n        return JSON.parse(await res.text())\n      } catch {\n        return null\n      }\n    })\n    .catch(() => null)\n}\n\nfunction startProxyDetached() {\n  const logFile = path.join(os.tmpdir(), 'cdp-proxy.log')\n  const logFd = fs.openSync(logFile, 'a')\n  const child = spawn(process.execPath, [PROXY_SCRIPT], {\n    detached: true,\n    stdio: ['ignore', logFd, logFd],\n    ...(os.platform() === 'win32' ? { windowsHide: true } : {}),\n  })\n  child.unref()\n  fs.closeSync(logFd)\n}\n\nasync function ensureProxy() {\n  const targetsUrl = `http://127.0.0.1:${PROXY_PORT}/targets`\n\n  // /targets 返回 JSON 数组即 ready\n  const targets = await httpGetJson(targetsUrl)\n  if (Array.isArray(targets)) {\n    console.log('proxy: ready')\n    return true\n  }\n\n  // 未运行或未连接，启动并等待\n  console.log('proxy: connecting...')\n  startProxyDetached()\n\n  // 等 proxy 进程就绪\n  await new Promise((r) => setTimeout(r, 2000))\n\n  for (let i = 1; i <= 15; i++) {\n    const result = await httpGetJson(targetsUrl, 8000)\n    if (Array.isArray(result)) {\n      console.log('proxy: ready')\n      return true\n    }\n    if (i === 1) {\n      console.log('⚠️  Chrome 可能有授权弹窗，请点击「允许」后等待连接...')\n    }\n    await new Promise((r) => setTimeout(r, 1000))\n  }\n\n  console.log('❌ 连接超时，请检查 Chrome 调试设置')\n  console.log(`  日志：${path.join(os.tmpdir(), 'cdp-proxy.log')}`)\n  return false\n}\n\n// --- main ---\n\nasync function main() {\n  checkNode()\n\n  const chromePort = await detectChromePort()\n  if (!chromePort) {\n    console.log(\n      'chrome: not connected — 请确保 Chrome 已打开，然后访问 chrome://inspect/#remote-debugging 并勾选 Allow remote debugging',\n    )\n    process.exit(1)\n  }\n  console.log(`chrome: ok (port ${chromePort})`)\n\n  const proxyOk = await ensureProxy()\n  if (!proxyOk) {\n    process.exit(1)\n  }\n\n  // 列出已有站点经验\n  const patternsDir = path.join(ROOT, 'references', 'site-patterns')\n  try {\n    const sites = fs\n      .readdirSync(patternsDir)\n      .filter((f) => f.endsWith('.md'))\n      .map((f) => f.replace(/\\.md$/, ''))\n    if (sites.length) {\n      console.log(`\\nsite-patterns: ${sites.join(', ')}`)\n    }\n  } catch {}\n}\n\nawait main()\n", mode: 493 },
+    { path: "scripts/find-url.mjs", content: "#!/usr/bin/env node\n// find-url - 从本地 Chrome 书签/历史中检索 URL\n// 用于定位公网搜索覆盖不到的目标（组织内部系统、SSO 后台、内网域名等）。\n//\n// 用法：\n//   node find-url.mjs [关键词...] [--only bookmarks|history] [--limit N] [--since 1d|7h|YYYY-MM-DD]\n//\n//   <关键词>            空格分词、多词 AND，匹配 title + url；可省略\n//   --only <source>     限定数据源（bookmarks / history），默认两者都查\n//   --limit N           条数上限，默认 20；0 = 不限\n//   --since <window>    时间窗（仅作用于历史）。1d / 7h / 30m 或 YYYY-MM-DD\n//   --sort recent|visits  历史排序：按最近访问 / 按访问次数，默认 recent\n//\n// 示例：\n//   node find-url.mjs 财务小智\n//   node find-url.mjs agent skills\n//   node find-url.mjs github --since 7d --only history\n//   node find-url.mjs --since 7d --only history --sort visits   # 最近一周高频网站\n//   node find-url.mjs --since 2d --only history --limit 0\n\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport os from 'node:os'\nimport { execFileSync } from 'node:child_process'\n\n// --- 参数解析 -----------------------------------------------------------\nfunction parseArgs(argv) {\n  const a = { keywords: [], only: null, limit: 20, since: null, sort: 'recent' }\n  for (let i = 0; i < argv.length; i++) {\n    const v = argv[i]\n    if (v === '--only') a.only = argv[++i]\n    else if (v === '--limit') a.limit = parseInt(argv[++i], 10)\n    else if (v === '--since') a.since = parseSince(argv[++i])\n    else if (v === '--sort') a.sort = argv[++i]\n    else if (v === '-h' || v === '--help') {\n      printUsage()\n      process.exit(0)\n    } else if (v.startsWith('--')) die(`未知参数: ${v}`)\n    else a.keywords.push(v)\n  }\n  if (a.only && !['bookmarks', 'history'].includes(a.only)) die(`--only 仅支持 bookmarks|history`)\n  if (!['recent', 'visits'].includes(a.sort)) die(`--sort 仅支持 recent|visits`)\n  if (Number.isNaN(a.limit) || a.limit < 0) die('--limit 需为非负整数')\n  return a\n}\n\nfunction parseSince(s) {\n  if (!s) die('--since 需要值')\n  const m = s.match(/^(\\d+)([dhm])$/)\n  if (m) {\n    const n = parseInt(m[1], 10)\n    const ms = { d: 86400000, h: 3600000, m: 60000 }[m[2]]\n    return new Date(Date.now() - n * ms)\n  }\n  const d = new Date(s)\n  if (Number.isNaN(d.getTime())) die(`无效 --since 值: ${s}（用 1d / 7h / 30m / YYYY-MM-DD）`)\n  return d\n}\n\nfunction die(msg) {\n  console.error(msg)\n  process.exit(1)\n}\nfunction printUsage() {\n  console.error(\n    fs\n      .readFileSync(new URL(import.meta.url))\n      .toString()\n      .split('\\n')\n      .slice(1, 19)\n      .map((l) => l.replace(/^\\/\\/ ?/, ''))\n      .join('\\n'),\n  )\n}\n\n// --- Chrome 用户数据目录（跨平台） ---------------------------------------\nfunction getChromeDataDir() {\n  const home = os.homedir()\n  switch (os.platform()) {\n    case 'darwin':\n      return path.join(home, 'Library/Application Support/Google/Chrome')\n    case 'linux':\n      return path.join(home, '.config/google-chrome')\n    case 'win32':\n      return path.join(process.env.LOCALAPPDATA || '', 'Google/Chrome/User Data')\n    default:\n      return null\n  }\n}\n\n// --- Profile 枚举 -------------------------------------------------------\nfunction listProfiles(dataDir) {\n  try {\n    const state = JSON.parse(fs.readFileSync(path.join(dataDir, 'Local State'), 'utf-8'))\n    const info = state?.profile?.info_cache || {}\n    const list = Object.keys(info).map((dir) => ({ dir, name: info[dir].name || dir }))\n    if (list.length) return list\n  } catch {\n    /* 回退 */\n  }\n  return [{ dir: 'Default', name: 'Default' }]\n}\n\n// --- 书签检索 -----------------------------------------------------------\nfunction searchBookmarks(profileDir, profileName, keywords) {\n  const file = path.join(profileDir, 'Bookmarks')\n  if (!fs.existsSync(file)) return []\n  let data\n  try {\n    data = JSON.parse(fs.readFileSync(file, 'utf-8'))\n  } catch {\n    return []\n  }\n  if (!keywords.length) return [] // 书签无时间维度，无关键词不返回\n\n  const needles = keywords.map((k) => k.toLowerCase())\n  const out = []\n  function walk(node, trail) {\n    if (!node) return\n    if (node.type === 'url') {\n      const hay = `${node.name || ''} ${node.url || ''}`.toLowerCase()\n      if (needles.every((n) => hay.includes(n))) {\n        out.push({\n          profile: profileName,\n          name: node.name || '',\n          url: node.url || '',\n          folder: trail.join(' / '),\n        })\n      }\n    }\n    if (Array.isArray(node.children)) {\n      const sub = node.name ? [...trail, node.name] : trail\n      for (const c of node.children) walk(c, sub)\n    }\n  }\n  for (const root of Object.values(data.roots || {})) walk(root, [])\n  return out\n}\n\n// --- 历史检索（SQLite 运行时锁定，需 copy 到 tmp） ------------------------\nconst WEBKIT_EPOCH_DIFF_US = 11644473600000000n // 1601→1970 微秒差\n\nfunction searchHistory(profileDir, profileName, keywords, since, limit, sort) {\n  const src = path.join(profileDir, 'History')\n  if (!fs.existsSync(src)) return []\n  const tmp = path.join(os.tmpdir(), `chrome-history-${process.pid}-${Date.now()}.sqlite`)\n  try {\n    fs.copyFileSync(src, tmp)\n    const conds = ['last_visit_time > 0']\n    for (const kw of keywords) {\n      const esc = kw.toLowerCase().replace(/'/g, \"''\")\n      conds.push(`LOWER(title || ' ' || url) LIKE '%${esc}%'`)\n    }\n    if (since) {\n      const webkitUs = BigInt(since.getTime()) * 1000n + WEBKIT_EPOCH_DIFF_US\n      conds.push(`last_visit_time >= ${webkitUs}`)\n    }\n    const limitClause = limit === 0 ? -1 : limit\n    const orderBy =\n      sort === 'visits' ? 'visit_count DESC, last_visit_time DESC' : 'last_visit_time DESC'\n    const sql = `SELECT title, url,\n      datetime((last_visit_time - 11644473600000000)/1000000, 'unixepoch', 'localtime') AS visit,\n      visit_count\n      FROM urls WHERE ${conds.join(' AND ')}\n      ORDER BY ${orderBy} LIMIT ${limitClause};`\n\n    const raw = execFileSync('sqlite3', ['-separator', '\\t', tmp, sql], {\n      encoding: 'utf-8',\n      maxBuffer: 50 * 1024 * 1024,\n    })\n    return raw\n      .trim()\n      .split('\\n')\n      .filter(Boolean)\n      .map((line) => {\n        const [title, url, visit, visit_count] = line.split('\\t')\n        return { profile: profileName, title, url, visit, visit_count: parseInt(visit_count, 10) }\n      })\n  } catch (e) {\n    if (e.code === 'ENOENT')\n      die(\n        '未找到 sqlite3 命令。macOS/Linux 通常自带；Windows 可用 `winget install sqlite.sqlite` 或从 https://sqlite.org/download.html 下载后加入 PATH。',\n      )\n    return []\n  } finally {\n    try {\n      fs.unlinkSync(tmp)\n    } catch {}\n  }\n}\n\n// --- 输出格式化 ---------------------------------------------------------\n// 用 `|` 作字段分隔符；字段内含 `|` 的替换成 `│`（全宽竖线）避免歧义\nconst clean = (s) =>\n  String(s ?? '')\n    .replaceAll('|', '│')\n    .trim()\n\nfunction printBookmarks(items, multiProfile) {\n  console.log(`[书签] ${items.length} 条`)\n  for (const b of items) {\n    const segs = [clean(b.name) || '(无标题)', clean(b.url)]\n    if (b.folder) segs.push(clean(b.folder))\n    if (multiProfile) segs.push('@' + clean(b.profile))\n    console.log('  ' + segs.join(' | '))\n  }\n}\n\nfunction printHistory(items, multiProfile, sortLabel) {\n  console.log(`[历史] ${items.length} 条（${sortLabel}）`)\n  for (const h of items) {\n    const segs = [clean(h.title) || '(无标题)', clean(h.url), h.visit]\n    if (h.visit_count > 1) segs.push(`visits=${h.visit_count}`)\n    if (multiProfile) segs.push('@' + clean(h.profile))\n    console.log('  ' + segs.join(' | '))\n  }\n}\n\n// --- main ---------------------------------------------------------------\nconst args = parseArgs(process.argv.slice(2))\n\nconst dataDir = getChromeDataDir()\nif (!dataDir || !fs.existsSync(dataDir)) die('未找到 Chrome 用户数据目录')\n\nconst profiles = listProfiles(dataDir)\nconst doBookmarks = args.only !== 'history'\nconst doHistory = args.only !== 'bookmarks'\n\nconst bookmarks = []\nconst history = []\nfor (const p of profiles) {\n  const pDir = path.join(dataDir, p.dir)\n  if (!fs.existsSync(pDir)) continue\n  if (doBookmarks) bookmarks.push(...searchBookmarks(pDir, p.name, args.keywords))\n  if (doHistory)\n    history.push(\n      ...searchHistory(\n        pDir,\n        p.name,\n        args.keywords,\n        args.since,\n        args.limit === 0 ? 0 : args.limit * 2,\n        args.sort,\n      ),\n    )\n}\n\n// 历史跨 profile 合并后按指定 sort 重排 + 切顶\nif (args.sort === 'visits') {\n  history.sort(\n    (a, b) =>\n      (b.visit_count || 0) - (a.visit_count || 0) || (b.visit || '').localeCompare(a.visit || ''),\n  )\n} else {\n  history.sort((a, b) => (b.visit || '').localeCompare(a.visit || ''))\n}\nconst bookmarksOut = args.limit === 0 ? bookmarks : bookmarks.slice(0, args.limit)\nconst historyOut = args.limit === 0 ? history : history.slice(0, args.limit)\n\n// 仅当结果真的横跨多个 profile 时，才输出 @profile 标注（空 profile 不算）\nconst seenProfiles = new Set([...bookmarksOut, ...historyOut].map((x) => x.profile))\nconst showProfile = seenProfiles.size > 1\n\nconst sortLabel = args.sort === 'visits' ? '按访问次数' : '按最近访问'\nif (doBookmarks) printBookmarks(bookmarksOut, showProfile)\nif (doBookmarks && doHistory) console.log()\nif (doHistory) printHistory(historyOut, showProfile, sortLabel)\n\nif (!args.keywords.length && doBookmarks && !doHistory) {\n  console.error('\\n提示：书签无时间维度，无关键词查询无意义。加关键词或切换 --only history。')\n}\n", mode: 493 },
+    { path: "scripts/match-site.mjs", content: "#!/usr/bin/env node\n// 根据用户输入匹配站点经验文件（跨平台，替代 match-site.sh）\n// 用法：node match-site.mjs \"用户输入文本\"\n// 输出：匹配到的站点经验内容，无匹配则静默\n\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')\nconst PATTERNS_DIR = path.join(ROOT, 'references', 'site-patterns')\nconst query = (process.argv[2] || '').trim()\n\nif (!query || !fs.existsSync(PATTERNS_DIR)) {\n  process.exit(0)\n}\n\nfor (const entry of fs.readdirSync(PATTERNS_DIR, { withFileTypes: true })) {\n  if (!entry.isFile() || !entry.name.endsWith('.md')) continue\n\n  const domain = entry.name.replace(/\\.md$/, '')\n  const raw = fs.readFileSync(path.join(PATTERNS_DIR, entry.name), 'utf8')\n\n  // 提取 aliases\n  const aliasesLine = raw.split(/\\r?\\n/).find((l) => l.startsWith('aliases:')) || ''\n  const aliases = aliasesLine\n    .replace(/^aliases:\\s*/, '')\n    .replace(/^\\[/, '')\n    .replace(/\\]$/, '')\n    .split(',')\n    .map((v) => v.trim())\n    .filter(Boolean)\n\n  // 构建匹配模式\n  const escaped = (t) => t.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n  const pattern = [domain, ...aliases].map(escaped).join('|')\n  if (!new RegExp(pattern, 'i').test(query)) continue\n\n  // 跳过 frontmatter，输出正文\n  const fences = [...raw.matchAll(/^---\\s*$/gm)]\n  const body =\n    fences.length >= 2\n      ? raw.slice(fences[1].index + fences[1][0].length).replace(/^\\r?\\n/, '')\n      : raw\n\n  process.stdout.write(`--- 站点经验: ${domain} ---\\n`)\n  process.stdout.write(body.trimEnd() + '\\n\\n')\n}\n", mode: 493 },
   ],
 }

package/src/skills/bundled-skills.ts

@@ -26,7 +26,7 @@ export const BUNDLED_SKILLS: ReadonlyArray<BundledSkill> = [
   { type: 'standard', raw: "---\nname: tdd\ndescription: Test-Driven Development — red-green-refactor cycle with language-specific guidance and test design rules\nversion: 2.0.0\n---\n\n# Test-Driven Development (TDD)\n\n## The Cycle\n\n```\nRED → GREEN → REFACTOR → repeat\n```\n\n### 1. RED — Write a Failing Test\n\nWrite the smallest test that captures the behavior you want:\n\n- Name the test descriptively: `it('should return 0 for empty string')`\n- Use the AAA pattern: **A**rrange → **A**ct → **A**ssert\n- Run to confirm it **fails** (not errors — fails)\n- If it passes before implementation, your test is wrong\n\n### 2. GREEN — Make It Pass\n\nWrite the **minimum** code to make the test pass:\n\n- Don't optimize, don't generalize, don't add features\n- A hardcoded return is fine if it passes the test\n- Run all tests — the new one should pass, old ones should still pass\n\n### 3. REFACTOR — Clean Up\n\nImprove the code while tests stay green:\n\n- Remove duplication (test code and production code)\n- Improve names, extract helpers\n- Simplify logic\n- Run tests after each change\n\n## Test Design Rules\n\n- **Deterministic**: No `Date.now()`, `Math.random()`, or network calls in test bodies\n- **Isolated**: Each test sets up its own state; no test-order dependency\n- **Fast**: Unit tests should run in milliseconds, not seconds\n- **Readable**: Test output should explain what broke without reading source\n\n## Language-Specific Guidance\n\n### TypeScript / JavaScript (Vitest)\n\n```ts\nimport { describe, it, expect } from 'vitest'\n\ndescribe('sum', () => {\n  it('should add two positive numbers', () => {\n    expect(sum(2, 3)).toBe(5)\n  })\n  it('should handle zero', () => {\n    expect(sum(0, 5)).toBe(5)\n  })\n})\n```\n\nFile naming: `src/foo.ts` → `test/foo.test.ts`\n\n### Python (pytest)\n\n```python\ndef test_sum_positive():\n    assert sum(2, 3) == 5\n\ndef test_sum_zero():\n    assert sum(0, 5) == 5\n```\n\n### Go (testing package)\n\n```go\nfunc TestSumPositive(t *testing.T) {\n    got := Sum(2, 3)\n    want := 5\n    if got != want {\n        t.Errorf(\"Sum(2,3) = %d; want %d\", got, want)\n    }\n}\n```\n\n## When NOT to TDD\n\n- Exploratory spikes (throw away after learning)\n- Configuration files and types (compile-time enforced)\n- Generated code\n" },
   { type: 'standard', raw: "---\nname: to-spec\ndescription: Turn a conversation into a structured specification document. Use after a grill-with-docs session or any requirements discussion to capture decisions in a durable, shareable format.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Bash\n---\n\n# To Spec — Conversation → Specification\n\nTurn the output of a requirements discussion into a structured specification document. This is the bridge between `/grill-with-docs` (alignment) and `/triage` (task decomposition).\n\n## When to Use\n\n- After a `/grill-with-docs` session — capture what was decided\n- After any requirements discussion — before starting implementation\n- User asks: \"write this up\", \"create a spec\", \"document the plan\"\n- Before handing off work to another session or person\n\n## When NOT to Use\n\n- The requirements are a single sentence and obvious\n- You're in the middle of a grill session — finish the interview first\n- The scope is so small that the spec would be longer than the implementation\n\n---\n\n## Spec Format\n\nWrite to `docs/specs/YYYY-MM-DD-slug.md`:\n\n```markdown\n---\nstatus: draft | approved | implemented\ncreated: 2026-08-10\n---\n\n# {Title}\n\n## Problem\n\n{What problem are we solving? Why now? 1-3 sentences.}\n\n## Scope\n\n### In Scope\n\n- {What we're building}\n\n### Out of Scope (Explicit)\n\n- {What we're NOT building — prevents scope creep}\n\n## Requirements\n\n### Functional\n\n- **{Requirement}**: {Description}. Acceptance: {measurable criterion}.\n\n### Non-Functional\n\n- **Performance**: {latency, throughput targets}\n- **Security**: {auth, data protection, threat model}\n- **Scale**: {expected volume, growth projections}\n\n## Design Decisions\n\n- **Decision**: {What we decided}. Because: {why}. Alternatives considered: {options + reasons rejected}.\n\n## Domain Model\n\n{Key terms and their definitions — from CONTEXT.md or the grill session.}\n\n## Edge Cases\n\n- **{Scenario}**: {Expected behavior}\n- **{Scenario}**: {Expected behavior}\n\n## Open Questions\n\n- {Question} — {who needs to answer / when needed}\n```\n\n---\n\n## The Spec Workflow\n\n### Step 1: Extract from Conversation\n\nScan the conversation history for:\n\n- Decisions made (explicit and implicit)\n- Terms defined (candidates for CONTEXT.md)\n- Edge cases discussed\n- Alternatives rejected (and why)\n- Open questions that remain\n\n### Step 2: Fill Gaps\n\nFor each gap you find:\n\n- Edge cases not discussed → flag as Open Questions\n- Terms used but not defined → propose definitions\n- Assumptions not stated → make them explicit\n\n### Step 3: Validate with User\n\nPresent the spec and ask:\n\n1. \"Does this match your understanding?\"\n2. \"What's missing?\"\n3. \"What's wrong?\"\n4. \"What surprised you?\"\n\n### Step 4: Feed Into Triage\n\nOnce approved, the spec's functional requirements become tickets in `/triage`. Non-functional requirements become acceptance criteria.\n\n---\n\n## Anti-Patterns\n\n- **Waterfall trap**: Don't try to spec everything upfront. Spec the next increment. Specs are living documents, not contracts.\n- **Premature detail**: Don't spec API signatures or DB schemas in the spec — those are implementation details.\n- **Vague acceptance**: \"Works well\" is not acceptance criteria. \"Returns 200 with valid JWT within 500ms\" is.\n\n---\n\n## Integration With Mipham Code\n\n- **grill-with-docs**: Input — the grill session produces the raw material\n- **triage**: Output — the spec feeds into ticket decomposition\n- **domain-modeling**: Terms discovered during spec writing go to CONTEXT.md\n- **Memory System**: The spec file persists as project reference across sessions\n" },
   { type: 'standard', raw: "---\nname: triage\ndescription: Structured task decomposition and tracking across sessions. Use for breaking complex plans into trackable tickets with dependency graphs, checking task status, or continuing work from a previous session.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Bash\n  - Glob\n  - Grep\n---\n\n# Triage — Cross-Session Task Tracking\n\nTurn plans into trackable tickets with dependency management. Inspired by Matt Pocock's `triage` + `to-tickets` + `wayfinder` skills, consolidated into one Mipham Code skill.\n\n## When to Use\n\n- Breaking a large plan into actionable tickets\n- Tracking work across multiple sessions\n- User asks: \"what's next?\", \"where did I leave off?\", \"what's the status?\"\n- Complex tasks with dependencies between them\n\n---\n\n## The Ticket Format\n\nTickets live in `.mipham/tickets/` as individual Markdown files:\n\n```markdown\n---\nid: T-001\ntitle: Add user authentication\nstatus: in-progress\npriority: P0\ndepends_on: []\nblocks: [T-003]\ncreated: 2026-08-10\ntags:\n  - auth\n  - backend\n---\n\n## Description\n\nAdd JWT-based authentication with refresh token rotation.\n\n## Acceptance Criteria\n\n- [ ] Login endpoint returns access + refresh tokens\n- [ ] Refresh endpoint rotates tokens\n- [ ] Invalid tokens return 401\n- [ ] Rate limiting on login attempts\n\n## Notes\n\n- OAuth not in scope for T-001 (punted to T-005)\n```\n\n### Status Values\n\n| Status        | Meaning                                    |\n| ------------- | ------------------------------------------ |\n| `backlog`     | Not yet planned for any session            |\n| `planned`     | Scoped and ready to work                   |\n| `in-progress` | Currently being worked on                  |\n| `review`      | Implementation done, awaiting verification |\n| `done`        | Verified and merged                        |\n| `blocked`     | Cannot proceed due to dependency           |\n| `wontfix`     | Decided not to do                          |\n\n---\n\n## The Triage Workflow\n\n### Phase 1: Decompose (Plan → Tickets)\n\nGiven a plan or feature request:\n\n1. **Identify the smallest independently-valuable units of work**\n   - Each ticket should deliver value on its own\n   - If a ticket requires 3+ files touched, it's probably too big\n   - If a ticket can be done in < 15 minutes, it's probably too small\n\n2. **Map dependencies**\n   - What must be done first? (hard dependency)\n   - What would be easier after something else? (soft dependency)\n   - What blocks other work? (reverse dependency)\n\n3. **Assign priorities**\n   - **P0**: Blocks other work, must do first\n   - **P1**: High value, should do soon\n   - **P2**: Nice to have, can defer\n   - **P3**: Optional, do if time permits\n\n4. **Write acceptance criteria**\n   - Specific, testable, unambiguous\n   - \"Login works\" is bad. \"POST /auth/login with valid credentials returns 200 + JWT\" is good.\n\n### Phase 2: Status Check\n\nWhen the user asks \"what's next?\" or \"what's the status?\":\n\n1. Read `.mipham/tickets/` directory\n2. Report:\n   - Currently in-progress tickets\n   - Blocked tickets (and what's blocking them)\n   - Next unblocked P0/P1 tickets ready to work\n   - Recently completed tickets (for context)\n\n### Phase 3: Session Handoff\n\nWhen starting a new session, check for continuity:\n\n1. Read the previous session's context from the session store\n2. Check ticket statuses — any that were `in-progress` last session?\n3. Present: \"Last session you were working on T-004 (Add rate limiting). Continue from there, or start on T-007 (API docs) which is next in the P1 queue?\"\n\n### Phase 4: Ticket Lifecycle\n\nWhen working on a ticket:\n\n- Mark it `in-progress` when you start\n- Mark it `review` when implementation is done\n- Mark it `done` after verification (tests pass, typecheck clean)\n- If you discover new dependencies, add them to `blocks`/`depends_on`\n\n---\n\n## Dependency Graph\n\nFor tickets with complex dependencies, generate a visual summary:\n\n```\nT-001 (Auth) ──blocks──→ T-003 (Dashboard)\n    │                        │\n    └──blocks──→ T-002 (API) ─┘\n                     │\n                     └──soft-dep──→ T-004 (Rate Limiting)\n\nReady to work: T-001 (no dependencies)\nBlocked: T-002 (waiting on T-001), T-003 (waiting on T-001, T-002)\n```\n\n---\n\n## Integration With Mipham Code\n\n- **Session Store**: Ticket status persists across sessions via `.mipham/tickets/`\n- **Memory System**: Active tickets are loaded as project memory for context\n- **grill-with-docs**: The output of a grill session feeds directly into ticket decomposition\n- **Background Agents**: Long-running work on a ticket can be spawned as a background agent\n- **Critical Thinking Layer**: When decomposing, ask \"what's the smallest thing that delivers value?\" — don't over-decompose\n" },
-  { type: 'standard', raw: "---\nname: web-access\ndescription: '联网访问：CDP 驱动用户已登录 Chrome（登录后操作、动态页面、反爬站点、社交媒体、本地书签/历史检索）'\nlicense: MIT\ngithub: https://github.com/eze-is/web-access\nversion: 2.5.0\nuser-invocable: true\nallowed-tools:\n  - Bash\n  - WebFetch\n  - WebSearch\n  - Read\n---\n\n# Web Access — CDP 驱动已登录 Chrome\n\n> 来源：eze-is/web-access (MIT)，Mipham Code 合并升级。核心能力 = CDP Proxy 直连用户日常 Chrome，天然携带登录态。\n\n## 前置检查\n\n先确保 CDP 就绪：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/check-deps.mjs\n```\n\n> Mipham Code 环境：`node` 不可用时可用 `bun` 替代（Bun 原生支持 WebSocket 与 node: 内建）。未通过时引导用户：Chrome 地址栏打开 `chrome://inspect/#remote-debugging`，勾选 \"Allow remote debugging for this browser instance\"。\n\n**必须向用户展示**：部分站点对浏览器自动化检测严格，存在账号封禁风险。已内置防护但无法完全避免，Agent 继续操作即视为接受。\n\n## 工具选择\n\n| 场景                                          | 工具        |\n| --------------------------------------------- | ----------- |\n| 搜索摘要 / 发现来源                           | WebSearch   |\n| URL 已知，定向提取                            | WebFetch    |\n| URL 已知，要原始 HTML（meta/JSON-LD）         | Bash + curl |\n| 非公开内容 / 反爬站点（小红书、微信公众号等） | 浏览器 CDP  |\n| 需要登录态、交互、自由导航                    | 浏览器 CDP  |\n\n浏览器 CDP 不要求 URL 已知；WebSearch/WebFetch/curl 均不处理登录态。\n\n## 浏览器 CDP 模式\n\n通过 CDP Proxy 直连用户日常 Chrome，天然携带登录态。**不主动操作用户已有 tab**，所有操作在自己创建的后台 tab 中进行，任务结束关闭自建 tab（保留用户原 tab）。\n\nProxy（`scripts/cdp-proxy.mjs`）由 `check-deps.mjs` 自动拉起并常驻。Proxy API（curl 调 `http://localhost:3456/...`）：\n\n| 端点                                       | 用途                                                                     |\n| ------------------------------------------ | ------------------------------------------------------------------------ |\n| `GET /targets`                             | 列出已开 tab                                                             |\n| `GET /new?url=`                            | 新建后台 tab（自动等加载）                                               |\n| `GET /navigate?target=&url=`               | 导航（自动等加载）                                                       |\n| `GET /back?target=`                        | 后退                                                                     |\n| `GET /info?target=`                        | 页面标题/URL/状态                                                        |\n| `POST /eval?target=`（body=JS）            | 执行任意 JS（读写 DOM、提取、提交）                                      |\n| `POST /click?target=`（body=CSS 选择器）   | JS 点击（`el.click()`，覆盖大多数场景）                                  |\n| `POST /clickAt?target=`（body=CSS 选择器） | 真实鼠标点击（`Input.dispatchMouseEvent`，算用户手势，能触发文件对话框） |\n| `POST /setFiles?target=`（body JSON）      | 设置 file input 本地文件路径（`DOM.setFileInputFiles`，绕过文件对话框）  |\n| `GET /scroll?target=&y=&direction=`        | 滚动（`direction=down/up/top/bottom`，触发懒加载）                       |\n| `GET /screenshot?target=&file=`            | 截图                                                                     |\n| `GET /close?target=`                       | 关闭 tab                                                                 |\n\n进入浏览器层后，`/eval` 是眼睛、`/click` 是手：先看 DOM 结构再决定下一步，不预先规划所有步骤。\n\n### 登录判断\n\n核心问题只有一个：**目标内容拿到了吗？** 打开页面先尝试获取目标内容；确认「目标内容无法获取」且判断登录能解决时，告知用户在其 Chrome 登录后继续（无需重启任何东西，刷新页面即可）。\n\n### 媒体资源提取\n\n判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL 定向读取，比全页截图精准。`/scroll` 到底部触发懒加载后再提取图片 URL。\n\n### 视频内容获取\n\n用户 Chrome 真实渲染，截图可捕获当前视频帧。用 `/eval` 操控 `<video>`（时长、seek、播放/暂停），配合 `/screenshot` 采帧，做离散采样分析。\n\n## 本地 Chrome 资源\n\n用户指向「本人访问过的页面」或「组织内部系统」时，检索本地书签/历史：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/find-url.mjs [关键词...] [--only bookmarks|history] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]\n```\n\n## 并行调研：子 Agent 分治\n\n多个独立调研目标时，分治给子 Agent 并行执行（共享一个 Chrome、一个 Proxy，各自建 tab、各自 `/close`，无竞态）。子 Agent prompt 写**目标**（「获取/调研/了解」），不写**手段**（避免「搜索xx」锚定到 WebSearch 而错过需 CDP 的反爬站点）。\n\n## 信息核实\n\n核实目标是一手来源，非二手报道。搜索引擎是**定位**工具，不可直接**证明**真伪；找到来源后直接访问读原文。\n\n| 信息类型      | 一手来源       |\n| ------------- | -------------- |\n| 政策/法规     | 发布机构官网   |\n| 企业公告      | 公司官方新闻页 |\n| 工具能力/用法 | 官方文档、源码 |\n\n### 交叉验证\n\n- 关键声明须 2+ 独立来源交叉印证。\n- 优先采纳当年/近期资料。\n- 权威层级：官方文档 > 知名博客 > 技术社区 > 随机论坛。\n\n### 来源归因\n\n回答结尾附来源列表：\n\n```markdown\nSources:\n\n- [标题](URL) — 一句话说明\n```\n\n## 站点经验\n\n特定网站经验按域名存 `~/.mipham/skills/web-access/references/site-patterns/<domain>.md`（frontmatter: domain/aliases/updated + 平台特征/有效模式/已知陷阱）。操作前若有匹配经验先读；操作成功后把验证过的新模式写回。\n\n## Security Rules\n\n- 不主动操作用户已有 tab；任务结束关闭自建 tab。\n- 不提交凭据（除非用户显式批准）。\n- 尊重 robots.txt 与速率限制；不抓 PII。\n- proxy 仅绑 127.0.0.1，不暴露外网；端口 3456 无鉴权，依赖本机信任边界，勿在共享/多用户主机运行。\n- ⚠️ proxy 不做 URL SSRF 校验（照搬上游，与 computer-use/Playwright 同类）：避免驱动 Chrome 访问本机内部服务/内网地址。\n\n## 何时不用本 skill\n\n- 纯逻辑/算法题（推理非研究）。\n- 代码已在上下文里的问题。\n- 大文件下载 → Bash + curl。\n" },
+  { type: 'standard', raw: "---\nname: web-access\ndescription: '联网访问：CDP 驱动用户已登录 Chrome（登录后操作、动态页面、反爬站点、社交媒体、本地书签/历史检索）'\nlicense: MIT\ngithub: https://github.com/eze-is/web-access\nversion: 2.5.0\nuser-invocable: true\nallowed-tools:\n  - Bash\n  - WebFetch\n  - WebSearch\n  - Read\n---\n\n# Web Access — CDP 驱动已登录 Chrome\n\n> 来源：eze-is/web-access (MIT)，Mipham Code 合并升级。核心能力 = CDP Proxy 直连用户日常 Chrome，天然携带登录态。\n\n## 前置检查\n\n先确保 CDP 就绪：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/check-deps.mjs\n```\n\n> Mipham Code 环境：`node` 不可用时可用 `bun` 替代（Bun 原生支持 WebSocket 与 node: 内建）。未通过时引导用户：Chrome 地址栏打开 `chrome://inspect/#remote-debugging`，勾选 \"Allow remote debugging for this browser instance\"。\n\n**必须向用户展示**：部分站点对浏览器自动化检测严格，存在账号封禁风险。已内置防护但无法完全避免，Agent 继续操作即视为接受。\n\n## 工具选择\n\n| 场景                                          | 工具        |\n| --------------------------------------------- | ----------- |\n| 搜索摘要 / 发现来源                           | WebSearch   |\n| URL 已知，定向提取                            | WebFetch    |\n| URL 已知，要原始 HTML（meta/JSON-LD）         | Bash + curl |\n| 非公开内容 / 反爬站点（小红书、微信公众号等） | 浏览器 CDP  |\n| 需要登录态、交互、自由导航                    | 浏览器 CDP  |\n\n浏览器 CDP 不要求 URL 已知；WebSearch/WebFetch/curl 均不处理登录态。\n\n## 浏览器 CDP 模式\n\n通过 CDP Proxy 直连用户日常 Chrome，天然携带登录态。**不主动操作用户已有 tab**，所有操作在自己创建的后台 tab 中进行，任务结束关闭自建 tab（保留用户原 tab）。\n\nProxy（`scripts/cdp-proxy.mjs`）由 `check-deps.mjs` 自动拉起并常驻。Proxy 首次启动生成共享密钥 `~/.mipham/skills/web-access/.cdp-token`（0600），除 `/health` 外所有端点都要求请求头 `X-CDP-Token`。先取 token 再调 API：\n\n```bash\nTOKEN=$(cat ~/.mipham/skills/web-access/.cdp-token)\ncurl -H \"X-CDP-Token: $TOKEN\" http://localhost:3456/targets\n```\n\n端点列表：\n\n| 端点                                       | 用途                                                                     |\n| ------------------------------------------ | ------------------------------------------------------------------------ |\n| `GET /targets`                             | 列出已开 tab                                                             |\n| `GET /new?url=`                            | 新建后台 tab（自动等加载）                                               |\n| `GET /navigate?target=&url=`               | 导航（自动等加载）                                                       |\n| `GET /back?target=`                        | 后退                                                                     |\n| `GET /info?target=`                        | 页面标题/URL/状态                                                        |\n| `POST /eval?target=`（body=JS）            | 执行任意 JS（读写 DOM、提取、提交）                                      |\n| `POST /click?target=`（body=CSS 选择器）   | JS 点击（`el.click()`，覆盖大多数场景）                                  |\n| `POST /clickAt?target=`（body=CSS 选择器） | 真实鼠标点击（`Input.dispatchMouseEvent`，算用户手势，能触发文件对话框） |\n| `POST /setFiles?target=`（body JSON）      | 设置 file input 本地文件路径（`DOM.setFileInputFiles`，绕过文件对话框）  |\n| `GET /scroll?target=&y=&direction=`        | 滚动（`direction=down/up/top/bottom`，触发懒加载）                       |\n| `GET /screenshot?target=&file=`            | 截图                                                                     |\n| `GET /close?target=`                       | 关闭 tab                                                                 |\n\n进入浏览器层后，`/eval` 是眼睛、`/click` 是手：先看 DOM 结构再决定下一步，不预先规划所有步骤。\n\n### 登录判断\n\n核心问题只有一个：**目标内容拿到了吗？** 打开页面先尝试获取目标内容；确认「目标内容无法获取」且判断登录能解决时，告知用户在其 Chrome 登录后继续（无需重启任何东西，刷新页面即可）。\n\n### 媒体资源提取\n\n判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL 定向读取，比全页截图精准。`/scroll` 到底部触发懒加载后再提取图片 URL。\n\n### 视频内容获取\n\n用户 Chrome 真实渲染，截图可捕获当前视频帧。用 `/eval` 操控 `<video>`（时长、seek、播放/暂停），配合 `/screenshot` 采帧，做离散采样分析。\n\n## 本地 Chrome 资源\n\n用户指向「本人访问过的页面」或「组织内部系统」时，检索本地书签/历史：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/find-url.mjs [关键词...] [--only bookmarks|history] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]\n```\n\n## 并行调研：子 Agent 分治\n\n多个独立调研目标时，分治给子 Agent 并行执行（共享一个 Chrome、一个 Proxy，各自建 tab、各自 `/close`，无竞态）。子 Agent prompt 写**目标**（「获取/调研/了解」），不写**手段**（避免「搜索xx」锚定到 WebSearch 而错过需 CDP 的反爬站点）。\n\n## 信息核实\n\n核实目标是一手来源，非二手报道。搜索引擎是**定位**工具，不可直接**证明**真伪；找到来源后直接访问读原文。\n\n| 信息类型      | 一手来源       |\n| ------------- | -------------- |\n| 政策/法规     | 发布机构官网   |\n| 企业公告      | 公司官方新闻页 |\n| 工具能力/用法 | 官方文档、源码 |\n\n### 交叉验证\n\n- 关键声明须 2+ 独立来源交叉印证。\n- 优先采纳当年/近期资料。\n- 权威层级：官方文档 > 知名博客 > 技术社区 > 随机论坛。\n\n### 来源归因\n\n回答结尾附来源列表：\n\n```markdown\nSources:\n\n- [标题](URL) — 一句话说明\n```\n\n## 站点经验\n\n特定网站经验按域名存 `~/.mipham/skills/web-access/references/site-patterns/<domain>.md`（frontmatter: domain/aliases/updated + 平台特征/有效模式/已知陷阱）。操作前若有匹配经验先读；操作成功后把验证过的新模式写回。\n\n## Security Rules\n\n- 不主动操作用户已有 tab；任务结束关闭自建 tab。\n- 不提交凭据（除非用户显式批准）。\n- 尊重 robots.txt 与速率限制；不抓 PII。\n- proxy 仅绑 127.0.0.1，不暴露外网；除 `/health` 外所有端点要求 `X-CDP-Token` 共享密钥（`~/.mipham/skills/web-access/.cdp-token`，0600），防浏览器 CSRF 到 localhost。勿在共享/多用户主机运行。\n- URL 过窄 SSRF 校验：拒绝非 http(s)/about 协议与云元数据端点（`169.254.169.254` / `metadata.google.internal`）。⚠️ 私有网段（10.x / 172.16 / 192.168 / localhost）**有意放行**——本工具用途即访问组织内网（SSO 后台/内部系统），与 web-fetch 的完整 SSRF 屏蔽不同。\n\n## 何时不用本 skill\n\n- 纯逻辑/算法题（推理非研究）。\n- 代码已在上下文里的问题。\n- 大文件下载 → Bash + curl。\n" },
   { type: 'standard', raw: "---\nname: web-search\ndescription: Search the web for current information — documentation, news, technical references, troubleshooting, and research. Routes queries through Brave Search API with domain filtering and source verification.\nversion: 3.0.0\nuser-invocable: true\nallowed-tools:\n  - WebSearch\n  - WebFetch\n---\n\n# Web Search — Executable Workflow\n\n**Type**: Flexible — follow the query construction rules strictly, then adapt verification depth to the task.\n\n**Purpose**: Find accurate, current information from the web. This skill covers query formulation, domain filtering, result verification, and when to follow up with WebFetch for deep reading.\n\n**Triggers**: \"search for\", \"look up\", \"find\", \"what is\", \"how to\", \"latest\", \"current\", \"news about\", \"documentation for\", \"research\"\n\n---\n\n## Phase 0: Decide Whether to Search (ALWAYS RUN FIRST)\n\n```\nQuestion involves...\n├── Current events, news, recent releases?\n│   └── YES → Search (model training cutoff limitation)\n│\n├── Library/framework documentation?\n│   └── YES → Search (version-specific, up-to-date)\n│\n├── Error messages, stack traces?\n│   └── YES → Search (known issues, fixes)\n│\n├── Technology comparisons, benchmarks?\n│   └── YES → Search (current data)\n│\n├── Pure logic, algorithms, math?\n│   └── NO → Reason directly (no external data needed)\n│\n├── Question answerable from code in context?\n│   └── NO → Use existing context (faster, no network)\n│\n└── Opinion / subjective?\n    └── MAYBE → Search for data points, not consensus\n```\n\n---\n\n## Phase 1: Construct the Query\n\n### Rules (apply in order)\n\n1. **Be specific**: include version numbers, dates, proper nouns\n2. **Use technical terms**: framework/language jargon over natural language\n3. **Include context**: OS, environment, constraints if relevant\n4. **English preferred**: technical content is richer in English\n\n### Examples\n\n```\n❌ \"React\"                                → too broad\n❌ \"React problems\"                       → ambiguous\n❌ \"how to make website fast\"             → natural language\n✅ \"React 19 useEffect double mount fix\"  → specific + versioned\n✅ \"Core Web Vitals LCP optimization Next.js 14\"\n✅ \"Prisma 5 findMany nested include filter TypeScript\"\n✅ \"playwright click button not working 2026\"\n```\n\n### For Chinese-Language Queries\n\nChinese queries work but yield fewer technical results:\n\n```\n✅ \"React 19 useEffect 执行两次 修复\"     → mixed language for best results\n✅ \"Vue 3 Composition API 最佳实践 2026\"\n```\n\n---\n\n## Phase 2: Filter & Verify Results\n\n### Domain Authority Tiers\n\n| Tier              | Domains                                                               | Weight  |\n| ----------------- | --------------------------------------------------------------------- | ------- |\n| **Official**      | docs.github.com, nextjs.org, nodejs.org, python.org, rust-lang.org    | Highest |\n| **Authoritative** | developer.mozilla.org, web.dev, kubernetes.io                         | High    |\n| **Trusted**       | stackoverflow.com (high-score), dev.to, medium.com (verified authors) | Medium  |\n| **Low**           | personal blogs, random forums, w3schools                              | Low     |\n\n### Use allowed_domains for targeted searches\n\n```json\n{ \"query\": \"Next.js caching\", \"allowed_domains\": [\"nextjs.org\", \"github.com\"] }\n```\n\n### Use blocked_domains to exclude noise\n\n```json\n{ \"query\": \"JavaScript array methods\", \"blocked_domains\": [\"w3schools.com\"] }\n```\n\n### Cross-Reference Rule\n\n- **Critical claims** (API behavior, security): 2+ independent sources\n- **Code examples**: test before recommending\n- **Version info**: check publish date (prefer current year)\n\n---\n\n## Phase 3: Deep Read (When Needed)\n\nAfter search returns results, decide whether to deep-read:\n\n```\nSearch result looks promising?\n├── Snippet answers the question fully?\n│   └── → Use snippet + cite source (done)\n│\n├── Need code examples / detailed API docs?\n│   └── → WebFetch the page URL\n│       Use prompt to focus extraction\n│\n├── Multiple sources needed for verification?\n│   └── → WebFetch top 2-3 results\n│       Cross-reference and flag contradictions\n│\n└── Page is JavaScript SPA / login-walled?\n    └── → Delegate to web-access skill (ComputerUse browser)\n```\n\n---\n\n## Phase 4: Report Results\n\n### Format\n\n```markdown\n## [Topic]\n\n[Answer with inline citations]\n\n### Details (if deep-read was done)\n\n[Structured content from fetched pages]\n\nSources:\n\n- [Title](URL) — [1-sentence note on what was found there]\n- [Title](URL) — [1-sentence note]\n```\n\n### Attribution Rules\n\n- Always include source URLs\n- Note if a source is official docs vs community\n- Flag outdated content (e.g., \"article from 2024, may be stale\")\n- Distinguish between facts (need citation) and reasoning (your own)\n\n---\n\n## Search API Configuration\n\nWeb search uses **Brave Search API** (free tier: 2,000 queries/month).\n\nIf search returns \"not configured\":\n\n1. Get a free API key at https://brave.com/search/api/\n2. Set: `export BRAVE_API_KEY=\"BSA...\"`\n3. Restart Mipham Code\n\nAlternatives (additional API keys supported):\n\n- `TAVILY_API_KEY` — https://tavily.com\n- `SERPAPI_API_KEY` — https://serpapi.com\n" },
   { type: 'mipham', raw: "---\nname: doc-sync\ndescription: Keep engineering truth docs aligned with code — map changed code to docs, update stale docs after functional changes, keep git-reviewable\nversion: 1.0.0\n---\n\n# Doc Sync\n\nKeep engineering \"truth docs\" aligned with code. After a functional code change, run this skill to find the docs that map to the changed code, check them against the code + tests, and update anything that drifted. Docs travel with the branch in git and are reviewed alongside the code diff.\n\n## Where truth docs live\n\nEngineering truth docs live under `docs/truth/engineering/`. Routing from code → docs lives in `docs/truth/ROUTES.md`.\n\n```\ndocs/truth/\n├── ROUTES.md            # code area → canonical doc mapping\n└── engineering/\n    ├── behaviors/       # implementation behavior\n    ├── contracts/       # API / interface contracts\n    ├── architecture/    # component structure and boundaries\n    ├── workflows/       # multi-step flows and orchestration\n    └── operations/      # runbooks, config, deployment\n```\n\n## Invariants (never break)\n\n- **Doc-only**: touch `docs/truth/**` and `ROUTES.md` only. Never modify functional code, tests, or config outside `docs/truth/`.\n- **Evidence-backed**: every claim cites `file:line` (or `file` for a whole file). No invented behavior.\n- **Branch-scoped**: docs change in the same branch as the code, so they review together.\n\n## Workflow\n\n### 1. Map — find the docs that cover the change\n\nDetermine the changed code. Prefer an explicit path argument; otherwise use the working-tree or branch diff:\n\n```bash\ngit diff --name-only            # uncommitted working-tree changes\ngit diff --name-only HEAD~1     # last commit\n```\n\nRead `docs/truth/ROUTES.md` and match the changed paths to their canonical doc. A route is a glob → doc path pair. A changed path with no route is a signal to create one (Step 3).\n\n### 2. Check — is the doc now stale?\n\nFor each mapped doc, read the doc, the changed code, and the relevant tests. Compare:\n\n- Does the doc describe behavior the code no longer has?\n- Does the code add or remove behavior the doc doesn't mention?\n- Do contract shapes (signatures, types, errors) still match?\n- Are the `file:line` evidence pointers still valid?\n\nA doc is stale when any claim no longer matches the code + tests.\n\n### 3. Update — fix the drift\n\n- **Existing doc, stale**: edit the doc in place. Update claims, refresh `file:line` pointers, remove dead behavior, add new behavior. Keep the section structure unless the change demands otherwise.\n- **Existing doc, orphaned**: if the mapped code is gone, remove the doc and its route entry.\n- **Changed path has no route**: create one bounded doc under the right `docs/truth/engineering/<type>/` folder and add a route entry to `ROUTES.md`. Scope the doc to the changed area — do not document the whole codebase.\n\nKeep the diff minimal and reviewable: one doc per functional change, no unrelated rewrites.\n\n### 4. Verify — reviewable and true\n\nConfirm before reporting done:\n\n- `git diff --stat` shows only `docs/truth/**` and `ROUTES.md`.\n- Every claim in the updated doc has a `file:line` pointer that exists in the working tree.\n- The doc matches the code + tests, not the other way around.\n\nReport: \"Updated <doc> for <change>. Review the truth diff alongside the code diff.\"\n\n## Document templates\n\n### Behavior (`behaviors/`)\n\n```markdown\n# <Behavior Name>\n\n**Area**: <route / component>\n**Evidence**: `src/<file>:<line>`\n\n## What it does\n\n<one-paragraph summary, from code + tests>\n\n## Behavior\n\n- <observable behavior> — `src/<file>:<line>`\n\n## Edge cases\n\n- <case> — `src/<file>:<line>`\n\n## Tests\n\n- `tests/<file>.test.ts` — covers <behavior>\n```\n\n### Contract (`contracts/`)\n\n```markdown\n# <API / Interface>\n\n**Evidence**: `src/<file>:<line>`\n\n## Signature\n\n\\`\\`\\`ts\n// the actual exported signature\n\\`\\`\\`\n\n## Parameters\n\n| Param | Type | Description |\n| ----- | ---- | ----------- |\n\n## Returns / Errors\n\n- ...\n\n## Consumers\n\n- <caller> — `src/<file>:<line>`\n```\n\n### Architecture (`architecture/`)\n\n```markdown\n# <Component / Module>\n\n**Evidence**: `src/<file>`\n\n## Responsibility\n\n<one paragraph — what it owns, what it doesn't>\n\n## Dependencies\n\n- depends on: <...>\n- depended on by: <...>\n\n## Boundaries\n\n- <seam / interface> — `src/<file>:<line>`\n```\n\n### Workflow (`workflows/`)\n\n```markdown\n# <Workflow Name>\n\n**Evidence**: `src/<file>:<line>`\n\n## Steps\n\n1. <step> — `src/<file>:<line>`\n\n## Trigger / Exit\n\n- trigger: <...>\n- success: <...> / failure: <...>\n```\n\n### Operations (`operations/`)\n\n```markdown\n# <Runbook / Config>\n\n**Evidence**: `src/<file>`\n\n## Config / Env\n\n| Key | Default | Meaning |\n| --- | ------- | ------- |\n\n## Runbook\n\n- <action> — <command or step>\n\n## Failure modes\n\n- <symptom> → <cause> → <fix>\n```\n\n## Routing file (`ROUTES.md`)\n\n```markdown\n# Truth Routes\n\n| Code pattern      | Doc                                      |\n| ----------------- | ---------------------------------------- |\n| src/auth/session* | engineering/behaviors/session-timeout.md |\n| src/api/*         | engineering/contracts/api.md             |\n```\n\nPatterns are globs relative to the repo root. One doc may be routed by several patterns; one pattern maps to one doc. Keep patterns as specific as needed to avoid one giant doc.\n" },
   { type: 'mipham', raw: "---\nname: om-artifact\ndescription: Mipham Artifacts — create interactive HTML/SVG dashboards, reports, and visualizations the user can view in their browser\nversion: 1.0.0\n---\n\n# Mipham Artifacts Skill\n\nCreate interactive browser-viewable artifacts from conversation output. Use the `Artifact` tool to save standalone HTML or SVG files that the user opens with `/artifact open <name>`.\n\n## When to Use Artifact vs Write\n\n| Artifact                                     | Write                                            |\n| -------------------------------------------- | ------------------------------------------------ |\n| Visual output (charts, dashboards, diagrams) | Source code files                                |\n| Interactive HTML demos                       | Configuration files                              |\n| Styled reports with CSS                      | Documentation (.md)                              |\n| SVG graphics and visualizations              | Data files (.json, .csv)                         |\n| Anything the user wants to SEE in a browser  | Anything the user wants to EDIT in a text editor |\n\n**Ask yourself**: \"Would this be better viewed in a browser than in a terminal or text editor?\" If yes, use Artifact.\n\n## Artifact Guidelines\n\n### Content Requirements\n\n- **Self-contained only**: All CSS and JS must be inline. No CDN links, no external fonts, no network requests. The CSP policy blocks all external resources.\n- **Size limit**: 5MB maximum. Aim for under 500KB for good performance.\n- **Artifact types**: `html` (full HTML pages) or `svg` (standalone SVG graphics)\n\n### Naming\n\n- Use short kebab-case names: `user-dashboard`, `pipeline-diagram`, `pr-diff-review`\n- The name becomes the filename: `user-dashboard.html`\n\n### Styling\n\n- Use inline `<style>` blocks in the HTML head\n- Dark theme recommended (matches Mipham Code aesthetic)\n- Responsive design where practical\n- Clean, professional look — this is user-facing output\n\n## Good Artifact Examples\n\n1. **Data dashboard**: Query results rendered as tables, charts (inline Chart.js data via canvas), metrics cards\n2. **Diff viewer**: Side-by-side code comparison with syntax highlighting\n3. **Report**: Structured markdown rendered as styled HTML with TOC\n4. **Timeline**: Event sequence visualization with expandable sections\n5. **Network graph**: Interactive node-edge visualization (D3 or vis.js inline)\n6. **Architecture diagram**: Components and connections with color coding\n7. **Test results**: Pass/fail grid with expandable failure details\n\n## Artifact Lifecycle\n\n1. AI creates artifact via `Artifact` tool → saved to `.mipham/artifacts/<session>/<name>.html`\n2. Tool returns the localhost URL\n3. User opens with `/artifact open <name>` → browser displays it\n4. User lists all artifacts with `/artifact list`\n5. Server runs on `http://localhost:9876` by default\n\n## Prompting the User\n\nAfter creating an artifact, always tell the user:\n\n- The artifact name\n- The URL\n- That they can open it with `/artifact open <name>`\n\nExample: \"I've created a dashboard artifact. Open it with `/artifact open dashboard`\"\n" },

package/src/tools/agent/exit-plan.ts

@@ -1,5 +1,4 @@
 import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
 import type { ToolDefinition } from '../../shared/index.ts'
 
 export const exitPlanModeTool: ToolDefinition = {
@@ -22,8 +21,7 @@ export const exitPlanModeTool: ToolDefinition = {
     },
     required: [],
   },
-  async execute(params, ctx) {
-    const planDir = join(ctx.cwd, '.mipham', 'plans')
+  async execute(params, _ctx) {
     const planFile = (params.planFile as string) || ''
 
     // Try to read the plan to confirm it exists

package/src/tools/agent/memory.ts

@@ -1,8 +1,9 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import { homedir } from 'node:os'
 import type { ToolDefinition } from '../../shared/index.ts'
 
-const MEMORY_DIR = join(process.env.HOME || '~', '.mipham', 'memory')
+const MEMORY_DIR = join(homedir(), '.mipham', 'memory')
 
 /**
  * Format a memory file with frontmatter, compatible with MemoryManager.parseMemoryFile.