microcodex 深度解构：C++ 终端 coding agent 的极简工程

一句话定位

MicroCodex 是一个用 C++23 编写的终端 coding agent。它直接调用 OpenAI Responses API，在终端里渲染 Markdown 和 shell 语法高亮，自带 OAuth 登录流程，零运行时依赖（libcurl 除外）。整个项目 49 个源文件（.cpp + .h），10,208 行代码，编译产物是单个二进制文件。

截至本文写作时（2026-08-03），仓库创建于 2026-07-30，25 stars，Apache 2.0 许可证。

仓库结构全景

先看整体。根目录下的源码文件和体积：

核心模块（按字节降序）

头文件（选录）

第三方依赖

仓库通过 git submodule 引入两个 vendor 依赖（.gitmodules 187 字节）：

• termbox2 (vendor/termbox2/) — MIT 许可，提供终端 UI 原语
• md4c (vendor/md4c/) — MIT 许可，C 语言 Markdown 解析器

NOTICE 文件（322 字节）明确列出了这两个依赖的版权归属。作者：Paolo Anzani，Copyright 2026。

5 分钟本地跑起来

MicroCodex 的构建链路设计得非常干净。三种方式，从快到慢：

方式一：一键安装（推荐）

curl -fsSL https://github.com/paoloanzn/microcodex/releases/latest/download/install.sh | sh

install.sh（301 行）做了什么：检测平台（macOS arm64/x86_64、Linux arm64/x86_64）→ 下载对应 tar.gz → 校验 SHA-256（三重校验：archive + binary + launcher 各有独立 checksum 文件）→ 安装到 ~/.local/bin/microcodex-bin → 写入 launcher.sh → 自动追加 PATH 到 shell 配置文件（根据 shell 类型选择 .zprofile/.bash_profile/.zshrc/.bashrc/.profile）。

安装后跑：

microcodex login        # 浏览器打开 OAuth 授权页
microcodex              # 进入交互式 TUI
microcodex "fix the failing test"   # 一次性 prompt

方式二：从源码构建

前置条件：C++23 编译器、make、libcurl 开发文件（Linux 还需 OpenSSL 开发文件）。

git clone --recurse-submodules https://github.com/paoloanzn/microcodex.git
cd microcodex
make          # 产物在 build/microcodex
make test     # 跑测试套件（需要 ruby）

Makefile 只有 56 行。macOS 用 clang++ 并通过 xcrun 获取 SDK 路径；Linux 用 g++ 并链接 -lcrypto。编译选项 -std=c++23 -O2 -Wall -Wextra -pthread，头文件搜索路径加入 vendor/termbox2。

方式三：远程/无头机器

microcodex login --device-auth

这走 device code flow：终端显示一个一次性码，你在另一台有浏览器的机器上打开验证 URL 输入这个码。OAuth 凭证存储在 $CODEX_HOME/auth.json（默认 ~/.codex/auth.json），权限 600。

launcher.sh 的自动更新机制

安装后的 microcodex 命令实际上是 launcher.sh（156 行）的软链接。每次启动时，launcher 下载对应平台的 .sha256 文件，和本地 microcodex-bin 的哈希比对。发现新版本时，如果终端可交互（[ -t 0 ] && [ -t 2 ] && [ -rw /dev/tty ]），提示用户是否更新。设置 MICROCODEX_NO_UPDATE_CHECK=1 跳过检查。

main.cpp：CLI 入口骨架

main.cpp（388 行 / 14,970 字节）解析命令行参数，分派到多条路径：

microcodex login [--device-auth]
microcodex logout
microcodex list
microcodex show ID
microcodex [--model MODEL] resume ID [PROMPT]
microcodex [--model MODEL]
microcodex [--model MODEL] PROMPT

默认模型是 gpt-5.6-sol（源码 constexpr std::string_view default_model）。参数解析使用 C++23 的 std::expected 做错误传播，不依赖任何 CLI 解析库。

AgentRequest 结构体持有 model、prompt、resume_id 三个字段，解析完成后传入 Agent 类执行。

Agent 类 + Conversation 管理

agent.cpp（157 行）是工具注册中心。它通过 makeCodingTools() 创建文件系统工具集：

• read — 读文件（path, offset, limit）
• write — 写文件（path, content）
• edit — 编辑文件（path, old_content, new_content, replaceAll）
• bash — 执行 shell 命令
• glob — 文件模式匹配

每个工具是 Tool<T, S...> 模板实例，继承自 ToolBase 抽象基类。ToolBase 定义了 name()、toJsonString()、executeJson() 三个虚函数。executeJson 接收 JSON 字符串参数，通过 ToolArguments 解析命名字段，再委托给底层 C++ 函数。

makeCodingAgentConfig() 返回 CodexApiConfig，包含 access_token、account_id、model、instructions、reasoning_effort（默认 "medium"）、endpoint（默认 https://chatgpt.com/backend-api/codex/responses）。限流参数：maximum_tool_rounds = 64、maximum_parallel_tool_calls = 32、maximum_tool_output_bytes = 64 KB。

对话持久化由 conversation.cpp（553 行）负责。每条对话存储在 $CODEX_HOME（默认 ~/.codex）下的 JSON 文件中。ConversationMetadata 记录 version、id、created_at、working_directory、model。对话按 turn 组织，TurnBoundary 标记每个 turn 的结束位置。

bash.cpp + bash-safety.cpp：Shell 安全层

bash.cpp（360 行）实现 shell 命令执行。核心是 runProcess 函数：

1. 构建 execvp 参数向量
2. 创建 stdout/stderr pipe
3. fork 子进程，子进程创建独立进程组（setpgid）
4. 父进程通过 poll 监听 pipe，同时检查 stop_token 实现中断
5. 支持超时 deadline

中断时，父进程向子进程组发送 SIGKILL，再 waitpid 回收。子进程创建独立进程组的目的是让信号能传播到命令的子孙进程。

bash-safety.cpp（67 行）是命令过滤层。它用 5 条 std::regex 拦截危险命令：

README 明确警告：这个安全层是词法黑名单，不是完整的 shell 解析器，也不是沙箱。所有未被黑名单匹配的命令都以 MicroCodex 进程的权限执行。

context-compaction.cpp：Context 压缩策略

context-compaction.cpp（181 行）解决 LLM 上下文窗口溢出问题。

ContextCompactor 接收 CompactionConfig（含 context_limit_tokens 和 compact_at_tokens）。needed() 方法判断当前 token 用量是否超过阈值。

压缩策略按 turn 边界操作。plan() 方法从最新 turn 向前遍历，累计 token 估算值，直到预算耗尽。被压缩的 turn 会被替换为一条 summary 指令：

“Summarize the conversation for another coding agent that must continue the work. Preserve the user’s goal and constraints, decisions and their reasons, files inspected and changed, important code behavior, commands and test results, unresolved errors, and remaining work. Do not include conversational filler.”

这保证 function call 不会和它的 output 分离，因为压缩总是以完整 turn 为单位。retain_recent_turns 参数控制是否保留最近几个完整 turn 的原文。

CompactionCheckpoint 记录压缩代次（generation）、压缩到哪个 turn、保留起始 turn、summary 文本。

ui.cpp + termbox.cpp：TUI 渲染

ui.cpp（1,583 行 / 63,348 字节）是全仓库最大的文件。它基于 termbox2 渲染终端 UI。

关键常量：

• maximum_transcript_bytes = 512 KB — 转写区上限
• maximum_tool_preview_bytes = 16 KB — 工具输出预览上限
• large_paste_character_threshold = 1000 — 大粘贴检测阈值
• maximum_collapsed_tool_output_rows = 5 — 工具输出折叠行数
• animation_frame_milliseconds = 32 — 动画帧间隔（~30fps）
• idle_poll_milliseconds = 250 — 空闲轮询间隔
• maximum_prompt_rows = 6 — 输入框最大行数

UI 层集成了三个渲染器：Markdown（通过 markdown.cpp 调用 MD4C）、shell 语法高亮（shell-highlight.cpp）、文本样式（styled-text.cpp）。代码块用青色（termbox color index 14），链接也用青色，引用块用绿色（color index 10）。

termbox.cpp（98 行）是对 termbox2 C API 的薄包装，提供 init()、shutdown()、present() 等方法。

oauth.cpp：OAuth 登录

oauth.cpp（1,362 行 / 62,208 字节）是第二大文件。它实现了完整的 OAuth 2.0 流程。

OAuthOptions 配置：

• issuer = "https://auth.openai.com"
• client_id = "app_EMoamEEZ73f0CkXaXp7hrann"
• originator = "codex_cli_rs"
• callback_port = 1455（备选 1457）
• token_request_timeout_seconds = 30

支持两种登录方式：

1. localhost redirect（默认）— 启动本地 HTTP 服务器监听 1455 端口，等待浏览器回调。如果 1455 被占用则尝试 1457。
2. device code flow（--device-auth）— 适合远程/无头机器，显示一次性码让用户在浏览器输入。

FileDescriptor RAII 类管理所有 socket 和文件描述符，防止早期返回路径泄漏。SHA-256 实现是平台条件编译：macOS 用 CommonCrypto（<CommonCrypto/CommonDigest.h>），Linux 用 OpenSSL（<openssl/sha.h>）。

OAuthCredentials 存储 access_token、account_id、id_token、refresh_token 四件套，持久化到 $CODEX_HOME/auth.json。

api.cpp：OpenAI Responses API 客户端

api.cpp（1,046 行 / 44,354 字节）是与 OpenAI 后端通信的核心。

它使用 SSE（Server-Sent Events）流式接收 Responses API 的增量输出。每个响应项打包为 UUID（makeUuid 函数自己实现，用 std::random_device 生成 16 字节再设置 version/variant 位，不依赖外部 UUID 库）。

关键逻辑：

• 工具调用并行执行（上限 32 个），结果按完成顺序收集
• 每轮最多 64 次 tool round（防止无限循环）
• 工具输出截断到 64 KB
• 支持中断：stop_token 传播到 HTTP 层和工具执行层
• 中断后注入 <turn_aborted> guidance 让模型理解上下文
• 到达 output token 上限时注入 turn_usage_limit_guidance，引导模型从断点继续

CodexApiConfig 的 endpoint 默认指向 https://chatgpt.com/backend-api/codex/responses——MicroCodex 复用 ChatGPT 订阅的 Codex 后端，而非标准 OpenAI API。client_id 和 originator = "codex_cli_rs" 进一步佐证它复用了 Codex CLI 的 OAuth 应用注册。

自实现基础设施

MicroCodex 不依赖任何第三方 JSON 库。json.cpp（498 行）手写了完整的 JSON 解析器和序列化器，支持 whitespace 跳过、字符串转义（\n/\t/\"/\\/\uXXXX）、UTF-16 surrogate pair 解码。

HTTP 客户端 http.cpp（180 行）封装 libcurl，支持 streaming body handler、header handler、超时（idle + total）、字节上限。libcurl 是全项目唯一的运行时外部 C 库依赖。

markdown.cpp（651 行）在 MD4C 的回调上构建了一个样式化渲染层：遍历 MD4C 的 block/span 事件，转换为 StyledSpan 数组，再由 ui.cpp 写入 termbox 单元格。

shell-highlight.cpp（240 行）自实现了 shell 命令语法高亮——关键字、字符串、管道符、重定向、变量展开各有颜色，不依赖任何语法高亮库。

model-catalog.cpp + skills.cpp

model-catalog.cpp（158 行）查询 /models 端点获取模型的上下文窗口限制。ModelContextLimits 包含 context_window_tokens、maximum_context_window_tokens、effective_context_window_percent、effective_context_window_tokens、compact_at_tokens 等字段。compactionConfigForModel() 根据模型参数计算压缩阈值。

skills.cpp（182 行）实现与 Codex 兼容的 skill 发现机制。扫描 $CODEX_HOME/skills 目录（默认 ~/.codex/skills），递归查找 SKILL.md 文件（最大深度 6 层），解析 YAML frontmatter 中的 name 和 description。有效 skill 上限 20,000 个，单文件上限 1 MB。扫描不感知 .gitignore，遍历目录树下的所有文件。

构建系统与 CI

Makefile（56 行）是干净的 C++23 项目构建脚本。源文件通过 $(wildcard *.cpp) 自动发现，依赖追踪用 -MMD -MP。C 源文件（MD4C）单独用 $(CC) 编译。

测试通过 make test 调用 tests/run.sh。该脚本（约 200 行）用 Ruby 搭建 mock server，对编译后的二进制做集成测试。测试框架自实现，不依赖任何测试库。expect_process 函数分别比较 stdout、stderr、exit code，捕获意外的诊断输出。8 个测试场景覆盖 CLI、prompt、tool loop、conversation、interruption、launcher、paste、keybindings。3 个额外的 Ruby 脚本（continue-ui.rb、interrupt-ui.rb、keybindings-ui.rb、paste-ui.rb）提供 UI 交互测试的 mock server 场景。

CI（.github/workflows/ci.yml）在 4 个平台上验证：macOS arm64（macos-26）、macOS x86_64（macos-26-intel）、Linux x86_64（Debian 12 container）、Linux arm64（Debian 12 container）。Linux 以 Debian 12 为基准，验证 glibc 2.36 和 libstdc++ GLIBCXX_3.4.30 ABI 符号——确保编译产物可以向前兼容。Release workflow 支持 tag 触发，自动构建 + SHA-256 校验和 + 上传 GitHub Release。

C++ 终端 coding agent 的工程哲学

MicroCodex 的 49 个源文件加起来 10,208 行。其中 27 个 .cpp 文件，22 个 .h 文件。所有代码平铺在仓库根目录——没有 src/、include/、lib/ 分层。这个选择很明确：flat layout 让 Makefile 的 $(wildcard *.cpp) 一行搞定源文件发现，也让 #include "xxx.h" 不需要配置 include path。

250 KB C++ 单体的取舍

49 个源文件的总字节数约 398 KB（含 .cpp + .h），编译后的二进制估计在 1-2 MB 级别（-O2 优化）。这个体量用 Electron 做大概要 200 MB+，用 Node.js 做至少需要 V8 运行时。MicroCodex 的选择是：

用编译时复杂度换运行时简洁。

代价是开发者必须有 C++23 编译器。-std=c++23 不是所有编译器都支持——macOS 默认的 clang 需要 Xcode 15+，Linux 需要 GCC 14+ 或 Clang 18+。std::expected、std::stop_token、<charconv> 这些都是 C++23 特性。

收益是终端用户拿到一个单文件二进制，启动时间在毫秒级，内存占用在 MB 级别。launcher.sh 的自动更新只需要下载一个 tar.gz 并替换一个文件。

三个文件占了一半代码量

ui.cpp（1,583 行）+ oauth.cpp（1,362 行）+ api.cpp（1,046 行）= 3,991 行，占总代码量的 39%。终端 UI 和 OAuth 是两块公认的"脏活"——前者要处理终端尺寸变化、颜色映射、动画帧、输入缓冲、粘贴检测、折叠/展开状态机；后者要处理 HTTP redirect、token 刷新、PKCE challenge、socket 生命周期、超时。

作者没有把这两块外包给库，而是全部自实现。termbox2 和 md4c 是仅有的两个 vendor 依赖，都很轻量（termbox2 是单文件 C 库，md4c 也是单文件 C 库），通过 git submodule 引入而非包管理器。

错误处理的统一性

全仓库使用 std::expected<T, std::string> 做错误传播。从 read.cpp 的文件读取（std::expected<std::string, std::string> read(...)）到 http.cpp 的 HTTP 请求（std::expected<HttpResponse, std::string> performHttpRequest(...)）到 api.cpp 的 API 调用，错误类型统一为 std::string。这让错误可以跨层传播而无需类型转换。正常流程中没有 try-catch，std::runtime_error 仅用于 bash.cpp 中 fork/pipe 等系统调用的致命错误（这些路径会直接 throw 到 main 的顶层 catch）。

静态链接策略

MicroCodex 不静态链接 libcurl。Linux 要求安装 libcurl4-openssl-dev（构建时）和 libcurl 运行时（运行时）。这是 CI 里 Debian 12 container 的原因之一——锁定 glibc 2.36 基线确保二进制向前兼容。如果静态链接 libcurl，二进制可以做到真正的零依赖，但会增大二进制体积并引入 OpenSSL 版本绑定的维护负担。作者选择了动态链接 libcurl + OpenSSL，用 CI 验证 ABI 兼容性。

给工程师的 5 个 takeaway

1. std::expected<T, std::string> 足以替代异常和错误码。MicroCodex 的 49 个源文件没有一个 try-catch 块用于正常流程。错误传播链路从 syscall 包装层（bash.cpp 的 pipe/fork）到 HTTP 层（http.cpp 的 curl 封装）到业务层（api.cpp 的 response 解析）到 UI 层（ui.cpp 的错误展示），全程 return std::unexpected(...) 传播。如果你在评估 C++23 的错误处理方案，这里是可参考的生产实践。

2. Terminal coding agent 的 tool loop 可以用三个参数定义边界：maximum_tool_rounds = 64、maximum_parallel_tool_calls = 32、maximum_tool_output_bytes = 64 KB。这三个值在 CodexApiConfig 里硬编码（api.h 第 142-145 行）。如果你在写自己的 agent loop，可以直接参考这些值作为起点，然后根据任务复杂度调整。

3. 词法黑名单的安全边界要诚实标注。bash-safety.cpp 用 5 条正则拦截最高频的危险命令，作者在 README（> [!WARNING] 段落）、bash-safety.h 头文件注释、system prompt 三处都标注了"not a complete security boundary"。这种诚实的降级声明比过度承诺的"沙箱"更值得信任。如果你在给 coding agent 设计安全层，考虑用同样的策略：拦截最高频的操作，明确告知用户未被拦截的部分。

4. Context 压缩要按 turn 边界操作。context-compaction.cpp 的 plan() 方法遍历 TurnBoundary 列表，以完整 turn 为最小压缩单位。这保证 function call 和它的 output 在同一批被压缩或保留——拆散它们会让模型看到 call 却找不到 result，导致幻觉或重复调用。summary 指令要求保留 “files inspected and changed” 和 “unresolved errors”，让续接的模型能快速重建工作状态。如果你在做 LLM 应用的 context 管理，这是工程范式。

5. OAuth 可以用纯 C++ 在 1,362 行内实现，包括 localhost redirect 和 device code flow 两种模式、PKCE challenge/verifier、token 刷新、credential 文件持久化（权限 600）。FileDescriptor RAII 类管理所有 socket 的生命周期，oauth.cpp 注释写道"OAuth has many error exits, so centralizing close() here makes the rest of the flow much easier to audit"。如果你的 CLI 工具需要 OAuth 登录，且不想引入 liboauth 或类似依赖，这个实现值得参考。

留给读者的 5 个问题

1. MicroCodex 的 endpoint 指向 chatgpt.com/backend-api/codex/responses，client_id 和 originator 也指向 Codex CLI 的 OAuth 注册。如果 OpenAI 收紧 Codex 后端的访问策略，MicroCodex 是否还能工作？社区是否需要一个支持标准 api.openai.com endpoint 的 fork？

2. maximum_tool_rounds = 64 对于复杂任务够用吗？一个需要修改 20 个文件、每个文件需要 read + edit + bash 验证的 task，理论上需要 60+ 次工具调用。到达上限后 api.cpp 注入 turn_usage_limit_guidance 引导模型从断点继续，但下一轮的 64 次限额是否会打断连续的编辑流程？

3. context-compaction.cpp 的 summary 指令保留了 “files inspected and changed”，但压缩粒度是 turn 级。如果一个 turn 内有 5 次 edit 操作（修改了 5 个文件），summary 是否会精确记录每个文件的路径和变更内容？还是只保留高层的 “modified auth module” 抽象描述？

4. skills.cpp 的扫描不感知 .gitignore。在 node_modules/、vendor/、.venv/ 等目录下如果有误放的 SKILL.md，会被纳入 skill catalog。20,000 个 skill 上限和 6 层深度限制能否在大型 monorepo 中撑住？

5. json.cpp 手写的 JSON 解析器是线性扫描 + 递归下降，没有 SIMD 加速。对于 Responses API 的 SSE 流（每个 chunk 通常几 KB），性能够用。但如果对话历史膨胀到几百 KB 的单条 JSON，解析时间是否可接受？有没有遇到过深嵌套 JSON 的栈溢出？

反写元数据

三维自评（v3）