<!-- 文档分类: MGMT-PLAN-002 | 阶段: 项目管理 | 原路径: docs/指南/khy-librechat-差距修复路线图.md -->
# KHY-OS 与 LibreChat 差距修复路线图

更新日期：2026-05-15  
范围：`/home/kodehu03/Khy-OS` vs `/tmp/librechat_cmp/LibreChat-main`

## 1. 目标

在 4 周内，弥合测试、CI 质量门禁、可观测性、权限模型与发布治理等核心工程差距，使 KHY-OS 能够支撑更快速、更安全的迭代。

## 2. 基线（当前对比）

- CI 工作流：KHY `5` vs LibreChat `26`
- 测试相关文件：KHY `230` vs LibreChat `610`
- E2E 覆盖文件：KHY `1` vs LibreChat `23`
- TS 代码量：KHY `8` vs LibreChat `2218`
- Helm chart 支持：KHY `none` vs LibreChat `present`
- Husky 预提交工作流：KHY `none` vs LibreChat `present`
- 前端语言包目录：KHY `0` vs LibreChat `41`

## 3. 优先级矩阵

## P0（必须优先完成，生产风险）

1. 前端自动化测试与 CI 强制执行
2. 统一的根级脚本（`build/test/lint/e2e`）与流水线质量门禁
3. 可观测性基线（`/metrics`、请求延迟/错误指标、基础追踪钩子）
4. 许可证与元数据一致性修复（仓库 LICENSE 与 package 元数据）
5. `backend` 与 `ai-backend` 网关代码的去重策略

## P1（重要，平台成熟度）

1. 细粒度的能力/授权权限模型（超越 `admin/user`）
2. 前端 i18n 架构基线
3. 安全/治理文档：`CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`

## P2（扩展性与生态）

1. 部署矩阵加固（Helm 或等效的部署模板）
2. 更强的依赖治理（`overrides`/锁定策略、依赖漂移检查）

## 4. 四周执行计划

## 第 1 周（P0 启动：测试 + CI）

交付物：

1. 引入前端单元测试框架，并至少为认证、路由、核心视图编写冒烟测试。
2. 引入根级脚本：
   - `test`
   - `test:frontend`
   - `test:backend`
   - `e2e`
3. 更新 CI，使合并在以下情况被阻断：
   - 前端测试
   - 后端测试
   - lint
   - build

退出标准：

1. 前端测试失败时 PR 失败。
2. CI 时长与通过率可在工作流摘要中度量。

## 第 2 周（P0 继续：可观测性 + 法务一致性）

交付物：

1. 添加带鉴权保护令牌的 `/metrics` 端点。
2. 添加计数器/直方图：
   - 请求总数
   - 请求延迟
   - 错误总数
3. 为关键服务（gateway、auth、proxy）添加结构化的启动/运行时日志。
4. 解决以下各处之间的许可证不一致问题：
   - `LICENSE`
   - `pyproject.toml`
   - `backend/package.json`
   - 发布文档

退出标准：

1. 在本地与容器化运行中均可抓取到指标。
2. 许可证声明实现单一来源、保持一致。

## 第 3 周（P0/P1：架构风险 + 权限）

交付物：

1. 决定并实施网关整合方案：
   - 抽取共享包，或
   - 严格的单一归属模块并通过 import 引用
2. 消除重复网关文件之间的漂移。
3. 为选定的管理类 API 引入基于能力（capability）的权限校验。
4. 为权限提升与拒绝路径添加回归测试。

退出标准：

1. 不存在缺乏明确归属的重复网关逻辑。
2. 权限测试同时覆盖允许/拒绝两条流程。

## 第 4 周（P1/P2：治理 + i18n + 部署）

交付物：

1. 添加治理文档：
   - `CONTRIBUTING.md`
   - `SECURITY.md`
   - `CODE_OF_CONDUCT.md`
2. 建立前端 i18n 基线：
   - 语言包目录
   - 语言切换机制
   - 回退策略
3. 添加部署模板加固（Helm 或等效方案）与快速启动验证。

退出标准：

1. 新贡献者仅凭文档即可运行 lint/test/build。
2. 至少两种语言能够渲染核心 UI 文本。
3. 部署模板能够通过干净环境的冒烟测试。

## 5. 验收指标（第 4 周结束）

1. CI 必需检查项 ≥ 8 且全部对 PR 形成阻断。
2. 前端自动化测试存在并在 CI 中运行。
3. E2E 场景数量超过当前基线，并包含登录 + 关键路径。
4. `/metrics` 可用且具备受保护的访问控制。
5. 许可证与 package 元数据完全一致。
6. 网关重复已消除或已正式集中化。
7. 基于能力的访问控制已在管理类关键路径上线。

## 6. 风险控制

1. 将每一周作为独立的里程碑；不要把未完成的 P0 堆积到 P2。
2. 任何触及 gateway/auth 的重构，必须先有回归测试保护。
3. 不得为临时便利而放宽权限或绕过校验。
4. 若 CI 运行时长增长过多，应先对测试分片并缓存依赖，再考虑削减覆盖率。

## 7. 建议负责人

1. 运行时/后端负责人：可观测性、网关整合、权限模型
2. 前端负责人：测试搭建、i18n 基线
3. DevOps 负责人：CI 质量门禁、部署模板
4. 仓库维护者：治理文档与许可证对齐
