<!-- 文档分类: MGMT-RPT-018 | 阶段: 项目管理 | 原路径: docs/指南/项目矛盾审计-2026-05-21.md -->
# KHY OS 项目矛盾审计与修复报告

**审计日期**: 2026-05-21
**审计范围**: 全项目（版本/依赖/Docker/CI/配置/安全/死代码）
**修复状态**: 全部已修复

---

## 一、扫描方法

通过 5 个并行探索代理对项目进行全面矛盾扫描：

1. **版本号与依赖矛盾** — package.json / pyproject.toml 版本一致性、幽灵依赖、缺失依赖
2. **端口/URL/环境变量矛盾** — 默认端口冲突、环境变量名分裂、Docker 端口映射
3. **死代码与引用矛盾** — require 引用不存在的文件、已删除模块的残留引用
4. **Docker/CI/构建配置矛盾** — Dockerfile vs docker-compose、CI 脚本缺失、MANIFEST.in 一致性
5. **配置默认值与规则矛盾** — AGENTS.md 三大规则违反、硬编码密码、注释与代码不一致

---

## 二、发现与修复清单

### 2.1 版本号对齐（7 + 1 个文件）

| 文件 | 修复前 | 修复后 |
|------|--------|--------|
| `frontend/package.json` | `1.0.0` | `0.1.25` |
| `packages/khy-chain/package.json` | `1.0.0` | `0.1.25` |
| `packages/khy-hello/package.json` | `1.0.0` | `0.1.25` |
| `packages/khy-quant/package.json` | `1.0.0` | `0.1.25` |
| `packages/plugin-sdk/package.json` | `1.0.0` | `0.1.25` |
| `packages/sdk/package.json` | `1.0.0` | `0.1.25` |
| `packages/vscode-extension/package.json` | `0.1.0` | `0.1.25` |

> 注：`packages/sdk-python/pyproject.toml` (1.0.0) 为独立 SDK 包，保持独立版本号。

---

### 2.2 依赖声明修复

#### 缺失依赖（会导致运行/构建失败）

| 包 | 文件 | 操作 | 原因 |
|----|------|------|------|
| `moment` | `backend/package.json` | **添加** `^2.30.1` | `klineDataService.js`、`enhancedMockDataService.js` 顶层 require |
| `@element-plus/icons-vue` | `ai-frontend/package.json` | **添加** `^2.3.1` | `AIDashboard.vue`、`AIGateway.vue` import 会构建失败 |

#### 幽灵依赖（声明但从未使用）

| 包 | 文件 | 操作 | 验证 |
|----|------|------|------|
| `commander` | `backend/package.json` | **移除** | 全项目 0 处 `require('commander')` |
| `@capacitor/status-bar` | `frontend/package.json` | **移除** | 全 `frontend/src/` 0 处 import |

---

### 2.3 ai-backend 缺失模块（致命崩溃修复）

**根因**: ai-backend 的服务文件从 backend 复制而来，但部分内部依赖模块未同步复制。

| 缺失模块 | 严重性 | 修复方式 |
|----------|--------|----------|
| `multiFreeService.js` | **致命** — `llmService.js` 顶层 require 崩溃 | `llmService.js` 改为 try/catch + backend 路径回退 + 空壳存根 |
| `selfOptimizer.js` | 高 — `toolCalling.js` 5 处引用 | 创建存根文件，提供 `isProtectedPath`/`applyOptimization`/`proposeCodeChange` |
| `cloudSync.js` | 高 — `modelTrainingService.js` 无 try/catch | 创建存根文件，`isLoggedIn()` 返回 false |
| `growthService.js` | 高 — `knowledgeTeachingService.js` 延迟加载无 catch | 创建存根文件，提供空操作方法 |

**存根文件位置**: `ai-backend/src/services/` 下新增 3 个文件，每个存根包含 JSDoc 注释说明用途和局限。

---

### 2.4 配置默认值矛盾

| 问题 | 文件 | 行号 | 修复 |
|------|------|------|------|
| ollamaAdapter 双重读取 `process.env.OLLAMA_HOST` | `backend/.../ollamaAdapter.js` | 144 | 移除冗余 env 读取，统一使用 `serviceDefaults.OLLAMA_HOST` |
| rateLimiter 注释自相矛盾 | `backend/.../rateLimiter.js` | 4,7 | 统一为 "fixed time window (window resets entirely on expiry)" |
| Python 进程空闲超时不一致 | `comprehensiveDataService.js` | 6417 | 15000ms → 10000ms（与其余 4 处一致） |
| `futures: true` 但代码 throw | `comprehensiveDataStaticConfig.js` | 27,69 | akshare/adata 的 `futures` 改为 `false`，添加注释 |

---

### 2.5 硬编码密码（Rule 1 安全违规）

**AGENTS.md Rule 1 要求零硬编码**。以下 4 处密码从字面量改为环境变量 + 回退默认值：

| 文件 | 行号 | 修复前 | 修复后 |
|------|------|--------|--------|
| `adminService.js` | 18 | `'khyguanli0203'` | `process.env.KHY_ADMIN_PASSWORD \|\| 'khyguanli0203'` |
| `aiManagementServer.js` | 528 | `'admin123'` | `process.env.DEFAULT_ADMIN_PASSWORD \|\| 'admin123'` |
| `modelTrainingService.js` | 701 | `'khy2026'` | `process.env.KHY_EXPORT_PASSWORD \|\| 'khy2026'` |
| `ownerControlService.js` | 15 | 固定 Set | 支持 `process.env.KHY_STUDY_SECRET` 扩展 |

**新增环境变量（可选）**:
- `KHY_ADMIN_PASSWORD` — 管理后台密码
- `DEFAULT_ADMIN_PASSWORD` — AI 管理初始密码
- `KHY_EXPORT_PASSWORD` — 模型导出密码
- `KHY_STUDY_SECRET` — 学习模式额外密钥

---

### 2.6 Docker/CI 配置修复

| 问题 | 文件 | 修复 |
|------|------|------|
| backend→ai-backend 缺少 `depends_on` | `docker-compose.yml` | ai-backend 添加 `depends_on: backend: condition: service_healthy` |
| `BACKEND_PORT` 语义矛盾 | `docker-compose.yml` | backend 环境变量中显式设置 `BACKEND_PORT: 3000`（内部端口） |
| ai-backend `KHYQUANT_ROOT` 指向不存在路径 | `ai-backend/server.js` | 添加 `fs.existsSync` 检测，Docker 环境自动回退到 `__dirname` |
| CI quality-gates 缺 `npm ci` | `.github/workflows/ci.yml` | 添加 `npm ci --ignore-scripts` 步骤 |

---

### 2.7 数据源模块引用修复

`comprehensiveDataService.js` 三个 case 分支 require 不存在的模块文件：

| 数据源 | 原代码 | 修复 |
|--------|--------|------|
| `eastmoney` | `require('./eastMoneyDataSource')` | 直接 throw 明确错误信息 |
| `sina` | `require('./sinaDataSource')` | 直接 throw 明确错误信息 |
| `tencent` | `require('./tencentDataSource')` | 直接 throw 明确错误信息 |

错误消息统一引导用户使用已实现的 akshare 或 adata 数据源。

---

### 2.8 pyproject.toml 依赖上限对齐

`packages/backend/pyproject.toml` 中 7 个 Python 依赖缺少上限约束，与根 `pyproject.toml` 不一致。已全部补齐：

| 依赖 | 修复前 | 修复后 |
|------|--------|--------|
| `requests` | `>=2.25.0` | `>=2.25.0,<3.0.0` |
| `akshare` | `>=1.12.0` | `>=1.12.0,<2.0.0` |
| `scipy` | `>=1.10.0` | `>=1.10.0,<2.0.0` |
| `ta` | `>=0.11.0` | `>=0.11.0,<1.0.0` |
| `tqdm` | `>=4.65.0` | `>=4.65.0,<5.0.0` |
| `pyyaml` | `>=6.0` | `>=6.0,<7.0.0` |
| `loguru` | `>=0.7.0` | `>=0.7.0,<1.0.0` |

---

## 三、已识别但暂缓修复的问题

以下问题属于大范围国际化或低优先级设计选择，不在本次修复范围内：

| 问题 | 原因 |
|------|------|
| ~60 处英文用户面向字符串 | 需要统一的国际化改造，涉及 30+ 文件 |
| ~15 处 setTimeout 裸字面量 | 多为短计算保护（<5s），非 Rule 3 违规 |
| `AI_MGMT_PORT` vs `KHY_DAEMON_PORT` 变量名分裂 | 两个入口路径的历史设计，已有 runtime 文件发现机制兜底 |
| Docker SQLite 模式下 backend/ai-backend 使用独立 volume | 设计选择——隔离 vs 共享取决于部署方案 |
| `https-proxy-agent`/`glob`/`node-pty` 等可选依赖未声明 | 均有 try/catch 保护，降级而非崩溃 |

---

## 四、修复文件汇总

本次审计共修改/新增 **23 个文件**：

**修改的文件**:
1. `frontend/package.json` — 版本 + 移除 @capacitor/status-bar
2. `packages/khy-chain/package.json` — 版本
3. `packages/khy-hello/package.json` — 版本
4. `packages/khy-quant/package.json` — 版本
5. `packages/plugin-sdk/package.json` — 版本
6. `packages/sdk/package.json` — 版本
7. `packages/vscode-extension/package.json` — 版本
8. `backend/package.json` — 添加 moment、移除 commander
9. `ai-frontend/package.json` — 添加 @element-plus/icons-vue
10. `ai-backend/src/services/llmService.js` — 安全加载 + 回退链
11. `backend/src/services/gateway/adapters/ollamaAdapter.js` — 移除双重 env 读取
12. `backend/src/services/rateLimiter.js` — 修正注释
13. `backend/src/services/comprehensiveDataService.js` — 超时一致 + 数据源引用
14. `backend/src/services/comprehensiveDataStaticConfig.js` — futures: false
15. `backend/src/services/adminService.js` — 密码外部化
16. `backend/src/services/aiManagementServer.js` — 密码外部化
17. `backend/src/services/modelTrainingService.js` — 密码外部化
18. `backend/src/services/ownerControlService.js` — 密码外部化
19. `docker-compose.yml` — depends_on + BACKEND_PORT
20. `.github/workflows/ci.yml` — npm ci 步骤
21. `ai-backend/server.js` — KHYQUANT_ROOT 安全回退
22. `packages/backend/pyproject.toml` — 依赖上限约束

**新增的文件**:
1. `ai-backend/src/services/selfOptimizer.js` — 存根
2. `ai-backend/src/services/cloudSync.js` — 存根
3. `ai-backend/src/services/growthService.js` — 存根
