dev-debug

name	dev-debug
description	启动开发环境 + 调试。触发场景："看一下效果 / 跑起来看看 / 启动一下 / 打开看看 / 启动 dev / 跑 dev"。本 skill 读 profile.devServer 配置 → 校验前置 → 后台 spawn dev server → 等 ready → 拼带 token 的真实域名 URL → open 浏览器。同时含项目特定的"关键调试场景"片段（按 profile 加载）。
allowed-tools	["Bash","Read","Write","Edit"]

dev-debug

把"想看效果 / 调试问题"主动闭环。本 skill 是项目特定的：通用框架在本文，项目特定调试场景在 <profile>.md fragment（如 assist-web.md）—— init 时按 profile 注入对应 fragment。

1. 启动开发环境

触发词

• 「看一下效果」/「跑起来看看」/「启动一下」/「打开看看」
• 「启动 dev」/「跑 dev」/「pnpm dev」
• 「我看看页面」/「browser 打开看下」

启动行为流程

1. 读 profile.devServer 配置（在 .ai/manifest.json 关联的 profile JSON 里）

2. 校验前置（任一缺失先解决）：
   a. /etc/hosts 含 hostsFileEntry → 缺失：引导用户跑 sudo 命令（AI 不主动 sudo）
   b. .env.local（或对应 envFile）存在 → 缺失：prompt 用户创建 + 列必需变量
   c. token 可得：
      - 从已知位置取（用户 memory / .env.local / 历史会话）
      - 都没有 → 「请把 messager userToken / userToken / TOKEN 粘贴给我」

3. background spawn dev server（run_in_background: true）：
   cd <project> && <profile.devServer.command>  # 例如 pnpm dev

4. 等 server ready（30s 超时）：
   - 监听 stdout 含 "Local:" / "ready in" / port 监听确认
   - 30s 没 ready 报错 + 给排查命令

5. 拼 URL（按 profile.devServer.urlTemplate 模板替换）：
   - {host} {port} 直接从 profile 取
   - {token} 从用户输入或已存
   - {shopId} 从 profile.templateVariables.static
   - {route} 智能选择：
     · 扫会话里 AI 用 Edit/Write 改过的文件清单
     · Read profile.devServer.routerFile（实时读 router 配置文件）
     · AI 自己理解：改的文件影响哪个 route
     · 取最相关的 path；找不到用 fallback

6. open <URL>：
   - macOS: `open <URL>`
   - Linux: `xdg-open <URL>`
   - Windows: `start <URL>`

7. 报告：「dev server 启动 + 浏览器打开 https://<host>:<port>/<smart-path>?<params>」

Token 注入策略（永远 URL query）

项目代码本身从 URL query 读 token，自己处理 → localStorage 转存。AI 完全不参与中转，只负责拼正确的 URL：

URL: https://<host>:<port>/<route>?token=xxx&shopId=1069&env=dev
        ↓ 浏览器加载
项目入口 router → 读 ?token=xxx → localStorage.setItem('TOKEN', 'xxx')

砍掉：原计划的 3 种注入方式（query / localStorage / cookie 三选一）+ 临时 .html 文件 + 清理 cron。永远 URL query。

智能 route 选择算法

function selectRoute(changedFiles, routerFile):
  router = Read(routerFile)
  for file in changedFiles (按改动时间倒序):
    # 例：改了 src/pages/Chat/index.tsx → 找 router 里 path 含 "Chat" 或 element 引用 "Chat" 的条目
    candidate = router.find(entry => entry.match(file))
    if candidate:
      return candidate.path
  return profile.devServer.templateVariables.route.fallback  # 默认 home

关键：让 AI 实时读 routerFile，不维护静态 fileToRouteMap（文件改了路由表会失同步）。

2. 关键调试场景

本节内容由项目特定 fragment 提供。 init 时按 profile 注入对应 fragment（<profile>.md），AI 实际看到的是融合后的 SKILL.md。

通用框架部分到这里结束。下一段开始是 profile 特定。

详见同目录下 <profile>.md（如 assist-web.md / qiandao-im.md / resonance.md / chat-assist-mobile.md）。

3. 日志位置

来源	位置
浏览器 console	Chrome DevTools / Edge DevTools Console panel
Network 请求	Chrome DevTools Network panel（开"Preserve log"避免页面跳转丢失）
Hermes WS log	console 里搜 [hermes] / [ws] 前缀；项目通常自己加了 logger
API response	Network panel 看具体请求；项目可能在 store 里 console 打印
Vite HMR log	dev server 终端 stdout
Sentry / 监控	项目接 Sentry 时通过 dashboard 看

4. 调试工具

工具	用法
React DevTools（assist-web / qiandao-im / resonance）	浏览器扩展；看组件树 + props + state
Vue DevTools（chat-assist-mobile）	浏览器扩展；看组件 + Pinia store
Zustand DevTools	集成 Redux DevTools 扩展；看 store action 历史
Pinia DevTools	Vue DevTools 内置标签页
Network panel	必备；看 API 请求 / 响应 / WS 帧
Application > Local Storage	看项目存的 token / shopId / 缓存
WS frames	Network panel 选具体 WS 连接，Frames 标签查推送

5. 改完代码的验证流程

浏览器手测（dev server + open）
  ↓ 看效果对了
unit test（适用时；按 test-assist 触发）
  ↓
e2e test（关键 flow 改动时；4 阶段流水线）
  ↓
imagi check（知识库一致性，不阻断）
  ↓
git-ship 流程（用户确认后）

dev-debug 是手测；test-assist 是自动化。两者互补。手测验"看上去对"，自动化验"行为正确"。

6. 与 test-assist 的关系

• dev-debug = 实时看效果（开发循环里用，手动触发，浏览器看）
• test-assist = 自动化验证（plan-test 流程里用，写 .spec.ts 跑，CI 友好）
• 互相引用、不重复

场景	选哪个
改了 UI 想看效果	dev-debug
改了核心逻辑想验证不破回归	test-assist
复杂任务改完想交付	两个都跑（手测 + 自动化）
调一个具体 bug	dev-debug + console.log + Network panel

7. 关键陷阱（硬约束）

陷阱	处理
host 不能用 localhost	强约束 — CORS / cookie domain / OAuth callback 全依赖真实域名（如 local.qiandao.com、local.echo.tech），用 localhost 会一连串失败
/etc/hosts 缺映射	引导用户跑 sudo sh -c 'echo "127.0.0.1 <host>" >> /etc/hosts'，AI 不主动 sudo
vite dev server 默认 listen localhost	profile 检查 vite.config.ts 含 server.host: "<域名>"，缺失 INFO 提示用户加
超过 30s server 没 ready	报错 + 给排查命令（端口占用？依赖装了吗？build 报错？）
token 用户没传	不要硬启动浏览器 — 先索要 token；空 token 打开页面项目可能直接跳登录
token 过期	引导用户重 login（messager / kyan / 各项目不同入口）
HTTPS dev	项目用 @vitejs/plugin-basic-ssl，浏览器会警告"自签证书"，用户首次需手动信任

8. 反模式（禁止）

• ❌ 自己跑 sudo（让用户跑）
• ❌ 用 localhost 替代真实域名（破坏 CORS / cookie / OAuth）
• ❌ 不读 routerFile 凭空猜 route（用错路由让用户看不到效果）
• ❌ token 还没拿到就启动浏览器（用户看到登录页一脸懵）
• ❌ dev server 卡住反复重启（先看 stdout 报错）
• ❌ 直接在 dev server 终端切别的命令（dev server 是 long-running，应 background）