AemeathCode

一个从零手搓的 Coding Agent —— 既是能跑的终端 AI Agent,也是一趟看得见的系统工程学习历程。

简体中文 · English

_{左栏 Status / Sessions / Thinking · 中间 Content 和输入行 · 右栏 Tasks / Changes / MCP / Skills。}

它是什么

给它一个目标,它自己规划步骤、读写文件、执行命令、观察结果,循环推进直到做完 —— 全程在终端里看得见。

它由两个进程组成:前台界面和后台常驻的 daemon,中间是一条自己实现的多路复用协议。ReAct 循环、工具注册表、会话记忆、权限审批、上下文压缩、子 agent、MCP 客户端,全部用纯 Python + asyncio 从零写,没有用任何 agent 框架。

这是一个学习与展示型项目。它能真实执行 shell 命令、真实写文件 —— 请在你信任的目录里跑(见安全声明)。

装上,跑起来

支持 Linux / macOS / Windows + WSL2。Windows 原生跑不起来,目前不打算适配。

wsl --install          # 管理员 PowerShell,装完重启,之后所有命令都在 WSL 终端里敲

一键安装启动

command -v uv >/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install aemeathcode && aemeath

检测 uv,没有就装,然后装 AemeathCode 并启动。

• 前置只有 uv 一件,Python 无需下载。已经有 pipx 也行:pipx install aemeathcode
• 首次启动弹配置向导,问 API Key / Base URL / 模型名。任何 Anthropic Messages API 兼容的端点都行(官方、DeepSeek、自建网关)
• 命令名 aemeath,包名 aemeathcode —— 升级卸载用包名:uv tool upgrade aemeathcode / uv tool uninstall aemeathcode
• 退出界面后 daemon 仍在后台常驻(下次秒进),aemeath stop 关掉

显示 harness 概况

_{/about —— 版本、模型、会话 ID、上下文占用。}

它怎么工作

ReAct 循环

_{一个 run 正在跑:中间是工具调用和逐字输出的回答,左边是它的思考,右边是它给自己列的任务。}

一个 run 是一段循环:对话发给模型 → 模型返回回答或 tool_use → 执行工具 → tool_result 写回对话 → 再次发给模型,直到不再返回 tool_use。

每个 tool_use 必须在下一轮有对应的 tool_result,数量与顺序都要对上,否则该轮对话被 API 拒绝。执行失败、权限拒绝、参数缺失同样返回 tool_result,内容为错误说明。

内置八类工具:读文件、写文件、跑 shell、列目录、任务增删查改、长期笔记、加载 skill、派子 agent。

动手前它会问你

写文件和执行命令在进入工具之前被拦截,daemon 通过同一条连接反向请求前端授权,方向与常规请求相反。授权可选「这次」或「永远」,后者会被记住。

• 审批面板展示完整的待写内容与完整命令,不截断
• 被拒绝的调用在 Content 留一行记录

它记得住东西

记忆分三层作用域:

消息按 run 增量存储,索引负责拼接成完整历史,恢复会话时按索引重建,不读取单一大文件。

上下文满了会自己压

历史逼近 token 预算时自动压缩:较早的轮次经一次独立的辅助 LLM 调用概括为摘要,最近若干轮逐字保留。压缩只作用于内存中的工作副本,磁盘上的原始记录不变,resume 得到的仍是完整历史。

能力边界可以往外扩

• 子 agent —— 子任务在隔离上下文中执行,只回传结果,中间过程不进入主对话;可指定角色(profiles)
• Skills —— 按需加载的操作手册,常驻的只有简介,调用 use_skill 时才载入正文
• MCP —— 作为客户端连接外部 server,其工具注册进同一张 ToolRegistry,在模型侧与内置工具无区别

自定义 skill、项目记忆、MCP 配置怎么写,见 examples/。

S0 → S7:它是怎么长出来的

八个阶段推出来的,每个阶段解决一个明确的工程问题:

对应 git tag stage-0 … stage-7,可按顺序 checkout 阅读。

架构

两个进程,一条连接

界面和大脑是两个独立进程,中间只有一条 TCP 连接,上面同时跑三种流量。

三种流量:

反向审批的方向与前两种相反,daemon 是发起方。三者共用同一条连接、同一套信封格式、同一个读循环,靠信封类型区分。

一个 run 在 daemon 里走过哪里

图上两条回边就是循环:tool_use 从模型回到 loop,tool_result 从工具回到 loop。走向由 stop_reason 决定:tool_use 进入下一轮,end_turn 正常结束;max_tokens、refusal、未知值和 max_steps 耗尽都中止并记为失败。

源码在 src/aemeathcode/:

参考

aemeath init --local            # ① 向导写 .aemeath/.env(不带 --local 是写全局)
cp .env.example .aemeath/.env   # ② 从模板抄一份改(全部可用变量都在模板里)
                                # ③ 或者手写 .aemeath/.env,只放要覆盖的那几行

git clone https://github.com/Nijikasuki/AemeathCode.git
cd AemeathCode
uv sync
uv run aemeath        # 之后所有命令前加 uv run
uv run pytest -q      # 114 passed

安全声明

AemeathCode 会真实执行 shell 命令、读写本地文件。内置的权限审批不能替代下面三条:

• 在隔离环境(容器 / 沙箱 / 专用目录)里运行,不要指向重要数据
• 审批时看清命令再批,allow_always 会被记住
• API Key 放 .aemeath/.env 或 ~/.config/aemeath/.env,不要提交

本项目用于学习与研究,使用者对其行为负责。

License

MIT © 2026 Nijikasuki

实现思路参考了 KamaClaude 的分阶段设计。欢迎开 issue 交流实现细节。