feat(dev): 新增组件样式与表单辅助 Skill

2026-08-25 17:16:03 +08:00
parent da5678f260
commit dec3855ce6
27 changed files with 335 additions and 14 deletions
@@ -1,6 +1,6 @@
 {
  "name": "dev",
-  "version": "0.1.0",
+  "version": "0.2.0",
  "description": "通用软件设计、编码、审查与测试工作流。",
  "author": {
    "name": "CraftKit"
@@ -9,7 +9,7 @@
  "interface": {
    "displayName": "Dev",
    "shortDescription": "软件设计、编码、审查与测试工具",
-    "longDescription": "提供不绑定公司框架的软件设计、编码、审查和测试工作流。",
+    "longDescription": "提供不绑定公司框架的组件选型、样式设计、表单设计及软件开发工作流。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
@@ -0,0 +1,27 @@
+---
+name: component
+description: 根据当前项目的真实依赖、已有用法和可验证契约选择或检查前端组件。适用于字段或场景组件选型、props、events、slots 查证和组件缺口评估；页面实现、视觉样式设计或无证据编造组件契约不应触发。
+---
+
+# 前端组件选型
+
+为当前项目选择可复用组件，并明确每项结论的证据。不要凭经验虚构组件、属性、事件或插槽。
+
+## 工作流
+
+1. 读取 `.craftkit/project.json`、依赖清单、锁文件和现有代码，确认框架、版本及组件来源。
+2. 按 [选型规则](references/selection.md) 比较复用、扩展和新建方案。
+3. 按 [证据规则](references/evidence.md) 查证组件契约及版本兼容性。
+4. 输出推荐组件、适用理由、契约摘要、替代方案、缺口和风险。
+5. 用户需要持续复用扫描结果时，按 [组件索引](references/index.md) 展示拟新增或更新内容；确认后写入 `.craftkit/standards/frontend/components.md`。
+6. 如证据不足，说明缺少的材料并询问用户，不代替后续页面实现 Skill 编写完整页面。
+
+项目没有 `.craftkit/project.json` 时，继续检查真实依赖和现有代码；只有缺失信息会改变结论时才询问用户。
+
+## 边界
+
+- 优先复用项目已有组件和封装，再评估已安装的公共组件库。
+- 内部组件只能从当前项目的源码、类型、示例或项目文档取得契约。
+- 公共组件库可查对应版本的官方文档，不把其他版本的接口当作当前契约。
+- 项目组件索引只保存可验证元数据和项目相对入口，不复制依赖库文档或私有实现。
+- 组件视觉样式交给 `style`，表单结构交给 `form`，完整页面实现交给前端实现 Skill。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "组件选型"
+  short_description: "基于项目证据选择并查证前端组件"
+  default_prompt: "使用 $component 为当前场景选择组件，并列出契约证据和风险。"
@@ -0,0 +1,18 @@
+# 组件契约证据
+
+## 证据优先级
+
+1. 当前项目源码、类型声明、测试和真实调用。
+2. `.craftkit/standards/frontend/` 中经过项目维护的规范。
+3. 本地依赖包中的类型、源码、示例或项目内 Storybook。
+4. 与已安装版本一致的公共组件库官方文档。
+5. 用户明确提供并授权采用的参考项目或设计资料。
+
+## 查证要求
+
+- 记录组件来源和版本，分别列出已验证的 props、events、slots 与限制。
+- 示例代码只能使用已验证契约；无法核实的接口标为待确认。
+- 不把相似组件、其他版本或其他项目的契约直接套用到当前项目。
+- 不复制参考项目的专有实现；只提炼用户授权范围内的通用模式。
+
+若无法取得可靠证据，应询问用户是否有组件文档、参考项目或可访问的源码，不编造结论。
@@ -0,0 +1,18 @@
+# 项目组件索引
+
+组件索引用于减少后续重复扫描，不是第三方文档镜像。默认位置为 `.craftkit/standards/frontend/components.md`。
+
+## 建立流程
+
+1. 读取 `.craftkit/project.json` 中的前端框架、组件库、版本、组件根和文档入口。
+2. 扫描用户授权的组件根、类型、测试、示例和本地文档，只收集当前项目实际存在的组件。
+3. 按组件记录名称、用途、来源、版本范围、源码或文档相对入口、已验证契约和验证日期。
+4. 区分项目自研组件、项目封装和公共依赖组件；公共依赖只链接官方资料或本地类型入口，不复制文档正文。
+5. 展示新增、变更、失效和冲突项，经用户确认后保守合并。
+
+## 维护边界
+
+- 没有源码、类型、测试、真实调用或对应版本官方资料支持的契约不得入库。
+- 依赖升级后将受影响记录标为待复核，不自动沿用旧版本接口。
+- 不写入凭据、私有仓库认证地址、个人绝对路径或参考项目业务代码。
+- 删除或重命名记录前必须核对当前项目并取得确认。
@@ -0,0 +1,21 @@
+# 组件选型规则
+
+## 判断顺序
+
+1. 当前页面或相邻模块已经稳定使用的组件。
+2. 项目公共组件、领域组件及其封装。
+3. 当前依赖中已安装且版本匹配的公共组件。
+4. 扩展现有组件或新建组件。
+
+## 比较维度
+
+- 语义是否匹配字段、操作和状态。
+- 是否能复用现有交互与错误处理方式。
+- 键盘操作、焦点、标签和辅助技术支持是否满足要求。
+- 是否兼容当前框架、组件库和构建工具版本。
+- 是否引入新的依赖、包体或维护成本。
+- 是否能接入项目已有的表单状态、校验和只读展示。
+
+## 输出建议
+
+每个候选项说明“复用、扩展或新建”、适用范围、证据、关键契约和代价。若需求超过现有组件能力，明确缺口，不用未经验证的参数掩盖缺口。
@@ -0,0 +1,23 @@
+---
+name: form
+description: 设计或检查前端表单的分组、列布局、响应式、条件字段、只读展示、错误位置和可访问性。适用于表单结构调整与布局评审；接口设计、业务校验规则、组件契约猜测和完整页面实现不应触发。
+---
+
+# 表单结构设计
+
+依据当前项目的真实组件契约和既有布局模式组织表单，不虚构组件接口、业务规则或固定列数。
+
+## 工作流
+
+1. 检查框架版本、现有表单、布局样式、需求和目标设备。
+2. 从当前项目证据或 `component` 的查证结果取得表单组件契约。
+3. 按 [布局规则](references/layout.md) 设计字段分组、标签、列、条件区域、操作区和响应行为。
+4. 按 [评审清单](references/review.md) 检查校验呈现、键盘操作、只读状态和小视口行为。
+5. 输出结构方案、采用的证据、待确认业务规则和剩余风险；只有用户要求时才修改现有表单文件。
+
+## 边界
+
+- 不设计接口、字典或数据回填协议。
+- 不自行确定字段必填、条件显示或业务校验逻辑；需求不明确时列为待确认。
+- 不使用未经验证的组件、属性、事件或插槽。
+- 视觉令牌和 CSS 交给 `style`，完整业务页面实现交给前端实现 Skill。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "表单设计"
+  short_description: "设计和检查前端表单结构与响应布局"
+  default_prompt: "使用 $form 为当前需求设计表单结构，并列出证据与待确认项。"
@@ -0,0 +1,16 @@
+# 表单布局规则
+
+## 结构
+
+- 按用户任务和信息语义分组，避免只按后端对象机械排列。
+- 标签、控件、提示和错误信息保持可关联且可读。
+- 列数和字段跨度由容器宽度、内容长度和目标设备决定，不采用固定通用值。
+- 条件字段应有稳定的布局位置，并明确隐藏、禁用、清空和保留策略由谁决定。
+- 动态必填只呈现已确认的业务规则，不从界面结构反推规则。
+- 操作区的位置、主次关系和滚动行为应与项目现有模式一致。
+
+## 状态
+
+- 编辑、只读、禁用、加载、空值和错误状态均应可辨识。
+- 只读展示应保留字段语义，不能只依赖颜色表达状态。
+- 小视口下优先保持阅读和操作顺序，处理标签换行、控件溢出和操作区遮挡。
@@ -0,0 +1,12 @@
+# 表单评审清单
+
+- 字段分组和顺序是否符合用户完成任务的流程。
+- 标签是否与控件程序化关联，必填含义是否可感知。
+- 键盘能否按合理顺序访问控件和操作。
+- 焦点、错误、禁用、只读和加载状态是否清晰。
+- 错误信息是否靠近相关字段，并能在提交失败后定位。
+- 条件字段切换是否造成焦点丢失、布局跳动或隐藏错误残留。
+- 小视口、缩放和长文本下是否溢出或遮挡。
+- 组件契约是否有项目源码、类型、测试或对应版本官方文档作为证据。
+- 接口、字典、回填和业务校验是否被明确标为外部输入，而非凭空补全。
+- 未执行构建、浏览器或辅助技术检查时，是否如实标注验证边界。
@@ -0,0 +1,25 @@
+---
+name: style
+description: 基于当前项目的设计令牌、主题、页面和用户参考设计前端视觉规范或 CSS、SCSS。适用于颜色、排版、间距、主题、响应式与状态样式；组件选型、业务表单结构和完整页面实现不应触发。
+---
+
+# 前端样式设计
+
+延续项目已有视觉语言，或在输入充分时建立中性视觉基线。不得把固定品牌、颜色、断点或模板强加给项目。
+
+## 工作流
+
+1. 确认框架版本，并检查设计令牌、主题配置、全局样式和代表性页面。
+2. 按 [来源优先级](references/sources.md) 确定现有设计权威与用户参考的关系。
+3. 识别需要继承、补充或覆盖的颜色、排版、间距、圆角、阴影、断点和交互状态。
+4. 按 [输出约定](references/output.md) 给出规范或样式修改，并说明未验证风险。
+5. 需要写入 `.craftkit/standards/frontend/design.md` 时，先展示拟写内容和合并策略，经用户确认后再修改。
+
+如果项目没有视觉基线，先询问用户是否有设计稿、截图或参考项目；输入仍不足时只给出待确认项，不擅自确定品牌风格。
+
+## 边界
+
+- 优先复用已有变量、令牌和主题能力，避免散落的任意值。
+- 断点由项目目标设备、现有规则或用户要求决定，不内置固定矩阵。
+- 组件契约交给 `component`，表单结构交给 `form`，业务页面实现交给前端实现 Skill。
+- 未进行真实渲染或浏览器检查时，不宣称视觉验收通过。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "样式设计"
+  short_description: "延续项目视觉语言并设计前端样式"
+  default_prompt: "使用 $style 基于当前项目视觉基线设计或调整样式。"
@@ -0,0 +1,22 @@
+# 样式输出约定
+
+## 规范内容
+
+按任务需要选择以下部分，不为凑齐章节虚构规则：
+
+- 颜色与语义状态
+- 字体、字号、行高和字重
+- 间距、尺寸、圆角和阴影
+- 页面层级和背景
+- 断点、目标设备和响应行为
+- 悬停、焦点、禁用、错误和加载状态
+- 对比度、缩放、减少动画等可访问性要求
+
+## 代码要求
+
+- 复用已有 CSS 变量、预处理器变量或主题令牌。
+- 新增令牌时说明命名、作用域、默认值和兼容影响。
+- 避免无来源的魔法数、过深选择器和不必要的强制覆盖。
+- 明确样式是否经过构建、页面渲染、视口和主题验证。
+
+输出末尾列出继承项、新增项、覆盖项、验证证据和剩余风险。
@@ -0,0 +1,12 @@
+# 样式来源优先级
+
+按以下顺序判断设计依据：
+
+1. 当前项目的设计令牌、主题、全局样式和稳定页面。
+2. 用户提供的设计稿、截图、品牌约束或参考项目。
+3. `.craftkit/standards/frontend/` 中的项目规范。
+4. 项目所用公共框架与组件库对应版本的官方资料。
+
+参考项目只用于用户授权的范围。若参考内容与当前项目冲突，列出冲突及合并方案，由用户决定继承还是覆盖。
+
+框架版本应从依赖清单、锁文件或 `.craftkit/project.json` 核实；不要用其他主版本的主题接口、选择器或构建方式替代当前版本。
@@ -1,6 +1,6 @@
 {
  "name": "knowledge",
-  "version": "0.2.0",
+  "version": "0.3.0",
  "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
  "author": {
    "name": "CraftKit"
@@ -22,15 +22,17 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 1. 确认项目根目录、初始化模式和参考材料范围。
 2. 扫描当前项目；只在用户授权的路径中扫描参考项目。
 3. 展示自动识别的信息、证据、冲突和待确认项。
-4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；禁止默认最新版本。
+4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；前端项目还需确认组件库、组件根、文档入口及参考项目范围。禁止默认最新版本。
 5. 展示拟创建或修改的文件及关键内容，取得确认后再写入。
-6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则和必要索引。
+6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则和必要索引；存在前端能力时同时准备 `.craftkit/standards/frontend/components.md` 的最小索引。
 7. 已有文件必须先完整读取并做保守合并；不明确的用户章节和字段原样保留，不直接覆盖。
 8. 初始化后验证 JSON、索引链接，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态。
 9. 使用 `guidance` 对一个真实项目问题执行检索验证；未安装该 Skill 时改用相同的入口顺序手工验证。

 框架版本写入 `technology.frameworks`。成熟项目优先从构建清单和锁文件探测；空项目根据用户选择或参考项目建议填写。只有公共 profile 已真实存在且版本范围匹配时才写入 `profile`，否则保留为空并记录待确认事项。

+前端组件信息写入 `frontend`。成熟项目从依赖清单、锁文件、组件目录、类型和现有调用提取；空项目根据用户已确认的技术选型或授权参考提议填写。未知组件库或版本保持为空，不根据框架名称自行猜测。
+
 ## 安全边界

 - 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。
@@ -5,6 +5,7 @@
 - `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。
 - `agents/`：项目对 Agent 的补充指令。
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `standards/frontend/components.md`：经确认的前端组件来源、版本和契约证据索引。
 - `knowledge/`：经过验证的技术决策和可复用经验。
 - `handoff/`：用户明确选择共享的任务交接。
 - `local/`：当前工作副本的本地上下文，不进入 Git。
@@ -0,0 +1,5 @@
+# 项目组件索引
+
+当前没有已验证的项目组件记录。使用 `component` 扫描当前项目并经用户确认后，在此记录组件用途、来源、版本范围、契约证据和项目相对入口。
+
+本索引不复制第三方文档、私有实现或参考项目业务代码。
@@ -5,6 +5,12 @@
  "technology": { "languages": [], "frameworks": [], "buildTools": [], "databases": [] },
  "code": { "sourceRoots": [], "packageRoots": [], "modules": [] },
  "dependencies": { "internal": [], "public": [] },
+  "frontend": {
+    "framework": "",
+    "componentLibraries": [],
+    "componentRoots": [],
+    "documentation": []
+  },
  "commands": { "build": [], "test": [], "check": [] },
  "documents": { "archiveRoot": "docs/archive", "archiveRules": [] },
  "guidance": {
@@ -14,6 +14,7 @@
 - 已有明确规范与代码冲突时保留规范，并列出待处理差异。
 - 多种风格并存时询问用户哪些模块是标准样本，不能按数量自动裁决。
 - 自动识别包根、框架和依赖后必须展示证据，由用户确认是否继续沿用。
+- 前端项目额外扫描依赖清单、锁文件、组件目录、类型、示例和代表性调用，识别组件库版本及项目封装入口；扫描结果先展示再写入项目配置和组件索引。

 ## 参考项目

@@ -6,6 +6,7 @@

 - 应用、库、插件、服务或其他项目类型。
 - 已确定的语言、框架、构建工具和数据库类型。
+- 前端框架、组件库、精确版本、组件目录规划和可用文档入口。
 - 组织标识、根包名或 npm scope。
 - 需要复用的内部依赖及其可查询来源。
 - 预期模块、测试方式和必须遵守的限制。
@@ -15,4 +16,5 @@
 - 未确定的信息使用空数组或“待确认”状态，不猜测框架、包名和内部依赖。
 - 有参考项目时，只提炼用户允许的范围并展示差异。
 - 没有参考项目时使用中性公共基线建立最小索引，不把建议写成强制项目规则。
+- 前端技术选型未确定时，询问目标平台、交互复杂度、可访问性、团队经验和是否允许新增依赖；只记录用户确认的组件库，不默认选择流行方案。
 - 本模式只创建 `AGENTS.md` 与 `.craftkit/` 资料骨架；用户明确要求搭建代码工程时另行制定实现方案。
@@ -9,11 +9,20 @@
 - `technology` 记录语言、框架、构建工具和数据库类型，不记录连接信息。每个框架使用 `name`、`version`、`profile` 对象；精确版本未知或公共 profile 不存在时不得猜测。
 - `code` 记录相对源码根、包根和模块。
 - `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
+- `frontend` 记录前端框架、组件库、组件根和文档入口；路径必须是项目相对路径，版本必须有依赖清单、锁文件或用户确认作为证据。
 - `commands` 只记录经过项目文件或用户确认的命令。
 - `documents.archiveRoot` 记录可共享的文档归档根；`documents.archiveRules` 记录项目确认的匹配、目标模板、转换和校验规则，不写入公司固定目录或外部系统凭据。
 - `guidance` 指向 `.craftkit/` 内的索引入口。
 - `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。

+## 前端组件信息
+
+- `frontend.framework` 引用 `technology.frameworks` 中已确认的前端框架名称。
+- `frontend.componentLibraries` 使用 `name`、`version`、`source` 对象；`source` 说明依赖清单或锁文件等证据入口。
+- `frontend.componentRoots` 记录项目自研或封装组件的相对目录。
+- `frontend.documentation` 记录项目内组件文档、类型、示例或 Storybook 的相对入口。
+- 未确认的数组保持为空；不得写入私有仓库认证地址或个人绝对路径。
+
 ## 合并规则

 - 未在本次扫描中验证的既有字段不得删除。