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,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/`。