nanoPyCodeAgent 0.3.0__tar.gz → 0.5.0__tar.gz

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/.agents/skills/release/SKILL.md

@@ -50,12 +50,18 @@ Read the entries under `## [Unreleased]` and propose the next semver `X.Y.Z`:
 **0.x caveat:** on `0.y.z` a minor may still contain breaking changes; treat the
 proposal as a suggestion. The maintainer makes the final call at the gate (step 5).
 
-### 4. Cut the changelog
+### 4. Cut the changelog and date the dev notes
 In `<series>`:
 - rename `## [Unreleased]` to `## [X.Y.Z] - <today YYYY-MM-DD>`, keeping its entries;
 - add a fresh empty `## [Unreleased]` section above it.
 
-Touch no other file — dev notes and README were synced per-PR by `land-pr`.
+In `docs/dev_notes/zh-CN/<series>.md` and `docs/dev_notes/en/<series>.md`,
+replace the `YYYY.MM.DD` placeholder in the `## X.Y.Z - YYYY.MM.DD` heading
+with today's date (dot-separated). Skip if the dev notes have no section for
+this version.
+
+Touch no other file — dev notes content and README were synced per-PR by
+`land-pr`.
 
 ### 5. ⛔ Confirmation gate (mandatory)
 Present to the maintainer: the proposed **version** `X.Y.Z` and the **changelog

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/.agents/skills/release/scripts/verify-release.sh

@@ -60,9 +60,14 @@ grep -q '\.tar\.gz$' <<<"$assets" || fail "Release ${tag} missing an sdist (.tar
 printf 'OK: GitHub Release %s has wheel + sdist\n' "$tag"
 
 # 3. uvx smoke test (official index, with retries) ------------------------
+# --default-index (not --index): --index only *adds* an index, and uv's
+# first-index strategy would stop at a locally configured mirror that has the
+# package but not the new version yet. --refresh: uv's cached simple-index
+# metadata can be stale right after a publish. </dev/null: the entry point
+# reads stdin; EOF makes it exit immediately instead of hanging interactively.
 log "Smoke-testing uvx ${PACKAGE}@${version}"
 deadline=$(( $(date +%s) + POLL_TIMEOUT ))
-until uvx --index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1; do
+until uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1 </dev/null; do
   (( $(date +%s) >= deadline )) && fail "uvx smoke test failed for ${PACKAGE}@${version} after ${POLL_TIMEOUT}s"
   printf 'uvx not ready (index propagation?); retrying in %ss...\n' "$POLL_INTERVAL"; sleep "$POLL_INTERVAL"
 done

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/.gitignore

@@ -216,3 +216,5 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+references/

nanopycodeagent-0.5.0/.ignore

@@ -0,0 +1 @@
+!references/

nanopycodeagent-0.5.0/.zed/debug.json

@@ -0,0 +1,20 @@
+[
+  {
+    "label": "nanoPyCodeAgent: CLI",
+    "adapter": "Debugpy",
+    "request": "launch",
+    "program": "$ZED_WORKTREE_ROOT/.venv/bin/nanoPyCodeAgent",
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "console": "integratedTerminal",
+    "justMyCode": true
+  },
+  {
+    "label": "nanoPyCodeAgent: all tests",
+    "adapter": "Debugpy",
+    "request": "launch",
+    "module": "pytest",
+    "args": ["-q"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "justMyCode": true
+  }
+]

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanoPyCodeAgent
-Version: 0.3.0
+Version: 0.5.0
 Summary: A nano code agent built from scratch in pure Python.
 Project-URL: Homepage, https://github.com/minixalpha/nanoPyCodeAgent
 Project-URL: Repository, https://github.com/minixalpha/nanoPyCodeAgent

nanopycodeagent-0.5.0/docs/changelogs/0.4.x.md

@@ -0,0 +1,34 @@
+# Changelog — 0.4.x
+
+All notable changes in the **0.4.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-07-14
+
+### Added
+- A `bash` tool with a tool-use loop: the model can now run shell commands and
+  read their output. Each command and its result are echoed to the terminal as
+  they happen; long output is truncated and hung commands are killed after a
+  timeout.
+- Tool commands and output are shaded with a background color so they read
+  apart from the agent's own text (skipped when stdout is not a terminal or
+  `NO_COLOR` is set).
+
+### Changed
+- The agent loop now handles only the happy path: anything unexpected — a
+  network error, a Ctrl-C mid-turn, a malformed config file — crashes the
+  session, and restarting it is the recovery. The previous hardened variant is
+  preserved at the `hardened-agent-loop` tag.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.4.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

nanopycodeagent-0.5.0/docs/changelogs/0.5.x.md

@@ -0,0 +1,35 @@
+# Changelog — 0.5.x
+
+All notable changes in the **0.5.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-07-29
+
+### Added
+- A dedicated `read` tool for viewing files: it returns the content with
+  1-based line numbers, `cat -n` style, and takes `offset`/`limit` to read a
+  window of a large file. Output is capped at 2000 lines and 50000 characters
+  per call, truncated only at line boundaries; a truncated result names the
+  range returned, the file's total line count, and the offset to continue
+  from. Files over 10 MB, binary files, and non-regular files (directories,
+  FIFOs, device files) are rejected, and every error message points at the
+  next action to take.
+
+### Changed
+- The startup banner now prints the installed package version, so it is clear
+  which version is running.
+- The system prompt now tells the model to prefer the `read` tool for viewing
+  files and to use `bash` for running commands and searching with `grep`.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.5.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/docs/dev_notes/README.md

@@ -11,3 +11,8 @@ Notes are bilingual, split by language:
 These are free-form notes — insights, takeaways, and design decisions gathered
 while developing each series, with no fixed structure. User-facing changes live
 in [`../changelogs/`](../changelogs/).
+
+The date in a `## X.Y.Z - YYYY.MM.DD` section heading is the **release date**
+of that version (the same date as the git tag and the changelog entry). While
+the version is unreleased, keep the literal `YYYY.MM.DD` placeholder — it is
+filled in by the release process.

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/docs/dev_notes/en/0.2.x.md

@@ -2,7 +2,7 @@
 
 > Generated from the Chinese source [`../zh-CN/0.2.x.md`](../zh-CN/0.2.x.md). Do not edit by hand.
 
-## 0.2.0 - 2026.06.29
+## 0.2.0 - 2026.07.09
 
 This release implements a minimally functional chatbot that holds a multi-turn conversation with the LLM through the [Messages](https://platform.claude.com/docs/en/api/python/messages/create) API.
 

nanopycodeagent-0.5.0/docs/dev_notes/en/0.4.x.md

@@ -0,0 +1,68 @@
+# Development Notes — 0.4.x
+
+> Generated from the Chinese source [`../zh-CN/0.4.x.md`](../zh-CN/0.4.x.md). Do not edit by hand.
+
+## 0.4.0 - 2026.07.14
+
+### The bash tool
+
+This version adds tool use, starting with a single bash tool. The bash tool can do almost anything — powerful yet simple — and it makes a good base to gradually split other tools out of, which will make it easy to compare having more tools against having just the one bash tool.
+
+Also, with no test environment for the other systems, Linux is the only platform that can be fully tested. Mac's bash is probably fairly similar to Linux's?
+
+### Background color for tool output
+
+I tried giving tool output a background color so it stands apart from the agent's text output, similar to the pi code agent's implementation.
+
+Along the way I learned how changing the terminal background color actually works:
+
+```
+1. Terminal colors are "in-band control": styling is mixed into the data stream
+
+Between a program and the terminal there is only one byte stream — no separate
+styling channel. To change how things look, you insert control sequences
+starting with ESC (\x1b) into the stream. The \x1b[<params>m family is called
+SGR (Select Graphic Rendition); it changes the terminal's current "brush"
+state — every character printed afterwards is written into its screen cell
+with the current brush attributes, until the brush changes again. The byte
+stream for each output line is really:
+
+\x1b[48;5;236m  [bash]$ ls ...  \x1b[K   \x1b[0m  \n
+└─ set bg color ─┘ └── text ──┘ └erase to EOL┘ └reset┘
+
+2. 48;5;236: dark gray from the 256-color palette
+
+48;5;N means "background color = entry N of the 256-color palette". The
+palette has three segments: 0–15 basic colors, 16–231 the color cube, 232–255
+the grayscale ramp. Entry 236 is a dark gray (about #303030). Picking the
+grayscale ramp over the basic background colors 41–47 is deliberate: basic
+colors get remapped by the user's terminal theme and can be harsh on the eyes,
+while grays stay "just a bit lighter than the base color" under any theme —
+exactly right for visual layering.
+
+3. \x1b[K makes the color block fill the whole line
+
+Background color only applies to cells where characters were actually
+printed; the blank space at the end of a line keeps the default background,
+so the block hugs the text with a ragged right edge. \x1b[K (Erase in Line)
+erases from the cursor to the end of the line, and mainstream terminals
+implement BCE (Background Color Erase): erased cells are filled with the
+current background color. So emitting \x1b[K before resetting the brush
+amounts to "painting the rest of this line dark gray" — which is why the
+blocks in the screenshot are clean rectangles.
+```
+
+### From production hardening back to the core
+
+The implementation had come to feel somewhat complex: the edge-case handling was crowding out the core. Those edge cases matter in a production-grade application, but for now, as long as normal use is unaffected, they hardly seem necessary.
+
+With that in mind, I stripped out the production hardening wholesale and kept only the core flow. The design principle moves from "repair history and survive on error" to "crash on the unexpected, restart to recover":
+
+- **Agent loop**: the per-moment Ctrl-C history repair, the API-error rollback (`ran_tools` / `turn_start`), patching `tool_result`s for truncated replies, and the per-turn request budget (`MAX_REQUESTS_PER_TURN`) are all deleted; the loop handles only the happy path.
+- **bash tool**: switched to `subprocess.run`; temp-file capture, process-group kill, capped per-stream reads, and NUL protection are all removed. Known trades: a background child (`some_server &`) blocks until the timeout; the timeout kills bash itself, with no guarantee of killing the whole process tree; and text mode translates `\r` in output to `\n`.
+- **terminal**: only this version's new tool-output background shading remains; control-character stripping and the stdout encoding fallback are removed.
+- **settings**: happy path only — a missing file is normal, a corrupt file simply raises.
+
+What stays is what genuinely belongs to agent design itself: the tool_use / tool_result pairing protocol, output truncation (protecting the context window), the command timeout, and `is_error` meaning only tool failure (the exit code goes into the result text, so the model can tell a negative answer from a failed execution).
+
+The source drops from 544 lines to 262, with agent.py going from 250 to 116 — the main loop now fits on one screen. How each edge case was discovered is recorded in the git history; the hardened version before the trim is preserved under the `hardened-agent-loop` tag.

nanopycodeagent-0.5.0/docs/dev_notes/en/0.5.x.md

@@ -0,0 +1,57 @@
+# Development Notes — 0.5.x
+
+> Generated from the Chinese source [`../zh-CN/0.5.x.md`](../zh-CN/0.5.x.md). Do not edit by hand.
+
+## 0.5.0 - 2026.07.29
+
+### Printing the version
+
+When the tool starts up without printing its version, I sometimes cannot tell which version I am actually running. So let's build that first.
+
+### Built-in tools in common code agents
+
+For a survey of the built-in tools of mainstream code agents, see [Built-in Tools in Common Code Agents](../../research/agent_tools.md) (Chinese).
+
+### Designing the built-in tools
+
+As the survey shows, beyond the core file/command tools that something like pi offers, the other agents have grown a large number of tools around subagent orchestration, task management, scheduling, user interaction, and so on. For our nano code agent, though, let's start expanding from the most basic category of all: file operations.
+
+#### The read tool
+
+We also surveyed the [read tool](../../research/read_tool.md) (Chinese): apart from codex, every code agent has a dedicated read tool. pi and opencode are model-agnostic, and you can see it in their read tools — their limits are line counts and file sizes, with no token limit. The other, model-specific code agents all have token limits; presumably because they only support their own vendor's models, where tokens are easier to count?
+
+Functionally, read and bash both seem able to satisfy the need to read a file. Even accounting for files that may exceed a size limit, bash can still read them fine. Take codex: in actual testing, whatever the size of the file, it always starts with a `sed -n '1,260p' foo.md`, and then, if it finds there is more, it may follow up with `wc -l foo.md && sed -n '1,260p' foo.md` — reading chunk by chunk, which looks a lot like the `limit` of a dedicated read tool. But I'm not sure whether, for any given model, reading files is better done with a dedicated tool or with `bash`.
+
+Another advantage of the read tool is that it makes it easy to constrain the agent to read-only operations, whereas bash is less directly controllable at the tool layer — which means control has to happen somewhere else, in a sandbox for instance. While testing the programmatic APIs of claude code, pi, and codex, I found that claude code and pi only need to be configured to use the read tool to be restricted to read-only operations, while codex needs a sandbox (`codex --sandbox read_only`).
+
+OpenAI's 2024 paper [SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering](https://arxiv.org/abs/2405.15793) argues that designing a dedicated tool set works better than using bash alone. But that is 2024 work, and models are certainly more capable now, so I don't know whether plain bash is in fact better (codex reads files with bash itself). We can't verify any of this for now, though — we probably need our set of basic tools to be a bit more complete before it can be tested. For the moment we can start by implementing basic tool capabilities similar to pi's.
+
+Here is what read implements today:
+
+**Interface**
+
+- **Parameters**: `path` (required, absolute or relative, `~` is expanded), `offset` (which line to start from, 1-based, default 1), `limit` (how many lines to return at most; omit it to read up to the line cap, and larger values are clamped to it). The line cap is interpolated into the schema description straight from the constant, because `limit` is the parameter the model can actively control — let it pick the right window size in one shot, instead of passing 5000, being silently cut to 2000, and only realizing after the fact from the truncation hint. The character cap, by contrast, is not mentioned in `limit`'s description: the model has no corresponding parameter to tune, so knowing the number would not change how it calls the tool; when it is hit, the runtime truncation hint and error messages explain it more effectively.
+- **Output format**: `cat -n` style, with a 1-based line number in front of every line (width 6 plus a tab), so it looks just like `cat -n` in bash and the model can cite line numbers directly.
+
+**Caps and truncation**
+
+- **Two output caps**: at most 2000 lines and 50000 characters per call, truncating at whichever is hit first, and **only at line boundaries** — a line is never cut in half. This way a single file cannot flood the context in one go.
+- **Continuation hint**: when the window stops short of the end of the file, the output ends with `[showing lines a-b of N; continue with offset=x]`, telling the model both the total line count and where to resume next time, so it doesn't need another `wc -l`.
+
+**Handling file content**
+
+- **Encoding**: decoded as UTF-8, with invalid bytes falling back to the replacement character (`errors="replace"`), matching the bash tool's tolerance.
+- **Splitting lines**: on `\n` alone, not with `splitlines()` — that one also breaks on `\x0c`, `\x0b`, `\x85` and U+2028, which puts the line numbers out of step with `sed`, `grep -n` and the editor; and the over-long-line error hands over exactly a `sed -n 'Np'`, which would then slice the wrong line. A trailing `\r` is dropped, so CRLF files read like LF ones.
+- **Binary rejection**: a `\x00` in the first 8KB marks the file as binary and it is rejected, to avoid stuffing garbage into the context.
+
+**Error handling**
+
+- **One return convention**: every error path returns `is_error=True`, covering `offset < 1`, `limit < 1`, a missing file, a path that is a directory or any other non-regular file, other `OSError`s, binary files, an `offset` past the total line count, and a single line over the character cap. An empty file returns `(empty file)`.
+- **Only regular files are opened**: a FIFO blocks until something writes to it, and a device file like `/dev/zero` never ends — and read has no timeout to escape that the way the bash tool does, so the type check has to come before the read.
+- **Error messages name the next action**: the message says not just "what went wrong" but "what to do next". For example, when `offset` is past the end of the file, it reports how many lines the file actually has; when a line is longer than the character cap, it hands over a bash command for the model to slice it itself (`sed -n 'Np' -- file | cut -c 1-2000`). That command is meant to be run, so the path in it is expanded first (quoting would stop the shell from expanding `~` itself), then escaped with `shlex.quote` and placed behind `--` — a space, a `$(...)` or a leading `-` in a filename should never get to reshape the command.
+
+**Division of labor with bash, and implementation trade-offs**
+
+- **The tool description steers the division of labor**: it tells the model to prefer read over bash's `cat`/`sed` for viewing files, while searching (`grep`) and slicing over-long lines still go through bash.
+- **The whole file is read into memory**: good enough for source and config files, and the output caps already bound what actually reaches the context, so there is no streaming read. The cost is that the line and character caps only get their turn once the whole file has been loaded, so there is one more gate in front of the read: a 10 MB byte cap, over which the file is turned away and the model is pointed at bash to slice it, so a multi-gigabyte log cannot blow up the process. That number is far more generous than the output caps because a small window may well sit deep inside a large file — it only has to stop files that should never be loaded at all.
+- **Call display**: the agent prints `[read] <path>` when executing, keeping the same style as the bash tool's call display.

{nanopycodeagent-0.3.0 → nanopycodeagent-0.5.0}/docs/dev_notes/zh-CN/0.2.x.md

@@ -2,7 +2,7 @@
 
 > 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.2.x.md`](../en/0.2.x.md) 由其生成。
 
-## 0.2.0 - 2026.06.29
+## 0.2.0 - 2026.07.09
 
 这个版本实现了一个最小功能的 chatbot，使用 [Message](https://platform.claude.com/docs/en/api/python/messages/create) 接口，完成与 LLM 的多轮对话。
 

nanopycodeagent-0.5.0/docs/dev_notes/zh-CN/0.4.x.md

@@ -0,0 +1,49 @@
+# 开发笔记 — 0.4.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.4.x.md`](../en/0.4.x.md) 由其生成。
+
+## 0.4.0 - 2026.07.14
+
+### bash 工具
+
+此版本增加 tool use 功能，首先增加一个 bash 工具，bash 工具几乎可以做任何事，功能强大又简单，可以以此为基础，再逐步拆分出其他工具，方便对比增加其他工具后与单一 bash 工具的区别。
+
+另外，由于其他系统无测试环境，能完全测试的只有 Linux。Mac 与 Linux 的 bash 可能比较类似？
+
+### 工具输出背景色
+
+尝试给工具输出增加背景颜色，这样方便与 agent 的文本输出有区分，类似 pi code agent 的实现。
+
+另外，学习了终端改背景色的原理：
+
+```
+1. 终端颜色是"带内控制"：样式混在数据流里
+
+程序和终端之间只有一条字节流，没有独立的样式通道。想改变显示效果，就往流里插入以 ESC（\x1b）开头的控制序列。\x1b[<参数>m 这一族叫 SGR（Select Graphic Rendition），它修改终端当前的"画笔"状态——之后打印的每个字符都带着当前画笔属性写进屏幕单元格，直到画笔再次被改。每行输出的字节流实际是：
+
+\x1b[48;5;236m  [bash]$ ls ...  \x1b[K   \x1b[0m  \n
+└─ 设背景色 ─┘  └── 文字 ──┘  └擦到行尾┘ └重置┘
+
+2. 48;5;236：256 色调色板里的深灰
+
+48;5;N 表示"背景色 = 256 色调色板第 N 号"。调色板分三段：0–15 基本色、16–231 色立方、232–255 灰阶梯。236 号是深灰（约 #303030）。选灰阶而不选 41–47 基本背景色，是因为基本色会被用户终端主题重映射、容易刺眼；灰阶在各种主题下都只是"比底色浅一点"，做层次区分正合适。
+
+3. \x1b[K 让色块铺满整行
+
+背景色只作用于实际打印了字符的单元格，行尾空白仍是默认背景，色块会紧贴文字、右缘参差。\x1b[K（Erase in Line）从光标擦到行尾，而主流终端实现了 BCE（Background Color Erase）：擦除时用当前背景色填充。所以在重置画笔前发一个 \x1b[K，等于"用深灰刷满本行剩余部分"——这就是截图里色块是整齐矩形的原因。
+```
+
+### 从生产级加固回到核心
+
+我觉得目前的实现，似乎有些复杂，边界条件的处理反而让核心内容不够明显。这些边界条件在生产级应用时有用，但目前如果不影响正常使用，似乎并无必要。
+
+基于这个想法，把生产级加固整体剥离，只保留核心流程。设计原则从「出错时修复历史并存活」改为「意外即崩溃，重启即恢复」：
+
+- **agent 循环**：Ctrl-C 分时刻的历史修复、API 错误回滚（`ran_tools` / `turn_start`）、截断回复补 `tool_result`、每轮请求预算（`MAX_REQUESTS_PER_TURN`）全部删除，循环只处理快乐路径。
+- **bash 工具**：改用 `subprocess.run`，临时文件捕获、进程组击杀、分流限量读、NUL 防护全部移除。已知取舍：后台子进程（`some_server &`）会阻塞到超时；超时只杀 bash 本体，不保证杀掉整棵进程树；文本模式会把输出中的 `\r` 转成 `\n`。
+- **terminal**：只保留本版新增的工具输出背景色，控制字符剥离和 stdout 编码兜底移除。
+- **settings**：只保留快乐路径 —— 文件缺失属正常，文件损坏直接抛异常。
+
+保留下来的是真正属于 agent 设计本身的部分：tool_use / tool_result 的配对协议、输出截断（保护上下文窗口）、命令超时、`is_error` 只表示工具失败（退出码写进正文，让模型区分「否定答案」和「执行失败」）。
+
+源码从 544 行降到 262 行，其中 agent.py 从 250 行降到 116 行，主循环可以一屏读完。这些边界条件的发现过程记录在 git 历史里；精简前的加固版打了 tag `hardened-agent-loop` 留档。

nanopycodeagent-0.5.0/docs/dev_notes/zh-CN/0.5.x.md

@@ -0,0 +1,56 @@
+# 开发笔记 — 0.5.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.5.x.md`](../en/0.5.x.md) 由其生成。
+
+## 0.5.0 - 2026.07.29
+
+### 打印版本号
+工具启动时，如果不打印版本号，有时候自己分辨不出来是哪个版本。先开发一下这个功能。
+
+### 常见 code agent 内置工具
+主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/agent_tools.md)。
+
+### 内置工具设计
+
+可以看出，除了 pi 那样的核心文件/命令工具外，其他 agent 还围绕子代理编排、任务管理、定时调度、用户交互等场景扩展了大量工具。不过对我们的 nano code agent 来说，先从文件操作这一类最基础的工具开始扩展。
+
+#### read 工具
+
+我们对 [read工具](../../research/read_tool.md) 也做了调研，除了 codex 外，其他 code agent 都有专门的 read 工具。pi 和 opencode 是模型无关的，可以看出他们的 read 工具，limit 除了行数，还有文件大小，并没有 token 限制。而其他专用的 code agent，都有 token 限制，大概是只支持自家模型，token 更方便计算？
+
+功能上讲，似乎 read 和 bash 都能实现读文件需求。即使考虑文件大小可能超出限制，bash 也能正常读取。例如 codex，实际测试中发现 codex 读文件的操作，不管读什么大小文件，他都会先来个 `sed -n '1,260p' foo.md`，之后如果发现还有内容，可能会 `wc -l foo.md && sed -n '1,260p' foo.md`,相当于一块一块读，和专用 read 工具的 limit 似乎差不多。但不太确定各个模型，在读文件的时候，是用专用工具好，还是用 `bash` 更好。
+
+另外， read 工具的好处是可以方便地控制 agent 进行只读操作，而 bash 可能在工具层控制起来不那么直接，这样可能就需要在其他层面做控制，例如，沙箱。我在测试 claude code, pi, codex 的程序化方式调用时就发现，claude code 和 pi 只需要设定只使用 read 工具就可以限制只读操作，但 codex 要用沙箱才行(`codex --sandbox read_only`)。
+
+在 OpenAI 2024 年的论文 [SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering
+](https://arxiv.org/abs/2405.15793) 中提到了设计专有工具集比只用 bash 效果要好，但这是 2024 年的工作，现在模型的能力肯定更强了，不知道单纯用 bash 是不是更好（codex 自己读文件就用 bash)。不过，这些我们目前似乎无法验证，可能需要我们的基础工具集完善一点后，才好测试。目前可以先实现类似 pi 的基础工具能力。
+
+对于 read，目前实现的功能有：
+
+**接口**
+
+- **参数**：`path`(必填，绝对或相对路径，支持 `~` 展开)、`offset`(从第几行开始，1 起，默认 1)、`limit`(最多返回多少行，不传就读到行数上限为止，超过上限会被 clamp)。行数上限这个数字直接从常量插值进 schema 描述里，因为 `limit` 是模型能主动控制的参数——让它一次就选对窗口大小，而不是传了个 5000 被静默截到 2000、只能靠事后的截断提示反应过来。字符上限则没写进 `limit` 的描述：模型没有对应的参数可调，知道了也改变不了调用方式，撞上时由运行时的截断提示和错误消息说明更有效。
+- **输出格式**：`cat -n` 风格，每行前面带 1 起的行号(宽度 6 + 制表符)，和 bash 里 `cat -n` 的观感一致，方便模型直接引用行号。
+
+**上限与截断**
+
+- **两道输出上限**：一次调用最多 2000 行、50000 字符，哪个先到按哪个截断，并且**只在行边界截断**，不会把一行切成两半。这样单个文件不会一次性淹没上下文。
+- **续读提示**：窗口没读到文件末尾时，结尾追加 `[showing lines a-b of N; continue with offset=x]`，直接告诉模型总行数和下一次该从哪行接着读，不用再去 `wc -l`。
+
+**文件内容处理**
+
+- **编码**：按 UTF-8 解码，非法字节用替换字符兜底(`errors="replace"`)，和 bash 工具的容忍度保持一致。
+- **行的切分**：只按 `\n` 切，不用 `splitlines()`——后者还会在 `\x0c`、`\x0b`、`\x85`、U+2028 处断行，行号就和 `sed`、`grep -n`、编辑器对不上了；而超长行的错误消息里恰好给了一条 `sed -n 'Np'`，对不上就会切到错误的行。行尾的 `\r` 会去掉，CRLF 文件读起来和 LF 一样。
+- **二进制拒绝**：前 8KB 里出现 `\x00` 就判定为二进制文件并拒绝，避免把乱码塞进上下文。
+
+**错误处理**
+
+- **统一返回**：所有错误路径都返回 `is_error=True`，覆盖 `offset < 1`、`limit < 1`、文件不存在、路径是目录或其他非普通文件、其他 `OSError`、二进制文件、`offset` 超出文件总行数、单行超过字符上限。空文件返回 `(empty file)`。
+- **只打开普通文件**：FIFO 会一直阻塞到有人写入，`/dev/zero` 这类设备文件则永远读不完，而 read 不像 bash 工具那样有超时可以脱身，所以类型检查必须放在读之前。
+- **错误信息带下一步动作**：消息里不只说"哪里错了"，还说"接下来该怎么办"。比如 `offset` 超过文件总行数时会报出文件实际有多少行；某一行长度超过字符上限时，会直接给出一条 bash 命令让模型自己切片(`sed -n 'Np' -- file | cut -c 1-2000`)。这条命令是要交给模型去执行的，所以里面的路径先展开 `~`(引号会挡住 shell 自己的 `~` 展开)，再 `shlex.quote` 转义，并放在 `--` 之后——文件名里的空格、`$(...)` 或开头的 `-` 都不该有机会改变这条命令的形状。
+
+**与 bash 的分工、实现取舍**
+
+- **工具描述里做了分工引导**：告诉模型查看文件优先用 read 而不是 bash 里的 `cat`/`sed`，但搜索(`grep`)和切超长行仍然走 bash。
+- **一次性读入内存**：对源码、配置这类文件足够用，而且输出上限已经限定了真正进入上下文的量，所以没有做流式读取。代价是行数和字符上限都要等整个文件读完才轮得到它们生效，所以读之前还有一道 10 MB 的字节闸门：超过就直接拒绝并让模型改用 bash 切片，免得一个几 GB 的日志把进程撑爆。这个数字比输出上限宽松得多，因为一个小窗口完全可能落在大文件的深处，它只需要挡住"整个文件根本不该被载入"的情况。
+- **调用展示**：agent 侧执行时打印 `[read] <path>`，和 bash 工具的调用展示保持同一种风格。

nanopycodeagent-0.5.0/docs/research/README.md

@@ -0,0 +1,14 @@
+# Research
+
+Notes from surveying how other projects solve a problem, written before
+building the equivalent here. Unlike changelogs and dev notes, these are not
+tied to a release series — each file stands on its own, and the decisions they
+feed into are recorded in [`../dev_notes/`](../dev_notes/).
+
+These notes are **written and maintained in Chinese**; each file says so at the
+top.
+
+- [`agent_tools.md`](agent_tools.md) — the built-in tools of Pi, Claude Code,
+  Codex, OpenCode and Grok Build.
+- [`read_tool.md`](read_tool.md) — how five agent projects read files, and what
+  a dedicated read tool buys over plain bash.

nanopycodeagent-0.5.0/docs/research/agent_tools.md

@@ -0,0 +1,154 @@
+# 常见 Code Agent 内置工具
+
+> 本文明确指定使用中文编写和维护。
+
+目前 nanoPyCodeAgent 只有 Bash 工具，但主流 Code Agent 通常还会提供其他内置工具。本文调研 Pi、Claude Code、Codex、OpenCode 和 Grok Build 的工具设计。
+
+## Pi
+
+Pi 的核心工具比较少。[Pi Quick Start](https://pi.dev/docs/latest/quickstart#first-session)介绍了四个核心工具：
+
+- `read`：读文件
+- `write`：创建或覆盖文件
+- `edit`：编辑文件
+- `bash`：运行 Shell 命令
+
+除此之外，还有三个可选扩展工具：`grep`、`find`、`ls`。
+
+## Claude Code
+
+Claude Code 提供的工具更多。[Claude Code 工具参考](https://code.claude.com/docs/en/tools-reference)介绍了以下主要工具。
+
+### 文件操作
+
+- `Read`：读取文件内容，支持文本、图片、PDF、Jupyter Notebook
+- `Write`：创建或整体覆盖文件
+- `Edit`：对文件做精确字符串替换式的局部修改
+- `NotebookEdit`：按 cell 修改 Jupyter Notebook
+
+### 搜索与代码智能
+
+- `Glob`：按文件名模式查找文件
+- `Grep`：按内容模式搜索文件，基于 ripgrep
+- `LSP`：通过语言服务器提供代码智能，例如跳转定义、查找引用、报告类型错误
+
+### 命令执行
+
+- `Bash`：在环境中执行 Shell 命令
+- `PowerShell`：原生执行 PowerShell 命令，主要面向 Windows
+- `Monitor`：在后台运行命令并逐行回传输出，用于监控日志、轮询状态、订阅 WebSocket 事件
+
+### Web 访问
+
+- `WebFetch`：抓取 URL 内容，转换成 Markdown 后用小模型按 prompt 提取信息
+- `WebSearch`：执行网络搜索，返回结果标题和链接
+
+### 子代理与编排
+
+- `Agent`：派生一个拥有独立上下文窗口的子代理去完成任务
+- `SendMessage`：给 Agent Team 队友发消息，或按 ID 恢复某个子代理
+- `Workflow`：运行动态工作流脚本，在后台编排多个子代理并返回汇总结果
+- `Skill`：在主对话中执行一个 Skill，即可复用的提示词工作流
+
+### 任务管理
+
+- `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`：创建、查询、列出、更新任务列表
+- `TaskOutput`：获取后台任务输出；已不推荐，改用 `Read` 读取输出文件
+- `TaskStop`：按 ID 停止后台任务
+- `TodoWrite`：管理会话任务清单；默认已禁用，被 `Task*` 系列取代
+
+### 计划与工作区
+
+- `EnterPlanMode`、`ExitPlanMode`：进入计划模式设计方案，提交计划供批准并退出
+- `EnterWorktree`、`ExitWorktree`：创建并切入隔离的 Git worktree，退出后返回原目录
+
+### 定时与调度
+
+- `CronCreate`、`CronDelete`、`CronList`：在当前会话内创建、取消、列出定时任务
+- `ScheduleWakeup`：为自适应节奏的 `/loop` 安排下一次迭代时间
+- `RemoteTrigger`：创建和管理 claude.ai 上的 Routines，即云端定时代理
+
+### 用户交互与输出
+
+- `AskUserQuestion`：向用户提多选题以澄清需求
+- `Artifact`：把 HTML 或 Markdown 文件发布为 claude.ai 上的 Artifact 页面
+- `PushNotification`：发送桌面或手机推送通知
+- `SendUserFile`：把会话中的报告、截图等文件直接发送到用户设备
+- `ReportFindings`：以结构化列表上报 Code Review 发现的问题
+- `ShareOnboardingGuide`：上传 `ONBOARDING.md` 并生成团队分享链接
+
+### MCP 相关
+
+- `ListMcpResourcesTool`、`ReadMcpResourceTool`：列出、读取 MCP Server 暴露的资源
+- `ToolSearch`：按需搜索并加载延迟加载的工具，需要开启 Tool Search
+- `WaitForMcpServers`：等待仍在后台连接中的 MCP Server 就绪
+
+## Codex
+
+Codex 与 Pi 和 Claude Code 不太一样，没有单独的 `Read`、`Glob`、`Grep`；读取和搜索由 `exec_command` 调用 `rg`、`sed` 等命令完成。除[官方工具文档](https://developers.openai.com/api/docs/guides/tools)外，本文也参考了开源的 [Codex](https://github.com/openai/codex) 源码。
+
+标准本地 Coding Turn 常见的工具有：
+
+- `exec_command`：执行 Shell 命令
+- `write_stdin`：向长时间运行的命令继续输入或轮询
+- `apply_patch`：用结构化 Patch 修改文件
+- `update_plan`：更新任务计划
+- `view_image`：查看本地图片
+- `web_search`，或新式命名空间下的 `web.run`：搜索网页
+
+条件性工具还包括：
+
+- 交互：`request_user_input`
+- MCP 资源：`list_mcp_resources`、`list_mcp_resource_templates`、`read_mcp_resource`
+- 权限：`request_permissions`
+- 多代理：`spawn_agent`、`send_message`、`followup_task`、`wait_agent`、`interrupt_agent`、`list_agents`
+- 搜索工具发现：`tool_search`
+- 图片生成：`image_gen.imagegen`
+- MCP、Apps、插件注入的动态工具
+
+## OpenCode
+
+[OpenCode](https://github.com/anomalyco/opencode) v1.18.3 的内置工具有：
+
+### 文件与执行
+
+- `bash`：执行 Shell 命令
+- `read`：读取文本、图片或列出目录内容
+- `write`：创建或覆盖文件
+- `edit`：精确字符串替换
+- `apply_patch`：用 Patch 批量新增、修改、删除文件
+- `glob`：按文件名模式查找文件
+- `grep`：用正则搜索文件内容
+
+### Web 访问
+
+- `webfetch`：获取指定 URL 内容
+- `websearch`：搜索互联网
+
+### 用户交互
+
+- `question`：在执行过程中向用户提问
+
+### 技能与任务管理
+
+- `skill`：加载 `SKILL.md`
+- `todowrite`：创建和更新任务列表
+
+## Grok Build
+
+刚开源的 [Grok Build](https://github.com/xai-org/grok-build) 内置工具有：
+
+- 文件与执行：`run_terminal_command`、`read_file`、`search_replace`、`write`、`list_dir`、`grep`、`lsp`
+- 后台任务与子代理：`spawn_subagent`、`get_command_or_subagent_output`、`wait_commands_or_subagents`、`kill_command_or_subagent`、`monitor`
+- 任务管理：`todo_write`、`update_goal`
+- 定时任务：`scheduler_create`、`scheduler_delete`、`scheduler_list`
+- Plan 模式：`enter_plan_mode`、`exit_plan_mode`、`ask_user_question`
+- Web：`web_search`、`web_fetch`
+- MCP 元工具：`search_tool`、`use_tool`
+- Memory：`memory_search`、`memory_get`
+- 媒体：`image_gen`、`image_to_video`、`reference_to_video`
+
+运行时还可能动态加入：
+
+- `image_edit`
+- 服务端 `x_search`