Frontend Scout

Frontend Scout — 前端接口侦察

触发条件

当用户提出以下任一需求时触发：

• 问某个接口在哪里调用、入参从哪来、出参怎么用
• 问某个页面的完整接口调用
• 问整个项目有哪些页面和接口
• 提供 PRD 或变更需求，要求分析影响范围
• 前后端方案对齐场景

工作模式选择

按以下规则判断走哪种模式：

• 用户问单个接口且调用点 = 5 处），或多个接口，或页面分析，或全项目摸底 → 报告模式，生成完整报告
• 用户输入 PRD / 变更需求 → PRD 分析模式，生成变更影响报告
• 用户明确要求"梳理/分析/报告" → 报告模式
• 调用点 3-5 处之间 → Q&A 模式，但末尾提示用户是否需要转为完整报告

Q&A 模式支持多轮对话：记住会话中讨论过的接口和页面，后续用户用代词指代时自动关联。

🔴 CHECKPOINT · 模式选择后：确认模式后进入对应工作流。如果用户中途改变需求（从查单个接口变为全模块梳理），重新判断模式。

受众对象判断

输出前先判断受众。判断策略按模式区分：

Q&A 模式：默认不询问

• 谁问的通常就是谁用 → 默认面向前端开发（提问者本人）
• 如果用户明确指定了受众（如"帮后端同事看一下"），则按指定受众处理
• Q&A 模式中不主动询问用户受众，直接按前端视角输出
• 用户可随时纠正："这不是给我看的，是给后端看的" → 重新按指定受众加载参考文件

报告模式 & PRD 分析模式：语义推断 + 人工确认

1. 语义推断：

• 提到"后端需要改什么"、"接口约定"、"字段枚举" → 面向后端
• 提到"用户体验"、"按钮在什么情况下显示"、"交互路径" → 面向产品
• 提到"怎么测"、"谁的问题"、"前后端责任" → 面向测试
• 提到"组件结构"、"props"、"组件树"、"组件实现" → 面向前端
• 提到"影响范围"、"变更分析"、"需要改哪些" → 面向后端 + 产品

1. 🛑 STOP · 无法推断时，停下来询问用户：

> 这份报告主要给谁看？我可以针对性地调整内容侧重： > > - 后端开发 — 接口约定、入参出参、职责划分 > - 产品经理 — 业务逻辑还原、交互路径 > - 测试人员 — 责任主体标注、重点验证点 > - 前端开发 — 组件树、Props/事件、API 调用点 > - 全都要 — 一份报告覆盖所有视角

1. 确定受众后，加载对应的参考文件：

• 面向后端 → 读取 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 项目查路由 ` 或 pages/`

追溯链路

从调用文件沿 import 反向追溯到页面入口：

1. 找到调用点所在文件
2. 查看该文件被哪些父组件引用（搜索 import 语句）
3. 递归向上，直到找到路由配置中的页面入口
4. 组件渲染条件分析：如果接口调用位于子组件中，逐层检查每个父组件引入该子组件时的渲染条件（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 模式

工作流程

1. 解析问题 — 提取目标接口/字段、问题类型（定位/入参/出参/对比/字段溯源）
2. 全局搜索 — 搜索接口路径，定位所有调用点。如果搜索未命中 → 走「搜索阶段失败」兜底
3. 追溯链路 — 从每个调用点追溯到页面入口。如果追溯中断 → 走「追溯链路断裂」兜底
4. 分析上下文 — 分析触发时机、入参来源、出参消费。如果字段含义无法推断 → 走「字段含义无法推断」兜底
5. 检查接口间关联 — 该接口返回字段是否被其他接口用作入参
6. 合规性自检 — 逐条检查输出是否符合禁止事项和必须做到
7. 🔴 CHECKPOINT · 输出前自检 — 逐条检查禁止事项和必须做到，确认无误后输出
8. 输出最终答案

输出格式

按用户操作生命周期组织，不用表格。格式模板见 templates/qa-output.md。

末尾附上前端参考附录。

报告模式

工作流程

1. 确定范围 — 单个接口 / 多个接口 / 单个页面 / 多个页面 / 全项目
2. 并行搜索：

• 多个接口 → 每个接口分配一个 sub-agent 独立搜索。如果 sub-agent 失败 → 走「Sub-agent 协同失败」兜底
• 全项目范围 → 先通过路由发现所有页面，再按页面分配 sub-agent
• 单个页面 → 从页面入口递归探索依赖

1. 合并结果 — 收集所有 sub-agent 结果，去重，补充跨接口/跨页面关联
2. 确定受众 — 如果语义推断失败 → 走受众询问流程
3. 生成草稿 — 按受众组织报告结构并生成草稿
4. 🔴 CHECKPOINT · 输出前自检 — 逐条检查：① 是否有代码术语 ② 是否按生命周期排序 ③ 枚举值是否完整 ④ 不确定项是否标注
5. 输出 — 默认打印到对话，用户可指定保存为 Markdown 文件等

报告结构

使用 templates/report.md 中的结构。

按受众调整内容侧重

已在确定受众后加载了对应的参考文件（见「受众对象判断」步骤 3），按参考文件中的结构组织报告内容。

如果受众为「全都要」，按后端 → 产品 → 测试 → 前端的顺序合并输出，每个受众章节独立成节。

PRD 分析模式

用户输入 PRD 内容或提出"帮我分析这个需求"时进入此模式。

工作流程

1. 提取变更 — 阅读 PRD，提取涉及的业务场景、功能点、变更描述。如果描述过于模糊无法分析 → 走「PRD 描述模糊」兜底（反问用户补充以下信息）：

• 涉及哪个页面？（页面名称或路由路径）
• 新增还是修改已有功能？
• 是否有接口路径或字段名参考？
• 是否有附图或原型？

如果反问后用户仍无法提供 → 按现有信息输出待确认清单： ``` ### 待确认清单

• {变更项 1}：{现有信息} → 待确认：{需要补充什么}
• {变更项 2}：{现有信息} → 待确认：{需要补充什么}

```

1. 搜索映射 — 根据业务描述在项目代码中搜索对应页面和接口：

• 从业务名词出发搜索相关页面路由。如果找不到匹配页面 → 走「找不到页面入口」兜底
• 从页面入口追溯接口调用
• 对变更描述匹配现有接口的出参/入参字段。如果字段含义无法推断 → 走「字段含义无法推断」兜底

1. 标记变更类型 — 逐项标记：

• 新增功能 → 定位受影响页面和接口，标记为新接入点
• 字段新增 → 标注 【需新增字段】
• 字段语义变化 → 标注 【⚠️ 字段语义变更，需确认前端适配】
• 枚举值扩展 → 标注 【需扩展枚举值】
• 接口废弃/替换 → 标注 【🚫 接口废弃，前端需迁移至新接口 xx】

1. 默认面向后端 + 产品，如需测试视角则询问
2. 🛑 STOP · 生成报告前 — 确认所有变更项已标记、受众已确定，再生成
3. 生成变更影响报告
4. 合规性自检

报告结构见 templates/prd-report.md。

验证与合规性自检

每次输出最终版本前执行：

1. 合规性 — 按当前受众对应的禁止事项表检查：

• 面向产品/测试 → 检查是否混入技术术语（文件名、代码名、框架概念）
• 面向后端/前端 → 检查是否缺失必要的技术细节，字段名是否保留原名
• 所有受众 → 检查是否有代码块/表格

1. 准确性 — 不确定的推断标注"推断"/"未推断出"，不猜测
2. 受众适配 — 输出内容是否针对当前受众做了侧重调整？是否加载了正确的参考文件？

前端参考附录

报告输出时使用 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 搜索结果、中间数据、草稿等），最终输出完成后必须删除。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gaorun
• Source: gaorun/my-labs
• License: MIT

Install and usage instructions live in the source repository linked above.