atomix-cli 0.1.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` 查看全部命令。常用交互：
@@ -39,6 +77,7 @@ atomix model                # 模型配置管理：list | add | use <名称> | q
 | `!命令` | 直接执行 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 / ↑↓ | 中断当前轮 / 输入历史 |
@@ -49,20 +88,43 @@ atomix model                # 模型配置管理：list | add | use <名称> | q
 
 ```
 ~/.atomix/                # 用户级（环境变量 ATOMIX_ROOT 可覆盖）
+├── config.json           # 主题 / 字形 / 生态共享 / persona / memory 开关
 ├── model.conf            # 模型配置
 ├── history/<项目>/       # 会话历史，按项目隔离
-├── skills/ agents/ commands/ mcp.json hooks.json
-└── AGENT.md              # 全局规则
+├── MEMORY.md             # 用户级长期记忆（模型可维护）
+├── projects/<项目>/MEMORY.md   # 项目级长期记忆（与 history/<项目> 同键）
+├── SOUL.md               # 人设（可选，persona.enabled=true 时读取）
+├── harness/<名称>/       # harness 定义（harness.yaml + rules.md）
+└── skills/ agents/ commands/ mcp.json hooks.json
 
 <项目目录>/
-├── AGENT.md | CLAUDE.md  # 项目规则（即本项目的"人设"）
-└── .atomix/              # 项目级 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`，改动重启会话生效：
+
+```jsonc
+{
+  "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](docs/memory-v1.md)。
+- `/memory config <persona|global|project> <on|off>` 免开编辑器改 `config.json` 开关（重启会话生效）。
+
 ## 文档
 
 - [开发文档](docs/development.md)：从源码构建、架构、贡献指南
 - [设计方案](docs/dev-plan-v0.md)
+- [记忆与人设 v1](docs/memory-v1.md)：MEMORY.md / SOUL.md / AGENTS.md 的边界、存储、开关与权限
+- [Harness 可插拔 v1](docs/harness-plugin-v1.md)、[P0/P1 验收说明](docs/harness-plugin-p0p1-review.md)
 
 ## License