atomix-cli 1.0.0 → 1.1.0

package/README.md

@@ -29,6 +29,44 @@ atomix model                # 模型配置管理：list | add | use <名称> | q
 
 首次运行会进入模型配置向导，配置保存在 `~/.atomix/model.conf`。
 
+## 程序化调用
+
+任何外部程序（辩论 / 面试 / 桌游模拟器……）都可以指定 harness、权限模式、工作目录和可累积的会话来调用 agent：
+
+```bash
+# 一次性调用：--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 事件流 + 结果）。退出码 0 成功、1 出错、2 超时。
+
+多回合、多角色的场景（桌游一局、辩论一场）用常驻服务：一个进程托管多个会话，每回合往对应会话发一条，任何语言起子进程按行收发 JSON 即可：
+
+```bash
+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.interrupt` / `session.close` / `session.list` / `history.list` / `harness.list` / `server.ping` / `server.shutdown`；stdin 结束即关闭全部会话退出。
+
+Node 程序可直接引库，一进程多会话（每个玩家一个 session，每回合一次 `send`，MCP 连接共享）：
+
+```ts
+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`。
+
 ## 会话内使用
 
 输入 `/help` 查看全部命令。常用交互：