helloagents 2.3.8 → 3.0.2-beta.1

package/skills/commands/loop/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ~loop
+description: 自主迭代优化循环 — 设定目标和指标，AI 自主循环修改-验证-保留/回滚，直到达成目标或达到迭代上限（~loop 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction higher|lower] [--guard "命令"]
+
+## 交互式配置
+
+如果用户未提供完整参数，通过对话确认以下配置：
+- 目标：优化什么？（如：提升测试覆盖率、减少构建时间、提升性能分数）
+- 指标命令：运行什么命令获取数值？（如：`npm run test -- --coverage`）
+- 方向：higher（越高越好）还是 lower（越低越好）？
+- 迭代上限：最多跑几轮？（默认 20，无上限则设为 0）
+- 守卫命令（可选）：每轮必须通过的底线检查（如：`npm test`）
+- 作用范围：哪些文件/目录可以修改？
+
+## 初始化
+
+1. 确认 git 工作区干净（有未提交变更则先提醒用户处理）
+2. 确保 `.helloagents/` 目录和 `.helloagents/STATE.md` 存在；目录不存在时先创建，`STATE.md` 不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制
+3. 运行指标命令获取基线值，记录到 results log
+4. 如有守卫命令，运行确认基线通过
+5. 创建 `.helloagents/loop-results.tsv`，并确保 .gitignore 包含该文件
+6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
+7. 重写 `.helloagents/STATE.md`：记录当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
+
+results log 格式：
+```
+# metric_direction: higher_is_better
+iteration	commit	metric	delta	guard	status	description
+0	a1b2c3d	85.2	0.0	pass	baseline	initial state
+```
+
+## 八阶段循环
+
+~loop 的八阶段循环是统一执行流程（ORIENT→CLARIFY→PLAN→EXECUTE→VALIDATE）在迭代优化场景下的特化形式。每轮迭代的 Modify 阶段遵循已标记的 hello-* 质量技能规范，Verify 阶段遵循 hello-verify 的验证规范。
+
+不要停止。不要询问是否继续。
+每轮迭代必须完整走完以下八个阶段：
+
+### Phase 1: Review
+- 读取 results log 最近 10-20 条记录
+- 运行 `git log --oneline -20` 查看最近变更
+- 运行 `git diff HEAD~1` 查看上一次变更
+- 如果 git log 有 results log 中未记录的 experiment commit → 上轮可能中断，先运行指标命令补录结果
+- 识别：什么有效、什么无效、什么还没试过
+
+### Phase 2: Ideate
+- 基于 review 结果，选择下一个改进方向
+- 优先尝试未探索的方向
+- 避免重复已失败的方向（git history 是记忆）
+- 连续 5 次 discard → 升级策略：组合近似成功的尝试、尝试相反方向、考虑架构级变更
+
+### Phase 3: Modify
+- 做一个原子修改（单一关注点）
+- 只修改作用范围内的文件
+- 不修改测试文件和守卫命令涉及的文件
+
+### Phase 4: Commit
+- 在验证之前提交（便于干净回滚）
+- commit message 格式：`experiment(<scope>): <description>`
+
+### Phase 5: Verify
+- 运行指标命令，获取新值
+- 计算 delta（新值 - 基线或上一次保留值）
+- 如有守卫命令，运行守卫检查
+
+### Phase 6: Decide
+- IMPROVED（指标改善 + 守卫通过）→ keep
+- SAME/WORSE（指标未改善）→ `git revert HEAD`（保留历史）
+- GUARD FAILED（指标改善但守卫失败）→ 尝试修复（最多 2 次），仍失败则 revert
+- CRASHED（命令执行失败）→ revert + 记录
+
+### Phase 7: Log
+- 追加一行到 results log
+- status: baseline / keep / discard / crash / no-op
+- 重写 `.helloagents/STATE.md`：记录当前轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
+
+### Phase 8: Repeat
+- 如果 iterations > 0 且 current_iteration >= max_iterations → 输出总结并停止
+- 否则 → 回到 Phase 1
+
+## 总结输出
+
+循环结束时输出：
+- 基线值 → 最终值（改善幅度）
+- 总迭代次数 / 保留次数 / 丢弃次数
+- 最有效的 3 个改进
+- results log 路径
+- 重写 `.helloagents/STATE.md`：将“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+
+## 安全规则
+- 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）
+- 不修改测试文件和守卫命令涉及的文件
+- 单次修改涉及 >5 个文件 → 重新评估，可能需要拆分
+- 守卫命令是底线，指标改善但守卫失败 = 不可接受

package/skills/commands/prd/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ~prd
+description: 完整 PRD 生成 — 头脑风暴式交互，逐维度挖掘，生成现代产品需求文档（~prd 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~prd [description]
+
+本 skill 自包含，不依赖再读取 `~design` 的 command skill。只有在本 skill 明确要求时，才继续读取对应的 hello-* 技能。
+
+## 铁律
+- 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
+- 每个维度的选项必须体现当前前沿水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
+- 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
+- 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
+
+## PRD 维度清单
+
+按编号排列，每个维度对应一个模板文件（templates/plans/prd/）：
+
+| 编号 | 文件 | 维度 | 说明 |
+|------|------|------|------|
+| 00 | 00-overview.md | 产品概述 | 愿景、用户画像、痛点、成功指标、范围与非目标 |
+| 01 | 01-user-stories.md | 用户故事 | 用户旅程、故事列表、边缘场景、验收标准 |
+| 02 | 02-functional.md | 功能需求 | 功能清单(MoSCoW)、业务规则、数据模型、API 契约、状态机 |
+| 03 | 03-ui-design.md | UI/UX 设计 | 设计风格、Token、布局、组件、动效、暗色模式、设计约束 |
+| 04 | 04-technical.md | 技术架构 | 技术选型、架构图、文件结构、依赖、数据库、ADR |
+| 05 | 05-nonfunctional.md | 非功能需求 | 性能、安全、可用性、可扩展性、可观测性 |
+| 06 | 06-i18n-l10n.md | 国际化与本地化 | 语言列表、文本外部化、RTL、格式化、文化适配 |
+| 07 | 07-accessibility.md | 无障碍 | WCAG 级别、键盘导航、屏幕阅读器、对比度、动效减弱 |
+| 08 | 08-content.md | 内容策略 | 文案风格、错误信息、空状态、帮助文档、SEO |
+| 09 | 09-testing.md | 测试策略 | 测试金字塔、关键场景、性能测试、兼容性矩阵 |
+| 10 | 10-deployment.md | 部署与运维 | 环境规划、CI/CD、发布策略、回滚、配置管理、数据迁移 |
+| 11 | 11-legal-privacy.md | 法律与隐私 | GDPR/CCPA、用户同意、数据保留、第三方共享、许可证 |
+| 12 | 12-timeline.md | 里程碑 | 阶段划分(MVP/V1/V2)、里程碑、依赖与风险、资源需求 |
+
+## 维度激活矩阵
+
+根据项目类型自动判断维度优先级（必选/推荐/可选）：
+
+| 项目类型 | 必选 | 推荐 | 可选 |
+|---------|------|------|------|
+| Web App | 00,01,02,03,04,09 | 05,06,07,08 | 10,11,12 |
+| Mobile App | 00,01,02,03,04,07,09 | 05,06,08 | 10,11,12 |
+| API/Backend | 00,02,04,05,09 | 10,11 | 01,08,12 |
+| CLI Tool | 00,02,04,09 | 05,08 | 10,12 |
+| Library/SDK | 00,02,04,09 | 08 | 05,10,12 |
+| 桌面应用 | 00,01,02,03,04,09 | 05,07,08 | 06,10,11,12 |
+| 游戏 | 00,01,02,03,04,09 | 05,08 | 10,12 |
+| 混合 | 取各子类型的并集 | — | — |
+
+## 流程
+
+### 1. 上下文收集（ORIENT）
+
+已有项目：
+- 读取 .helloagents/context.md 获取项目上下文和模块索引
+- 读取 .helloagents/guidelines.md 获取项目约定
+- 扫描相关代码文件理解现有架构
+
+全新项目（无 .helloagents/ 目录）：
+- 跳过，直接进入项目定位
+
+### 2. 项目定位（快速，1-2 轮）
+
+目标：快速锁定项目类型和 PRD 范围。
+
+a. 理解用户的初始描述
+b. 确认项目类型（Web App / Mobile / API / CLI / Library / 桌面 / 游戏 / 混合）
+c. 根据维度激活矩阵，列出本项目的必选/推荐/可选维度
+d. 询问用户：推荐维度是否需要？可选维度是否需要？
+e. 确定最终的维度列表
+
+### 3. 维度探索（头脑风暴，核心阶段）
+
+按维度编号顺序，逐个展开讨论。每个维度的交互模式：
+
+a. AI 先给出该维度的行业最佳实践参考和推荐方案
+b. 用户确认/修改/补充
+c. AI 总结该维度的决策结果，进入下一个维度
+
+交互原则：
+- 每个维度内，每次只问一个问题，偏好选择题
+- 用户说"跳过" → 跳过该维度，不生成对应文件
+- 用户说"默认" → AI 按推荐方案填充，快速过
+- 用户说"展开" → 深入讨论该维度的子项
+- 维度之间可以回溯：用户说"回到 03" → 重新讨论 UI/UX 设计
+
+选项质量要求：
+- 涉及视觉/交互/体验的问题时，选项必须体现当前前沿设计水准
+- 不确定当前前沿趋势时，主动搜索查阅最新设计案例和技术能力后再给出选项
+- 每个选项必须包含具体的视觉特征描述，不接受泛化标签
+
+### 4. 写入方案包
+
+将讨论结果写入本地项目：
+- 全新项目（无 .helloagents/ 目录）：先创建 .helloagents/ 和 STATE.md（按 templates/STATE.md 格式）。这是方案包写入的前置操作，不受 kb_create_mode 开关控制
+- 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/prd/
+- 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
+- 生成 tasks.md（每个任务包含具体文件路径、预期变更、验证方式；任务独立可验证；依赖顺序明确）
+- 生成 decisions.md（贯穿全程的决策日志）
+- 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md
+- 重写 .helloagents/STATE.md
+
+输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。
+
+### 5. 执行决策
+
+展示 PRD 摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
+- 开始执行 → 重写 STATE.md（下一步设为第一个任务的具体动作）
+- 修改 PRD / 补充维度 → 回到对应维度继续讨论
+- 暂不执行，保留方案 → 重写 STATE.md（下一步设为“方案已确认；执行需用户明确启动”）
+
+如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，直接进入执行，不再追加确认环节。
+
+### 6. 执行
+
+按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
+任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
+所有任务完成后进入当前已加载 bootstrap 中定义的 VALIDATE 阶段。
+可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。
+执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。
+执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。
+
+## 方案包结构
+
+~prd 生成的方案包结构：
+
+```
+plans/YYYYMMDDHHMM_{feature}/
+├── prd/                    # PRD 文档（按维度生成）
+│   ├── 00-overview.md
+│   ├── 01-user-stories.md  # 仅用户未跳过的维度
+│   ├── 02-functional.md
+│   └── ...
+├── tasks.md                # 任务分解
+└── decisions.md            # 决策日志
+```
+
+## 文档限制
+
+| 文件类型 | 上限 |
+|---------|------|
+| 单个维度文件（prd/*.md） | ≤150 行 |
+| tasks.md | ≤100 行 |
+| decisions.md | ≤80 行 |
+| 方案包总计 | ≤1500 行 |
+
+- 只记录决策和约束，不记录讨论过程
+- 用表格和列表，不用段落叙述
+- 单文件超限 → 拆分为子文件（如 `02-functional-api.md`），主文件保留摘要和链接

package/skills/commands/review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: ~review
+description: 代码审查 + 质量检查（~review 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~review [scope]
+
+## 流程
+
+1. 获取变更范围：
+   - 无参数：git diff（未提交的变更）
+   - 指定文件/目录：只审查指定范围
+   - "staged"：git diff --staged
+2. 按 hello-* 技能查找路径读取 hello-review SKILL.md，按其审查规范逐文件审查
+3. 按严重度分类输出结果，给出具体修复建议

package/skills/commands/test/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: ~test
+description: 为指定模块或最近变更编写完整测试（~test 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~test [scope]
+
+## 流程
+
+1. 确定测试范围：
+   - 无参数：为最近变更的文件编写测试
+   - 指定文件/模块：为指定范围编写测试
+2. 按 hello-* 技能查找路径读取 hello-test SKILL.md，按其 TDD 规范和边界用例要求编写测试
+3. 运行测试确认全部通过
+4. 报告覆盖情况和遗漏

package/skills/commands/verify/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ~verify
+description: 运行项目的所有验证命令并报告结果（~verify 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~verify
+
+## 流程
+
+1. 按 hello-* 技能查找路径读取 hello-verify SKILL.md，并按其“验证命令来源”优先级检测命令
+2. 逐个运行所有检测到的命令
+3. 收集每个命令的输出和退出码
+4. 汇总报告：
+   - ✅ 通过的命令
+   - ❌ 失败的命令 + 错误详情
+   - 修复建议
+
+## 失败处理
+- 有失败 → 逐个修复，修复后重新运行验证
+- 全部通过 → 报告完成

package/skills/hello-api/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: hello-api
+description: 构建、修改或审查 REST API、GraphQL 端点、webhook、中间件、请求/响应处理、API 版本管理、限流或分页时使用。
+---
+
+API 相关代码必须遵循以下规范。
+
+## 编码前
+先确定资源模型和端点契约，再写代码。
+
+## RESTful 设计
+- 资源命名：复数名词 `/users`，嵌套 `/users/:id/posts`
+- HTTP 方法语义：GET 读、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
+- 状态码准确：200 成功、201 创建、204 无内容、400 参数错误、401 未认证、403 无权限、404 不存在、409 冲突、422 验证失败、500 服务端错误
+
+## 请求验证
+- 入参验证在 controller 层，使用 schema 验证库（zod、joi、ajv）
+- 验证类型、范围、格式、必填
+- 文件上传限制大小和类型
+- 请求体大小限制
+
+## 响应格式
+- 统一成功响应：`{ data, meta? }`
+- 统一错误响应：`{ error: { code, message, details? } }`
+- 列表接口必须分页：`?page=1&limit=20` 或 cursor-based
+- 支持排序：`?sort=created_at&order=desc`
+- 过滤参数白名单
+
+## 版本与保护
+- API 版本化：URL 前缀 `/v1/` 或 header
+- 限流保护：按 IP/用户/API key
+- 超时设置：所有外部调用设超时
+- CORS：明确允许的 origin，不用 `*`
+
+## 交付检查
+- [ ] 状态码准确反映操作结果
+- [ ] 所有入参已验证
+- [ ] 列表接口有分页
+- [ ] 错误响应格式统一
+- [ ] 有限流保护

package/skills/hello-arch/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: hello-arch
+description: 重构代码、调整模块结构、管理依赖、拆分文件、提取组件、设计系统架构或做代码组织决策时使用。
+---
+
+架构相关变更必须遵循以下规范。
+
+## 编码前
+先画出当前→目标依赖关系和变更路径，再写代码。
+
+## SOLID 原则
+- 单一职责：一个模块/类只做一件事，变更只有一个原因
+- 开闭原则：扩展开放，修改关闭——新功能通过扩展实现
+- 依赖倒置：高层不依赖低层，都依赖抽象（接口/协议）
+
+## 边界与分层
+- 清晰的模块边界，通过接口通信
+- 依赖方向：外层 → 内层（UI → Service → Repository）
+- 循环依赖 = 架构问题，必须解决
+- 配置与代码分离，环境变量管理
+
+## 代码组织
+- 按功能分组（feature-based），非按类型分组
+- 代码体积控制（同当前已加载 bootstrap 的编码原则）：文件/类预警 300 行、强制拆分 400 行，函数预警 40 行、强制拆分 60 行。例外：生成代码、大型测试夹具、迁移脚本、协议常量表
+- 公共逻辑提取到 shared/，但避免过早抽象
+- 三次重复才提取——两次相似不够
+
+## 变更策略
+- 评估变更的影响范围（blast radius）
+- 大重构分步进行，每步可独立验证和回滚
+- 保持向后兼容，除非明确要求破坏性变更
+
+## 交付检查
+- [ ] 无循环依赖
+- [ ] 文件/类不超过 400 行，函数不超过 60 行（例外类型除外，非压缩代码）
+- [ ] 依赖方向正确（外 → 内）
+- [ ] 变更范围可控
+- [ ] 技术选型符合当前已加载 bootstrap 的技术下限要求；若当前模式未加载质量下限章节，则至少满足技术选型原则且新项目无过时依赖

package/skills/hello-data/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: hello-data
+description: 操作数据库、编写迁移、设计 schema、管理事务、创建索引、使用 Prisma/Sequelize/TypeORM/Mongoose 等 ORM，或执行 SQL/NoSQL 操作时使用。
+---
+
+数据库相关代码必须遵循以下规范。
+
+## 编码前
+先设计数据模型、迁移策略、回滚方案，再写代码。
+
+## 迁移管理
+- 所有 schema 变更通过迁移文件，不手动修改数据库
+- 迁移必须可回滚（up + down）
+- 生产迁移前在 staging 验证
+- 迁移文件按时间戳排序
+
+## 事务处理
+- 多表写操作使用事务
+- 事务范围最小化，避免长事务锁表
+- 死锁预防：固定加锁顺序
+- 失败时完整回滚，不留半完成状态
+
+## 索引策略
+- 查询条件字段建索引
+- 复合索引注意列顺序（最左前缀匹配）
+- 不要过度索引——每个索引都有写入成本
+- 定期检查慢查询，优化索引
+
+## 数据完整性
+- 外键约束保证引用完整性
+- NOT NULL + DEFAULT 避免脏数据
+- 唯一约束防止重复
+- 软删除 vs 硬删除：根据业务需求选择，但要一致
+
+## 交付检查
+- [ ] Schema 变更通过迁移文件
+- [ ] 多表写操作使用事务
+- [ ] 查询条件字段有索引
+- [ ] 无 N+1 查询（配合 hello-perf）

package/skills/hello-debug/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: hello-debug
+description: 调试错误、修复 bug、排查失败测试、处理异常行为，或代码行为与预期不符时使用。
+---
+
+调试相关工作必须遵循以下规范。
+
+## 编码前
+禁止未经根因分析直接修复。
+
+## Git 作为记忆
+每次调试前，先读取相关的 git 历史：
+- `git log --oneline -20` 查看最近变更
+- `git log --all --grep="revert"` 查看过去的失败回滚
+- 如果发现之前已经尝试并回滚过类似修复 → 不要重复同样的方向
+
+## 四阶段调试法
+
+### 1. 定位
+- 完整读取错误信息（不截断、不猜测）
+- 稳定复现问题（确定触发条件）
+- 反向追踪数据流（从错误点向上游追溯）
+
+### 2. 分析
+- 找到类似的正常工作代码，对比差异
+- 检查最近的变更（git log/diff）
+- 识别所有隐含假设
+
+### 3. 假设
+- 形成具体、可验证的假设
+- 单变量测试（一次只改一个东西）
+- 记录每次尝试和结果
+
+### 4. 修复
+- 先写失败测试复现 bug
+- 实现最小修复（针对根因，不是症状）
+- 验证修复有效且无回归
+
+## 卡住升级机制
+
+连续修复失败时，按以下阶梯升级策略：
+
+第 1-2 次失败：正常反思，调整修复方向
+第 3 次失败：停止。3 次失败意味着可能是架构问题而非局部 bug。重新从根因分析开始，质疑当前方向是否正确
+第 4 次失败：扩大范围——重读所有相关文件，审查 git 历史中的相关变更，检查是否有隐藏的依赖或副作用
+第 5 次失败：必须与用户讨论。提出以下选项：
+  1. 组合之前接近成功的尝试
+  2. 尝试完全相反的方向
+  3. 重构架构而非继续局部修补
+  4. 重新定义问题
+
+超过 5 次：停止自主尝试，转为用户决策。
+
+## 交付检查
+- [ ] 根因已识别并记录
+- [ ] 有失败测试复现 bug
+- [ ] 单一修复针对根因
+- [ ] 无回归引入

package/skills/hello-errors/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: hello-errors
+description: 实现错误处理、try-catch、日志记录、监控、重试逻辑、降级机制，或处理错误响应和异常管理时使用。
+---
+
+错误处理相关代码必须遵循以下规范。
+
+## 编码前
+先分类可预期错误 vs 不可预期错误，再写代码。
+
+## 错误分类
+- 可预期错误（验证失败、资源不存在）→ 正常处理，返回友好信息
+- 不可预期错误（系统故障、第三方宕机）→ 记录日志，返回通用错误
+- 不要用 try-catch 包裹所有代码——只捕获你能处理的
+
+## 结构化错误
+- 统一错误格式：`{ code, message, details? }`
+- HTTP 状态码准确：4xx 客户端错误，5xx 服务端错误
+- 不暴露内部实现细节（堆栈、SQL、文件路径）给用户
+- 错误码可枚举，便于前端处理
+
+## 日志规范
+- 结构化日志（JSON），包含 timestamp、level、context
+- 错误日志包含：堆栈、请求 ID、用户上下文
+- 敏感信息脱敏后再记录（密码、token、身份证）
+- 日志级别：error（必须处理）> warn（需关注）> info（正常流程）> debug（调试）
+
+## 恢复策略
+- 外部调用：超时 + 重试（指数退避，最多 3 次）
+- 关键操作：幂等设计，支持安全重试
+- 优雅降级：部分功能不可用时不影响核心流程
+- 断路器：连续失败超过阈值时快速失败
+
+## 交付检查
+- [ ] 错误响应格式统一
+- [ ] 不暴露内部细节给用户
+- [ ] 外部调用有超时设置
+- [ ] 敏感信息已脱敏
+- [ ] 无静默失败：无空 catch 吞错误、无静默降级、无静默回退（见当前已加载 bootstrap 的“静默失败防护”规则）

package/skills/hello-perf/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: hello-perf
+description: 优化性能、处理数据库查询、实现缓存、懒加载、分页、打包优化，或代码涉及大数据集循环、并发操作、内存管理时使用。
+---
+
+性能相关代码必须遵循以下规范。
+
+## 编码前
+先定位性能瓶颈（I/O / 计算 / 内存），再写代码。
+
+## 查询优化
+- 禁止 N+1 查询：使用 JOIN、批量加载、dataloader
+- 大数据集必须分页，不一次加载全部
+- 数据库索引覆盖常用查询条件
+- 只查需要的字段（SELECT 具体列，不用 SELECT *）
+
+## 缓存策略
+- 读多写少的数据 → 缓存（内存/Redis）
+- 设置合理的 TTL
+- 缓存失效策略：写时失效 > 定时过期
+- 防止缓存穿透（空值缓存）和雪崩（随机 TTL）
+
+## 前端性能
+- 代码分割 + 路由级懒加载
+- 图片：WebP/AVIF、懒加载、srcset 响应式
+- 声明 width/height 或 aspect-ratio 防止布局偏移
+- 关键 CSS 内联，非关键 CSS 异步加载
+- 50+ 项列表使用虚拟滚动
+
+## 算法与并发
+- 注意时间复杂度，禁止嵌套循环处理大数据集（O(n²)+）
+- Map/Set 查找 O(1) vs Array.includes O(n)
+- 批量操作优于逐条操作
+- 高频事件（scroll/resize/input）使用 debounce/throttle
+
+## 交付检查
+- [ ] 无 N+1 查询
+- [ ] 列表接口有分页
+- [ ] 图片已优化（格式/懒加载/尺寸声明）
+- [ ] 无嵌套循环处理大数据集

package/skills/hello-reflect/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: hello-reflect
+description: 任务完成后使用 — 生成会话反思，提取经验教训追加到相关模块文档，供未来会话参考。
+---
+
+任务完成后，执行会话反思。
+
+## 触发条件
+以下场景完成后应生成反思（kb_create_mode ≥ 1 时）：
+- 经历了 2+ 次验证循环才通过
+- 调试超过 3 次尝试才修复
+- 执行过程中方案发生变更
+- 用户纠正了错误的假设或方向
+
+## 反思产出
+将反思内容追加到相关 modules/*.md 的"经验"章节（增量追加，不重写）。
+
+追加格式：
+```
+- [{日期}] {经验教训} — 背景: {什么有效/什么失败的简述}
+```
+
+如果涉及多个模块，分别追加到各自的 modules/*.md。
+如果不属于任何特定模块（如项目级经验），追加到 context.md 末尾新增的"## 经验"章节。
+
+## 质量要求
+- 经验教训必须是抽象指导，不是具体代码模板（具体模板会导致 AI 锚定在错误细节上）
+- 每条经验 ≤2 行，精简有力
+- 只记录真正有价值的发现，不记录显而易见的事情
+
+## 交付检查
+- [ ] 经验已追加到相关 modules/*.md 的经验章节
+- [ ] 经验教训是抽象指导而非具体模板
+- [ ] 适用场景从上下文可推断

package/skills/hello-review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: hello-review
+description: 审查代码变更、检查 PR、review 代码质量，或用户要求看看代码、检查代码时使用。
+---
+
+代码审查必须遵循以下规范。
+
+## 审查维度
+
+逐文件检查以下维度：
+- 逻辑正确性：Bug、边界条件、空值处理、竞态条件
+- 安全漏洞：注入、XSS、硬编码密钥、权限绕过
+- 性能问题：N+1 查询、内存泄漏、不必要的重渲染、大循环
+- 可维护性：命名清晰、职责单一、重复代码、过度抽象
+- 错误处理：异常是否被正确捕获和处理
+
+## 严重度分类
+
+- 🔴 严重：必须修复（Bug、安全漏洞、数据丢失风险）
+- 🟡 建议：应该修复（性能问题、可维护性、代码风格）
+- 🟢 良好：值得肯定的好实践
+
+## 审查原则
+
+- 指出问题时给出具体修复建议和代码示例
+- 不只挑毛病，也肯定好的实践
+- 关注变更本身，不扩大审查范围到未修改的代码
+- 严重问题优先，建议性问题其次
+
+## 交付检查
+- [ ] 每个文件都已审查
+- [ ] 严重问题都有修复建议
+- [ ] 按严重度分类输出

package/skills/hello-security/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: hello-security
+description: 涉及认证、密码、token、JWT、OAuth、session、cookie、加密、密钥、API key、权限、角色、用户输入验证、文件上传等安全敏感操作时使用。
+---
+
+安全相关代码必须遵循以下规范。
+
+## 编码前
+先识别攻击面和信任边界，再写代码。
+
+## 认证与密钥
+- 密码：bcrypt/argon2 哈希，不可逆存储
+- JWT：设置过期时间，使用 RS256 或 HS256，不在 payload 存敏感数据
+- 密钥/API key：环境变量或密钥管理服务，不硬编码
+- .env 不提交到版本控制（.gitignore）
+- API key 使用最小权限原则
+
+## 输入验证
+- 所有外部输入（用户、API、文件）必须验证
+- 白名单优于黑名单
+- SQL：参数化查询，不拼接字符串
+- 文件上传：验证类型、大小、内容，不信任文件扩展名
+
+## 输出防护
+- XSS：输出编码，设置 CSP 头
+- CSRF：token 验证
+- 敏感数据：HTTPS 传输，加密存储，不记录到日志
+- 错误信息：不暴露内部实现细节给用户
+
+## 权限控制
+- 最小权限原则
+- 检查资源所有权（不能只检查角色）
+- 路径遍历：规范化路径，限制访问范围
+
+## 交付检查
+- [ ] 无硬编码密钥/密码
+- [ ] 所有用户输入已验证
+- [ ] SQL 使用参数化查询
+- [ ] 敏感数据不在日志中
+- [ ] 认证 token 有过期时间