如何运行 learn-claude-code 的 s15 集成运行时并验证 25 个内置工具在一个循环上协作

如何运行 learn-claude-code 的 s15 集成运行时并验证 25 个内置工具在一个循环上协作

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code

learn-claude-code 的s15_integrated_harness/章节提供一个集成运行时：把工具分发、权限、hooks、todo、任务图、子代理、技能、记忆、上下文压缩、后台任务、cron 调度、多代理团队、任务绑定的 worktree 和 MCP 插件全部挂到同一个while True循环上。它的内置工具池共 25 个工具，本文的目标是：在本机把s15_integrated_harness/code.py跑起来，并用章节 README 给出的提示词逐项验证这些工具确实在同一个循环上被调用、被权限检查拦截、被 hooks 观察。

前提：Python 环境、一份 Anthropic API Key（或兼容端点）、一个本地 learn-claude-code 仓库副本。s15 会在工作目录内真实执行 shell 命令和文件读写，并写出.tasks/、.memory/、.transcripts/、.task_outputs/等运行状态目录，建议在自己的仓库副本里运行。

准备依赖与环境变量

s15 的入口文件 code.py 头部注明：Need: pip install anthropic python-dotenv pyyaml + .env with ANTHROPIC_API_KEY。仓库的 requirements.txt 固定了依赖版本下限：

anthropic>=0.25.0 python-dotenv>=1.0.0 pyyaml>=6.0

在仓库根目录执行：

pip install -r requirements.txt cp .env.example .env

然后编辑.env。.env.example 中的必填项是ANTHROPIC_API_KEY和MODEL_ID——代码里MODEL = os.environ["MODEL_ID"]直接取环境变量，缺了MODEL_ID进程启动即失败。示例文件给出的默认值是MODEL_ID=claude-sonnet-4-6。ANTHROPIC_BASE_URL可选，用于指向 Anthropic 兼容供应商；.env.example里列出了 MiniMax、GLM、Kimi、DeepSeek 等兼容端点的MODEL_ID与Base URL对照，可按需替换。FALLBACK_MODEL_ID未出现在.env.example中，但代码会读取它：连续 529 错误达到阈值后可切换到该模型，属于可选项。

另外注意：s15 启动时会通过 importlib 加载 s09_memory/code.py 作为记忆运行时，因此必须保留完整仓库结构、在仓库根目录启动，而不是把s15_integrated_harness/单独拷出去。

启动 s15 运行时

python s15_integrated_harness/code.py

启动成功后终端显示（文档中的启动文案）：

s15: integrated harness Enter a question, press Enter to send. Type q to quit.

之后出现s15 >>提示符，输入一行自然语言回车即发送，输入q、exit或空行退出。运行时以当前工作目录为WORKDIR：文件类工具在WORKDIR之外会被拒绝，bash 命令也会在当前目录下真实执行。

进入交互后，每轮循环的流程见 s15 README：

user input → UserPromptSubmit hooks → cron/background notification injection → context compact → memory + skills + MCP state assemble the system prompt → LLM → has tool_use block? no → Stop hooks → return yes → PreToolUse hooks + permission → TOOL_HANDLERS / MCP handlers / background dispatch → PostToolUse hooks → tool_result / task_notification back to messages → next round

也就是说，是否继续执行工具完全由模型响应里有没有tool_useblock 决定，每个tool_use对应一个tool_result后进入下一轮模型调用。

25 个内置工具在哪里

s15 README 明确列出内置工具池包含 25 个工具，按功能分组的原文清单是：

bash, read_file, write_file, edit_file, glob todo_write, task, load_skill, compact create_task, list_tasks, get_task, claim_task, complete_task schedule_cron, list_crons, cancel_cron spawn_teammate, list_teammates, send_message request_shutdown, request_plan, review_plan create_worktree connect_mcp

assemble_tool_pool()每一轮重新组装一次工具池：BUILTIN_TOOLS加上已连接 MCP server 的动态工具（命名形如mcp__docs__search）。connect_mcp("docs")之后，下一轮模型就能看到 MCP 工具。README 给出的 s14 → s15 对比表也把内置工具数从 6 提升到 25，外部工具走同一条动态 MCP 路径和宿主策略。

执行BUILTIN_TOOLS与BUILTIN_HANDLERS的定义见 code.py 中BUILTIN_TOOLS = [及紧随其后的 handler 映射，可对照上文清单逐个核对 25 个条目一一对应。

主验证路径：用 README 的 5 条提示词跑通协作

s15 README 的 "Try It" 一节给出了 5 条现成提示词和一份 "Watch for" 检查清单。按顺序输入即可覆盖文件工具、MCP、后台、cron、团队/计划/工作树这几类机制：

1. Inspect this repository and tell me which Python files matter most.
2. Search the connected documentation for agent loop guidance.
3. Refactor the authentication module and login page in parallel in separate worktrees. Show me each plan before editing.
4. Remind me about the meeting in 3 minutes.
5. Install the dependencies in the background while you read README.md.

运行期间每次工具调用，终端会打印青色> 工具名（来自 code.py 中print(f"\033[36m> {block.name}\033[0m")），并打印该工具输出（截断到 300 字符）。据此可判断 25 个工具是否真的在同一个循环里被调度。对照 README 的 "Watch for" 清单逐项确认：

• hooks 与权限：每次工具调用都应经过PreToolUsehooks（权限就是一个PreToolUsehook），允许执行后再走 handler 和PostToolUse。具体策略：文件工具拒绝WORKDIR之外的路径；每条 bash 命令执行前都会询问；MCP 工具中只有宿主 allowlist 内的只读调用直接放行，其余都会向用户征求批准。只有前台用户轮可以弹交互式批准，异步轮遇到批准需求会直接 fail closed。
• MCP 动态工具：第 2 条提示词会触发connect_mcp，随后应观察到mcp__docs__*工具在下一轮出现并被调用。
• 后台任务：第 5 条提示词中，带run_in_background=true的 bash 调用应立即返回占位结果[Background task {bg_id} started] Result will arrive as a task_notification.，不阻塞主循环；命令完成后以task_notification形式注入下一轮。只有显式标记后台的 bash 才走这条路径，非零退出会产生failed通知。
• cron：第 4 条提示词调度提醒后，到点会看到[cron inject]标记并自动触发一轮代理动作；durable 一次性任务是 at-least-once 投递（模型调用失败会恢复回队列，重启后会重新入队）。
• 团队与计划：第 3 条提示词涉及spawn_teammate并行工作。确认点是：teammate 先提交计划、在批准前暂停；idle 的 teammate 一次最多原子认领一个 ready 任务；teammate 的文件工具切换到所认领任务的cwd，且任务完成前该cwd保持到该轮结束、IDLE 时释放。注意create_worktree在创建前会校验任务、名称、路径、分支和 Git registry，worktree 只隔离工作副本、不是沙箱。
• 权限边界行为：可以主动试一条越界操作（例如让代理读WORKDIR外的文件），预期是权限层直接拒绝并返回拒绝原因，而不是执行失败。

如果模型触发max_tokens上限，code.py 会先打印[max_tokens] retry with 16000（把 max_tokens 从 8000 升到 16000 重试），之后仍截断则注入续写 prompt；prompt 过长则做 reactive compact 后重试——这些输出本身也可以作为"恢复机制与工具循环在同一循环里协作"的佐证。

已知边界与限制

• 交互式批准只在前台用户轮可用；cron/团队事件触发的异步轮遇到需要批准的工具调用会 fail closed，而不是抢 stdin。
• worktree 分离的是工作目录，不是进程沙箱：启动新会话的进程会逃出进程组清理，这也是删除 worktree 仍由宿主侧remove_worktree()负责、模型无法直接调用的原因。
• s15 会真实执行你批准的任何 bash 命令，并可能修改WORKDIR内文件；运行状态写在当前目录的.tasks/、.memory/、.transcripts/、.task_outputs/下，介意仓库变脏的话在仓库副本里跑。
• MODEL_ID是硬性要求；FALLBACK_MODEL_ID与ANTHROPIC_BASE_URL按所选供应商选填。

跑完以上提示词后，用q退出。下一章 s16 Workflow Runtime 在这个宿主上增加Workflow工具，用于把固定编排路径写进代码并记录进度以支持恢复。

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code