最近在看 Claude Code 源码学习 Agent 开发，本着动手做巩固知识的想法，决定用 Python 复现一个类似的 Code Agent，顺便尝试着用用自己学到的 Harness 工程的相关知识。于是做了这个叫 OneCode 的项目，历时几个星期，踩了不少坑，最终实现了一个可以在终端中交互的 Coding Agent，支持会话历史恢复、MCP 和 Skill 的接入、Task 系统、SubAgent 委托等功能。

项目地址：https://github.com/EtherealStar/OneCode
给个Star谢谢喵

---

效果预览

OneCode 主界面

在激活虚拟环境之后，使用 uv run python -m ui.cli.app 启动 OneCode。

OneCode 输入 / 后的命令自动补全界面

输入 / 后的 OneCode 可以自动补全命令，可以继续输入也可以在键盘按上下键选择后按回车发送并执行命令，按 Tab 则是只补全命令。

OneCode 调用 frontend-slides skill 生成的 HTML Slide

这是 OneCode 接入 DeepSeek-V4-Pro 后，调用内置 frontend-slides skill 为自己生成的项目介绍幻灯片的第一张。

OneCode执行任务时的截图

可以看到 OneCode 在执行过程中可以正常调用 read_file、bash、write_file 等工具，读取 skill 模板、创建目录、并行生成三套风格的预览文件，还能使用 bash 打开浏览器预览网页。

---

核心功能

OneCode 参考 Claude Code 的分层架构，用 Python 从零实现，整体分为 6 层，每层都有独立的设计文档。以下是已实现的主要特性：

上下文工程

长对话中 Token 消耗是个核心问题。OneCode 实现了上下文压缩机制，在对话历史超出阈值时自动摘要旧消息，还有裁剪工具输出的微压缩等等。

记忆机制

引入了持久化长期记忆，存储在 .onecode/memory/ 目录下。Agent 可以在多次会话中积累对项目的理解，避免每次都从零开始读代码。

会话历史恢复

支持 /resume 命令恢复历史会话，会话消息序列化为 JSONL 文件，可以精确回到上次中断的状态继续工作。

附件系统

支持使用 @ 输入文件名或者文件夹名选取附件，并发送给 OneCode。

MCP和Skills

可以将外部 MCP工具集成进 OneCode 的工具集。也实现了实现了 skill 加载机制，OneCode 可以读取 .onecode/skills/ 下的 skill ，按需调用。

Task System与Background Task任务

实现了 TaskStore 和基于 Hook 的任务生命周期事件系统。支持创建持久化任务（task_create）、查询（task_list/task_get）、更新（task_update），并通过 Hook 机制在任务状态变更时触发回调。后台任务支持与主会话并行执行。

SubAgent 子智能体委托

实现了 agent 工具，支持将复杂的研究或规划子任务委托给独立的子智能体并行处理，主 Agent 等待结果后继续后续步骤。

多 Provider 支持

这里只展示了接入DeepSeek模型，实际上展示的供应商都可以接入的。

---

架构设计

项目整体分 6 层，各层之间职责清晰，每个模块都有对应的设计文档。

OneCode/
├── ui/                  # CLI 终端渲染层（流式输出、Streaming UI）
├── core/                # Agent Loop 核心（ReAct 架构）
├── tools/               # 工具层（`read_file`, `write_file`, `bash`, `glob`, `grep` 等）
├── tasks/               # 任务管理（Task System）
├── memory/              # 记忆层（长期记忆、会话历史）
├── skills/              # Skill 加载与调度
├── mcp/                 # MCP 工具接入
└── docs/
    ├── AGENTS.md        # 项目指南（供 Agent 阅读）
    └── exec-plans/
        └── completed/   # 各功能模块的开发计划与执行记录

AGENTS.md 是为 Agent 准备的项目说明文件。将 OneCode 项目本身克隆到工作区后，让 Agent 先读这个文件，它就能自主理解整个仓库的架构和开发脉络，然后帮你继续开发或解读代码。

大部分功能模块的开发过程都记录在 docs/exec-plans/completed/ 下的计划文档里，可以看到每个功能从设计到实现的完整思路。

---

Harness 工程

整个项目的开发过程引入了学到的 Harness 工程 的理念，不过主要是文件夹安排和文档组织这方面的。AI帮我总结的时候是这么说的

未来的一些想法

考虑升级下OneCode现有的计划模式，把我现在用Agent时候常用的与Agent讨论最后再执行计划的流程在OneCode里实现，然后试试能不能实现些Claude Code和Codex可能没做到的功能，也许吧。

---

欢迎 PR 和 Star

项目还有很多可以改进的地方，欢迎提 Issue 或 PR。
如果这个项目对你有参考价值，请给个 Star。做这个项目快把孩子搞崩溃了。
项目地址：https://github.com/EtherealStar/OneCode