update

.agents/skills/writing-plan/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: writing-plan
+description: 实施计划创建技能，用于多步骤任务。在有规范或需求时，在直接接触代码前使用本技能。创建详细、可执行的实施计划。当用户提及"创建计划"、"实施计划"、"编写计划"、"规划"、"任务分解"或开始复杂的多步骤开发工作且有现有规范时触发本技能。
+license: MIT
+metadata:
+  version: "3.0.1"
+---
+
+# 编写计划技能
+
+本技能用于创建多步骤开发任务的全面实施计划。在有规范或需求时，在直接接触任何代码之前使用。
+
+---
+
+## 核心原则
+
+### 计划优先
+
+在计划完成前，请勿：
+
+- 调用任何实施技能
+- 编写任何代码
+- 创建或修改项目文件（计划文档除外）
+- 采取任何实施行动
+
+### 会话状态管理
+
+使用统一的会话状态文件跟踪进度：
+
+- **路径**：`design/session-state.md`
+- **模板**：`references/session-state-template.md`（共享）
+
+**操作时机**：
+
+- 技能激活时 → **创建/更新状态文件**
+- 完成阶段性成果后 → **更新状态文件**
+- 每轮对话开始时 → 读取状态文件恢复上下文
+- **每个阶段完成后 → 更新状态文件**
+
+### 终止条件
+
+本技能的唯一终止方式是完成计划文档并通知用户准备执行。
+
+---
+
+## 工作流程
+
+### 阶段 1：上下文与范围分析
+
+**目标**：理解规格文档，识别子系统。
+
+**执行动作**：
+
+1. 接收 brainstorming 传递的规格文档路径
+2. 读取规格文档，理解需求
+3. 评估是否涉及多个独立子系统
+
+**子系统识别标准**：
+
+| 特征         | 说明                     |
+| ------------ | ------------------------ |
+| 独立数据模型 | 子系统有独立的数据结构   |
+| 独立接口     | 子系统对外提供独立 API   |
+| 独立部署     | 子系统可独立部署运行     |
+| 清晰边界     | 子系统间通过明确接口通信 |
+
+**处理策略**：
+
+- 单一子系统 → 直接进入阶段 2
+- 多个子系统 → 先创建纲领文件，再逐个子系统编写计划
+
+**完成标准**：已理解需求，已识别子系统划分
+
+---
+
+### 阶段 2：文件结构规划
+
+**目标**：规划将创建或修改的文件及其职责。
+
+**设计原则**：
+
+- 单一职责：每个文件应有单一明确职责
+- 上下文友好：能在一个上下文窗口中理解的代码
+- 聚焦文件：优先选择小而专注的文件
+
+**输出格式**：
+
+```markdown
+## 文件结构
+
+### 新建文件
+
+- `path/to/new/file.ts` - 职责描述
+
+### 修改文件
+
+- `path/to/existing/file.ts` - 修改内容描述
+
+### 测试文件
+
+- `tests/path/to/test.ts` - 测试职责
+```
+
+**代码注释规划**：
+
+**在文件结构规划中明确注释需求**：
+
+对于每个新建或修改的文件，标注注释需求：
+
+```markdown
+### 新建文件
+
+- `src/utils/helper.ts` - 职责描述
+  - 注释需求：需要为所有公共函数添加文档注释
+  - 复杂度：中等（包含复杂算法，需要详细注释）
+```
+
+**注释需求评估标准**：
+
+- **高优先级**：公共 API、核心业务逻辑、复杂算法
+- **中优先级**：工具函数、数据处理逻辑
+- **低优先级**：简单工具函数、配置文件
+
+**完成标准**：文件结构已规划，测试文件已明确，注释需求已评估，用户已确认
+
+---
+
+### 阶段 3：任务定义
+
+**目标**：定义具体的实施任务。
+
+**任务粒度**：每个步骤应对应一个操作（耗时 2-5 分钟）。
+
+**任务结构**：
+
+```markdown
+### 任务 N：[任务名称]
+
+**文件**：
+
+- 创建：`path/to/file.ts`
+- 测试：`tests/path/to/test.ts`
+
+- [ ] **步骤 1**：编写失败测试
+- [ ] **步骤 2**：运行测试验证失败
+- [ ] **步骤 3**：编写最小实现
+- [ ] **步骤 4**：运行测试验证通过
+```
+
+**任务要求**：
+
+- 精确文件路径，无模糊引用
+- 计划中包含完整代码，非占位符
+- 精确命令及预期输出
+- **测试优先方法（TDD）**：每个任务必须先定义测试文件和测试用例
+
+**测试要求**：
+
+⚠️ **任务必须包含测试步骤**，禁止以下情况：
+
+- ❌ 只写实现代码，不写测试
+- ❌ 测试文件路径为空或使用占位符
+- ❌ 测试用例不完整或过于简单
+- ❌ 跳过"编写失败测试"步骤
+
+**测试覆盖标准**：
+
+- 每个函数/方法至少有一个正向测试用例
+- 边界条件必须有对应测试
+- 错误处理路径必须有测试覆盖
+- 测试文件必须在任务开始前创建
+
+**完成标准**：所有任务已定义，每个任务都包含完整的测试计划，用户已确认
+
+---
+
+### 阶段 4：计划保存与确认
+
+**目标**：保存计划文档，获得用户批准。
+
+**执行动作**：
+
+1. 保存计划到 `design/plans/YYYY-MM-DD-<feature>.md`
+2. 请用户确认计划内容
+3. 若用户批准，询问是否开始执行
+
+**标准话术**：
+
+> "计划已完成并保存。请确认以下内容：
+>
+> **计划文档**：`design/plans/<filename>.md`
+> **任务总数**：[数量]
+>
+> 确认后是否开始执行？"
+
+---
+
+### 阶段 5：执行交接
+
+**目标**：调用 executing-plans 技能。
+
+**调用格式**：
+
+```
+调用 executing-plans 技能，计划文档路径：<path>
+```
+
+**终止**：此阶段完成后，本技能结束。
+
+---
+
+## 多子系统处理
+
+当识别到多个子系统时：
+
+### 1. 创建纲领文件
+
+**路径**：`design/plans/YYYY-MM-DD-<topic>-outline.md`
+
+**内容**：
+
+```markdown
+# [项目名称] 实施计划纲领
+
+## 子系统划分
+
+| 子系统  | 范围   | 依赖 | 状态   |
+| ------- | ------ | ---- | ------ |
+| 子系统A | [范围] | 无   | 待编写 |
+| 子系统B | [范围] | A    | 待编写 |
+
+## 执行顺序
+
+1. 子系统A（无依赖）
+2. 子系统B（依赖A）
+
+## 共享组件
+
+| 组件     | 使用子系统 | 定义位置      |
+| -------- | ---------- | ------------- |
+| [组件名] | A, B       | 子系统A计划中 |
+```
+
+### 2. 逐个子系统编写计划
+
+每个子系统独立编写计划文档，完成后更新纲领文件状态。
+
+---
+
+## 参考指南
+
+| 参考文档                      | 用途         |
+| ----------------------------- | ------------ |
+| `references/plan-template.md` | 计划模板     |
+| `references/patterns.md`      | 常见计划模式 |
+
+---
+
+## 常见问题
+
+### 计划需要修改？
+
+处理方式：
+
+1. 在纲领文件中记录变更
+2. 更新受影响的计划文档
+3. 通知用户变更影响范围
+
+### 对话中断后如何恢复？
+
+处理方式：
+
+1. 读取会话状态文件 `design/session-state.md`
+2. 根据"下一步"继续执行

.agents/skills/writing-plan/references/patterns.md

@@ -0,0 +1,114 @@
+# 常见计划模式库
+
+预定义的任务模板，可快速复用于常见场景。
+
+---
+
+## 使用方式
+
+当识别到以下常见模式时，可直接引用对应模板。
+
+---
+
+## 模式 1：CRUD 模块
+
+**适用场景**：数据增删改查操作
+
+**典型文件结构**：
+
+| 文件 | 职责 |
+|------|------|
+| `src/models/<entity>.ts` | 数据模型定义 |
+| `src/repositories/<entity>Repository.ts` | 数据访问层 |
+| `src/services/<entity>Service.ts` | 业务逻辑层 |
+| `src/controllers/<entity>Controller.ts` | API 控制器 |
+| `tests/<entity>.test.ts` | 测试文件 |
+
+**典型任务顺序**：
+1. 定义数据模型
+2. 实现 Repository（CRUD 操作）
+3. 实现 Service（业务逻辑）
+4. 实现 Controller（API 端点）
+5. 集成测试
+
+---
+
+## 模式 2：认证模块
+
+**适用场景**：用户认证授权
+
+**典型文件结构**：
+
+| 文件 | 职责 |
+|------|------|
+| `src/auth/jwtHandler.ts` | JWT 令牌处理 |
+| `src/auth/middleware.ts` | 认证中间件 |
+| `src/auth/refreshHandler.ts` | 令牌刷新 |
+| `src/services/userService.ts` | 用户服务 |
+| `tests/auth.test.ts` | 认证测试 |
+
+**典型任务顺序**：
+1. 实现 JWT 生成和验证
+2. 实现认证中间件
+3. 实现登录/登出逻辑
+4. 实现令牌刷新机制
+5. 权限验证
+
+---
+
+## 模式 3：API 集成
+
+**适用场景**：第三方服务集成
+
+**典型文件结构**：
+
+| 文件 | 职责 |
+|------|------|
+| `src/clients/<service>Client.ts` | API 客户端 |
+| `src/adapters/<service>Adapter.ts` | 数据适配器 |
+| `src/services/<service>Service.ts` | 业务封装 |
+| `src/mocks/<service>Mock.ts` | 模拟实现 |
+| `tests/<service>.test.ts` | 集成测试 |
+
+**典型任务顺序**：
+1. 定义 API 客户端接口
+2. 实现请求/响应处理
+3. 实现数据适配层
+4. 实现错误处理和重试
+5. 创建模拟实现用于测试
+
+---
+
+## 模式 4：中间件/插件
+
+**适用场景**：请求处理管道、插件系统
+
+**典型文件结构**：
+
+| 文件 | 职责 |
+|------|------|
+| `src/middleware/<name>.ts` | 中间件实现 |
+| `src/types/middleware.ts` | 类型定义 |
+| `tests/middleware/<name>.test.ts` | 测试文件 |
+
+**典型任务顺序**：
+1. 定义中间件接口
+2. 实现核心逻辑
+3. 实现配置选项
+4. 错误处理
+5. 集成测试
+
+---
+
+## 模式引用方式
+
+在计划中引用模式：
+
+```markdown
+### 任务组：用户管理 CRUD
+
+> 引用模式：CRUD 模块
+> 实体：User
+
+[基于模式模板编写具体任务...]
+```

.agents/skills/writing-plan/references/plan-template.md

@@ -0,0 +1,107 @@
+# 实施计划模板
+
+本文档提供实施计划的标准结构。
+
+---
+
+## 文档路径
+
+```
+design/plans/YYYY-MM-DD-<feature>.md
+```
+
+---
+
+## 单一子系统计划模板
+
+```markdown
+# [功能名称] 实施计划
+
+**目标**：[一句话描述此功能构建什么]
+
+**架构**：[2-3 句关于方法]
+
+**技术栈**：[关键技术/库]
+
+---
+
+## 文件结构
+
+### 新建文件
+- `path/to/new/file.ts` - 职责描述
+
+### 修改文件
+- `path/to/existing/file.ts` - 修改内容描述
+
+### 测试文件
+- `tests/path/to/test.ts` - 测试职责
+
+---
+
+## 任务列表
+
+### 任务 1：[任务名称]
+
+**文件**：
+- 创建：`path/to/file.ts`
+- 测试：`tests/path/to/test.ts`
+
+- [ ] **步骤 1**：编写失败测试
+- [ ] **步骤 2**：运行测试验证失败
+- [ ] **步骤 3**：编写最小实现
+- [ ] **步骤 4**：运行测试验证通过
+
+### 任务 2：[任务名称]
+
+[继续按相同模式...]
+```
+
+---
+
+## 多子系统纲领文件模板
+
+```markdown
+# [项目名称] 实施计划纲领
+
+## 子系统划分
+
+| 子系统 | 范围 | 依赖 | 状态 |
+|--------|------|------|------|
+| 子系统A | [范围] | 无 | 待编写 |
+| 子系统B | [范围] | A | 待编写 |
+
+## 执行顺序
+
+1. 子系统A（无依赖）
+2. 子系统B（依赖A）
+
+## 共享组件
+
+| 组件 | 使用子系统 | 定义位置 |
+|------|------------|----------|
+| [组件名] | A, B | 子系统A计划中 |
+```
+
+---
+
+## 分块指南
+
+| 指标 | 标准 | 原因 |
+|------|------|------|
+| 行数 | 300-500 行 | 适配上下文窗口 |
+| 任务数 | 5-10 个 | 保持逻辑完整性 |
+
+**分块边界**：
+- 按功能模块分块
+- 按实施阶段分块（基础设施、核心功能、集成测试）
+- 按子系统分块
+
+---
+
+## 任务要求
+
+- 精确文件路径，无模糊引用
+- 计划中包含完整代码，非占位符
+- 精确命令及预期输出
+- 测试优先方法（TDD）
+- 每个步骤 2-5 分钟可完成