折腾有记

Coding Agent 原理与实践：
Ink 开发手记

Ink 是我（折腾客，GitHub：FishInSalt）开发的开源终端 AI 助手，npm 包名为 ink-agent。我参考 pi，从零实现自己的 Agent Harness： 连接模型调用、工具执行、上下文与会话，让模型能在项目中完成编程任务。

这个系列聚焦代码场景，结合 Ink 源码、带注释的代码与图解，解释各个模块为什么需要、怎样工作，以及实现时的工程取舍。

系列文章 已发布 19 篇，按章节顺序阅读

  1. Coding Agent 原理与实践 00：为什么开发 Ink

    更新于:

    为什么参考 pi 从零开发 Ink？从一个改代码的任务出发，看看 Coding Agent 需要哪些模块，以及这个系列会怎样介绍它们。

  2. Coding Agent 原理与实践 01：最小 Agent 与执行循环

    更新于:

    从“读取 README，告诉我项目怎样启动”开始，结合带注释的源码节选和逐步演示，理解 Agent Loop 怎样调用模型、执行工具、传回结果，以及处理错误和中断。

  3. Coding Agent 原理与实践 02（上）：模型接入：请求与消息转换

    更新于:

    接着读取 README 的任务，看看 Agent 循环里的消息和工具定义，怎样转换成模型服务接收的请求，以及工具结果怎样在下一次调用中传回去。

  4. Coding Agent 原理与实践 02（下）：模型接入：流式响应与组装

    更新于:

    从一次读取 README 的工具请求出发，逐步观察流式参数怎样拼接、完整回复何时交回循环，以及中断、截断和参数解析失败怎样处理。

  5. Coding Agent 原理与实践 03：工具系统：定义、调用与反馈

    更新于:

    从给 Agent 增加一种能力出发，解释工具怎样定义、注册、校验和执行，怎样统一返回结果，以及取消与并发调度需要约定什么。

  6. Coding Agent 原理与实践 04：上下文管理：信息组织与历史压缩

    更新于:

    用修复求和函数的任务，解释每次模型调用需要哪些信息、上下文预算怎样估算，以及历史太长时怎样压缩并继续工作。

  7. Coding Agent 原理与实践 05：会话与持久化：保存记录，恢复任务

    更新于:

    从关闭终端后继续修复代码的任务出发，解释 Agent 怎样保存消息、恢复压缩后的历史，以及处理中途退出留下的不完整记录。

  8. Coding Agent 原理与实践 06：交互与运行控制

    更新于:

    从查看进展、提前安排任务、执行中纠偏和中断四种交互出发，解释 Agent 的事件反馈、输入队列、取消机制，以及中断或失败后的恢复。

  9. Coding Agent 原理与实践 07：终端界面——回答与状态怎样实时刷新

    更新于:

    从模型文字、工具状态、子代理进展和等待动画出发，解释终端控制序列、显示状态、组件与差异重绘怎样配合，让 Coding Agent 在终端中持续更新界面。

  10. Coding Agent 原理与实践 08：权限与信任——怎样控制 Agent 的执行风险

    更新于:

    从项目资源加载和工具操作两类风险出发，解释 Ink 内置的项目信任检查，以及 Guardian 扩展怎样利用执行前钩子和用户确认接口控制工具操作，再讨论当前方案的局限。

  11. Coding Agent 原理与实践 09：扩展机制——怎样增加能力与自定义行为

    更新于:

    从运行结束提醒、网页搜索工具和任务计时器出发，解释扩展怎样被加载、注册并接入 Agent，再以 pi 为例，讨论会话状态、界面和生命周期为何也是扩展机制的一部分。

  12. Coding Agent 原理与实践 10（上）：子代理——怎样委派任务并回收结果

    更新于:

    从调查登录逻辑的任务出发，解释主 Agent 怎样通过 task 工具启动独立的 Agent 循环，准备子代理的上下文与工具，再把结果带回主对话。

  13. Coding Agent 原理与实践 10（中）：并发协作——怎样协调多个子代理

    更新于:

    从两个子代理同时调查代码出发，解释并发任务怎样启动、等待并交回结果，以及共享目录、文件锁和 Git worktree 分别解决什么问题。

  14. Coding Agent 原理与实践 10（下）：子代理续跑——怎样恢复历史并继续执行？

    从继续调查登录测试的任务出发，解释子代理怎样核对启动记录与运行条件、取得单写者租约、修复中断留下的历史，再带着新要求开始下一次运行。

  15. Coding Agent 原理与实践 11：Skills——Agent 怎样使用任务相关的“技能”？

    以生成 Git 提交信息为例，解释 Ink 怎样准备可用 Skill 清单、将清单提供给模型、按需读取正文与参考资料，以及用户指定 Skill 时怎样将正文加入上下文。

  16. Coding Agent 原理与实践 12：MCP——外部工具接入的统一协议

    解释 MCP 是什么，以及统一协议怎样减少外部工具接入中的重复适配；再以查询天气为例，追踪 Ink 中的服务连接、工具发现、调用和失败处理。

  17. Coding Agent 原理与实践 13：图片输入——怎样把图片交给模型

    从界面开发中对视觉信息的需求出发，解释 Coding Agent 怎样把本地图片带入模型上下文，再沿着截图的读取、处理、请求转换和历史保存，分析 Ink 的实现与限制。

  18. Coding Agent 原理与实践 14：用量统计——Token 消耗与成本估算

    沿一次模型调用的用量报告，解释 Ink 怎样统一并保存计数、汇总主 Agent 与子代理和摘要的消耗，再按产生用量的模型估算会话成本，并说明界面数字的统计范围与限制。

  19. Coding Agent 原理与实践 15：模型管理——多家大模型提供商的配置与切换

    沿着登录、选择和使用模型的过程，解释 Ink 怎样分别保存多家大模型提供商的凭据、汇集候选模型、应用切换和适配能力差异，以及怎样保留模型选择。