10天手搓开源Agent项目获3000万投资：执行循环、GraphRAG与Docker部署实战

1. 从“10 天手搓”说起：这个项目到底做对了什么

第一次看到“10 天手搓一个开源项目，拿到 3000 万投资”这个说法，我的第一反应不是羡慕，而是好奇：10 天能写出来的东西，凭什么值这个价？后来把项目背景、技术路线和当时的行业环境捋了一遍，我才意识到，真正被投的从来不是那 10 天的代码量，而是那 10 天里被验证的一个判断——Agent 这条路线，在 2023 年下半年那个时间点，需要一个足够轻、足够开放、足够快能跑起来的落地样本。

这个项目最核心的关键词是Agent。很多人第一次接触 Agent 会把它和普通的聊天机器人混为一谈，其实差别很大。普通对话模型是“你问一句，它答一句”，而 Agent 是“你给一个目标，它自己拆解步骤、调用工具、观察结果、再决定下一步”。这中间多出来的“循环”和“工具调用”，才是 Agent 的灵魂。项目能在短时间内跑通，靠的不是模型本身多强，而是把Agent 的执行循环、工具注册机制、上下文管理这三件事用最朴素的方式串了起来。

我后来复盘过很多类似的开源项目，发现一个规律：能在 GitHub 上快速起量的 Agent 项目，往往不是功能最全的，而是“最小可运行闭环”做得最干净的。你 clone 下来，配一个模型 API Key，几分钟内就能看到一个 Agent 真的在帮你查资料、写文件、执行命令。这种“即时正反馈”是 star 数暴涨的直接推手。7.4 万星不是靠文档堆出来的，是靠无数人第一次跑通时的那句“卧槽，它真的自己动了”。

那 3000 万投资看中的是什么？我的判断是三点：第一，验证了 Agent 在真实任务中的可用性，不是 demo 级别的玩具；第二，项目结构足够开放，别人可以基于它快速二次开发，形成生态；第三，团队在极短时间内展现出的工程判断力，知道什么该做、什么先不做。这三点里，第三点最值钱，也最容易被忽略。10 天手搓不是炫技，是在资源极度受限的情况下，把力气全花在了刀刃上。

如果你现在也想做一个 Agent 相关的开源项目，或者想理解这类项目为什么能火，我建议你别一上来就研究它的架构图。先问自己一个问题：我的 Agent 能不能在 5 分钟内让一个陌生人看到它“自己干活”的样子？如果答案是否定的，那再漂亮的架构也换不来第一波传播。

2. Agent 的执行循环：拆开看就是“想、做、看”三步

2.1 为什么大多数 Agent 项目死在“循环”上

Agent 的核心是一个循环，但这个循环写起来容易，写对很难。我见过太多项目，第一版跑起来很惊艳，多轮对话几轮之后就崩了：要么陷入死循环反复调用同一个工具，要么上下文爆炸把 token 烧光，要么工具报错之后 Agent 完全不知道怎么处理。这些问题的根子，都在于循环的退出条件和状态管理没设计好。

一个健康的 Agent 循环，我习惯把它拆成三步：想（Reason）、做（Act）、看（Observe）。想，是模型根据当前目标和历史信息，决定下一步该干什么；做，是执行选定的工具或动作；看，是把执行结果拿回来，更新状态，再进入下一轮“想”。听起来简单，但每一步都有坑。

“想”这一步最大的坑是目标漂移。模型在多轮之后容易忘记最初的任务是什么，开始自己给自己加戏。解决办法是在每一轮“想”的时候，都把原始目标重新注入上下文，并且明确告诉它“你现在的进度是什么，还差什么”。这听起来很笨，但实测下来比任何花哨的记忆机制都稳。

“做”这一步的坑是工具选择错误。模型可能选了一个参数不对的工具，或者该用 A 工具的时候用了 B。我的经验是，工具的描述要写得极其具体，包括什么时候用、什么时候不用、参数格式是什么、常见错误是什么。你写得越像给一个新员工看的操作手册，模型选错的概率就越低。

“看”这一步最容易被忽视。很多人把工具返回结果直接塞回上下文就完事了，但结果里可能包含大量无关信息，甚至包含错误信息。正确的做法是对观察结果做一次过滤和摘要，只把和当前目标相关的部分喂回去。这一步做得好，token 消耗能降一半以上。

2.2 一个最小可运行的循环长什么样

下面这段伪代码是我自己常用的骨架，去掉了所有花哨的东西，只保留最核心的循环逻辑。你可以把它当成一个模板，往里面填自己的工具和模型调用。

def run_agent(goal, tools, max_steps=10): context = [{"role": "system", "content": SYSTEM_PROMPT}] context.append({"role": "user", "content": f"目标：{goal}"}) for step in range(max_steps): # 想：让模型决定下一步 decision = llm.chat(context, tools=tools) # 如果模型认为任务完成，退出循环 if decision.type == "finish": return decision.answer # 做：执行工具 tool_name = decision.tool_name tool_args = decision.tool_args result = tools[tool_name].run(**tool_args) # 看：把结果过滤后放回上下文 observation = summarize(result, goal) context.append({"role": "assistant", "content": decision.raw}) context.append({"role": "tool", "content": observation}) return "达到最大步数，任务未完成"

这段代码里，max_steps是保命用的，防止无限循环。summarize那一步是很多人省掉的，但恰恰是省掉之后最容易出问题。我自己的经验是，观察结果超过 500 字就必须做摘要，否则几轮下来上下文就满了。

还有一个细节：decision.type == "finish"这个判断，不能只靠模型自己说“我完成了”。更稳的做法是加一个验证步骤，比如让另一个模型调用或者用规则检查一下目标是否真的达成。我踩过的坑是，模型经常在任务只完成一半的时候就说“已完成”，然后循环退出，用户拿到一个半成品。

2.3 循环里的状态到底该存什么

状态管理是 Agent 项目里最不性感但最要命的部分。我见过有人把所有东西都塞进对话历史，结果 token 爆炸；也有人什么都不存，每轮都从零开始，结果 Agent 像个失忆症患者。

我的做法是把状态分成三层：目标层、进度层、工具层。目标层只存原始目标和当前子目标，永远不丢；进度层存已经完成了哪些步骤、当前卡在哪里；工具层存最近几次工具调用的结果摘要。这三层分开管理，每轮只把必要的部分注入上下文，既不会丢信息，也不会撑爆窗口。

具体到实现上，我一般用一个字典来存状态，每轮循环开始时根据状态生成上下文，循环结束时更新状态。这样即使对话历史被截断，核心状态也不会丢。这个思路在长任务场景下特别重要，比如让 Agent 帮你调研一个话题、写一份报告，没有状态管理根本跑不完。

3. GraphRAG 的引入：为什么 Agent 需要“知识地图”

3.1 从“检索片段”到“检索关系”

Agent 要干活，光有循环不够，还得有知识。早期的做法是 RAG（检索增强生成），把文档切块、向量化、按相似度检索。这套方法在“问答”场景下够用，但在“任务执行”场景下就露怯了。因为任务往往需要多跳推理：A 和 B 有关，B 和 C 有关，所以 A 和 C 也有关。向量检索只能找到和问题最相似的片段，找不到这种关系链。

GraphRAG 就是来解决这个问题的。它把知识组织成图结构，节点是实体，边是关系。检索的时候不是找“最相似的文本块”，而是找“和当前目标相关的子图”。这样一来，Agent 就能沿着关系链一路查下去，而不是每次只看到一个孤立的片段。

我举个具体的例子。假设你让 Agent 帮你分析“某公司的供应链风险”。传统 RAG 会检索出所有提到这家公司的文档片段，可能包括财报、新闻、公告。但 GraphRAG 会构建出“公司—供应商—原材料—产地”这样的关系图，Agent 可以顺着图去查：这家公司的关键供应商是谁，供应商的原材料来自哪里，那个产地最近有没有风险事件。这种结构化推理能力，是 Agent 从“玩具”走向“工具”的关键一步。

3.2 构建知识图谱时最容易踩的三个坑

第一个坑是实体消歧。同一个东西在不同文档里可能有不同叫法，比如“苹果公司”和“Apple Inc.”，如果不做归一化，图谱里就会出现两个节点，关系链就断了。我的做法是建一个别名词典，在抽取实体的时候做映射。这个词典不用很全，覆盖高频实体就行，剩下的靠人工补。

第二个坑是关系抽取的粒度。抽得太细，图谱会变得极其稀疏，查两跳就查不到东西了；抽得太粗，又丢失了关键信息。我的经验是，关系粒度要匹配你的查询场景。如果你主要做供应链分析，那就重点抽“供应、采购、合作”这类关系；如果你做人物关系分析，那就重点抽“任职、投资、校友”这类关系。不要试图一次抽全，按场景来。

第三个坑是图谱更新。知识是动态的，今天的关系明天可能就变了。如果图谱不能增量更新，很快就会过时。我的做法是给每条边加时间戳，查询的时候默认只查最近 N 天的边，同时保留一个后台任务定期做全量重建。这样既能保证时效性，又不会因为频繁更新把系统拖垮。

3.3 GraphRAG 和 Agent 怎么配合才不别扭

GraphRAG 和 Agent 的配合，关键在于把图查询封装成 Agent 的一个工具。Agent 不需要知道图谱长什么样，它只需要知道“我有一个工具叫 query_graph，输入是实体名和关系类型，输出是相关的子图”。这样 Agent 的循环逻辑不用改，只是多了一个更强的工具而已。

我自己的实现里，query_graph工具会返回一个结构化的结果，包括节点列表、边列表和每个节点的属性摘要。Agent 拿到之后，可以决定是继续沿着某条边查下去，还是把当前结果整合进答案。这种按需展开的方式，比一次性把整个图谱塞进上下文要高效得多。

还有一个细节：图查询的结果往往比较大，直接塞回上下文会爆。我的做法是让query_graph工具自己先做一次摘要，只返回和当前目标最相关的 top-k 条边和节点。这个摘要逻辑可以用规则做，也可以用一个小模型做，看你的资源情况。

4. Docker 部署：让 Agent 项目“开箱即跑”的关键

4.1 为什么 Agent 项目特别需要 Docker

Agent 项目和普通 Web 项目不一样，它往往依赖一堆外部服务：模型 API、向量数据库、图数据库、各种工具的运行环境。如果让用户自己一个个装，光是环境配置就能劝退 90% 的人。Docker 的价值在这里就体现出来了：把整个运行环境打包成一个镜像，用户一条命令就能跑起来。

我自己的项目从“手动部署”切换到“Docker Compose 一键启动”之后，issue 里关于环境问题的提问直接少了七成。这不是夸张，是真实数据。因为 Agent 项目涉及的东西太多，Python 版本、依赖冲突、系统库缺失，任何一个环节出问题都会让用户卡住。Docker 把这些不确定性全部封在镜像里，用户只需要关心“怎么用”，不需要关心“怎么装”。

4.2 一个 Agent 项目的 Docker Compose 该怎么写

下面这个 compose 文件是我常用的模板，包含 Agent 主服务、向量数据库和图数据库三个部分。你可以根据自己的技术栈替换具体镜像。

version: "3.8" services: agent: build: . ports: - "8000:8000" environment: - MODEL_API_KEY=${MODEL_API_KEY} - VECTOR_DB_URL=http://vector-db:6333 - GRAPH_DB_URL=http://graph-db:7474 depends_on: - vector-db - graph-db volumes: - ./data:/app/data vector-db: image: qdrant/qdrant:latest ports: - "6333:6333" volumes: - ./qdrant_data:/qdrant/storage graph-db: image: neo4j:5 ports: - "7474:7474" - "7687:7687" environment: - NEO4J_AUTH=neo4j/password volumes: - ./neo4j_data:/data

这个文件里有几个细节值得说。第一，MODEL_API_KEY用环境变量注入，不要写死在代码里，也不要在 compose 里硬编码，让用户自己配。第二，depends_on只保证启动顺序，不保证服务就绪，所以 Agent 服务里要有重试逻辑，等数据库真正可用再开始工作。第三，数据卷一定要挂出来，否则容器一删数据就没了，用户会疯。

4.3 部署时最常见的三个报错和排查思路

第一个报错是“virtualization support not detected”。这个在 Windows 上特别常见，原因是 Docker Desktop 需要开启硬件虚拟化，而很多电脑默认是关的。排查思路：进 BIOS 找 Intel VT-x 或 AMD-V 选项，打开它。如果 BIOS 里找不到，可能是系统层面的 Hyper-V 冲突，需要检查 Windows 功能里 Hyper-V 和 WSL2 的状态。

第二个报错是“docker desktop failed to start”。这个原因很多，最常见的是 WSL2 内核版本太旧。排查思路：先跑wsl --update更新内核，然后重启 Docker Desktop。如果还不行，检查一下是不是杀毒软件拦截了 Docker 的虚拟网卡，把 Docker 加入白名单。

第三个报错是“访问 docker 容器内的 mysql 失败”。这个在 Agent 项目里也常见，因为很多工具需要连数据库。排查思路：先确认容器内的服务真的起来了，用docker exec -it 容器名 bash进去，跑mysql -u root -p试试。如果容器内能连、宿主机连不上，那就是端口映射或者网络模式的问题，检查 compose 里的ports配置和network_mode。

提示：Docker 相关的报错，九成以上是环境问题，不是代码问题。遇到报错先别改代码，先确认 Docker 本身是不是正常运行的。

5. 从 7.4 万星到 3000 万：开源项目的传播逻辑

5.1 第一波 star 从哪来

开源项目的 star 增长不是线性的，它更像是一个触发式传播。第一波 star 往往来自一个很小的圈子：可能是某个技术群里的分享，可能是某个大 V 的一条推文，也可能是 Hacker News 上的一个帖子。这个阶段的关键不是项目多完美，而是有没有一个让人愿意转发的点。

这个项目的转发点很明确：“10 天手搓”加上“3000 万投资”。前者是技术圈喜欢的故事，后者是大众喜欢的故事。两个故事叠在一起，就形成了跨圈层的传播。我观察过很多爆款开源项目，发现它们都有一个共同特征：能用一句话说清楚，而且这句话里有反差。“10 天”和“3000 万”就是反差，“大学生”和“盛大投资”也是反差。

但反差只是引子，真正留住人的还是项目本身能跑。如果用户点进来发现跑不起来，star 会涨得快掉得也快。所以第一波传播之后，项目的“首次运行体验”决定了它能不能留住这波流量。这也是为什么 Docker 部署、一键脚本这些东西在开源项目里这么重要，它们直接决定了转化率。

5.2 第二波增长靠什么

第一波靠故事，第二波靠生态。当有人开始基于你的项目做二次开发、写教程、提 PR 的时候，项目就进入了自增长阶段。这个阶段的关键是降低贡献门槛：issue 模板要清晰，PR 流程要简单，文档要告诉别人“你可以从哪里开始改”。

我自己的经验是，一个项目如果有 10 个活跃贡献者，它的 star 增长速度会比只有 1 个维护者快 3 到 5 倍。因为每个贡献者都会在自己的圈子里传播，而且他们产出的内容（教程、插件、案例）会持续吸引新用户。这个项目能拿到投资，很大程度上也是因为它在短时间内形成了初步的生态，而不是只有一个孤零零的仓库。

5.3 投资方到底在看什么

很多人以为投资方看的是技术，其实技术只是门槛。真正决定投不投的，是这个项目有没有可能成为一个平台。Agent 这个方向之所以被看好，是因为它有机会成为“AI 应用的操作系统”：上面跑着各种工具，下面连着各种模型，中间是 Agent 的调度逻辑。谁定义了这个调度逻辑，谁就有机会拿到生态位。

这个项目在 10 天内做出来的东西，恰好展示了这个生态位的雏形：一个开放的 Agent 框架，加上 GraphRAG 的知识层，再加上 Docker 的部署方案。这三样东西合在一起，就是一个“最小可用的平台”。投资方投的不是代码，是这个平台的可能性。

当然，从开源项目到商业公司，中间还有很长的路。我见过太多明星项目拿了投资之后反而沉寂了，原因是开源社区的节奏和商业公司的节奏不一样。开源要快、要开放、要听社区的声音；商业要稳、要聚焦、要对股东负责。这两者之间的平衡，是每个开源创业者都要面对的难题。

6. 如果你想复现一个类似的 Agent 项目

6.1 技术选型上的几个关键决策

如果你现在想从零做一个 Agent 项目，我建议你在选型上做几个明确的决策。第一，模型用 API 还是本地部署？如果目标是快速验证和传播，用 API，因为用户不需要显卡就能跑。如果目标是隐私和成本控制，本地部署，但要做好用户被环境劝退的准备。第二，知识层用向量还是图？如果任务以问答为主，向量够用；如果任务需要多跳推理，上图。第三，部署用 Docker 还是裸机？只要你想让别人快速跑起来，Docker 是唯一选择。

这几个决策没有绝对的对错，但一定要和你的目标匹配。我见过有人为了“技术先进”上了图数据库，结果用户连 Docker 都装不明白，项目根本传播不出去。也见过有人为了“简单”只用向量，结果任务稍微复杂一点就歇菜。选型的本质是取舍，想清楚你要什么，再决定放弃什么。

6.2 从最小闭环开始，别一上来就做平台

我踩过最大的坑，就是一开始就想做一个“通用 Agent 平台”，结果三个月过去连一个能跑的任务都没有。后来我把目标砍到最小：只做一个任务，只支持一个工具，只跑通一条链路。结果两天就做出来了，而且因为能跑，反而吸引了一批早期用户。

这个经验我想反复强调：Agent 项目的价值不在于支持多少工具，而在于能不能把一个任务从头到尾跑完。你先做一个“查天气”的 Agent，把它做到极致稳定，比做一个支持一百个工具但每个都跑不通的 Agent 有价值得多。用户要的是“能用”，不是“看起来什么都能”。

6.3 文档和示例比代码更重要

最后说一个反直觉的点：在开源 Agent 项目里，文档和示例的重要性不亚于代码本身。因为 Agent 是一个新概念，很多人不知道它能干什么、该怎么用。如果你的 README 里只有一段安装说明，用户装完就不知道该干嘛了。

我的做法是，README 里至少放三个完整的示例：一个最简单的（比如查天气），一个中等复杂的（比如读文件并总结），一个展示 Agent 特色的（比如多步推理）。每个示例都要有完整的输入输出，让用户能直接复制粘贴跑起来。这三个示例写好了，项目的可用性会提升一个档次。

注意：示例不要用“Hello World”这种没有实际意义的任务。用真实场景，哪怕简单一点，用户才能感受到 Agent 的价值。

7. 一些实操中的零碎经验

关于 Agent 的 token 消耗，我自己的经验是大部分浪费在无效的上下文重复上。每一轮循环都把完整历史塞进去，几轮下来 token 就爆了。解决办法是只保留最近 N 轮，加上一个状态摘要。这个摘要可以每轮更新，用一个小模型生成，成本很低。

关于工具的设计，我建议每个工具只做一件事，而且要把这件事做到极致。不要设计一个“万能工具”，参数一大堆，模型根本不知道怎么填。工具越简单、越专注，模型选对的概率越高。我自己的项目里，工具数量控制在 10 个以内，每个工具的参数不超过 3 个。

关于错误处理，Agent 和普通程序最大的区别是它必须能自己从错误中恢复。工具报错之后，不能直接把错误抛给用户，而要把错误信息喂回给模型，让它决定是重试、换工具还是放弃。这个“错误恢复循环”是 Agent 鲁棒性的关键，也是很多项目忽略的地方。

关于测试，Agent 的测试比普通程序难得多，因为输出是不确定的。我的做法是用规则做断言，而不是用精确匹配。比如测试“查天气”的 Agent，不检查它返回的具体温度，而是检查它有没有调用天气工具、有没有返回一个合理的温度范围。这样既能保证功能正确，又不会因为模型输出的随机性导致测试失败。

关于社区运营，我最大的体会是回复 issue 的速度比回复的质量更重要。用户提了一个问题，你哪怕只回一句“我看看”，也比三天不回要好。因为用户提 issue 的时候是有热情的，你拖三天，热情就没了。这个项目能在短时间内起量，和团队对社区的响应速度肯定有关系。

最后说一个心态上的经验。做开源 Agent 项目，不要追求一步到位，要追求持续迭代。第一版能跑就行，第二版修 bug，第三版加功能，第四版优化体验。每一版都发一个 release，让用户看到项目在动。一个持续更新的项目，比一个完美但半年不动的项目，生命力强得多。