openmatrix 0.2.5 → 0.2.7

package/dist/storage/file-store.js

@@ -48,7 +48,8 @@ class FileStore {
         }
         catch (error) {
             // 只隐藏"文件不存在"错误，其他错误（权限、磁盘等）抛出以便调用者处理
-            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+            const nodeError = error;
+            if (nodeError.code === 'ENOENT' || nodeError.code === 'EISDIR') {
                 return null;
             }
             throw error;
@@ -64,7 +65,8 @@ class FileStore {
             return await (0, promises_1.readFile)(fullPath, 'utf-8');
         }
         catch (error) {
-            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+            const nodeError = error;
+            if (nodeError.code === 'ENOENT' || nodeError.code === 'EISDIR') {
                 return null;
             }
             throw error;
@@ -126,7 +128,8 @@ class FileStore {
             return JSON.parse(content);
         }
         catch (error) {
-            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+            const nodeError = error;
+            if (nodeError.code === 'ENOENT' || nodeError.code === 'EISDIR') {
                 return null;
             }
             throw error;

package/dist/types/index.d.ts

@@ -267,3 +267,47 @@ export interface ResearchSession {
     createdAt: string;
     completedAt?: string;
 }
+/** 问题类型 */
+export type ProblemType = 'task_failure' | 'project_bug' | 'system_bug' | 'environment';
+/** 诊断报告 */
+export interface DiagnosisReport {
+    id: string;
+    problemType: ProblemType;
+    trigger: 'explicit' | 'auto';
+    description: string;
+    errorInfo?: {
+        message: string;
+        stack?: string;
+        timestamp: string;
+    };
+    relatedTaskId?: string;
+    relatedFiles?: string[];
+    rootCause: string;
+    impactScope: string[];
+    suggestedFix: string;
+    diagnosedAt: string;
+    diagnosisDuration?: number;
+}
+/** 调试会话状态 */
+export type DebugStatus = 'initialized' | 'diagnosing' | 'awaiting_fix' | 'fixing' | 'verifying' | 'completed' | 'cancelled';
+/** 调试会话 */
+export interface DebugSession {
+    id: string;
+    status: DebugStatus;
+    report: DiagnosisReport;
+    fixDecision?: 'approve' | 'skip' | 'manual';
+    fixResult?: {
+        success: boolean;
+        operations: string[];
+        modifiedFiles: string[];
+        output: string;
+    };
+    verifyResult?: {
+        passed: boolean;
+        details: string;
+    };
+    retryCount: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}

package/dist/utils/logger.d.ts

@@ -42,10 +42,10 @@ export declare function initLoggerWithRunId(runId: string, omPath?: string): voi
  * 便捷方法: 直接记录日志
  */
 export declare const logger: {
-    info: (message: string, meta?: any) => winston.Logger;
-    error: (message: string, meta?: any) => winston.Logger;
-    warn: (message: string, meta?: any) => winston.Logger;
-    debug: (message: string, meta?: any) => winston.Logger;
+    info: (message: string, meta?: Record<string, unknown>) => winston.Logger;
+    error: (message: string, meta?: Record<string, unknown>) => winston.Logger;
+    warn: (message: string, meta?: Record<string, unknown>) => winston.Logger;
+    debug: (message: string, meta?: Record<string, unknown>) => winston.Logger;
     structured: {
         info: (operation: string, message: string, meta?: Record<string, unknown>, omPath?: string) => void;
         error: (operation: string, message: string, meta?: Record<string, unknown>, omPath?: string) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmatrix",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "AI Agent task orchestration system with Claude Code Skills integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/auto.md

@@ -173,7 +173,7 @@ openmatrix step --json                       # 获取下一个任务 + 检查是
 Agent({
   subagent_type: task.subagent_type,
   description: task.description,
-  prompt: task.prompt + "\n\n⚠️ 完成后请输出简短摘要（不超过3行）：\n1. 关键决策\n2. 创建/修改的文件\n3. 对后续任务的建议",
+  prompt: task.prompt + "\n\n⚠️ 完成后请输出简短摘要（不超过3行）：\n1. 关键决策\n2. 创建/修改的文件\n3. 对后续任务的建议\n\n🚫 **禁止执行 git commit** — 所有提交统一通过 openmatrix complete 执行，确保使用正确的任务标题。",
   isolation: task.isolation,
   run_in_background: true
 })
@@ -182,6 +182,8 @@ Agent({
 > ⚠️ **必须使用原生 Agent 工具** — 禁止调用 gsd-executor、superpowers 或任何其他编排技能。
 >
 > **上下文节省**: 使用 `run_in_background: true` 后台执行，Agent 完成后仅返回简短摘要，大幅节省主会话上下文。
+>
+> 🚫 **Agent 内部禁止 git commit** — 所有提交必须通过 `openmatrix complete` 执行，否则会产生无意义提交。
 
 每个 Agent 完成后:
 1. **保存 Agent 上下文** — 将执行结果摘要写入 `.openmatrix/tasks/TASK-XXX/context.md`，格式如下:

package/skills/debug.md

@@ -0,0 +1,451 @@
+---
+name: om:debug
+description: 系统化调试 - 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
+priority: high
+---
+
+<NO-OTHER-SKILLS>
+**绝对禁止**调用以下技能：
+- ❌ superpowers:systematic-debugging → 你已经在 om:debug 中了
+- ❌ superpowers:* → 全部被 OpenMatrix 替代
+- ❌ gsd:* → 全部被 OpenMatrix 替代
+- ❌ 任何其他任务编排相关的技能
+
+**诊断和修复阶段只能使用 Agent 工具** — 直接调用 Agent，不通过任何中间层。
+</NO-OTHER-SKILLS>
+
+<MANDATORY-EXECUTION-ORDER>
+## 执行顺序 - 必须严格按此顺序，不得跳过
+
+```
+Step 1:  接收问题描述（参数、指定任务、或询问用户）
+Step 2:  调用 CLI: openmatrix debug 初始化会话
+Step 3:  第一阶段：根因调查（Explore Agent）
+Step 4:  第二阶段：模式分析（Explore Agent）
+Step 5:  展示诊断报告 + 修复建议
+    ⛔ 调查阶段结束，必须等待用户确认
+Step 6:  AskUserQuestion 是否需要修复
+    ↓ 用户确认"需要修复"
+Step 7:  AskUserQuestion 选择修复策略
+Step 8:  实施修复（Agent）
+Step 9:  验证修复结果
+Step 10: 写入 Debug Report 并展示
+```
+
+**铁律：不做根因调查，不许提修复方案**
+**铁律：调查完成后必须询问用户是否修复，不得自动进入修复流程**
+</MANDATORY-EXECUTION-ORDER>
+
+<objective>
+系统化调试 - 通过四阶段流程诊断和修复问题。不依赖任务流程，可独立使用。
+</objective>
+
+<process>
+
+## Step 1: 接收问题
+
+**检查 `$ARGUMENTS`:**
+
+| 参数 | 处理方式 |
+|------|---------|
+| `--task TASK-XXX` | 读取指定失败任务 |
+| `<问题描述>` | 直接使用描述 |
+| 空 | 询问用户问题描述 |
+
+**如果是空参数，询问：**
+
+AskUserQuestion: `header: "问题描述"`, `multiSelect: false`
+**question:** 请描述你遇到的问题
+
+| label | description |
+|-------|-------------|
+| 描述问题 | 输入自由文本描述 |
+| 选择失败任务 | 从当前失败任务中选择 |
+| 取消 | 退出调试模式 |
+
+**如果有失败任务（检查 .openmatrix/state.json）：**
+```bash
+cat .openmatrix/state.json 2>/dev/null | grep -o '"failed":[0-9]*'
+```
+如果 `statistics.failed > 0`，读取 `.openmatrix/tasks/` 目录找到 failed 任务并展示。
+
+## Step 2: 调用 CLI 初始化
+
+**带任务 ID：**
+```bash
+openmatrix debug --task TASK-XXX --json
+```
+
+**带描述：**
+```bash
+openmatrix debug "问题描述" --json
+```
+
+CLI 返回：
+```json
+{
+  "sessionId": "DEBUG-xxx",
+  "status": "diagnosing",
+  "problemType": "task_failure",
+  "report": {
+    "description": "...",
+    "relatedTaskId": "TASK-003",
+    "relatedFiles": ["src/xxx.ts"]
+  }
+}
+```
+
+从返回结果中读取 `sessionId`，后续步骤使用此 ID。
+
+## Step 3: 第一阶段 - 根因调查
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "根因调查 - 第一阶段",
+  prompt: `你是调试专家。正在进行系统化调试的第一阶段：根因调查。
+
+**铁律：在找到根因之前，不要提出任何修复方案。**
+
+## 问题信息
+- 问题类型: ${problemType}
+- 问题描述: ${description}
+${relatedTaskId ? `- 关联任务: ${relatedTaskId}` : ''}
+
+## 任务
+1. 仔细阅读所有错误信息（不要跳过任何警告或错误）
+2. 收集相关文件和日志
+3. 检查近期代码变更（git diff、最近提交）
+4. 如果有多个组件，追踪数据流，找到断裂点
+5. 定位问题根源
+
+## 输出格式
+请按以下格式输出：
+
+### 错误信息
+- 错误类型: ...
+- 错误位置: 文件:行号
+- 错误详情: ...
+
+### 复现步骤
+1. ...
+
+### 近期变更
+- 提交1: 描述
+- 提交2: 描述
+
+### 根因分析
+[详细描述问题根源]
+
+### 影响范围
+- 文件1
+- 文件2
+
+## 禁止行为
+❌ 提出修复方案
+❌ 修改任何文件
+❌ 做出未经证实的假设`,
+  run_in_background: false
+})
+```
+
+## Step 4: 第二阶段 - 模式分析
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "模式分析 - 第二阶段",
+  prompt: `继续进行系统化调试的第二阶段：模式分析。
+
+## 第一阶段发现
+
+${第一阶段根因调查的完整输出}
+
+## 任务
+1. 在代码库中找到类似的、正常工作的代码
+2. 对比正常代码和异常代码的差异
+3. 列出所有差异点（无论多小）
+4. 理解功能依赖关系和隐含假设
+
+## 输出格式
+
+### 正常示例
+- 文件: path:line
+- 说明: 为什么这段代码能正常工作
+
+### 差异点
+1. 差异1: 正常代码 vs 异常代码
+2. 差异2: ...
+
+### 依赖关系
+- 需要哪些前置条件
+- 有哪些隐含假设`,
+  run_in_background: false
+})
+```
+
+## Step 5: 展示诊断报告
+
+**第一阶段和第二阶段完成后，展示诊断报告：**
+
+```
+🔍 诊断报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+问题类型: xxx
+
+根因分析
+  [来自第一阶段调查的根因描述]
+
+正常示例
+  文件: path:line
+  说明: ...
+
+差异点
+  1. ...
+  2. ...
+
+影响范围
+  - 文件1
+  - 文件2
+
+修复建议
+  [基于差异分析的具体修复建议]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 6: 确认是否修复
+
+**⛔ 调查阶段结束，必须在此暂停等待用户确认。不得跳过此步骤自动进入修复。**
+
+AskUserQuestion: `header: "是否修复"`, `multiSelect: false`
+**question:** 调查已完成，是否需要修复？
+
+| label | description |
+|-------|-------------|
+| 需要修复 | 选择修复策略并执行 |
+| 仅查看报告 | 不修复，仅输出诊断报告后结束 |
+| 继续深入调查 | 根因不够清晰，继续调查 |
+
+**用户选择 "继续深入调查"** → 回到 Step 3，带着新信息重新调查。
+**用户选择 "仅查看报告"** → 跳到 Step 10，输出诊断报告后结束。
+
+## Step 7: 选择修复策略
+
+**仅在用户选择"需要修复"后执行此步骤。**
+
+AskUserQuestion: `header: "修复策略"`, `multiSelect: false`
+**question:** 选择修复策略？
+
+| label | description |
+|-------|-------------|
+| 自动修复 (推荐) | 调用 Agent 执行修复 |
+| 手动修复 | 仅展示具体修复建议，用户自行修改 |
+
+## Step 8: 实施修复
+
+**如果用户选择自动修复：**
+
+**修复前安全检查（必须执行）：**
+```bash
+git status --porcelain
+git log --oneline -5
+```
+
+```typescript
+Agent({
+  subagent_type: "general-purpose",
+  description: "实施 bug 修复",
+  prompt: `根据诊断报告执行修复。
+
+## 铁律
+1. 只实施单一修复（不要做额外改动）
+2. 每次只改一个变量
+3. 不在诊断不清的情况下盲目尝试
+4. 不做"顺便"的重构
+
+## 诊断报告
+${诊断报告全文}
+
+## 修复建议
+${suggestedFix}
+
+## 任务
+1. 根据修复建议实施修改
+2. 确保修改范围最小化
+3. 完成后输出修改了哪些文件和具体改动
+
+## 禁止行为
+❌ 修改与修复无关的文件
+❌ 进行额外的重构
+❌ 同时修复多个问题`,
+  run_in_background: false
+})
+```
+
+**Agent 完成后：**
+1. 检查 Git 状态
+2. 提交修复（如果文件有变更）
+3. 进入 Step 9 验证
+
+## Step 9: 验证修复
+
+**根据问题类型选择验证方式：**
+
+| 问题类型 | 验证方式 |
+|---------|---------|
+| task_failure | 重新运行失败任务或相关测试 |
+| project_bug | 运行相关测试或构建 |
+| system_bug | 验证 CLI 功能 |
+| environment | 检查依赖安装状态 |
+
+**任务失败：**
+```bash
+# 运行相关测试
+npm test -- --run 2>&1 | tail -20
+```
+
+**项目 bug：**
+```bash
+npm run build 2>&1 | tail -10
+```
+
+**环境：**
+```bash
+npm ls --depth=0 2>&1 | tail -20
+```
+
+**验证结果判断：**
+- 测试全通过 / 构建成功 → 验证通过
+- 仍有失败 / 构建失败 → 验证未通过
+
+AskUserQuestion: `header: "验证结果"`, `multiSelect: false`
+**question:** 修复验证通过了吗？
+
+| label | description |
+|-------|-------------|
+| 通过 | 修复成功，记录报告 |
+| 未通过 | 修复未生效，重新分析 |
+| 部分通过 | 部分修复，继续诊断 |
+
+**如果验证未通过：**
+- 重试计数 +1
+- **< 3 次** → 回到 Step 3（带着新信息重新分析）
+- **>= 3 次** → 输出"已尝试 3 次以上修复，建议暂停并质疑架构"，进入 Step 10
+
+## Step 10: 写入 Debug Report
+
+完成调试会话：
+```bash
+openmatrix debug --list
+```
+
+**生成诊断报告文件（在界面输出）：**
+
+```markdown
+# Debug Report
+
+**会话 ID**: ${sessionId}
+**日期**: ${timestamp}
+**状态**: ${status}
+
+## 问题描述
+${description}
+
+## 问题类型
+${problemType}
+
+## 诊断结果
+### 根因
+${rootCause}
+
+### 影响范围
+${impactScope}
+
+## 修复操作
+${operations}
+
+## 验证结果
+${verifyResult}
+
+## 经验教训
+${lessons}
+```
+
+**Git 提交修复（如果有文件变更）：**
+```bash
+git status --porcelain
+# 如果有未提交文件：
+git add -A && git commit -m "$(cat <<'EOF'
+fix: 修复 bug - 问题描述
+
+根因: ...
+修复: ...
+
+影响范围: ...
+文件改动: ...
+
+Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix
+EOF
+)"
+```
+
+</process>
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+<examples>
+/om:debug                          # 交互式调试
+/om:debug --task TASK-003          # 调试指定失败任务
+/om:debug "API 返回 500 错误"      # 带问题描述调试
+</examples>
+
+<notes>
+## 四阶段流程
+
+```
+Step 1: 接收问题
+    ↓
+Step 2: CLI 初始化会话
+    ↓
+Step 3: 第一阶段 - 根因调查（只读）
+    ↓
+Step 4: 第二阶段 - 模式分析（只读）
+    ↓
+Step 5: 展示诊断报告 + 修复建议
+    ↓
+    ⛔ 调查阶段结束 — 必须等待用户确认
+    ↓
+Step 6: AskUserQuestion 是否需要修复
+    ├─ "仅查看报告" → Step 10 输出报告
+    ├─ "继续深入调查" → 回到 Step 3
+    └─ "需要修复" ↓
+Step 7: AskUserQuestion 选择修复策略
+    ↓
+Step 8: 实施修复
+    ↓
+Step 9: 验证修复结果
+    ├─ 未通过 (< 3次) → 回到 Step 3
+    ├─ 未通过 (>= 3次) → Step 10
+    └─ 通过 ↓
+Step 10: 写入 Debug Report
+```
+
+## 铁律
+
+**不做根因调查，不许提修复方案**
+
+## 红线
+
+- 3 次修复失败 → 暂停，质疑架构
+- 不修改未关联的文件
+- 单一修复原则
+- 修复前必须有验证方法
+</notes>

package/skills/om.md

@@ -82,6 +82,7 @@ OpenMatrix 默认入口 — 用户无需记忆命令，直接描述任务即可
      /om:status      - View status
      /om:meeting     - Handle blockers
      /om:report      - Generate report
+     /om:debug       - Systematic debugging (bug/error investigation)
    ```
 </process>
 
@@ -99,5 +100,5 @@ $ARGUMENTS
 
 <notes>
 `/om` is shorthand for the OpenMatrix workflow. Same skill set as `openmatrix`, shorter invocation.
-Available commands: `/om:brainstorm`, `/om:start`, `/om:auto`, `/om:status`, `/om:meeting`, `/om:report`, `/om:resume`, `/om:retry`, `/om:research`, `/om:approve`, `/om:check`
+Available commands: `/om:brainstorm`, `/om:start`, `/om:auto`, `/om:status`, `/om:meeting`, `/om:report`, `/om:resume`, `/om:retry`, `/om:research`, `/om:approve`, `/om:check`, `/om:debug`
 </notes>

package/skills/start.md

@@ -23,6 +23,7 @@ description: "Use when starting a new development task cycle with interactive qu
 Step 1:  初始化 .openmatrix 目录
 Step 2:  解析任务输入（文件或描述）
 Step 3:  智能分析任务类型（开发/非开发）
+Step 3.5: 提交文档（git add docs/ + 所有 .md 文件, commit）
 Step 4:  必选问题（开发任务:质量+E2E+模式; 非开发:仅模式）← 不可跳过
 Step 5:  可选问题（仅复杂开发任务）+ 展示执行计划
 Step 6:  AI 提取 goals，生成 plan
@@ -141,6 +142,41 @@ cat .openmatrix/research/context.json 2>/dev/null || echo "NO_RESEARCH"
 
 ---
 
+### Step 3.5: 提交文档（必须执行，不可跳过）
+
+在开始任何新任务之前，先提交所有已变更的文档文件，确保文档和代码同步提交。
+
+```bash
+git status --porcelain
+```
+
+检查是否有文档变更（包括 `docs/` 目录、所有 `.md` 文件、`.openmatrix/` 下的文档）：
+
+```bash
+git diff --name-only | grep -E '\.md$|^docs/' 2>/dev/null
+git ls-files --others --exclude-standard | grep -E '\.md$|^docs/' 2>/dev/null
+```
+
+如果有文档变更（未追踪或未提交），执行提交：
+
+```bash
+git add docs/ .openmatrix/*.md CLAUDE.md README.md README_EN.md
+git commit -m "$(cat <<'EOF'
+docs: 更新项目文档
+
+更新内容: ...
+
+Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix
+EOF
+)"
+```
+
+**如果没有文档变更，跳过此步骤继续。**
+
+> ⚠️ **此步骤不可跳过** — 避免"代码提交了但文档没提交"的情况。
+
+---
+
 ### Step 4: 必选问题（不可跳过，不可使用默认值，必须通过 AskUserQuestion 让用户选择）
 
 根据 `goalTypes` 字段判断需要询问哪些问题：
@@ -359,7 +395,7 @@ openmatrix step --json                       # 获取下一个任务 + 检查是
 Agent({
   subagent_type: task.subagent_type,
   description: task.description,
-  prompt: task.prompt + "\n\n⚠️ 完成后请输出简短摘要（不超过3行）：\n1. 关键决策\n2. 创建/修改的文件\n3. 对后续任务的建议",
+  prompt: task.prompt + "\n\n⚠️ 完成后请输出简短摘要（不超过3行）：\n1. 关键决策\n2. 创建/修改的文件\n3. 对后续任务的建议\n\n🚫 **禁止执行 git commit** — 所有提交统一通过 openmatrix complete 执行，确保使用正确的任务标题。",
   isolation: task.isolation,
   run_in_background: true
 })
@@ -368,6 +404,8 @@ Agent({
 > ⚠️ **必须使用原生 Agent 工具** — 禁止调用 gsd-executor、superpowers 或任何其他编排技能。
 >
 > **上下文节省**: 使用 `run_in_background: true` 后台执行，Agent 完成后仅返回简短摘要，不返回完整输出，大幅节省主会话上下文。
+>
+> 🚫 **Agent 内部禁止 git commit** — 所有提交必须通过 `openmatrix complete` 执行，否则会产生 "Test Task" 等无意义提交。
 
 每个 Agent 完成后（收到后台完成通知时）:
 1. **标记完成并更新统计（必须执行）:**
@@ -508,7 +546,7 @@ $ARGUMENTS
 ## 执行流程
 
 ```
-Step 1-5: 初始化 + 问答 + 确认 → Step 6: 提取 goals + plan → Step 7: 写入 tasks-input.json
+Step 1-3: 初始化 + 解析输入 + 分析类型 → Step 3.5: 提交文档 → Step 4-5: 问答 + 确认 → Step 6: 提取 goals + plan → Step 7: 写入 tasks-input.json
 → Step 8: openmatrix start --tasks-json (必须) → Step 9: 读取 subagentTasks
 → Step 10: Agent 逐个执行 (只有这里写代码)
 ```