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

2026-08-25 14:52:43 +08:00
parent ac189b8395
commit dbc2f65154
40 changed files with 587 additions and 19 deletions
@@ -1,18 +1,18 @@
 {
  "name": "knowledge",
  "version": "0.1.0",
-  "description": "任务交接、复盘与知识沉淀工作流。",
+  "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
  "author": {
    "name": "CraftKit"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "Knowledge",
-    "shortDescription": "交接、复盘与知识沉淀工具",
-    "longDescription": "提供任务交接、过程复盘、经验维护和工作总结相关的通用工作流。",
+    "shortDescription": "项目初始化与知识沉淀工具",
+    "longDescription": "提供项目 Agent 上下文初始化、任务交接、过程复盘、经验维护和工作总结工作流。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
-    "defaultPrompt": ["帮我总结当前任务并沉淀可复用经验。"]
+    "defaultPrompt": ["帮我初始化项目上下文，或总结任务并沉淀可复用经验。"]
  }
 }
@@ -0,0 +1,41 @@
+---
+name: init
+description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；支持成熟项目延续既有风格，以及空项目根据需求和参考项目建立上下文。普通规范查询、代码脚手架生成或无确认覆盖已有配置不应触发本 Skill。
+---
+
+# 项目初始化
+
+建立可持续维护的项目上下文，使后续 Agent 能识别项目用途、技术栈、代码边界、内部依赖标识和适用规范。只初始化 Agent 与知识资料，不默认生成业务代码。
+
+## 选择模式
+
+先只读探测源码、构建文件、依赖清单、`AGENTS.md` 和 `.craftkit/`：
+
+- 存在有效源码或构建文件时建议“成熟项目”。
+- 仓库为空或只有少量说明文件时建议“空项目”。
+- 向用户说明判断结果，并询问是否有参考项目或参考材料；用户可以覆盖模式。
+
+执行成熟项目模式时读取[成熟项目流程](references/existing.md)；执行空项目模式时读取[空项目流程](references/new.md)。两种模式都遵循[项目配置规则](references/project-config.md)。
+
+## 共同流程
+
+1. 确认项目根目录、初始化模式和参考材料范围。
+2. 扫描当前项目；只在用户授权的路径中扫描参考项目。
+3. 展示自动识别的信息、证据、冲突和待确认项。
+4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；禁止默认最新版本。
+5. 展示拟创建或修改的文件及关键内容，取得确认后再写入。
+6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则和必要索引。
+7. 已有文件必须先完整读取并做保守合并；不明确的用户章节和字段原样保留，不直接覆盖。
+8. 初始化后验证 JSON、索引链接，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态。
+9. 使用 `guidance` 对一个真实项目问题执行检索验证；未安装该 Skill 时改用相同的入口顺序手工验证。
+
+框架版本写入 `technology.frameworks`。成熟项目优先从构建清单和锁文件探测；空项目根据用户选择或参考项目建议填写。只有公共 profile 已真实存在且版本范围匹配时才写入 `profile`，否则保留为空并记录待确认事项。
+
+## 安全边界
+
+- 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。
+- 扫描配置文件时只提取框架、数据库类型、依赖标识等非秘密元数据；疑似凭据只报告位置和风险。
+- 参考项目只用于用户指定的结构、依赖、命名、测试、规范或工具范围，不复制业务代码和专属规则正文。
+- 共享文件不保存个人机器绝对路径。无法转成工作区相对路径的参考位置只写入 `.craftkit/local/`，或仅记录参考项目名称和用途。
+- 内部包名、框架名和依赖标识属于当前项目资料，是否提交由项目自身规则和用户决定；CraftKit 插件不预置这些内容。
+- 不安装 Git Hook、不修改全局工具配置、不联网查询内部信息，也不自动提交初始化产物。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Init"
+  short_description: "按成熟或空项目模式初始化 Agent 上下文与项目资料"
+  default_prompt: "使用 $init 初始化当前项目，先判断成熟项目或空项目，并询问我是否有参考项目。"
@@ -0,0 +1,25 @@
+# 项目协作说明
+
+## 项目定位
+
+- 项目名称：待确认
+- 项目用途：待确认
+- 项目类型：待确认
+
+## 技术与代码边界
+
+技术栈、源码根、包名、模块和内部依赖以 `.craftkit/project.json` 为结构化入口。未确认的信息不得自行补全。
+框架记录精确版本和已存在的公共 profile；普通开发只使用当前 profile，升级或版本比较任务才读取源、目标两个版本。
+
+## 项目资料
+
+- Agent 补充说明：`.craftkit/agents/index.md`
+- 项目规范：`.craftkit/standards/index.md`
+- 可复用知识：`.craftkit/knowledge/index.md`
+
+## 工作约束
+
+- 修改前先阅读与目标目录和任务主题相关的项目资料。
+- 区分明确项目规则、公共建议和从代码观察到的现状。
+- 不提交凭据、个人机器路径、本地状态或可重新生成缓存。
+- 发现规范冲突、信息缺失或多种并存风格时先向用户说明。
@@ -0,0 +1,3 @@
+# Agent 补充说明索引
+
+当前没有项目专属 Agent 补充说明。新增说明时记录适用目录、触发条件和文件路径。
@@ -0,0 +1,13 @@
+# CraftKit 项目资料
+
+本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。
+
+- `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。
+- `agents/`：项目对 Agent 的补充指令。
+- `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `knowledge/`：经过验证的技术决策和可复用经验。
+- `handoff/`：用户明确选择共享的任务交接。
+- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `cache/`：可重新生成的缓存，不进入 Git。
+
+共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -0,0 +1,3 @@
+# Local CraftKit data
+/local/
+/cache/
@@ -0,0 +1,3 @@
+# 项目知识索引
+
+当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。
@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "initialization": { "mode": "new", "references": [] },
+  "project": { "name": "", "description": "", "type": "other" },
+  "technology": { "languages": [], "frameworks": [], "buildTools": [], "databases": [] },
+  "code": { "sourceRoots": [], "packageRoots": [], "modules": [] },
+  "dependencies": { "internal": [], "public": [] },
+  "commands": { "build": [], "test": [], "check": [] },
+  "guidance": {
+    "agentIndex": ".craftkit/agents/index.md",
+    "standardsIndex": ".craftkit/standards/index.md",
+    "knowledgeIndex": ".craftkit/knowledge/index.md"
+  }
+}
@@ -0,0 +1,3 @@
+# 项目规范索引
+
+当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
@@ -0,0 +1,20 @@
+# 成熟项目模式
+
+## 扫描范围
+
+- 现有 `AGENTS.md`、`.craftkit/` 和项目说明。
+- 构建清单与锁文件，例如 Maven、Gradle、npm、Python、Rust 或 Go 的标准文件。
+- 源码根、模块边界、测试目录和自动化配置。
+- 少量具有代表性的入口、接口、服务和测试文件；不得为总结风格读取全部业务代码。
+
+## 提炼规则
+
+- 重复出现且有多个独立样本支持的写法可记录为“现有约定”。
+- 单文件写法、废弃目录和历史兼容代码只记录为观察，不提升为规范。
+- 已有明确规范与代码冲突时保留规范，并列出待处理差异。
+- 多种风格并存时询问用户哪些模块是标准样本，不能按数量自动裁决。
+- 自动识别包根、框架和依赖后必须展示证据，由用户确认是否继续沿用。
+
+## 参考项目
+
+询问参考项目用于哪些方面：架构、依赖、命名、测试、规范或工具。比较结果应区分“当前项目事实”“参考项目做法”和“建议采用项”，只有用户确认的建议才能写为当前项目约定。
@@ -0,0 +1,18 @@
+# 空项目模式
+
+## 必要信息
+
+先询问项目用途、交付形态和是否存在参考项目。随后只补齐会影响初始化资料的决策：
+
+- 应用、库、插件、服务或其他项目类型。
+- 已确定的语言、框架、构建工具和数据库类型。
+- 组织标识、根包名或 npm scope。
+- 需要复用的内部依赖及其可查询来源。
+- 预期模块、测试方式和必须遵守的限制。
+
+## 生成边界
+
+- 未确定的信息使用空数组或“待确认”状态，不猜测框架、包名和内部依赖。
+- 有参考项目时，只提炼用户允许的范围并展示差异。
+- 没有参考项目时使用中性公共基线建立最小索引，不把建议写成强制项目规则。
+- 本模式只创建 `AGENTS.md` 与 `.craftkit/` 资料骨架；用户明确要求搭建代码工程时另行制定实现方案。
@@ -0,0 +1,37 @@
+# 项目配置规则
+
+`.craftkit/project.json` 是可共享的结构化项目元数据，不是依赖锁文件或秘密配置中心。
+
+## 字段原则
+
+- `initialization.mode` 使用 `existing` 或 `new`。
+- `project` 记录名称、用途和项目类型。
+- `technology` 记录语言、框架、构建工具和数据库类型，不记录连接信息。每个框架使用 `name`、`version`、`profile` 对象；精确版本未知或公共 profile 不存在时不得猜测。
+- `code` 记录相对源码根、包根和模块。
+- `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
+- `commands` 只记录经过项目文件或用户确认的命令。
+- `guidance` 指向 `.craftkit/` 内的索引入口。
+- `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。
+
+## 合并规则
+
+- 未在本次扫描中验证的既有字段不得删除。
+- 新证据与旧值冲突时保留旧值并展示差异，用户确认后修改。
+- 数组按语义去重，不因大小写或路径分隔符制造重复项。
+- 所有项目路径使用正斜杠相对路径。
+- 模板中的空值表示待补充，不代表扫描失败。
+
+## 框架版本
+
+```json
+{
+  "name": "framework-name",
+  "version": "已确认的精确版本或空字符串",
+  "profile": "已存在且匹配的公共 profile 或空字符串"
+}
+```
+
+- 先从构建清单和锁文件探测，再由用户确认。
+- 普通项目只选择当前 profile，不登记无关版本。
+- 升级计划中的目标版本属于项目决策或迁移资料，不得冒充当前运行版本。
+- 内部框架可以记录名称和版本，但其规则只能位于项目 `.craftkit/standards/`。
@@ -1,18 +1,18 @@
 {
  "name": "skill",
  "version": "0.1.0",
-  "description": "Codex Skill 创建、迁移、检查与维护工具。",
+  "description": "项目规范检索及 Codex Skill 创建、迁移与维护工具。",
  "author": {
    "name": "CraftKit"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "Skill",
-    "shortDescription": "Codex Skill 创建与维护工具",
-    "longDescription": "提供 Codex Skill 的创建、迁移、规范检查和来源同步工作流。",
+    "shortDescription": "项目规范与 Skill 维护工具",
+    "longDescription": "提供项目规范渐进检索，以及 Codex Skill 的创建、迁移、检查和来源同步工作流。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
-    "defaultPrompt": ["帮我创建或维护一个 Codex Skill。"]
+    "defaultPrompt": ["帮我检索项目规范，或创建和维护一个 Codex Skill。"]
  }
 }
@@ -0,0 +1,40 @@
+---
+name: guidance
+description: 检索当前项目的 AGENTS.md、.craftkit 项目资料和 CraftKit 中性公共基线，返回可追溯的规则、冲突与缺口。适用于查询或应用项目规范；初始化、修改和接入规范不应触发本 Skill。
+---
+
+# 项目规范检索
+
+以只读方式定位当前任务真正适用的项目规则。不得创建、修改或补全规范文件，也不得把代码中的偶然写法自动提升为规范。
+
+## 检索顺序
+
+1. 确定任务涉及的目录、文件类型和主题。
+2. 读取从项目根到目标目录沿途适用的 `AGENTS.md`，距离目标更近的文件约束更具体。
+3. 若存在 `.craftkit/project.json`，读取其中的项目类型、技术栈、代码边界和规范入口。
+4. 涉及框架时按[版本 Profile 路由](references/profile-routing.md)确定当前项目版本；普通开发只加载当前 profile，升级或版本比较才加载源、目标两个 profile。
+5. 按需读取 `.craftkit/agents/index.md`、`.craftkit/standards/index.md`、`.craftkit/knowledge/index.md`；只继续读取索引命中的域、路由和正文。
+6. 项目资料未覆盖主题时，读取[公共基线索引](references/guidance/index.md)，只加载当前任务需要的规则。
+7. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。
+
+目录布局和优先级的详细说明见[检索布局](references/layout.md)。
+
+## 输出
+
+直接回答用户问题，并附带最小充分的依据：
+
+- 结论及其适用范围。
+- 命中的项目相对路径和规则摘要。
+- 项目规则、公共基线或现有代码之间的冲突。
+- 未被规范覆盖、需要用户决定的事项。
+
+区分“明确规则”“公共建议”和“从代码观察到的现状”。没有项目规则时不得声称公共基线是项目强制要求。
+
+## 边界
+
+- 用户当前指令和适用的 `AGENTS.md` 高于 `.craftkit/`；项目规范高于公共基线。
+- `.craftkit/local/` 与 `.craftkit/cache/` 默认不是共享规范来源，除非用户明确要求读取其中的本地上下文。
+- 不读取凭据、环境密钥、数据库连接信息或与问题无关的业务数据。
+- 项目尚未初始化或关键索引缺失时，说明缺口并建议使用 `knowledge` 插件的 `init`；不得在检索过程中隐式初始化。
+- 项目未声明且无法从构建清单确定框架版本时，必须询问用户；禁止默认最新版本或跨版本混用推荐写法。
+- 用户要求新增、整理或修复规范索引时，应交由后续的规范维护 Skill，不在本 Skill 中写文件。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Guidance"
+  short_description: "按索引渐进检索项目规范、中性公共基线及冲突依据"
+  default_prompt: "使用 $guidance 查找当前任务适用的项目规范，并给出可追溯依据。"
@@ -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。