pi-frontend-kpc-agent

一个基于 Pi 的终端前端 coding agent 扩展包，面向 Vue、@ksyun-internal/versatile 和 @king-design/vue。从目标项目实际安装的包版本、入口声明、类型关系和 lockfile 中生成组件契约，再用编译器做确定性校验。

核心链路

flowchart LR
  A[目标项目 package.json / lockfile] --> B[精确定位已安装版本]
  B --> C[TypeScript 组件契约清单]
  B --> T[frontend_scene_template 场景骨架]
  T -->|命中| F[Vue SFC 静态校验]
  T -->|未命中 / 新增组件| D[component_query 精简发现]
  D --> U[component_usage 安装包示例 / 组合结构]
  U -->|示例未覆盖| E[component_contract 精确成员]
  C --> E
  C --> F[Vue SFC 静态校验]
  H[frontend_preview 截图 / 路由<br/>仅显式视觉验收时] -.-> I[frontend_finish]
  F --> I
  G[typecheck / lint / test / build] --> I

组件库升级后会按“项目根目录 + 包名 + 精确版本”重新抽取契约，不需要维护一份手写 API 文档副本。

环境与安装

• Node.js >=22.19.0
• 已按 Pi 0.81.1、TypeBox 1.1.38 完成构建和测试

推荐：使用安装脚本

0.1.11 发布到 npm 后，其他人可以先下载并检查脚本，再执行：

curl -fsSL https://unpkg.com/pi-frontend-kpc-agent@latest/install.sh | sh

curl -fsSLo /tmp/pi-frontend-kpc-agent-install.sh \
  https://unpkg.com/pi-frontend-kpc-agent@0.1.11/install.sh
less /tmp/pi-frontend-kpc-agent-install.sh
sh /tmp/pi-frontend-kpc-agent-install.sh

仓库使用者也可以直接运行：

./install.sh

脚本会依次：

1. 检查 Node.js、npm 和 pi；若缺少 pi，全局安装已验证的 @earendil-works/pi-coding-agent@0.81.1。
2. 通过 pi install npm:pi-frontend-kpc-agent@0.1.11 安装与脚本相同版本的 Agent Package。
3. 将 company-openai 的无密钥模型模板合并到 ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/models.json。

脚本不会复制开发者本机的密钥、认证信息或其他 Pi 配置。模型配置只保存环境变量引用 $COMPANY_LLM_API_KEY，使用前请在当前 shell 提供真实密钥：

export COMPANY_LLM_API_KEY='your-key'
pi --model company-openai/qwen3.6-plus

默认模型服务地址为公司内网的 http://kspmas.ksyun.com/v1。仅应在可信内网使用；如有 HTTPS 地址，可在安装时覆盖：

PI_COMPANY_OPENAI_BASE_URL='https://llm.example.com/v1' \
  sh /tmp/pi-frontend-kpc-agent-install.sh

已有 company-openai 配置时，脚本默认保持原样，适合重复执行。确认要用包内模板替换时，显式开启覆盖；原文件会以 models.json.bak-* 备份：

PI_MODELS_OVERWRITE=1 sh /tmp/pi-frontend-kpc-agent-install.sh

高级参数：

• PI_CODING_AGENT_DIR=/absolute/path：修改 Pi agent 配置目录，必须是绝对路径。
• PI_FRONTEND_AGENT_SOURCE=npm:pi-frontend-kpc-agent@0.1.11：固定版本或切换为本地包路径。
• PI_NPM_PACKAGE=@earendil-works/pi-coding-agent@version：显式选择要安装的 Pi 版本；必须满足 >=0.81.1。

若上次执行被 kill -9 强制终止，可能留下 .pi-frontend-kpc-agent-install.lock。确认没有其他安装进程后再手动删除该空目录。全局 npm 目录无写权限时，脚本会直接失败且不会尝试 sudo；建议使用 nvm 管理 Node.js 后重试。

卸载 Agent Package 可执行 pi remove npm:pi-frontend-kpc-agent。为避免误删用户配置，卸载不会自动移除 models.json 中的 provider。

手动安装

安装 Pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1

安装已发布的 Agent Package：

pi install npm:pi-frontend-kpc-agent@0.1.11

本地开发及验收：

npm install
npm run verify
pi -e /absolute/path/to/pi-frontend-kpc-agent

开发阶段安装当前本地包：

pi install /absolute/path/to/pi-frontend-kpc-agent

进入目标 Vue 项目后运行 pi，可直接描述需求，也可使用包内提示模板：

/frontend 实现带筛选、分页和错误重试的实例列表
/frontend-review 当前改动

九个确定性工具

工具	作用
frontend_project_inspect	识别包管理器、精确组件库版本、脚本、构建配置、Node 兼容性、数据层路径，以及 Vue 的 TS/JS、script setup/Options API 等现有约定
frontend_scene_template	第一级检索：按自然语言或模板 ID 返回一个匹配的列表、详情或购买场景骨架；根据 targetFile 自动匹配 TS/JS，优先选择 Versatile，未安装时回退原生 KPC；命中后模板组件自动登记为已验证证据
component_query	模板未命中或需要新增组件时，批量发现最多 12 个精确安装导出；模板尚未解析或请求的组件已被模板覆盖时自动跳过
component_usage	第二级检索：从当前安装版本的 tests/examples/source 提取最小用法，并识别 Table > TableColumn、Dropdown > DropdownMenu > DropdownItem 等组合结构
component_contract	第三级检索：示例未覆盖所需细节时，按需读取 props、events、models、slots、methods 或 exposed 精确成员
component_validate	用 Vue/TypeScript AST 校验 SFC 的导入、静态 prop、event、v-model、slot、枚举和必填 prop
frontend_verify	可选的中途诊断工具：只从固定脚本候选生成 fast 或 full 检查计划，区分变更范围内与存量错误，并为变更范围诊断附上失败源码和所属组件；不要紧接着再调用本身已执行 full gate 的 frontend_finish
frontend_preview	高成本、显式启用的视觉工具。只有用户明确要求截图验证、视觉对比/验收或渲染预览时，才启动目标项目并截图真实路由；无路由的独立组件走单 SFC 沙箱。返回截图、渲染状态、console error、路由和可选参考图比较
frontend_finish	默认按 code 模式校验组件证据、mock/图标/列表结构、新页面静态路由引用，并运行项目可用的 typecheck、lint、test、build；只有显式 visual 模式才启动页面并增加截图、参考图和真实路由验收

包内还提供三个可组合 Skill：ksyun-frontend-workflow、ksyun-frontend-review、ksyun-frontend-testing。

P0 / P1 / P2 执行策略

P0：先产出，再校验

• 常见列表、详情和购买流程先调用一次 frontend_scene_template，传入准备修改或创建的 targetFile，并等待模板结果后再查询组件。并行发起的提前组件检索会被工具跳过，避免提示规则被绕过。工具按“目标文件 → 同目录 Vue 文件 → 项目采样 → TypeScript 依赖”的顺序选择 TS/JS；若局部代码仍使用 Options API，只返回可迁移的 template/style 组合，不要求整页改写为 Composition API。
• 兼容模板是实现基线，不只是参考代码。列表模板会记录当前变体要求的 ProTable 或 Table 根组件；首次 write/edit 若把它替换成另一套表格组合，会在落盘前被拒绝，后续静态检查也会按 error 阻断。
• list-basic 会同时返回 supportingFiles，提供与主 SFC 一致的 types、确定性 mock 和纯函数 utils 源码及建议路径。应在同一实现批次写入并统一改字段，不能一边复制主模板、一边重新猜测配套模块。
• 命中兼容模板后直接按本地数据、字段、路由和状态做最小适配。模板列出的组件自动计为渲染验证证据，后续 component_query、component_usage 或 component_contract 会跳过这些 API；只有实质改变模板 API 时才显式 force: true。
• 兼容模板命中后、目标页首次写入前最多允许 4 次聚焦的额外组件研究调用；模板覆盖组件此时不能用 force 绕过。先写出最小页面，再由自动校验或最终门禁给出精确缺口，避免长时间“查而不写”。
• 模板的 TS SFC 是实际渲染基线；JS 版本仅替换独立脚本适配器，template/style 共用同一份，避免双份页面结构逐渐漂移。确有迁移或测试需要时才显式传 language: "ts" 或 language: "js" 覆盖自动判断。
• 没有兼容模板时，先看邻近业务代码，再用一次 component_query 批量确认精确组件名，并优先读取 component_usage 的安装包示例。只有示例未覆盖的 API 成员才读取 component_contract 或安装源码。
• 在线组件文档放在最后，只作为搜索线索；任何文档写法都必须回到当前安装版本的声明、测试或源码验证，不能覆盖本地包事实。
• frontend_project_inspect 只读取项目结构，不在后台启动 typecheck/build，也不会因生成 tsconfig.tsbuildinfo 等产物污染工作区。项目脚本仅在显式调用 frontend_verify 或最终 frontend_finish 时运行；最终检查按诊断文件路径隔离变更范围与存量错误。
• 源码变更后最多允许两次无关只读调查；当前报错文件、变更文件、组件 usage、验证命令和生成截图不受该预算限制。一次验证尝试后预算会重置，不再因项目缺脚本形成死锁。
• 同一组件错误，或同一文件/错误码/行号的 TypeScript 错误连续出现两次后暂停继续盲改。frontend_verify 会附上准确源码行、上下文和最近的所属组件，应先修这一表达式，不能顺手删除模板里的选择、分页、搜索或总数行为。
• provider 请求按估算 token 使用滚动 TPM 窗口节流；遇到 429 时优先遵循 Retry-After，否则至少退避 60 秒。
• 页面 SFC 保持展示和交互职责；本轮新建或明显膨胀到 500 行以上的页面会阻止完成，要求把类型、纯逻辑和可选 mock 拆出。

页面功能较复杂时，推荐按 feature 共置：

src/views/Instances.vue
src/views/instances/types.ts
src/views/instances/utils.ts
src/views/instances/mock.ts   # 仅在 mock 判定成立时创建

TypeScript 页面用 types.ts 放接口、表单和行数据类型；JavaScript 页面不为模板强行引入 TypeScript。utils.ts/utils.js 放搜索、过滤、排序、分页等纯函数。不要为了凑目录创建空模块。

Mock 数据不是附图或页面任务的默认选择。frontend_project_inspect 会报告已有 API/service/store/mock 路径和请求库：

• 已有 API、service、store 或邻近页面数据流时，优先复用真实 adapter；测试在边界层 mock。
• 明确是隔离原型或图片生成、没有可用数据源且需要稳定展示 loading、empty、error、success 状态时，才按项目语言创建 mock.ts/mock.js。
• Mock 必须有明确数据结构、确定性、无随机数和当前时间依赖，不得把大段数组直接写进 .vue；不要让 mock 静默成为生产默认数据源。
• 明确要求 mock 或任务显式启用视觉门禁时，frontend_verify/frontend_finish 会扫描本轮所有变更源码中的 Math.random()、Date.now()、randomUUID()，不能通过把随机生成器放进 utils.ts 绕过；同时检查生成的 Table/ProTable 搜索分页页是否导入共置 utils.ts/utils.js、搜索输入是否真正进入过滤链路。TS 列表模板要求类型从 types.ts 导入；明确要求 mock 时要求从共置 mock.ts/mock.js 导入。

P1：控制上下文和环境噪音

• 上下文超过约 32k token 后压缩旧的成功工具结果；超过约 48k 时进一步压缩其他旧结果。最近消息和错误输出保留。
• frontend_project_inspect 缓存到 package.json 发生变化为止，组件查询和单组件契约按参数缓存。
• 验证前检查当前 Node 版本是否满足项目和构建工具的 engines.node，不兼容时直接报告环境阻塞，不消耗一次无效构建。
• 存量项目使用同口径的 full 可用-gate 基线；若仍无基线，则按报错路径判断是否落在本轮 dirty scope。任务外旧错误不会触发自动修复，无法归属文件的失败仍阻塞。
• formatter、patch、codegen 等不透明写入通过前后工作区快照定位实际文件；不要求目标目录必须是 Git 仓库。2>/dev/null 等诊断重定向不会再被标成写入。
• npx/bunx 调用项目 node_modules/.bin 中已安装的命令不再误标为依赖变更；显式 --package 或需要下载的执行仍要求授权。
• KPC 图标类会对照当前安装包的 iconfont registry，错误的 k-icon-plus、k-icon-arrow-down 等会在完成前给出精确文件和行号。
• KPC Table 运行时默认启用 checkbox 选择列。生成页若又手写包含 Checkbox 的 selection 列会被阻断；使用内置选择时绑定 v-model:checkedKeys，确需自定义列时显式设置 check-type="none"。
• 从列表模板生成的 ProTable 会保留选择状态和受控分页不变量。批量按钮依赖 checkedKeys 却没有 v-model:checked-keys，或把模板分页对象退化成 :pagination="true"，都会在执行项目脚本前被阻断。
• ProTable 列表模板还会保留 request、row-key、sort、group、搜索模型、LayoutContent 头部和 TableColumnId 主列；这些绑定缺失会被视为模板结构退化。新生成的模板页必须保留显式组件 import，不能依赖无法静态确认的全局同名组件。
• 生成页中的 any、any[]、as any、@ts-ignore/@ts-expect-error 会被视为组件事件/数据类型尚未查明，而不是可接受的修复。

P2：默认代码验收，视觉验收显式启用

• 默认 validationMode 为 code。附件、.png/.jpg/.webp 路径、“根据图片生成”或“原型”只作为需求输入，不会启动目标项目、浏览器或 SSIM。
• code 模式依赖场景模板不变量、组件契约与安装示例、页面架构、纯函数/行为门禁，以及项目已有的 typecheck、lint、test、build。frontend_finish 会静态确认新页面已被现有 Vue Router 引用，并明确返回“未验证运行时外观”；它不会启动页面或要求截图。
• 只有用户明确要求“截图验证/对比/验收”“视觉验证/对比/验收”“像素级还原”或“查看渲染预览”等操作时才切换到 visual。用户也可以明确要求只做代码/编译检查切回 code。
• visual 模式下，每个变更的 Vue 文件必须有成功预览；views/ 页面和 App.vue 还必须证明请求路由已声明且目标页面被路由引用。
• 有已验证路由时，预览工具启动目标项目并截图真实页面；没有路由时才使用独立 SFC 沙箱。只有 wrapper 明确报告渲染成功且没有 console.error 时才计入视觉证据；错误页只作为诊断附件。相同基础设施失败重复两次后会熔断本轮重试。
• visual 模式会自动选择提示中唯一的项目内参考图；多张图时必须明确选择。工具记录尺寸并在 ffmpeg 可用时计算 SSIM；低于 0.75 或未产生比较证据时阻断完成。

版本与发布

版本脚本会修改 package.json、package-lock.json，并同步 install.sh 中固定的 Agent 版本；不会创建 Git tag、commit 或执行发布：

npm run release:version:patch
npm run release:version:minor
npm run release:version:major

发布前检查会运行完整验证，并检查最终 npm tarball 的入口、Skills 和 Prompts：

nvm use 22.19.0
npm run release:check

确认版本和检查结果后，由发布者手动执行。当前开发机的默认 npm cache 存在权限问题，因此使用一个可写的临时 cache：

npm publish --cache "${TMPDIR:-/tmp}/pi-frontend-kpc-agent-npm-cache"

契约判定规则

• KPC 支持直接或间接 Component<Props, Events, Blocks> 继承，并提取继承的公开方法。
• KPC 的 Vue adapter 语义按已安装运行时代码处理：默认 v-model 映射到 value，v-model:x、@change:x、@change-x 与 @update:x 仅在契约中存在对应 prop 时通过。
• Vue DefineComponent 支持标准多泛型声明，读取 props、emits 和 RawBindings/defineExpose 表面。
• 字面量枚举保留真实的 string/number/boolean/null 值；开放类型不会被错误收窄成封闭枚举。
• coverage: false 表示声明只提供了部分证据。已知成员仍会校验，未知成员降为 UNVERIFIABLE warning，不臆断为非法。Versatile 组件可能通过 $attrs 透传 props/listeners/slots，因此默认采用这一保守策略。
• 已知 prop 的普通动态值（如 :data="rows"）不产生噪音 warning，由 vue-tsc 负责表达式类型；无法确定成员名的 v-bind spread、动态 event/slot、全局注册或 auto-import 组件仍会给出 warning。
• KPC/Intact 声明经常不表达 Vue adapter 接受的隐式 default children；这类内容不再误报为非法 slot，复合结构由 component_usage 的安装包示例证明。
• 组件深路径导入若无法由根声明证明，会给出 warning，并交给 vue-tsc/build 判断是否真实可解析；生成代码优先使用清单给出的根导入路径。

最终门禁

fast 优先运行 typecheck 与 lint；如果两者都不存在但有 build，则用 build 作为可用回退。full 会运行项目实际存在的 typecheck、lint、test、build；缺失项作为明确的 residual risk 返回，但不会让原型任务永久无法完成。typecheck/lint 单步最长 5 分钟，test/build 单步最长 15 分钟；取消后不再继续。已有失败只有在同口径基线中存在，或能明确归属到 dirty scope 之外时才可接受。

frontend_finish 会先运行不需要项目脚本的确定性预检；组件、结构、证据或新页面静态路由引用未通过时直接返回，不重复消耗 typecheck/build。只有 visual 模式才启动页面并把真实路由和截图加入预检。预检通过后才运行项目 gate。只有以下条件同时成立时才返回终止信号：

1. 本轮已知变更的 Vue 文件没有契约 error。
2. formatter、patch、codegen 等不透明写入已通过工作区前后快照解析为具体文件；遗留未知范围才回退到 Git 状态。
3. 没有无法解析的写入范围或项目根外改动。
4. 所有可用 full gate 成功，或失败已被基线/文件路径证明只属于本轮范围外的存量问题；缺失 gate 已显式报告。
5. 模板语言可被契约校验器处理。
6. 用户显式要求视觉验收时，变更 SFC 已成功预览，页面级文件的目标路由已验证；code 模式不运行也不宣称视觉验收。
7. 本轮没有生成或大幅扩张出超过 500 行的单体页面 SFC。
8. 新生成页中每个组件 import 都有 contract 或 installed-usage 证据；Table、Dropdown、Select、Form 等复合组件必须有 installed usage，并符合其观测到的子组件结构。表格搜索分页逻辑已按项目语言拆到 utils.ts/utils.js。
9. mock 数据确定、图标名存在于安装包 registry，搜索控件不是未连接的装饰。
10. KPC Table 没有同时启用内置选择列和手写 Checkbox selection 列；列表模板的 checkedKeys 与受控分页仍连接；生成页没有用 any 或 TypeScript suppression 掩盖组件类型问题。
11. visual 模式且提供参考图时，已记录对应页面的参考比较；预览日志没有 console.error。

当前契约 AST 只支持 HTML template。Pug 会明确标记 TEMPLATE_LANGUAGE_UNSUPPORTED 并阻止最终门禁，而不是伪装成已校验。

测试与实包验证

npm run check   # TypeScript strict check
npm test        # manifest / validator / safety / installer / tools / verification tests
npm run build   # ESM + declarations
npm run smoke   # 动态加载 dist 入口并核对九个 Pi 工具

离线实包冒烟结果：KPC 3.8.0 抽取 413 个根导出、95 个组件；Versatile 1.1.2 抽取 1047 个根导出、59 个组件。覆盖了 KPC 间接继承以及 Versatile ProTable 的公开 ref 方法。

这些门禁能证明“声明契约、静态 SFC、项目既有检查均通过”，但不能数学上保证所有运行时行为。新业务仍应为 loading、empty、error、retry、重复交互、可访问性和关键视觉状态补充有针对性的组件/E2E 测试。

安全边界与已知限制

• write/edit 的路径、符号链接逃逸、敏感文件、常见 shell 写入和依赖变更都有保护；交互模式的依赖变更需要确认，headless 默认阻断。
• 真实路由截图会启动目标项目的 dev 脚本，typecheck/test/build 也会执行项目自己的代码。只有项目已受信，或终端用户显式确认后才运行，并设置超时。
• shell 和项目脚本是图灵完备的；命令解析保护是 guardrail，不是 OS sandbox。需要强隔离时应在容器或操作系统沙箱内运行 Pi。
• 当前要求依赖存在于所选项目根的 node_modules；Yarn PnP 与依赖仅 hoist 到工作区父目录的 monorepo 尚未支持。此时请从实际 workspace 根运行，或后续增加受限的 workspace package resolver。
• 当前包名为无 scope 的 pi-frontend-kpc-agent，publishConfig.access 为 public；若改发公司私有 registry，应在发布前调整 registry 与访问策略。