openmatrix 0.2.15 → 0.2.17

package/skills/deploy.md

@@ -0,0 +1,338 @@
+---
+name: om:deploy
+description: "智能部署助手：分析项目+系统环境 → 推荐最可行方案 → 执行部署 → 生成一键脚本。Triggers on: deploy, 部署, 发布, docker, kubernetes, 环境搭建, 开发环境, make, taskfile, pm2"
+---
+
+<NO-OTHER-SKILLS>
+执行此技能时，不得调用 superpowers、gsd 或其他任务编排相关的技能。
+</NO-OTHER-SKILLS>
+
+<objective>
+智能部署助手：自动分析项目文件和系统环境 → 推荐当前环境下最可行的部署方案 → 用户确认后执行 → 生成可复用的一键脚本。
+</objective>
+
+<process>
+
+## Step 1: 分析项目文件
+
+直接读取项目文件，不调用 CLI：
+
+```bash
+# 项目配置文件
+ls -la Dockerfile docker-compose.yml docker-compose.yaml Makefile Taskfile.yml Taskfile.yaml 2>/dev/null
+ls -la k8s/ helm/ .github/workflows/ 2>/dev/null
+cat package.json 2>/dev/null
+cat go.mod 2>/dev/null
+cat Cargo.toml 2>/dev/null
+cat requirements.txt pyproject.toml 2>/dev/null
+```
+
+提取关键信息：
+- 项目类型（Node.js/Go/Python/Rust/Java 等）
+- 已有部署配置（Dockerfile、docker-compose、Makefile、k8s 等）
+- package.json 中的 scripts（build/start/deploy 等）
+
+---
+
+## Step 2: 检测系统环境
+
+```bash
+# 检测已安装的工具
+docker --version 2>/dev/null && echo "docker:ok" || echo "docker:missing"
+docker-compose --version 2>/dev/null && echo "docker-compose:ok" || echo "docker-compose:missing"
+kubectl version --client 2>/dev/null && echo "kubectl:ok" || echo "kubectl:missing"
+make --version 2>/dev/null && echo "make:ok" || echo "make:missing"
+task --version 2>/dev/null && echo "task:ok" || echo "task:missing"
+pm2 --version 2>/dev/null && echo "pm2:ok" || echo "pm2:missing"
+node --version 2>/dev/null && echo "node:ok" || echo "node:missing"
+
+# 操作系统
+uname -s 2>/dev/null || echo "Windows"
+```
+
+---
+
+## Step 3: AI 分析并展示环境报告
+
+基于收集到的信息，直接输出分析报告（不用 AskUserQuestion）：
+
+```markdown
+## 🔍 环境分析报告
+
+**项目**: [名称] ([类型])
+**操作系统**: [Linux/macOS/Windows]
+
+### 已检测到的部署配置
+- ✅ Dockerfile
+- ✅ docker-compose.yml
+- ❌ Makefile（未找到）
+
+### 已安装的工具
+- ✅ Docker 24.0.5
+- ✅ make 4.3
+- ❌ task（未安装）
+- ❌ pm2（未安装）
+```
+
+---
+
+## Step 4: 推荐部署方案（带理由）
+
+AI 根据"项目配置 × 已安装工具"交叉分析，用 AskUserQuestion 展示推荐方案：
+
+**推荐逻辑（AI 自行判断，不是硬编码）：**
+- 有 Dockerfile + docker 已安装 → Docker 是最直接的选择
+- 有 docker-compose + 多服务 → Docker Compose 更合适
+- 有 k8s 配置 + kubectl 已安装 → Kubernetes
+- 有 Makefile + make 已安装 → 直接用 make
+- Node.js + pm2 已安装 → PM2 轻量方案
+- 什么都没有 → AI 根据项目类型推荐创建配置
+
+```
+AskUserQuestion:
+  header: "部署方案"
+  question: "基于你的环境分析，推荐以下方案（已标注推荐原因）："
+
+  options:
+  - label: "Docker (推荐)"
+    description: "已有 Dockerfile + Docker 已安装，直接可用，环境隔离好"
+  - label: "Docker Compose"
+    description: "检测到 docker-compose.yml，适合多服务编排"
+  - label: "Make"
+    description: "已有 Makefile + make 已安装，运行 make deploy"
+  - label: "npm scripts"
+    description: "无需额外工具，直接用 package.json 中的 scripts"
+```
+
+---
+
+## Step 5: 确认部署环境
+
+```
+AskUserQuestion:
+  header: "目标环境"
+  question: "部署到哪个环境？"
+
+  options:
+  - label: "本地开发 (推荐)"
+    description: "快速启动，用于开发调试"
+  - label: "测试环境"
+    description: "模拟生产配置，用于验证"
+  - label: "生产环境"
+    description: "需要完整配置和安全检查"
+```
+
+---
+
+## Step 6: 执行部署
+
+根据用户选择，AI 执行对应命令：
+
+**Docker 本地：**
+```bash
+docker build -t <project-name> .
+docker run -d -p <port>:<port> --name <project-name> <project-name>
+docker ps | grep <project-name>
+```
+
+**Docker Compose：**
+```bash
+docker-compose up -d --build
+docker-compose ps
+```
+
+**Make：**
+```bash
+make deploy
+```
+
+**npm scripts：**
+```bash
+npm run build
+npm run start
+```
+
+执行后验证：
+```bash
+# 检查服务是否正常运行
+docker ps 2>/dev/null | grep <name>
+curl -s http://localhost:<port>/health 2>/dev/null || echo "服务已启动"
+```
+
+输出执行结果，告知用户服务状态。
+
+---
+
+## Step 7: 询问是否生成一键脚本
+
+```
+AskUserQuestion:
+  header: "一键脚本"
+  question: "部署完成！是否生成一键脚本方便后续开发调试？"
+
+  options:
+  - label: "生成 Taskfile.yml (推荐)"
+    description: "task 已安装 / 现代化工具，YAML 格式简洁，跨平台"
+  - label: "生成 Makefile"
+    description: "make 已安装 / 经典工具，已有 Makefile 时保持一致"
+  - label: "添加到 npm scripts"
+    description: "Node.js 项目，无需额外工具"
+  - label: "不需要"
+    description: "已有足够配置"
+```
+
+---
+
+## Step 8: 生成一键脚本
+
+根据用户选择和项目实际情况，用 Write 工具生成脚本。
+
+**Taskfile.yml 示例（根据实际项目定制）：**
+```yaml
+version: '3'
+
+vars:
+  APP: '{{.APP | default "app"}}'
+  PORT: '{{.PORT | default "3000"}}'
+
+tasks:
+  setup:
+    desc: 安装依赖
+    cmds:
+      - npm install
+
+  build:
+    desc: 构建项目
+    cmds:
+      - npm run build
+
+  test:
+    desc: 运行测试
+    cmds:
+      - npm test
+
+  dev:
+    desc: 本地开发（热重载）
+    cmds:
+      - npm run dev
+
+  deploy:local:
+    desc: 本地 Docker 部署
+    cmds:
+      - docker build -t {{.APP}} .
+      - docker run -d -p {{.PORT}}:{{.PORT}} --name {{.APP}} {{.APP}}
+      - echo "✅ 服务已启动 http://localhost:{{.PORT}}"
+
+  deploy:prod:
+    desc: 生产部署
+    cmds:
+      - docker build -t {{.APP}}:{{.VERSION}} .
+      - docker push {{.REGISTRY}}/{{.APP}}:{{.VERSION}}
+
+  logs:
+    desc: 查看日志
+    cmds:
+      - docker logs -f {{.APP}}
+
+  stop:
+    desc: 停止服务
+    cmds:
+      - docker stop {{.APP}} && docker rm {{.APP}}
+```
+
+**Makefile 示例（根据实际项目定制）：**
+```makefile
+APP ?= app
+PORT ?= 3000
+
+.PHONY: setup build test dev deploy-local deploy-prod logs stop
+
+setup:
+	npm install
+
+build:
+	npm run build
+
+test:
+	npm test
+
+dev:
+	npm run dev
+
+deploy-local:
+	docker build -t $(APP) .
+	docker run -d -p $(PORT):$(PORT) --name $(APP) $(APP)
+	@echo "✅ 服务已启动 http://localhost:$(PORT)"
+
+deploy-prod:
+	docker build -t $(APP):$(VERSION) .
+	docker push $(REGISTRY)/$(APP):$(VERSION)
+
+logs:
+	docker logs -f $(APP)
+
+stop:
+	docker stop $(APP) && docker rm $(APP)
+```
+
+---
+
+## Step 9: 输出总结
+
+```markdown
+## ✅ 部署完成
+
+**方案**: Docker 本地部署
+**环境**: 本地开发
+**脚本**: 已生成 Taskfile.yml
+
+### 常用命令
+- `task dev` — 本地开发
+- `task deploy:local` — Docker 本地部署
+- `task deploy:prod` — 生产部署
+- `task logs` — 查看日志
+- `task stop` — 停止服务
+```
+
+</process>
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+<examples>
+/om:deploy              # 自动分析 → 推荐方案 → 执行 → 生成脚本
+/om:deploy local        # 直接指定本地环境
+/om:deploy prod         # 直接指定生产环境
+</examples>
+
+<notes>
+## 核心原则
+
+1. **AI 是分析者**：读取真实文件和系统状态，不靠硬编码规则推断
+2. **AI 是执行者**：用户确认后直接运行命令，不只是给建议
+3. **推荐最可行的**：基于"当前系统已有什么工具"，不是"理论上最好的"
+4. **产出可复用脚本**：最终生成 Taskfile/Makefile，方便后续开发调试
+
+## 推荐决策依据（AI 自行判断）
+
+| 项目配置 | 系统工具 | 推荐方案 |
+|---------|---------|---------|
+| 有 Dockerfile | docker 已安装 | Docker |
+| 有 docker-compose | docker-compose 已安装 | Docker Compose |
+| 有 k8s/ | kubectl 已安装 | Kubernetes |
+| 有 Makefile | make 已安装 | Make |
+| Node.js | pm2 已安装 | PM2 |
+| Node.js | 无特殊工具 | npm scripts |
+| 无任何配置 | docker 已安装 | 生成 Dockerfile |
+| 无任何配置 | 无工具 | npm scripts / shell 脚本 |
+
+## 脚本工具选择依据
+
+| 条件 | 推荐 |
+|------|------|
+| task 已安装 | Taskfile.yml |
+| make 已安装 / 已有 Makefile | Makefile |
+| Node.js 项目 / 无工具 | npm scripts |
+| Windows + 无工具 | package.json scripts |
+</notes>

package/skills/feature.md

@@ -20,6 +20,7 @@ priority: high
 ## 执行顺序 - 必须严格按此顺序，不得跳过
 
 ```
+Step 0:  Git 前置检查与持久化初始化（必须执行）
 Step 1:  接收任务输入（参数、文件、或询问用户）
 Step 2:  AI 自动判断任务边界（不符合条件才询问切换）
 Step 3:  收集项目上下文（技术栈、目录结构、CLAUDE.md）
@@ -45,6 +46,39 @@ Step 11: 输出执行摘要并清理
 
 <process>
 
+## Step 0: Git 前置检查与持久化初始化（必须执行）
+
+**检查 Git 仓库:**
+
+```bash
+ls -la .git 2>/dev/null || echo "NOT_INITIALIZED"
+git status --porcelain
+```
+
+| 检查结果 | 处理 |
+|---------|------|
+| `NOT_INITIALIZED` | AskUserQuestion 是否初始化 git |
+| 有未提交文件 | AskUserQuestion 处理方式（暂存/忽略/取消） |
+| 干净 | 继续执行 |
+
+**初始化持久化状态:**
+
+```bash
+mkdir -p .openmatrix
+cat > .openmatrix/feature-session.json << 'EOF'
+{
+  "sessionId": "FEATURE-$(date +%Y%m%d%H%M%S)",
+  "status": "running",
+  "tasks": [],
+  "currentTaskIndex": 0,
+  "quality": null,
+  "failureCount": {}
+}
+EOF
+echo '' > .openmatrix/feature-context.md
+echo '' > .openmatrix/feature-progress.md
+```
+
 ## Step 1: 接收任务输入
 
 **检查 `$ARGUMENTS`:**
@@ -96,35 +130,33 @@ AskUserQuestion: `header: "任务复杂度"`, `multiSelect: false`
 | 切换到 /om:start | 使用完整流程 |
 | 继续用 /om:feature | 强制使用轻量流程（可能无法完整追踪） |
 
-## Step 3: 收集项目上下文
+## Step 3: 收集项目上下文并写入文件
 
-**在拆分任务前，收集必要的项目上下文信息，存入 `${projectContext}` 变量供后续步骤使用。**
+**收集并写入上下文文件:**
 
 ```bash
-# 收集技术栈（从 package.json 提取关键依赖）
-cat package.json | grep -E '"(react|vue|angular|next|express|fastify|koa|typeorm|prisma|sequelize|mongoose|jest|vitest|playwright|cypress)"' || echo "未检测到常见框架"
+mkdir -p .openmatrix
 
-# 收集项目目录结构（仅顶层，避免输出过长）
-find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.openmatrix/*' | head -30
+# 写入上下文文件头
+echo "# 项目上下文" > .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
-# 读取 CLAUDE.md 项目规范（如果存在）
-cat CLAUDE.md 2>/dev/null | head -50 || echo "无 CLAUDE.md"
-```
+# 收集技术栈并写入文件
+echo "## 技术栈" >> .openmatrix/feature-context.md
+cat package.json 2>/dev/null | grep -E '"(react|vue|angular|next|express|fastify|koa|typeorm|prisma|sequelize|mongoose|jest|vitest|playwright|cypress)"' >> .openmatrix/feature-context.md || echo "未检测到常见框架" >> .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
-**将收集结果存入 `${projectContext}`：**
+# 收集目录结构并写入文件
+echo "## 目录结构" >> .openmatrix/feature-context.md
+find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.openmatrix/*' 2>/dev/null | head -30 >> .openmatrix/feature-context.md
+echo "" >> .openmatrix/feature-context.md
 
+# 读取 CLAUDE.md 并写入文件
+echo "## 项目规范（来自 CLAUDE.md）" >> .openmatrix/feature-context.md
+cat CLAUDE.md 2>/dev/null | head -50 >> .openmatrix/feature-context.md || echo "无 CLAUDE.md" >> .openmatrix/feature-context.md
 ```
-## 项目上下文
-
-### 技术栈
-${从 package.json 提取的关键依赖}
 
-### 目录结构
-${顶层目录结构}
-
-### 项目规范（来自 CLAUDE.md）
-${CLAUDE.md 前 50 行，包含构建/测试命令、架构概述、开发约定}
-```
+上下文已写入 `.openmatrix/feature-context.md`，后续 Agent 会读取此文件。
 
 ## Step 4: AI 拆分为 2-5 个小任务块
 
@@ -191,7 +223,7 @@ TodoWrite({
 })
 ```
 
-状态仅在当前会话有效，不产生持久化文件。
+状态同时在会话和 `.openmatrix/feature-session.json` 中管理。
 
 ## Step 6: 问答确认
 
@@ -199,18 +231,29 @@ TodoWrite({
 
 **6.1 质量等级（必选）**
 
+根据任务描述，Claude 直接推断推荐的质量等级，并在问题中标注推荐项：
+
+- Bug 修复 / 重构 → 推荐 `balanced`
+- 原型 / demo / 快速验证 → 推荐 `fast`
+- 新功能 / 生产代码 / 涉及测试 → 推荐 `strict`
+- 文档 / skill 文件 → 推荐 `fast`
+
 AskUserQuestion: `header: "质量等级"`, `multiSelect: false`
 
-**question:** 选择质量等级（决定测试覆盖、Lint、安全扫描等要求）
+**question:** 选择质量等级（Claude 推荐：${inferredQuality}，原因：${inferReason}）
 
 | label | description |
 |-------|-------------|
 | `strict` | TDD + >80%覆盖率 + 严格Lint + 安全扫描 — 生产级代码 |
-| `balanced (推荐)` | >60%覆盖率 + Lint + 安全扫描 — 日常开发 |
+| `balanced` | >60%覆盖率 + Lint + 安全扫描 — 日常开发 |
 | `fast` | 无质量门禁 — 快速原型/验证 |
 
 **6.2 E2E 测试（仅 strict/balanced）**
 
+根据任务描述推断：若任务涉及前端页面/UI/Web，询问；否则默认跳过（不需要）。
+
+如需询问：
+
 AskUserQuestion: `header: "E2E 测试"`, `multiSelect: false`
 
 **question:** 是否需要端到端 (E2E) 测试？（适用于 Web/Mobile/GUI 项目）
@@ -241,7 +284,56 @@ AskUserQuestion: `header: "确认计划"`, `multiSelect: false`
 TodoWrite({ todos: [...] }) // 当前任务标记 in_progress
 ```
 
-**7.2 调用 Agent 执行**
+**7.2 歧义检测与处理**
+
+Agent 输出中可能包含歧义报告：
+
+当 Agent 输出包含以下标记时，表示检测到歧义：
+```
+<AMBIGUITY_REPORT>
+{
+  "ambiguities": [
+    {
+      "type": "missing_info" | "conflicting_req" | "unclear_scope" | "tech_choice" | "edge_case",
+      "severity": "critical" | "high" | "medium" | "low",
+      "description": "歧义描述",
+      "suggestions": ["建议1", "建议2"]
+    }
+  ],
+  "overallSeverity": "critical" | "high" | "medium" | "low"
+}
+</AMBIGUITY_REPORT>
+```
+
+**5 种歧义类型说明：**
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `missing_info` | 缺失关键信息 | "未指定数据库类型" |
+| `conflicting_req` | 需求冲突 | "既要高性能又要低成本" |
+| `unclear_scope` | 范围不清晰 | "是否包含历史数据处理？" |
+| `tech_choice` | 技术选型歧义 | "用 REST 还是 GraphQL？" |
+| `edge_case` | 边界情况未定义 | "超过限制时如何处理？" |
+
+**歧义处理策略（轻量模式）：**
+
+| 严重程度 | 处理方式 |
+|---------|---------|
+| **Critical/High** | AskUserQuestion 立即确认 |
+| **Medium/Low** | 写入进度文件，继续执行 |
+
+**AskUserQuestion 处理（仅 Critical/High）：**
+
+AskUserQuestion: `header: "歧义确认"`, `multiSelect: false`
+**question:** 检测到 ${severity} 级歧义：${description}。请确认处理方式
+
+| label | description |
+|-------|-------------|
+| 提供信息 | 回答歧义相关问题，继续执行 |
+| 跳过任务块 | 标记当前任务块为可选，继续执行下一个 |
+| 修改方案 | 根据歧义调整方案后继续 |
+
+**7.3 调用 Agent 执行**
 
 ```typescript
 Agent({
@@ -249,6 +341,12 @@ Agent({
   description: task.content,
   prompt: `你是实现专家。执行以下任务块。
 
+## 项目上下文（请读取文件）
+请先读取 .openmatrix/feature-context.md 了解项目上下文。
+
+## 前序任务结果（请读取文件）
+请读取 .openmatrix/feature-progress.md 了解前序 Agent 的决策和发现。
+
 ## 整体任务
 ${taskDescription}
 
@@ -258,11 +356,6 @@ ${taskDescription}
 - 质量等级：${quality}
 - 前置任务完成状态：${previousTasksStatus}
 
-${projectContext}
-
-${agentMemory ? `## 前序任务结果（跨 Agent 上下文）
-${agentMemory}` : ''}
-
 ## 质量要求
 ${quality === 'strict' ? `
 - 必须使用 TDD：先写测试，再写实现
@@ -307,17 +400,19 @@ ${quality === 'strict' ? `
 })
 ```
 
-**7.3 等待 Agent 完成，收集上下文**
+**7.3 等待 Agent 完成，写入进度文件**
 
-Agent 完成后，将输出中的关键决策和建议追加到 `${agentMemory}` 变量中：
-```
-${agentMemory}
----
-## 任务 N: ${task.content}
-${agentOutput}
+Agent 完成后，将输出中的关键决策和建议写入 `.openmatrix/feature-progress.md` 文件：
+
+```bash
+# Agent 完成后，追加写入进度文件
+echo "" >> .openmatrix/feature-progress.md
+echo "## 任务 N: ${task.content}" >> .openmatrix/feature-progress.md
+echo "${agentOutput}" >> .openmatrix/feature-progress.md
+echo "" >> .openmatrix/feature-progress.md
 ```
 
-这样后续 Agent 能获取前序 Agent 的决策和发现。
+这样后续 Agent 能通过读取文件获取前序 Agent 的决策和发现。
 
 ## Step 8: 验证（按质量等级）
 
@@ -329,10 +424,14 @@ ${agentOutput}
 
 | 质量等级 | 验证命令 |
 |---------|---------|
-| `strict` | `npm test -- --run && npm run lint && npm run test:coverage` |
-| `balanced` | `npm test -- --run && npm run lint` |
+| `strict` | `npm test -- --run && npm run lint && npm run test:coverage && npm audit --audit-level=moderate` |
+| `balanced` | `npm test -- --run && npm run lint && npm audit --audit-level=moderate` |
 | `fast` | 跳过验证 |
 
+**覆盖率阈值检查说明：**
+- strict 模式要求 >80% 覆盖率，`npm run test:coverage` 命令应输出覆盖率报告
+- balanced 模式要求 >60% 覆盖率，建议定期检查覆盖率报告
+
 **8.2 E2E 验证（如果用户选择）**
 - 功能测试：`npm run test:e2e`
 - 视觉验证：启动 Playwright 截图对比
@@ -366,8 +465,14 @@ fi
 
 **⛔ 验证通过后必须立即提交，不得积累多个任务块**
 
+**只提交本次任务修改的文件（而非 `git add -A`）：**
+
 ```bash
-git add -A
+# 获取本次任务修改的文件列表（从 Agent 输出中提取）
+git status --porcelain
+
+# 只提交任务涉及的文件
+git add ${modifiedFiles}
 git commit -m "$(cat <<'EOF'
 feat(feature): ${originalTask} - ${currentChunk}
 
@@ -420,8 +525,8 @@ ${decisions}
 
 **清理操作：**
 - TodoWrite 所有任务保持 completed 状态
-- 不产生任何 `.openmatrix/` 持久化文件
-- 会话结束后状态自动消失
+- 持久化文件可选择保留或手动清理
+- 任务完成后状态标记为 `completed`
 
 </process>
 
@@ -474,12 +579,12 @@ $ARGUMENTS
 
 ## 与其他指令的区别
 
-| 指令 | 适用场景 | 任务文件 | 问答 | 验证 |
-|-----|---------|:-------:|:----:|:----:|
-| `/om:feature` | 小需求（≤100字，单一功能） | ❌ | 质量+E2E | 按等级 |
-| `/om:start` | 标准任务 | ✅ | 质量+E2E+模式 | 按等级 |
-| `/om:brainstorm` | 复杂任务 | ✅ | 设计问答 | 按等级 |
-| `/om:auto` | 全自动执行 | ✅ | 无 | 按等级 |
+| 指令 | 适用场景 | 任务文件 | 问答 | 验证 | 持久化 |
+|-----|---------|:-------:|:----:|:----:|:-----:|
+| `/om:feature` | 小需求（≤100字，单一功能） | ❌ | 质量+E2E | 按等级 | 必须 |
+| `/om:start` | 标准任务 | ✅ | 质量+E2E+模式 | 按等级 | 必须 |
+| `/om:brainstorm` | 复杂任务 | ✅ | 设计问答 | 按等级 | 必须 |
+| `/om:auto` | 全自动执行 | ✅ | 无 | 按等级 | 必须 |
 
 ## 路由触发条件
 
@@ -492,13 +597,14 @@ $ARGUMENTS
 ## 错误处理流程
 
 ```
-验证失败 → 停止执行 → 展示错误详情 → 提示用户修复 → 建议使用 /om:resume 继续
+验证失败 → 停止执行 → 展示错误详情 → 提示用户修复 → 使用 /om:resume 恢复
 ```
 
 | 错误 | 处理 |
 |-----|-----|
 | 测试失败 | 停止，提示用户修复 |
 | Lint 错误 | 停止，提示用户修复 |
+| 安全扫描失败 | 停止，提示用户修复 |
 | Agent 超时 | 询问重试或跳过 |
 | Git 失败 | 提示手动处理 |
 
@@ -534,8 +640,14 @@ type: feat/fix/test/refactor/docs
 
 ## 恢复执行
 
-如果验证失败需要修复，使用 `/om:resume` 继续执行：
-```bash
-/om:resume
-```
+如果验证失败需要修复：
+
+使用 `/om:resume` 继续执行（自动检测 `.openmatrix/feature-session.json` 或 `state.json`）
+
+## 挡久化文件说明
+
+执行过程中产生以下文件：
+- `.openmatrix/feature-session.json` - 会话状态（任务列表、当前索引、质量等级）
+- `.openmatrix/feature-context.md` - 项目上下文
+- `.openmatrix/feature-progress.md` - Agent 执行进度
 </notes>