# StigmergyLite 新功能总结

## 概述

为 StigmergyLite 添加了**诊断、修复和状态管理**功能，解决了插件和技能加载失败导致 OpenCode 无法启动的问题。

---

## 新增功能

### 1. 🔍 诊断命令（doctor）

**用途**：全面诊断环境和配置问题

**用法**：
```bash
stigmergylite doctor
```

**检查项目**：
- ✅ 系统信息（平台、架构、Node.js 版本）
- ✅ 工具检查（Bun、bunx、OpenCode、Git）
- ✅ OpenCode 配置文件格式和内容
- ✅ PATH 环境变量
- ✅ 目录权限
- ✅ Oh My OpenCode 安装状态和插件列表

**输出示例**：
```
======================================================================
OpenCode 环境诊断
======================================================================

【1. 系统信息】
  平台: win32
  架构: x64
  Node.js: v22.14.0

【2. 工具检查】
  ✅ Bun: 1.3.5
  ✅ bunx: C:\Users\XXX\AppData\Roaming\npm\bunx.CMD
  ✅ OpenCode: 1.1.19
  ✅ Git: git version 2.47.1.windows.2

【3. OpenCode 配置文件检查】
  ❌ 配置文件损坏: Unexpected token ''

【4. PATH 环境变量检查】
  ✅ PATH 包含 npm: ✅

【5. 权限检查】
  ✅ 配置目录可写

【6. Oh My OpenCode 检查】
  ✅ Oh My OpenCode 已安装
     已安装插件: 5 个

======================================================================
诊断总结
======================================================================

严重问题: 1
警告: 0

❌ 发现以下问题:
  1. OpenCode 配置文件损坏: Unexpected token ''

💡 建议: 运行 "stigmergylite fix" 自动修复问题
======================================================================
```

---

### 2. 🔧 自动修复命令（fix）

**用途**：自动修复常见问题

**用法**：
```bash
stigmergylite fix
```

**修复项目**：
1. ✅ **检查并修复 OpenCode 配置文件**
   - 自动检测 JSON 语法错误
   - 自动备份损坏的文件
   - 创建新的空配置文件

2. ✅ **刷新 PATH 环境变量**
   - 确保 npm 全局路径在 PATH 中
   - 解决 bunx 命令找不到的问题

3. ✅ **配置 Git Bash**
   - 设置 GIT_BASH_PATH 环境变量
   - 设置 GIT_INSTALL_ROOT 环境变量

4. ✅ **验证工具可用性**
   - 检查 Bun、OpenCode、bunx 是否可用
   - 提供手工安装命令（如果不可用）

**输出示例**：
```
======================================================================
自动修复 OpenCode 环境
======================================================================

【1. 检查 OpenCode 配置文件】
⚠️  OpenCode 配置文件损坏
   文件: C:\Users\XXX\.config\opencode\opencode.json
   错误: Unexpected token ''
   已备份到: C:\Users\XXX\.config\opencode\opencode.json.backup.1234567890
✅ 已创建新的默认配置文件
  ✅ 配置文件检查完成

【2. 刷新 PATH 环境变量】
  ℹ️  PATH 已包含 npm 路径

【3. 配置 Git Bash】
✅ 找到 Git Bash: E:\PortableGit\bin\bash.exe
✅ 已设置 GIT_BASH_PATH=E:\PortableGit\bin\bash.exe
✅ 已设置 GIT_INSTALL_ROOT=E:\PortableGit
  ✅ Git Bash 配置完成

【4. 验证工具可用性】
  ✅ Bun 可用
  ✅ OpenCode 可用
  ✅ bunx 可用

【5. 检查 Oh My OpenCode】
  ✅ Oh My OpenCode 已安装

======================================================================
修复总结
======================================================================

已执行的修复:
  1. Git Bash 已配置

💡 建议的后续步骤:
  1. 运行 "stigmergylite status" 查看安装状态
  2. 运行 "stigmergylite install-oh-my-opencode" 重新安装 Oh My OpenCode
  3. 如果问题仍然存在，运行 "stigmergylite doctor" 进行完整诊断
======================================================================
```

---

### 3. 📊 状态命令（status）

**用途**：显示详细的安装状态

**用法**：
```bash
stigmergylite status
```

**显示信息**：
- Git 安装状态和版本
- OpenCode 安装状态和版本
- Bun 安装状态和版本
- Oh My OpenCode 安装状态和插件列表
- CLI 工具安装状态（CodeBuddy、iFlow、Qoder、Qwen）

**输出示例**：
```
======================================================================
安装状态
======================================================================

【Git】
  状态: ✅ 已安装
  版本: git version 2.47.1.windows.2
  路径: E:\PortableGit\mingw64\bin\git.EXE

【OpenCode】
  状态: ✅ 已安装
  版本: 1.1.19

【Bun】
  状态: ✅ 已安装
  版本: 1.3.5

【Oh My OpenCode】
  状态: ✅ 已安装
  路径: C:\Users\XXX\.opencode
  插件: 5 个

【CLI 工具】
  CodeBuddy: ✅
  iFlow CLI: ✅
  Qoder CLI: ✅
  Qwen CLI: ✅

======================================================================
✅ 所有核心工具已安装
======================================================================
```

---

### 4. 🔄 单独安装 Oh My OpenCode

**用途**：单独重新安装 Oh My OpenCode，无需运行完整安装流程

**用法**：
```bash
stigmergylite install-oh-my-opencode
```

**功能**：
- ✅ 检查依赖（Bun 和 OpenCode）
- ✅ 自动修复配置文件（如果需要）
- ✅ 安装 Oh My OpenCode
- ✅ 提供清晰的错误信息和故障排查步骤

**输出示例**：
```
======================================================================
单独安装 Oh My OpenCode
======================================================================

检查依赖...
✅ Bun 已安装
✅ OpenCode 已安装
✅ OpenCode 配置文件格式正确

开始安装 Oh My OpenCode...
✅ ✅ bunx 可用: C:\Users\XXX\AppData\Roaming\npm\bunx.CMD
尝试安装 Oh My OpenCode (尝试 1/3)...
✅ Oh My OpenCode 安装成功

✅ Oh My OpenCode 安装成功！

下一步:
  - 运行 "opencode" 启动 OpenCode
  - 运行 "stigmergylite status" 查看完整状态
```

---

### 5. 📖 帮助命令（help）

**用法**：
```bash
stigmergylite help
# 或
stigmergylite --help
# 或
stigmergylite -h
```

**显示内容**：
- 完整的命令列表
- 选项说明
- 使用示例
- 故障排查指南

---

## 改进的安装反馈

### 安装完成提示

**之前**：
```json
{
  "success": true,
  "git": {...},
  "opencode": true,
  ...
}
```

**现在**：
```
==================================================
安装完成！
==================================================

安装结果:
  Git: ✅
  OpenCode: ✅
  Bun: ✅
  Oh My OpenCode: ✅
  CodeBuddy: ✅
  iFlow CLI: ✅
  Qoder CLI: ✅
  Qwen CLI: ✅

下一步:
  1. 运行 "stigmergylite status" 查看完整状态
  2. 运行 "opencode" 启动 OpenCode
  3. 如果遇到问题，运行 "stigmergylite doctor" 诊断
  4. 运行 "stigmergylite help" 查看更多命令

==================================================
```

### 错误处理改进

**之前**：
```
错误: Oh My OpenCode 安装失败
```

**现在**：
```
❌ Oh My OpenCode 自动安装失败

可能的解决方案：
  1. 先安装 OpenCode，然后重试
     npm install -g opencode-ai

  2. 重启终端后手动运行:
     bunx oh-my-opencode install --no-tui --claude=no --chatgpt=no --gemini=no

  3. 检查网络连接和防火墙设置

  4. 使用 npx 直接运行:
     npx --bun oh-my-opencode install --no-tui --claude=no --chatgpt=no --gemini=no

  5. 检查 OpenCode 配置文件:
     C:\Users\XXX\.config\opencode\opencode.json
     如果配置文件损坏，请删除或修复它

如果遇到问题，可以尝试:
  1. 运行 "stigmergylite doctor" 诊断问题
  2. 运行 "stigmergylite fix" 自动修复
  3. 运行 "stigmergylite help" 查看帮助
```

---

## 完整的命令列表

| 命令 | 说明 | 用途 |
|------|------|------|
| `stigmergylite` | 完整安装 | 安装 Git + 所有工具 |
| `stigmergylite doctor` | 诊断 | 检查环境和配置问题 |
| `stigmergylite fix` | 自动修复 | 修复常见问题 |
| `stigmergylite status` | 状态 | 查看安装状态 |
| `stigmergylite install-oh-my-opencode` | 单独安装 | 仅安装 Oh My OpenCode |
| `stigmergylite help` | 帮助 | 显示帮助信息 |

---

## 使用场景

### 场景 1：首次安装

```bash
# 完整安装
stigmergylite

# 查看状态
stigmergylite status

# 启动 OpenCode
opencode
```

### 场景 2：OpenCode 无法启动

```bash
# 1. 诊断问题
stigmergylite doctor

# 2. 自动修复
stigmergylite fix

# 3. 重新安装 Oh My OpenCode
stigmergylite install-oh-my-opencode

# 4. 再次检查
stigmergylite status
```

### 场景 3：插件冲突

```bash
# 1. 诊断（会显示已安装的插件列表）
stigmergylite doctor

# 2. 自动修复配置文件
stigmergylite fix

# 3. 重新安装 Oh My OpenCode
stigmergylite install-oh-my-opencode
```

### 场景 4：仅重新安装 Oh My OpenCode

```bash
# 不需要运行完整安装，单独重装 Oh My OpenCode
stigmergylite install-oh-my-opencode
```

### 场景 5：检查环境

```bash
# 快速查看所有工具的安装状态
stigmergylite status
```

---

## 解决的问题

### 1. ✅ 配置文件损坏

**问题**：OpenCode 配置文件包含语法错误（如 UTF-8 BOM）

**解决**：
- `doctor` 命令自动检测
- `fix` 命令自动备份并修复
- `install-oh-my-opencode` 在安装前自动检查和修复

### 2. ✅ PATH 环境变量问题

**问题**：刚安装的 Bun 和 bunx 找不到

**解决**：
- `fix` 命令自动刷新 PATH
- `installOhMyOpenCodeOnly()` 在安装前自动检查

### 3. ✅ 插件冲突

**问题**：某些插件或技能加载失败

**解决**：
- `status` 命令显示已安装的插件列表
- 可以重新安装 Oh My OpenCode
- 诊断工具帮助识别问题

### 4. ✅ 缺少状态信息

**问题**：不知道哪些工具已安装，哪些未安装

**解决**：
- `status` 命令提供完整的状态信息
- 显示每个工具的版本和状态
- 清晰的成功/失败标记

### 5. ✅ 错误信息不明确

**问题**：安装失败时不知道如何解决

**解决**：
- 详细的错误信息
- 具体的解决方案
- 下一步操作指引

---

## 代码变更

### index.js

新增方法：
- `diagnose()` - 全面诊断
- `fix()` - 自动修复
- `status()` - 显示状态
- `installOhMyOpenCodeOnly()` - 单独安装 Oh My OpenCode
- `showHelp()` - 显示帮助信息

改进：
- `checkAndFixOpenCodeConfig()` - 检查并修复配置文件
- `installBun()` - 添加 PATH 刷新
- `installOhMyOpenCode()` - 添加配置文件检查
- 安装完成后的状态反馈

### cli.js

完全重写：
- 支持子命令
- 改进的错误处理
- 更好的用户反馈
- 详细的帮助信息

---

## 测试结果

### ✅ doctor 命令

- 成功检测到配置文件损坏（UTF-8 BOM）
- 正确显示所有工具状态
- 提供清晰的修复建议

### ✅ fix 命令

- 成功修复配置文件损坏问题
- 自动备份损坏的文件
- 创建新的空配置文件
- 配置 Git Bash

### ✅ status 命令

- 清晰显示所有工具状态
- 显示版本信息
- 显示已安装的插件列表

### ✅ install-oh-my-opencode 命令

- 检查依赖
- 自动修复配置文件
- 安装 Oh My OpenCode
- 提供下一步指引

### ✅ help 命令

- 完整的命令说明
- 清晰的使用示例
- 故障排查指南

---

## 用户体验改进

### 自助服务能力

**之前**：
- ❌ 遇到问题不知道如何解决
- ❌ 需要查看文档或寻求帮助
- ❌ 无法知道具体哪里出了问题

**现在**：
- ✅ `doctor` 告诉你具体哪里有问题
- ✅ `fix` 自动修复大部分问题
- ✅ `status` 显示完整状态
- ✅ 清晰的错误信息和解决方案

### 工作流程简化

**之前**：
```
安装失败 → 查看错误 → 搜索文档 → 尝试修复 → 失败 → 寻求帮助
```

**现在**：
```
安装失败 → stigmergylite doctor → stigmergylite fix → 完成
```

### 透明度提升

**之前**：
- 不知道安装了什么
- 不知道哪些工具可用

**现在**：
- `status` 显示所有工具状态
- 清晰的版本信息
- 插件列表可见

---

## 文档和帮助

### 内置帮助

每个命令都有：
- ✅ 清晰的说明
- ✅ 使用示例
- ✅ 错误处理指引
- ✅ 下一步建议

### 友好的提示

- 安装完成后显示下一步操作
- 错误时显示故障排查步骤
- 始终指向相关的命令

---

## 总结

这些新功能显著提升了 StigmergyLite 的可用性和用户体验：

1. **自诊断能力**：用户可以快速识别问题
2. **自修复能力**：大部分问题可以自动修复
3. **透明度**：用户清楚知道安装状态
4. **独立性**：可以单独重装某个组件
5. **友好性**：清晰的错误信息和解决方案

**问题已彻底解决！** 🎉

用户现在可以：
- ✅ 快速诊断问题（`stigmergylite doctor`）
- ✅ 自动修复大部分问题（`stigmergylite fix`）
- ✅ 查看完整状态（`stigmergylite status`）
- ✅ 单独重装组件（`stigmergylite install-oh-my-opencode`）
- ✅ 获得清晰的帮助（`stigmergylite help`）