一句话MyCodeAgent 是一个「用来学习」的 AI 编码代理框架。它不打算跟商业产品比谁更能打而是把 Claude Code 那类工具的核心机制——工具调用、上下文压缩、子代理协作、行为追踪——做成了一份能读、能改、能跑的开源代码。我是怎么遇到这个项目的我最近在折腾 AI 编码助手就是你让 AI 帮你看代码、改文件的那种工具。用是会用但一直有个说不清的疑问它底层到底是怎么「调工具」的上下文动辄上万字它是怎么塞进模型窗口的为什么有的 Agent 你能看清它干了啥有的就跟黑盒子一样碰巧在 GitHub 上翻到一个叫MyCodeAgent的项目。它的副标题很直白——Claude Code like agent for study一个用来学习的、类似 Claude Code 的 Agent。我点进去读了一圈文档发现它正好补上了我想看的「内部课」。所以这篇文章算是我的阅读笔记顺手分享给同样想「看懂 Agent 内部」的朋友。文末我也整理了一张名词速查表看晕了直接翻到底。配图说明上图是整体概念——一个终端旁边飘着「搜索 / 读文件 / 执行命令」等工具图标下面几张图会分别拆解里面的关键机制。它到底是个啥先说人话你可以把它理解成一个「教学版」的 AI 编码助手。市面上那种能帮你写代码的 AI 工具底层逻辑其实都差不多模型思考 → 决定调哪个工具读文件、跑命令…→ 拿到结果 → 再思考 → 直到任务完成。MyCodeAgent 把这个循环完整实现了一遍而且刻意把每一步都写得很清楚方便你改、方便你 Debug。它重点放在四件事上工具协议工具怎么定义、怎么被调用、返回结果长啥样让行为可预期、可调试上下文工程对话和工具输出那么长怎么截断、压缩、存盘控制 token模型的「字数单位」和成本子代理机制Skills、Task 子代理、AgentTeams 怎么分工协作可观测性它干了啥、为啥这么干能不能被「回放」出来看。一句话总结作者想做的事让「Agent 能做什么」和「Agent 为什么能这么做」都变得可追溯、可验证、可扩展。谁适合看这个项目不是所有人都适合。从 README 和它致谢的开源项目HelloAgent、Kode-Cli、Mini-Agent、opencode 等来看它的目标用户很明确想搞懂Function Calling函数调用和工具协议到底怎么真实落地的开发者研究上下文工程截断、压缩、存盘的工程师或学生想拿它当「试验场」做 Skills / Task 子代理协作实验的 Agent 开发者想本地快速搭一个能换模型、能接外部工具的可扩展 Agent 的人。如果你只是想「找个能用的 AI 写代码工具」那直接上成熟产品更省事。它是教具不是成品。核心特性我挑重点说1. 工具调用走 Function Calling不靠「读小作文」很多早期的 Agent 玩法是让模型输出一段Action: xxx这样的文本程序再去正则解析。这法子容易翻车——模型偶尔写错格式就挂了。MyCodeAgent 用的是Function Calling模型直接输出结构化的「函数名 参数」程序照着执行。类比一下你跟助手说「去查下天气」它不写小作文而是直接填一张查天气(城市北京)的表单递给你。稳定、可预期、还能追溯。而且它给所有工具定了一套统一响应协议返回里通常含这些字段status成功还是失败data/text结构化的结果或文本结果stats/context统计信息或上下文error出错信息这套格式的好处是前端展示、日志落盘、后续重试 / 熔断连续失败就先停用该工具都能用同一套逻辑处理。配图说明模型大脑和工具齿轮之间用一个个干净的数据包来回传这就是 Function Calling 统一协议的样子。2. 上下文工程长内容怎么「瘦身」这是我觉得最值得学的一块。上下文喂给模型的历史对话 工具输出太长会爆窗口、烧钱。它的处理思路分层注入系统提示、工具说明、历史消息分层组织控制进上下文的内容历史压缩历史太长时按策略压缩比如做摘要、截断相关环境变量CONTEXT_WINDOW上下文窗口大小、COMPRESSION_THRESHOLD压缩阈值比如 0.8 表示用到 80% 就开始压file 强制读取你用文件名引用时保证那段内容一定进上下文就像你跟助手说「先看这份文件」超限落盘单次工具输出太长时主体截断保留头 / 尾 / 头尾超出的部分写到tool-output/目录里而不是全塞进对话。打个比方上下文窗口就像一个容量有限的「工作台」。东西太多放不下时它先把旧的整理成摘要压缩实在放不下的挪到旁边的文件柜tool-output/目录里需要时再取。配图说明一长串文本流过「漏斗」被压缩进小窗口溢出的部分落到硬盘图标上——这就是压缩 落盘。3. 内置工具够日常用开箱自带这些工具基本覆盖文件操作和命令执行LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser日常看目录、搜文件、读改写代码、跑命令、记待办都能直接上手。4. 可观测性它干了啥能「回放」这点对我挺重要——能看见 Agent 的决策过程才算真的能学。它用JSONL HTML 双轨 TraceTrace 就是「行为轨迹日志」一条条记录每次交互、每次工具调用可选脱敏怕把密钥记进去可选把原始模型响应也存下来方便复盘还有 token 统计、工具调用树配合 CLI 里的工具调用树和进度显示看得很清楚。配图说明一棵由调用节点连成的「树 / 时间线」就是 Trace 想把行为讲清楚的样子。5. Skills 和 Task 子代理Skills技能约定放在skills/技能名/SKILL.md。SKILL.md里写技能说明$ARGUMENTS会被实际参数替换然后整段注入上下文。相当于给 Agent 准备一本「操作手册」随时翻。一个SKILL.md长这样--- name: code-review description: Review code quality and risks --- # Code Review Use this checklist: - ... $ARGUMENTSTask 子代理有 general / explore / plan / summary 等类型对应不同复杂度的子任务。子代理可以配轻量模型省钱也能配成只读或受限工具集保证安全。6. AgentTeams实验性默认关这块我得提醒一句README 里标了「实验性」默认是关的要开得设ENABLE_AGENT_TEAMStrue。开了之后能玩多角色协作TeamCreate建个团队SendMessage互相发消息TeamStatus看状态TeamDelete解散Task 有三种模式oneshot一次性子任务默认、persistent建个常驻队友、parallel一次性派发多个任务并行干TeamFanout/TeamCollect做「广播分工 收结果」。最小玩法大概是建个 team → 派个常驻 dev 队友 → 发消息安排活 → 看状态 → 干完解散。配图说明几个 Agent 节点互相发消息、并行干活就是 AgentTeams 想支撑的协作形态。小提示因为这是实验特性且项目本身迭代挺快真要试建议先去看一眼仓库最新 README确认当前版本还支持哪些。跟「黑盒产品 / 纯 Demo」比它强在哪我用表格简单对比下方便你判断要不要看对比项MyCodeAgent纯黑盒 Agent 产品仅 Demo 型项目工具协议统一响应协议 Function Calling多为内部实现看不到常没规范上下文工程截断 / 压缩 / 落盘 / file 可配置多不可见简单或缺失可观测性Trace JSONL/HTML、可脱敏、有统计有限或无多是 print子代理 / 协作Skills Task AgentTeams看产品心情少有文档协议 / 上下文 / 截断 / Trace / Skill / Task 都有专文多是使用说明较少定位学习与实验生产 / 产品演示为主说白了如果你想「会用 Agent」用产品就行如果你想「会做 Agent」这个项目更对路。怎么跑起来附真实命令环境要求Python 3.8装个pip就行。# 克隆 git clone https://github.com/YYHDBL/MyCodeAgent.git cd MyCodeAgent # 虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # .\venv\Scripts\activate # Windows # 装依赖 pip install -r requirements.txt配置复制或新建.env按需填# LLM export OPENAI_API_KEYyour-api-key export DEFAULT_MODELgpt-4 export TEMPERATURE0.7 # AgentTeams可选默认关闭 export ENABLE_AGENT_TEAMStrue # 上下文 export CONTEXT_WINDOW128000 export COMPRESSION_THRESHOLD0.8跑交互式命令行python scripts/chat_test_agent.py想换个模型 / 供应商比如智谱也行python scripts/chat_test_agent.py \ --provider zhipu \ --model GLM-4.7 \ --api-key YOUR_API_KEY \ --base-url https://open.bigmodel.cn/api/coding/paas/v4想看原始输出方便调试python scripts/chat_test_agent.py --show-raw注上面是文章材料里给的命令。我刚顺手看了眼仓库现在的 README把它做成了更「精简」的运行时默认只有 7 个工具、默认不启用 MCP 和 AgentTeams启动命令变成了mycodeagent。所以具体以你 clone 下来的那版 README 为准别照搬上面命令发现跑不通就懵了。几个我能记住的「数字」仓库状态79 commits还在持续维护LicenseMIT随便改、随便二次开发文档仓库docs/下有一堆专文——工具协议、上下文工程、截断、Trace、Task、Skill、交接说明都有。热度参考材料里提到 GitHub 上大约 100 Star、20 Fork看个大致活跃度就行别当回事。技术栈Python 3.x用到了 openai / pydantic / mcp / anyio、rich / prompt_toolkit后两个是负责命令行界面好看的。想接外部工具有 MCP 口子如果你想让它用上 GitHub、数据库之类的外部能力可以在根目录放个mcp_servers.json配置以命令方式拉起 MCP 服务MCP 就是给 AI 接外部工具的开放标准相当于给 Agent 装 USB 接口。{ mcpServers: { example: { command: npx, args: [-y, some-mcp-server, --api-key, ${API_KEY}] } } }配好之后Agent 就能用这个 MCP 提供的工具了。相关资源GitHubgithub.com/YYHDBL/MyCodeAgent文档都在仓库docs/里Issue 反馈GitHub Issues。名词速查表看晕了翻这里Function Calling / 函数调用让模型直接输出「函数名 参数」这种结构化指令程序照着执行而不是去解析一段自然语言。类比填表单而不是写小作文。上下文Context/ 上下文窗口喂给模型的所有内容对话历史 工具输出。窗口是有限容量的超了要么压缩要么落盘。Token令牌模型计费 / 计算长度的「字数单位」中文里大概 1~2 个字算一个。MCPModel Context Protocol给 AI 接外部工具 / 数据的开放标准相当于 Agent 的「USB 接口」。Trace轨迹日志记录 Agent 每一步行为调用了啥工具、花了多久、用了多少 token的日志用来回放和排查。Skill技能放在skills/名/SKILL.md的操作手册需要时注入上下文。Subagent / 子代理主代理派出去干子任务的小代理可配轻量模型或受限权限。AgentTeams实验性的多角色协作机制能建团队、互发消息、并行派活默认关闭。 
长河君 · 2026/10/10 6:11:12 · 阅读 1.2k 想搞懂 AI 编码助手内部是怎么跑起来的？这个开源项目把 Claude Code 的套路拆开了
一句话MyCodeAgent 是一个「用来学习」的 AI 编码代理框架。它不打算跟商业产品比谁更能打而是把 Claude Code 那类工具的核心机制——工具调用、上下文压缩、子代理协作、行为追踪——做成了一份能读、能改、能跑的开源代码。我是怎么遇到这个项目的我最近在折腾 AI 编码助手就是你让 AI 帮你看代码、改文件的那种工具。用是会用但一直有个说不清的疑问它底层到底是怎么「调工具」的上下文动辄上万字它是怎么塞进模型窗口的为什么有的 Agent 你能看清它干了啥有的就跟黑盒子一样碰巧在 GitHub 上翻到一个叫MyCodeAgent的项目。它的副标题很直白——Claude Code like agent for study一个用来学习的、类似 Claude Code 的 Agent。我点进去读了一圈文档发现它正好补上了我想看的「内部课」。所以这篇文章算是我的阅读笔记顺手分享给同样想「看懂 Agent 内部」的朋友。文末我也整理了一张名词速查表看晕了直接翻到底。配图说明上图是整体概念——一个终端旁边飘着「搜索 / 读文件 / 执行命令」等工具图标下面几张图会分别拆解里面的关键机制。它到底是个啥先说人话你可以把它理解成一个「教学版」的 AI 编码助手。市面上那种能帮你写代码的 AI 工具底层逻辑其实都差不多模型思考 → 决定调哪个工具读文件、跑命令…→ 拿到结果 → 再思考 → 直到任务完成。MyCodeAgent 把这个循环完整实现了一遍而且刻意把每一步都写得很清楚方便你改、方便你 Debug。它重点放在四件事上工具协议工具怎么定义、怎么被调用、返回结果长啥样让行为可预期、可调试上下文工程对话和工具输出那么长怎么截断、压缩、存盘控制 token模型的「字数单位」和成本子代理机制Skills、Task 子代理、AgentTeams 怎么分工协作可观测性它干了啥、为啥这么干能不能被「回放」出来看。一句话总结作者想做的事让「Agent 能做什么」和「Agent 为什么能这么做」都变得可追溯、可验证、可扩展。谁适合看这个项目不是所有人都适合。从 README 和它致谢的开源项目HelloAgent、Kode-Cli、Mini-Agent、opencode 等来看它的目标用户很明确想搞懂Function Calling函数调用和工具协议到底怎么真实落地的开发者研究上下文工程截断、压缩、存盘的工程师或学生想拿它当「试验场」做 Skills / Task 子代理协作实验的 Agent 开发者想本地快速搭一个能换模型、能接外部工具的可扩展 Agent 的人。如果你只是想「找个能用的 AI 写代码工具」那直接上成熟产品更省事。它是教具不是成品。核心特性我挑重点说1. 工具调用走 Function Calling不靠「读小作文」很多早期的 Agent 玩法是让模型输出一段Action: xxx这样的文本程序再去正则解析。这法子容易翻车——模型偶尔写错格式就挂了。MyCodeAgent 用的是Function Calling模型直接输出结构化的「函数名 参数」程序照着执行。类比一下你跟助手说「去查下天气」它不写小作文而是直接填一张查天气(城市北京)的表单递给你。稳定、可预期、还能追溯。而且它给所有工具定了一套统一响应协议返回里通常含这些字段status成功还是失败data/text结构化的结果或文本结果stats/context统计信息或上下文error出错信息这套格式的好处是前端展示、日志落盘、后续重试 / 熔断连续失败就先停用该工具都能用同一套逻辑处理。配图说明模型大脑和工具齿轮之间用一个个干净的数据包来回传这就是 Function Calling 统一协议的样子。2. 上下文工程长内容怎么「瘦身」这是我觉得最值得学的一块。上下文喂给模型的历史对话 工具输出太长会爆窗口、烧钱。它的处理思路分层注入系统提示、工具说明、历史消息分层组织控制进上下文的内容历史压缩历史太长时按策略压缩比如做摘要、截断相关环境变量CONTEXT_WINDOW上下文窗口大小、COMPRESSION_THRESHOLD压缩阈值比如 0.8 表示用到 80% 就开始压file 强制读取你用文件名引用时保证那段内容一定进上下文就像你跟助手说「先看这份文件」超限落盘单次工具输出太长时主体截断保留头 / 尾 / 头尾超出的部分写到tool-output/目录里而不是全塞进对话。打个比方上下文窗口就像一个容量有限的「工作台」。东西太多放不下时它先把旧的整理成摘要压缩实在放不下的挪到旁边的文件柜tool-output/目录里需要时再取。配图说明一长串文本流过「漏斗」被压缩进小窗口溢出的部分落到硬盘图标上——这就是压缩 落盘。3. 内置工具够日常用开箱自带这些工具基本覆盖文件操作和命令执行LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser日常看目录、搜文件、读改写代码、跑命令、记待办都能直接上手。4. 可观测性它干了啥能「回放」这点对我挺重要——能看见 Agent 的决策过程才算真的能学。它用JSONL HTML 双轨 TraceTrace 就是「行为轨迹日志」一条条记录每次交互、每次工具调用可选脱敏怕把密钥记进去可选把原始模型响应也存下来方便复盘还有 token 统计、工具调用树配合 CLI 里的工具调用树和进度显示看得很清楚。配图说明一棵由调用节点连成的「树 / 时间线」就是 Trace 想把行为讲清楚的样子。5. Skills 和 Task 子代理Skills技能约定放在skills/技能名/SKILL.md。SKILL.md里写技能说明$ARGUMENTS会被实际参数替换然后整段注入上下文。相当于给 Agent 准备一本「操作手册」随时翻。一个SKILL.md长这样--- name: code-review description: Review code quality and risks --- # Code Review Use this checklist: - ... $ARGUMENTSTask 子代理有 general / explore / plan / summary 等类型对应不同复杂度的子任务。子代理可以配轻量模型省钱也能配成只读或受限工具集保证安全。6. AgentTeams实验性默认关这块我得提醒一句README 里标了「实验性」默认是关的要开得设ENABLE_AGENT_TEAMStrue。开了之后能玩多角色协作TeamCreate建个团队SendMessage互相发消息TeamStatus看状态TeamDelete解散Task 有三种模式oneshot一次性子任务默认、persistent建个常驻队友、parallel一次性派发多个任务并行干TeamFanout/TeamCollect做「广播分工 收结果」。最小玩法大概是建个 team → 派个常驻 dev 队友 → 发消息安排活 → 看状态 → 干完解散。配图说明几个 Agent 节点互相发消息、并行干活就是 AgentTeams 想支撑的协作形态。小提示因为这是实验特性且项目本身迭代挺快真要试建议先去看一眼仓库最新 README确认当前版本还支持哪些。跟「黑盒产品 / 纯 Demo」比它强在哪我用表格简单对比下方便你判断要不要看对比项MyCodeAgent纯黑盒 Agent 产品仅 Demo 型项目工具协议统一响应协议 Function Calling多为内部实现看不到常没规范上下文工程截断 / 压缩 / 落盘 / file 可配置多不可见简单或缺失可观测性Trace JSONL/HTML、可脱敏、有统计有限或无多是 print子代理 / 协作Skills Task AgentTeams看产品心情少有文档协议 / 上下文 / 截断 / Trace / Skill / Task 都有专文多是使用说明较少定位学习与实验生产 / 产品演示为主说白了如果你想「会用 Agent」用产品就行如果你想「会做 Agent」这个项目更对路。怎么跑起来附真实命令环境要求Python 3.8装个pip就行。# 克隆 git clone https://github.com/YYHDBL/MyCodeAgent.git cd MyCodeAgent # 虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # .\venv\Scripts\activate # Windows # 装依赖 pip install -r requirements.txt配置复制或新建.env按需填# LLM export OPENAI_API_KEYyour-api-key export DEFAULT_MODELgpt-4 export TEMPERATURE0.7 # AgentTeams可选默认关闭 export ENABLE_AGENT_TEAMStrue # 上下文 export CONTEXT_WINDOW128000 export COMPRESSION_THRESHOLD0.8跑交互式命令行python scripts/chat_test_agent.py想换个模型 / 供应商比如智谱也行python scripts/chat_test_agent.py \ --provider zhipu \ --model GLM-4.7 \ --api-key YOUR_API_KEY \ --base-url https://open.bigmodel.cn/api/coding/paas/v4想看原始输出方便调试python scripts/chat_test_agent.py --show-raw注上面是文章材料里给的命令。我刚顺手看了眼仓库现在的 README把它做成了更「精简」的运行时默认只有 7 个工具、默认不启用 MCP 和 AgentTeams启动命令变成了mycodeagent。所以具体以你 clone 下来的那版 README 为准别照搬上面命令发现跑不通就懵了。几个我能记住的「数字」仓库状态79 commits还在持续维护LicenseMIT随便改、随便二次开发文档仓库docs/下有一堆专文——工具协议、上下文工程、截断、Trace、Task、Skill、交接说明都有。热度参考材料里提到 GitHub 上大约 100 Star、20 Fork看个大致活跃度就行别当回事。技术栈Python 3.x用到了 openai / pydantic / mcp / anyio、rich / prompt_toolkit后两个是负责命令行界面好看的。想接外部工具有 MCP 口子如果你想让它用上 GitHub、数据库之类的外部能力可以在根目录放个mcp_servers.json配置以命令方式拉起 MCP 服务MCP 就是给 AI 接外部工具的开放标准相当于给 Agent 装 USB 接口。{ mcpServers: { example: { command: npx, args: [-y, some-mcp-server, --api-key, ${API_KEY}] } } }配好之后Agent 就能用这个 MCP 提供的工具了。相关资源GitHubgithub.com/YYHDBL/MyCodeAgent文档都在仓库docs/里Issue 反馈GitHub Issues。名词速查表看晕了翻这里Function Calling / 函数调用让模型直接输出「函数名 参数」这种结构化指令程序照着执行而不是去解析一段自然语言。类比填表单而不是写小作文。上下文Context/ 上下文窗口喂给模型的所有内容对话历史 工具输出。窗口是有限容量的超了要么压缩要么落盘。Token令牌模型计费 / 计算长度的「字数单位」中文里大概 1~2 个字算一个。MCPModel Context Protocol给 AI 接外部工具 / 数据的开放标准相当于 Agent 的「USB 接口」。Trace轨迹日志记录 Agent 每一步行为调用了啥工具、花了多久、用了多少 token的日志用来回放和排查。Skill技能放在skills/名/SKILL.md的操作手册需要时注入上下文。Subagent / 子代理主代理派出去干子任务的小代理可配轻量模型或受限权限。AgentTeams实验性的多角色协作机制能建团队、互发消息、并行派活默认关闭。