| name | frontend-scout |
| description | 从前端代码中定位后端接口的使用情况、分析页面与接口的关联、生成面向不同角色的接口分析报告。当用户问到某个接口在哪些地方有调用、入参/出参如何被使用、页面调了哪些接口、字段与接口的对应关系、接口调用链路、页面接口发现报告时触发。也适合在开发前做方案对齐时使用，输入 PRD 或变更需求后自动分析影响范围。还能分析整个前端项目的架构和接口全景。使用场景包括：接口反向溯源、页面接口发现、全项目接口摸底、前后端方案对齐、PRD 变更影响分析。适合后端、测试、产品同学了解前端接口使用全貌。 |
Frontend Scout — 前端接口侦察
触发条件
当用户提出以下任一需求时触发：
- 问某个接口在哪里调用、入参从哪来、出参怎么用
- 问某个页面的完整接口调用
- 问整个项目有哪些页面和接口
- 提供 PRD 或变更需求，要求分析影响范围
- 前后端方案对齐场景
工作模式选择
按以下规则判断走哪种模式：
- 用户问单个接口且调用点 <= 3 处 → Q&A 模式，直接回答，不生成文件
- 用户问单个接口但调用点多（>= 5 处），或多个接口，或页面分析，或全项目摸底 → 报告模式，生成完整报告
- 用户输入 PRD / 变更需求 → PRD 分析模式，生成变更影响报告
- 用户明确要求"梳理/分析/报告" → 报告模式
- 调用点 3-5 处之间 → Q&A 模式，但末尾提示用户是否需要转为完整报告
Q&A 模式支持多轮对话：记住会话中讨论过的接口和页面，后续用户用代词指代时自动关联。
🔴 CHECKPOINT · 模式选择后：确认模式后进入对应工作流。如果用户中途改变需求（从查单个接口变为全模块梳理），重新判断模式。
受众对象判断
输出前先判断受众。判断策略按模式区分：
Q&A 模式：默认不询问
- 谁问的通常就是谁用 → 默认面向前端开发（提问者本人）
- 如果用户明确指定了受众（如"帮后端同事看一下"），则按指定受众处理
- Q&A 模式中不主动询问用户受众，直接按前端视角输出
- 用户可随时纠正："这不是给我看的，是给后端看的" → 重新按指定受众加载参考文件
报告模式 & PRD 分析模式：语义推断 + 人工确认
-
语义推断：
- 提到"后端需要改什么"、"接口约定"、"字段枚举" → 面向后端
- 提到"用户体验"、"按钮在什么情况下显示"、"交互路径" → 面向产品
- 提到"怎么测"、"谁的问题"、"前后端责任" → 面向测试
- 提到"组件结构"、"props"、"组件树"、"组件实现" → 面向前端
- 提到"影响范围"、"变更分析"、"需要改哪些" → 面向后端 + 产品
-
🛑 STOP · 无法推断时，停下来询问用户：
这份报告主要给谁看？我可以针对性地调整内容侧重：
- 后端开发 — 接口约定、入参出参、职责划分
- 产品经理 — 业务逻辑还原、交互路径
- 测试人员 — 责任主体标注、重点验证点
- 前端开发 — 组件树、Props/事件、API 调用点
- 全都要 — 一份报告覆盖所有视角
-
确定受众后，加载对应的参考文件：
- 面向后端 → 读取
references/audience-backend.md
- 面向产品 → 读取
references/audience-product.md
- 面向测试 → 读取
references/audience-testing.md
- 面向前端 → 读取
references/audience-frontend.md
- 全都要 → 读取以上全部 4 个文件
输出约束
禁止事项
- ❌ 代码片段和反引号代码块
- ❌ 技术实现描述（"通过展开运算符混入到 query 参数中"）
- ❌ Markdown 表格（因复制到 IM 工具会变形）
禁止事项（按受众区分）
以下约束并非全局禁用，而是根据受众调整：
| 约束 | 后端开发 | 产品经理 | 测试人员 | 前端开发 |
|---|
文件名/路径（如 io.js） | ✅ 允许 | ❌ 禁止 | ❌ 禁止 | ✅ 允许 |
函数名/变量名（如 fetchData） | ✅ 允许 | ❌ 禁止 | ❌ 禁止 | ✅ 允许 |
| 前端框架概念（组件、mounted、Vuex） | ⚠️ 仅在必要时使用 | ❌ 禁止 | ❌ 禁止 | ✅ 允许 |
代码条件表达式（type === 3） | ⚠️ 需同时写出业务含义 | ❌ 禁止 | ⚠️ 允许 | ⚠️ 需同时写出业务含义 |
规则：对于后端和前端受众，保留技术细节（文件名、字段名、函数名）并附加业务说明。对于产品和测试受众，一律翻译为纯业务语言。
例外：前端参考附录不受本约束限制。
关于表格的强制替代方案：凡是有多行多列对应关系的数据（如事件映射、状态码枚举、接口返回字段对照等），一律用列表格式，不要用表格。
反面案例（有表格）：
| 用户操作 | 回传事件 | 附带数据 |
|---|
| 密码正确 | success | token |
正确做法（用列表）：
- 密码正确时 → 回传 success 事件，携带 token
- 点击关闭时 → 回传 close 事件，无附带数据
- 跳转其他页面时 → 回传 switch 事件
必须做到
- ✅ 业务语言翻译：不说"组件 mounted 时调用"，说"用户进入页面时自动加载"。但对后端/前端受众，可附加技术标注："用户进入页面时自动加载（文件：xxx.vue，mounted 中调用 fetchList）"
- ✅ 大白话风格：像给同事口头解释
- ✅ 按用户操作生命周期排序：页面加载 → 用户操作 → 结果反馈/弹窗 → 页面离开
- ✅ 保留技术原名并附加业务说明：如字段
orderStatus 保留原名，附加"订单状态"中文说明。对产品和测试受众则只说"订单状态"
- ✅ 魔法数字（如
status === 3）：写出数字值，标注"需与后端确认含义"
- ✅ 枚举值展示完整映射：如
0=待审核, 1=已通过, 2=已拒绝
- ✅ 空值兜底说明：后端不下发/下发空值时前端做什么
- ✅ 动态参数留占位符：
/api/order/:id 保留 :id
- ✅ 后端动态配置驱动的 UI：识别并说明模式，不猜测具体内容
- ✅ 不确定信息标注"未推断出"，不猜测
- ✅ 复杂逻辑或接口参数传递链用 Mermaid 流程图
搜索策略
全局搜索
- 接口路径搜索：搜索完整路径或路径片段
- 字段名搜索：搜索响应字段在代码中的消费模式（赋值、渲染、条件判断）
- HTTP 调用模式：搜索
axios.get/post、request(、fetch(、服务名.api.xxx
- 页面入口判断：Vue 项目查
src/views/ 或路由 component；React 项目查路由 <Route> 或 pages/
追溯链路
从调用文件沿 import 反向追溯到页面入口：
- 找到调用点所在文件
- 查看该文件被哪些父组件引用（搜索 import 语句）
- 递归向上，直到找到路由配置中的页面入口
- 组件渲染条件分析：如果接口调用位于子组件中，逐层检查每个父组件引入该子组件时的渲染条件（v-if、弹窗/抽屉条件、标签页切换），合并为完整的触发条件描述
搜索范围
- 只搜索当前项目，不越界
- 跳过 node_modules
- 项目级公共 API 封装（如
@/api/xxx.ts）：追溯到该模块并记录实际请求路径，不展开内部
- 微服务名作为搜索前缀：以微服务名为前缀搜索所有接口
异常处理与兜底策略
每个工作流的搜索阶段和分析阶段都可能失败。以下表格定义了各场景的触发条件、一线修复措施和仍失败的兜底行为。
搜索阶段失败
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|
| 全局搜索未找到接口路径或字段名 | 去掉前后缀/版本号/微服务名前缀再次搜索；搜索完整路径的后半段或关键字片段 | 告知用户"代码中未找到该接口的直接调用"，列出可能原因：① 接口路径写法不同（如大小写、下划线）② 通过动态拼接生成 ③ 前后端尚未联调。建议用户提供更精确的路径片段 |
| 追溯链路断裂（import 链中断，无法追溯到页面入口） | 搜索文件名关键特征或在相近目录就近搜索；尝试搜索路由配置中关联的组件名 | 只输出已追溯到的部分，在报告中标注"【⚠️ 部分链路断裂，以下为不完全分析】"，附上已找到的调用位置供手动对照 |
| 找不到页面入口（路由配置中无匹配项） | 按目录结构从调用文件向上回溯 2-3 层；搜索与文件路径关键词匹配的路由定义 | 确认调用文件路径但不关联页面，标注"【⚠️ 未找到路由配置，以下仅展示调用点，未关联页面】" |
分析阶段失败
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|
| PRD 描述过于模糊，无法映射到具体代码 | 反问用户补充关键信息：涉及哪个页面、新增还是修改、是否有接口路径或字段参考 | 按需求拆解输出"待确认清单"，按页面/功能列每个待确认项，标注"【需确认】"并建议用户补充后再分析 |
| 接口返回字段含义无法从代码推断 | 搜索该字段在其他文件的消费上下文（赋值、渲染、判断）；搜索附近的中文文案或注释 | 标注"【⚠️ 字段含义需与后端确认】"，保留字段名（如有）供后续定位 |
| 枚举值映射找不到完整定义 | 搜索附近常量/枚举定义文件；搜索该枚举值在模板中的展示文案 | 输出已找到的部分映射，标注"【⚠️ 仅部分枚举值，缺失值需与后端确认】" |
Sub-agent 协同失败
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|
| 某 sub-agent 超时或未返回结果 | 主 agent 自行搜索该接口/页面，限制搜索范围到关键文件 | 跳过该接口/页面，在报告中标注"【⚠️ 该部分因 {原因} 跳过，建议手动确认】" |
| Sub-agent 返回内容含代码/文件名（违反输出约束） | 主 agent 清洗后使用，原内容写入前端参考附录 | 要求该 sub-agent 重新输出；仍不合格则主 agent 自行处理 |
Q&A 模式
工作流程
- 解析问题 — 提取目标接口/字段、问题类型（定位/入参/出参/对比/字段溯源）
- 全局搜索 — 搜索接口路径，定位所有调用点。如果搜索未命中 → 走「搜索阶段失败」兜底
- 追溯链路 — 从每个调用点追溯到页面入口。如果追溯中断 → 走「追溯链路断裂」兜底
- 分析上下文 — 分析触发时机、入参来源、出参消费。如果字段含义无法推断 → 走「字段含义无法推断」兜底
- 检查接口间关联 — 该接口返回字段是否被其他接口用作入参
- 合规性自检 — 逐条检查输出是否符合禁止事项和必须做到
- 🔴 CHECKPOINT · 输出前自检 — 逐条检查禁止事项和必须做到，确认无误后输出
- 输出最终答案
输出格式
按用户操作生命周期组织，不用表格。格式模板见 templates/qa-output.md。
末尾附上前端参考附录。
报告模式
工作流程
- 确定范围 — 单个接口 / 多个接口 / 单个页面 / 多个页面 / 全项目
- 并行搜索：
- 多个接口 → 每个接口分配一个 sub-agent 独立搜索。如果 sub-agent 失败 → 走「Sub-agent 协同失败」兜底
- 全项目范围 → 先通过路由发现所有页面，再按页面分配 sub-agent
- 单个页面 → 从页面入口递归探索依赖
- 合并结果 — 收集所有 sub-agent 结果，去重，补充跨接口/跨页面关联
- 确定受众 — 如果语义推断失败 → 走受众询问流程
- 生成草稿 — 按受众组织报告结构并生成草稿
- 🔴 CHECKPOINT · 输出前自检 — 逐条检查：① 是否有代码术语 ② 是否按生命周期排序 ③ 枚举值是否完整 ④ 不确定项是否标注
- 输出 — 默认打印到对话，用户可指定保存为 Markdown 文件等
报告结构
使用 templates/report.md 中的结构。
按受众调整内容侧重
已在确定受众后加载了对应的参考文件（见「受众对象判断」步骤 3），按参考文件中的结构组织报告内容。
如果受众为「全都要」，按后端 → 产品 → 测试 → 前端的顺序合并输出，每个受众章节独立成节。
PRD 分析模式
用户输入 PRD 内容或提出"帮我分析这个需求"时进入此模式。
工作流程
- 提取变更 — 阅读 PRD，提取涉及的业务场景、功能点、变更描述。如果描述过于模糊无法分析 → 走「PRD 描述模糊」兜底（反问用户补充以下信息）：
- 涉及哪个页面？（页面名称或路由路径）
- 新增还是修改已有功能？
- 是否有接口路径或字段名参考？
- 是否有附图或原型？
如果反问后用户仍无法提供 → 按现有信息输出待确认清单：
### 待确认清单
- **{变更项 1}**：{现有信息} → **待确认**：{需要补充什么}
- **{变更项 2}**：{现有信息} → **待确认**：{需要补充什么}
- 搜索映射 — 根据业务描述在项目代码中搜索对应页面和接口：
- 从业务名词出发搜索相关页面路由。如果找不到匹配页面 → 走「找不到页面入口」兜底
- 从页面入口追溯接口调用
- 对变更描述匹配现有接口的出参/入参字段。如果字段含义无法推断 → 走「字段含义无法推断」兜底
- 标记变更类型 — 逐项标记：
- 新增功能 → 定位受影响页面和接口，标记为新接入点
- 字段新增 → 标注 【需新增字段】
- 字段语义变化 → 标注 【⚠️ 字段语义变更，需确认前端适配】
- 枚举值扩展 → 标注 【需扩展枚举值】
- 接口废弃/替换 → 标注 【🚫 接口废弃，前端需迁移至新接口 xx】
- 默认面向后端 + 产品，如需测试视角则询问
- 🛑 STOP · 生成报告前 — 确认所有变更项已标记、受众已确定，再生成
- 生成变更影响报告
- 合规性自检
报告结构见 templates/prd-report.md。
验证与合规性自检
每次输出最终版本前执行：
- 合规性 — 按当前受众对应的禁止事项表检查：
- 面向产品/测试 → 检查是否混入技术术语（文件名、代码名、框架概念）
- 面向后端/前端 → 检查是否缺失必要的技术细节，字段名是否保留原名
- 所有受众 → 检查是否有代码块/表格
- 准确性 — 不确定的推断标注"推断"/"未推断出"，不猜测
- 受众适配 — 输出内容是否针对当前受众做了侧重调整？是否加载了正确的参考文件？
前端参考附录
报告输出时使用 templates/frontend-appendix.md 中的格式。
Sub-agent 协同
按以下规则拆分子任务：
- 多个接口并行搜索 → 每个接口分配一个 sub-agent
- 全项目摸底 → 至少每 5 个页面分配一个 sub-agent
- PRD 分析 → 按 PRD 中的不同变更项分配 sub-agent
- 单接口跨页面分析 → 按页面分配 sub-agent
协同规则
- 主 agent 负责：解析任务 → 拆分 → 分配 → 合并结果 → 去重 → 组织报告 → 自检 → 输出
- Sub-agent 负责：执行搜索 → 追溯链路 → 分析上下文 → 返回业务语言描述
- 主 agent 合并时检查 sub-agent 结果间交叉引用
- 如果 sub-agent 返回失败 → 走「Sub-agent 协同失败」兜底
- 如果 sub-agent 返回内容含违禁项 → 主 agent 清洗后使用
Sub-agent 提示模板
分配给 sub-agent 时包含：
- 要搜索的接口路径或页面路径
- 搜索策略（接口路径搜索 / 字段搜索 / 页面依赖探索）
- 输出要求：纯业务语言描述，禁止出现文件名、函数名、代码片段
- 调用位置和文件路径另外单独记录（供主 agent 合并到前端参考附录）
清理规则
分析过程中产生的中间文件（sub-agent 搜索结果、中间数据、草稿等），最终输出完成后必须删除。
