仓库 →

Headless 与 Daemon

AtomCode 除了交互式 TUI,还提供两种无头运行方式:CLI 的 -p headless 模式适合脚本与 CI;atomcode-daemon 则是一个基于 HTTP + SSE 的 API 服务,可以被任意客户端调用。

Headless CLI 模式

在 atomcode 后加上 -p / --prompt,即可单次执行一条任务并直接把回复写到 stdout(类似 Claude Code 的 -p 模式):

atomcode -p "简要介绍这个仓库"

默认只输出 AI 最终的回复文本,方便 pipe 到其他命令。工具调用、token 用量等信息不会污染 stdout。

常用 headless 参数

参数说明
-p, --prompt TEXT要执行的任务描述
--prompt-file PATH从文件读取 prompt(适合长文本,与 -p 互斥)
-v, --verbose把工具调用日志、token 用量、turn 摘要打到 stderr,不影响 stdout
--max-turns N强制上限 N 轮 LLM 调用,避免 agent 在长任务里无限跑。默认不设上限
--disable-tools LIST禁用特定工具,比如 bash,web_fetch。被禁用的工具不会出现在 schema 列表中,模型不会尝试调用
-C, --dir PATH工作目录,默认为当前目录
--provider / --model临时覆盖 provider 或模型
--no-telemetry本次调用关闭遥测上报

示例

# 把当前项目总结写进 README
atomcode -p "总结项目结构并写成 README 草稿" > README.draft.md

# 在 CI 里跑一轮自动修复
atomcode -p "跑 pnpm lint 并修复所有报错,不修改测试文件" \
         --max-turns 30 --disable-tools web_search,web_fetch

# 从文件读取 prompt
atomcode --prompt-file task.md -v 2> run.log

# 指定本地 Ollama,完全离线
atomcode -p "解释这段代码" --provider local --model qwen2.5:14b

退出码

注意:权限模型

Headless 模式没有交互式权限确认对话框。当前实现中,需要确认的 bash 调用会自动批准,并把原因写到 stderr:

[headless] auto-approved bash: <reason>

其他需要确认的工具(edit、write、web_fetch 等的高风险路径)会被自动拒绝:

[approval-denied] tool=<name> reason=<reason>

出现 [approval-denied] 时进程会以非 0 退出码结束。如果你不希望 CI 中执行 shell,可以显式加上 --disable-tools bash 把它从工具列表里彻底移除。

atomcode-daemon

atomcode-daemon 是独立的二进制,直接复用 atomcode-core。它对外暴露 HTTP + Server-Sent Events 接口,可以被 Web 前端、IDE 插件、编辑器扩展消费。AtomCode 官方的 VS Code 扩展和 AtomCode Air 桌面端都是通过它连过来的。

启动

# 推荐:通过 CLI 子命令启动,自动调用同目录下的 atomcode-daemon 二进制
atomcode daemon

# 指定端口与客户端身份(用于遥测分流)
atomcode daemon --port 13456 --client vscode

# 也可以直接调用 daemon 二进制(支持更多参数)
atomcode-daemon --host 127.0.0.1 --port 13456 \
                --client atomcode-air --idle-timeout 1800

daemon 读取与 CLI 相同的 ~/.atomcode/config.toml,登录态、provider 配置、会话历史全部共享。

启动参数

参数说明
--host HOST监听地址,默认 127.0.0.1。非 loopback 地址会触发警告(daemon 没有鉴权,不应暴露到公网)
--port PORT监听端口,默认 13456
--client NAME客户端身份,目前识别 vscode / atomcode-air,其他值视为通用 IDE。影响遥测打点与部分行为
--idle-timeout SECS空闲超时(秒)。默认 1800(30 分钟),0 表示禁用,非零值最小钳制到 60。也可用环境变量 ATOMCODE_DAEMON_IDLE_TIMEOUT
--no-telemetry关闭本次进程的遥测上报
安全

daemon 没有内置鉴权,默认只监听 127.0.0.1。切勿把它直接暴露到公网或局域网 —— 调用方相当于直接拿到本机所有工具的执行权(包括 bash、write、edit)。需要远程使用时,请在前置反代上自行做认证 / TLS / 来源限制。

端点总览

所有端点都注册在 crates/atomcode-daemon/src/main.rs,以下按功能分组。

健康与生命周期

Method + Path说明
GET /health健康检查
POST /shutdown主动关闭 daemon(用于客户端退出时优雅关停)

会话 / 项目

Method + Path说明
GET /sessions列出所有会话
POST /sessions创建新会话
GET /sessions/search按关键词搜索历史会话
GET /project当前工作目录的项目状态
POST /cd切换工作目录
GET /projects列出所有有过会话的项目
GET /projects/:hash/sessions某个项目下的会话列表
GET /projects/:hash/sessions/:id会话详情
DELETE /projects/:hash/sessions/:id删除会话
PATCH /projects/:hash/sessions/:id/rename重命名会话

聊天与模型

Method + Path说明
GET /models列出可用的 provider / model
POST /chat发送一条 prompt,返回 SSE 流
POST /chat/stop停止正在进行的 /chat

配置 / Provider

Method + Path说明
GET /config读取当前 config.toml
POST /config/reload重新加载 config.toml
GET /providers列出所有 provider
POST /providers新增 provider
PATCH /providers/:name修改 provider
DELETE /providers/:name删除 provider
POST /providers/:name/default把该 provider 设为默认
PATCH /providers/:name/thinking切换/调整 provider 的 thinking 模式

MCP

Method + Path说明
GET /mcp/statusMCP server 接入状态
POST /mcp/reload重新加载 .mcp.json

认证 / CodingPlan

Method + Path说明
GET /auth/status当前登录状态
POST /auth/login/start启动 AtomGit OAuth 登录流程
POST /auth/login/:login_id/poll轮询登录结果
DELETE /auth/login/:login_id取消正在进行的登录
POST /auth/logout登出
POST /codingplan/setup领取 CodingPlan 并写入 provider 配置(等同 CLI atomcode login;atomcode codingplan 仍作为隐藏别名保留)

SSE 流式聊天

POST /chat 返回的 SSE 流事件包含:AI 增量文本、推理 (reasoning) 增量、工具调用批次 (开始 / 结束)、token 统计、错误等。具体事件 schema 见 crates/atomcode-core/src/turn/event.rs 的 TurnEvent 定义。

前端可以用原生 EventSource 消费,也可以借助任何 SSE 客户端库。

CORS

daemon 配置了 CORS,仅允许 loopback origin:host 必须是 localhost、127.0.0.1 或 ::1(端口任意,协议任意)。其他来源会被拒绝,这是配合 --host 127.0.0.1 默认监听做的纵深防御 —— 即便有人通过 DNS rebinding 等方式构造请求,跨域那一层也过不去。

典型应用

下一步