夜雨聆风学习资料网

ARTICLE · 1258647

想搞懂 AI 编码助手内部是怎么跑起来的?这个开源项目把 Claude Code 的套路拆开了

发布时间：2026-10-27 10:51:47 最近访问：2026-10-27 10:51:47
想搞懂 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。

它重点放在四件事上：

  1. 工具协议
    工具怎么定义、怎么被调用、返回结果长啥样，让行为可预期、可调试；
  2. 上下文工程
    对话和工具输出那么长，怎么截断、压缩、存盘，控制 token（模型的「字数单位」）和成本；
  3. 子代理机制
    Skills、Task 子代理、AgentTeams 怎么分工协作；
  4. 可观测性
    它干了啥、为啥这么干，能不能被「回放」出来看。

一句话总结作者想做的事：让「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：出错信息

这套格式的好处是：前端展示、日志落盘、后续重试 / 熔断（连续失败就先停用该工具）都能用同一套逻辑处理。

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 双轨 Trace（Trace 就是「行为轨迹日志」）：

  • 一条条记录每次交互、每次工具调用；
  • 可选脱敏（怕把密钥记进去）；
  • 可选把原始模型响应也存下来，方便复盘；
  • 还有 token 统计、工具调用树，配合 CLI 里的工具调用树和进度显示，看得很清楚。

5. Skills 和 Task 子代理

  • Skills（技能）
    ：约定放在 skills/<技能名>/SKILL.md。SKILL.md 里写技能说明，$ARGUMENTS 会被实际参数替换，然后整段注入上下文。相当于给 Agent 准备一本「操作手册」随时翻。

一个 SKILL.md 长这样：

---name: code-reviewdescription: Review code quality and risks---# Code ReviewUse this checklist:- ...$ARGUMENTS
  • Task 子代理
    ：有 general / explore / plan / summary 等类型，对应不同复杂度的子任务。子代理可以配轻量模型省钱，也能配成只读或受限工具集，保证安全。

6. AgentTeams（实验性，默认关）

这块我得提醒一句：README 里标了「实验性」，默认是关的，要开得设 ENABLE_AGENT_TEAMS=true。

开了之后能玩多角色协作：

  • TeamCreate
     建个团队，SendMessage 互相发消息，TeamStatus 看状态，TeamDelete 解散；
  • Task 有三种模式：oneshot（一次性子任务，默认）、persistent（建个常驻队友）、parallel（一次性派发多个任务并行干）；
  • TeamFanout/TeamCollect 做「广播分工 + 收结果」。

最小玩法大概是：建个 team → 派个常驻 dev 队友 → 发消息安排活 → 看状态 → 干完解散。

小提示：因为这是实验特性，且项目本身迭代挺快，真要试建议先去看一眼仓库最新 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.gitcd MyCodeAgent# 虚拟环境（推荐）python -m venv venvsource venv/bin/activate   # Linux/Mac# .\venv\Scripts\activate  # Windows# 装依赖pip install -r requirements.txt

配置：复制或新建 .env，按需填：

# LLMexport OPENAI_API_KEY="your-api-key"export DEFAULT_MODEL="gpt-4"export TEMPERATURE="0.7"# AgentTeams（可选，默认关闭）export ENABLE_AGENT_TEAMS="true"# 上下文export CONTEXT_WINDOW="128000"export COMPRESSION_THRESHOLD="0.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，还在持续维护；
  • License
    ：MIT，随便改、随便二次开发；
  • 文档
    ：仓库 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 提供的工具了。

相关资源

  • GitHub：github.com/YYHDBL/MyCodeAgent
  • 文档都在仓库 docs/ 里
  • Issue 反馈：GitHub Issues

名词速查表（看晕了翻这里）

  • Function Calling / 函数调用
    ：让模型直接输出「函数名 + 参数」这种结构化指令，程序照着执行，而不是去解析一段自然语言。类比：填表单而不是写小作文。
  • 上下文（Context）/ 上下文窗口
    ：喂给模型的所有内容（对话历史 + 工具输出）。窗口是有限容量的，超了要么压缩要么落盘。
  • Token（令牌）
    ：模型计费 / 计算长度的「字数单位」，中文里大概 1~2 个字算一个。
  • MCP（Model Context Protocol）
    ：给 AI 接外部工具 / 数据的开放标准，相当于 Agent 的「USB 接口」。
  • Trace（轨迹日志）
    ：记录 Agent 每一步行为（调用了啥工具、花了多久、用了多少 token）的日志，用来回放和排查。
  • Skill（技能）
    ：放在 skills/<名>/SKILL.md 的操作手册，需要时注入上下文。
  • Subagent / 子代理
    ：主代理派出去干子任务的小代理，可配轻量模型或受限权限。
  • AgentTeams
    ：实验性的多角色协作机制，能建团队、互发消息、并行派活（默认关闭）。

相关学习资料