specops 0.2.5 → 0.3.2

package/.opencode/templates/requirements.md

@@ -0,0 +1,130 @@
+# 需求模板
+
+`.planning/REQUIREMENTS.md` 的模板，可检查的需求定义 "完成" 的标准。
+
+<template>
+
+```markdown
+# 需求: [项目名称]
+
+**定义时间:** [日期]
+**核心价值:** [来自 PROJECT.md]
+
+## v1 需求
+
+初始发布的需求。每个需求映射到路线图阶段。
+
+### 认证
+
+- [ ] **AUTH-01**: 用户可以用邮箱和密码注册
+- [ ] **AUTH-02**: 用户注册后收到邮箱验证
+- [ ] **AUTH-03**: 用户可以通过邮件链接重置密码
+- [ ] **AUTH-04**: 用户会话在浏览器刷新后保持
+
+### [类别 2]
+
+- [ ] **[CAT]-01**: [需求描述]
+- [ ] **[CAT]-02**: [需求描述]
+- [ ] **[CAT]-03**: [需求描述]
+
+### [类别 3]
+
+- [ ] **[CAT]-01**: [需求描述]
+- [ ] **[CAT]-02**: [需求描述]
+
+## v2 需求
+
+延后到未来版本。已追踪但不在当前路线图中。
+
+### [类别]
+
+- **[CAT]-01**: [需求描述]
+- **[CAT]-02**: [需求描述]
+
+## 超出范围
+
+明确排除。记录以防止范围蔓延。
+
+| 功能 | 原因 |
+|------|------|
+| [功能] | [排除原因] |
+| [功能] | [排除原因] |
+
+## 可追溯性
+
+哪些阶段覆盖哪些需求。路线图创建时更新。
+
+| 需求 | 阶段 | 状态 |
+|------|------|------|
+| AUTH-01 | 阶段 1 | 待定 |
+| AUTH-02 | 阶段 1 | 待定 |
+| AUTH-03 | 阶段 1 | 待定 |
+| AUTH-04 | 阶段 1 | 待定 |
+| [REQ-ID] | 阶段 [N] | 待定 |
+
+**覆盖率:**
+- v1 需求: [X] 个总计
+- 已映射到阶段: [Y]
+- 未映射: [Z] ⚠️
+
+---
+*需求定义时间: [日期]*
+*最后更新: [日期] 在 [触发事件] 之后*
+```
+
+</template>
+
+<guidelines>
+
+**需求格式:**
+- ID: `[类别]-[编号]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- 描述: 以用户为中心、可测试、原子化
+- 复选框: 仅用于 v1 需求 (v2 尚不可操作)
+
+**类别:**
+- 从研究 FEATURES.md 的类别推导
+- 保持与领域约定一致
+- 典型: 认证, 内容, 社交, 通知, 审核, 支付, 管理
+
+**v1 vs v2:**
+- v1: 承诺的范围，将在路线图阶段中
+- v2: 已确认但延后，不在当前路线图中
+- 将 v2 → v1 需要更新路线图
+
+**超出范围:**
+- 明确排除并附理由
+- 防止以后 "为什么没包含 X？"
+- 研究中的反功能属于这里并附警告
+
+**可追溯性:**
+- 初始为空，路线图创建时填充
+- 每个需求映射到恰好一个阶段
+- 未映射的需求 = 路线图缺口
+
+**状态值:**
+- 待定: 未开始
+- 进行中: 阶段活跃
+- 已完成: 需求已验证
+- 被阻塞: 等待外部因素
+
+</guidelines>
+
+<evolution>
+
+**每个阶段完成后:**
+1. 将覆盖的需求标记为已完成
+2. 更新可追溯性状态
+3. 记录任何范围变更的需求
+
+**路线图更新后:**
+1. 验证所有 v1 需求仍有映射
+2. 如果范围扩大则添加新需求
+3. 如果缩减范围则将需求移到 v2/超出范围
+
+**需求完成标准:**
+- 需求 "已完成" 当:
+  - 功能已实现
+  - 功能已验证 (测试通过，手动检查完成)
+  - 功能已提交
+
+</evolution>

package/.opencode/templates/research-project/ARCHITECTURE.md

@@ -0,0 +1,204 @@
+# 架构研究模板
+
+`.planning/research/ARCHITECTURE.md` 的模板，项目领域的系统结构模式。
+
+<template>
+
+```markdown
+# 架构研究
+
+**领域:** [领域类型]
+**研究时间:** [日期]
+**置信度:** [高/中/低]
+
+## 标准架构
+
+### 系统概览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        [层名称]                               │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ [组件]  │  │ [组件]  │  │ [组件]  │  │ [组件]  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+├───────┴────────────┴────────────┴────────────┴──────────────┤
+│                        [层名称]                               │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    [组件]                             │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│                        [层名称]                               │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │ [存储]   │  │ [存储]   │  │ [存储]   │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 组件职责
+
+| 组件 | 职责 | 典型实现 |
+|------|------|---------|
+| [名称] | [负责什么] | [通常如何构建] |
+| [名称] | [负责什么] | [通常如何构建] |
+| [名称] | [负责什么] | [通常如何构建] |
+
+## 推荐项目结构
+
+```
+src/
+├── [文件夹]/           # [用途]
+│   ├── [子文件夹]/    # [用途]
+│   └── [文件].ts       # [用途]
+├── [文件夹]/           # [用途]
+│   ├── [子文件夹]/    # [用途]
+│   └── [文件].ts       # [用途]
+├── [文件夹]/           # [用途]
+└── [文件夹]/           # [用途]
+```
+
+### 结构理由
+
+- **[文件夹]/:** [为什么这样组织]
+- **[文件夹]/:** [为什么这样组织]
+
+## 架构模式
+
+### 模式 1: [模式名称]
+
+**是什么:** [描述]
+**何时使用:** [条件]
+**权衡:** [优缺点]
+
+**示例:**
+```typescript
+// [展示模式的简要代码示例]
+```
+
+### 模式 2: [模式名称]
+
+**是什么:** [描述]
+**何时使用:** [条件]
+**权衡:** [优缺点]
+
+**示例:**
+```typescript
+// [展示模式的简要代码示例]
+```
+
+### 模式 3: [模式名称]
+
+**是什么:** [描述]
+**何时使用:** [条件]
+**权衡:** [优缺点]
+
+## 数据流
+
+### 请求流
+
+```
+[用户操作]
+    ↓
+[组件] → [处理器] → [服务] → [数据存储]
+    ↓              ↓           ↓            ↓
+[响应] ← [转换] ← [查询] ← [数据库]
+```
+
+### 状态管理
+
+```
+[状态存储]
+    ↓ (订阅)
+[组件] ←→ [操作] → [Reducers/Mutations] → [状态存储]
+```
+
+### 关键数据流
+
+1. **[流名称]:** [数据如何流动的描述]
+2. **[流名称]:** [数据如何流动的描述]
+
+## 扩展考虑
+
+| 规模 | 架构调整 |
+|------|---------|
+| 0-1k 用户 | [方案 — 通常单体就够了] |
+| 1k-100k 用户 | [方案 — 先优化什么] |
+| 100k+ 用户 | [方案 — 何时考虑拆分] |
+
+### 扩展优先级
+
+1. **第一个瓶颈:** [什么先崩溃，如何修复]
+2. **第二个瓶颈:** [接下来什么崩溃，如何修复]
+
+## 反模式
+
+### 反模式 1: [名称]
+
+**人们怎么做:** [错误做法]
+**为什么错:** [造成什么问题]
+**应该这样做:** [正确方法]
+
+### 反模式 2: [名称]
+
+**人们怎么做:** [错误做法]
+**为什么错:** [造成什么问题]
+**应该这样做:** [正确方法]
+
+## 集成点
+
+### 外部服务
+
+| 服务 | 集成模式 | 备注 |
+|------|---------|------|
+| [服务] | [如何连接] | [注意事项] |
+| [服务] | [如何连接] | [注意事项] |
+
+### 内部边界
+
+| 边界 | 通信方式 | 备注 |
+|------|---------|------|
+| [模块 A ↔ 模块 B] | [API/事件/直接] | [考虑事项] |
+
+## 来源
+
+- [架构参考]
+- [官方文档]
+- [案例研究]
+
+---
+*架构研究领域: [领域]*
+*研究时间: [日期]*
+```
+
+</template>
+
+<guidelines>
+
+**系统概览:**
+- 使用 ASCII 框线图提高清晰度 (├── └── │ ─ 仅用于结构可视化)
+- 展示主要组件及其关系
+- 不要过度细化 — 这是概念性的，不是实现
+
+**项目结构:**
+- 具体说明文件夹组织
+- 解释分组的理由
+- 匹配所选技术栈的约定
+
+**模式:**
+- 在有帮助的地方包含代码示例
+- 诚实说明权衡
+- 注明何时模式对小项目来说过度
+
+**扩展考虑:**
+- 要现实 — 大多数项目不需要扩展到百万级
+- 聚焦 "什么先崩溃" 而非理论极限
+- 避免过早优化建议
+
+**反模式:**
+- 针对此领域的特定问题
+- 包含应该怎么做
+- 帮助在实现期间防止常见错误
+
+</guidelines>

package/.opencode/templates/research-project/FEATURES.md

@@ -0,0 +1,147 @@
+# 功能研究模板
+
+`.planning/research/FEATURES.md` 的模板，项目领域的功能全景。
+
+<template>
+
+```markdown
+# 功能研究
+
+**领域:** [领域类型]
+**研究时间:** [日期]
+**置信度:** [高/中/低]
+
+## 功能全景
+
+### 基本功能 (用户期望这些)
+
+用户默认认为存在的功能。缺少这些 = 产品感觉不完整。
+
+| 功能 | 为何被期望 | 复杂度 | 备注 |
+|------|-----------|--------|------|
+| [功能] | [用户期望] | 低/中/高 | [实现备注] |
+| [功能] | [用户期望] | 低/中/高 | [实现备注] |
+| [功能] | [用户期望] | 低/中/高 | [实现备注] |
+
+### 差异化功能 (竞争优势)
+
+让产品脱颖而出的功能。非必需，但有价值。
+
+| 功能 | 价值主张 | 复杂度 | 备注 |
+|------|---------|--------|------|
+| [功能] | [为什么重要] | 低/中/高 | [实现备注] |
+| [功能] | [为什么重要] | 低/中/高 | [实现备注] |
+| [功能] | [为什么重要] | 低/中/高 | [实现备注] |
+
+### 反功能 (常被要求，但往往有问题)
+
+看起来好但会制造问题的功能。
+
+| 功能 | 为何被要求 | 为何有问题 | 替代方案 |
+|------|-----------|-----------|---------|
+| [功能] | [表面吸引力] | [实际问题] | [更好的方法] |
+| [功能] | [表面吸引力] | [实际问题] | [更好的方法] |
+
+## 功能依赖
+
+```
+[功能 A]
+    └──需要──> [功能 B]
+                   └──需要──> [功能 C]
+
+[功能 D] ──增强──> [功能 A]
+
+[功能 E] ──冲突──> [功能 F]
+```
+
+### 依赖说明
+
+- **[功能 A] 需要 [功能 B]:** [为什么存在依赖]
+- **[功能 D] 增强 [功能 A]:** [它们如何协同]
+- **[功能 E] 与 [功能 F] 冲突:** [为什么不兼容]
+
+## MVP 定义
+
+### 发布时包含 (v1)
+
+最小可行产品 — 验证概念所需的最少功能。
+
+- [ ] [功能] — [为什么必要]
+- [ ] [功能] — [为什么必要]
+- [ ] [功能] — [为什么必要]
+
+### 验证后添加 (v1.x)
+
+核心功能运行后添加的功能。
+
+- [ ] [功能] — [添加的触发条件]
+- [ ] [功能] — [添加的触发条件]
+
+### 未来考虑 (v2+)
+
+延后到产品市场契合确立后的功能。
+
+- [ ] [功能] — [为什么延后]
+- [ ] [功能] — [为什么延后]
+
+## 功能优先级矩阵
+
+| 功能 | 用户价值 | 实现成本 | 优先级 |
+|------|---------|---------|--------|
+| [功能] | 高/中/低 | 高/中/低 | P1/P2/P3 |
+| [功能] | 高/中/低 | 高/中/低 | P1/P2/P3 |
+| [功能] | 高/中/低 | 高/中/低 | P1/P2/P3 |
+
+**优先级说明:**
+- P1: 发布必须有
+- P2: 应该有，尽快添加
+- P3: 锦上添花，未来考虑
+
+## 竞品功能分析
+
+| 功能 | 竞品 A | 竞品 B | 我们的方案 |
+|------|--------|--------|-----------|
+| [功能] | [他们怎么做] | [他们怎么做] | [我们的计划] |
+| [功能] | [他们怎么做] | [他们怎么做] | [我们的计划] |
+
+## 来源
+
+- [分析的竞品]
+- [用户研究或反馈来源]
+- [参考的行业标准]
+
+---
+*功能研究领域: [领域]*
+*研究时间: [日期]*
+```
+
+</template>
+
+<guidelines>
+
+**基本功能:**
+- 发布时不可或缺
+- 用户不会因为有它们而给好评，但会因为没有而差评
+- 示例: 社区平台没有用户资料就是残缺的
+
+**差异化功能:**
+- 竞争的地方
+- 应与 PROJECT.md 的核心价值对齐
+- 不要试图在所有方面都差异化
+
+**反功能:**
+- 通过记录看似好但实际不好的功能来防止范围蔓延
+- 包含替代方案
+- 示例: "实时一切" 往往制造复杂性而无价值
+
+**功能依赖:**
+- 对路线图阶段排序至关重要
+- 如果 A 需要 B，B 必须在更早的阶段
+- 冲突告知什么不要放在同一阶段
+
+**MVP 定义:**
+- 对什么是真正最小的要狠心
+- "锦上添花" 不是 MVP
+- 少发布，验证，然后扩展
+
+</guidelines>

package/.opencode/templates/research-project/PITFALLS.md

@@ -0,0 +1,200 @@
+# 陷阱研究模板
+
+`.planning/research/PITFALLS.md` 的模板，项目领域中应避免的常见错误。
+
+<template>
+
+```markdown
+# 陷阱研究
+
+**领域:** [领域类型]
+**研究时间:** [日期]
+**置信度:** [高/中/低]
+
+## 关键陷阱
+
+### 陷阱 1: [名称]
+
+**会出什么问题:**
+[失败模式描述]
+
+**为什么会发生:**
+[根本原因 — 开发者为什么犯这个错误]
+
+**如何避免:**
+[具体预防策略]
+
+**预警信号:**
+[如何在问题变大之前早期发现]
+
+**应在哪个阶段解决:**
+[路线图中哪个阶段应该预防这个]
+
+---
+
+### 陷阱 2: [名称]
+
+**会出什么问题:**
+[失败模式描述]
+
+**为什么会发生:**
+[根本原因 — 开发者为什么犯这个错误]
+
+**如何避免:**
+[具体预防策略]
+
+**预警信号:**
+[如何在问题变大之前早期发现]
+
+**应在哪个阶段解决:**
+[路线图中哪个阶段应该预防这个]
+
+---
+
+### 陷阱 3: [名称]
+
+**会出什么问题:**
+[失败模式描述]
+
+**为什么会发生:**
+[根本原因 — 开发者为什么犯这个错误]
+
+**如何避免:**
+[具体预防策略]
+
+**预警信号:**
+[如何在问题变大之前早期发现]
+
+**应在哪个阶段解决:**
+[路线图中哪个阶段应该预防这个]
+
+---
+
+[继续所有关键陷阱...]
+
+## 技术债务模式
+
+看起来合理但会造成长期问题的捷径。
+
+| 捷径 | 即时收益 | 长期成本 | 何时可接受 |
+|------|---------|---------|-----------|
+| [捷径] | [收益] | [成本] | [条件，或 "永远不行"] |
+| [捷径] | [收益] | [成本] | [条件，或 "永远不行"] |
+| [捷径] | [收益] | [成本] | [条件，或 "永远不行"] |
+
+## 集成陷阱
+
+连接外部服务时的常见错误。
+
+| 集成 | 常见错误 | 正确方法 |
+|------|---------|---------|
+| [服务] | [人们做错什么] | [应该怎么做] |
+| [服务] | [人们做错什么] | [应该怎么做] |
+| [服务] | [人们做错什么] | [应该怎么做] |
+
+## 性能陷阱
+
+小规模可用但随使用增长而失败的模式。
+
+| 陷阱 | 症状 | 预防 | 何时崩溃 |
+|------|------|------|---------|
+| [陷阱] | [如何发现] | [如何避免] | [规模阈值] |
+| [陷阱] | [如何发现] | [如何避免] | [规模阈值] |
+| [陷阱] | [如何发现] | [如何避免] | [规模阈值] |
+
+## 安全错误
+
+超出通用 Web 安全的领域特定安全问题。
+
+| 错误 | 风险 | 预防 |
+|------|------|------|
+| [错误] | [可能发生什么] | [如何避免] |
+| [错误] | [可能发生什么] | [如何避免] |
+| [错误] | [可能发生什么] | [如何避免] |
+
+## UX 陷阱
+
+该领域常见的用户体验错误。
+
+| 陷阱 | 用户影响 | 更好的方法 |
+|------|---------|-----------|
+| [陷阱] | [用户如何受影响] | [应该怎么做] |
+| [陷阱] | [用户如何受影响] | [应该怎么做] |
+| [陷阱] | [用户如何受影响] | [应该怎么做] |
+
+## "看起来完成但其实没有" 检查清单
+
+看起来完成但缺少关键部分的事项。
+
+- [ ] **[功能]:** 常缺少 [东西] — 验证 [检查]
+- [ ] **[功能]:** 常缺少 [东西] — 验证 [检查]
+- [ ] **[功能]:** 常缺少 [东西] — 验证 [检查]
+- [ ] **[功能]:** 常缺少 [东西] — 验证 [检查]
+
+## 恢复策略
+
+尽管预防了但陷阱仍然发生时，如何恢复。
+
+| 陷阱 | 恢复成本 | 恢复步骤 |
+|------|---------|---------|
+| [陷阱] | 低/中/高 | [怎么做] |
+| [陷阱] | 低/中/高 | [怎么做] |
+| [陷阱] | 低/中/高 | [怎么做] |
+
+## 陷阱到阶段映射
+
+路线图阶段应如何解决这些陷阱。
+
+| 陷阱 | 预防阶段 | 验证 |
+|------|---------|------|
+| [陷阱] | 阶段 [X] | [如何验证预防有效] |
+| [陷阱] | 阶段 [X] | [如何验证预防有效] |
+| [陷阱] | 阶段 [X] | [如何验证预防有效] |
+
+## 来源
+
+- [参考的事后分析]
+- [社区讨论]
+- [官方 "注意事项" 文档]
+- [个人经验 / 已知问题]
+
+---
+*陷阱研究领域: [领域]*
+*研究时间: [日期]*
+```
+
+</template>
+
+<guidelines>
+
+**关键陷阱:**
+- 聚焦领域特定问题，不是通用错误
+- 包含预警信号 — 早期发现防止灾难
+- 链接到具体阶段 — 使陷阱可操作
+
+**技术债务:**
+- 要现实 — 有些捷径是可接受的
+- 注明何时捷径 "永远不可接受" vs "仅在 MVP 中可以"
+- 包含长期成本以指导权衡决策
+
+**性能陷阱:**
+- 包含规模阈值 ("在 1 万用户时崩溃")
+- 聚焦与项目预期规模相关的内容
+- 不要为假设的规模过度工程化
+
+**安全错误:**
+- 超出 OWASP 基础 — 领域特定问题
+- 示例: 社区平台与电商有不同的安全关注点
+- 包含风险级别以确定优先级
+
+**"看起来完成但其实没有":**
+- 执行期间验证的检查清单格式
+- 演示 vs 生产中常见
+- 防止 "在我机器上能用" 的问题
+
+**陷阱到阶段映射:**
+- 对路线图创建至关重要
+- 每个陷阱应映射到预防它的阶段
+- 指导阶段排序和成功标准
+
+</guidelines>