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 组件契约清单]
  C --> D[component_query 精简发现]
  D --> E[component_contract 精确成员]
  D --> U[component_usage 安装包示例 / 组合结构]
  C --> F[Vue SFC 静态校验]
  H[frontend_preview 截图 / 路由] --> 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.2 发布到 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.2/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.2 安装与脚本相同版本的 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.2：固定版本或切换为本地包路径。
• 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.2

本地开发及验收：

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 文件约定
component_query	单次可批量发现最多 12 个已知组件名；单查询最多返回 3 个紧凑候选，精确命中时只返回一个
component_contract	按需读取一个已选组件的 props、events、models、slots、methods 或 exposed 成员；支持 members 聚焦，输出保持为完整 JSON
component_usage	从当前安装版本的 tests/examples/source 提取最小用法，并识别 Table > TableColumn、Dropdown > DropdownMenu > DropdownItem 等组合结构
component_validate	用 Vue/TypeScript AST 校验 SFC 的导入、静态 prop、event、v-model、slot、枚举和必填 prop
frontend_verify	只从固定脚本候选生成 fast 或 full 检查计划；运行项目实际存在的 gate，并区分变更范围内与存量错误
frontend_preview	页面优先启动目标项目并截图真实路由，因而支持 types.ts/utils.ts/mock.ts 等相对导入；无路由的独立组件才走单 SFC 沙箱。返回截图、渲染状态和路由结果，参考 PNG 可计算 SSIM
frontend_finish	校验组件证据、mock/图标/列表结构、视觉与路由，并运行项目可用的 typecheck、lint、test、build 后决定是否结束

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

P0 / P1 / P2 执行策略

P0：先产出，再校验

• 已知组件名通过一次 component_query 批量发现；API 只取需要的成员，复合组件必须再读取安装包中的真实用法，避免套用其他 UI 库的记忆。
• frontend_project_inspect 完成后在后台预取 full 模式下所有可用 gate 的变更前基线；若基线不可用，最终检查仍会按诊断文件路径隔离变更范围与存量错误。
• 源码变更后最多允许两次无关只读调查；当前报错文件、变更文件、组件 usage、验证命令和生成截图不受该预算限制。一次验证尝试后预算会重置，不再因项目缺脚本形成死锁。
• 同一组件错误，或同一文件/错误码/行号的 TypeScript 错误连续出现两次后暂停继续盲改，必须先读取安装声明、component_usage 或精确诊断再恢复编辑。
• 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 判定成立时创建

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

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

• 已有 API、service、store 或邻近页面数据流时，优先复用真实 adapter；测试在边界层 mock。
• 明确是隔离原型/截图、没有可用数据源且需要稳定展示 loading、empty、error、success 状态时，才创建 mock.ts。
• Mock 必须有类型、确定性、无随机数和当前时间依赖，不得把大段数组直接写进 .vue；不要让 mock 静默成为生产默认数据源。
• frontend_verify/frontend_finish 会直接拦截 mock 文件中的 Math.random()、Date.now()、randomUUID()，并检查生成的表格搜索分页页是否导入共置 utils.ts、搜索输入是否真正进入过滤链路。

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"。
• 生成页中的 any、any[]、as any、@ts-ignore/@ts-expect-error 会被视为组件事件/数据类型尚未查明，而不是可接受的修复。

P2：前端结果必须可见、可达

• 截图、原型、视觉还原或提示中出现 .png/.jpg/.webp 路径时会自动启用视觉门禁。
• 每个变更的 Vue 文件必须有成功预览；views/ 页面和 App.vue 还必须证明请求路由已声明且目标页面被路由引用。
• 有已验证路由时，预览工具启动目标项目并截图真实页面，拆分后的相对模块会按项目本身解析；没有路由时才使用独立 SFC 沙箱。
• 预览工具直接把 PNG 作为图像结果返回。只有 wrapper 明确报告渲染成功时才计入视觉证据；错误页 PNG 只作为诊断附件，绝不会因“文件可读”被误判为成功。相同基础设施失败重复两次后会熔断本轮重试。
• 提供项目内参考 PNG 时记录预览与参考尺寸，并在 ffmpeg 可用时计算 SSIM。SSIM 作为诊断信息，最终视觉判断仍需结合截图和业务状态。

版本与发布

版本脚本会修改 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。预检通过后才运行项目 gate。只有以下条件同时成立时才返回终止信号：

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

当前契约 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 与访问策略。