diff --git a/README.md b/README.md index 971fac94e..3ced6ddb8 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # CoreCoder -**The nanoGPT of coding agents. A 1.5k-line engine inside 3,370 readable lines of pure Python: understand how a coding agent actually works, then fork your own.** +**The nanoGPT of coding agents. A 1.5k-line engine inside 3,374 readable lines of pure Python: understand how a coding agent actually works, then fork your own.** *learn from it · fork it · ship something better* @@ -12,7 +12,7 @@ [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions) -[![engine](https://img.shields.io/badge/engine-1528_LoC-blue)](article/00-index_EN.md) +[![engine](https://img.shields.io/badge/engine-1532_LoC-blue)](article/00-index_EN.md) [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md) @@ -25,7 +25,7 @@ | | CoreCoder | Claude Code | aider | nanoGPT | |---|---|---|---|---| -| Lines of code | ~1,528 engine / 3,370 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) | +| Lines of code | ~1,532 engine / 3,374 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) | | Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon | | Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes | | What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching | @@ -36,9 +36,9 @@ The nanoGPT column is there as a reference point: minimal, readable, but it teac I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly. -The engine (loop, model interface, context, tools, sessions) is 1,528 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,370 physical lines, 2,783 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below. +The engine (loop, model interface, context, tools, sessions) is 1,532 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,374 physical lines, 2,787 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below. -And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. Anything that would mutate your disk or run a command stops for your consent first. The suite has 368 offline tests and an opt-in live smoke test. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work. +And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. Anything that would mutate your disk or run a command stops for your consent first. The suite has 373 offline tests and an opt-in live smoke test. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work. The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change. @@ -92,7 +92,7 @@ corecoder/ ├── agent.py agent loop + parallel tool exec 240 lines ← start here ├── llm.py streaming client + retry + cost 364 lines ├── context.py three-tier context compaction 251 lines -├── session.py save / resume + path-traversal guard 97 lines +├── session.py save / resume + path-traversal guard 101 lines ├── permissions.py consent for mutating tools 81 lines ├── hooks.py Pre/PostToolUse shell hooks 87 lines ├── shell.py POSIX shell routing (Git Bash on Windows) 61 lines diff --git a/README_CN.md b/README_CN.md index 6382089f8..b6b13409b 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,7 +2,7 @@ # CoreCoder -**编程 agent 里的 nanoGPT。1.5k 行引擎、整包 3370 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。** +**编程 agent 里的 nanoGPT。1.5k 行引擎、整包 3374 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。** *learn from it · fork it · ship something better* @@ -12,7 +12,7 @@ [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions) -[![engine](https://img.shields.io/badge/engine-1528_LoC-blue)](article/) +[![engine](https://img.shields.io/badge/engine-1532_LoC-blue)](article/) [![源码导读](https://img.shields.io/badge/源码导读-8篇双语-orange)](article/) @@ -25,7 +25,7 @@ | | CoreCoder | Claude Code | aider | nanoGPT | |---|---|---|---|---| -| 代码量 | 引擎约 1528 行 / 整包 3370 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) | +| 代码量 | 引擎约 1532 行 / 整包 3374 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) | | 读完要多久 | 一个下午 | 读不了(闭源) | 得啃几天 | 一个下午 | | 能不能下断点改了再跑 | 能,每一行 | 不能 | 能,但量大 | 能 | | 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT | @@ -36,9 +36,9 @@ nanoGPT 那一列是拿来对照的:它最小、可读,但教的是训一个 我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底,核心是一个 while 循环套着一个大模型,外加七八个让它能真正动手的工具。难的从来不是这个循环,而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。 -引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1528 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3370 行、净 2783 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。 +引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1532 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3374 行、净 2787 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。 -它真能跑:读写文件、执行 shell、派子 agent、分三层压上下文,还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用,都会先停下来等你点头。现在有 368 个离线测试,另有按需开启的真实 API 冒烟。但能跑不是为了劝你拿去日用,而是为了让这份「注释」不撒谎:一个解释 agent 怎么运作的范例,自己得真能运作。 +它真能跑:读写文件、执行 shell、派子 agent、分三层压上下文,还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用,都会先停下来等你点头。现在有 373 个离线测试,另有按需开启的真实 API 冒烟。但能跑不是为了劝你拿去日用,而是为了让这份「注释」不撒谎:一个解释 agent 怎么运作的范例,自己得真能运作。 代码来自一次公开拆解。公开的源码分析里,Claude Code 这类生产级 agent 暴露出不少关键架构,我挑出最核心的一层,用尽量少的代码诚实地复写了一遍。所以读 CoreCoder,约等于读一份基于公开源码分析的「可运行注释版」:讲的是这类 agent 的核心思路,而它本身只是最小复写,就摆在你机器上,随你拆、随你改。 @@ -92,7 +92,7 @@ corecoder/ ├── agent.py agent 主循环 + 并行工具执行 240 行 ← 从这里开始读 ├── llm.py 流式客户端 + 重试 + 成本统计 364 行 ├── context.py 三层上下文压缩 251 行 -├── session.py 会话存盘 / 续聊 + 路径穿越防护 97 行 +├── session.py 会话存盘 / 续聊 + 路径穿越防护 101 行 ├── permissions.py 改动类工具的用户授权 81 行 ├── hooks.py 工具调用前后的用户 shell 钩子 87 行 ├── shell.py POSIX shell 路由(Windows 走 Git Bash) 61 行 diff --git a/article/06-session-and-cli.md b/article/06-session-and-cli.md index 85710b0d8..ab3a086e4 100644 --- a/article/06-session-and-cli.md +++ b/article/06-session-and-cli.md @@ -1,6 +1,6 @@ # 把它跑成一个真正的命令行工具 -前五篇拆的是 agent 的内脏:循环、工具、模型接口、上下文压缩、并发与子 agent。这些零件再漂亮,你也没法直接用,因为还缺一层皮,一个让人能坐下来跟它对话、能存盘、能续聊、能查状态的命令行界面。这一篇讲这层皮,对应 `cli.py`(404 行)和 `session.py`(97 行)。 +前五篇拆的是 agent 的内脏:循环、工具、模型接口、上下文压缩、并发与子 agent。这些零件再漂亮,你也没法直接用,因为还缺一层皮,一个让人能坐下来跟它对话、能存盘、能续聊、能查状态的命令行界面。这一篇讲这层皮,对应 `cli.py`(404 行)和 `session.py`(101 行)。 它不光是「锦上添花的 UI」。这层皮里藏着一个很值得讲的安全细节,我们留到后面压轴。 diff --git a/corecoder/session.py b/corecoder/session.py index d03562b1e..15f3ce9dd 100644 --- a/corecoder/session.py +++ b/corecoder/session.py @@ -64,6 +64,8 @@ def load_session(session_id: str) -> tuple[list[dict], str] | None: try: data = json.loads(path.read_text(encoding="utf-8")) + if not isinstance(data, dict): + return None return data["messages"], data["model"] except (json.JSONDecodeError, UnicodeDecodeError, KeyError, OSError): # a corrupt or truncated session file shouldn't crash resume @@ -79,6 +81,8 @@ def list_sessions() -> list[dict]: for f in sorted(SESSIONS_DIR.glob("*.json"), reverse=True): try: data = json.loads(f.read_text(encoding="utf-8")) + if not isinstance(data, dict): + continue # grab first user message as preview preview = "" for m in data.get("messages", []): diff --git a/pyproject.toml b/pyproject.toml index bcdba694d..a34a52f85 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "corecoder" version = "0.14.0" -description = "Minimal AI coding agent (3,370 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)" +description = "Minimal AI coding agent (3,374 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)" readme = "README.md" license = "MIT" requires-python = ">=3.10" diff --git a/tests/test_session.py b/tests/test_session.py index c720dffaa..1329ca991 100644 --- a/tests/test_session.py +++ b/tests/test_session.py @@ -1,3 +1,5 @@ +import pytest + from corecoder import session as session_module from corecoder.session import load_session, save_session @@ -64,6 +66,16 @@ def test_corrupt_session_file_returns_none(tmp_path, monkeypatch): assert load_session("broken") is None +@pytest.mark.parametrize("record", ["[]", "null", "42", '\"hello\"']) +def test_non_object_session_file_returns_none(tmp_path, monkeypatch, record): + monkeypatch.setattr(session_module, "SESSIONS_DIR", tmp_path) + fixture = tmp_path / "not_a_session.json" + fixture.write_text(record, encoding="utf-8") + + assert load_session("not_a_session") is None + assert fixture.read_text(encoding="utf-8") == record + + def test_session_roundtrips_unicode(tmp_path, monkeypatch): monkeypatch.setattr(session_module, "SESSIONS_DIR", tmp_path) diff --git a/tests/test_session_catalog_cli.py b/tests/test_session_catalog_cli.py index 3b7ffcd3e..8f56f970b 100644 --- a/tests/test_session_catalog_cli.py +++ b/tests/test_session_catalog_cli.py @@ -36,6 +36,20 @@ def test_list_sessions_offline(isolated_sessions, monkeypatch, capsys): assert path.read_bytes() == before +def test_list_sessions_skips_non_object_record(isolated_sessions, monkeypatch, capsys): + sid = session.save_session([{"role": "user", "content": "keep this"}], "m") + unreadable = isolated_sessions / "zz_not_a_session.json" + unreadable.write_text("[]", encoding="utf-8") + monkeypatch.setattr(sys, "argv", ["corecoder", "--list-sessions"]) + + cli.main() + + output = capsys.readouterr().out + assert sid in output + assert "zz_not_a_session" not in output + assert unreadable.read_text(encoding="utf-8") == "[]" + + def test_list_sessions_empty_is_read_only(isolated_sessions, monkeypatch, capsys): monkeypatch.setattr(sys, "argv", ["corecoder", "--list-sessions"])