MiniCode Python（Learning Fork）

Fork 声明：本仓库 fork 自 LiuMengxuan04/MiniCode（TypeScript 主仓）及其 Python 运行时 QUSETIONS/MiniCode-Python。 原项目采用 MIT License，版权归 Copyright (c) 2026 Liu Mengxuan 所有。本仓库为个人学习 / 二次阅读版本，用于理解现代 AI 编码 Agent 的工程实现；版权与许可归原作者所有，此处仅作学习记录。

这是什么

MiniCode 是一个终端优先的 AI 编码助手。它的核心目标不是做一个"聊天 wrapper"，而是把 Agent 的运行过程变得可观察、可恢复、可测试。本仓库是我本地搭建并逐模块阅读的 Python 运行时，用来学习一个生产级编码 Agent 是怎么组织"循环、工具、记忆、恢复"这几件事的。

梳理的核心机制

（结合 minicode/ 包的真实结构）

1. Agent Loop 执行循环 — agent_loop.py

模型推理 → 工具调用 → 结果回填 → 终止检查，形成闭环。我重点理解了"循环如何在不依赖人工介入的情况下稳定推进多轮任务"。

2. 工具契约 — ToolDefinition / ToolRegistry

每个工具都有统一的描述、参数 Schema、运行时校验与执行句柄。这解决的是"模型输出"到"安全函数调用"之间的契约问题，避免任意字符串被当成命令执行。

3. 会话持久化 — session.py

会话可以被检查、重放、恢复、压缩。我理解了"会话状态如何跨进程边界存活"，以及 checkpoint / rewind 如何让本地编辑可回退。

4. 控制论自调节 — cybernetic_orchestrator.py + turn_kernel.py

运行时把"上下文溢出、工具报错、成本飙升、震荡"当成可被控制的信号，通过 phase policy、widening、verification gate 做自适应调节。这是这个项目让我觉得最值得学的地方。

5. 记忆管线 — memory.py / working_memory.py / memory_pipeline.py

记忆不是附属功能：工作记忆、项目记忆、记忆注入、记忆感知压缩都已经在运行时路径里。我理解了"如何让 Agent 在长任务里保留关键上下文，而不是只靠当前聊天窗口"。

架构（保留原图，便于对照源码）

flowchart LR
    User["User task"] --> Loop["agent_loop.py"]
    Loop --> Kernel["turn_kernel.py<br/>phase policy, widening,<br/>verification gate"]
    Loop --> Memory["Memory stack<br/>working_memory.py,<br/>memory.py, memory_pipeline.py"]
    Kernel --> Tools["Local tools<br/>files, search, edit, shell"]
    Tools --> Loop
    Memory --> Loop
    Loop --> Signals["Signals<br/>context, cost, errors,<br/>progress, provider state"]
    Signals --> Orchestrator["CyberneticOrchestrator"]
    Orchestrator --> Actions["Runtime actions<br/>compact, checkpoint, rewind,<br/>adjust budget, recover, reflect"]
    Actions --> Loop

Loading

核心模块（对照学习）

模块	我关注的点
minicode/agent_loop.py	主循环与运行时事件流
minicode/turn_kernel.py	步策略、phase 转换、widening、验证门
minicode/session.py	持久会话、重放、checkpoint、rewind
minicode/memory.py	长期项目记忆管理与检索
minicode/working_memory.py	受保护的工作记忆条目
minicode/memory_pipeline.py	闭环记忆检索、注入、反思回写
minicode/cybernetic_orchestrator.py	运行时控制生命周期

本地运行（原项目命令，保留供参考）

git clone https://github.com/QUSETIONS/MiniCode-Python.git
cd MiniCode-Python
python -m pip install -e .[dev]
minicode-py

个人收获

通过阅读和实践这个项目，我建立了对"编码 Agent 不是 prompt 堆砌，而是一套带状态、带恢复、带验证的工程系统"的直观理解，也积累了把控制论思路引入 Agent 运行时调节的视角。这些理解支撑了我在电商智能客服工单 Agent 等项目中设计可控、可兜底的 Agent 工作流。

许可证

本项目遵循原项目 MIT License，版权归 Liu Mengxuan 所有。详见 LICENSE。