feat(skill): 新增项目规范与初始化 Skill

2026-08-25 14:52:43 +08:00
parent ac189b8395
commit dbc2f65154
40 changed files with 587 additions and 19 deletions
@@ -0,0 +1,10 @@
+# API 语义
+
+- 接口以稳定资源或业务能力表达，不把控制器方法名、数据库表名直接暴露为外部契约。
+- HTTP 方法按 RFC 9110 的语义选择。读取、创建处理、整体替换和删除不应全部压缩为同一种方法。
+- 状态码表达协议结果：成功创建、无响应内容、客户端请求问题、认证授权问题、资源不存在、冲突和服务端失败应可区分。
+- 4xx 表示请求或调用方状态需要调整；5xx 表示服务端未能完成看似有效的请求。不得用成功状态包装所有失败。
+- 请求在信任边界校验类型、长度、范围、格式和允许值；业务不变量在业务层再次验证。
+- 响应字段、空值、分页、排序和时间格式形成稳定契约。新增兼容字段通常安全，删除或改变语义需要版本与迁移策略。
+- 错误响应提供稳定错误标识、可理解消息和必要关联 ID，不返回堆栈、SQL、内部路径或秘密值。
+- 重试和幂等设计依据方法语义与业务副作用；涉及支付、任务创建等写操作时使用业务键或幂等机制防止重复执行。
@@ -0,0 +1,10 @@
+# 错误与日志
+
+- 区分业务拒绝、输入错误、认证授权失败、资源冲突、外部依赖失败和内部缺陷；只在系统边界映射为协议响应。
+- 不捕获后静默忽略异常。能够恢复时记录恢复策略，不能恢复时保留原因链并交由统一边界处理。
+- 面向调用方的错误保持稳定、可行动且不泄露内部实现；面向维护者的日志包含必要上下文和关联标识。
+- 日志按事件记录“发生了什么、作用于什么、结果如何”，避免只写“进入方法”或重复打印同一异常。
+- 密码、令牌、私钥、会话标识、完整连接串和不必要的个人数据不得进入日志。
+- 外部调用记录目标类别、耗时、结果和关联 ID；默认不记录完整请求响应正文。
+- 健康检查、指标和追踪应围绕真实依赖及关键用例设计，不能用“进程仍在运行”代替服务可用性。
+- 告警对应可处理故障并控制重复噪声；预期业务拒绝不应全部按系统故障告警。
@@ -0,0 +1,13 @@
+# 后端开发规范索引
+
+本域提供语言和框架中性的后端基线。项目自己的分层、事务、异常和数据访问约定优先。
+
+| 主题 | 读取文件 | 重点 |
+| --- | --- | --- |
+| HTTP 接口 | [API 语义](api.md) | 资源、方法、状态和错误响应 |
+| 业务逻辑 | [服务与事务](service.md) | 职责、用例、事务和幂等性 |
+| 数据访问 | [持久化](persistence.md) | 查询、边界、并发和演进 |
+| 运行诊断 | [错误与日志](error.md) | 错误分类、敏感信息和关联标识 |
+| 验证 | [后端测试](test.md) | 单元、集成、契约和回归 |
+
+只读取当前任务对应的主题；跨层用例再组合相关文件。
@@ -0,0 +1,10 @@
+# 持久化
+
+- 数据访问接口围绕业务查询和写入意图设计，不让上层拼接 SQL、存储过程参数或 ORM 内部对象。
+- 查询只选择需要的数据，限制返回规模；列表接口明确分页、稳定排序和过滤条件。
+- 参数通过驱动或框架的绑定机制传递，不拼接不可信输入形成查询语句、标识符或排序片段。
+- 一次业务读取避免隐式逐条查询。发现 N+1 或无界扫描时，根据数据量和访问模式选择批量、连接或分步加载。
+- 唯一性、外键和非空等可由数据库可靠保证的不变量应具有数据库约束，同时在业务层提供可理解错误。
+- 并发写入使用项目明确的锁、版本或条件更新策略，并检查实际受影响行数。
+- 模式变更考虑向前兼容、存量数据、回滚和分阶段部署；破坏性删除不与依赖旧字段的代码同时上线。
+- 日志和错误不得输出完整 SQL 参数中的秘密或个人数据；诊断信息保持最小充分。
@@ -0,0 +1,9 @@
+# 服务与事务
+
+- 入口层负责协议转换、认证上下文和响应映射；业务服务负责用例编排与业务不变量；持久化层负责数据访问细节。
+- 业务服务使用领域含义清晰的输入输出，不依赖 HTTP 请求对象、界面模型或数据库行结构。
+- 事务边界围绕需要保持一致的业务动作设置，避免把慢速远程调用和无关批处理长期包在数据库事务中。
+- 事务内外的副作用需要明确顺序和失败补偿。数据库提交不能自动保证消息、文件或外部服务已经成功。
+- 并发更新必须说明覆盖、拒绝、重试或合并策略；不能依赖“通常不会同时操作”。
+- 可重试操作区分暂时故障与永久业务拒绝，并设置次数、退避和停止条件；非幂等副作用不得盲目重试。
+- 时间、随机数、当前用户和外部网关等不稳定依赖通过明确边界注入，使业务规则可以独立验证。
@@ -0,0 +1,9 @@
+# 后端测试
+
+- 业务规则和分支使用不依赖框架启动的单元测试，覆盖正常、边界和拒绝路径。
+- 数据映射、事务、查询约束和框架配置使用真实边界的集成测试；仅模拟持久化接口不能证明 SQL 或映射正确。
+- HTTP 层测试验证方法、路径、状态码、序列化、校验和错误契约，不重复证明全部业务分支。
+- 外部服务通过契约明确的替身或隔离环境测试；同时验证超时、错误响应和不可用等失败模式。
+- 并发、幂等和重试逻辑至少包含重复请求、旧版本更新或部分失败等风险场景。
+- 测试数据保持最小且显式，避免依赖执行顺序、共享脏状态、真实凭据或不受控时间。
+- 修复缺陷时增加修复前能够失败的回归测试；无法自动化的真实环境验证应单独列出，不能用静态检查替代。
@@ -0,0 +1,7 @@
+# 共享与本地资料
+
+- 会影响团队共同开发行为的 Agent 指令、规范、决策和项目元数据应放在可审查的共享目录。
+- 凭据、个人机器路径、临时运行状态和可重新生成缓存不得作为共享项目资料提交。
+- `.gitignore` 只影响未跟踪文件；已经被 Git 跟踪的敏感文件不能依靠新增忽略规则自动解除跟踪。
+- 忽略规则应尽量靠近其适用目录，并保持范围最小，避免误排除共享资料。
+- 是否提交内部包名、框架名和依赖标识由项目自身的保密与仓库规则决定；CraftKit 不预置这些信息。
@@ -0,0 +1,9 @@
+# 规则级别
+
+- “必须”仅用于违反后会造成明确兼容性、安全性、数据或流程风险的要求。
+- “禁止”必须同时说明被禁止的行为和适用范围。
+- “建议”表示存在合理例外；偏离时应理解影响并说明原因。
+- “可以”表示真正可选，不应被下游解释为默认义务。
+- 项目规则应尽量写出适用目录、技术范围或触发条件，避免把局部要求扩大到整个仓库。
+
+这些措辞是基于 BCP 14 要求级别思想的中性中文表达，不声称逐字等同于 RFC 定义。
@@ -0,0 +1,7 @@
+# 输入与敏感信息
+
+- 对来自用户、文件、网络或外部系统的输入，在信任边界处校验类型、长度、范围和允许值。
+- 校验失败应给出可操作错误，但不得回显密码、令牌、私钥或完整连接信息。
+- 项目扫描只提取完成任务所需的结构和标识，不收集无关业务数据。
+- 配置示例使用明确占位符，不嵌入真实凭据。
+- 发现疑似凭据时停止复制或写入，并向用户说明文件位置和风险，不在输出中展示秘密值。
@@ -0,0 +1,8 @@
+# 组件边界
+
+- 页面负责路由级组合和用例编排；可复用组件通过清晰输入、输出和插槽等公开接口协作，不直接依赖页面私有状态。
+- 一个组件应围绕单一可描述职责组织。仅为减少行数拆分组件，或把多个无关业务动作塞进同一组件，都会增加隐式耦合。
+- 输入数据按只读契约使用；修改意图通过事件、回调或项目约定的数据流向上表达。
+- 对外接口应采用业务含义命名，说明必填性、默认值和错误状态；不要暴露仅服务于内部实现的临时状态。
+- 优先组合现有语义化组件。抽象前确认至少存在可复用关系，避免只有一个调用方却引入难以理解的通用层。
+- 列表项使用能代表实体身份的稳定键；不得以可变位置代替业务身份，除非列表不会插入、删除或重排。
@@ -0,0 +1,9 @@
+# 数据访问
+
+- 页面和组件通过项目的数据访问边界调用后端，不在多个视图中重复拼接地址、认证头和错误映射。
+- 同时建模初次加载、刷新、空数据、成功和失败状态；不得把空数组同时解释为“尚未请求”和“确实无数据”。
+- HTTP 客户端应检查协议层结果。以 Fetch 为例，服务器返回 4xx 或 5xx 时 Promise 仍可能正常完成，不能只依赖异常捕获判断成功。
+- 解析响应前确认状态、媒体类型和预期结构；错误响应不得按成功模型强制解析。
+- 用户可重复触发的写操作需要防重复提交；是否重试必须考虑方法语义、幂等性和业务副作用。
+- 请求参数、响应字段和日期金额等转换集中在边界层，界面内部使用稳定模型；不要让传输格式渗透到所有组件。
+- 面向用户的错误说明下一步可采取的动作；诊断详情进入受控日志，不直接展示堆栈、内部地址或敏感响应。
@@ -0,0 +1,9 @@
+# 表单与可访问性
+
+- 每个输入控件都应具有可识别名称。优先使用原生 `label` 与控件建立显式关联，不能只用占位文本代替标签。
+- 必填、格式和输入限制在用户操作前可发现；仅用颜色表示必填或错误是不充分的。
+- 校验应覆盖客户端交互反馈，但客户端校验不能替代服务端校验。
+- 错误信息以文本指出具体字段和修正方式，并与对应控件建立可感知关联；提交失败后将焦点或错误摘要引导到可处理位置。
+- 使用原生按钮、输入、表格等语义元素满足需求时，不用无语义容器重新模拟交互控件。
+- 所有主要操作应能通过键盘完成，焦点顺序与视觉和业务顺序一致；弹窗打开、关闭后应有可预测的焦点位置。
+- 提交期间明确展示进行中状态并防止意外重复操作；失败后保留用户仍可安全复用的输入。
@@ -0,0 +1,13 @@
+# 前端开发规范索引
+
+本域提供框架中性的前端基线。项目指定 Vue、React 或其他框架时，应优先读取项目自己的 `.craftkit/standards/`，再把本域作为未覆盖主题的补充建议。
+
+| 主题 | 读取文件 | 重点 |
+| --- | --- | --- |
+| 组件与页面 | [组件边界](component.md) | 职责、接口、组合和复用 |
+| 状态与副作用 | [状态管理](state.md) | 状态归属、派生值和生命周期 |
+| 数据请求 | [数据访问](data.md) | HTTP 结果、并发、取消和展示状态 |
+| 表单与交互 | [表单与可访问性](form.md) | 标签、校验、错误和键盘操作 |
+| 验证 | [前端测试](test.md) | 用户行为、边界和异步状态 |
+
+只读取当前任务对应的文件；跨主题修改时才组合多个规则文件。
@@ -0,0 +1,8 @@
+# 状态与副作用
+
+- 状态放在能够拥有其完整生命周期的最近层级；只有多个独立区域确实共享时才提升到更高层或共享存储。
+- 能从现有状态稳定计算出的值应作为派生值，不保存第二份可独立变化的副本。
+- 远程数据、界面临时状态和用户输入分别建模，避免一个字段同时承担服务器事实和未提交编辑值。
+- 副作用应有明确触发条件和清理时机。订阅、定时器、事件监听及未完成请求在所属生命周期结束时释放或取消。
+- 异步结果写回前确认请求仍然有效；搜索、切页等高频交互应防止旧响应覆盖新状态。
+- 持久化状态前明确存储范围、失效条件和敏感性；令牌或隐私数据不得因开发方便写入不合适的浏览器存储。
@@ -0,0 +1,9 @@
+# 前端测试
+
+- 测试从用户可观察行为出发：输入、操作、可见结果、导航和可访问状态，而不是绑定组件内部变量或私有方法。
+- 纯转换和复杂状态计算使用快速单元测试；组件交互使用渲染测试；关键跨页面流程再使用端到端测试。
+- 异步用例显式覆盖加载、成功、空数据、失败、取消和旧响应晚到等实际状态。
+- 表单至少覆盖有效提交、字段错误、服务端拒绝和重复提交保护。
+- 使用稳定的语义查询或专用测试标识。样式类和深层 DOM 结构不应成为首选定位契约。
+- 模拟应位于真实外部边界，保留本模块内部协作；过度模拟会让测试通过但真实集成失败。
+- 修复缺陷时增加能够在修复前失败的回归用例，并保持断言聚焦于缺陷的外部行为。
@@ -0,0 +1,13 @@
+# 中性公共基线索引
+
+公共基线只在项目资料未覆盖相应主题时提供建议，不替代项目自己的约束。
+
+| 主题 | 读取文件 | 适用场景 |
+| --- | --- | --- |
+| 规则措辞 | [规则级别](common/rule-levels.md) | 编写或解释“必须、建议、可以”等要求 |
+| 项目资料 | [共享与本地资料](common/project-files.md) | 判断 `.craftkit/` 内容是否应共享 |
+| 安全输入 | [输入与敏感信息](common/security.md) | 处理外部输入、配置和凭据风险 |
+| 前端开发 | [前端规范索引](frontend/index.md) | 页面、组件、状态、请求、表单和测试 |
+| 后端开发 | [后端规范索引](backend/index.md) | HTTP API、业务服务、持久化、错误和测试 |
+
+资料依据、重建边界和复核日期记录在[来源登记](sources.md)。
@@ -0,0 +1,16 @@
+# 公共基线来源登记
+
+复核日期：2026-08-25。
+
+| 主题 | 一级资料 | 使用方式 |
+| --- | --- | --- |
+| 规则级别 | [RFC 2119](https://www.rfc-editor.org/info/rfc2119/) 与其更新 RFC 8174 | 只采用要求级别的通用思想，独立编写中文规则 |
+| Git 忽略 | [Git gitignore 文档](https://git-scm.com/docs/gitignore) | 独立总结共享规则、本地规则和已跟踪文件边界 |
+| 输入校验 | [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/stable-en/02-checklist/) | 独立总结信任边界、输入校验与敏感信息原则 |
+| HTTP 语义 | [RFC 9110](https://www.rfc-editor.org/info/rfc9110/) | 独立总结方法、状态码、内容和幂等语义 |
+| 浏览器请求 | [MDN Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | 独立总结网络失败与 HTTP 错误状态的处理边界 |
+| Web 可访问性 | [WCAG 2.2](https://www.w3.org/TR/WCAG22/) 与 [WAI 表单标签教程](https://www.w3.org/WAI/tutorials/forms/labels/) | 独立总结标签、错误、键盘和语义化控件要求 |
+| SQL 注入防护 | [OWASP SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html) | 独立总结参数绑定和不可信查询输入边界 |
+| 应用日志 | [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html) | 独立总结安全事件、敏感字段和日志失败边界 |
+
+本知识库不复制第三方规范正文、公司内部规则、私有组件契约或业务代码。RFC 与 W3C 资料按其文档政策引用；OWASP Cheat Sheet 标明 CC BY-SA 4.0，本项目仅依据其原则独立重写并保留来源链接；MDN 只作为浏览器行为事实依据。新增公共基线时必须登记来源、适用版本、重建日期和必要的许可证说明。
@@ -0,0 +1,44 @@
+# 检索布局
+
+## 来源优先级
+
+1. 用户当前明确指令。
+2. 目标目录适用的 `AGENTS.md`。
+3. `.craftkit/project.json` 声明的项目边界和入口。
+4. `.craftkit/agents/`、`.craftkit/standards/`、`.craftkit/knowledge/` 中的项目资料。
+5. Skill 随附的中性公共基线。
+6. 现有代码，只用于规范未覆盖时观察项目现状。
+
+同一层出现冲突时，不静默选择：列出冲突文件、适用范围和需要用户决定的事项。
+
+## 渐进加载
+
+先读入口，再读路由，最后读正文：
+
+```text
+index.md
+└─ domain/index.md
+   ├─ layers/topic.md
+   └─ rules/detail.md
+```
+
+- 第一跳只判断领域和候选路径。
+- 第二跳只读取当前任务相关的层或横切主题。
+- 第三跳只展开命中的规则正文。
+- 高置信规则已经覆盖问题时停止，不为“完整”继续追踪无关链接。
+- 索引无效时使用文件名、标题和关键词搜索，并在输出中标注使用了兜底检索。
+
+## 项目目录
+
+```text
+.craftkit/
+├─ project.json
+├─ agents/
+├─ standards/
+├─ knowledge/
+├─ handoff/
+├─ local/
+└─ cache/
+```
+
+前五项可以是共享项目资产。`local/` 和 `cache/` 应由 `.craftkit/.gitignore` 排除，不参与普通共享规范检索。
@@ -0,0 +1,23 @@
+# 版本 Profile 路由
+
+## 职责边界
+
+- CraftKit 公共知识库维护根据官方资料独立重建的框架版本差异，例如未来的 Spring 2、Spring 3、Vue 2 和 Vue 3 profile。
+- 当前项目在 `.craftkit/project.json` 中声明实际框架、精确版本和所选 profile。
+- 项目的内部框架、依赖、组件库、历史兼容要求和覆盖规则放在 `.craftkit/standards/`，不得写入公共 profile。
+
+## 选择流程
+
+1. 优先读取 `technology.frameworks` 中的 `name`、`version` 和 `profile`。
+2. 项目未声明时，从 Maven、Gradle、npm 等构建清单与锁文件只读探测，并展示证据。
+3. 精确版本可以确定但没有 profile 映射时，只使用框架中性基线并报告缺口。
+4. 版本或映射无法可靠确定时询问用户，不默认最新版本。
+5. 普通开发任务只加载当前 profile；升级、迁移或版本比较任务才同时加载明确的源 profile 与目标 profile。
+6. 项目规范覆盖公共 profile 时采用项目规则，并在结果中标出冲突和覆盖依据。
+
+## 防止混用
+
+- 未被当前 profile 路由命中的版本规范不得作为普通开发建议。
+- 公共 profile 尚未建立时，不创建空目录或假设规则存在。
+- 框架主版本不足以判断兼容性时继续使用精确版本、生态依赖和项目覆盖规则缩小范围。
+- 代码中出现其他版本写法只能作为迁移风险，不代表项目同时采用多个 profile。