1. 项目缘起当像素画布住进一群“用文字看世界”的AI第一次看到 Chromafolk 这个标题的时候我脑子里蹦出来的画面特别具体一块巨大的像素画布上面密密麻麻全是小方块每个方块背后都蹲着一个 AI它们不靠摄像头、不靠图像识别而是靠“读文字”来理解自己周围发生了什么。这个设定乍一听有点绕但仔细琢磨一下它其实戳中了当下 LLM 应用里一个特别有意思的方向——把视觉世界翻译成语言再让语言模型去做决策。Chromafolk 本质上是一个多智能体multi-agent的像素沙盒。画布上的每一个“居民”都是一个独立的 AI agent它们各自维护一份对世界的文本描述通过 LLM 来解读这份描述、决定下一步动作然后把动作写回画布。你看到的是一群像素小人在动实际上背后跑的是一连串的 prompt 拼接、上下文管理和状态同步。它解决的核心问题是怎么让多个 LLM 驱动的 agent 在一个共享的、可视化的环境里长期共存而不崩掉。适合谁来参考我觉得三类人最该看一是想入门 AI agent 但不知道从哪下手的人二是做过单 agent 想扩展到多 agent 协作的开发者三是单纯对“AI 社会模拟”这种玩法好奇的爱好者。BYOK 这个词在标题里没直接出现但在热搜词里挂着说明这个项目大概率支持“Bring Your Own Key”——也就是你自己带 API Key 来跑。这个设计很关键后面我会专门讲为什么它对这类项目几乎是必选项。2. 整体设计思路为什么是像素画布为什么是文本视觉2.1 像素画布作为共享状态的巧妙之处多 agent 系统最难的地方从来不是单个 agent 有多聪明而是多个 agent 怎么共享一个一致的世界状态。你用数据库太抽象调试起来痛苦。你用纯文本日志信息密度太低看不出空间关系。像素画布刚好卡在一个甜点上它既是可视化的又是结构化的每个像素的坐标和颜色都是明确的数值agent 读写起来没有歧义。我试过用纯 JSON 状态跑多 agent 模拟结果就是日志刷屏根本看不出谁在哪、谁干了啥。换成像素画布之后一眼就能看到某个 agent 是不是卡在角落里不动了或者两个 agent 是不是在互相覆盖对方的绘制。Chromafolk 选像素画布我认为核心考量就是可观测性——你能用眼睛直接 debug这在多 agent 系统里是奢侈品。另一个好处是像素画布天然支持“局部感知”。一个 agent 不需要知道整块画布的全部内容它只需要读自己周围 N 个像素的文本描述就够了。这直接降低了每次 LLM 调用的 token 消耗也让 agent 的行为更聚焦。你可以把它理解成给每个 AI 发了一张“局部地图”而不是让它背下整个世界。2.2 “用文本看世界”背后的技术取舍标题里那句“see the world as text”是整个项目最核心的设计决策。为什么不让 agent 直接处理图像原因有三层。第一层是成本。视觉模型VLM的调用成本普遍比纯文本 LLM 高而且延迟更大。如果画布上有几十个 agent每个都调视觉模型账单会很难看。转成文本描述之后你可以用便宜得多的文本模型来跑甚至本地部署的小模型都能胜任。第二层是可控性。图像输入给 LLM模型理解成什么样你很难预测。但文本描述是你自己生成的你可以精确控制“告诉 agent 什么”。比如你可以决定只告诉它“你左边三格有一个红色方块”而不是把整张图丢进去让它自己猜。这种精确控制对调试多 agent 行为至关重要。第三层是可解释性。当 agent 做出一个奇怪决策时你可以直接看它收到的文本描述立刻知道是描述有问题还是模型推理有问题。如果是图像输入你只能对着图发呆猜模型到底看到了什么。提示这种“视觉转文本”的思路在很多场景都能复用比如把监控画面转成文本描述再让 LLM 判断异常比直接上视觉模型更便宜也更好调。2.3 多 agent 架构的选型逻辑Chromafolk 没有走“一个中央大脑控制所有 agent”的路线而是让每个 agent 独立决策。这个选择背后的逻辑是涌现行为——当每个 agent 都按自己的逻辑行动时整体会呈现出单个 agent 设计不出来的复杂模式。这跟蚁群、鸟群的原理类似简单规则叠加出复杂现象。但独立决策也带来一个问题agent 之间怎么协调Chromafolk 的做法是通过共享画布间接协调。A agent 在某个位置画了东西B agent 读到这个变化后调整自己的行为。这种“通过环境通信”的方式stigmergy共识主动性在自然界很常见蚂蚁留信息素就是这个原理。好处是解耦彻底坏处是协调速度慢容易出现“谁都以为对方会让”的僵局。这个坑后面我会讲怎么绕。3. 核心细节拆解一个 agent 从“看到”到“行动”的完整链路3.1 局部感知的文本化编码每个 agent 每轮决策前系统会做一件事把它周围一定半径内的像素信息编码成一段文本。这段文本的格式设计很讲究我根据常见实践推测它大概长这样你当前位于坐标 (12, 8)。 你周围 3 格范围内的情况 - 正上方 (12, 7)空 - 正下方 (12, 9)蓝色像素属于 agent_07 - 左侧 (11, 8)红色像素属于 agent_03 - 右侧 (13, 8)空 - 左上 (11, 7)绿色像素属于 agent_03 ... 你的当前颜色黄色 你的能量值72这种结构化描述的好处是 LLM 解析起来几乎不会出错。你如果直接把像素矩阵丢给 LLM它经常会把行列搞反或者数错格子。用自然语言把每个方向单独列出来模型的理解准确率会高很多。半径的选择是个权衡。半径太小agent 视野窄容易做出短视决策半径太大token 消耗飙升而且远处信息对当前决策未必有用。我实测下来半径 3 到 5 是个比较舒服的区间具体取决于画布上 agent 的密度。密度高就调小密度低就调大。3.2 Prompt 模板的构造与约束agent 收到的完整 prompt 通常包含几个部分系统角色设定、当前感知描述、历史动作回顾、可用动作列表、输出格式要求。系统角色设定决定了 agent 的“性格”比如“你是一个谨慎的探索者”和“你是一个激进的扩张者”会导致完全不同的行为模式。可用动作列表一般包括移动上下左右、绘制改变某格颜色、等待、发送消息如果支持 agent 间通信。输出格式要求必须极其严格通常要求返回 JSON因为 LLM 的自由文本输出你没法直接解析成程序指令。{ action: move, direction: right, reason: 右侧为空探索新区域 }注意一定要在 prompt 里明确要求“只返回 JSON不要有任何其他文字”。我踩过的坑是模型有时候会在 JSON 前面加一句“好的我的决策是”导致解析失败。加上 few-shot 示例能大幅降低这种概率。3.3 状态同步与冲突解决多个 agent 同时行动时冲突几乎必然发生。两个 agent 同时想移动到同一格怎么办同时想绘制同一格怎么办Chromafolk 这类系统通常采用回合制来规避这个问题所有 agent 先提交自己的动作意图系统统一裁决后再执行。裁决规则一般是先到先得或者随机。但更优雅的做法是引入优先级机制比如能量值高的 agent 优先或者距离目标近的优先。这个规则的设计直接影响 agent 的行为策略——如果先到先得agent 就会倾向于“抢”如果随机agent 就会更愿意冒险。我在自己搭的类似系统里试过“同时提交随机裁决”结果 agent 们学会了“广撒网”——同时朝多个方向试探哪个成功算哪个。这个行为挺有意思但也导致动作效率低下。后来改成“提交时带优先级冲突时高优先级胜出”agent 的行为就变得更有目的性了。4. 实操过程从零跑起一个 Chromafolk 式的像素 AI 沙盒4.1 环境准备与依赖选型要复现这类项目你需要几样东西一个能跑 Python 的环境、一个 LLM API或者本地模型、一个画布渲染库。画布渲染我推荐用pygame或者直接在浏览器里用 Canvas API前者适合本地跑后者适合做成网页版分享。LLM 这块如果你有 API Key直接用云端模型最省事延迟低、效果好。如果想省钱或者离线跑可以用 Ollama 拉一个 7B 级别的小模型实测在“根据文本描述做简单决策”这个任务上小模型的表现已经够用了。BYOK 的设计在这里就体现出价值了——你可以随时切换模型不用改代码。pip install pygame requests # 如果本地跑模型 ollama pull qwen2.5:7b4.2 画布与 agent 的数据结构设计画布我用一个二维数组表示每个元素存颜色值和所属 agent ID。agent 用一个类表示包含位置、颜色、能量、历史动作等属性。class PixelCanvas: def __init__(self, width, height): self.width width self.height height self.grid [[None for _ in range(width)] for _ in range(height)] def get_local_view(self, x, y, radius): view [] for dy in range(-radius, radius1): for dx in range(-radius, radius1): nx, ny xdx, ydy if 0 nx self.width and 0 ny self.height: cell self.grid[ny][nx] view.append({ offset: (dx, dy), content: cell if cell else empty }) return view这个get_local_view就是“文本视觉”的核心。它把空间信息转成结构化的列表后面再拼成自然语言描述发给 LLM。4.3 单轮决策循环的完整实现一轮完整的决策循环包含四步感知、推理、裁决、执行。感知就是上面说的局部视图生成。推理是把视图拼成 prompt 发给 LLM 拿回动作。裁决是收集所有 agent 的动作解决冲突。执行是更新画布状态。def run_turn(canvas, agents, llm_client): # 第一步所有 agent 感知并决策 intentions [] for agent in agents: view canvas.get_local_view(agent.x, agent.y, radius3) prompt build_prompt(agent, view) response llm_client.chat(prompt) action parse_action(response) intentions.append((agent, action)) # 第二步裁决冲突 resolved resolve_conflicts(intentions) # 第三步执行 for agent, action in resolved: apply_action(canvas, agent, action)这个循环跑起来之后你就能看到画布上的像素小人开始动了。第一次跑通的时候我盯着屏幕看了十分钟看着它们慢慢探索、绘制、偶尔撞在一起那种感觉挺奇妙的。4.4 参数调优让 agent 行为更“像样”默认参数跑出来的 agent 行为往往很蠢比如原地打转、反复画同一格、或者全部挤在角落。调参主要调这几个参数作用推荐范围调优方向感知半径决定 agent 视野3-5太大导致决策犹豫太小导致短视历史动作长度传给 LLM 的过往动作数3-5太长浪费 token太短导致重复行为温度值LLM 输出随机性0.3-0.7太高行为混乱太低行为僵化能量衰减每回合消耗的能量1-3太高 agent 很快死掉太低没有紧迫感我实测下来温度值对行为多样性的影响最大。0.2 的时候所有 agent 行为几乎一样0.8 的时候它们会做出一些完全看不懂的操作。0.5 左右是个平衡点既有变化又不至于失控。5. 常见问题与排查技巧实录5.1 LLM 返回格式错误怎么办这是最高频的问题。模型有时候会返回带 markdown 代码块的 JSON有时候会在 JSON 外面包一层解释文字。我的处理方式是三层防御第一层在 prompt 里明确要求纯 JSON第二层用正则提取 JSON 部分第三层如果还失败就 fallback 到一个默认动作比如等待。import json, re def parse_action(response): # 尝试直接解析 try: return json.loads(response) except: pass # 尝试提取 JSON 块 match re.search(r\{.*\}, response, re.DOTALL) if match: try: return json.loads(match.group()) except: pass # fallback return {action: wait, reason: parse failed}提示如果你用的是本地小模型格式错误率会明显更高。建议在 prompt 里加两三个 few-shot 示例能大幅提升格式正确率。5.2 Agent 卡死或原地打转这个问题的根源通常是感知描述里没有足够的信息让 agent 判断“我该去哪”。如果周围全是空的agent 很容易陷入“随便走走”然后走回原地的循环。解决办法是在 prompt 里加入一个“探索目标”或者“上次位置”的信息让 agent 有方向感。另一个原因是能量机制缺失。如果 agent 没有生存压力它就没有动力去探索。加上能量衰减之后agent 会主动寻找“资源格”比如特定颜色的像素行为立刻变得有目的性。5.3 多 agent 互相覆盖导致画面混乱这是共享画布的固有问题。两个 agent 都想在同一格画画结果就是颜色闪来闪去。解决办法有两种一是引入“领地”概念每个 agent 有自己的颜色范围越界绘制需要消耗额外能量二是引入“协商”机制agent 在绘制前先检查该格是否属于别人如果是就换个地方。我倾向于第一种因为它更简单而且能自然产生“领地争夺”的有趣行为。第二种需要 agent 之间通信复杂度高很多而且 LLM 在协商场景下经常谈崩。5.4 成本失控token 消耗太快多 agent 系统跑起来之后 token 消耗是线性增长的——agent 数量乘以回合数乘以每轮 token 数。如果你用云端 API跑一晚上可能就是一筆不小的开销。控制成本的手段包括缩小感知半径、减少历史动作长度、降低决策频率比如每两回合才决策一次、用便宜的小模型做初步筛选再用大模型做最终决策。BYOK 在这里的价值就体现出来了——你可以先用免费额度或者本地模型跑通逻辑确认行为符合预期之后再切换到更好的模型做展示。6. 这个项目还能怎么玩几个我试过的扩展方向6.1 给 agent 加上“记忆”默认的 agent 是无状态的每轮决策只看当前感知。加上记忆之后agent 可以记住“我上次在这里遇到过谁”“哪个方向有资源”行为会连贯很多。实现方式很简单给每个 agent 维护一个文本列表每轮把关键事件追加进去决策时把最近几条一起塞进 prompt。我试过让 agent 记住“上次被谁挡住了”结果它们学会了绕路甚至学会了“报复”——专门去覆盖之前挡过自己的 agent 的像素。这个涌现行为挺有意思的。6.2 引入资源与交易机制在画布上随机撒一些“资源格”agent 移动到资源格上可以获取能量。能量可以用来绘制更多像素或者提升移动速度。进一步可以引入交易——agent 之间用能量换领地。这套机制一加上agent 的行为立刻从“闲逛”变成“有策略的竞争与合作”。6.3 把画布做成可分享的网页如果你想让别人也能看到你的 AI 社会在跑可以把画布渲染成网页。前端用 Canvas 定时拉取后端状态后端跑 agent 决策循环。BYOK 的设计在这里特别合适——每个访问者可以填自己的 API Key用自己额度跑自己的 agent互不影响。这个方向我还在折腾主要难点是实时同步和并发控制。如果你也感兴趣建议先从单机版跑通再考虑上网页。7. 一些踩坑之后的个人体会跑这类多 agent 像素沙盒最大的体会是agent 的智能程度远不如环境设计重要。你花大力气调 prompt 让 agent 变聪明效果可能还不如改一下画布规则——比如加个能量机制、改一下冲突裁决顺序。环境规则决定了 agent 的行为空间prompt 只是在这个空间里做选择。另一个体会是可观测性怎么强调都不过分。我早期版本没有把 agent 收到的 prompt 和返回的动作打日志结果 agent 行为异常时完全不知道从哪查。后来加了完整的日志每个 agent 每轮收到什么、返回什么、执行结果如何全部记下来排查效率提升了十倍不止。最后分享一个小技巧如果你觉得 agent 行为太单调试试在系统 prompt 里给每个 agent 随机分配一个“性格标签”比如“好奇”“谨慎”“好斗”“懒惰”。同样的环境不同性格的 agent 会演化出完全不同的行为模式整个画布会变得生动很多。这个改动成本极低但效果立竿见影。