最近我准备系统复盘一个项目：HInsight。

这个项目最容易引起关注的问题，可能是：

真的能用 Codex 把 Grafana 前端从 React 迁到 Vue 吗？

我的结论是：

可以，但不是一键迁移。

HInsight 是我基于 Grafana 开源能力体系 迁移和改造出来的一套工业可观测平台，目前已经进入真实生产场景使用。

先说明几个边界：

• HInsight 不是 Grafana Labs 官方项目；
• HInsight 不是所谓“Vue 版 Grafana”；
• 迁移到 Vue 是基于团队技术栈、长期维护和内部部署需求；
• 公开内容会做必要脱敏；
• 不会披露公司名称、客户信息、现场接口、生产数据和控制策略。

---

一、这次迁移不是几个页面的重写

Grafana 不是普通前端项目。

它不只是一些 React 页面，而是一整套复杂的可观测系统能力，包括 Dashboard、DataSource、Panel、Explore、权限、日志、插件、配置、packages 分包体系、UI 组件体系，以及 Go 后端运行链路。

HInsight 目前已经基本继承并适配了原有可观测系统的核心能力，包括：

• Dashboard
• DataSource
• Panel
• Explore
• 权限
• 日志
• 配置
• 常用插件能力
• packages 目录下的所有分包体系
• UI 组件能力，尤其是 grafana-ui 相关能力

同时，这次迁移不只是前端改造。

后端 Go 代码、运行配置、工程结构、构建链路和 demo 验证链路，也都做了相应修改和适配。

所以这件事并不是简单的：

React Component -> Vue Component

而是一次成熟复杂系统的整体迁移。

---

二、为什么这件事难？

从零开发一个新系统时，很多边界可以自己定义。

但迁移一个成熟系统时，真正困难的是：

不能随意破坏原有行为。

比如：

• Dashboard 要能正常打开和使用；
• DataSource 要能查询数据；
• Panel 要能正常渲染；
• Explore 要能用于问题排查；
• 权限、日志、配置不能断；
• packages 分包体系不能散；
• UI 组件能力要能承接；
• Go 后端链路要能和前端配合；
• 构建、测试、运行链路要闭合。

这就是它和普通 demo 最大的区别。

---

三、Codex 不能直接放开干

HInsight 迁移过程中，我主要使用的是 Codex。

不过，这个系列并不想讨论“Codex、Claude Code、Cursor、Copilot 谁更强”。Codex 是我当时实际使用的主要 AI 辅助编码工具，但后续复盘的方法论并不绑定某一个工具。

只要 AI 辅助编码工具进入真实复杂工程，都会遇到类似问题：

• 上下文如何保持；
• 任务如何拆分；
• 边界如何约束；
• 结果如何验收；
• 中断后如何接续；
• 经验如何沉淀。

在实际过程中，Codex 并不能直接放开干。

它会遇到这些问题：

• 长任务跑偏；
• 上下文丢失；
• 掉线后接不上；
• 新会话需要重新建立背景；
• 为了尽快完成选择短平快方案；
• 修改范围扩大；
• 页面实际运行和汇报不一致；
• 花很久修一个问题，最后又回到原点。

所以后来我不再让 AI 自由发挥，而是把它纳入工程流程。

---

四、我后来形成的 AI 工程闭环

HInsight 能够持续推进，关键不在于“AI 一次性做对”，而在于建立了一套闭环。

我后来形成的流程是：

这套流程的核心是：

不是让 AI 自由发挥，而是把 AI 纳入工程闭环。

---

五、每个环节解决什么问题？

1. 目标定义

先明确这次任务要解决什么问题，也明确不解决什么问题。

如果目标不清楚，AI 很容易选择自己最容易完成的路径，而不是项目真正需要的路径。

---

2. 验收标准

先定义什么叫完成。

例如：

• 构建是否通过；
• typecheck 是否通过；
• 单测是否通过；
• e2e 是否通过；
• 目标页面是否可用；
• 核心交互是否一致；
• 是否允许改接口；
• 是否允许引入新依赖。

如果没有验收标准，AI 很容易给出一个“看起来完成”的结果。

---

3. 计划

让 AI 先输出执行路径，而不是直接改代码。

这一步的价值，是提前判断它对任务的理解是否正确。

---

4. 差异表

差异表用于记录：

• 当前实现是什么；
• 目标实现是什么；
• 差异在哪里；
• 哪些文件需要改；
• 哪些逻辑必须保留；
• 哪些风险需要注意。

差异表能防止 AI 一开始方向偏了，后面越改越远。

---

5. 执行

AI 按计划实施改动。

这里必须控制边界，避免修改范围无限扩大。

---

6. 自检与测试

AI 改完之后，不能直接算完成。

必须先自检，再跑测试：

• 构建；
• typecheck；
• 单测；
• e2e；
• 目标页面运行检查。

---

7. 人工验收

复杂系统不能只靠测试。

尤其是 Dashboard、Panel、Explore、DataSource 这类功能，必须做人工视觉和操作验收。

---

8. 交接书

任务结束时，要求输出：

• 完成了什么；
• 修改了哪些文件；
• 跑了哪些测试；
• 还有哪些风险；
• 下一步应该从哪里继续。

---

9. 本地记忆

这是为了解决上下文中断、会话切换和 worktree 并行的问题。

不能指望 AI 永远记得前面发生了什么，必须把关键上下文沉淀到本地。

---

10. 复盘沉淀

最后把有效经验变成规则、模板和 checklist。

否则下一个类似任务还会重新踩坑。

---

六、后续会继续复盘什么？

这个系列后续会继续展开：

• Grafana 开源能力体系到 HInsight 的迁移；
• React → Vue 的具体迁移规则；
• packages 分包体系和 grafana-ui 相关能力；
• Go 后端代码和运行配置；
• Dashboard / DataSource / Panel / Explore 迁移；
• Codex 跑偏和返工案例；
• 差异表和交接书模板；
• 本地记忆机制；
• e2e 测试血泪史；
• HInsight Core 开放核心版本。

---

七、后续会整理 HInsight Core

后续我会整理 HInsight Core 开放核心版本，用于下载、学习和验证。

它会尽量保留完整核心工程结构，包括：

• Go 后端；
• Vue 前端；
• 核心 packages；
• Docker demo；
• 模拟数据源；
• 示例 dashboard。

但出于行业保密和安全要求，HInsight Core 不会包含：

• 真实生产数据；
• 客户信息；
• 现场接口；
• 控制策略；
• 内部算法；
• 生产部署配置。

公开版本的目标，是帮助大家理解和验证这套工程方法，而不是直接暴露生产系统。

---

八、小结

能不能用 Codex 辅助迁移 Grafana 前端 React → Vue？

我的结论是：

能，但前提不是“让 AI 一键完成”，而是把 AI 纳入可控工程闭环。

HInsight 对我最大的意义，不只是完成了一次技术栈迁移，而是让我重新理解了 AI 编程：

AI 编程真正难的，不是生成代码，而是建立一个可控的工程闭环。

这里是「码客问剑」。

不只讲 AI 工具，更讲真实复杂系统里 AI 怎么落地。