---
name: init
description: 项目初始化技能。当用户输入 "/init" 且没有任何其他内容时触发。用于分析当前项目结构并生成 minimal-agent.md 项目文档。
---

# Init Skill

当用户输入 `/init` 时触发，执行以下任务：

1. 分析项目目录结构
2. 识别技术栈和框架
3. 提取关键配置文件和入口点
4. 深入理解核心模块的运作机制
5. 生成或更新 `minimal-agent.md` 项目文档

---

## 执行步骤

### Step 1: 分析项目结构

使用 Glob 扫描项目，识别：
- 源码目录结构（src/、lib/、app/ 等）
- 配置文件
- 根目录的文档文件
- 测试文件位置

扫描策略：
- 根据语言类型选择对应的源码目录（TS/JS 用 src/，Python 用 lib/ 或直接是 .py 文件）
- 根据语言类型识别配置文件（TS 用 tsconfig.json，Python 用 pyproject.toml 或 requirements.txt）

### Step 2: 识别技术栈

读取项目根目录的配置文件（根据语言类型选择）：
- `package.json` → Node.js/Bun 项目
- `pyproject.toml` / `requirements.txt` → Python 项目
- `Cargo.toml` → Rust 项目
- `go.mod` → Go 项目

识别要点：
- 运行时（Node.js / Bun / Deno / Python / Rust / Go）
- 语言（TypeScript / JavaScript / Python / Rust / Go 等）
- 框架
- 构建工具/包管理器

### Step 3: 提取项目元信息

从以下位置提取：
- `package.json` / `pyproject.toml` / `Cargo.toml` → 项目名、版本、描述
- `README.md` → 项目简介（如果存在）
- `CLAUDE.md` → 如果存在，参考其描述风格（尤其是"核心架构"部分的深度）
- 根目录的 `*.md` 文件 → 了解项目文档结构

### Step 4: 深入理解核心模块

这是最关键的一步。

**识别核心模块的方法**：
1. 找到程序入口文件（名字可能是 main、index、app、run、start 等）
2. 找到类型定义文件（types、models、schemas 等）
3. 找到配置管理文件（config、settings、env 等）
4. 识别主要的功能目录（如 tools/、services/、handlers/ 等）

**读取文件的原则**：
- 不硬编码文件名，根据项目实际情况推断
- 优先读取：有顶部大段注释的文件（通常包含设计意图）
- 优先读取：入口文件和类型定义文件
- 用文件名和目录结构推断模块职责

**需要提取的关键信息**：

| 模块类型 | 需要了解的内容 |
|----------|---------------|
| 主循环/入口 | 工作流程、关键步骤、核心函数 |
| 客户端/通信 | 协议、接口格式、关键函数 |
| 工具/功能集合 | 工具列表、注册方式、参数校验 |
| 上下文管理 | 触发条件、保留策略、关键函数 |
| UI/界面 | 组件结构、状态管理 |

**判断模块类型的信号**：
- 文件名含 `loop`、`main`、`run`、`start` → 主循环类型
- 文件名含 `client`、`http`、`request`、`api` → 通信类型
- 目录名含 `tools`、`handlers`、`commands` → 工具类型
- 文件名含 `context`、`memory`、`history` → 上下文类型

### Step 5: 提取设计原则

从以下位置提取：
- 关键文件顶部的大段注释（通常描述设计理念）
- README.md 中的设计理念
- 代码注释（TODO、FIXME、NOTE 等标记）

---

## 生成 minimal-agent.md

### 文档结构

```markdown
# [项目名]

> [一句话项目简介，从项目配置或 README 提取]

## 技术栈

- **运行时**: [根据项目实际填写]
- **语言**: [根据项目实际填写]
- **框架**: [根据项目实际填写]
- **构建工具/包管理器**: [根据项目实际填写]
- **其他关键依赖**: [列出 2-4 个重要依赖]

## 项目结构

```
[项目名]/
├── [主要源码目录]
│   ├── [按功能划分的子目录或文件]
│   └── ...
├── [其他目录]
└── 配置文件
```

## 快速开始

```bash
[根据项目实际命令填写]
```

## 环境配置

[如果有 .env.example 或类似配置，提取环境变量]

## 核心架构

[对于每个核心模块，详细描述其运作机制]

### [模块名]

[一段话描述模块的职责和定位]

[根据模块类型选择描述方式]
- **主循环类型**：列出关键步骤（1. 2. 3. ...）
- **工具类型**：列出工具/功能列表和重要特性
- **通信类型**：描述协议、接口格式
- **数据处理类型**：描述数据流向

关键函数/类：
- `[名称]` — [一句话描述]

## 设计原则

- [从代码或文档中提取的设计原则，每条一句话]

## 维护提示

> ⚠️ 本文档由 `/init` 自动生成，是了解项目的**线索**而非**真理**。随着项目演进，内容可能变得不准确。涉及代码的具体实现，请在实际使用中核实相关源文件。
```

### 内容质量要求（核心）

**项目简介**：
- 一句话说清楚项目做什么
- 说明项目的定位（学习用/生产用/工具类等）

**技术栈**：
- 只列出最重要的 4-6 项
- 用「**运行时**」「**语言**」「**框架**」等标签

**项目结构**：
- 用目录树展示，不列出具体文件
- 根据项目实际结构描述（不一定是 src/，可能是 lib/ 或直接是根目录的源文件）
- 用 `...` 省略次要文件

**快速开始**：
- 只列出最核心的 4-6 个命令
- 根据项目类型填写（Python 可能是 `pip install` + `python main.py`，Rust 可能是 `cargo build` + `./target/...`）

**核心架构（最重要！）**：
- 这部分是让 agent 能够"修改项目"的关键
- 根据实际识别的模块来描述，不拘泥于固定数量
- 每个模块用"###"小标题
- 描述模块职责和定位（一段话）
- **主循环类型**：列出关键步骤
- **工具类型**：列出工具列表和特性
- **关键函数/类**：用列表展示名称和一句话描述

**设计原则**：
- 只保留真正重要的设计决策
- 每条原则一行，简洁明了
- 3-5 条足够

### 写作风格

**参考 CLAUDE.md 的写作风格**：

✅ 好的描述：
- "当 context 接近上限（contextWindow - 13000 token）时触发压缩"
- "基于 `Tool` 接口（name / description / inputSchema / parameters / call）"

❌ 糟糕的描述：
- "这是一个处理文件的模块"（太模糊）
- "通过某种方式实现了功能"（太模糊）

**写作原则**：
- 写"是什么"和"为什么"，不写"怎么做"
- 用具体数字/名称，不写"[某个值]"
- 让读者知道改哪里、怎么改

---

## 已有文件处理

**如果 `minimal-agent.md` 已存在：**

1. **读取现有内容**，对比新分析的结果
2. **识别差异**：
   - 哪些部分过时了（技术栈变化、模块重构等）
   - 哪些部分仍然有效
   - 哪些新内容需要添加
3. **编辑更新**（而非覆盖）：
   - **保留**：用户之前强调过的规则、设计原则、特殊约定
   - **删除**：过时的模块、不再使用的配置、错误的描述
   - **补充**：新发现的模块、新增的配置、更新后的命令
4. **保持结构一致**：尽量保留原文档的结构，只做局部修改
5. **不改动用户强调的内容**：如果文件中用户用特殊标记（如「注意」「警告」「重要」）强调的内容，要保留

**如果 `minimal-agent.md` 不存在：**
- 按照上面的模板生成新文件

---

## 输出要求

- 输出文件：`minimal-agent.md`（项目根目录）
- 使用中文编写
- 保持简洁，但核心架构部分要有深度
- 不写具体实现细节，但要让读者知道如何修改
- 文件长度建议 100-150 行