@deepstorm/cli 0.1.0

package/dist/skills/atoll-ops/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: atoll-ops
+description: 运维辅助 — 部署策略、监控查询、故障排查
+allowed-tools: []
+deepstorm:
+  tool: atoll
+---
+
+# Atoll — 运维侧工具集
+
+> 🏝️ 环礁为珊瑚礁生态系统提供保护屏障——Atoll 保障服务的稳定运行。
+
+当前为规划阶段，功能待实现。
+
+## 规划中的核心功能
+
+### 部署辅助
+- CI/CD 流水线管理与触发
+- 部署策略建议（滚动更新/蓝绿部署/金丝雀发布）
+- 回滚评估与执行
+
+### 监控查询
+- 监控平台数据查询（Prometheus/Grafana/Datadog）
+- 告警分析与聚合
+- 性能趋势诊断
+
+### 故障排查
+- 错误日志分析
+- 慢查询/慢接口定位
+- 依赖链追踪
+- 故障恢复策略建议
+
+### 云平台操作
+- 资源状态查询
+- 配置变更管理
+- 成本分析
+
+---
+
+## 使用方式
+
+安装后可直接通过自然语言提出运维需求：
+
+> "帮我看看生产环境最近的错误日志"
+> "部署这个版本的策略建议是什么？"
+> "分析下这个告警的根因"

package/dist/skills/reef-commit/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: reef-commit
+description: 根据当前变更和 OpenSpec 上下文，生成规范的提交信息并创建新提交。用户说「提交代码」「commit」「git push」「提交」「推送」等触发
+allowed-tools: Bash(git:*), Bash(./gradlew:*), Bash(pnpm:*)
+deepstorm:
+  tool: reef
+---
+
+# 智能生成提交信息
+
+根据当前变更、OpenSpec 任务定义及仓库历史 PR 风格，生成中文提交信息，创建新的 git 提交。
+
+## 提交信息风格规范（基于历史 PR 总结）
+
+### 标题
+
+1. 不使用 conventional commit 前缀（无 `feat:`、`fix:`、`chore:` 等）
+2. 一句话说清做了什么，可含英文术语
+3. 命名来源优先级：OpenSpec proposal/design 标题 → 分支名语义化 → 变更内容总结
+4. 每行 ≤ 70 字符
+
+### 正文（根据任务复杂度决定）
+
+| 复杂度 | 正文策略 |
+|--------|---------|
+| 简单（单文件/小修补/配置改动） | 仅标题 |
+| 中等 | 标题 + 一段说明 |
+| 复杂（多模块/架构级/前后端/破坏性变更） | 标题 + `本次提交改动如下：` + 要点列表 |
+
+有参考文档加 `参考资料：`，关联 Issue 在尾部隔空行加 `JIRA: {完整 URL}`。文件数仅作参考（50 个重命名仍属简单）。
+
+## 工作流
+
+### 1. 检测变更
+
+```bash
+git status --short
+```
+
+若无任何变更则提示用户并退出。
+
+### 2. 审查待提交文件
+
+展示变更清单，检查敏感文件：
+
+```bash
+git diff --stat
+```
+
+如包含 `.env`、凭据、证书或大型二进制文件，让用户确认或排除后再继续。
+
+### 2.4 分支范围检查
+
+检查当前分支是否涉及多个业务领域。如果跨领域，给出拆分建议并中止提交。
+
+```bash
+BRANCH=$(git branch --show-current)
+FORK_POINT=$(git merge-base main HEAD 2>/dev/null || echo "")
+echo "检查分支范围（基准: main）..."
+SCOPE_HOOK="packages/reef/hooks/reef-scope-gate.sh"
+if [ -f "$SCOPE_HOOK" ]; then
+  bash "$SCOPE_HOOK" || {
+    echo ""
+    echo "提示：如需继续提交，请使用 'reef-scope-split.sh' 拆分分支"
+    echo "或临时禁用 scope 检查（不推荐）：deepstorm/scope-config.json → enabled: false"
+    exit 1
+  }
+fi
+```
+
+### 2.5 运行单元测试
+
+```bash
+git status --short
+```
+
+如有变更则全量运行测试：
+
+```bash
+./gradlew test
+(cd src/main/web && pnpm test -- --run)
+```
+
+- 测试全部通过 → 继续
+- 任一测试失败 → 提示用户修复后再提交
+
+### 3. 收集上下文
+
+```bash
+BRANCH=$(git branch --show-current)
+FORK_POINT=$(git merge-base main HEAD 2>/dev/null)
+echo "Branch: $BRANCH"; git diff "$FORK_POINT"..HEAD --stat
+ls -d openspec/changes/*/ 2>/dev/null | grep -v archive
+[ -f "openspec/changes/$BRANCH/proposal.md" ] && head -5 "openspec/changes/$BRANCH/proposal.md"
+# 从 proposal/commit 提取 Issue 引用
+grep -iE '(issue|jira|lc-|proj-)' "openspec/changes/$BRANCH/proposal.md" 2>/dev/null | head -3
+git log "$FORK_POINT"..HEAD --format="%B" 2>/dev/null | grep -ioP '[A-Z]+-\d+' | head -1
+```
+
+### 4. 生成提交信息
+
+**标题：** 优先 OpenSpec proposal 标题 → 分支名（kebab-case 转中文）→ 变更总结。依赖更新用 `更新 {依赖} 至 {版本}`，问题修复用 `解决{问题描述}的问题`。
+
+**正文：** 中/复杂变更用 `本次提交改动如下：` + 3-6 条要点。尾部隔空行加 `JIRA: {完整 URL}`（优先从 proposal.md/jira-start 元数据中获取 JIRA 链接），如有 PRD 链接加 `Ref: {URL}`。
+
+### 5. 展示并确认
+
+展示完整提交信息，用户确认即可提交；支持 `--amend` 合并；用户可要求修改后重新生成。
+
+### 6. 执行提交
+
+```bash
+git add -A && git commit -m "<完整提交信息>"
+# 用户要求 amend 时: git commit --amend -m "<完整提交信息>"
+```
+
+### 7. 推送（仅在用户要求时）
+
+```bash
+# 新提交（有远程跟踪）：git push
+# Amend：git push --force-with-lease
+# 首次推送：git push -u origin $(git branch --show-current)
+```
+
+## 约束规则
+
+默认新提交，用户要求才 `--amend`。每行 ≤ 70 字符。无变更则退出。

package/dist/skills/reef-gen-backend/SKILL.md.tmpl

@@ -0,0 +1,87 @@
+---
+name: reef-gen-backend
+description: 后端代码编写流程（{{reef.backend.language.label}}）。编写或生成后端代码时自动加载，编码规范详情引用 reef:reef-style-backend。
+when_to_use: 用户要求编写或修改后端代码；创建新的后端文件；用户说"生成后端代码""写接口""加表"等
+user-invocable: false
+allowed-tools: Bash(git:*), Bash({{reef.backend.language.buildTool}})
+deepstorm:
+  tool: reef
+  configKey: reef.backend.language
+---
+
+# 后端代码编写流程
+
+编码规范详情（实体层次、数据访问、业务逻辑、API 模式、多租户红线、代码风格）请通过 Skill tool 加载 **`reef:reef-style-backend`** 获取。
+
+## 工作流
+
+### 1. 找参考实现
+
+在动手之前，先在已有代码中找一个同类实现。优先搜索当前模块目录：
+
+```bash
+# 替换 <module> 为当前模块名
+find {{reef.backend.language.sourcePath}} -path "*/<module>/*" -type f
+
+# 找最近修改的同类文件（使用 fork-point 避免全量历史）
+FORK_POINT=$(git merge-base "$(git reflog --date=local | grep "checkout: moving from.* to $(git rev-parse --abbrev-ref HEAD)$" | head -1 | sed -n 's/.*from \([^ ]*\) to .*/\1/p' || echo main)" HEAD)
+git diff "$FORK_POINT"..HEAD --diff-filter=M --name-only
+```
+
+**规则**：不凭空写新文件。先读一个真实存在的同类文件，理解模式后再动手。写新模块时参考已有模块的完整实现。
+
+### 2. 查阅规范
+
+加载 `reef:reef-style-backend` 技能，阅读 `quick-reference.md` 和必要示例。
+
+涉及库/框架 API 用法时，使用 context7 获取最新文档：`resolve-library-id` → `query-docs`。
+
+### 3. 编写代码
+
+{{#if reef.backend.language.sourcePath}}
+阅读本技能目录下的 `steps.md` 了解当前技术栈的编码步骤顺序和规范。编写过程中逐单元对照 `reef:reef-style-backend` 中对应章节检查。
+
+**注释语言**：代码注释统一使用中文，专有名词/技术术语（如 REST、DTO、HTTP、JPA 等）保留英文。
+{{/if}}
+
+{{#if reef.backend.java.dbMigration.styleRef}}
+### 4. 数据库迁移
+
+如果涉及新表或字段变更（新增实体、新增字段、修改字段类型），加载 `reef:reef-style-backend` 技能，阅读其数据库迁移章节创建变更文件。
+
+迁移脚本参考：加载 `reef:reef-style-backend` 后阅读 `examples/` 目录中的示例。
+{{else}}
+{{#if reef.backend.python.dbMigration.styleRef}}
+### 4. 数据库迁移
+
+如果涉及新表或字段变更（新增实体、新增字段、修改字段类型），加载 `reef:reef-style-backend` 技能，阅读其数据库迁移章节创建变更文件。
+
+迁移脚本参考（Alembic）：加载 `reef:reef-style-backend` 后阅读 `examples/` 目录中的示例。
+{{/if}}
+{{/if}}
+
+### {{#if reef.backend.java.dbMigration.styleRef}}5{{else}}{{#if reef.backend.python.dbMigration.styleRef}}5{{else}}4{{/if}}{{/if}}. 运行验证
+
+写完后运行验证：
+
+{{#if reef.backend.language.isPython}}
+```bash
+# 快速验证
+ruff check .
+
+# 最终验证（提交前）
+ruff check . && mypy . && python -m pytest
+```
+{{else}}
+```bash
+# 快速验证（秒级）
+{{reef.backend.language.formatCmd}} build
+
+# 最终验证（提交前）
+{{reef.backend.language.formatCmd}} check
+```
+{{/if}}
+
+### {{#if reef.backend.java.dbMigration.styleRef}}6{{else}}{{#if reef.backend.python.dbMigration.styleRef}}6{{else}}5{{/if}}{{/if}}. 提交前自检
+
+加载 `reef:reef-style-backend` 技能，逐项检查所有规范要求。**未通过不得提交。**

package/dist/skills/reef-gen-backend/variants/java/steps.md

@@ -0,0 +1,28 @@
+# Java 后端编码步骤
+
+按以下顺序逐块编写，依赖关系由前向后：
+
+1. **Entity** — 实体类，定义表结构（JPA 注解、表名、字段映射）
+2. **DTO** — 数据传输对象，匹配实体层次
+3. **Mapper** — MapStruct 映射，连接 Entity ↔ DTO
+4. **Repository** — 数据访问（Spring Data JPA），多租户安全查询
+5. **Service** — 业务逻辑，事务管理
+6. **Controller** — REST API，请求/响应
+
+每完成一块对照 `reef:reef-style-backend` 中对应章节检查。
+
+## 多租户红线
+
+- 所有数据库查询用 `findByIdAndAppId`，禁止裸 `findById`
+- 禁止 `createNativeQuery`
+- 禁止手动拼接 SQL
+
+## 构建命令
+
+```bash
+# 快速编译验证
+./gradlew compileJava
+
+# 完整检查（测试 + 风格）
+./gradlew check
+```

package/dist/skills/reef-gen-backend/variants/python/steps.md

@@ -0,0 +1,70 @@
+# Python 后端编码步骤（FastAPI）
+
+按以下顺序逐块编写，依赖关系由前向后：
+
+## 0. 安装依赖
+
+如项目尚未安装所需包，用 `uv` 安装：
+
+```bash
+# FastAPI + ASGI 服务器
+uv add fastapi uvicorn[standard]
+
+# SQLAlchemy（异步）+ Alembic
+uv add sqlalchemy[asyncio] alembic asyncpg
+
+# Pydantic 验证
+uv add pydantic[email]
+
+# LangChain（如启用 AI 集成）
+uv add langchain langchain-openai
+
+# 开发依赖
+uv add --dev pytest pytest-asyncio httpx ruff mypy
+```
+
+1. **Schema** — Pydantic Model，定义请求/响应结构
+2. **Model** — SQLAlchemy ORM Model，定义表结构
+3. **Migration** — Alembic 迁移文件，生成 DDL
+4. **Service** — 业务逻辑，输入验证，事务管理
+5. **Router** — FastAPI API 路由，请求/响应
+6. **注册到主应用**
+
+将新创建的路由器注册到主应用中：
+
+```python
+# app/main.py
+from fastapi import FastAPI
+from app.api.v1 import users, orders
+
+app = FastAPI(title="MyApp")
+
+# 注册路由
+app.include_router(users.router, prefix="/api/v1/users", tags=["users"])
+app.include_router(orders.router, prefix="/api/v1/orders", tags=["orders"])
+```
+
+每完成一块对照 `reef:reef-style-backend` 的 Python 章节检查。
+
+## ⚠️ 异步红线
+
+- 所有数据库操作用 `AsyncSession`，禁止同步 `Session`
+- Service 层函数都用 `async def`
+- `async def` 内部禁止调同步 IO（`time.sleep()`、`requests.get()`）
+- 需要同步操作时用 `asyncio.to_thread()` 包裹
+
+## 构建命令
+
+```bash
+# 格式化和 lint
+ruff check . && ruff format
+
+# 类型检查
+mypy .
+
+# 运行测试
+python -m pytest
+
+# 启动开发服务器
+uv run uvicorn app.main:app --reload
+```

package/dist/skills/reef-gen-frontend/SKILL.md.tmpl

@@ -0,0 +1,83 @@
+---
+name: reef-gen-frontend
+description: 前端代码编写流程（{{reef.frontend.framework.label}}）。编写或生成前端代码时自动加载，编码规范详情引用 reef:reef-style-frontend。
+when_to_use: 用户要求编写或修改前端代码；创建新的前端文件；用户说"生成前端代码""写页面""写组件""加表单"等
+user-invocable: false
+allowed-tools: Bash(git:*), Bash({{reef.frontend.framework.buildTool}})
+model: opus
+deepstorm:
+  tool: reef
+  configKey: reef.frontend.framework
+---
+
+# 前端代码编写流程
+
+编码规范详情（组件/Signal/Signal Forms/HTTP/UI 库/CSS/路由/错误处理）请通过 Skill tool 加载 **`reef:reef-style-frontend`** 获取。
+
+## 工作流
+
+### 1. 找参考实现
+
+在动手之前，先在已有代码中找一个同类实现。优先搜索当前模块目录：
+
+```bash
+# 替换 <module> 为当前模块名
+find {{reef.frontend.framework.sourcePath}} -path "*/<module>/*" -type f
+
+# 找最近修改的同类文件（使用 fork-point 避免全量历史）
+FORK_POINT=$(git merge-base "$(git reflog --date=local | grep "checkout: moving from.* to $(git rev-parse --abbrev-ref HEAD)$" | head -1 | sed -n 's/.*from \([^ ]*\) to .*/\1/p' || echo main)" HEAD)
+git diff "$FORK_POINT"..HEAD --diff-filter=M --name-only
+```
+
+**规则**：不凭空写新文件。先读一个真实存在的同类文件，理解模式后再动手。
+
+### 2. 查阅规范
+
+加载 `reef:reef-style-frontend` 技能，阅读 `quick-reference.md` 和必要示例。
+
+涉及库/框架 API 用法时，使用 context7 获取最新文档：`resolve-library-id` → `query-docs`。
+
+{{#if reef.frontend.framework.sourcePath}}
+### 3. 获取设计数据
+
+如果当前变更关联了设计工具数据（从 `design.md` 或 Issue context 中可获取 `fileKey` 和 `nodeId`），通过运行时能力映射检测可用的设计工具 MCP 服务加载设计节点数据。
+
+运行时 AI 从 `.claude/settings.json` → `deepstorm.mcpCapabilities` 中感知可用的设计工具 provider，读取 `.claude/skills/deepstorm-mcp-figma-read/SKILL.md` 了解工具调用方式。使用 design_tools MCP 工具获取设计节点数据：
+
+```bash
+<design_tool_mcp_get_data>(fileKey: "<fileKey>", nodeId: "<nodeId>")
+```
+
+从返回的节点结构中提取实现所需的设计 token：
+- **尺寸**：节点宽高、间距、内边距
+- **颜色**：填充色、边框色、文字色
+- **排版**：字号、字重、行高
+- **布局**：Flex/Grid 方向、对齐方式、Auto Layout 属性
+
+设计数据用于指导 UI 实现，无需另外编写文档中转。如果无可用设计工具 MCP 服务则跳过。
+{{/if}}
+
+### {{#if reef.frontend.framework.sourcePath}}4{{else}}3{{/if}}. 编写代码
+
+{{#if reef.frontend.framework.sourcePath}}
+阅读本技能目录下的 `steps.md` 了解当前框架的编码步骤顺序和核心约束。编写过程中逐单元对照 `reef:reef-style-frontend` 中对应章节检查。
+
+**注释语言**：代码注释统一使用中文，专有名词/技术术语（如 Signal、Pipe、Component、Service、httpResource 等）保留英文。
+{{/if}}
+
+### {{#if reef.frontend.framework.sourcePath}}5{{else}}4{{/if}}. 运行验证
+
+先快速验证，写完后全量检查：
+
+```bash
+# 快速验证（秒级，确保编译和类型通过）
+{{reef.frontend.framework.formatCmd}} lint
+{{reef.frontend.framework.formatCmd}} typecheck
+
+# 最终验证（提交前）
+{{reef.frontend.framework.formatCmd}} lint && {{reef.frontend.framework.formatCmd}} typecheck && {{reef.frontend.framework.formatCmd}} test
+```
+
+### {{#if reef.frontend.framework.sourcePath}}6{{else}}5{{/if}}. 提交前自检
+
+加载 `reef:reef-style-frontend` 技能，逐项检查所有规范要求。**未通过不得提交。**

package/dist/skills/reef-gen-frontend/variants/angular/steps.md

@@ -0,0 +1,30 @@
+# Angular 前端编码步骤
+
+按以下顺序逐块编写，依赖关系由前向后：
+
+1. **类型定义** — 实体接口/类型，继承 `shared/base.ts`
+2. **Service** — HttpClient 封装，`httpResource` 读请求
+3. **Component** — 组件 UI，Signal 状态，Signal Forms
+4. **路由** — `loadComponent` 懒加载注册
+
+每完成一块对照 `reef:reef-style-frontend` 中对应章节检查。
+
+## 核心约束
+
+- Standalone 组件（不使用 NgModule）
+- OnPush ChangeDetection
+- `inject()` 代替构造函数注入
+- Signal Forms 代替模板驱动表单
+- `httpResource` 代替手动 subscribe
+- Service 禁止管理 UI 状态
+
+## 构建命令
+
+```bash
+# 快速验证
+pnpm lint
+pnpm typecheck
+
+# 完整检查
+pnpm lint && pnpm typecheck && pnpm test
+```

package/dist/skills/reef-harden/EXAMPLES.md

@@ -0,0 +1,89 @@
+# Spec Hardener — 实践案例
+
+以下案例来自 `form-excel-import-export` change 的实际加固过程。
+
+## 案例：proposal.md — 补"不做什么"
+
+### 加固前
+
+proposal.md 的 Scope 段列出了 21 条要做的功能，但没有一条"不做什么"。
+
+### 加固后
+
+在 Scope 和 Impact 之间新增：
+
+```markdown
+## 不做什么
+- 仅支持 Scope 中列出的控件类型（TextControl、NumberControl、DateTimeControl、
+  ChoiceControl、ObjectControl），其余控件均不在本版本支持范围内
+- 不支持批量导入（不支持一次上传多个 Excel 文件）
+- 不支持并发导入（不处理多个用户同时导入同一表单的并发控制）
+- 不支持超大文件处理（不实现分片上传或流式解析）
+- 不支持多 Sheet 导入/导出（仅单 Sheet 可见数据 + 单 Sheet 隐藏元数据）
+- 仅支持使用系统导出的模板进行导入（不接受用户自定义格式的 Excel）
+- 仅支持新增数据（不支持通过 Excel 更新已有 FormResponse）
+- ObjectControl 仅支持单层数据关联（不支持嵌套对象）
+```
+
+关键动作：反向提问用户"第一版应该不做什么"，将用户回答整理为结构化清单。
+
+---
+
+## 案例：spec.md — 补 Known Limitations
+
+### 加固后
+
+spec.md 末尾新增：
+
+```markdown
+## Known Limitations
+本版本存在以下已知约束：
+
+- **仅支持新增**：导入操作仅创建新的 FormResponse，不支持通过
+  Excel 更新已有数据。如需对已有数据进行批量修改，需等待后续版本。
+- **ObjectControl 仅单层**：ObjectControl 的数据关联值仅支持一层
+  对象引用，不支持嵌套的关联对象结构。
+- **仅接受系统模板**：导入功能仅接受通过本系统导出接口生成的
+  Excel 模板填写后上传。用户自行构造的 Excel 将直接拒绝。
+- **单文件串行处理**：每次导入仅支持一个 Excel 文件，不提供并发导入
+  或流式逐行写入的能力。
+- **固定限制不可配置**：5MB 文件上限、3000 行上限、200 列上限为
+  硬编码限制，当前版本不提供管理员可配置的入口。
+```
+
+来源：反向 grill（"三个月后可能在哪五处后悔"）+ "不做什么"段。
+
+---
+
+## 案例：tasks.md — 细化验证
+
+### 加固前
+
+```markdown
+- [x] 7.1 `FormExportServiceTest`：测试 Excel 生成逻辑（表头必填标记、
+  填写说明行、下拉验证、隐藏 Sheet、Sheet 保护）
+```
+
+### 加固后
+
+```markdown
+- [x] 7.1 `FormExportServiceTest`：覆盖 TextControl / NumberControl /
+  DateTimeControl / ChoiceControl（PredefinedOptionsSource + DatasetOptionsSource）
+  / ObjectControl 五种控件导出；验证标题行必填标记 *、填写说明行、_meta Sheet
+  的 revisionId 与 key 顺序、Sheet VERY_HIDDEN + 保护、白名单过滤、空字段报错
+```
+
+关键动作：将"测试 X"的许愿式描述替换为场景覆盖清单。
+
+---
+
+## 案例：数字处理策略
+
+加固过程中发现的数字：
+
+| 数字 | 处理方式 | 理由 |
+|------|---------|------|
+| 5MB / 3000行 / 200列 | **不修改** | 业务指标，用户确认 |
+| #3B82F6 / #22C55E 等颜色 | **不修改** | 有引用来源（Figma） |
+| w-225（对话框宽度） | **不修改** | 设计稿尺寸，可追溯 |
+| application.properties vs .yaml | **修正** | 项目实际使用 yaml，文档写错 |