ironweave 1.0.0

package/skills/engineering-principles/references/patterns-module.md

@@ -0,0 +1,95 @@
+# 中尺度模式（模块 / 子系统级）
+
+调度、协调、流控、并发管理相关模式。
+
+## 管道 / 中间件 (Pipeline / Middleware)
+
+```typescript
+// 数据沿处理链流过，每个中间件独立
+type Middleware = (ctx: Context, next: () => Promise<void>) => Promise<void>
+
+const app = new App()
+app.use(cors())        // 跨域
+app.use(authGuard())   // 认证
+app.use(rateLimit())   // 限流
+app.use(router())      // 路由
+```
+
+## 工作池 (Worker Pool)
+
+```typescript
+// 有限并发 + 任务队列
+class WorkerPool {
+  private running = 0
+  private queue: (() => Promise<void>)[] = []
+
+  constructor(private concurrency: number) {}
+
+  async add<T>(task: () => Promise<T>): Promise<T> {
+    if (this.running >= this.concurrency) {
+      await new Promise<void>(r => this.queue.push(async () => r()))
+    }
+    this.running++
+    try { return await task() }
+    finally { this.running--; this.queue.shift()?.() }
+  }
+}
+```
+
+## 断路器 (Circuit Breaker)
+
+```typescript
+// 三态: closed → open → half-open → closed
+class CircuitBreaker {
+  private failures = 0
+  private state: 'closed' | 'open' | 'half-open' = 'closed'
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') throw new Error('Circuit is open')
+    try {
+      const result = await fn()
+      this.reset()
+      return result
+    } catch (e) {
+      this.failures++
+      if (this.failures >= this.threshold) this.state = 'open'
+      throw e
+    }
+  }
+}
+```
+
+## 仓库模式 (Repository)
+
+```typescript
+// 数据访问抽象，隔离 ORM/SQL 细节
+interface UserRepository {
+  findById(id: string): Promise<User | null>
+  findByEmail(email: string): Promise<User | null>
+  save(user: User): Promise<User>
+}
+
+// 底层实现可替换（TypeORM, Prisma, 内存mock）
+class TypeORMUserRepository implements UserRepository { ... }
+class InMemoryUserRepository implements UserRepository { ... } // 测试用
+```
+
+## 有限状态机 (FSM)
+
+适用场景：表单流程、工作流引擎、游戏逻辑、协议解析、UI 交互状态。
+
+```typescript
+// 状态 + 事件 + 转换表 = 可预测行为
+interface FSM<S extends string, E extends string> {
+  initial: S
+  states: Record<S, { on?: Partial<Record<E, S>>; type?: 'final' }>
+}
+
+function transition<S extends string, E extends string>(
+  fsm: FSM<S, E>, current: S, event: E
+): S {
+  const next = fsm.states[current]?.on?.[event]
+  if (!next) throw new Error(`Invalid transition: ${current} + ${event}`)
+  return next
+}
+```

package/skills/engineering-principles/references/patterns-small-scale.md

@@ -0,0 +1,79 @@
+# 小尺度模式（函数级）
+
+单个函数或几行代码粒度的模式。
+
+## Guard Clause（提前返回）
+
+```typescript
+// DO: 提前返回消除嵌套
+function getPayAmount(employee: Employee): number {
+  if (employee.isSeparated) return 0
+  if (employee.isRetired) return retiredAmount()
+  return normalPayAmount()
+}
+
+// DON'T: 多层嵌套
+function getPayAmount(employee: Employee): number {
+  if (!employee.isSeparated) {
+    if (!employee.isRetired) {
+      return normalPayAmount()
+    } else {
+      return retiredAmount()
+    }
+  } else {
+    return 0
+  }
+}
+```
+
+## Pipe / Compose（管道与组合）
+
+```typescript
+// DO: 线性数据流变换
+const result = pipe(rawInput, normalize, parse, validate, format)
+
+// DON'T: 嵌套调用
+const result = format(validate(parse(normalize(rawInput))))
+```
+
+## 表驱动（Table-Driven）
+
+```typescript
+// DO: 用数据替代分支逻辑
+const statusConfig: Record<Status, { icon: string; color: string }> = {
+  active: { icon: '✅', color: 'green' },
+  pending: { icon: '⏳', color: 'yellow' },
+  error: { icon: '❌', color: 'red' },
+}
+const { icon, color } = statusConfig[status] ?? statusConfig.pending
+
+// DON'T: if-else 逐个判断
+if (status === 'active') { icon = '✅'; color = 'green' }
+else if (status === 'pending') { icon = '⏳'; color = 'yellow' }
+```
+
+## Null Object（空对象）
+
+```typescript
+// DO: 无操作对象代替 null 检查
+const logger = options.logger ?? { log: () => {}, warn: () => {} }
+
+// DON'T: 到处检查 if (logger)
+if (logger) { logger.log(...) }
+```
+
+## 惰性求值 & 闭包封装
+
+```typescript
+// 惰性求值：延迟到首次访问才计算
+class Config {
+  private _parsed?: ParsedConfig
+  get parsed() { return this._parsed ??= parseConfig(this.raw) }
+}
+
+// 闭包封装私有状态
+function createCounter(initial = 0) {
+  let count = initial
+  return { increment: () => ++count, get: () => count }
+}
+```

package/skills/engineering-principles/references/quality-checklist.md

@@ -0,0 +1,76 @@
+# 代码质量检查清单
+
+## Clean Code（始终适用）
+
+### 命名
+
+- **DO**: `getUserByEmail(email)` — 动词+名词，意图清晰
+- **DON'T**: `getData(e)` — 无语义缩写
+
+### 函数
+
+- 单个函数 ≤ 30 行（超过考虑拆分）
+- 参数 ≤ 3 个（超过用对象参数）
+- 一个函数做一件事（能用一个动词描述）
+- 避免 boolean 参数（拆成两个函数）
+
+### 避免 Magic Number
+
+- **DO**: `const MAX_RETRY = 3; if (retries >= MAX_RETRY)`
+- **DON'T**: `if (retries >= 3)`
+
+### 注释
+
+- 好的代码不需要注释解释"做什么"（命名应自解释）
+- 注释用于解释"为什么"（业务原因、历史决策、workaround）
+- **DON'T**: `// 增加计数器` `count++`
+
+## 错误处理（始终适用）
+
+### 异常分级
+
+| 级别 | 类型 | 处理方式 |
+|------|------|---------|
+| 业务异常 | 参数校验失败、业务规则违反 | 返回明确错误码和消息 |
+| 系统异常 | 数据库超时、网络错误 | 记录日志 + 降级/重试 |
+| 致命异常 | 配置缺失、依赖不可用 | 快速失败（fail fast） |
+
+### 具体约束
+
+- **DO**: 自定义异常类区分业务/系统异常
+- **DO**: 在系统边界处（Controller/API Gateway）统一捕获并格式化
+- **DON'T**: `catch (e) {}` — 绝不吞异常
+- **DON'T**: 用异常控制正常流程
+
+### 边界校验
+
+- 在系统入口（Controller/API）校验输入
+- 领域层假设输入合法（已被入口校验）
+- **DO**: `if (!email.includes('@')) throw new ValidationError('...')`
+- **DON'T**: 在每一层都重复校验同一参数
+
+## 可测试性（有测试框架时适用）
+
+- 业务逻辑通过构造函数注入依赖（不在方法内 new）
+- 纯函数优先（无副作用，输出只取决于输入）
+- 外部依赖（DB / HTTP / 文件系统）通过接口隔离
+- 避免全局状态和静态方法中的副作用
+
+## 性能意识（涉及 DB / API 时适用）
+
+| 问题 | 检查项 |
+|------|-------|
+| N+1 查询 | 循环中有单条查询 → 改为批量查询 |
+| 缺少索引 | WHERE/JOIN 字段无索引 → 检查执行计划 |
+| 大数据返回 | API 返回所有字段 → 按需 select |
+| 重复计算 | 同一请求中多次查同一数据 → 缓存/提前查询 |
+
+## 安全实践（涉及用户输入/API 时适用）
+
+| 威胁 | 防护 |
+|------|------|
+| SQL 注入 | 参数化查询，不拼接 SQL |
+| XSS | 输出编码，CSP headers |
+| CSRF | Token 校验 |
+| 越权 | 每个 API 校验当前用户权限 |
+| 敏感数据 | 密码 bcrypt，日志脱敏，不返回敏感字段 |

package/skills/engineering-principles/references/solid-principles.md

@@ -0,0 +1,46 @@
+# SOLID 原则
+
+## SRP — 单一职责原则
+
+一个类/函数只有一个引起它变化的原因。
+
+- **DO**: 拆分 `UserService` 为 `UserAuthService` + `UserProfileService`
+- **DON'T**: 一个 `UserService` 同时处理登录、注册、修改资料、发邮件
+
+判断标准：如果你需要用"和"来描述一个类的职责，它可能违反了 SRP。
+
+## OCP — 开闭原则
+
+对扩展开放，对修改关闭。通过接口/抽象类实现新行为，而非修改已有代码。
+
+- **DO**: 定义 `PaymentStrategy` 接口，新增支付方式实现新类
+- **DON'T**: 在 `pay()` 方法中用 `if/else` 判断支付类型
+
+适用信号：当你发现自己在添加新的 `else if` 分支时，考虑 OCP。
+
+## LSP — 里氏替换原则
+
+子类必须能替代父类使用，不改变程序正确性。
+
+- **DO**: `Square extends Rectangle` 在所有使用 `Rectangle` 的地方行为一致
+- **DON'T**: 子类重写方法后抛出父类调用方不期望的异常
+
+适用信号：当子类需要限制或强制父类的某些行为时，继承关系可能不合适。
+
+## ISP — 接口隔离原则
+
+客户端不应依赖它不使用的接口。多个小接口优于一个大接口。
+
+- **DO**: `Readable`, `Writable`, `Closable` 三个独立接口
+- **DON'T**: 一个 `FileOperations` 接口包含 20 个方法，实现类只用其中 3 个
+
+适用信号：实现类中有大量空方法或 `throw new NotImplementedError()`。
+
+## DIP — 依赖倒置原则
+
+高层模块不应依赖低层模块，两者都应依赖抽象。
+
+- **DO**: `OrderService` 依赖 `OrderRepository`（接口），具体实现注入
+- **DON'T**: `OrderService` 直接 `new MySQLOrderRepository()`
+
+适用信号：`new` 关键字出现在业务类中（应通过依赖注入替代）。

package/skills/engineering-principles/references/tdd-workflow.md

@@ -0,0 +1,60 @@
+# TDD 工作流
+
+## 适用条件
+
+- 项目已配置测试框架（jest / vitest / junit / pytest / go test）
+- 新功能开发 或 Bug 修复
+
+## 不适用场景
+
+- 旧项目无测试框架且无计划引入
+- 纯 UI 样式调整（无逻辑）
+- 一次性脚本/迁移脚本
+
+## 红绿重构循环
+
+```
+🔴 RED   → 写一个失败的测试（定义期望行为）
+🟢 GREEN → 写最少代码让测试通过
+🔵 REFACTOR → 重构代码，保持测试绿色
+```
+
+每次循环控制在 5-15 分钟。
+
+## 测试金字塔
+
+```
+        /  E2E  \          少量 · 慢 · 高置信
+       /  集成测试  \       适量 · 中速
+      /   单元测试    \     大量 · 快 · 高频
+```
+
+| 层级 | 占比 | 测试什么 |
+|------|------|---------|
+| 单元 | 70% | 纯函数、业务逻辑、工具方法 |
+| 集成 | 20% | API 端点、数据库交互、模块间协作 |
+| E2E | 10% | 关键用户流程、冒烟测试 |
+
+## 具体约束
+
+- **DO**: 每个新 public 函数写至少 1 个正向 + 1 个异常测试
+- **DO**: Bug 修复先写复现测试，再改代码
+- **DO**: 测试方法名描述行为：`should_return_error_when_email_invalid`
+- **DON'T**: 测试实现细节（不要 mock 私有方法）
+- **DON'T**: 测试中有条件逻辑（if/for）
+- **DON'T**: 一个测试验证多个不相关行为
+
+## BDD 扩展（需有 E2E 框架）
+
+适用条件：项目配置了 Cypress / Playwright。
+
+验收场景用 Gherkin 格式：
+
+```gherkin
+Scenario: 用户登录成功
+  Given 用户在登录页面
+  When 输入正确的用户名和密码
+  And 点击登录按钮
+  Then 应跳转到首页
+  And 显示用户名
+```