git:20250807.349d574 to git:20250814.0b2a2ca

---

alwaysApply: true

---

# CloudBase AI Toolkit 项目规范

## 项目统一约束 ⚠️

### 代码规范（强制要求）

- **所有代码注释必须使用英文，禁止使用中文注释**

- **代码中的变量名、函数名、类名等标识符应使用英文**

- 代码中的字符串内容可以使用中文（如用户界面文本、错误信息等）

### 提交规范（强制要求）

- **Git commit 信息必须使用英文，采用 conventional-changelog 风格**

- **Commit 信息格式：** `type(scope): description`，例如 `feat(auth): add user authentication system`

- **在 feat(xxx): 后面可以添加 emoji 字符**

- **禁止在 commit 信息中使用中文**

### 项目结构

- `doc` 存放对外的文档

- `mcp` 核心的 mcp package

- `config` 用来给 AI IDE提供的规则和 mcp 预设配置

- `tests` 自动化测试

- `specs` 存放核心的迭代过程中沉淀的 spec

---

# 自定义斜杠命令

## 命令列表

### `/list_commands`

**功能：** 列出所有可用的斜杠命令

**触发条件：** 当用户输入 `/list_commands` 时

**行为：** 显示所有可用的命令及其功能描述

### `/new_feature`

**功能：** 新功能开发工作流

**触发条件：** 当用户输入 `/new_feature` 或提出新需求时

**行为：** 采用标准软件工程方式独立开展工作，每个环节完成后都需要用户确认后才可进行下一个环节

**工作流程：**

1. 需求澄清：搞清楚问题和需求

2. 需求文档设计：按照 EARS 简易需求语法方法描述，保存在 `specs/spec_name/requirements.md`

3. 技术方案设计：描述技术架构，保存在 `specs/spec_name/design.md`

4. 任务拆分：细化具体任务，保存在 `specs/spec_name/tasks.md`

5. 执行任务：独立自主运行，及时更新任务状态

### `/add_aiide`

**功能：** 新增 AI IDE 支持

**触发条件：** 当用户输入 `/add_aiide` 时

**行为：** 按照 CloudBase AI Toolkit 新增 AI IDE 支持工作流执行

**步骤：**

1. 创建 IDE 特定配置文件（如 `.mcp.json` 和 `CLAUDE.md`）

2. 更新 `scripts/fix-config-hardlinks.sh` 添加新目标文件到硬链接列表

3. 执行硬链接脚本确保规则文件同步

4. 创建 `doc/ide-setup/{ide-name}.md` 配置文档

5. 更新 `README.md`、`doc/index.md`、`doc/faq.md` 中的 AI IDE 支持列表

6. 更新 IDE 文件映射（在 `mcp/src/tools/setup.ts` 中）

7. 验证硬链接状态和文档完整性

8. 测试IDE特定下载功能是否正常工作

### `/add_example`

**功能：** 新增用户案例/视频/文章

**触发条件：** 当用户输入 `/add_example` 时

**行为：** 按照 CloudBase AI Toolkit 新增用户案例工作流执行

**步骤：**

1. 注意标题尽量用原标题，然后适当增加一些描述

2. 更新 README.md

3. 更新 doc/tutorials.md

### `/sync_doc`

**功能：** 同步文档到官方文档库

**触发条件：** 当用户输入 `/sync_doc` 时

**行为：** 执行 `cp -r doc/* {cloudbase-docs dir}/docs/ai/cloudbase-ai-toolkit/`

### `/update_readme`

**功能：** 更新 README 文档

**触发条件：** 当用户输入 `/update_readme` 时

**行为：**

1. 按照中文文档更新英文文档（README-ZH.md → README.md）

2. 英文文档中的banner 图是英文的，保持不变

3. 复制 README-ZH.md 覆盖 mcp/

### `/fix_config`

**功能：** 修复 config 中的硬链接

**触发条件：** 当用户输入 `/fix_config` 时

**行为：** 执行 `sh ./scripts/fix-config-hardlinks.sh`

### `/git_push`

**功能：** Git 代码提交和推送

**触发条件：** 当用户输入 `/git_push` 时

**行为：**

1. 提交代码注意 commit 采用 conventional-changelog 风格，在feat(xxx): 后面提加一个 emoji 字符，提交信息使用英文描述

2. 提交代码不要直接提到 main，可以提一个分支，例如 feature/xxx，然后

3. 执行 `git push github && git push cnb --force`

4. 然后自动创建 PR

5. 创建完 PR 后还是切回到 main 来

## 需求文档模板

### 需求文档格式

```markdown

# 需求文档

## 介绍

需求描述

## 需求

### 需求 1 - 需求名称

**用户故事：** 用户故事内容

#### 验收标准

1. 采用 ERAS 描述的子句 While <可选前置条件>, when <可选触发器>, the <系统名称> shall <系统响应>，例如 When 选择"静音"时，笔记本电脑应当抑制所有音频输出。

2. ...

```

### 任务计划格式

```markdown

# 实施计划

- [ ] 1. 任务信息

- 具体要做的事情

- ...

- _需求: 相关的需求点的编号

```