Frontend Agent

跨平台前端开发 Agent 规范包。它为 Codex、Claude Code 和其他代码 Agent 提供统一规则，并通过一个无外部依赖的 Node.js scanner 生成项目画像和可复用代码索引。

能解决什么问题

• 在修改前识别框架、平台、包管理器、依赖、脚本和验证命令。
• 索引已有 pages、components、hooks、composables、utils、API、stores、styles、directives、plugins 和 locales，并可输出 i18nKeyMap。
• 在 project-profile.json 和 extended summary 中输出 platformEntry，帮助 Agent 先确认跨端项目当前实际入口文件和平台落点，再决定修改位置。
• 在 project-profile.json 和 extended summary 中输出 routePermissionModel，帮助 Agent 先确认 route / guard / menu / permission helper 的入口事实，再决定权限敏感改动的最小回归面。
• 约束 Agent 阅读源码后再复用，减少重复实现和无关重构。
• 使用 impact 命令基于变更文件分析可能波及的模块与页面，结果写入 .agent-cache/frontend/impact.json。
• 在 project-profile.json 和 extended summary 中输出 API Contracts，索引现有 request wrapper、API module、schema、契约文件和 mock 入口，帮助 Agent 先复用已有数据链路，再决定是否新增请求层代码。
• 使用 verify 命令把推荐检查转成可执行验证计划，过滤 watch / fix / write / deploy / publish，并识别可安全执行的预算脚本，把结果写入 .agent-cache/frontend/verify-last.json。
• 读取项目已有的 ESLint、Prettier、Stylelint、Biome、EditorConfig 等规范配置，并在 extended summary 中输出 Code Standards 提示，帮助 Agent 基于现有规范做最小改动。
• 在 project-profile.json 和 extended summary 的 ## Project Onboarding 中输出 runtimeReadiness 事实，帮助 Agent 更快接手 monorepo 或本地运行环境。
• 在 project-profile.json 和 extended summary 的 ## Design System 中输出 designSystem 事实，帮助 Agent 优先复用现有设计系统资产。
• 在 project-profile.json 和 extended summary 中输出 visualRegression，提供视觉回归的结构化事实或 gap 提示，内容可能包括可运行的视觉基线入口、截图产物 / baseline 约定事实，以及缺失能力的 gaps；只有存在可运行入口时，才应把它当成已有可复跑的视觉基线入口。
• 在 project-profile.json 和 summary-extended.md 中输出质量、视觉回归、性能预算、无障碍、浏览器验证等结构化事实或 gap；具体执行时机以 agent-core/core.md 和 agent-core/references/ 为准。
• 为 Web PC、移动 H5、小程序、跨端框架和 Electron 客户端提供统一工作流。
• 使用同一份核心规则适配不同 Agent 平台，避免多份规则漂移。

前置条件

• 可运行 Node.js ESM 脚本的环境。建议使用 Node.js 18 或更高版本。
• 目标 Agent 支持项目级指令文件，或允许在任务开始时手动加载规则。

当前仓库没有 Node.js 版本兼容矩阵，也没有外部 npm 依赖。根目录的 package.json 承载 repo-local 维护脚本、package manager 元数据，以及 npm 分发所需的 CLI 与 files 元数据；不要求安装额外依赖即可运行 scanner 或仓库级回归入口。

浏览器验证约定

涉及 UI、布局、响应式、交互、移动端适配或可见状态变化时，不要只看单测结果。

• 先检查目标项目是否已经提供 browser:*、e2e*、playwright*、cypress* 一类浏览器级脚本。
• 如果存在可运行的浏览器级脚本，优先把它们作为验证入口，再补 lint、typecheck 或单测。
• 目标项目可以放一个最小 smoke spec 在 tests/browser/front-end-smoke.spec.mjs，默认覆盖桌面和移动端 viewport，并通过环境变量补充 ready selector、关键元素、点击、输入、滚动、抽屉/弹窗和截图路径。
• 推荐把 smoke 模板至少接到这几类检查：页面打开、异步 ready selector、关键元素可见、空白页检测、截图输出、错误态隐藏、遮挡检查、横向溢出和交互后异步稳定。
• 如果 scanner 已输出 visualRegression，先把它当成视觉回归的结构化事实或 gap 提示；artifactDir / baselineFiles 非空只能说明存在截图产物或 baseline 约定，不等于仓库已经提供可直接复跑的入口。只有存在可运行入口时，才应把它当成已有视觉基线入口。verify --project . --level ui 会把 visual:*、regression:*、screenshot:* 里可运行、非交互式且通过现有过滤的入口纳入浏览器级计划。第一版仍以本地截图复核为主，不默认接 CI，也不会把新截图自动当作通过。
• 如果目标项目暂时没有可执行的浏览器脚本，就明确写出未验证项，不要把“看起来应该没问题”当成验证结论。

本仓库自身也提供了一个无依赖的真实浏览器夹具，便于给 smoke 模板留仓库级运行记录：

node tests/browser/serve-smoke-fixture.mjs --port 4173

对应页面位于：

tests/browser/fixtures/smoke-app/index.html

它不是业务页面替代品，而是仓库内的稳定验证目标，用来完成 smoke 模板的真实浏览器回归。

仓库自身的自动回归入口与清单分别是：

node scripts/frontend-agent/run-real-repo-regression.mjs

tests/browser/real-repo-regression.md

前者负责顺序执行仓库内可直接跑的 scanner / test / diff 检查；后者补充真实浏览器夹具、front-end-smoke.spec.mjs 和截图人工复核步骤。

仓库自身默认的真实浏览器回归入口是：

node scripts/frontend-agent/run-real-repo-browser-smoke.mjs

它会临时启动本地 smoke 夹具，并通过 npx --yes --package @playwright/cli playwright-cli 执行 repo-local 的真实浏览器操作，不要求仓库安装本地 playwright 依赖。稳定产物会写到：

output/playwright/real-repo-smoke/

其中至少包含：

• desktop-smoke.png
• mobile-smoke.png
• console.log

如果默认 Playwright 浏览器缓存不完整，也可以让模板切到系统安装浏览器：

$env:FRONTEND_SMOKE_BROWSER_CHANNEL='chrome'

必要时再回退到显式路径：

$env:FRONTEND_SMOKE_BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'

安装与使用

1. 运行 CLI

yd-frontend-agent 已发布到 npm，可直接在目标项目运行：

npx yd-frontend-agent profile --refresh-if-stale

等价写法：

npm exec --yes yd-frontend-agent -- profile --refresh-if-stale

• 该命令只运行 CLI 并生成项目画像，不会把规范包写入项目。
• 缓存 .agent-cache/ 仍需手动 .gitignore（见下方）。

2. 安装 npm 分发包到项目

在目标项目运行：

npx yd-frontend-agent install
npx yd-frontend-agent install --dry-run
npx yd-frontend-agent install --host codex
npx yd-frontend-agent install --host claude-code

如果使用 npm exec，中间必须保留参数分隔符 --：

npm exec --yes yd-frontend-agent -- install
npm exec --yes yd-frontend-agent -- install --dry-run
npm exec --yes yd-frontend-agent -- install --host codex
npm exec --yes yd-frontend-agent -- install --host claude-code

install --dry-run 会先预览共享资源、宿主资源和安装元数据的写入计划，但不会真正落盘。正式执行 install 时，--host codex 还会生成项目内的 Codex marketplace metadata；--host claude-code 会把 Claude Code 入口接入项目根 CLAUDE.md，若该文件已存在则追加 Frontend Agent 适配块而不覆盖原内容。npm 分发包与本仓库内的 repo-local source 是两套交付形式：repo-local source 仍可用于复制到目标项目的本地安装和本地验证；npm 分发包则是标准分发方式。

3. 宿主级后续接线

第一阶段不会自动执行 codex plugin add ...，也不会修改机器级插件目录。生成项目内 marketplace 仅提供项目级 metadata；如需把 plugin 注册到本机 Codex，请在确认本机状态变更后自行完成宿主级接线。

4. 通过复制 repo-local 源码安装

将以下文件复制到目标前端项目，并保持相同相对路径：

TARGET_PROJECT/
├── AGENTS.md 或 CLAUDE.md
├── agent-core/
│   ├── core.md
│   └── references/
└── scripts/
    └── frontend-agent/
        └── index.mjs

其中 agent-core/references/ 和 scripts/frontend-agent/ 都需要整体复制；CLI 入口文件是 scripts/frontend-agent/index.mjs。如果只复制 core.md 而缺少 references，Agent 仍可走 L1，但 L2 细则缺失时必须在汇报中说明已降级。

平台入口来源（保持原样，不变）：

| 平台 | 复制来源 | 目标文件 | |---|---|---| | Codex | adapters/codex/AGENTS.md | AGENTS.md | | Claude Code | adapters/claude-code/CLAUDE.md | CLAUDE.md | | 其他平台 | adapters/generic/AGENT.md | 平台要求的指令文件名 |

如果目标项目已有指令文件，合并 adapter 内容，不要覆盖原文件。目标项目自己的业务规则应保留，并优先于通用规则。

5. 忽略缓存

在目标项目的 .gitignore 中加入：

.agent-cache/

6. 生成项目画像

使用 repo-local 源码安装时，在项目根目录运行：

node scripts/frontend-agent/index.mjs profile --refresh-if-stale

成功后读取：

.agent-cache/frontend/summary.md

profile 会同时生成默认摘要和扩展摘要：

.agent-cache/frontend/summary.md
.agent-cache/frontend/summary-extended.md

默认只读 summary.md。当 agent-core/core.md 的任务升档矩阵要求 L2/L3 时，再读取对应 agent-core/references/ 文件和 summary-extended.md 的相关段；也可以用 summary --extended 打印扩展摘要。

简化升档提示：

| 任务 | 默认读取 | 升档动作 | |---|---|---| | 常规局部前端改动 | summary.md | 按 Recommended Checks 做相称验证 | | 共享抽象、API、设计系统、接手、跨端、复杂 bug | summary.md | 按 core.md 矩阵读 references + summary-extended.md | | 共享组件 / hooks / stores / 跨页面抽象 | summary.md | L2 后运行 impact | | 用户要求完整验证或收口证据 | summary.md | L2 后运行 verify |

详细升档矩阵以 agent-core/core.md 为准，README 不维护第二份规则正文。如果未检测到显式代码规范，Agent 不应静默启用默认规范；应先向用户暴露 Style Decision 选项，再按用户选择执行。

7. 开始任务

示例任务：

请按 Frontend Agent 核心规则修复登录页按钮 loading 不结束的问题。
限制范围：只修改登录相关文件。
完成前检查可复用实现，并运行可用的 lint、typecheck 或测试。

8. 复杂任务写法

当任务比较大时，直接按这个格式描述会更稳：

任务 -> 影响面 -> 需要读的文件 -> 修改点 -> 验证点 -> 回滚点

收口时建议固定成这四句：

修改了什么
为什么改
验证了什么
还剩什么风险

复杂任务、完整验证或收口证据要求会升档到 L2。按 agent-core/core.md 的矩阵读取 agent-core/references/complex-task-gates.md，并按需查看 summary-extended.md 的 ## Task Phases / ## Task Guardrails。

如果需要看完整示例，直接读：

docs/superpowers/examples/2026-07-13-multi-step-task-examples.md

里面包含 Web 登录页 loading 修复、共享 hook 变更、uni-app 跨端差异修复和 Next.js 首屏调整这几类真实任务的阶段推进写法。

复杂 bug、项目接手、设计系统、API、跨端和共享抽象等任务的细则不在 README 维护；按 agent-core/core.md 矩阵读取对应 agent-core/references/ 文件，并只查看 summary-extended.md 的相关段。

Codex Plugin 包

仓库现在同时提供一个 repo-local 的 Codex plugin 包，路径是：

plugins/frontend-agent/

这个 plugin 的定位很克制：

• skill 入口负责把 Codex 引到唯一规则源 agent-core/core.md
• scanner 继续复用仓库里的 scripts/frontend-agent/index.mjs
• references 负责记录边界、安装更新和验证流程
• 当前不额外打包新的 MCP server

repo-local marketplace 入口放在：

.agents/plugins/marketplace.json

它声明了 frontend-agent 的本地 source path，方便后续做本机安装或重装；但仓库默认只交付 source 和 metadata，不会静默改动当前用户的 Codex 已安装插件状态。

核心文件

.
├── .agents/
│   └── plugins/
│       └── marketplace.json         # repo-local plugin marketplace 入口
├── AGENTS.md                         # 本仓库自身的维护入口
├── README.md                         # 安装和使用说明
├── package.json                      # 维护脚本、package manager 与 npm 分发 CLI/files 元数据
├── agent-core/
│   ├── core.md                       # 唯一运行时规则源
│   └── references/                   # L2/L3 按需细则
├── adapters/
│   ├── codex/AGENTS.md               # Codex 薄适配器
│   ├── claude-code/CLAUDE.md         # Claude Code 薄适配器
│   └── generic/AGENT.md              # 通用薄适配器
├── plugins/
│   └── frontend-agent/               # repo-local Codex plugin 包
├── scripts/
│   └── frontend-agent/
│       └── index.mjs                 # 项目画像 scanner
└── tests/
    └── frontend-agent.test.mjs       # scanner 测试

具体工作流、范围、编码、平台和验证规则只维护在 agent-core/core.md。README 和 adapters 不复制这些规则。

Scanner 命令

按需刷新画像

node scripts/frontend-agent/index.mjs profile --refresh-if-stale

缓存未过期时直接复用；缺少缓存或指纹变化时重新扫描。

强制刷新

node scripts/frontend-agent/index.mjs profile --force-refresh

输出已有摘要

node scripts/frontend-agent/index.mjs summary
node scripts/frontend-agent/index.mjs summary --extended
node scripts/frontend-agent/index.mjs impact --project .
node scripts/frontend-agent/index.mjs impact --files src/components/Button.tsx
node scripts/frontend-agent/index.mjs impact --since HEAD
node scripts/frontend-agent/index.mjs verify --project .
node scripts/frontend-agent/index.mjs verify --project . --level ui
node scripts/frontend-agent/index.mjs verify --project . --print

summary 默认打印 .agent-cache/frontend/summary.md；summary --extended 打印 .agent-cache/frontend/summary-extended.md。摘要不存在时，命令会提示先运行 profile。

impact 是 L2 按需独立命令，不支持 --refresh-if-stale。它会输出候选影响面到 .agent-cache/frontend/impact.json，并在 stdout 打印简短摘要或 --json 完整结果。

verify 也是 L2 按需独立命令。第一版支持 quick|standard|ui 三档 level，以及 --print 只打印计划不执行。它会过滤 watch / fix / write / deploy / publish 类命令，识别可安全执行的预算脚本，并把真实执行结果写到 .agent-cache/frontend/verify-last.json。如果 scanner 没有发现预算入口，extended summary 会把它标记为缺口；verify 则不会假装仓库已经具备预算门禁或可执行的预算命令。若 scanner 已输出 visualRegression，verify --level ui 只会识别并纳入其中可运行、非交互式且通过现有过滤的视觉基线入口；缺少入口时会明确保留 skip reason。若 scanner 已输出 routePermissionModel，路由、guard、middleware、permission、menu 配置文件会被视为权限敏感的 UI / flow-related 变更，verify --level ui 不会把这类变更误判成“非 UI 相关”。

扫描指定项目

node scripts/frontend-agent/index.mjs profile --refresh-if-stale --project /path/to/frontend-project

PowerShell 示例：

node D:\agents\developer\frontend\scripts\frontend-agent\index.mjs profile --refresh-if-stale --project D:\path\to\frontend-project

Monorepo 应将 --project 指向实际应用或 package，而不是默认扫描仓库根目录。

Repo 级扫描配置

Scanner 现在支持两个 repo 级配置入口：

frontend-agent.config.json
package.json -> frontendAgent

当前可覆盖这四类硬编码规则：

• watchFiles
• watchDirs
• ignoredDirs
• depGroups

列表类配置支持两种写法：

{
  "watchDirs": ["src", "components"],
  "ignoredDirs": {
    "add": ["tmp"],
    "remove": ["dist"]
  }
}

依赖分组支持整组替换或增删：

{
  "depGroups": {
    "testing": {
      "add": ["custom-test-runner"]
    },
    "analytics": ["posthog-js"]
  }
}

frontend-agent.config.json 与 package.json.frontendAgent 会按顺序合并，后者优先级更高。

查看帮助

node scripts/frontend-agent/index.mjs --help

缓存说明

默认输出目录：

.agent-cache/frontend/
├── impact.json
├── project-profile.json
├── reusables-index.json
├── verify-last.json
├── file-fingerprints.json
├── profile-slices.json
├── reusables-slices.json
├── scan-meta.json
├── summary.md
└── summary-extended.md

| 文件 | 内容 | |---|---| | impact.json | 基于 git diff 或显式文件列表生成的候选影响面、风险提示与建议回归点 | | project-profile.json | 框架、平台、包管理器、依赖、scripts 和推荐验证命令 | | project-profile.json -> runtimeReadiness | example env 键名、proxy / base path 线索、workspace package 映射和一跳依赖提示 | | project-profile.json -> designSystem | token 文件、变量样例、primitive 候选和 Storybook 入口 | | project-profile.json -> apiContracts | request wrapper、API module、schema、契约文件和 mock 入口的只读索引 | | reusables-index.json | 可复用代码候选及其路径和类型 | | verify-last.json | verify 最近一次执行的命令清单、结果状态、跳过项和错误摘要 | | file-fingerprints.json | 切片级输入指纹 manifest；既保留 profile / reusables 域级过期判断，也记录各能力切片的输入指纹 | | profile-slices.json | profile 域的切片级中间缓存，用于按能力切片复用并组装最终 project-profile.json | | reusables-slices.json | reusables 域的切片级中间缓存，用于按能力切片复用并组装最终 reusables-index.json | | scan-meta.json | scanner 版本、扫描时间、统计信息，以及本次域级与切片级重建/复用结果 | | summary.md | L1 默认紧凑摘要，包含 Stack、Scripts、Recommended Checks、Reusable Index Counts、Escalation/Rules 等 | | summary-extended.md | L2/L3 扩展摘要，包含 Project Onboarding、Design System、API Contracts、Change Impact、Task Guardrails、Reusable Samples 等按需段 |

缓存可以安全删除并重新生成。它不包含源码正文，但包含项目路径、依赖和脚本等元数据，因此不应提交或公开分享。

缓存只作为索引，不是事实来源。复用、修改或删除候选项前，必须阅读对应源码并检查调用点。

--refresh-if-stale 当前会按能力切片复用缓存，而不是只按 profile / reusables 两个粗域整块复用。若 profile-slices.json 或 reusables-slices.json 缺失、损坏、schema 不匹配，或缺少该域必需切片 key，scanner 会只对对应域保守回退为“该域全部切片重建”；另一个健康域仍可继续复用。CLI 本身没有新增参数或行为入口。

impact 的当前局限：

• 零依赖轻量解析，不是完整 TypeScript Program 或 AST。
• 别名最小容错覆盖 tsconfig / jsconfig 的 baseUrl + paths（最长前缀、/*）以及静态字符串形式的 Vite resolve.alias。
• 仅有 baseUrl、没有 paths 时，只有 baseUrl + specifier 真正落盘存在才会 resolve，否则视为 external。
• 不覆盖动态 alias、package.json exports 条件和 monorepo 跨 package 源码映射。
• 解析失败的项目内边会进入 unresolved 样例与计数，不会静默丢边。
• monorepo 请用 --project 指向具体前端 package。
• 结果是候选影响面，修改前仍需回读源码与调用点。

API Contracts 的当前边界：

• 第一版只做路径级索引，不推断 request / response 字段树。
• 不做 OpenAPI / GraphQL codegen，也不做运行时抓包。
• 测试目录、*.test.*、*.spec.* 等文件会被过滤，避免误判为生产 API 事实。

verify 的当前边界：

• 第一版是串行执行，不做并行调度。
• --print 只打印计划，不写执行结果。
• 失败摘要当前只做 ESLint、TypeScript、测试和 generic fallback 启发式抽取。

当前识别能力

| 类型 | 主要能力 | |---|---| | Web | Vue、React、Svelte、Solid、Angular、Preact、Next.js、Nuxt、SvelteKit、Astro、Remix、Qwik、SolidStart、Analog、TanStack Start、Umi / Max | | 小程序 | 原生微信小程序、分包、miniprogramRoot、小程序页面和组件 | | 跨端 | uni-app、Taro、H5 与常见小程序构建脚本 | | 桌面 | Electron、electron-vite、Electron renderer 框架组合 | | 构建工具 | Vite、Webpack、Rollup、Parcel、Vue CLI 及框架自带 builder | | 可复用索引 | pages、components、hooks、composables、utils、API、stores、styles、directives、plugins、locales | | 验证推荐 | lint、typecheck、test、build、浏览器 smoke、视觉基线入口、可安全执行的预算脚本及常见平台构建脚本 | | 质量提示 | performanceBudget、a11y、performance、responsive/mobile 规则提示；缺少预算信号时明确记为 gap |

Scanner 会排除常见测试、mock、Storybook、声明和构建产物，避免把它们误识别为业务复用项。完整行为以 scripts/frontend-agent/index.mjs 和测试为准。

影响面

impact 是 L2 按需命令，用于共享抽象、跨页面或主题类改动的候选影响面分析。生成结果仍只是索引提示，修改前必须回读源码、调用点和测试；详细使用时机以 agent-core/core.md 的矩阵为准。

使用边界

• Scanner 采用启发式识别，输出的是候选和信号，不是完整语义分析。
• 动态生成的目录、非常规 monorepo 布局和自定义构建系统可能无法完整识别。
• Scanner 不会替代阅读源码、运行项目测试或浏览器验证。
• 浏览器级问题必须回到真实浏览器里确认，不能只靠静态扫描下结论。
• Quality Notes 只是提示，不是自动结论；仍要结合源码和运行结果判断。
• Next.js、Nuxt、SvelteKit、Astro 和 Electron 可能包含服务端或主进程代码，修改前应先确认边界。
• 小程序支付、签名、证书和服务端回调不属于客户端 scanner 或 Agent 的默认职责。

升级与卸载

升级

通过 npm 分发包安装到项目后，优先在目标项目运行：

npx yd-frontend-agent doctor
npx yd-frontend-agent upgrade

如果使用 npm exec，写法应为：

npm exec --yes yd-frontend-agent -- doctor
npm exec --yes yd-frontend-agent -- upgrade

doctor 会只读检查项目根目录的 frontend-agent.install.json、共享资源和宿主资源是否完整；发现缺失时只输出问题与建议，不会自动修复。若需要脚本化接入，可使用 npx yd-frontend-agent doctor --json 获取结构化结果。upgrade 会读取项目根目录的 frontend-agent.install.json，并按上次安装记录重放共享资源与宿主资源。等价的手工升级范围是：

agent-core/core.md
agent-core/references/
scripts/frontend-agent/
adapters/

如果安装时使用了 --host codex，还要同步项目内生成的：

.agents/plugins/marketplace.json
plugins/frontend-agent/.codex-plugin/plugin.json
plugins/frontend-agent/skills/frontend-agent/**

升级后删除 .agent-cache/frontend/ 或运行 --force-refresh，再执行维护者验证命令。

如果目标指令文件包含业务规则，不要用新版 adapter 整文件覆盖它。

卸载

优先在目标项目运行：

npx yd-frontend-agent doctor
npx yd-frontend-agent uninstall --dry-run
npx yd-frontend-agent uninstall

如果使用 npm exec，写法应为：

npm exec --yes yd-frontend-agent -- doctor
npm exec --yes yd-frontend-agent -- uninstall --dry-run
npm exec --yes yd-frontend-agent -- uninstall

建议先运行 doctor 看当前安装是否完整，再决定是否执行 upgrade 或 uninstall。uninstall --dry-run 会先预览将要删除的共享资源、宿主资源和安装元数据，但不会真正删除文件。正式执行 uninstall 时，会读取 frontend-agent.install.json 并删除由 Frontend Agent 安装的项目内资源；若安装时使用了 --host claude-code，还会从项目根 CLAUDE.md 中移除 Frontend Agent 管理块但保留原有内容。卸载后如需彻底清理缓存，再手动删除 .agent-cache/frontend/。

故障排查

summary 提示找不到缓存

先运行：

node scripts/frontend-agent/index.mjs profile --refresh-if-stale

画像识别成 framework: none

常见原因是扫描了 monorepo 根目录或规范仓库。使用 --project 指向实际前端应用，并确认该目录包含 package.json 或平台配置。

缓存没有反映最新文件

先强制刷新：

node scripts/frontend-agent/index.mjs profile --force-refresh

如果问题仍存在，应检查 scanner 的监听范围并为缺失场景补测试。

Adapter 无法读取核心规则

确认目标项目中存在：

agent-core/core.md
agent-core/references/

Adapter 使用目标项目根目录下的相对路径。只复制 adapter 而没有复制核心规则和 scanner，安装是不完整的。

维护者验证

修改 scanner、测试或能力说明后，优先运行这两个 repo-local 回归入口：

node scripts/frontend-agent/run-real-repo-regression.mjs
node scripts/frontend-agent/run-real-repo-browser-smoke.mjs

其中：

• run-real-repo-regression.mjs 负责仓库级自动检查：node --check、完整 Node 测试、scanner smoke 和 git diff --check
• run-real-repo-browser-smoke.mjs 负责真实浏览器夹具回归，并在 output/playwright/real-repo-smoke/ 下生成稳定截图和 console 记录

如果本次改动会影响 scanner 对真实业务前端项目的识别、summary、recommended checks、impact 或 verify 计划，还应按：

docs/validation/real-project-validation-matrix.md

补跑真实前端项目验证矩阵，并记录样本仓库、关键发现和临时 clone 清理结果。

如果你需要单独排查底层步骤，仍然可以直接运行这些命令：

node --check scripts/frontend-agent/index.mjs
node --test tests/frontend-agent.test.mjs
node scripts/frontend-agent/index.mjs profile --force-refresh
git diff --check

如果本次改动涉及浏览器验证约定，还要确认 tests/browser/ 下的 smoke 模板仍能被目标项目直接复用。

修改规则或 adapters 后还应搜索旧文件引用，确认所有入口只指向 agent-core/core.md。

不要声称未运行的检查通过，也不要把自动修复命令当作默认验证。