02
DECIDE AND EXECUTE · agent/loop.py
边界确认后，
再让任务一步步往前走。
模型可以选择读文件、搜索、编辑或执行命令。每一次工具结果都会回到当前任务的上下文，Agent 再根据新证据决定下一步，而不是一次生成后就“装作完成”。
LOCAL PYTHON CODING AGENT
写代码之外，
把 Agent 怎么工作
也看明白。
FirstCoder 是一个真实可运行的本地 Coding Agent：它会调用工具、确认权限、保存会话、管理长上下文；这些都不是黑箱。
终端安装
pipx install firstcoder
BUILT TO BE UNDERSTOOD
不是把 Agent
包装得更神秘。
大多数演示只展示「输入一句话，代码就改好了」。FirstCoder 选择把中间过程摊开：请求从哪里来，工具为什么能执行，风险操作何时暂停，长任务又如何继续。
它的取舍也很明确：不追求成为功能最杂的大平台，而是留下一条完整、可读、可修改的 Python 执行链路。
沿着运行过程往下看 →17k约 1.7 万行 Python
运行时代码
运行时代码
1条完整的
Model → Tool → Model 循环
Model → Tool → Model 循环
0不透明的「帮你办了」
执行黑箱
执行黑箱
ONE REQUEST, END TO END
一条任务，
从哪开始，往哪结束？
FirstCoder 不把 Agent 讲成一组散落功能。它先确认你正在做哪件事，再让模型调用工具；风险处暂停，长任务留下可恢复的记录。
01 / KNOW THE TASK · context/task_boundary.py
先确认你在做哪件事，
再开始调用工具。
每个 user turn 都不是一团模糊历史。FirstCoder 会为当前任务建立可追踪的边界，后续消息、工具结果和上下文操作都归到同一条任务线上。
01user message新的用户请求进入 session
↓
02task_boundary程序生成稳定 task hash
↓
03task scoped context消息和工具结果带上边界
↓
04compact if needed切换任务时按策略整理上下文
不是提示词约定
任务 hash 由程序侧生成；模型只对真实 user message 做判断，不能自己编一个边界。
首次请求先定边界
支持强制 tool choice 的 Provider，会在用户新一轮任务的第一次请求先调用 task_boundary，再恢复自动工具选择。
可恢复、可复盘
task_boundary_observed 会进入 session 事件流；重新打开会话后，活动任务和稳定窗口都能重放。
边界确认后，
03
PAUSE AT RISK · permissions/
需要冒险时，
任务会停下来等你。
写文件、运行 shell、访问网络等动作先经过工具声明、注册表预检与策略判断。若结果是 ask，Loop 保存原始调用、暂停后续执行，等确认再按 request id 恢复。
04
KEEP THE SIGNAL · context/
任务变长，
也只带上现在需要的内容。
稳定系统前缀、会话历史和工具输出会按需投影。旧任务切换或窗口接近阈值时，FirstCoder 可以压缩历史，把大输出归档在本地，需要时再有界读取。
WHAT COMPACTION KEEPS
压缩不是删掉历史，
而是把上下文重新分层。
每次模型请求都重新组合稳定前缀与当前任务需要的投影。信息量大的工具结果不会一直挤在消息窗口里：它们先归档，提示词只保留可判断下一步的摘要与引用。
留在当前请求稳定系统前缀当前任务消息工具结果预览
窗口接近阈值 / 确认任务切换 ↓
下沉到本地 archive完整命令输出旧任务细节长文本原文
retrieve_archive需要证据时，按 archive id 读取有界片段，而不是把全部历史再塞回来。1. 保留每次请求都要用的系统前缀2. 压缩的是历史投影，不是 session 事件本身3. archive 只允许当前 session 有界读取
PAUSE
需要确认就暂停
ask 不只是 UI 弹窗。Loop 保存原始调用，确认之后从 request id 恢复。
ARCHIVE
大结果需要时再取
工具结果可以归档，只投影预览；需要细节时再用 retrieve_archive 读取有界片段。
GUARD
每轮都有明确终点
任务会完成、等待确认，或触发保护上限；不会无限转圈，主打一个“到点下班”。
05 / CONTINUE LATER · session/
离开终端，
任务也能从原处继续。
每个项目的消息、工具调用、授权和结果都会追加为本地事件流。你可以恢复最近会话、选择旧会话、改名或分叉新思路；压缩之后，仍能重建可读记录。
messagetool callapprovalresult
THE TOOLS IN THE MIDDLE
任务真正向前走时，
中间到底能做什么？
不是一堆临时脚本。每个工具都有 schema、权限需求和执行结果，模型可以调用，用户也能追踪。
01
阅读与定位
lsviewgrepglobtreeread_multi
02
代码与 Git
git_statusgit_diffgit_logdiagnosticsthink
03
修改与执行
writeeditdeleteapply_patchshellpython_exec
04
网络与协作
fetchweb_searchask_usertodo
05
会话级能力
task_boundaryretrieve_archive
WHY THIS STAYS READABLE
每个阶段，
都有一个能找到的模块。
上下文、工具、权限、Provider 与会话各自处理自己的职责。FirstCoder 的价值不在于让你相信它，而在于你可以从一次请求顺着模块读到具体实现。
agent/编排执行循环tools/运行本地工具permissions/管理策略与授权context/维护长对话上下文
terminal
$ pipx install firstcoder
$ firstcoder
# 单条任务
$ firstcoder --message "Summarize this repository"
# 交互模式
$ firstcoder --interactiveFAQ
先把边界，
说在前面。
FirstCoder 更适合谁？+
适合想理解 coding agent 运行机制、希望二次开发本地 Python 实现，或需要一个能讲清楚架构的作品集项目的人。它也能用于日常任务，但优先级是「真实且可读」。
它和“一次生成代码”的聊天助手有什么不同？+
FirstCoder 维护的是完整的 model → tool → evidence → model 循环。模型可以读取仓库、修改文件、执行命令，再根据新的工具结果继续判断；任务会在完成、等待确认或触发保护条件时结束。
权限确认真的会阻止操作吗？+
会。权限由工具注册表、权限管理器与默认策略在程序侧执行。当策略返回 ask，Agent Loop 会保存原始调用并暂停，后续工具不会抢跑；确认后才用对应 request id 恢复。
为什么每轮都会先判断 task boundary？+
因为新问题不应该被旧任务的上下文污染。task_boundary 只让模型报告 same / new / uncertain，稳定 task hash 由程序生成，并随 session 事件保存。支持强制 tool choice 的 Provider 会在真实 user turn 的首次请求先走这一步。
上下文变长后，是不是会丢掉之前的内容？+
不是直接丢。稳定系统前缀和当前任务需要的历史会继续投影；大工具输出和较旧细节可以归档，提示词里保留摘要与引用。需要原始证据时，retrieve_archive 只能从当前 session 读取有界片段，而不是一次塞回全部历史。
关闭终端以后，怎么继续上一次工作？+
会话以事件流保存消息、工具调用、授权和结果。使用 /resume 选择已有会话即可继续；也可以用 /fork 从当前会话复制一条新分支，或用 /rename 整理会话标题。
模型和密钥怎么配置？+
模型配置可放在全局 ~/.config/firstcoder/config.toml 或项目级 ./firstcoder.toml；密钥通过如 FIRSTCODER_API_KEY 的环境变量提供，不需要写进项目代码。
能接自己的模型、Skill 或 MCP 吗？+
可以。Provider Adapter 负责把不同模型协议收敛到运行时；项目与全局 Skill 可被发现、加载并写入审计事件；stdio MCP 与外部能力通过统一工具协议接入。具体可用性取决于当前 Provider 配置和已安装服务。
本地数据与工具访问范围怎么控制？+
默认策略会按工具和路径请求权限，标准模式限制在项目范围内；会话、归档和配置都由本地工作流管理。切换到更宽松模式会改变访问范围，因此应只在你明确理解影响时使用。
写代码，也把代码背后的
Agent 看明白。