---
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. 展示自动识别的信息、证据、冲突和待确认项；读取已有画像时兼容 Schema 1 和 Schema 2。
4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；前端项目还需确认组件库、组件根、文档入口及参考项目范围。禁止默认最新版本。
5. 展示拟创建或修改的文件及关键内容，取得确认后再写入；Schema 1 升级必须展示完整字段差异。
6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则、必要索引和 `.craftkit/standards/document-maintenance.md`；存在前端能力时同时准备 `.craftkit/standards/frontend/components.md` 的最小索引。
7. 已有文件必须先完整读取并做保守合并；不明确的用户章节和字段原样保留，不直接覆盖。
8. 初始化后验证 JSON、索引链接、文档维护规范，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态；按[文档目录配置](references/project-config.md#文档目录)验证过程、共享设计、归档路径和生命周期策略，不创建示例任务或业务文档。
9. 使用 `guidance` 对一个真实项目问题执行检索验证；未安装该 Skill 时改用相同的入口顺序手工验证。

Schema 1 的框架版本继续从 `technology.frameworks` 读取。Schema 2 保留顶层兼容概要，并把精确语言、框架、版本和证据写入 `modules[].technology`。`preferredProfiles` 只记录用户确认的项目偏好，不表示当前机器已经安装插件；运行时发现结果不得写入共享画像。

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

## 安全边界

初始化或更新 `documents` 时，区分过程文档、共享交付文档与归档目标。读取已有值和明确的文档规范；缺失字段按[文档目录配置](references/project-config.md#文档目录)提出默认值，纳入第 5 步的统一预览。目录只按需创建，不因根目录已有说明文档就把根目录配置为过程文档目录。

- 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。
- 扫描配置文件时只提取框架、数据库类型、依赖标识等非秘密元数据；疑似凭据只报告位置和风险。
- 参考项目只用于用户指定的结构、依赖、命名、测试、规范或工具范围，不复制业务代码和专属规则正文。
- 共享文件不保存个人机器绝对路径。无法转成工作区相对路径的参考位置只写入 `.craftkit/local/`，或仅记录参考项目名称和用途。
- 内部包名、框架名和依赖标识属于当前项目资料，是否提交由项目自身规则和用户决定；CraftKit 插件不预置这些内容。
- 不安装 Git Hook、不修改全局工具配置、不联网查询内部信息，也不自动提交初始化产物。