真实代码驱动的放置游戏： Coding-Agent 如何让游戏进度源于实际开发劳动

一个桌面放置游戏，进度不是靠定时器模拟，而是由一个真实的 coding-agent 在后台写代码、改文件、跑测试来推动。这个项目把“玩家点击——游戏产出”变成了“玩家下发任务——AI 代理真实完成——游戏结算奖励”。核心不是游戏画面多精致，而是它成功把真实开发行为映射成了增量游戏的成长曲线。

对两类人来说这个项目特别值得研究：一类是玩过 Cookie Clicker、Melvor Idle 这类放置游戏的玩家，好奇“如果游戏里的资源真的来自现实劳动”会是什么体验；另一类是关注 coding-agent 落地形态的开发者，想看看除了自动补代码、修 issue 之外，AI 代理还能被包装成什么有趣的东西。下面我按实际运行、核心循环、挂机坑位和自制原型四个方向拆一遍。

1. 先说结论：它不是“装成写代码”的放置游戏，而是“真的在写代码”

1.1 项目把“真实劳动”当成游戏增量来源

增量游戏最常见的做法是：设置一个间隔计时器，每隔几秒给你加一点金币、经验或材料。玩家看到数字增长，本质上只是程序在后台累加。这个项目最大的不同在于，增量来源是编码代理的真实执行结果。

一个典型循环是这样的：游戏里有一个任务队列，玩家或系统往队列里塞任务，编码代理拿到任务后按真实开发流程执行——创建文件、修改代码、跑命令、读输出、再修改，直到任务完成。任务完成的判定不是游戏虚构的，而是代理确实把代码写出来了、把测试跑过了。这时候游戏才给玩家结算对应奖励。

这个设计的妙处在于，游戏里每一个金币、每一段经验值，背后都有真实事件作为依据。玩家看到“我的代码仓库多了一个功能模块”和“我的游戏角色涨了一级”同时发生，而且二者因果关系是真实的，不是随机数。

1.2 它解决的实际问题不是“好玩”，而是“让代理过程可见”

编码代理目前最大的使用痛点之一是过程不透明。你给它一个需求，它吭哧吭哧跑几分钟，最后给你一个结果，中间发生了什么、哪些尝试失败、为什么选这个方案，很多时候玩家根本不知道。

这个桌面游戏等于给代理执行过程加了一层可视化外壳。任务状态、执行步骤、产出文件、耗时统计，都被包装成游戏里的任务进度条、奖励弹窗和资源收入。玩家看到的不再是黑盒调用，而是“代理正在读文件”“代理正在安装依赖”“代理正在修改配置”这些过程节点。

所以它的价值不只是娱乐，而是提供了一种观察 coding-agent 行为的交互方式。从这个角度看，它更适合被当作“代理执行可视化工具 + 游戏化外壳”来理解，而不是单纯一个游戏 DEMO。

1.3 和普通增量游戏的核心差异看这张表

2. 运行前先弄清楚三件事：通信、成本和安全边界

2.1 桌面壳和编码代理是怎么配合的

这个项目基本可以拆成两层：外层是桌面应用，负责游戏界面、任务展示、奖励结算；内层是编码代理，负责真实执行开发任务。两层之间需要一套通信机制。

常见的做法有几种：

• 桌面应用直接调用代理提供的命令行接口，启动一个子进程，把输入输出重定向到游戏日志系统。
• 桌面应用通过本地 HTTP 服务或 WebSocket 与代理服务通信，代理服务独立运行，二者通过端口交互。
• 桌面应用读取代理生成的日志文件和工作目录快照，用轮询方式判断任务状态。

具体用哪种取决于作者在项目里怎么接的。但这三件事是通用的：任务输入要能传给代理，代理输出要能被游戏读取，任务状态要能从“排队”切换到“执行中”再到“完成”或“失败”。

2.2 资源和成本不能忽视

这是最容易让新手误判的地方。普通放置游戏开一晚上没问题，但这种由真实代理驱动的游戏，每执行一个任务都要调用模型推理服务。如果你用的是云端大模型 API，那每次任务的 token 消耗都是真金白银。

我的建议是，第一次运行先看三样东西：

• 单次任务的平均消耗，包括输入 token、输出 token 和执行时长。
• 任务的频率控制，是不是每个任务都必须完整跑完一个代理循环。
• 有没有缓存或结果复用机制，同一个任务反复执行是否会重复计费。

如果只是体验，可以选择本地小模型或者限制任务队列长度。不要把任务频率设得太高，否则你可能睡一觉起来发现账单比游戏数据增长得还快。

2.3 权限边界必须提前收紧

编码代理意味着它能在你电脑上真实执行命令、读写文件。如果游戏把代理接入到你的个人开发目录，那它就有能力修改这些文件。这里一定要做好权限隔离。

我建议至少做到以下几点：

• 给游戏单独建一个工作目录，不让代理直接操作你的正式项目。
• 检查代理的允许命令列表，默认不要开放任意 shell 命令。
• 任务来源如果来自网络或社区，要仔细看是不是存在恶意指令注入的可能。
• 定期备份工作目录，尤其是你想长时间挂机的情况下。

注意：任何 coding-agent 驱动的应用，本质都是一台能执行命令的本地机器。第一次运行前先看一眼它到底会在哪个目录下做什么，比急着看游戏画面重要得多。

3. 第一次运行：怎么判断代理真的在干活，而不是装样子

3.1 一次完整启动流程大概长这样

虽然不同项目的入口不一样，但通用的启动顺序大致是：

1. 安装基础运行环境，通常需要桌面应用对应的语言运行时和 Node、Python 之类的开发环境。
2. 配置编码代理的后端模型地址、API Key 和工作目录。
3. 启动桌面应用，检查任务面板是否出现初始任务。
4. 观察日志输出，确认代理开始执行，而不是一直停在初始化状态。

第一次跑不要急着接复杂任务。先给一个最小任务，比如“创建一个名为 hello.txt 的文件，内容为 hello world”，然后看它能不能完整闭环。

3.2 成功和失败的判断标准

一个任务真正完成的判断标准，不是游戏界面上出现了“任务完成”四个字，而是以下条件同时满足：

• 工作目录里确实出现了对应文件或代码变更。
• 命令行执行记录里有完整的命令和输出。
• 游戏日志里记录了任务从开始到结束的时间线。
• 如果任务包含验证步骤，验证命令必须执行成功。

如果这些条件里只有界面显示完成，但文件目录没有任何变化，那说明游戏只是给代理发了个请求，但代理的产出没有被正确回收。这时候优先检查代理的输出解析逻辑，看它是依据什么来判断“完成”的。

3.3 我常用的验证方法是直接看工作目录

比起盯着游戏界面，我更习惯直接打开工作目录看文件。游戏界面可能美化真实性，但文件系统不会骗人。跑完第一个任务后，我一般会执行这样几个检查：

# 查看工作目录下新增了哪些文件 find . -type f -mmin -10 # 看最近一次任务产生的文件内容是否跟预期一致 cat hello.txt # 查看代理执行日志的最后 50 行 tail -n 50 agent.log

如果文件存在、内容正确、日志时间线完整，那基本可以认为这套链路是通的。下一步再考虑给游戏加真实任务。

3.4 第一次运行最容易出现的三个问题

第一个问题是代理根本没有拿到任务。原因通常是任务队列和代理进程之间的通信没建立，客户端把任务发到端口，但代理服务没监听。

第二个问题是代理执行了任务，但游戏没有收到完成事件。这往往是代理和游戏之间的状态同步只靠进度日志解析，而解析规则没覆盖代理所有可能的输出格式。

第三个问题是环境依赖不完整。代理执行任务时可能尝试安装依赖，但桌面应用没有给代理足够的权限，或者网络环境不允许访问包管理器。看到“任务失败”之前，先确认失败日志到底是模型报错、权限报错还是网络报错。

4. 核心循环拆解：任务队列、奖励曲线和升级逻辑

4.1 任务从哪来，决定了游戏能不能持续

放置游戏最怕内容耗尽。这个项目里，任务来源的设计直接决定了长期可玩性。

可能的方向有三类：

• 固定任务集：项目内置一批写好的开发任务，玩家按顺序解锁。
• 玩家自定义任务：玩家在输入框里描述需求，代理执行。
• 系统生成任务：由另一个 LLM 根据当前仓库状态、用户目标或游戏进度自动生成下一个任务。

固定任务集最简单，但玩两小时就腻了。玩家自定义任务有互动感，但对任务格式校验要求高。系统生成任务最可持续，但需要额外接一个任务规划模型，而且生成质量不稳定时会影响游戏体验。

我自己的判断是，做原型阶段先用固定任务集验证闭环，跑通后再考虑系统生成。不要一开始就上自动生成，否则你很难判断到底是游戏逻辑有问题，还是任务生成本身有问题。

4.2 奖励曲线要和任务难度匹配

增量游戏的核心是奖励曲线。如果所有任务奖励一样，玩家很快失去目标；如果奖励曲线设计得太陡，玩家会觉得后期无所事事。

基于实际代理任务，奖励可以这么设计：

奖励不仅要看任务数量，还要看任务是否真实完成、是否包含验证步骤。一个只改了代码但没有跑测试的任务，奖励应该低于附带测试验证的任务。这样才能引导玩家和代理都去做更完整的工作。

4.3 升级系统的本质是缩短时间或扩大任务池

放置游戏的升级系统，本质上是两种形式：要么让单位时间产出更多，要么解锁新的可玩内容。

在这个项目里：

• “单位时间产出更多”可以体现为代理并发数提升、任务队列容量扩大、执行速度优化。
• “解锁新内容”可以体现为新的任务类型、新的工作目录、新的代码仓库，或者更复杂的技术栈。

不过这里有一个和纯虚拟游戏不同的坑：提升并发数不等于真正提速。如果你的代理后端是单请求模型服务，同时跑多个任务只会排队，不会并行。升级面板里写的“并发 +1”，必须要落到真实的任务调度层才有意义，否则只是一个没有实际效果的数值。

5. 长时间挂机最容易踩的坑

5.1 速率限制和接口配额

挂机是放置游戏的标配玩法，但带 coding-agent 的放置游戏挂机时要格外小心。绝大多数模型服务都有速率限制和配额限制，你可能连续跑了几十个任务之后突然发现所有任务都开始报错。

处理方式：

• 记录每个任务的系统级错误，区分速率限制、超时、配额不足和模型侧错误。
• 遇到速率限制时采用退避重试，不要立即拼命重发。
• 设置单日任务上限，超过后游戏自动进入“休眠模式”，只展示进度不触发新任务。

我建议把“配额不足”当成一种游戏事件来设计。比如当天额度用完后，游戏显示“代理疲惫了，明天再来”，既避免成本失控，也比直接报错更有游戏感。

5.2 工作目录会越挂越乱

代理执行几十个任务以后，工作目录里会堆积大量临时文件、未提交的改动、互相冲突的代码片段。如果没有清理机制，后期代理自己都会看花眼，任务成功率明显下降。

解决思路：

• 每个任务使用独立子目录，避免任务间互相干扰。
• 定期清理临时文件和缓存目录。
• 任务开始前先记录当前 git 状态，任务结束后对比变更内容，判断改动了哪些文件。
• 如果支持沙箱，尽量在隔离环境里让代理执行命令。

5.3 任务卡死和输出一致性问题

卡死是这类项目最让人头疼的问题。代理可能在等待模型响应，可能在等待用户确认，也可能陷入一个死循环反复执行同一个命令。游戏界面看起来还在运行，但其实已经完全不推进了。

我的排查顺序是这样的：

1. 先看代理进程的 CPU 和网络占用，判断它是不是真的还在干活。
2. 再查看最近一条日志的时间戳，如果超过阈值没更新，基本可以判定卡死。
3. 如果卡在模型请求阶段，检查网络和模型服务状态。
4. 如果卡在命令执行阶段，检查命令是不是在等待输入。

输出一致性问题则是另一个隐蔽坑。同一个任务，代理第一次用一个方案，第二次可能用另一个方案，导致产出文件结构不一致。如果你后面要做批量任务或自动化评估，一定要先固定任务验收标准，比如必须包含哪些文件、必须通过哪些测试、代码风格必须符合哪个规范。

注意：挂机不是搭好环境就不管了。合理的设计应该是在任务失败到达一定次数后自动暂停，并且把失败任务单独放一个队列，避免失败任务污染后续任务。

6. 如果自己做同款原型，怎么最小化起步

6.1 一个最小可运行的架构

如果你看过这个项目之后，也想做一个同款原型，我建议不要一开始就做完整桌面游戏，先做一个最小闭环：一个任务输入 + 一个代理执行 + 一个结果展示。

最小架构可以这样拆：

• 任务输入：一个 JSON 文件或简单的输入框。
• 代理执行：复用现成的 coding-agent 开源框架，不自己实现代理逻辑。
• 状态记录：把代理输出重定向到日志文件。
• 结果展示：一个本地网页或命令行界面，轮询日志文件显示状态。

对应的目录结构大概是这样：

game-root/ ├── tasks/ # 任务定义 ├── workspace/ # 代理工作目录 ├── logs/ # 代理和游戏日志 ├── config.json # 模型、路径、并发配置 └── game-loop.py # 游戏主循环

6.2 核心代码不需要很复杂

真正的核心逻辑就三块：读任务、调代理、写状态。伪代码形式大概是：

for task in task_queue: # 把任务写入代理输入 result = agent_execute(task, workspace) # 把执行结果写入日志 append_log(task.id, result) # 根据结果结算游戏奖励 if result.success: player.gold += reward_for(task) else: task_retry(task)

这里最需要花心思的是agent_execute返回结果的结构化解析。代理输出通常很冗长，你必须从中提取出“是否完成”“改了哪些文件”“测试是否通过”这些关键字段。如果这一步做不好，后面所有奖励结算都会失真。

6.3 建议的起步顺序

按这个顺序推进，踩坑成本最低：

1. 先跑通一个命令行版的最小闭环，不写任何界面。
2. 确认任务从输入到执行到结果判定全链路可用。
3. 再加一个简单的界面层，展示日志和任务状态。
4. 然后设计奖励曲线和升级逻辑。
5. 最后才考虑任务自动生成、并发队列、沙箱隔离这些高级功能。

6.4 值得扩展的方向

这个项目真正有意思的地方在于，它打通了“真实劳动”和“虚拟奖励”之间的映射。往远处想，有很多可扩展空间：

• 把任务结果做成可视化的“代码贡献时间线”，玩家可以看到自己的游戏进度快照对应的代码仓库演化过程。
• 根据代理最终产出的代码质量评定游戏成就，比如“首次通过全部测试”“完成一次跨文件重构”。
• 把多人玩法做成团队副本，多个玩家各自运行代理，共同完成一个更大的代码任务。
• 把任务池做成玩家之间互发任务，让“给别人写需求”也成为游戏机制。

不过这些方向都应该放在最小闭环验证之后再考虑。先确认一件事：游戏里的增量是否真的等于代理产出的增量，如果是，这个项目就已经成功一大半了。

我自己试过类似方案之后最大的体会是，这类项目最大的风险不是技术实现，而是设计失衡。如果代理执行太快，游戏会变成“排队看演示”，失去游戏性；如果奖励和真实产出脱节，又变成了套了一层壳的普通任务管理器。真正合适的节奏，是让玩家既能感受到真实代理在工作，又愿意为了游戏里的目标不断给代理安排更有挑战的任务。这个平衡点，花多少时间调都值得。