Skip to content
mothierasPublic

About

An embeddable, local-first coding agent engine — small trusted core, MCP, subagents, observable execution, and reports.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

coil-core

CI License: MIT

可嵌入的本地优先 coding agent 引擎,提供模型与工具循环、MCP、并发子代理、运行取消、会话持久化与报告。核心位于 src/core/,不依赖 UI;仓库附带的 Ink/React TUI 是它的一个客户端。

快速开始

需要 Node.js 22.19 或更高版本,以及 pnpm 11.0.9。在仓库目录执行:

pnpm install
pnpm build
pnpm exec tsx examples/headless-agent.ts --scripted hello
pnpm exec tsx examples/custom-tool.ts
pnpm exec tsx examples/cancel-run.ts
pnpm exec tsx examples/recover-session.ts

这些示例通过包的公共导出消费构建产物,使用临时 workspace,无需模型配置或凭据:

示例 预期结果
headless-agent --scripted hello 输出 本地演示已收到:hello
custom-tool 有效输入返回 completed,无效输入返回 invalid_input 且不执行 handler
cancel-run 启动真实进程后取消,输出 interrupted、aborted、confirmed,检查进程已退出
recover-session 在文件副作用发生、结果保存前终止真实进程;恢复后先阻止继续执行,核实文件并保存决定后才接受新消息,检查副作用只发生一次

运行 pnpm dev 启动 TUI。输入 /login 选择服务商、登录方式和模型,也可以用 /login <provider> 直接进入指定服务商的登录流程。可用的登录方式由 pi-ai 提供,包括 API Key 和浏览器授权。输入密钥时会遮罩字符,按 Esc 可取消。

保存后即可在当前会话使用新模型。输入 /ping 可发出测试请求。配置按工作目录保存在 ~/.coil/state/auth/,文件权限为 0600。在同一工作目录重启 TUI 时,优先使用已保存的登录配置。

也可以通过环境变量配置模型,供未保存登录配置的 TUI、headless 示例或嵌入式宿主使用:

cp .env.example .env
# 在 .env 中填写模型 ID 和对应 provider 的凭据
pnpm dev

环境变量方式默认使用 Anthropic。设置 COIL_LLM_PROVIDER 可选择已安装 pi-ai 的其他内置 provider,同时配置该 provider 的凭据和目录中的 MODEL_ID。使用 Anthropic 兼容网关时保留 COIL_LLM_PROVIDER=anthropic,设置 ANTHROPIC_BASE_URL、网关密钥和模型 ID。配置示例见 .env.example。

嵌入应用

SessionController 管理会话、运行、异步结果和保存,适合需要取消或恢复能力的宿主。先构建,再通过包的公共导出使用:

pnpm build
import { SessionController } from "coil-core";

const controller = await SessionController.createNew({
  workspaceRoot: process.cwd(),
});

try {
  const turn = await controller.handleUserMessage("说明这个项目的入口和主要模块");
  console.log(turn.assistantMessage.content);

  while (controller.hasPendingAsyncWork()) {
    await controller.waitForAsyncWork();
    const wake = await controller.handleAutoWake("async_work_finished");
    if (wake) console.log(wake.assistantMessage.content);
  }
} finally {
  await controller.close();
}

示例使用 .env 中的模型配置。宿主也可注入 provider 和 checkPermission。headless 宿主负责调用 handleAutoWake(),TUI 已接入这一流程;core 合并并发唤醒请求,避免主代理重入。没有可交付结果或请求失效时,该方法返回 undefined。hasPendingAsyncWork() 同时包含活动工作和已完成但未消费的结果。

只需要模型与工具循环时,可直接使用 Agent 和 agentLoop,参见 headless 示例;去掉 --scripted 即使用真实模型。此入口的持久化与资源管理由宿主负责;需要按运行 ID 取消时,使用 app.agentRuntime.run() 和 cancelRun(),参见取消示例。

导入 coil-core 不会校验模型配置;注入 provider 可完全绕过默认模型配置。创建默认 provider 时才检查 MODEL_ID(兼容旧名 ANTHROPIC_MODEL),请求时由 pi-ai 检查凭据。

扩展工具与模型

  • 用 builtinTool() 定义自定义工具,经 app.toolRuntime.registerTool() 注册。参数由 JSON Schema 校验;handler 返回 { status, output } 形式的 ToolExecutionResult,不再返回字符串。参见 自定义工具示例。
  • TUI 从 .coil/config/mcp.json 加载 stdio MCP server,工具以 mcp__server__tool 命名。headless 宿主可调用 loadConfiguredMcpTools(),将结果传入 controller 的 toolProviderResults。
  • 注入实现 Provider 接口的对象即可替换模型后端。pi-ai 适配位于 src/core/providers/。

取消与关闭

SessionController.cancelRun(id?) 取消指定运行及其活动后代,省略 ID 时选择最近的主运行。父运行正常结束后,已启动的子代理和后台工作可以继续;close() 则停止整个会话所属的工作、关闭连接并保存。重复关闭复用同一个 Promise,清理或保存失败会返回错误。

waitForAsyncWork({ shouldStop }) 允许宿主只停止等待,不取消任务。有结果可交付时,等待即可结束,无需等待其余工作全部完成。取消或关闭会抑制相关唤醒,保留的结果仍可通过 controller.appContext.inbox.getResults() 检查。

TUI 操作:

操作 按键
发送消息 Enter
选择斜杠命令 输入 / 后用 ↑↓ 选择,Tab 补全,Enter 执行
浏览输入历史 ↑↓,返回末尾恢复草稿
滚动对话历史 鼠标滚轮或触控板上下滑动,也可拖动右侧滚动条
滚动较长的输入或权限预览 将指针移到对应区域后滚动
回到最新消息 点击 ↓ Latest,或向下滚到底部
加速滚动 按住 Alt 滚动,每个滚轮事件移动五行
键盘滚动(备用) PageUp / PageDown;Alt+PageUp / Alt+PageDown 滚动输入区
取消当前响应或工具执行 Esc 或 Ctrl+C
取消运行及其异步工作 Ctrl+C
只停止等待异步结果 异步等待时按 Esc
清空输入草稿 空闲时 Ctrl+C
关闭会话 /quit、Ctrl+D,或空闲且输入为空时按 Ctrl+C
确认权限 ↑↓ 选择后按 Enter;也可用 y 允许一次、n / Esc 拒绝

TUI 使用独立的终端屏幕,顶部显示 ⊙ coil 和工作目录,输入区固定在底部,对话在页面内滚动。退出后恢复进入前的终端内容。配色参考 pi 的默认主题,使用紫色强调和蓝灰色边界;ASCII 模式下图标显示为 (o)。

运行时可以编辑下一条消息的草稿,当前运行结束后按 Enter 发送;草稿不会自动排队或提交。多行粘贴保留换行,按 Enter 后才发送。向上翻阅历史时,新消息不会抢走阅读位置;翻到底部或点击 ↓ Latest 后恢复自动跟随。滚动优先作用于指针所在区域,该区域滚到边界后的剩余滚动量传递给对话。详细会话信息使用 /status 查看。

取消不会回滚已经发生的副作用。无法确认进程或远端操作停止时,cleanup.status 为 unconfirmed,宿主不能将其视为已停止。单个 MCP 请求取消不会关闭其他调用共享的连接。进程清理已在 macOS arm64 / Node 24 和 Linux CI / Node 22 中验证,范围限于引擎创建且留在受管进程组内的 shell 与后代;脱离进程组的进程、远端操作和 Windows 进程树清理不在已验证范围内。工具权限规则不提供操作系统沙箱隔离。

保存与恢复

TUI 中用 /resume 列出会话,使用 /resume <序号或 ID> 打开。headless 宿主使用 SessionController.resume({ workspaceRoot, sessionId })。运行状态、消息和报告保存在 workspace 的 .coil/state/ 下,不应提交到版本库。

恢复使用最后一个可信检查点。已保存但未交付的异步结果可继续消费,已确认加入主消息的结果不会重复应用。如果工具或异步工作可能已执行但没有可靠结果,恢复会阻止继续执行和自动唤醒;用 /recover 查看,再用 /recover verify <id> 记录核实,或用 /recover discard <id> 放弃追查。headless 宿主从 getSnapshot().recovery 读取待处理项,通过 resolveRecovery(id, "verified" | "discarded") 记录决定。需要重做时,在新消息中明确请求,并重新经过权限流程。

resolveRecovery() 只保存核实或放弃的决定,不会自动继续执行,也不会将历史未知结果改为成功。恢复演示会读取已知的本地标记文件完成核实;真实宿主需检查相应文件或外部系统后再记录决定。

检查点写入失败后,当前 controller 停止继续执行;flush() 可重试保留的写入,随后重新打开会话核对结果。events.jsonl 的可信检查点及其引用的私有上下文槽位是恢复依据,snapshot.json 和 lead-messages.json 是派生视图。旧版 pi-ai 和 Anthropic 会话仍可恢复对话,但缺少执行证据时无法提供同等恢复保证。

恢复保证面向本地文件系统上的单进程会话和进程异常退出,不承诺跨崩溃的模型调用或自动唤醒恰好执行一次。

迁移已有嵌入代码

  • 自定义工具 handler 从字符串返回值改为 ToolExecutionResult,例如 { status: "completed", output: "done" };可供模型修正的失败使用对应状态,存储和运行时故障继续抛出。
  • 直接调用 agentLoop() 时可传 signal;需要运行记录、按 ID 取消及所属工作的收尾时改用 AgentRuntime。createAppContext() 消费者在退出时应关闭 app.agentRuntime 和工具 providers。
  • handleAutoWake() 的结果现在可能为 undefined;等待异步工作时同时考虑活动工作与待交付结果,参照上面的嵌入示例。
  • 需要保存与恢复保证时通过 SessionController 执行和 flush();不要向新版 events.jsonl 直接追加无检查点事件。恢复未决项后,用 resolveRecovery() 保存决定,再明确提交下一条消息。

开发

src/core/   可嵌入的引擎与公共导出
src/tui/    Ink/React 客户端
examples/   嵌入与自定义工具示例
模块 职责
agent/、loop/ Agent 身份与消息、运行终态与取消、模型及工具循环
tools/、app/ 工具校验与派发、共享连接、子代理及后台工作的装配与归属
session/、async/ 主运行准入、结果交付、检查点保存、恢复、投影与报告
providers/ pi-ai 模型接入、请求取消与错误信息;core 其他模块只依赖 provider 契约
src/tui/ 通过 controller 和 view events 展示状态、处理输入与权限请求
命令 用途
pnpm dev 从源码启动 TUI
pnpm dev:watch 监听源码变动并重启
pnpm build 清理并编译到 dist/
pnpm start 运行已构建的 TUI
pnpm test 运行测试
pnpm typecheck 检查 src/ 类型
pnpm typecheck:tests 检查源码与测试类型
pnpm lint ESLint
pnpm format:check 检查格式

TERM=dumb 会启用 ASCII 显示。组件测试包含 Unicode 输出断言,在此环境下可用 TERM=xterm-256color pnpm test 运行。工程约束和代理工作说明见 AGENTS.md。

License

MIT © mothieras

About

An embeddable, local-first coding agent engine — small trusted core, MCP, subagents, observable execution, and reports.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages