atomix

绑定当前工作目录的终端 AI 编码助手。在项目目录里启动，它就以这个项目为上下文：读写代码、执行命令、编排子代理，会话历史与配置按项目天然隔离。

• 终端 TUI：Markdown 流式渲染、工具执行与权限确认卡片、todos 与上下文用量状态栏
• 多模型服务商：Anthropic / OpenAI / DeepSeek / Kimi / GLM / Qwen / MiniMax / OpenRouter 及自定义接口，首次运行向导配置
• 可扩展：skills、子代理、MCP 服务器、hooks、自定义斜杠命令，支持用户级与项目级两层配置
• 并行子代理：AgentTeam 以任务 DAG 一次编排多个子代理，无依赖任务并行执行

安装

需要 Node.js ≥ 20。

npm install -g atomix-cli

从源码构建见开发文档。

快速开始

atomix                      # 在当前目录启动交互会话（TTY 下为 TUI，否则回退基础 REPL）
atomix -C /path/to/project  # 指定工作目录
atomix -p "prompt"          # 一次性执行，stdout 只输出最终回复（适合脚本/管道）
atomix -r                   # 恢复历史会话（列表选择，或 -r <sessionId>）
atomix model                # 模型配置管理：list | add | use <名称> | quick <名称> | del <名称>

首次运行会进入模型配置向导，配置保存在 ~/.atomix/model.conf。

界面语言

界面文案支持 zh-CN / en-US，优先级：--lang > 环境变量 ATOMIX_LANG > ~/.atomix/config.json 的 locale > 系统 LC_ALL / LC_MESSAGES / LANG > en-US。

atomix --lang en-US         # 本次启动用英文
ATOMIX_LANG=zh-CN atomix    # 环境变量

会话内 /lang 查看当前语言与来源，/lang en-US 写入 config.json，重启会话生效。界面语言只影响 atomix 自己的界面文案：atomix 内置的系统提示段、工具描述与占位符恒为英文；你写的 rules.md / AGENTS.md / 记忆与人设文件原样注入，不做翻译；模型的回复语言由对话本身决定，不跟随界面语言。

程序化调用

任何外部程序（辩论 / 面试 / 桌游模拟器……）都可以指定 harness、权限模式、工作目录和可累积的会话来调用 agent：

# 一次性调用：--session 存在即续、不存在即建；--harness 会话级指定，不改项目态
atomix -p "正方一辩发言" -C ./arena --harness debater-a --session debate-a --output-format json
echo "很长的发言稿" | atomix -p - --harness debater-b --session debate-b
atomix -p "整理 src 目录" --permission-mode action-check   # 无人值守：非只读操作被拒绝并报出
atomix --harness reviewer --permission-mode ac             # 交互式同样接受这两个参数

--output-format：text（默认，stdout 只有回复）| json（一行结果对象）| stream-json（NDJSON 事件流 + 结果）。--timeout <秒>：整个任务的超时（不是单步，默认 600，最长 10800 即 3 小时）；--max-steps <n>：主代理模型回复次数上限，第 n 步仍要调工具即中止（默认不限）。退出码 0 成功、1 出错、2 超时、3 达到步数上限。

多回合、多角色的场景（桌游一局、辩论一场）用常驻服务：一个进程托管多个会话，每回合往对应会话发一条，任何语言起子进程按行收发 JSON 即可：

atomix serve -C ./arena
# stdin  → {"id":1,"op":"session.open","params":{"sessionId":"player-1","harness":"pirate"}}
# stdout ← {"type":"response","id":1,"ok":true,"result":{"sessionId":"player-1",...}}
# stdin  → {"id":2,"op":"session.send","params":{"session":"player-1","input":"轮到你出牌"}}
# stdout ← {"type":"event","session":"player-1","event":{"type":"text","delta":"我出"}} …
# stdout ← {"type":"response","id":2,"ok":true,"result":{"text":"…","blocked":[]}}

op 还有 session.inject（处理中插入消息，不打断进行中的 send）/ session.modal（模态输入：语音转写、OCR 等补充文字，落盘、节流、quick 整理后交给 agent）/ llm.quick / session.interrupt（可带 expectedTurn）/ session.close / session.list / history.list / harness.list / server.ping / server.shutdown；事件流带 turn_start / turn_end（完成 / 中断 / 失败）。stdin 结束即关闭全部会话退出。语音、OCR 这类模态程序就是一个 serve 客户端，示例见 examples/modal-dictation.mjs。

TUI 自己的会话接语音 / OCR 不需要 serve 端口：在 ~/.atomix/config.json 写 "modal": { "programs": [{ "name": "voice", "command": ["node", "/abs/voice.mjs", "--hosted"] }] }，TUI 启动时把它作为子进程拉起，在其 stdio 上说同一套协议（程序 session.list 拿到 TUI 会话即可 session.modal，另有 ui.draft 写输入框 / ui.status 状态栏短文本）；打断时未发出的模态文字与键盘文本会回到输入框（docs/session-api-v1.md §12.6）。

Node 程序可直接引库，一进程多会话（每个玩家一个 session，每回合一次 send，MCP 连接共享）：

import { openSession } from 'atomix-cli/session';
const a = await openSession({ cwd: './arena', harness: 'debater-a', sessionId: 'debate-a', multiSession: true });
const { text } = await a.send('辩题：远程办公利大于弊');
await a.dispose();

设计与完整接口见 docs/session-api-v1.md；模态输入见其 §12 与 docs/modality-extension-v1.md。

会话内使用

输入 /help 查看全部命令。常用交互：

| 输入 | 作用 | |---|---| | @文件路径 | 引用文件（自动路径补全；图片扩展名自动作为多模态发送） | | !命令 | 直接执行 shell 命令（输出仅本地显示，不进模型上下文） | | /resume /clear /compact | 切换会话 / 清空上下文 / 压缩上下文 | | /skills /agents /mcp /marketplace | 组件启停、列表与插件市场 | | /memory | 长期记忆 / 人设文件：list 状态与路径，show / path <scope>（scope = global\|project\|soul）、write <global\|project> <一行>（末尾追加；soul 不支持写，人设由模型维护或编辑器改）、config <persona\|global\|project> <on\|off>（写 config.json，重启生效） | | /theme /glyphs /thinking | 主题 / 字形风格 / 思考开关 | | Ctrl+V | 粘贴剪贴板图片或文本 | | Esc / ↑↓ | 中断当前轮 / 输入历史 | | 处理中继续输入 | 不打断当前轮：文本排队，本批工具调用结束后注入对话（模型收尾时作为追问同轮续跑）；Esc 中断会丢弃排队消息 |

自定义命令放在 ~/.atomix/commands/（用户级）或 <项目>/.atomix/commands/（项目级），支持 $ARGUMENTS 替换。

数据与配置

~/.atomix/                # 用户级（环境变量 ATOMIX_ROOT 可覆盖）
├── config.json           # 主题 / 字形 / 生态共享 / persona / memory 开关
├── model.conf            # 模型配置
├── history/<项目>/       # 会话历史，按项目隔离
├── MEMORY.md             # 用户级长期记忆（模型可维护）
├── projects/<项目>/MEMORY.md   # 项目级长期记忆（与 history/<项目> 同键）
├── SOUL.md               # 人设（可选，persona.enabled=true 时读取）
├── harness/<名称>/       # harness 定义（harness.yaml + rules.md）
└── skills/ agents/ commands/ mcp.json hooks.json

<项目目录>/
├── AGENTS.md             # 项目协议（存在即默认加载；入库）
└── .atomix/              # 项目级 skills / agents / commands / mcp.json / hooks.json / harness-state.json

记忆与人设

• 长期记忆：用户级 ~/.atomix/MEMORY.md 与项目级 ~/.atomix/projects/<项目>/MEMORY.md 在每个新会话（及压缩后）注入上下文，主代理可直接维护（无需逐次确认），子代理只读。文件不存在即不注入，不预创建。
• 人设：~/.atomix/SOUL.md 属 base（默认关闭，开启后作为最高权威的 persona 段注入，模型可按你的口头调整落盘）；harness 可自带专属人设 harness/<名称>/SOUL.md（存在即用，切 profile 即覆盖；不带人设的 harness 下人设为关）。
• 项目协议 <项目>/AGENTS.md：与记忆、人设互不相关，存在即加载；不给子代理默认注入（主代理派任务时转述）。
• 开关在 ~/.atomix/config.json，改动重启会话生效：

{
  "persona": { "enabled": false },
  "memory":  { "enabled": true, "global": true, "project": true }
}

• harness 有两档:prompt.disable: [memory-notes] 只关掉"维护记忆"的提示段（仍注入、只是模型不再主动写）;harness.yaml 顶层 memory: / persona: 三态开关注入本身——off 本 harness 下连注入一起关（子代理同）、on 强制开（config.json 关着也开,memory 的 global/project 细分仍尊重 config）、缺省跟随 config。切走即回 config 状态。设计见 记忆与人设 v1。
• /memory config <persona|global|project> <on|off> 免开编辑器改 config.json 开关（重启会话生效）。

文档

• 开发文档：从源码构建、架构、贡献指南
• 设计方案
• 记忆与人设 v1：MEMORY.md / SOUL.md / AGENTS.md 的边界、存储、开关与权限
• Harness 可插拔 v1、P0/P1 验收说明

License

MIT