@zonease/aiworker-cli 0.5.2 → 0.6.0

package/README.md

@@ -1,14 +1,67 @@
 # AIWorker
 
-自托管 Agent Runtime — 由 **Brain provider**（知识 / 记忆 / 技能）与 **Executor provider**（OpenAI 兼容 / claude-code / codex / gemini-cli / qwen-code / cursor / MCP）组合而成。
+轻量自托管 **Project Brain + Worker/Fleet aggregation runtime**。
+
+AIWorker 负责 Project Brain、worker identity/state、gateway routing、fleet
+presence、audit 和 admin surface。Executor 是 bring-your-own 外部 agent runtime：
+Codex、Claude Code、Hermes、OpenClaw、Cursor 等继续拥有自己的 MCP、skills、
+plugins、auth、sandbox、approval 和 native sessions，AIWorker 只通过薄 adapter
+调用、观察和聚合它们。
+
+这里的 Project 是 worker 在 host/workspace 上服务的业务作用域，不等同于
+software project。developer Soul 可以把 scope 绑定到代码仓库；HR Soul 可以把
+scope 绑定到岗位、候选人池或简历库；legal、finance、ops 等 Soul 也应以各自
+业务对象、资料、审核和归档流程为中心建模。
 
 工作站、服务器、k8s pod、docker container 都能跑成一个 worker 加入同一个 fleet。Operator 用一个 CLI 控制所有 worker。
 
+## Operator topology（一图 canonical）
+
+```text
+        ┌──────────────────────────────────────────────────────────────┐
+        │ Operator / Admin                                             │
+        │   $ aiworker fleet ...    $ aiworker gateway ...             │
+        └───────────────────┬──────────────────────────────────────────┘
+                            │ WS  /ws (basicauth) + /enroll-ws (OTP)
+                            ▼
+        ┌──────────────────────────────────────────────────────────────┐
+        │ AIWorker Gateway (control plane)                             │
+        │   fleet.db: registered_workers + audit_events                │
+        │   只持指针 / presence / routing / audit ── 不持 brain / 对话 │
+        └───────────────────┬──────────────────────────────────────────┘
+                            │ WS frame relay
+       ┌────────────────────┼────────────────────┐
+       ▼                    ▼                    ▼
+   ┌──────────┐         ┌──────────┐        ┌──────────┐
+   │ Worker A │         │ Worker B │        │ Worker N │
+   └────┬─────┘         └────┬─────┘        └────┬─────┘
+        │                    │                   │
+        ▼ (data plane, per worker)              ...
+   ┌─────────────────────────────────────────────────────────────┐
+   │ worker.db (identity + config + conversations, AES-256-GCM)  │
+   │ Project Brain (filesystem 权威，5 类资产)                   │
+   │ Thin Executor Adapter   →  External Engine                  │
+   │   health / run / stream / cancel / resume                   │
+   │                            └─→ user/host MCP / skills /     │
+   │                                plugins / auth / sessions    │
+   └─────────────────────────────────────────────────────────────┘
+```
+
+详见 [`docs/architecture.md` § Product Positioning](docs/architecture.md#product-positioning)（同一份 mermaid 图，operator 与 dataplane 视角分开画）；部署形态对照见 [`docs/deployment.md`](docs/deployment.md)。
+
+要点：
+
+- **Gateway = control plane**：fleet.db 只存 worker 指针 / presence / audit；从不缓存 conversations / messages / secrets，也不主动持有 brain 资产。
+- **Worker = data plane**：worker.db 与 Project Brain 都在 worker 本机；fleet 视角通过 gateway WS 发指令读 worker，**不**反向 fetch worker REST。
+- **External executor only inside the worker**：Codex / Claude Code / Hermes / OpenClaw / Cursor 等 engine 在 worker 内由薄 adapter 调用，永不被 gateway 直接接触；engine 自己持 user/host 级 MCP / skills / plugins / auth / native sessions，AIWorker 不默认隔离这些 ambient capabilities。
+
 ## Features
 
+- **Project Brain**：每个业务作用域一份 5 类 brain 资产 — identity（`AGENT/SOUL/USER`）、memory（`MEMORY.md` + `memories/`）、brain skills（`.aiworker/skills/**`）、policy & drafts（`policy.json` / `toolsets.json` / `capability-packs.json` / `.aiworker/mcp.json`）、admission state（roadmap）；filesystem 为权威，便于迁移和审计
+- **Worker/Fleet 聚合**：gateway 管 workers、presence、audit、routing；worker 自持 worker.db、Project Brain 和外部 executor adapter
 - **4 种入网路径**：OTP-attended（worker deployer 零凭证）/ self-enroll（unattended 批量）/ 手动 pair / docker auto-launch
 - **WS 控制面**：operator + worker 共享同一 gateway 入口，按 path 分流（`/ws` basicauth + `/enroll-ws` OTP 专用）
-- **多 LLM engine**：`http` (OpenAI / DeepSeek / SiliconFlow / 任意 OpenAI 兼容) / `claude-code` / `codex` / `acp` (gemini / qwen) / `cursor` / `mcp`
+- **Bring-your-own executor**：`http` baseline / `claude-code` / `codex` / `acp` (gemini / qwen) / `cursor` / `mcp`，外部 engine 自己管理 user/host 级能力
 - **多 channel webhook**：Telegram / WhatsApp / Lark / LINE / Web，全部强制验签
 - **Cron / per-tool approvals / hot-reload / fallback chain** 内建
 - **数据物理隔离**：fleet.db（gateway）与 worker.db（每 worker）AES-256-GCM 各自加密
@@ -107,7 +160,8 @@ npm install -g @zonease/aiworker-cli
 
 AIWorker CLI 是 Bun-native：`npx` / `npm install -g` 不会把 runtime 改成 Node。没有 Bun 时，CLI 会提示安装 Bun 或改用 GitHub Releases 的 standalone binary。binary 跑在 `~/.bun/bin/aiworker` 或 `$(npm bin -g)/aiworker`。第一次跑任意命令时自动 mint master key 写到 `~/.aiworker/.env`（chmod 0600）。
 
-**项目级 worker**（PLAN-023，可选）：`aiworker up --soul developer` 会在当前目录 `<cwd>/.aiworker/` 落项目级 layout（每 project 一份独立 worker.db / master key / persona / skills；不要求当前目录是 git repo），随后完成能力预检并启动本地 HTTP/admin。engine（claude / codex / cursor）保持 user 级共享。`aiworker scope` 诊断当前命中的 layout；显式拆步时仍可用 `aiworker init` / `aiworker doctor` / `aiworker serve`。详见 [docs/cli.md §`aiworker up`](docs/cli.md)。
+**项目级 worker**（PLAN-023，可选）：`aiworker up --soul developer` 会在当前目录 `<cwd>/.aiworker/` 落 Project Brain layout（每个 worker-bound business scope 一份独立 worker.db / master key / persona / brain skills；不要求当前目录是 git repo，也不要求 scope 是软件工程项目），随后完成 brain/runtime 静态预检并启动本地 HTTP/admin。executor（claude / codex / cursor / Hermes / OpenClaw 等）默认是 operator 自己提供的外部运行时，可能加载 user/host 级 MCP、skills、plugins、auth 和 native sessions；AIWorker 不默认做 executor isolation。`aiworker scope` 诊断当前命中的 layout；显式拆步时仍可用 `aiworker init` / `aiworker doctor` / `aiworker serve`。详见 [docs/cli.md §`aiworker up`](docs/cli.md)。
+新项目默认使用安全的 `http/default` stub executor；准备好 Codex / Claude 等本机 CLI 后，用 `aiworker executor select --engine codex --apply` 显式切换 task executor，再用 `aiworker executor doctor --engine codex` 检查 engine CLI 和可选 project executor overlay。`.aiworker/executor-capabilities.json` 只是 bootstrap hint / best-effort projection helper，不是 executor effective capability 的完整来源。
 
 ```sh
 cd ~/code/my-project
@@ -259,8 +313,16 @@ aiworker fleet config get <workerId>
 
 # 2. 切到 claude-code default variant（model=sonnet, timeout=120s）
 NEW='{
-  "brains": [],
-  "brainWriteTarget": "",
+  "brains": [
+    {
+      "id": "local-filesystem",
+      "type": "filesystem",
+      "priority": 100,
+      "readOnly": false,
+      "config": {}
+    }
+  ],
+  "brainWriteTarget": "local-filesystem",
   "brainRetrieval": "first-match",
   "executor": { "engine": "claude-code", "variant": "default" },
   "channels": [],
@@ -268,7 +330,12 @@ NEW='{
 }'
 aiworker fleet config set <workerId> "$NEW" --if-match 1
 
-# 3. chat 验证
+# 3. 如果是在该 worker 主机 / 项目目录内调试，可只读确认 brain source / skills / memories
+aiworker brain status
+aiworker brain skills
+aiworker brain memories --limit 20
+
+# 4. chat 验证
 aiworker fleet chat <workerId> '请用中文回我一句话'
 # {"kind":"accepted",...}
 # {"kind":"chat.message","payload":{"role":"assistant","content":"...claude 真实回复..."}}