<!-- markdownlint-disable MD013 -->
<!-- markdownlint-disable MD029 -->

# 技能开发规则

## 规则简介

本规则定义了技能开发的标准化流程和要求，确保技能添加的规范性、功能分析的准确性和注册信息的一致性。

本规则适用于以下场景：

- **Git仓库技能添加**：从远程Git仓库克隆并注册技能
- **本地路径技能添加**：验证并注册本地技能路径

技能可以是本地路径或Git仓库，添加后将在 `{{ jarvis_data_dir }}/rule` 中注册技能信息，供后续使用。

## Jinja2 变量使用指南

### 可用的内置变量

技能文档文件中可以使用以下 Jinja2 模板变量：

| 变量名                                       | 说明                 | 示例值                   |
| -------------------------------------------- | -------------------- | ------------------------ |
| `{% raw %}{{ rule_file_dir }}{% endraw %}`   | 当前规则文件所在目录 | `/path/to/builtin/rules` |
| `{% raw %}{{ git_root_dir }}{% endraw %}`    | Git 仓库根目录       | `/home/user/project`     |
| `{% raw %}{{ current_dir }}{% endraw %}`     | 当前工作目录         | `/home/user/project/src` |
| `{% raw %}{{ jarvis_src_dir }}{% endraw %}`  | Jarvis 源码目录      | `/home/user/jarvis`      |
| `{% raw %}{{ jarvis_data_dir }}{% endraw %}` | Jarvis 数据目录      | `/home/user/.jarvis`     |

### 变量使用示例

#### 示例 1：在技能文档中引用路径

```markdown
### 技能文件位置

技能文件位于：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/skills/my_skill/`
```

#### 示例 2：动态生成路径

```markdown
### 文档路径

- 技能文档：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/rules/[skill_name].md`
- 技能目录：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/skills/[skill_name]/`
```

#### 示例 3：在代码示例中使用变量

```markdown
### 安装命令

`` `bash
cd {% raw %}{{ jarvis_data_dir }}{% endraw %}/skills/my_skill/
pip install -r requirements.txt `` `
```

## 你必须遵守的原则

### 1. 路径验证原则

- **必须**：在处理任何输入前，先验证其有效性
- **必须**：对于Git URL，确认其格式正确
- **必须**：对于本地路径，确认路径存在且可访问
- **禁止**：直接使用未验证的路径或URL

### 2. 技能分析原则

- **必须**：分析技能的核心功能和特性
- **必须**：优先读取README、package.json、setup.py等文档文件
- **必须**：根据技能复杂度选择合适的分析方法
- **禁止**：仅凭文件名或目录名推断功能

**分析策略：**

- **简单技能**（文件数 < 50，有清晰文档）：直接读取关键文件总结功能
- **复杂技能**（文件数 ≥ 50，文档复杂或缺失）：使用`task_list_manager`创建任务列表进行深度分析

### 3. 注册规范原则

- **必须**：在`{{ jarvis_data_dir }}/rule`中注册技能信息
- **必须**：使用统一的注册格式
- **必须**：记录技能名称、功能描述、位置和添加时间
- **禁止**：覆盖已存在的技能注册信息

## 你必须遵循的工作流程

### 阶段1：输入处理与验证

1. **接收用户输入**（本地路径或Git URL）
2. **判断输入类型**：
   - 如果是Git URL（以`http://`、`https://`、`git@`开头）→ 进入阶段2
   - 如果是本地路径 → 进入阶段3

### 阶段2：Git仓库处理

1. **检查技能目录**：验证`{{ jarvis_data_dir }}/skills`目录是否存在，不存在则创建
2. **提取仓库名称**：从Git URL中提取仓库名称（例如：`https://github.com/user/repo.git` → `repo`）
3. **执行克隆操作**：

   ```bash
   git clone <url> {{ jarvis_data_dir }}/skills/<repo_name>
   ```

4. **处理克隆失败**：询问用户处理方法（重试、更换URL或放弃）
5. **验证克隆结果**：确认克隆后的目录有效

**优化策略：**

- 大仓库使用shallow clone：`git clone --depth 1 <url>`
- 目标目录存在时询问用户是否覆盖

### 阶段3：本地路径验证

1. **路径存在性检查**：确认路径存在
2. **路径可读性验证**：验证路径具有读取权限
3. **错误处理**：路径无效时询问用户确认正确路径

### 阶段4：技能功能分析

1. **关键文档读取**（按优先级）：
   - `README.md`、`README.rst`、`README.txt`
   - `package.json`（Node.js项目）
   - `setup.py`、`pyproject.toml`（Python项目）
   - `Cargo.toml`（Rust项目）
   - `pom.xml`（Java项目）

2. **信息提取分析**：
   - 技能名称识别
   - 核心功能描述
   - 主要特性总结
   - 适用场景分析

3. **复杂度评估**：
   - 统计技能目录文件数量
   - 判断文档完整性
   - 复杂技能使用`task_list_manager`创建深度分析任务

**缺失处理：**

- 文档缺失时基于目录结构推断
- 推断困难时使用基础描述：`[技能名称] - 功能待完善`

### 阶段4.5：创建技能文档文件

1. **检查规则目录**：验证`{{ jarvis_data_dir }}/rules`目录是否存在，不存在则创建
2. **创建技能文档文件**：在`{{ jarvis_data_dir }}/rules`目录下创建`[skill_name].md`文件
3. **编写文档内容**：在文件中详细记录技能的详细介绍和使用方法

   文档内容应包含：
   - 技能名称和功能概述
   - 详细的功能描述
   - 使用方法和示例
   - 适用场景
   - 其他必要说明

4. **验证文档格式**：确保Markdown格式正确

### 阶段5：询问用户是否需要注册

1. **告知用户完成情况**：明确告知用户技能已添加，文档文件已创建
2. **询问注册意愿**：询问用户是否要将技能注册到技能索引中
3. **等待用户确认**：根据用户选择决定是否进入注册阶段

### 阶段6：技能信息注册（仅在用户确认注册后执行）

#### 重要提示：注册前询问用户

- **必须**：在将技能信息注册到索引之前，**必须先询问用户是否需要注册**
- **原因**：有些技能可能不需要注册到索引中（如临时技能、测试技能、内部工具技能等）
- **询问方式**：明确告知用户技能已添加并创建了文档文件，询问是否要将其注册到技能索引中
- **用户选择**：
  - 如果用户选择注册：按照下方要求进行注册
  - 如果用户选择不注册：技能文件和文档仍然存在，可以通过 `load_rule` 工具直接加载使用

#### 注册步骤（仅在用户确认注册后执行）

1. **注册文件检查**：验证`{{ jarvis_data_dir }}/rule`是否存在
2. **创建注册文件**：不存在时创建并写入标准头部：

   ```markdown
   # 技能列表

   本文件记录已添加到Jarvis系统的技能信息。
   ```

3. **追加技能信息**（使用统一格式）：

   ```markdown
   ## [技能名称]

   - **功能描述**：[技能的核心功能描述]
   - **位置**：[技能的完整路径]
   - **规则文件**：`{{ jarvis_data_dir }}/rules/[skill_name].md`
   ```

4. **格式验证**：确保Markdown格式正确

**注册规范：**

- 使用追加模式，禁止覆盖已有信息
- 技能项间保持单一空行分隔
- 技能位置必须使用绝对路径

## 具体要求和规范

### 1. 输入验证规范

- **Git URL格式**：必须支持`http://`、`https://`、`git@`等标准格式
- **本地路径格式**：必须支持绝对路径和相对路径解析
- **路径有效性**：必须验证路径存在性和访问权限
- **输入类型判断**：必须准确区分Git URL和本地路径

### 2. Git操作规范

- **克隆目录结构**：`{{ jarvis_data_dir }}/skills/<repo_name>`
- **克隆失败处理**：必须提供重试、更换URL、放弃等选项
- **仓库名称提取**：必须从URL中正确解析仓库名称
- **shallow clone优化**：大仓库必须使用`--depth 1`参数

### 3. 技能分析规范

- **文档读取优先级**：README → package.json → setup.py → Cargo.toml → pom.xml
- **信息提取完整性**：必须包含技能名称、功能描述、主要特性、适用场景
- **复杂度评估标准**：文件数量<50为简单技能，≥50为复杂技能
- **分析方法选择**：简单技能直接读取，复杂技能使用`task_list_manager`

### 4. 注册格式规范

- **注册前提**：必须询问用户并获得确认后才进行注册
- **注册文件位置**：`{{ jarvis_data_dir }}/rule`
- **技能信息格式**：必须包含功能描述、位置、规则文件
- **技能文档位置**：`{{ jarvis_data_dir }}/rules/[skill_name].md`
- **路径规范**：必须使用绝对路径，禁止相对路径

### 5. 错误处理规范

- **Git克隆失败**：网络检查、URL验证、用户交互处理
- **路径验证失败**：用户确认、拼写检查、重新输入
- **技能分析失败**：基础描述、用户手动输入、功能待完善标记
- **注册失败**：文件权限、格式验证、备份恢复

## 实践指导

### 最佳实践建议

1. **预处理验证**：在执行任何操作前，先进行全面的输入有效性检查
2. **渐进式分析**：从简单文档开始，逐步深入到复杂分析
3. **用户交互优化**：在关键决策点提供清晰的选择和提示
4. **错误恢复机制**：每个阶段都要考虑失败情况和恢复策略

### 性能优化建议

1. **shallow clone使用**：对于大型仓库优先使用浅克隆
2. **文档缓存**：分析过的技能信息可以考虑缓存避免重复分析
3. **并行处理**：多个技能添加时可以考虑批量处理优化

### 质量控制建议

1. **多源验证**：结合多个文档源进行交叉验证
2. **功能完整性检查**：确保提取的功能描述准确全面
3. **格式一致性验证**：注册信息格式必须严格统一

## 执行检查清单

在完成任务后，你必须确认以下项目全部完成：

### 输入验证检查

- [ ] 输入类型判断准确（Git URL或本地路径）
- [ ] Git URL格式验证通过
- [ ] 本地路径存在性和可读性验证通过

### Git操作检查

- [ ] 技能目录结构创建正确（`{{ jarvis_data_dir }}/skills/`）
- [ ] 仓库名称提取准确
- [ ] Git克隆操作执行成功
- [ ] 克隆失败处理机制生效

### 技能分析检查

- [ ] 关键文档文件读取完成
- [ ] 技能功能描述生成准确
- [ ] 复杂度评估标准应用正确
- [ ] 分析方法选择适当

### 注册规范检查

- [ ] 技能文档文件创建成功（`{{ jarvis_data_dir }}/rules/[skill_name].md`）
- [ ] 技能文档内容完整详细
- [ ] 已询问用户是否需要将技能注册到索引
- [ ] 如果用户选择注册，注册文件存在或创建成功
- [ ] 如果用户选择注册，技能信息格式符合标准
- [ ] 如果用户选择注册，路径信息使用绝对路径

### 质量控制检查

- [ ] Markdown语法正确无错误
- [ ] 注册信息格式统一
- [ ] 错误处理机制完备
- [ ] 用户交互流程清晰

## 错误处理规范

### Git克隆失败处理

**必须执行：**

1. **网络连接检查**：验证网络连通性
2. **URL格式验证**：确认Git URL格式正确性
3. **用户交互处理**：提供重试、更换URL、放弃等选项

**处理流程：**

- **重试机制**：允许用户重新执行克隆操作
- **URL更换**：支持用户输入新的Git URL
- **放弃处理**：提供完整的退出机制

### 路径验证失败处理

**必须执行：**

1. **用户确认机制**：询问并确认正确路径
2. **拼写检查提示**：提供路径拼写检查建议
3. **重新输入机会**：允许用户重新输入路径

### 技能分析失败处理

**必须执行：**

1. **基础描述提供**：使用目录名作为技能名称
2. **用户手动输入选项**：允许用户手动提供功能描述
3. **功能待完善标记**：使用"[技能名称] - 功能待完善"标准格式

**降级处理：**

- **文档缺失应对**：基于目录结构进行功能推断
- **分析困难处理**：使用标准化待完善描述
- **用户参与机制**：提供手动输入和确认流程

## 相关资源

- **参考规则**：`{{ rule_file_dir }}/../tool_config/add_rule.md`
- **技能注册文件**：`{{ jarvis_data_dir }}/rule`
- **技能文档目录**：`{{ jarvis_data_dir }}/rules/`
- **技能存储目录**：`{{ jarvis_data_dir }}/skills/`
