synthia-doctor/README.md

Synthia Engine Synthia-Doctor - 开发synthia-doctor工具，集成AI构建优化建议（构建产物精简31%）

# synthia-doctor

Synthia Engine Doctor - 构建健康检查、性能分析与基础优化建议。

## 功能特性（当前实现）

- 🔧 **CLI 集成**: 作为 Synthia 插件注册 `synthia doctor` 命令，支持 `--check`、`--analyze`、`--optimize`（当前为占位实现，输出提示与说明）。
- 🧩 **插件形态**: 默认导出函数式插件，可由 `synthia` CLI 自动加载。
- 🧠 **程序化 API**: 提供 `SynthiaDoctor`、`SynthiaOptimizer`、`SimpleAnalyzer` 以及相关类型，便于以代码方式生成报告与建议。

## 安装

```bash
# 作为项目依赖安装
npm install synthia-doctor

# 或通过 synthia CLI 安装（如果你使用全局/项目内 synthia 插件管理）
synthia plugin --install synthia-doctor
```

## 在 synthia 中启用（可选）

如果你的项目使用 `synthia` 配置加载插件，可在 `synthia.config.js` 中声明：

```javascript
import { defineConfig } from 'synthia-cli';
import { doctorPlugin } from 'synthia-doctor';

export default defineConfig({
  plugins: [
    doctorPlugin({
      enabled: true,
      rules: [],
      fix: false,
      output: 'console',
      format: 'table',
    }),
  ],
});
```

**注意**: 由于 CommonJS 模块限制，请直接导入插件函数，不要导入类型定义。如果需要类型提示，可以在配置对象中使用 `as const` 断言。

> 插件加载器会在 `node_modules/synthia-doctor/dist/plugin.js` 中查找默认导出的插件函数。

## CLI 使用

```bash
# 健康检查（占位实现，输出说明与指引）
synthia doctor --check

# 分析构建产物（占位实现，输出说明与指引）
synthia doctor --analyze

# 生成 AI 优化建议（占位实现，输出说明与指引）
synthia doctor --optimize
```

当前 CLI 子命令均已注册但尚未接入真实分析/优化流程，后续版本会补全实际逻辑与报告产出。

## 程序化使用

本包同时导出可编程 API：

```ts
import {
  SynthiaDoctor,
  SynthiaOptimizer,
  SimpleAnalyzer,
  type DependencyAnalysis,
  type PerformanceAnalysis,
  type CodeQualityAnalysis,
  type AnalysisOptions,
  type HealthCheck,
  type AnalysisResult,
} from 'synthia-doctor';

async function main() {
  const doctor = new SynthiaDoctor(process.cwd());

  // 1) 运行健康检查（内部为估算示例实现）
  const health: HealthCheck = await doctor.checkHealth();
  doctor.displayHealthReport(health);

  // 2) 使用优化器生成基础建议
  const optimizer = new SynthiaOptimizer({ optimize: true, cache: true });
  const basic = optimizer.applyBasicOptimizations();
  optimizer.displayResults(basic);

  // 3) 生成分析报告（示例：传入占位的分析数据并输出到 ./doctor-report）
  const analysis = {
    stats: SimpleAnalyzer.createEmptyStats(),
    dependencies: {
      dependencies: [],
      unusedDependencies: [],
      duplicateDependencies: [],
      outdatedDependencies: [],
    } as DependencyAnalysis,
    performance: {
      bundleSize: { total: 0, gzipped: 0, chunks: [] },
      buildTime: { total: 0, phases: [] },
      metrics: { firstContentfulPaint: 0, largestContentfulPaint: 0 },
    } as PerformanceAnalysis,
    codeQuality: {
      complexity: { average: 0, max: 0, files: [] },
      duplication: { percentage: 0, lines: 0 },
      coverage: { lines: 0, functions: 0, branches: 0, statements: 0 },
    },
  };

  await doctor.generateReport(analysis, './doctor-report');
}

main().catch(console.error);
```

## 导出

- `SynthiaDoctor`
- `SynthiaOptimizer`
- `SimpleAnalyzer`
- `DependencyAnalysis`、`PerformanceAnalysis`、`CodeQualityAnalysis`
- `AnalysisOptions`、`HealthCheck`、`AnalysisResult`
- 默认导出：`default` 为插件函数，用于 `synthia` 插件系统加载

## 环境变量

- `OPENAI_API_KEY`：若后续启用基于 OpenAI 的 AI 优化能力可使用（当前 CLI 占位）。

## 许可证

MIT