Claude Code From Scratch

工业级本地 AI Coding Agent（支持 MCP / 长上下文 / 权限控制）

Claude-Agent-Core 是一款专为复杂长程编码任务设计的本地化 AI Agent 底层框架。本项目构建了包含多级上下文渐进压缩、旁路记忆召回 (Agentic RAG) 与状态机纵深防御的硬核基座。

通过原生集成业内最新的 MCP (Model Context Protocol) 标准，本框架实现了外部工具链的零代码侵入式路由。无论是直接作为日常开发的命令行 Copilot，还是作为企业级专属 Coding Agent 的二次开发脚手架，均能提供极度稳定、高安全边界的任务调度体验。

核心特性

• 4 层上下文压缩：budget trimming、snip、micro-compact、auto-compact，专门解决长对话和大结果的 token 爆炸
• 异步记忆召回：用户输入后并发预取相关记忆，减少主循环阻塞，提升连续对话体验
• 状态机权限控制：Plan Mode、安全确认、allow/deny 规则和危险命令拦截，默认按最小权限执行
• MCP 动态工具路由：通过 JSON-RPC over stdio 动态接入外部工具，统一映射为 mcp__server__tool

核心架构

graph TB
    User["用户输入"] --> CLI["cli.py<br/>CLI 入口 / REPL"]
    CLI --> Agent["agent.py<br/>Agent 主循环"]
    Agent --> Prompt["prompt.py<br/>System Prompt"]
    Agent --> API{"API 后端"}
    API -->|"Anthropic"| AnthropicSDK["Anthropic SDK"]
    API -->|"OpenAI 兼容"| OpenAISDK["OpenAI SDK"]
    Agent --> Tools["tools.py<br/>工具系统"]
    Tools --> FS["文件读写"]
    Tools --> Shell["Shell 命令"]
    Tools --> Search["搜索工具"]
    Tools --> SkillTool["skill 工具"]
    Tools --> WebFetch["web_fetch"]
    Agent --> SubAgent["subagent.py<br/>子 Agent"]
    SubAgent -.->|"fork-return"| Agent
    Agent --> Memory["memory.py<br/>记忆系统"]
    Prompt --> Memory
    Prompt --> Skills["skills.py<br/>技能系统"]
    Agent --> MCP["mcp.py<br/>MCP 集成"]
    MCP --> ExtTools["外部工具服务器"]
    Agent --> Session["session.py<br/>会话管理"]
    Agent --> UI["ui.py<br/>终端 UI"]

    style Agent fill:#7c5cfc,color:#fff
    style Tools fill:#e8e0ff
    style CLI fill:#e8e0ff
    style Memory fill:#ffe0e0
    style Skills fill:#ffe0e0
    style SubAgent fill:#e0ffe0
    style MCP fill:#e0f0ff

Loading

• 主线流转：用户输入 → CLI 拦截 → Agent 核心循环 → 模型规划决策 → 工具路由执行 → 结果观测反馈 → 迭代直至完成。
  • cli.py (入口与交互)：解析命令行参数，提供类似 IDE 的交互式 REPL，并负责处理 Slash Commands（斜杠命令）的入口拦截。
  • agent.py (核心引擎)：系统大脑。负责消息组装、多模态 API 调度、流式响应解析、工具路由，以及极其重要的上下文压缩流水线与 Token 预算控制。
  • prompt.py (上下文注入)：动态组装器。将静态提示词模板与动态环境信息（系统 OS、目录结构、Git 状态、记忆池、可用技能）深度融合为 System Prompt。
  • tools.py (工具基座)：内置工具栈。包含核心工具的定义与执行逻辑，内建权限校验门禁（check_permission）与工具“延迟加载（Lazy Loading）”机制。
  • memory.py & skills.py (知识与工作流)：memory.py 使 Agent 具备跨会话认知能力并支持旁路语义召回；skills.py 提供可复用的标准作业流（SOP）。二者均在 Agent 启动阶段动态注入上下文。
  • subagent.py (多智能体编排)：分身机制。当任务过于庞大或需要严格权限隔离时，通过 fork 拉起具备独立上下文的子智能体处理子任务，完成后仅返回核心结论给主 Agent。
  • mcp.py (外部能力扩展)：MCP 协议客户端。通过底层的 JSON-RPC over stdio 标准协议，动态发现并无缝桥接外部工具服务器。
  • session.py (状态管理)：会话持久化。将对话历史与运行状态实时本地落盘，支持通过 --resume 实现无缝断点恢复。
  • ui.py (视图层)：终端渲染引擎。负责终端日志的颜色高亮、格式化排版以及流式打字机效果。

Demo

本框架不仅能完成基础的代码生成，更具备工具链路由与环境自主执行的闭环能力。

场景一：外部工具路由与链式审查 (Custom MCP Skill)

展示：Skill 拦截 -> MCP 外部工具 JSON 解析 -> 发现错误 -> 调用内置 File 工具生成修复代码。

mcp-audit-demo.mp4

Tech Note: 此处 Agent 自动跨越了 Python 主循环与外部 Node.js 服务的边界，完成了零侵入式调用。

场景二：Autonomous Coding 与权限沙盒 (Snake Game) 展示：长文本代码生成 -> 写入磁盘 -> 触发命令沙盒拦截 -> 人类授权执行 -> 成功运行。

snake-demo.mp4

Tech Note: 即使大模型生成了正确的 python snake.py 运行指令，底层的 State Machine 依然会物理拦截高危的 Shell 操作，确保 Human-in-the-loop（人类始终在环)。

核心拓展

本项目在吸收基础 Agent Loop 理论体系后，为解决“外部系统孤岛”与“大模型权限泛滥”两大痛点，进行了拓展实现：

• MCP 动态工具接入：通过 Node.js JSON-RPC 通信接入外部工具，运行时自动发现并路由
• 自定义 Skill：json_audit：把 JSON 审查流程封装成可复用技能，支持自动校验边界 case
• 工具权限隔离：在工具路由层注入了声明式的 allow/deny 鉴权中间件。配合系统底层的 Plan Mode 状态机，实现了动态的读写权限升降级，确保高风险操作（如 run_shell）严格遵循最小权限原则 (PoLP) 和 Human-in-the-loop 审批。
• 项目级规则配置：将配置项剥离出核心代码，设计了级联的规则引擎目录（涵盖权限、安全隔离、技能池、MCP 节点配置）。为框架赋予了热插拔能力，使其具备了随时外挂企业内部数据库、Jira 或 Slack 接口的生产级脚手架标准。

致谢

本项目基于 Claude Code 的公开设计思路、How Claude Code Works 的源码级讲解，以及官方相关文档和社区实践进行学习与重构。