---
description: "? 需求澄清助手 - 使用EARS语法结构化分析和澄清用户需求"
alwaysApply: false
enabled: true
updatedAt: 2025-11-2 5T09:40:00.000Z
provider: 
---
 # ? EARS 需求澄清助手
 使用 EARS (Easy Approach to Requirements Syntax) 语法帮助用户澄清和结构化需求描述。

 ## ? 需求信息收集

 ### 原始需求描述
$1

 ### 相关上下文检查
!`echo "=== 项目配置 ===" && cat package.json 2>/dev/null | jq -r '.name, .description' || echo "无package.json" && echo "\n=== 现有功能模块 ===" && find . -type f -name "*.tsx" -o -name "*.ts" | grep -E "(components|pages|app)" | head -10 || echo "无相关文件"`

 ### 现有需求文档
!`echo "=== 需求文档 ===" && ls -la | grep -E "需求|规格|spec|requirement" || echo "无需求文档"`

 ## ? EARS 语法模式

 ### 五种需求类型

 #### 1️⃣ Ubiquitous (无处不在型)
**格式**: `系统应<系统响应>`
- 描述系统**始终**要执行的行为
- 示例: "系统应使用 HTTPS 加密所有网络通信"
- 适用: 全局规则、安全要求、性能指标

 #### 2️⃣ Event-Driven (事件驱动型)
**格式**: `当<可选前置条件><触发器>时，系统应<系统响应>`
- 描述**特定事件**触发的行为
- 示例: "当用户点击保存按钮时，系统应验证表单数据"
- 适用: 用户交互、API调用、定时任务

 #### 3️⃣ State-Driven (状态驱动型)
**格式**: `当<状态>时，系统应<系统响应>`
- 描述在**特定状态**下的行为
- 示例: "当用户处于离线状态时，系统应显示缓存的数据"
- 适用: 状态依赖功能、条件显示

 #### 4️⃣ Optional (可选型)
**格式**: `在<特性激活>的情况下，系统应<系统响应>`
- 描述**可选或可配置**的功能
- 示例: "在启用暗黑模式的情况下，系统应使用深色主题配色"
- 适用: 功能开关、配置项、A/B测试
 #### 5️⃣ Unwanted (不期望型)
**格式**: `如果<可选前置条件><触发器>，那么系统应<系统响应>`
- 描述需要**避免或处理**的异常情况
- 示例: "如果用户连续输入错误密码3次，那么系统应锁定账户15分钟"
- 适用: 错误处理、边界情况、安全防护

 ## ? 澄清流程

 ### 第一步：理解需求
1. 识别核心功能和目标用户
2. 提取关键动作和业务流程
3. 标记模糊或不明确的描述

 ### 第二步：提出澄清问题

 #### 事件触发维度
- 这个功能的**触发条件**是什么？（点击/输入/定时/API）
- 是否有**前置条件**需要满足？（登录/权限/状态）
- 触发频率和并发情况如何？

 #### 系统响应维度
- 系统**具体应该做什么**？（保存/跳转/提示/计算）
- 响应时间要求是什么？（实时/异步/批处理）
- 成功标准是什么？（可测量的指标）

 #### 状态依赖维度
- 这个功能依赖什么**状态**？（用户登录/网络连接/数据加载）
- 不同状态下**行为是否不同**？
- 状态转换条件是什么？

 #### 异常处理维度
- 如果操作**失败**会发生什么？（重试/回滚/提示）
- 需要处理哪些**边界情况**？（空数据/超时/权限不足）
- 降级方案是什么？

 #### 可选性维度
- 这是**必需功能**还是**可选功能**？（MVP/增强功能）
- 是否需要**配置开关**？（环境变量/用户设置）
- 优先级如何？（P0/P1/P2）

 ### 第三步：输出结构化需求

 ```markdown
## ? 结构化需求（EARS 格式）
 ### 无处不在型 (Ubiquitous)
- [ ] 系统应...
- [ ] 系统应...

 ### ? 事件驱动型 (Event-Driven)
- [ ] 当...时，系统应...
- [ ] 当...时，系统应...

 ### ? 状态驱动型 (State-Driven)
- [ ] 当...时，系统应...
- [ ] 当...时，系统应...

 ### ? 可选型 (Optional)
- [ ] 在...的情况下，系统应...
- [ ] 在...的情况下，系统应...

 ### ⚠️ 不期望行为 (Unwanted)
- [ ] 如果...，那么系统应...
- [ ] 如果...，那么系统应...
```

 ## ? 质量检查清单

 ### 需求完整性
- [ ] 所有用户交互场景都已覆盖
- [ ] 异常情况和边界条件已明确
- [ ] 性能和安全要求已定义
- [ ] 依赖和前置条件已列出
 ### 需求清晰性
- [ ] 使用精确的动词（验证/保存/跳转，而非处理/操作）
- [ ] 使用具体的名词（登录按钮，而非按钮）
- [ ] 避免技术实现细节（关注"做什么"而非"怎么做"）
- [ ] 每条需求独立且可测试

 ### 需求可行性
- [ ] 技术栈支持该功能实现
- [ ] 时间和资源估算合理
- [ ] 没有相互冲突的需求
- [ ] 优先级和依赖关系清晰

 ## ? 实战示例

 ### 示例 1：待办事项功能
 **原始需求**: "我想做一个待办事项列表"
 **澄清问题**:
1. 添加待办事项的方式？（输入框+按钮 / 快捷键 / 语音输入）
2. 待办事项包含哪些属性？（标题/描述/优先级/截止日期）
3. 如何标记完成？（复选框 / 滑动 / 长按）
4. 是否需要分类或标签？
5. 数据如何持久化？（localStorage / 后端API）
6. 空列表时显示什么？

 **结构化需求**:
```
无处不在型
- 系统应将所有待办事项保存到 localStorage 中
- 系统应在页面加载时自动读取并显示已保存的待办事项
 ? 事件驱动型
- 当用户在输入框中按下回车键时，系统应创建新的待办事项并清空输入框
- 当用户点击待办事项的复选框时，系统应切换该项的完成状态
- 当用户点击删除按钮时，系统应移除该待办事项
 ? 状态驱动型
- 当待办事项列表为空时，系统应显示"暂无待办事项"的友好提示
- 当待办事项已完成时，系统应显示删除线样式
 ⚠️ 不期望行为
- 如果用户尝试添加空白待办事项，那么系统应阻止添加并显示提示
- 如果localStorage不可用，那么系统应显示警告并使用内存存储
```
 ### 示例 2：用户登录功能
 **原始需求**: "实现用户登录"
 **澄清问题**:
1. 登录方式？（用户名密码 / 手机验证码 / 第三方OAuth）
2. 登录失败限制？（次数限制 / 验证码 / 账号锁定）
3. 是否需要"记住我"功能？
4. 登录成功后跳转逻辑？
5. 会话管理策略？（JWT / Session / Cookie）

 **结构化需求**:
```

无处不在型
- 系统应使用 HTTPS 加密传输所有登录凭证
- 系统应在服务端对密码进行哈希加密存储
 ? 事件驱动型
- 当用户输入用户名和密码并点击登录按钮时，系统应验证凭证并跳转到首页
- 当用户点击"忘记密码"链接时，系统应跳转到密码重置页面
 ? 可选型
- 在用户勾选"记住我"的情况下，系统应保存登录状态7天
 ⚠️ 不期望行为
- 如果用户连续3次输入错误密码，那么系统应锁定账户15分钟
- 如果用户名或密码为空，那么系统应显示"请输入完整信息"错误提示
- 如果网络请求失败，那么系统应显示"网络错误，请稍后重试"
```
 ## ? 输出格式模板

 使用以下模板输出澄清结果：
 ```markdown
## ? 需求澄清报告

 ### ? 原始需求
[用户描述的原始需求]

 ### ? 关键澄清问题
1. **触发方式**: [问题]
2. **功能范围**: [问题]
3. **异常处理**: [问题]
4. **优先级**: [问题]
 ### ? 结构化需求（EARS 格式）
 #### 无处不在型 (Ubiquitous)
- [ ] 系统应...

 #### ? 事件驱动型 (Event-Driven)
- [ ] 当...时，系统应...
 #### ? 状态驱动型 (State-Driven)
- [ ] 当...时，系统应...
 #### ? 可选型 (Optional)
- [ ] 在...的情况下，系统应...
 #### ⚠️ 不期望行为 (Unwanted)
- [ ] 如果...，那么系统应...
 ### ? MVP 范围建议
**第一期必做**:
- [核心功能 1]
- [核心功能 2]
 **第二期增强**:
- [增强功能 1]
- [增强功能 2]
 ### ⚠️ 需要确认的关键决策
- [ ] [决策点 1]
- [ ] [决策点 2]
 ### ? 下一步行动
1. 确认以上需求理解是否正确
2. 补充遗漏的需求细节
3. 确定优先级和排期
```

 ## ? 最佳实践

 ### DO ✅
- 使用**精确的动词**：验证、保存、跳转、计算、显示
- 包含**可测量的标准**：3秒内响应、支持1000条数据
- 明确**角色和权限**：管理员可以...、普通用户只能...
- 定义**清晰的边界**：最多上传5MB、最少3个字符
- 关注**用户价值**：为什么要做这个功能？解决什么问题？
 ### DON'T ❌
- 避免模糊词汇：大概、可能、差不多、应该
- 不要混淆需求和实现：不说"使用React Hooks"，说"实现状态管理"
- 不要遗漏异常情况：只写正常流程
- 不要假设隐性知识：不说"按照常规做法"
- 不要过度设计：优先MVP，避免"万一将来..."
 ### 优先级评估
- **P0 (Must Have)**: 没有这个功能系统无法使用
- **P1 (Should Have)**: 重要但有替代方案
- **P2 (Nice to Have)**: 锦上添花的增强功能
- **P3 (Won't Have)**: 本期不做，未来考虑

 ## ? 使用方式
 ### 方式一：直接描述需求
用户直接说：
```
我想做一个用户个人资料编辑功能
```
 助手会自动：
1. 收集项目上下文
2. 提出澄清问题
3. 输出结构化需求
 ### 方式二：携带需求描述
```
帮我澄清需求：实现一个商品搜索功能，支持关键词搜索和筛选
```
 ### 方式三：追加补充信息
如果需求已有部分细节：
```
澄清需求：用户注册功能
- 支持邮箱注册
- 需要发送验证码
- 密码至少8位
```
 ---
**? 现在就开始澄清你的需求吧！**

/req-clarify 我想做一个用户注册功能

---
description: "? TAPD Issue 自动化 - 智能解析需求，自动创建/更新Issue，IDE中预览确认"
alwaysApply: false
enabled: true
updatedAt: 2025-11-27T00:00:00.000Z
provider: 
---

 # ? TAPD Issue 自动化管理流程
 自动化创建和管理 TAPD Issue，包括需求解析、自动创建、属性更新和 IDE 预览确认。
 ## ? 项目地址

 https://tapd.cn/tapd_fe/70112815/story/detail/1070112815128202751

 ### TAPD 平台信息

- 平台：tapd.cn
- API 方式：TAPD MCP Server
- 支持类型：需求(story)、缺陷(bug)、任务(task)
 ## ? 需求类型和优先级
 ### 支持的需求类型
- **Bug 修复** - 「创建 Bug 需求：[问题描述]，优先级 [P0/P1/P2]，处理人 [姓名]」
- **功能优化** - 「创建功能需求：[功能描述]，优先级 [P0/P1/P2]，处理人 [姓名]」
- **文档更新** - 「创建文档需求：[文档问题]，优先级 [P0/P1/P2]」

 ### 优先级映射规则
| 用户描述 | TAPD 优先级 | 说明 |
|---------|------------|------|
| P0、紧急、critical | High | 最高优先级 |
| P1、高、high | High | 高优先级 |
| P2、中、medium | Middle | 中等优先级 |
| P3、低、low | Low | 低优先级 |
 ## ? 自动化执行流程

 ### 第一步：解析用户需求
1. **提取标题** - 从描述中提取核心内容
2. **识别优先级** - 匹配 P0/P1/P2/P3 或 High/Middle/Low
3. **识别处理人** - 提取姓名或"我"代指
4. **生成描述** - 结构化生成详细描述（背景、目标、预期效果）

 ### 第二步：自动创建 Issue
```javascript
stories_create({
  "workspace_id": "从项目列表中自动获取",
  "name": "解析的标题",
  "description": "结构化生成的详细描述",
  "priority_label": "识别的优先级(High/Middle/Low)",
  "creator": "当前用户(dyuankong)"
})
```

 ### 第三步：更新 Issue 属性
```javascript
stories_update({
  "id": "创建后获取的19位ID",
  "workspace_id": "项目ID",
  "priority_label": "High/Middle/Low",
  "owner": "处理人用户名"
})
```

 ### 第四步：IDE 中预览确认
```javascript
preview_url("https://tapd.cn/{workspace_id}/prong/stories/view/{story_id}")
```

 ## ? 智能解析示例

 ### 示例输入
```
"帮我创建一个 Bug 需求：代码补全功能在大文件中响应缓慢，
优先级 P0，处理人是我，需要在本周内解决"
```

### AI 自动解析结果
- **标题**：代码补全功能在大文件中响应缓慢
- **描述**：自动生成结构化描述（包含问题、影响范围、预期效果）
- **优先级**：High (P0)
- **处理人**：dyuankong (当前用户)
- **创建人**：dyuankong
- **项目**：自动从用户参与项目中选择

 ## 人工职责和 AI 职责

 ### ? 人工职责
1. **清晰描述需求** - 说明问题、目标、优先级
2. **指定处理人** - 明确谁负责处理
3. **最终确认** - 在 IDE 中查看并确认需求信息

 ### ? AI 职责
1. **自动获取项目** - 从用户参与的项目中智能选择
2. **智能解析描述** - 提取标题、优先级、处理人等信息
3. **自动创建 Issue** - 调用 TAPD MCP Server 创建
4. **自动更新属性** - 设置优先级、处理人等
5. **自动打开预览** - 在 IDE 中展示需求详情

 ## ? TAPD 链接格式

 ### 完整链接
```
https://tapd.cn/{workspace_id}/prong/stories/view/{story_id}
```

 ### 短链接
```
https://tapd.cn/{workspace_id}/s/{short_id}
```

 ## ? 工作流程图

 ```
用户描述需求
    ↓
AI 解析需求描述（自动）
    ↓
获取项目列表（自动）
    ↓
创建 Issue（自动）
    ↓
更新 Issue 属性（自动）
    ↓
IDE 中打开预览（自动）
    ↓
用户确认 ← 需要修改？→ AI 更新 Issue
    ↓
完成
```

 ## ? 常见使用场景

 ### 场景 1：快速创建 Bug
```
"创建 Bug 需求：用户登录后页面白屏，优先级 P0，处理人是我"
```

 ### 场景 2：功能需求
```
"创建功能需求：增加代码片段收藏功能，方便用户保存常用代码，
优先级 P1，处理人张三"
```

 ### 场景 3：批量创建
```
"创建 3 个需求：
1. 优化搜索性能，P1
2. 增加导出功能，P2
3. 更新用户手册，P3
都由张三处理"
```
 ### 场景 4：关联迭代
```
"创建需求：实现多语言支持，P1，
关联到 2025-Q1 迭代，处理人李四"
```

 ## ⚠️ 重要说明

 ### 平台限制
- 仅适用于腾讯TAPD 平台（tapd.cn）
- ❌ 不允许使用其他任何 issue 平台或项目管理平台

 ### 需求修改
用户可在 IDE 预览中确认后，告知 AI 需要的修改内容，AI 将自动更新 Issue

 ### 数据准确性
- 优先级、处理人等字段自动从描述中提取
- 建议用户在描述时尽量清晰明确

 ---
 **文档版本**: v2.0  
**更新时间**: 2025-11-27  
**维护人**: dyuankong  
**适用平台**: tapd.cn (腾讯TAPD)

 **开始创建 TAPD Issue...**

/issue-create 创建一个 2026 年新年晚会的抽奖小程序APP 需求，优先级 p1，处理人是我

---
allowed-tools: Bash(curl:*), Bash(jq:*), Write, Read
description: 使用 TAPD MCP Sever 查询 TAPD 待办事项，基于优先级生成计划和时间表
---

 # TAPD 待办事项查询和计划生成工具
使用 TAPD MCP Sever  一键查询我在 https://tapd.cn 上面 TAPD 的所有待办需求、缺陷、任务，基于查询结果，借助 AI 帮我按优先级自动生成项目计划。

 ## 工作流程
1. 从 TAPD 系统获取数据
   ├─ 待办需求 (stories)
   ├─ 待办缺陷 (bugs)
   └─ 待办任务 (tasks)

 2. 按优先级分类和排序
   ├─ High (紧急 - 1-2 天)
   ├─ Middle (中等 - 3-5 天)
   └─ Low (普通 - 7+ 天)

 3. 生成项目执行计划
   ├─ 周期规划表
   ├─ 每日任务清单

 ## 使用 Tapd MCP Server 快速查看个人所有待办事项
1.使用 tapd_mcp_http:user_todo_stories_get 工具获取待办需求
2.使用 tapd_mcp_http:user_todo_bugs_get  获取待办缺陷
3.使用 tapd_mcp_http:user_todo_tasks_get  获取待办任务

 ## 优先级决策
 - ? High: 今天必做，不能延期
- ? Middle: 本周完成，可优化分配
- ? Low: 有时间就做，可延后

 ## 参考链接
- [TAPD API 文档](https://tapd.cn)
- [优先级管理最佳实践](https://zh.wikipedia.org/wiki/%E6%97%B6%E9%97%B4%E7%AE%A1%E7%90%86)

- [任务分解方法](https://en.wikipedia.org/wiki/Work_breakdown_structure)
 

/tapd-todo 

---
allowed-tools: Read, Write, Edit, Bash
argument-hint: [框架] | --c4-model | --arc42 | --adr | --plantuml | --full-suite
description: 生成包含图表、ADR和交互式可视化的全面架构文档
---
 # 架构文档生成器
 生成全面的架构文档：$ARGUMENTS

 ## 当前架构上下文

  - 项目结构：!`find . -type f -name "*.json" -o -name "*.yaml" -o -name "*.toml" | head -5`
- 文档存在：@docs/或@README.md（如果存在）
- 架构文件：!`find . -name "*architecture*" -o -name "*design*" -o -name "*.puml" | head -3`
- 服务/容器：@docker-compose.yml或@k8s/（如果存在）
- API定义：!`find . -name "*api*" -o -name "*openapi*" -o -name "*swagger*" | head -3`

 ## 任务

 使用现代工具和最佳实践生成全面的架构文档：

 1. **架构分析和发现**
   - 分析当前系统架构和组件关系
   - 识别关键架构模式和设计决策
   - 记录系统边界、接口和依赖项
   - 评估数据流和通信模式
   - 识别架构债务和改进机会

 2. **架构文档框架**
   - 选择合适的文档框架和工具：
     - **C4模型**：上下文、容器、组件、代码图
     - **Arc42**：全面的架构文档模板
     - **架构决策记录（ADR）**：决策文档
     - **PlantUML/Mermaid**：图表即代码文档
     - **Structurizr**：C4模型工具和可视化
     - **Draw.io/Lucidchart**：可视化图表工具

 3. **系统上下文文档**
   - 创建高级系统上下文图
   - 记录外部系统和集成
   - 定义系统边界和职责
   - 记录用户人物角色和利益相关者
   - 创建系统景观和生态系统概述
 4. **容器和服务架构**
   - 记录容器/服务架构和部署视图
   - 创建服务依赖项映射和通信模式
   - 记录部署架构和基础设施
   - 定义服务边界和API合同
   - 记录数据持久化和存储架构
 5. **组件和模块文档**
   - 创建详细的组件架构图
   - 记录内部模块结构和关系
   - 定义组件职责和接口
   - 记录设计模式和架构风格
   - 创建代码组织和包结构文档
 6. **数据架构文档**
   - 记录数据模型和数据库架构
   - 创建数据流图和处理流水线
   - 记录数据存储策略和技术
   - 定义数据治理和生命周期管理
   - 创建数据集成和同步文档
 7. **安全和合规架构**
   - 记录安全架构和威胁模型
   - 创建身份验证和授权流程图
   - 记录合规要求和控制
   - 定义安全边界和信任区域
   - 创建事件响应和安全监控文档
 8. **质量属性和横切关注点**
   - 记录性能特征和可扩展性模式
   - 创建可靠性和可用性架构文档
   - 记录监控和可观测性架构
   - 定义可维护性和演进策略
   - 创建灾难恢复和业务连续性文档

 9. **架构决策记录（ADR）**
   - 创建全面的ADR模板和流程
   - 记录历史架构决策和基本原理
   - 创建决策跟踪和审查流程
   - 记录权衡和考虑的替代方案
   - 建立ADR维护和演进程序

 10. **文档自动化和维护**
    - 从代码注释设置自动图表生成
    - 配置文档流水线和发布自动化
    - 设置文档验证和一致性检查
    - 创建文档审查和审批流程
    - 培训团队架构文档实践和工具
    - 建立文档版本控制和变更管理

/架构文档生成 执行

---
description: 智能上下文管理和优化
---

 # 上下文优化：$ARGUMENTS

 ## 上下文分析

 ** 对话长度 **：当前对话包含约 X 条消息
**Token 使用 **：预估 token 消耗情况
** 关键信息 **：识别核心讨论内容

 ## 压缩策略

 ### 1. 保留关键信息
- ** 项目背景 **：@CodeBuddy.md
- ** 当前任务 **：$ARGUMENTS
- ** 重要决策 **：技术选型、架构设计
- ** 待解决问题 **：阻塞问题、技术难点
 
 ### 2. 移除冗余内容
- 重复的代码片段
- 已解决的问题讨论
- 过程性的调试信息
- 不相关的话题

 ### 3. 结构化总结
** 项目状态 **：
- 当前进度
- 完成的功能
- 待开发特性

 ** 技术栈 **：
- 主要框架和库
- 开发工具配置
- 部署环境

 ** 约定规范 **：
- 代码风格
- 命名约定
- 文件组织

 ## 优化建议
 
 基于分析结果，建议在以下时机进行上下文压缩：
- 对话消息超过 50 条
- 讨论主题发生转换
- 开始新的开发阶段
- Token 使用接近限制

 使用 `/compact` 命令执行压缩，保留核心上下文信息。

/compact 

---
allowed-tools: Read, Write, Edit, Bash
argument-hint: [功能名] | [功能类型] [名字]
description: 使用样板代码、测试和文档为新功能搭建开发框架，实现快捷开发
---

 # 创建功能

  为新功能搭建开发框架：$ARGUMENTS
 ## 当前项目上下文
 - 项目结构：!`find . -maxdepth 2 -type d -name src -o -name components -o -name features | head -5`
- 当前分支：!`git branch --show-current`
- 包信息：@package.json或@Cargo.toml或@requirements.txt（如果存在）
- 架构文档：@docs/architecture.md或@README.md（如果存在）
 ## 任务
 按照以下系统方法创建新功能：$ARGUMENTS
 1. **功能规划**
   - 定义功能要求和验收标准
   - 将功能分解为更小、可管理的任务
   - 识别受影响的组件和潜在影响区域
   - 在实现之前计划API/接口设计

 2. **研究与分析**
   - 研究现有代码库模式和约定
   - 为一致性识别类似功能
   - 研究所需的外部依赖或库
   - 审查任何相关文档或规范
 3. **架构设计**
   - 设计功能架构和数据流
   - 如果需要，计划数据库架构更改
   - 定义API端点和合同
   - 考虑可扩展性和性能影响
 4. **环境设置**
   - 创建新功能分支：`git checkout -b feature/$ARGUMENTS`
   - 确保开发环境是最新的
   - 如果需要，安装任何新的依赖项
   - 根据适用情况设置功能标志

 5. **实现策略**
   - 从核心功能开始并逐步构建
   - 遵循项目的编码标准和模式
   - 实现适当的错误处理和验证
   - 使用依赖项注入并保持松散耦合

 6. **数据库更改（如果适用）**
   - 为架构更改创建迁移脚本
   - 确保向后兼容性
   - 计划回滚场景
   - 在示例数据上测试迁移

 7. **API开发**
   - 实现具有适当HTTP状态代码的API端点
   - 添加请求/响应验证
   - 实现适当的身份验证和授权
   - 记录API合同和示例

 8. **前端实现（如果适用）**
   - 遵循项目模式创建可重用组件
   - 实现响应式设计和可访问性
   - 添加适当的状态管理
   - 处理加载和错误状态

 9. **测试实现**
   - 为核心业务逻辑编写单元测试
   - 为API端点创建集成测试
   - 为用户工作流添加端到端测试
   - 测试错误场景和边界情况

 10. **安全考虑**
    - 实现适当的输入验证和清理
    - 为敏感操作添加授权检查
    - 审查常见安全漏洞
    - 确保数据保护和隐私合规
 11. **性能优化**
    - 优化数据库查询和索引
    - 在适当的地方实现缓存
    - 监控内存使用并优化算法
    - 考虑延迟加载和分页

 12. **文档**
    - 添加内联代码文档和注释
    - 更新API文档
    - 创建用户文档（如果需要）
    - 根据适用情况更新项目README
 13. **代码审查准备**
    - 运行所有测试并确保它们通过
    - 运行linting和格式化工具
    - 检查代码覆盖率和质量指标
    - 执行变更的自审查
 14. **集成测试**
    - 测试功能与现有功能的集成
    - 验证功能标志正常工作
    - 测试部署和回滚程序
    - 验证监控和日志记录
 15. **提交和推送**
    - 创建带有描述性消息的原子提交
    - 如果项目使用，遵循常规提交格式
    - 推送功能分支：`git push origin feature/$ARGUMENTS`

 16. **拉取请求创建**
    - 创建包含全面描述的PR
    - 根据适用情况包含屏幕截图或演示
    - 添加适当的标签和审查者
    - 链接到任何相关问题或规范

 17. **质量保证**
    - 与QA团队协调进行测试
    - 解决发现的任何错误或问题
    - 验证可访问性和可用性要求
    - 在不同的环境和浏览器上测试
 18. **部署规划**
    - 计划功能推出策略
    - 建立监控和告警
    - 准备回滚程序
    - 安排部署和通信

 记住在整个开发过程中保持代码质量、遵循项目约定并优先考虑用户体验。
 

/创建功能 开发一个 1024 小游戏

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*), Bash(git log:*)
argument-hint: [message] | --no-verify | --amend
description: 创建格式规范的提交信息，使用常规提交格式和表情符号
---

 # 智能 Git 提交
 创建格式规范的提交：$ARGUMENTS

 ## 当前仓库状态
- Git 状态：!`git status --porcelain`
- 当前分支：!`git branch --show-current`
- 暂存的更改：!`git diff --cached --stat`
- 未暂存的更改：!`git diff --stat`
- 最近的提交：!`git log --oneline -5`

 ## 此命令的作用

 1. 除非使用 `--no-verify` 指定，否则自动运行提交前检查：
   - `pnpm lint` 确保代码质量
   - `pnpm build` 验证构建成功
   - `pnpm generate:docs` 更新文档
2. 使用 `git status` 检查哪些文件已暂存
3. 如果有 0 个文件暂存，自动使用 `git add` 添加所有修改的和新文件
4. 执行 `git diff` 以了解正在提交的更改
5. 分析差异以确定是否存在多个不同的逻辑更改
6. 如果检测到多个不同的更改，建议将提交拆分为多个较小的提交
7. 为每个提交（或单个提交（如果不拆分））使用表情符号常规提交格式创建提交信息
 ## 提交的最佳实践

- **提交前验证**：确保代码已通过 lint 检查、能正确构建、文档已更新
- **原子提交**：每个提交应包含服务于单一目的的相关更改
- **拆分大更改**：如果更改涉及多个关注点，请将其拆分为单独的提交
- **常规提交格式**：使用格式 `<type>: <description>`，其中类型是以下之一：
  - `feat`：新功能
  - `fix`：错误修复
  - `docs`：文档更改
  - `style`：代码样式更改（格式化等）
  - `refactor`：既不修复错误也不添加功能的代码更改
  - `perf`：性能改进
  - `test`：添加或修复测试
  - `chore`：对构建过程、工具等的更改
- **现在时、祈使语气**：将提交信息编写为命令（例如，"add feature" 而不是 "added feature"）
- **简洁的第一行**：保持第一行在 72 个字符以下
- **表情符号**：每个提交类型都配有相应的表情符号：
  - ✨ `feat`：新功能
  - ? `fix`：错误修复
  - ? `docs`：文档
  - ? `style`：格式化/样式
  - ♻️ `refactor`：代码重构
  - ⚡️ `perf`：性能改进
  - `test`：测试
  - ? `chore`：工具、配置
  - ? `ci`：CI/CD 改进
  - ?️ `revert`：恢复更改
  - ? `test`：添加失败的测试
  - ? `fix`：修复编译器/linter 警告
  - ?️ `fix`：修复安全问题
  - ? `chore`：添加或更新贡献者
  - ? `refactor`：移动或重命名资源
  - ?️ `refactor`：进行架构更改
  - ? `chore`：合并分支
  - ?️ `chore`：添加或更新编译文件或包
  - ➕ `chore`：添加依赖项
  - ➖ `chore`：移除依赖项
  - ? `chore`：添加或更新种子文件
  - ?‍? `chore`：改善开发者体验
  - ? `feat`：添加或更新与多线程或并发相关的代码
  - ?️ `feat`：改善 SEO
  - ?️ `feat`：添加或更新类型
  - ? `feat`：添加或更新文本和字面量
  - ? `feat`：国际化和本地化
  - ? `feat`：添加或更新业务逻辑
  - ? `feat`：处理响应式设计
  - ? `feat`：改善用户体验/可用性
  - ? `fix`：非关键问题的简单修复
  - ? `fix`：捕获错误
  - ?️ `fix`：因外部 API 更新代码
  - ? `fix`：删除代码或文件
  - ? `style`：改进代码的结构/格式
  - ?️ `fix`：关键热修复
  - ? `chore`：开始项目
  - ? `chore`：发布/版本标签
  - ? `wip`：进行中的工作
  - ? `fix`：修复 CI 构建
  - ? `chore`：将依赖项固定到特定版本
  - ? `ci`：添加或更新 CI 构建系统
  - ? `feat`：添加或更新分析或跟踪代码
  - ✏️ `fix`：修复拼写错误
  - ⏪️ `revert`：恢复更改
  - ? `chore`：添加或更新许可证
  - ? `feat`：引入重大更改
  - ? `assets`：添加或更新资源
  - ♿️ `feat`：改善可访问性
  - ? `docs`：在源代码中添加或更新注释
  - ?️ `db`：执行数据库相关更改
  - ? `feat`：添加或更新日志
  - ? `fix`：删除日志
  - ? `test`：模拟事物
  - ? `feat`：添加或更新彩蛋
  - ? `chore`：添加或更新 .gitignore 文件
  - ? `test`：添加或更新快照
  - ⚗️ `experiment`：执行实验
  - ? `feat`：添加、更新或删除功能标志
  - ? `ui`：添加或更新动画和过渡
  - ⚰️ `refactor`：删除死代码
  - ? `feat`：添加或更新与验证相关的代码
  - ✈️ `feat`：改善离线支持
 ## 拆分提交的指南

 分析差异时，请根据以下标准考虑拆分提交：

1. **不同关注点**：对代码库不相关部分的更改
2. **不同类型的更改**：混合功能、修复、重构等
3. **文件模式**：对不同类型文件的更改（例如，源代码 vs 文档）
4. **逻辑分组**：分开更容易理解或审查的更改
5. **大小**：非常大的更改，如果分解会更清晰
 ## 示例
 好的提交信息：
- ✨ feat: 添加用户认证系统
- ? fix: 解决渲染过程中的内存泄漏
- ? docs: 使用新端点更新 API 文档
- ♻️ refactor: 简化解析器中的错误处理逻辑
- ? fix: 解决组件文件中的 linter 警告
- ?‍? chore: 改善开发者工具设置过程
- ? feat: 实现交易验证的业务逻辑
- ? fix: 解决头部中轻微的样式不一致
- ?️ fix: 修补认证流程中的关键安全漏洞
- ? style: 为更好的可读性重新组织组件结构
- ? fix: 删除已弃用的遗留代码
- ? feat: 为用户注册表单添加输入验证
- ? fix: 解决失败的 CI 管道测试
- ? feat: 实现用户参与度分析跟踪
- ?️ fix: 加强身份验证密码要求
- ♿️ feat: 改善屏幕阅读器的表单可访问性
 拆分提交的示例：
- 第一次提交：✨ feat: 添加新的 solc 版本类型定义
- 第二次提交：? docs: 为新 solc 版本更新文档
- 第三次提交：? chore: 更新 package.json 依赖项
- 第四次提交：?️ feat: 为新 API 端点添加类型定义
- 第五次提交：? feat: 改善工作线程中的并发处理
- 第六次提交：? fix: 解决新代码中的 lint 问题
- 第七次提交：test: 为新 solc 版本功能添加单元测试
- 第八次提交：?️ fix: 更新存在安全漏洞的依赖项
 ## 命令选项
- `--no-verify`：跳过运行提交前检查（lint、build、generate:docs）

 ## 重要说明

- 默认情况下，提交前检查（`pnpm lint`、`pnpm build`、`pnpm generate:docs`）将运行以确保代码质量
- 如果这些检查失败，您将被问及是否要继续提交或先修复问题
- 如果已有特定文件暂存，命令将只提交这些文件
- 如果没有文件暂存，它将自动暂存所有修改的和新文件
- 提交信息将根据检测到的更改构建
- 在提交之前，命令将检查差异以确定多个提交是否更合适
- 如果建议多个提交，它将帮助您分别暂存和提交更改
- 始终检查提交差异以确保信息与更改匹配

/执码提交

---
description: "? Git变更分析 - 分析当前git状态、分支信息和变更详情"
---
 # ? Git 变更分析器
 分析 Git 仓库的变更信息，为分支创建、提交信息生成提供决策依据。

 ## ? 分析目标

 | 分析项 | 说明 |
|-------|------|
| **Git 状态** | 工作区和暂存区状态（整个仓库） |
| **分支信息** | 当前分支和远程信息 |
| **变更统计** | 修改的文件和代码行数 |
| **变更详情** | 具体的文件变更和代码差异 |
| **变更范围** | 区分 agent-cli 和其他包的变更 |
| **提交历史** | 最近的提交信息风格 |

 ## ? 执行步骤
 **重要**：使用 Bash 工具执行以下命令，合并相关命令减少 tool call 次数。

 ### 1. 基础信息收集
```bash
REPO_ROOT=$(git rev-parse --show-toplevel) && \
echo "=== 仓库根目录 ===" && echo "$REPO_ROOT" && \
echo -e "\n=== Git 状态 ===" && git -C "$REPO_ROOT" status --short && \
echo -e "\n=== 当前分支 ===" && git -C "$REPO_ROOT" branch --show-current && \
echo -e "\n=== 远程仓库 ===" && git -C "$REPO_ROOT" remote -v
```

 ### 2. 变更统计和文件列表
```bash
REPO_ROOT=$(git rev-parse --show-toplevel) && \
echo "=== 整体变更统计 ===" && \
(git -C "$REPO_ROOT" diff --cached --stat 2>/dev/null || git -C "$REPO_ROOT" diff --stat 2>/dev/null || echo "无变更") && \
echo -e "\n=== 文件变更列表 ===" && \
(git -C "$REPO_ROOT" diff --name-status 2>/dev/null || echo "无文件变更")
```
 ### 3. agent-cli 包的变更详情
```bash
REPO_ROOT=$(git rev-parse --show-toplevel) && \
echo "=== agent-cli 包变更统计 ===" && \
(git -C "$REPO_ROOT" diff --stat -- packages/agent-cli/ 2>/dev/null || echo "agent-cli 包无变更") && \
echo -e "\n=== 其他包变更 ===" && \
(git -C "$REPO_ROOT" diff --name-only 2>/dev/null | grep -v '^packages/agent-cli/' || echo "其他包无变更")
```

 ### 4. 未跟踪文件和提交历史
```bash
REPO_ROOT=$(git rev-parse --show-toplevel) && \
echo "=== 未跟踪文件 ===" && \
(git -C "$REPO_ROOT" ls-files --others --exclude-standard | grep -E '\.(ts|js|json|md|yml|yaml)$' || echo "无相关未跟踪文件") && \
echo -e "\n=== 最近提交历史 ===" && \
(git -C "$REPO_ROOT" log --oneline -5 --format="%s" || echo "无提交历史")
```

 ## ? 分析报告

 基于以上命令输出，生成简洁的变更分析报告：

 ### 1. 当前状态
- 当前分支和远程仓库信息
- 工作区状态（已暂存/未暂存/未跟踪文件数量）

 ### 2. 变更范围
- agent-cli 包的变更文件数
- 其他包的变更（如果有）

 ### 3. 变更性质
- 根据文件变更判断类型：feat/fix/refactor/docs/chore
- 识别主要变更点
 ### 4. 关键变更点
- 列出主要的文件变更
- 重点关注 agent-cli 包的变更

 ### 5. 提交风格参考
- 最近的提交信息格式
- 用于保持一致的命名风格

 ## ⚠️ 错误处理

 | 问题 | 处理方式 |
|------|---------|
| 命令执行失败 | 显示友好提示（如「无变更」），继续执行后续步骤 |
| 空输出 | 显示相应提示，这是正常情况 |
| 大型变更 | 输出已限制行数，避免信息过载 |

 ## 输出要求

 1. **信息准确性**：直接从命令输出提取信息，不臆测
2. **突出重点**：优先展示 agent-cli 包的变更
3. **标识范围**：明确指出是否包含其他包的变更
4. **支持决策**：提供足够信息支持后续的分支创建和提交信息生成
 

/执码提交

---
description: "? 智能发版 - 自动更新版本号和changelog，执行构建验证并创建发版MR"
argument-hint: "[custom-prompt]"
---
# ? 智能发版流程

分析变更历史，自动更新版本号和changelog，执行构建验证并创建发版MR。

## ? 发版信息收集

### 工作区和分支状态
!`git status --porcelain && echo "--- Current Branch ---" && git branch --show-current && echo "--- Remote Status ---" && git fetch origin && git status -uno`

### 当前版本信息
!`echo "Package.json version:" && jq -r '.publishConfig.customPackage.version // .version' package.json`

### Changelog 结构检查
!`echo "Current CHANGELOG.md:" && head -20 CHANGELOG.md 2>/dev/null || echo "CHANGELOG.md 不存在"`

### 最近提交历史
!`git log --oneline -10 --format="%s"`

### 未发布变更检查
!`grep -n "未发布" CHANGELOG.md | head -5 || echo "无未发布标记"`

## ? 发版策略

### 版本号规则
遵循 [语义化版本]( https://semver.org/lang/zh-CN/ ) 规范：
- `major.minor.patch` - 主版本.次版本.修订版本
- **Major**: 破坏性变更 (BREAKING CHANGE)
- **Minor**: 新功能 (feat)  
- **Patch**: 修复和改进 (fix, docs, chore等)

### 分支命名规范
- `Release/Travel-v{版本号}` - 发版分支
- 例如: `Release/Travel-v1.0.12`

## ? 自动化流程

1. **执行构建验证**（确保代码质量）
2. **分析变更类型确定版本号**
3. **创建发版分支**（如在主分支）
4. **更新package.json版本号**（改 publishConfig.customPackage.version 这个字段的版本号）
5. **更新CHANGELOG.md**（移除"未发布"标记，添加发布日期）
6. **生成发版提交信息**
7. **暂存并所有提交变更（git add .）**
8. **推送到远程**
9. **在 IDE 内置浏览器进行预览， open 命令打开MR页面，等待合并，不要跳转到外部浏览器**

### 构建验证步骤，不要做任何代码修改！！！
```bash
npm install 
不要执行 npm run build，npm run dev 通过即可   # 生产环境构建验证
npm run dev     # 开发环境启动验证（包含lint检查）

 ```

 ### 代码提交和推送
```bash
git add .
git commit -m "chore(release): v{版本号} - {变更摘要}"
git push origin {发版分支名}
```

 ### 额外补充说明

 ！重要事项，不要修改本地的任代码！！！
---
**开始智能发版流程...**
 

# 测试驱动开发（TDD）工作流

 我将帮助你使用测试驱动开发来实现需求变更。这是一个确保高质量、经过充分测试代码的优秀工作流。

 ## TDD 流程概览
 我将严格遵循以下步骤：
1. **先编写失败的测试** - 基于你的需求
2. **验证测试失败** - 确认我们测试的是正确的内容
3. **实现最小化代码** - 刚好足够让测试通过
4. **必要时重构** - 在保持测试通过的前提下改进代码

 ## 你的需求
 请提供：
1. **你想要什么功能/变更？**
   - 描述期望的行为
   - 包含需要处理的边界情况

 2. **测试示例（可选但有帮助）：**
   - 输入/输出对
   - 错误场景
   - 性能要求

 3. **测试框架偏好：**
   - 你的项目使用哪个测试框架？
   - 有特定的测试模式需要遵循吗？

 ## 重要提示

 - 在编写并使测试失败之前，我**不会**编写任何实现代码
- 一旦开始实现，我**不会**修改测试（除非测试本身有 bug）
- 我将使用你项目的测试命令高效运行测试
- 我会从你的项目设置中识别合适的测试命令
 ## 我将遵循的流程
 ### 阶段 1：测试创建
```bash
# 1. 分析现有测试结构（查找 *.test.tsx 或 *.spec.ts 文件）

 # 2. 编写全面的测试
# 3. 运行测试并确认它们失败
npm test  # 或使用你的项目测试命令
```

 ### 阶段 2：实现
```bash
# 1. 编写最小化实现
# 2. 重复运行测试直到全部通过
npm test  # 或 npm test -- --watch
# 3. 避免过度拟合特定测试用例
```

 ### 阶段 3：验证
```bash
# 1. 运行完整测试套件
npm test

 # 2. 检查测试覆盖率（如果可用）
npm test -- --coverage

 # 3. 所有测试通过后提交代码
git add .
git commit -m "feat: 实现功能并通过测试"
```

 让我们开始吧！你想使用 TDD 实现什么功能？
 

---
description: "? JavaScript/TypeScript 代码规范审查助手"
---

 你是一个专业的JavaScript/TypeScript开发助手，所有代码必须严格遵循以下编码规范，当我引用的时候，针对我的项目进行执行检查，最终输出 html 报告，然后调用企业微信机器人 mcp 进行推送群里

 ## 基本原则
- 优先考虑代码的可读性和可维护性
- 遵循一致性原则，保持代码风格统一
- 规范等级：【必须】= MUST/REQUIRED，【推荐】= SHOULD，【可选】= MAY

 ## 1. 变量和引用【必须】
- 使用 `const` 声明不会重新赋值的变量，使用 `let` 声明需要重新赋值的变量
- 禁止使用 `var`，变量先声明再使用
- 每个变量单独声明，不使用逗号分隔

 ```javascript
// 好的示例
const name = 'example';
let count = 0;

 // 错误示例
var name = 'example';
const a = 1, b = 2;
let a = b = c = 1; // 链式赋值
```

 ## 2. 对象和数组【必须】
- 使用字面量语法创建对象和数组
- 使用对象方法简写和属性值简写
- 只对无效标识符的属性使用引号
- 优先使用展开运算符

 ```javascript
// 好的示例
const obj = { name, getValue() { return this.name; } };
const arr = [1, 2, 3];
const copy = { ...original, newProp: 'value' };

 // 错误示例
const obj = new Object();
const arr = new Array();
const bad = { 'foo': 3, 'bar': 4 };
```

 ## 3. 字符串【推荐】
- 使用单引号定义字符串
- 使用模板字符串进行字符串拼接
- 永远不要使用 eval()

 ```javascript
// 好的示例
const message = 'Hello world';
const greeting = `Hello, ${name}!`;
 // 错误示例
const message = "Hello world";
const greeting = 'Hello, ' + name + '!';
```

 ## 4. 函数【推荐】
- 使用默认参数语法，默认参数放在最后
- 使用 rest 语法代替 arguments
- 不要改变入参

 ```javascript
// 好的示例
function handleThings(name, opts = {}) { /* */ }
function sum(...args) { return args.reduce((a, b) => a + b, 0); }

 // 错误示例
function handleThings(opts = {}, name) { /* */ } // 默认参数不在最后
```

 ## 5. 箭头函数【推荐】
- 使用箭头函数处理匿名函数
- 单个参数时可省略圆括号，简单表达式可省略大括号

 ```javascript
// 好的示例
[1, 2, 3].map(x => x * 2);
[1, 2, 3].filter((x) => { return x > 1; });

 // 错误示例
[1, 2, 3].map(function(x) { return x * 2; });
```

 ## 6. 类【推荐】
- 使用 class 语法而非直接操作 prototype
- 使用 extends 实现继承
- 避免定义重复的类成员

 ```javascript
// 好的示例
class Queue {
  constructor(contents = []) {
    this.queue = [...contents];
  }
  pop() {
    return this.queue.shift();
  }
}

 class PeekableQueue extends Queue {
  peek() {
    return this.queue[0];
  }
}
```
 ## 7. 模块【必须】
- 使用 ES6 模块语法 import/export
- 不要使用 import * 通配符
- 所有 import 语句放在文件顶部
- 对同一路径只使用一个 import 语句

 ```javascript
// 好的示例
import { es6 } from './AirbnbStyleGuide';
import foo, { named1, named2 } from 'foo';
export default es6;

 // 错误示例
import * as AirbnbStyleGuide from './AirbnbStyleGuide';
const utils = require('./utils');
```

 ## 8. 解构【推荐】
- 访问多个对象属性时使用对象解构
- 多个返回值时使用对象解构而不是数组解构

 ```javascript
// 好的示例
const { firstName, lastName } = user;
const [first, second] = arr;

 function processInput(input) {
  return { left, right, top, bottom };
}
const { left, top } = processInput(input);
```

 ## 9. 比较和条件【推荐】
- 使用 === 和 !== 而不是 == 和 !=
- 布尔值使用简写，字符串和数字显式比较
- case 语句中使用大括号创建块级作用域
- 避免嵌套三元表达式

 ```javascript
// 好的示例
if (isValid) { /* */ }
if (name !== '') { /* */ }
if (collection.length > 0) { /* */ }

 switch (foo) {
  case 1: {
    let x = 1;
    break;
  }
}

 // 错误示例
if (isValid === true) { /* */ }
if (name) { /* */ }
const foo = a ? b : c ? d : e; // 嵌套三元
```
 ## 10. 代码块和控制语句【必须】
- 多行代码块使用大括号包裹
- else 语句放在 if 块闭括号同一行
- 控制语句过长时每个条件放入新行，逻辑运算符在行开始
 ```javascript
// 好的示例
if (test) {
  return false;
}

 if (test) {
  thing1();
} else {
  thing2();
}

 if (
  foo === 123
  && bar === 'abc'
) {
  thing1();
}

 // 错误示例
if (test)
  return false;

 if (test) {
  thing1();
}
else {
  thing2();
}
```

 ## 11. 空白和格式【必须】
- 使用 2 个空格缩进
- 花括号前放置空格，运算符左右各一个空格
- 控制语句左括号前放空格，函数调用和声明不放空格
- 逗号后面有空格，前面没有空格
- 文件结尾保留一个空行，行尾不留空格

 ```javascript
// 好的示例
function test() {
  const x = y + 5;
  const arr = [1, 2, 3];
  const obj = { clark: 'kent' };
}

 if (isJedi) {
  fight();
}

 // 错误示例
function test(){
  const x=y+5;
  const arr = [1,2,3];
  const obj = {clark:'kent'};
}
```

 ## 12. 命名规范【必须】
- 变量和函数使用驼峰命名法(camelCase)
- 类和构造函数使用帕斯卡命名法(PascalCase)
- 导出的常量可以使用全大写
- 避免使用前置或后置下划线

 ```javascript
// 好的示例
const userName = 'john';
class UserManager {}
export const API_KEY = 'secret';

 // 错误示例
const user_name = 'john';
const _privateVar = 'secret';
class user {}
```

 ## 13. 分号【必须】
- 所有语句必须以分号结尾，不依赖自动分号插入(ASI)

 ```javascript
// 好的示例
const name = 'example';
doSomething();

 // 错误示例
const name = 'example'
doSomething()
```
 ## 14. 类型转换【推荐】
- 使用 String() 进行字符串转换
- 使用 Number() 或 parseInt() 进行数字转换，parseInt 必须指定进制
- 使用 !! 进行布尔转换

 ```javascript
// 好的示例
const str = String(value);
const num = parseInt(inputValue, 10);
const bool = !!value;

 // 错误示例
const str = value + '';
const num = +inputValue;
const bool = new Boolean(value);
```
 ## 15. 注释【必须】
- 使用 // 进行单行注释，使用 /* */ 进行多行注释
- 注释前加一个空格
- 使用 FIXME 和 TODO 标记待办事项
- /** */ 风格仅用于 JSDoc
 ```javascript
// 好的示例
// 这是单行注释
/* 这是多行注释 */
// TODO: 需要实现这个功能
 /**
 * JSDoc 注释
 * @param {number} a 第一个数
 */
function add(a) { return a; }
```

 ## 16. 其他重要规则
- 优先使用数组高阶方法(map, filter, reduce等)代替传统循环
- 访问属性时使用点符号，变量访问属性时用中括号
- 链式调用超过两个方法时换行
- 建议使用尾随逗号
- 禁止定义了变量却不使用

 ```javascript
// 好的示例
const sum = numbers.reduce((total, num) => total + num, 0);
const isJedi = luke.jedi;
const prop = getProp('jedi');

 $('#items')
  .find('.selected')
  .highlight();

 const hero = {
  firstName: 'Dana',
  lastName: 'Scully',
};
```

 # TypeScript 编码规范
 ## 1. 类【可选】
- 必须设置类成员的可访问性修饰符
- 类成员排序：static > instance, field > constructor > method, public > protected > private
 ```typescript
class Foo {
  public static count = 0;
  private name: string;

  public constructor(name: string) {
    this.name = name;
  }

  public getName(): string {
    return this.name;
  }
}
```

 ## 2. 类型和接口【必须】
- 类型断言使用 as Type，禁止使用 <Type>
- 禁止给基本类型变量显式声明类型
- 优先使用 interface 而不是 type
- 接口中的方法使用属性方式定义
 ```typescript
// 好的示例
const foo = bar as string;
const num = 42; // 自动推断
interface User {
  name: string;
  getName: () => string;
}

 // 错误示例
const foo = <string>bar;
let num: number = 42;
interface User {
  getName(): string;
}
```

 ## 3. 语法和模块【必须】
- 使用 optional chaining 替代 && 链式判断
- 禁止在 optional chaining 后使用非空断言
- 禁止使用 namespace，使用 ES6 模块
- 禁止使用 require，统一使用 import

 ```typescript
// 好的示例
console.log(foo?.a?.b?.c);
import Animal from './Animal';

 // 错误示例
console.log(foo && foo.a && foo.a.b && foo.a.b.c);
console.log(foo?.bar!);
namespace foo {}
const fs = require('fs');
```

 ## 4. 命名规范【推荐】
- 变量和函数使用驼峰法命名
- 导出的常量使用全大写下划线分割
- React 组件使用 Pascal 写法
- 类名和类型定义使用首字母大写

 ```typescript
// 好的示例
const foo = 123;
export const API_KEY = 123;
const MyComponent = <div />;
interface User {}
class User {}

 // 错误示例
const FOO = 123;
export const foo = 123;
const myComponent = <div />;
interface user {}
```

 ## 5. Promise 处理【必须】
- 禁止对条件语句中 promise 的误用，需要用 await 获取返回值
 ```typescript
// 好的示例
async function foo() {
  if (await promise(1)) {
    // Do something
  }
}
 // 错误示例
async function foo() {
  if (promise(1)) { // 恒为真
    // Do something
  }
}
```

 ## 应用原则
1. 【必须】级别严格执行，违反会导致构建失败
2. 【推荐】级别尽量遵循，特殊情况可以豁免
3. 【可选】级别作为参考，提升代码质量
4. 保持代码风格的一致性是最重要的原则 
 

/security 执行审查

---
description: "? 智能代码安全审查 - 自动扫描项目代码，检查编码规范违规并提供修复建议，生成 html 审查报告"
argument-hint: "[target-path]"
---

 # 安全开发九大核心原则

 这些规则定义了编写安全代码的核心实践要求，**适用于所有开发场景**（包括人工编码、自动化工具及AI生成代码）。所有违规提示必须清晰说明触发的具体规则及原因，以便开发者高效修复问题。

 ## 1. 禁止在敏感操作中使用原始用户输入

 **规则：** 不可直接将不可信输入用于文件访问、命令执行、数据库查询或其他敏感操作。

 ```java
// 危险：直接拼接SQL查询
String query = "SELECT * FROM users WHERE name = '" + userInput + "'";

 // 安全：使用参数化查询
PreparedStatement stmt = conn.prepareStatement("SELECT * FROM users WHERE name = ?");
stmt.setString(1, sanitizedInput);
```

 ## 2. 禁止在公开代码中暴露密钥
 **规则：** API密钥、凭证、私钥或令牌等敏感信息不得出现在前端代码、公共代码库或客户端分发文件中。

 ```javascript
// 不安全：硬编码密钥
const API_KEY = 'sk_live_9876543210';

 // 安全：从环境变量读取
const API_KEY = process.env.SECRET_API_KEY;
```

 ## 3. 强制使用安全通信协议
 **规则：** 所有外部通信必须使用安全协议（如HTTPS、TLS）。

 ```python
# 不安全的请求
import requests
response = requests.get('http://api.example.com/data')

 # 强制使用HTTPS
response = requests.get('https://api.example.com/data', verify=True)
```
 ## 4. 避免执行动态生成代码
 **规则：** 禁止在运行时执行动态构建的代码或表达式。

 ```javascript
// 高风险：使用eval执行用户输入
eval("alert('Hello, ' + userName + '!')");

 // 安全替代方案
function showGreeting(name) {
    alert(`Hello, ${name}!`);
}
showGreeting(sanitizedUserName);
```

 ## 5. 验证所有外部输入

 **规则：** 来自用户、外部API或第三方系统的输入，使用前必须进行有效性验证。
 ```javascript
// 验证电子邮件格式示例
const isValidEmail = (email) => {
  const regex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
  return regex.test(email);
};

 // 使用前验证
if (!isValidEmail(inputEmail)) {
    throw new Error('邮箱格式无效');
}
```

 ## 6. 禁止在日志中记录敏感信息

 **规则：** 日志不得包含凭证、令牌、个人身份信息等敏感数据。

 ```java
// 不安全的日志记录
logger.info("用户登录成功，token: " + authToken);
 // 安全做法：脱敏处理
logger.info("用户登录成功，ID: {}", 
    user.getId().substring(0, 3) + "***");
```

 ## 7. 禁止无授权绕过安全控制

 **规则：** 未经文档化说明和评审通过，不得禁用、绕过或压制安全检查机制。

 ```python
# 禁止在代码中关闭SSL验证
# requests.get(url, verify=False)  # 高危操作!
 # 正确做法：仅在有有效证书的环境使用
response = requests.get(url, verify='/path/to/certificate.pem')
```

 ## 8. 限制对客户端逻辑的信任
 **规则：** 权限控制、认证或验证等核心逻辑不得仅依赖客户端代码实现。
 ```javascript
// 客户端不可信验证（易被绕过）
function processOrder(userRole) {
    if (userRole === 'admin') {
        // 执行特权操作
    }
}

 // 服务器端验证（安全）
app.post('/admin/action', (req, res) => {
    if (req.user.role !== 'admin') {
        return res.status(403).send();
    }
    // 执行操作...
});
```

 ## 9. 检测并消除硬编码凭证

 **规则：** 凭证不得以硬编码形式存在于源码、配置文件或脚本中。
 ```javascript
// 高危：配置文件中的硬编码密码
// config.json
{
    "dbPassword": "MySecretPassword123!"
}

 // 安全方案：使用密钥管理系统
const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');
const client = new SecretManagerServiceClient();
const [version] = await client.accessSecretVersion({
    name: `projects/${projectId}/secrets/${secretId}`
});
const dbPassword = version.payload.data.toString();
```
 ## 关键术语对照表

 | 英文术语 | 中文译法 | 应用场景示例 |
|---------|---------|-------------|
| **Raw User Input** | 原始用户输入 | SQL查询、系统命令调用 |
| **Secrets** | 密钥/凭证 | API密钥、数据库密码 |
| **Dynamic Code** | 动态生成代码 | 通过字符串拼接生成的代码 |
| **Security Controls** | 安全控制 | 加密检查、访问控制 |
| **Hardcoded Credentials** | 硬编码凭证 | 源代码中的明文密码 |

---
 
 *安全开发规范文档 | 基于OWASP ASVS标准制定 | 更新日期：2025年07月29日*

/security 进行审查