我用 Codex 做了一个智能围棋机器人系统：从 AI 引擎接入到前后端联调的完整实战

这个项目并不简单：后端要接 KataGo 引擎，前端要做智能分析工作台，还要考虑人类棋风模型、机器人陪练、局域网访问、后续移动端扩展，以及未来的机械臂与视觉识盘接口。整个过程中，Codex 不仅参与了编码，还参与了架构拆分、UI 重构、WSL/Windows 运行时隔离、接口联调、错误定位与文档沉淀。

这篇文章，我不想写成"AI 真香"式流水账，而是尽量从技术角度复盘：Codex 在一个真实项目中到底能帮到什么程度，怎么用它才更像一个高级开发协作者，而不是随机生成器。

一、这个项目到底是什么

我做的是一个智能围棋机器人系统，目标不是单纯做一个"棋盘网页"，而是搭出一个可持续扩展的 AI 围棋中枢。

当前已经落地的核心能力包括：

围棋局面分析
AI 下一步推荐
教学提示与讲解开关
机器人陪练
联机模式基础能力
标准模型与人类风格模型切换
Web 工作台
局域网访问准备
为移动端、视觉识盘、机械臂控制预留接口

整个技术栈大致如下：

KataGo / 分析引擎

↓

C++ 查询层 / GTP 或 JSON 路线

↓

Python Gateway（统一 API）

↓

React + Vite + Tailwind 前端工作台

↓

未来扩展：移动端 / AR识盘 / 机械臂硬件

这不是一个 demo，而是一个正在往"产品化原型"推进的系统。

二、为什么这个项目特别适合用 Codex

很多项目不适合一上来就让 AI 深度参与，因为需求边界不清、代码规范混乱、技术选型飘忽不定，AI 很容易越写越歪。

但这个项目恰好满足了 Codex 发力的几个关键前提：

有明确的目标系统：围棋分析、陪练、教学、联机

有逐步推进的技术路线：引擎接入、接口统一、前端消费、局域网放开

有清晰的约束：不随意删文件、优先修改现有代码、记录进度文档

有真实工程问题：端口占用、Windows/WSL 运行时冲突、接口模式切换、UI/UX 重构

也就是说，Codex 在这里不是"瞎猜需求"，而是在一个可验证、可迭代、可复盘的工程环境里工作。

这时它的价值就会被放大。

三、我不是把 Codex 当 AI，我是把它当"技术协作者"

这是整个过程里最重要的一点。

如果你只是对 Codex 说一句：

"帮我做个围棋项目"

那最后多半只会得到一堆中看不中用的代码骨架。

但如果你像和一个真正的工程同事协作一样去使用它，效果会完全不同。我的做法大概是这样的：

1. 先让它读项目，再让它动手

我一开始不是让它立刻生成代码，而是先要求它：

阅读当前目录下的文件
判断项目开发进度
说明下一步应该做什么
经我确认后再继续

这一步非常关键。

它逼着 Codex 先建立上下文，而不是直接"脑补"。

2. 明确告诉它什么能改，什么不能改

比如我会持续强调这些约束：

尽量修改原文件，不要随意删除重建
每完成一步就更新项目记录文档
前端必须遵守既定设计规范
保持 React + Vite + Tailwind 的目录分层
逻辑要优先用 Hook 解耦
不要把接口写死为 127.0.0.1

你会发现，AI 不是不听话，而是你不给约束，它就只能用"统计学平均答案"来应付你。

3. 让它先收敛方案，再执行实现

有些时候我不是直接让它改，而是先问：

当前阶段卡在哪里
这个问题的根因是什么
下一步最优先该做什么
有哪些可选方案

这样做的好处是，Codex 会从"代码生成器"切换到"问题分析器"的角色。

四、这个项目里，Codex 真正帮我解决了哪些硬问题

如果只是写几个组件、拼几个页面，那不能说明什么。真正让我觉得它有工程价值的，是它参与解决了几类很现实的问题。

1. 前后端运行时冲突：Windows 能跑服务，但跑不动引擎

这是我遇到的一个非常典型的问题。

前端页面虽然能打开，但一切进入分析、陪练、评级等真实引擎逻辑时，就会报错：

$WinError 193\] %1 不是有效的 Win32 应用程序$

表面上看像接口挂了，实际上根因是：

Python 网关可以在 Windows 上启动，但底层引擎链路更适合 WSL/Linux 环境运行。

最后做的不是"强行让所有东西都在 Windows 原生跑"，而是做了更合理的运行时分层：

Windows 原生 Python：允许启动网关，但对引擎能力返回结构化 503
WSL/Linux：作为标准后端运行环境，真正承载分析引擎
网关健康检查接口暴露运行时信息
增加 WSL 启动脚本和说明文档

这件事说明一个很现实的问题：

Codex 最有价值的地方，不是帮你"凑出能跑的代码"，而是帮你把错误的工程路径掰正。

2. 8080 端口占用：问题不在代码，在旧进程

还有一次，页面一直访问异常，乍看很像前端或接口路径写错了。但继续排查后发现，真正的问题是：

旧的 Windows Python 进程一直占着 8080
新启动的 WSL 网关其实根本没接管到正确端口

后来做了几件事：

清理旧的 python_gateway/app.py 占用进程
脚本化检测谁在监听 8080
确保 WSL 版本网关真正监听在 0.0.0.0:8080
启动脚本自动识别是否已有正确进程运行

这类问题非常能体现 Codex 的一个优势：

它可以把"定位问题 -> 给出命令 -> 修改脚本 -> 更新文档"这一整串链路连起来。

3. 前端 UI 不是"能用就行"，而是反复重构

项目后面最花精力的，其实不是底层引擎，而是前端工作台。

一开始页面虽然能工作，但存在很多问题：

棋盘不够突出
顶部留白过大
控制区信息堆叠
陪练配置和分析档位重复
交互路径不够直观
小白用户看不懂参数

后来，我们连续做了几轮产品化重构：

三栏式工作台布局
赛博暗黑风格
棋盘点击即落子
推荐点发光环可视化
教学栏与推荐开关解耦
Pro 模式与简洁模式分层
段位与引擎能力拆分
人类风格模型做吸附式档位展示
预留实景识盘与硬件中枢入口

这让我意识到，Codex 在前端里最适合扮演的角色，不是"设计师"，而是：

设计约束的执行者
状态逻辑的实现者
重构节奏的推进者

前提是，你必须把设计原则说得足够明确。

4. Bot 模式里，开关不是"创建时生效"，而是"落子时持续生效"

这个问题挺隐蔽，但很典型。

当用户在机器人陪练模式中，切换"推荐点开关"或"教学提示开关"时，界面看起来切了，但实际对局期间点击并没有产生预期效果。

原因在于：

之前这些选项只在创建 bot game 时写入，后续每一步落子请求并没有同步更新当前开关状态。

后来的修正方式是：

/bot_games/{id}/move 请求中携带 enable_recommendation 和 enable_teaching
后端在每一步中更新当前对局配置
前端点击开关后，不需要重建整局，也能即时生效

这个问题很有代表性，因为它不是"写个接口"那么简单，而是涉及：

状态源头在哪
配置是一次性写入还是持续同步
交互预期和系统实现是否一致

这种问题如果让人纯靠肉眼扫代码，往往要花很久。让 Codex 参与做链路级排查，效率会高很多。

五、我如何把 Codex 用到"像工程师"，而不是"像聊天机器人"

这是我最想分享的部分。

方法一：任务必须拆成可验证的小步

我几乎不会让它一次性重构整个系统，而是像这样推进：

先改 client_bootstrap
再接 analysis_query
再做 bot game
再处理 live room
再优化 UI/UX
再放开局域网访问
再补文档和启动脚本

每一步都可以验证。

这样 Codex 的输出质量会显著提高。

方法二：要求它同步维护文档

我反复要求它每完成一个阶段，就更新项目记录文档。

这件事看起来像"形式主义"，但实际非常有用，因为它会迫使 AI 持续回答这三个问题：

我们现在做到哪里了
刚刚改了什么
下一步应该是什么

这能显著减少后续上下文漂移。

方法三：让它解释"为什么这么改"

只看代码是不够的。

我会追问：

这个错误的根因是什么
为什么选方案 A，不选方案 B
这个改动会影响什么
未来 App 化、视觉识盘、数据库接入时是否还能复用

这会把 Codex 从"执行层"拉到"设计层"。

六、这个项目当前做到哪一步了

如果从工程成熟度来看，我认为项目现在已经走过了最危险的"原型失控期"，进入了"可以演示、可以迭代、可以扩展"的阶段。

目前大体处于这个位置：

已完成

KataGo 能力接入主链路
Python Gateway API 跑通
React 前端工作台落地
分析、陪练、联机基础模式接通
推荐点、教学栏、机器人模式联动修复
WSL 运行标准化
局域网访问初步放开
UI 进入可演示级状态
移动端、视觉识盘、硬件控制已预留接口思路

正在逼近的阶段

在线房间体验强化
学生/学校体系数据库接入
用户段位与对局记录持久化
实景识盘输入链路
App 化与跨端适配
机械臂协议与硬件联动

换句话说，现在它已经不是"想法"，而是一个真正有机会继续长成产品的系统。

七、我对 Codex 的真实评价

如果非要我用一句话总结，那就是：

Codex 最强的地方，不是替你写代码，而是当你已经知道自己要做什么时，它能帮你把工程推进速度拉高一个量级。

但它也不是万能的。它依然有几个边界：

你不给清晰约束，它就容易发散
你不做阶段验证，它可能一路写偏
你不盯产品逻辑，它会默认走"技术正确但体验平庸"的路线
复杂项目里，它更适合"协作推进"，而不是"完全放权"

所以正确的用法不是：

"AI，帮我做完这个项目"

而是：

"这是目标、这是约束、这是当前状态、这是下一步，请在这个边界内推进，并持续给我可验证结果。"

这两种用法，结果完全不是一个量级。

八、结语

这次做智能围棋机器人项目，让我对 Codex 的看法发生了很大变化。

它已经不只是一个"自动补全工具"，也不只是"写代码助手"。在复杂项目里，只要你给它清晰的目标、稳定的上下文、严格的工程边界，它可以逐步承担：

架构推进
代码实现
状态解耦
问题定位
跨层联调
文档沉淀
工程节奏管理

我更愿意把这种能力理解为：

一种面向真实项目的 AI 协作式开发。

而这个围棋项目，就是我目前为止最有说服力的一次实践。

总结

如果你也在做一个复杂项目，尤其是涉及前后端、AI 引擎、UI 重构和运行环境切换的系统，我非常建议你别再把 Codex 只当"写函数工具"了。真正高价值的用法，是把它纳入你的工程协作流，让它参与节奏、参与拆分、参与排错、参与演进。你会发现，AI 编程真正的壁垒，不是模型本身，而是你是否会组织它。