1. 项目概述Clawd Code又称 Claude-Code-Python是一个基于 Claude Code 原始 TypeScript 源码的完整 Python 重构实现。它不是一个简单的源码转储而是一个可运行的生产级 CLI Agent具备工具调用循环、流式 REPL、会话历史和多轮执行能力。属性说明仓库地址https://github.com/GPT-AGI/Clawd-Code开发语言Python 100%许可证MIT星标数345Fork 数180核心定位Claude Code 的 Python 重实现2. 核心设计思路2.1 设计哲学项目遵循以下核心设计原则高保真移植保留原始 Claude Code 的架构设计同时适配 Python 的惯用模式生产级运行真正的 Agent 运行时而非源码转储可扩展性可读性优先的 Python 代码库支持技能扩展多模型兼容通过抽象层支持多家 LLM 提供商2.2 核心工作流程用户输入(REPL/CLI) → 命令解析(Command System) → Agent 循环(Agent Loop) → LLM 调用(Provider) → 工具执行(Tool System) → 结果返回 → 流式输出(Stream Output)3. 整体架构框架3.1 模块结构30 子模块src/ ├── agent/ # Agent 核心对话与会话管理 │ ├── conversation.py # 对话数据模型Message/Conversation │ └── session.py # 会话状态管理 ├── assistant/ # 助手功能初始化占位 ├── bootstrap/ # 启动/初始化流程 ├── bridge/ # 桥接层 ├── buddy/ # 伙伴系统 ├── command_system/ # 命令系统 ├── compact_service/ # 上下文压缩服务 ├── components/ # UI 组件 ├── constants/ # 常量定义 ├── context_system/ # 上下文管理 ├── coordinator/ # 协调器 ├── entrypoints/ # 入口点定义 ├── hooks/ # 生命周期钩子 ├── keybindings/ # 键盘快捷键 ├── memdir/ # 内存目录管理 ├── migrations/ # 数据迁移 ├── native_ts/ # TypeScript 原生代码引用 ├── outputStyles/ # 输出样式 ├── plugins/ # 插件系统 ├── providers/ # LLM 提供商抽象层 │ ├── base.py # 提供商抽象基类 │ ├── anthropic_provider.py │ ├── openai_provider.py │ ├── openai_compatible.py │ ├── glm_provider.py │ └── minimax_provider.py ├── reference_data/ # 参考数据 ├── remote/ # 远程运行时 ├── repl/ # REPL 交互核心 │ └── core.py # REPL 主循环 ├── schemas/ # 数据模式定义 ├── screens/ # 终端界面 ├── server/ # 服务端组件 ├── services/ # 业务服务层 ├── skills/ # 技能系统 ├── state/ # 全局状态管理 ├── tool_system/ # 工具系统核心 │ ├── agent_loop.py # Agent 主循环 │ ├── context.py # 工具上下文 │ ├── defaults.py # 默认配置 │ ├── diff_utils.py # Diff 工具 │ ├── errors.py # 错误定义 │ ├── loader.py # 工具加载器 │ ├── permission_handler.py │ ├── permissions.py # 权限控制 │ ├── protocol.py # 工具调用协议 │ ├── registry.py # 工具注册表 │ ├── schema_validation.py │ ├── task_manager.py # 任务管理 │ └── tools/ # 内置工具集 ├── types/ # 类型定义 ├── upstreamproxy/ # 上游代理 ├── utils/ # 工具函数 ├── vim/ # Vim 集成 ├── voice/ # 语音功能 ├── cli.py # CLI 入口 ├── main.py # 主程序入口 ├── runtime.py # 运行时环境 ├── repl.py # REPL 实现 ├── config.py # 配置管理 └── context.py # 上下文管理3.2 分层架构┌─────────────────────────────────────┐ │ 用户界面层 │ │ CLI (cli.py) / REPL (repl/core.py) │ ├─────────────────────────────────────┤ │ 命令系统层 │ │ Command System / Skill System │ ├─────────────────────────────────────┤ │ Agent 核心层 │ │ Agent Loop / Conversation / Session │ ├─────────────────────────────────────┤ │ 提供商抽象层 │ │ Providers (Base 具体实现) │ ├─────────────────────────────────────┤ │ 工具系统层 │ │ Tool System / Registry / Protocol │ ├─────────────────────────────────────┤ │ 基础设施层 │ │ Config / State / Utils / Hooks │ └─────────────────────────────────────┘4. 核心原理与算法4.1 Agent 循环Agent LoopAgent 循环是整个系统的核心采用ReActReasoning Acting模式# 伪代码示意classAgentLoop:defrun(self,user_input):# 1. 将用户输入添加到对话历史conversation.add_user_message(user_input)# 2. 主循环思考-行动-观察whilenotdone:# 2.1 调用 LLM 获取响应responseprovider.chat(messagesconversation.messages,toolsavailable_tools# Function Calling)# 2.2 检查是否包含工具调用ifresponse.tool_uses:fortool_callinresponse.tool_uses:# 2.3 执行工具resultexecute_tool(tool_call)# 2.4 将工具结果添加到对话conversation.add_tool_result(result)else:# 2.5 直接返回文本响应returnresponse.content关键特性流式处理支持 SSEServer-Sent Events流式输出多轮迭代工具调用结果会反馈给 LLM 进行下一轮推理上下文窗口管理max_history100自动裁剪历史消息4.2 工具调用协议Tool Protocoldataclass(frozenTrue)classToolCall:name:str# 工具名称如 Read, Grep, WebFetchinput:dict# 工具参数tool_use_id:str# 唯一标识符dataclass(frozenTrue)classToolResult:name:str# 工具名称output:Any# 执行结果is_error:bool# 是否出错tool_use_id:str# 对应 ToolCall 的 IDcontent_type:str# text 或 json工具执行流程LLM 通过 Function Calling 返回ToolCall系统通过registry.py查找对应工具loader.py加载工具实现permission_handler.py检查权限执行工具并封装为ToolResult结果反馈到对话上下文4.3 对话管理系统dataclassclassMessage:role:str# user | assistant | systemcontent:str|list[ContentBlock]timestamp:str_is_internal:bool# 内部标记如压缩边界dataclassclassConversation:messages:list[Message]max_history:int100# 滑动窗口限制内容块类型TextContentBlock纯文本内容ToolUseContentBlock工具调用请求ToolResultContentBlock工具执行结果4.4 多提供商抽象架构classBaseProvider(ABC):def__init__(self,api_key,base_urlNone,modelNone):self.api_keyapi_key self.base_urlbase_url self.modelmodelabstractmethoddefchat(self,messages,toolsNone,**kwargs)-ChatResponse:核心对话接口abstractmethoddefstream_chat(self,messages,toolsNone,**kwargs)-Generator:流式对话接口已实现的提供商提供商文件说明Anthropic Claudeanthropic_provider.py原生 Claude APIOpenAI GPTopenai_provider.pyOpenAI 官方 APIOpenAI Compatibleopenai_compatible.py兼容 OpenAI 格式的第三方 APIZhipu GLMglm_provider.py智谱 AIMiniMaxminimax_provider.pyMiniMax API4.5 技能系统Skill System技能系统是可编程扩展的核心基于Markdown 驱动的声明式配置---description:Explain code with diagrams and analogiesallowed-tools:-Read-Grep-Globarguments:[path]---Explain the code in $path. Start with an analogy,then draw a diagram.技能加载层级项目级技能.clawd/skills/或.claude/skills/目录用户级技能用户 home 目录下的技能内置技能随项目分发的默认技能技能运行时通过/skill-name命令触发支持命名参数传递工具沙箱限制allowed-tools白名单动态加载和热更新4.6 上下文压缩Compact Service为解决长对话的 token 限制问题系统实现了上下文压缩完整对话历史 → 触发压缩条件token 阈值 → 调用 /compact 命令 → 生成历史摘要 → 替换为压缩后的上下文 → 继续对话4.7 流式输出算法# 流式处理流程defstream_response(provider,messages,tools):# 1. 建立 SSE 连接streamprovider.stream_chat(messages,tools)# 2. 实时解析内容块forchunkinstream:ifchunk.typetext:# 2.1 文本块直接输出到终端yield(text,chunk.text)elifchunk.typetool_use:# 2.2 工具调用块显示工具执行状态yield(tool_start,chunk.name)elifchunk.typetool_result:# 2.3 工具结果块显示执行结果yield(tool_end,chunk.result)# 3. 完整响应缓存用于 /render-last 重新渲染cache_full_response()5. 关键数据流5.1 正常对话流程┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ │ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │ │ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │ └────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘ │ │ │ ┌───────────────────────────┘ │ │ 返回文本响应 │ ▼ │ ┌────────┐ │ │ 直接 │ └─┤ 输出 │ └────────┘5.2 工具调用流程┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ │ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │ │ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │ └────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘ ▲ │ │ 返回工具调用请求 │ │ ┌───────────────────────────┘ │ │ │ ▼ │ ┌──────────┐ ┌────────┐ │ │ Tool │───→│ 文件系统│ └─┤ Registry │ │ 网络等 │ └──────────┘ └────────┘6. 关键技术亮点6.1 架构设计亮点特性说明模块化设计30 独立模块职责清晰便于扩展抽象提供商统一接口支持多模型切换零成本工具沙箱技能级别的工具权限控制流式架构全链路流式处理无阻塞等待热加载技能Markdown 驱动无需重启即可扩展6.2 与原版 Claude Code 的对比维度Claude Code (原版)Clawd Code (本项目)语言TypeScriptPython开源闭源MIT 开源可扩展性有限高技能系统模型支持Anthropic 独占多提供商社区官方维护社区驱动7. 总结Clawd Code 是一个架构清晰、设计精良的 Claude Code Python 重实现。其核心价值在于完整的 Agent 架构ReAct 循环 Function Calling 工具系统生产级设计流式输出、会话管理、错误处理、权限控制高度可扩展技能系统、插件架构、多模型支持Python 原生充分利用 Python 生态易于二次开发该项目为理解 Claude Code 的内部工作原理提供了极佳的参考同时也是构建 Python Agent 应用的优质基础框架。
Clawd Code 技术分析
1. 项目概述Clawd Code又称 Claude-Code-Python是一个基于 Claude Code 原始 TypeScript 源码的完整 Python 重构实现。它不是一个简单的源码转储而是一个可运行的生产级 CLI Agent具备工具调用循环、流式 REPL、会话历史和多轮执行能力。属性说明仓库地址https://github.com/GPT-AGI/Clawd-Code开发语言Python 100%许可证MIT星标数345Fork 数180核心定位Claude Code 的 Python 重实现2. 核心设计思路2.1 设计哲学项目遵循以下核心设计原则高保真移植保留原始 Claude Code 的架构设计同时适配 Python 的惯用模式生产级运行真正的 Agent 运行时而非源码转储可扩展性可读性优先的 Python 代码库支持技能扩展多模型兼容通过抽象层支持多家 LLM 提供商2.2 核心工作流程用户输入(REPL/CLI) → 命令解析(Command System) → Agent 循环(Agent Loop) → LLM 调用(Provider) → 工具执行(Tool System) → 结果返回 → 流式输出(Stream Output)3. 整体架构框架3.1 模块结构30 子模块src/ ├── agent/ # Agent 核心对话与会话管理 │ ├── conversation.py # 对话数据模型Message/Conversation │ └── session.py # 会话状态管理 ├── assistant/ # 助手功能初始化占位 ├── bootstrap/ # 启动/初始化流程 ├── bridge/ # 桥接层 ├── buddy/ # 伙伴系统 ├── command_system/ # 命令系统 ├── compact_service/ # 上下文压缩服务 ├── components/ # UI 组件 ├── constants/ # 常量定义 ├── context_system/ # 上下文管理 ├── coordinator/ # 协调器 ├── entrypoints/ # 入口点定义 ├── hooks/ # 生命周期钩子 ├── keybindings/ # 键盘快捷键 ├── memdir/ # 内存目录管理 ├── migrations/ # 数据迁移 ├── native_ts/ # TypeScript 原生代码引用 ├── outputStyles/ # 输出样式 ├── plugins/ # 插件系统 ├── providers/ # LLM 提供商抽象层 │ ├── base.py # 提供商抽象基类 │ ├── anthropic_provider.py │ ├── openai_provider.py │ ├── openai_compatible.py │ ├── glm_provider.py │ └── minimax_provider.py ├── reference_data/ # 参考数据 ├── remote/ # 远程运行时 ├── repl/ # REPL 交互核心 │ └── core.py # REPL 主循环 ├── schemas/ # 数据模式定义 ├── screens/ # 终端界面 ├── server/ # 服务端组件 ├── services/ # 业务服务层 ├── skills/ # 技能系统 ├── state/ # 全局状态管理 ├── tool_system/ # 工具系统核心 │ ├── agent_loop.py # Agent 主循环 │ ├── context.py # 工具上下文 │ ├── defaults.py # 默认配置 │ ├── diff_utils.py # Diff 工具 │ ├── errors.py # 错误定义 │ ├── loader.py # 工具加载器 │ ├── permission_handler.py │ ├── permissions.py # 权限控制 │ ├── protocol.py # 工具调用协议 │ ├── registry.py # 工具注册表 │ ├── schema_validation.py │ ├── task_manager.py # 任务管理 │ └── tools/ # 内置工具集 ├── types/ # 类型定义 ├── upstreamproxy/ # 上游代理 ├── utils/ # 工具函数 ├── vim/ # Vim 集成 ├── voice/ # 语音功能 ├── cli.py # CLI 入口 ├── main.py # 主程序入口 ├── runtime.py # 运行时环境 ├── repl.py # REPL 实现 ├── config.py # 配置管理 └── context.py # 上下文管理3.2 分层架构┌─────────────────────────────────────┐ │ 用户界面层 │ │ CLI (cli.py) / REPL (repl/core.py) │ ├─────────────────────────────────────┤ │ 命令系统层 │ │ Command System / Skill System │ ├─────────────────────────────────────┤ │ Agent 核心层 │ │ Agent Loop / Conversation / Session │ ├─────────────────────────────────────┤ │ 提供商抽象层 │ │ Providers (Base 具体实现) │ ├─────────────────────────────────────┤ │ 工具系统层 │ │ Tool System / Registry / Protocol │ ├─────────────────────────────────────┤ │ 基础设施层 │ │ Config / State / Utils / Hooks │ └─────────────────────────────────────┘4. 核心原理与算法4.1 Agent 循环Agent LoopAgent 循环是整个系统的核心采用ReActReasoning Acting模式# 伪代码示意classAgentLoop:defrun(self,user_input):# 1. 将用户输入添加到对话历史conversation.add_user_message(user_input)# 2. 主循环思考-行动-观察whilenotdone:# 2.1 调用 LLM 获取响应responseprovider.chat(messagesconversation.messages,toolsavailable_tools# Function Calling)# 2.2 检查是否包含工具调用ifresponse.tool_uses:fortool_callinresponse.tool_uses:# 2.3 执行工具resultexecute_tool(tool_call)# 2.4 将工具结果添加到对话conversation.add_tool_result(result)else:# 2.5 直接返回文本响应returnresponse.content关键特性流式处理支持 SSEServer-Sent Events流式输出多轮迭代工具调用结果会反馈给 LLM 进行下一轮推理上下文窗口管理max_history100自动裁剪历史消息4.2 工具调用协议Tool Protocoldataclass(frozenTrue)classToolCall:name:str# 工具名称如 Read, Grep, WebFetchinput:dict# 工具参数tool_use_id:str# 唯一标识符dataclass(frozenTrue)classToolResult:name:str# 工具名称output:Any# 执行结果is_error:bool# 是否出错tool_use_id:str# 对应 ToolCall 的 IDcontent_type:str# text 或 json工具执行流程LLM 通过 Function Calling 返回ToolCall系统通过registry.py查找对应工具loader.py加载工具实现permission_handler.py检查权限执行工具并封装为ToolResult结果反馈到对话上下文4.3 对话管理系统dataclassclassMessage:role:str# user | assistant | systemcontent:str|list[ContentBlock]timestamp:str_is_internal:bool# 内部标记如压缩边界dataclassclassConversation:messages:list[Message]max_history:int100# 滑动窗口限制内容块类型TextContentBlock纯文本内容ToolUseContentBlock工具调用请求ToolResultContentBlock工具执行结果4.4 多提供商抽象架构classBaseProvider(ABC):def__init__(self,api_key,base_urlNone,modelNone):self.api_keyapi_key self.base_urlbase_url self.modelmodelabstractmethoddefchat(self,messages,toolsNone,**kwargs)-ChatResponse:核心对话接口abstractmethoddefstream_chat(self,messages,toolsNone,**kwargs)-Generator:流式对话接口已实现的提供商提供商文件说明Anthropic Claudeanthropic_provider.py原生 Claude APIOpenAI GPTopenai_provider.pyOpenAI 官方 APIOpenAI Compatibleopenai_compatible.py兼容 OpenAI 格式的第三方 APIZhipu GLMglm_provider.py智谱 AIMiniMaxminimax_provider.pyMiniMax API4.5 技能系统Skill System技能系统是可编程扩展的核心基于Markdown 驱动的声明式配置---description:Explain code with diagrams and analogiesallowed-tools:-Read-Grep-Globarguments:[path]---Explain the code in $path. Start with an analogy,then draw a diagram.技能加载层级项目级技能.clawd/skills/或.claude/skills/目录用户级技能用户 home 目录下的技能内置技能随项目分发的默认技能技能运行时通过/skill-name命令触发支持命名参数传递工具沙箱限制allowed-tools白名单动态加载和热更新4.6 上下文压缩Compact Service为解决长对话的 token 限制问题系统实现了上下文压缩完整对话历史 → 触发压缩条件token 阈值 → 调用 /compact 命令 → 生成历史摘要 → 替换为压缩后的上下文 → 继续对话4.7 流式输出算法# 流式处理流程defstream_response(provider,messages,tools):# 1. 建立 SSE 连接streamprovider.stream_chat(messages,tools)# 2. 实时解析内容块forchunkinstream:ifchunk.typetext:# 2.1 文本块直接输出到终端yield(text,chunk.text)elifchunk.typetool_use:# 2.2 工具调用块显示工具执行状态yield(tool_start,chunk.name)elifchunk.typetool_result:# 2.3 工具结果块显示执行结果yield(tool_end,chunk.result)# 3. 完整响应缓存用于 /render-last 重新渲染cache_full_response()5. 关键数据流5.1 正常对话流程┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ │ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │ │ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │ └────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘ │ │ │ ┌───────────────────────────┘ │ │ 返回文本响应 │ ▼ │ ┌────────┐ │ │ 直接 │ └─┤ 输出 │ └────────┘5.2 工具调用流程┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ │ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │ │ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │ └────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘ ▲ │ │ 返回工具调用请求 │ │ ┌───────────────────────────┘ │ │ │ ▼ │ ┌──────────┐ ┌────────┐ │ │ Tool │───→│ 文件系统│ └─┤ Registry │ │ 网络等 │ └──────────┘ └────────┘6. 关键技术亮点6.1 架构设计亮点特性说明模块化设计30 独立模块职责清晰便于扩展抽象提供商统一接口支持多模型切换零成本工具沙箱技能级别的工具权限控制流式架构全链路流式处理无阻塞等待热加载技能Markdown 驱动无需重启即可扩展6.2 与原版 Claude Code 的对比维度Claude Code (原版)Clawd Code (本项目)语言TypeScriptPython开源闭源MIT 开源可扩展性有限高技能系统模型支持Anthropic 独占多提供商社区官方维护社区驱动7. 总结Clawd Code 是一个架构清晰、设计精良的 Claude Code Python 重实现。其核心价值在于完整的 Agent 架构ReAct 循环 Function Calling 工具系统生产级设计流式输出、会话管理、错误处理、权限控制高度可扩展技能系统、插件架构、多模型支持Python 原生充分利用 Python 生态易于二次开发该项目为理解 Claude Code 的内部工作原理提供了极佳的参考同时也是构建 Python Agent 应用的优质基础框架。
