cli-jaw 2.0.5 → 2.0.6

package/README.zh-CN.md

@@ -2,164 +2,119 @@
 
 # CLI-JAW
 
-### 你已有的 AI 订阅，一个助手统一使用。
+### 你的个人 AI 助手。2 行安装。7 个 AI 引擎，一个仪表盘。
 
 [![npm](https://img.shields.io/npm/v/cli-jaw)](https://npmjs.com/package/cli-jaw)
+[![Version](https://img.shields.io/badge/v2.0.0-GA-brightgreen)](https://github.com/lidge-jun/cli-jaw/releases)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://typescriptlang.org)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-blue)](https://nodejs.org)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
-[![Docker](https://img.shields.io/badge/Docker-supported-2496ED?logo=docker&logoColor=white)](#-docker)
+[![Docker](https://img.shields.io/badge/Docker-supported-2496ED?logo=docker&logoColor=white)](#docker)
 
 [English](README.md) / [한국어](README.ko.md) / **中文** / [日本語](README.ja.md)
 
-![CLI-JAW manager dashboard](docs/screenshots/manager-dashboard-light.png)
-
 </div>
 
-<table>
-<tr><td><b>统一使用已有订阅</b></td><td>通过 OAuth 接入 Claude Max、ChatGPT Pro、Copilot、Gemini Advanced。也可以通过 OpenCode 添加任意模型。没有按 token 计费。</td></tr>
-<tr><td><b>Manager dashboard</b></td><td>在一个浏览器工作区里追踪所有本地 JAW 实例，预览实时 Web UI，切换浅色/深色主题，查看运行时设置，并启动或停止托管会话。</td></tr>
-<tr><td><b>Notes workspace</b></td><td>仪表盘主目录下的 Markdown 仓库。支持文件夹、重命名/移动、未保存状态标记、raw/split/preview 模式、KaTeX、Mermaid 和代码高亮。</td></tr>
-<tr><td><b>你在哪里，它就在哪里</b></td><td>Manager dashboard、Web PWA、Mac WebView app、terminal TUI、带语音的 Telegram、Discord。所有入口共享同一个助手和同一份记忆。</td></tr>
-<tr><td><b>3-layer memory</b></td><td>History Block（近期会话）+ Memory Flush（episodes、daily logs）+ Soul and Task Snapshot（identity、semantic recall）。使用 SQLite FTS5 全文搜索。</td></tr>
-<tr><td><b>Multi-agent orchestration</b></td><td>PABCD 是持久化到 DB 的 5 阶段 FSM。Employee system 带 worker registry。支持并行 subtask 和文件重叠检测。每个 phase 都由你确认。</td></tr>
-<tr><td><b>Browser and desktop automation</b></td><td>Chrome CDP、vision-click、ChatGPT/Grok/Gemini 的 DOM reference、通过 Codex App 接入 Computer Use、用于 SVG 与交互式可视化的 diagram skill。</td></tr>
-<tr><td><b>MCP install once, 5 engines</b></td><td><code>jaw mcp install</code> 会同时同步到 Claude、Codex、Gemini、OpenCode、Copilot。只维护一份配置。</td></tr>
-<tr><td><b>多语言支持</b></td><td>English、Korean、Chinese、Japanese README。i18n Web UI。通过 OfficeCLI 支持 HWP/HWPX 韩文办公文档。</td></tr>
-</table>
+## 安装
 
----
+<details>
+<summary><b>安全安装</b> — 面向现有用户，最小改动</summary>
 
-## 快速链接
+```bash
+# macOS / Linux
+JAW_SAFE=1 npm install -g cli-jaw    # skips optional tool/runtime setup
+jaw init                              # 准备好后再交互式配置
 
-- [安装](#-安装与运行) · [认证](#-认证) · [使用入口](#-使用入口)
-- [引擎路由](#-引擎路由) · [记忆](#-记忆) · [PABCD](#-编排--pabcd) · [技能](#-技能)
-- [浏览器自动化](#-浏览器与桌面自动化) · [MCP](#-mcp) · [消息](#-消息)
-- [CLI 命令](#%EF%B8%8F-cli-命令) · [Docker](#-docker) · [文档](#-文档) · [对比](#%EF%B8%8F-对比)
+# Windows PowerShell
+$env:JAW_SAFE="1"; npm install -g cli-jaw
+jaw init
+```
 
----
+</details>
 
-## Manager dashboard
+```bash
+npm install -g cli-jaw
+jaw dashboard
+```
 
-Dashboard 现在是本地运行 CLI-JAW 的主控制面。实例发现、预览、设置、员工和 Notes 都在一个地方；每个实例仍然保留自己的主目录、数据库、记忆、生命周期元数据和工作目录。
+完成。打开 **http://localhost:3457** 即可拥有你的个人 AI 助手。需要 [Node.js 22+](https://nodejs.org)。
 
-| 区域 | 作用 |
-|---|---|
-| **Navigator** | 按活跃/运行中/离线分组实例，显示 CLI 与模型标签、自定义名称、端口，并提供预览/打开/启动/停止/重启操作 |
-| **Live preview** | 通过 Manager 预览代理嵌入所选实例的 Web UI，带刷新/打开控件和预览开关 |
-| **Runtime settings** | 显示所选实例的当前 CLI、模型、推理深度、权限模式、工作目录、员工、技能和设置 |
-| **Notes** | 仪表盘本地的 markdown 仓库，支持文件夹树、手动保存、拖拽到文件夹、重命名、分屏预览、KaTeX、Mermaid 和代码高亮 |
+> **第一次用？** 安装时会自动配置 Claude、Codex、Gemini、Copilot 和 OpenCode CLI。只需认证其中一个（参见[认证](#认证)）即可开始。
 
-发布打磨还需要补齐的截图：
+<details>
+<summary><b>macOS 一键安装</b> — 没有 Node.js？用这个</summary>
 
-1. 同样三栏布局的深色主题 dashboard。
-2. 展示文件夹树、分屏编辑器/预览、已渲染 KaTeX/Mermaid/代码块的 Notes 模式。
-3. 展示 responsive navigation 的 mobile 或 narrow viewport dashboard。
+```bash
+curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install.sh | bash
+```
 
-<details>
-<summary>在 Windows 上使用？— WSL 一键安装</summary>
+</details>
 
-**步骤 1：安装 WSL**（以管理员身份打开 PowerShell）
+<details>
+<summary><b>Windows（WSL — Windows 子系统 Linux）</b> — 从零一键安装</summary>
 
 ```powershell
+# 1. 安装 WSL（以管理员身份运行 PowerShell）
 wsl --install
 ```
 
-重启后，从 Start Menu 打开 **Ubuntu**。
-
-**步骤 2：安装 CLI-JAW**
+重启后打开 **Ubuntu**，然后：
 
 ```bash
+# 2. 安装 CLI-JAW + 所有依赖
 curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install-wsl.sh | bash
-```
-
-**步骤 3：重新加载 shell 并启动**
-
-```bash
 source ~/.bashrc
-copilot login    # or: claude auth / codex login / gemini
-jaw serve        # → http://localhost:3457
+jaw dashboard
 ```
 
-WSL 脚本是集成 Linux 安装路径：它会验证 `jaw --version`，以 strict mode
-请求同捆 CLI 工具，安装 OfficeCLI，并在成功前验证 `officecli --version`。
-如果没有检测到可运行的 Chromium 或 Windows Chrome fallback，安装器会给出警告，
-不会把 browser/web-ai 说成已经完全可用。
-
-<details>
-<summary>WSL 故障排查</summary>
-
-| 问题 | 解决办法 |
-|---|---|
-| `unzip: command not found` | 重新运行 installer |
-| `jaw: command not found` | `source ~/.bashrc` 或 `export PATH="$HOME/.local/bin:$PATH"` |
-| `officecli: command not found` | 重新运行 WSL installer，或执行 `bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh"` |
-| Permission errors | `sudo chown -R $USER $(npm config get prefix)` |
-
-</details>
 </details>
 
 <details>
-<summary>第一次用终端？— macOS 一键安装</summary>
-
-1. 打开 **Terminal**（`Cmd + Space` → 输入 `Terminal`）
-2. 粘贴下面的命令并按 Enter：
+<summary><b>Docker</b></summary>
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/lidge-jun/cli-jaw/master/scripts/install.sh | bash
-```
-
-3. 认证并启动：
-
-```bash
-copilot login
-jaw serve        # → http://localhost:3457
+docker compose up -d       # → http://localhost:3457
 ```
 
 </details>
 
 ---
 
-## 🚀 安装与运行
+## CLI-JAW 是什么？
 
-```bash
-npm install -g cli-jaw
-jaw serve
-```
+CLI-JAW 是一个开源平台，将你已经在用的 AI 编码 CLI — Claude、Codex、Gemini、Grok、OpenCode、Copilot — 统一成**一个助手、一份记忆、一个仪表盘**。
 
-普通 Linux 的 `npm install -g cli-jaw` 为了兼容性仍把 optional helper 安装视为
-best-effort。需要集成安装保证时请使用 WSL 一键脚本；普通 Linux 安装后请手动验证：
+你的主 CLI（Boss）调度其他 CLI 作为"员工"。不用在各种应用之间来回切换，直接在一个地方下达指令。
 
-```bash
-jaw --version
-officecli --version
-jaw doctor
-```
+- **无需 API 密钥** — 通过你已有的订阅路由
+- **无按 token 计费** — 和你现在的月费一样
+- **本地运行** — 代码不会离开你的机器
 
-打开 **http://localhost:3457**。需要 Node.js 22+，并且至少完成下面一个 AI CLI 的认证。
+<div align="center">
+
+![CLI-JAW Manager Dashboard](docs/screenshots/manager-dashboard-light.png)
 
-> `jaw service install` — 开机自启（自动检测 systemd、launchd 或 Docker）。
->
-> Claude Code 说明：如果需要 Anthropic computer-use MCP，建议使用原生 Claude installer（`curl -fsSL https://claude.ai/install.sh | bash` 或 `claude install`）。当 `claude` 看起来由 npm/bun 管理时，`jaw doctor` 现在会提示警告。
+</div>
 
 ---
 
-## 🔑 认证
+## 认证
 
-只需要一个。选择你已经订阅的服务：
+只需一个。选择你已经订阅的服务：
 
 ```bash
-# Free
-copilot login        # GitHub Copilot
-opencode             # OpenCode — free models available
+# 免费选项（无需信用卡）
+copilot login        # GitHub Copilot（有免费层）
+opencode             # OpenCode — 有免费模型
 
-# Paid (monthly subscription)
-claude auth          # Anthropic Claude Max (computer-use MCP users: native Claude install recommended)
-codex login          # OpenAI ChatGPT Pro (npm/bun installs are fine)
+# 付费（你已经在付的月订阅）
+claude auth login    # Anthropic Claude Max
+codex login          # OpenAI ChatGPT Pro
 gemini               # Google Gemini Advanced
+grok login --oauth   # xAI Grok / Grok Heavy
 ```
 
-检查状态：`jaw doctor`
+一次性检查全部：`jaw doctor`
 
 <details>
 <summary>jaw doctor 输出示例</summary>
@@ -174,9 +129,9 @@ gemini               # Google Gemini Advanced
  ✅ OpenCode CLI    installed
  ✅ Copilot CLI     installed
  ✅ Database        jaw.db OK
- ✅ Skills          22 active, 94 reference
- ✅ MCP             3 servers configured
- ✅ Memory          MEMORY.md exists
+ ✅ Skills          32 active, 194 reference
+ ✅ MCP（插件）      3 servers configured
+ ✅ Memory          structured/ exists
  ✅ Server          port 3457 available
 ```
 
@@ -184,321 +139,352 @@ gemini               # Google Gemini Advanced
 
 ---
 
-## 🖥️ 使用入口
+## 仪表盘
 
-CLI-JAW 有五个使用入口。每个入口使用同一个助手、同一份记忆、同一组 skills。
+仪表盘是你的指挥中心——一个运行在 `http://localhost:3457` 的本地 Web 应用。
 
-| Surface | 你得到什么 |
-|---|---|
-| **Web PWA** | 完整 UI：markdown/KaTeX/Mermaid rendering、virtual scroll、WS streaming、drag-and-drop file upload、voice recording、PABCD roadmap bar、i18n（English, Korean, Chinese, Japanese）、dark/light theme、基于 IndexedDB 的 offline message cache |
-| **Mac WebView app** | 把 `jaw serve` 包在原生 macOS app shell 中。不打开浏览器也能从 Dock 访问 |
-| **Terminal TUI** | multiline editing、slash-command autocomplete、overlay selectors、session persistence、resume classification |
-| **Telegram** | 语音消息（multi-provider STT）、照片、文件。scheduled task 结果会自动送达。支持 model/CLI 切换 slash commands |
-| **Discord** | 文本和文件消息、command sync、channel/thread routing、agent result forwarder |
+### 实例管理器
 
----
+查看每个正在运行的 AI 实例——一键启动、停止、重启。在仪表盘中直接预览实时 Web UI。
 
-## 🔀 引擎路由
+<div align="center">
 
-五个 CLI backend 通过你已有的 OAuth 订阅进行路由。没有按 token 的 API 账单。
+![Dashboard Navigator](docs/screenshots/dashboard-navigator.png)
 
-| CLI | 默认模型 | 认证 | 费用模式 |
-|---|---|---|---|
-| **Claude** | `opus-4-6` | `claude auth` | Claude Max subscription |
-| **Codex** | `gpt-5.5` | `codex login` | ChatGPT Pro subscription |
-| **Gemini** | `gemini-3.1-pro-preview` | `gemini` | Gemini Advanced subscription |
-| **OpenCode** | `minimax-m2.7` | `opencode` | Free models available |
-| **Copilot** | `gpt-5-mini` | `copilot login` | Free tier available |
+</div>
 
-**Fallback chain**：某个引擎 rate-limited 或不可用时，下一个引擎会自动接上。使用 `/fallback [cli1 cli2...]` 配置。
+### 看板
 
-**OpenCode wildcard**：接入任意模型 endpoint，包括 OpenRouter、local LLMs 或任何 OpenAI-compatible API。
+将实例卡片拖入泳道（Backlog → Ready → In Progress → Review → Done）。跟踪每个 AI 会话正在做什么。
 
-> 切换引擎：`/cli codex`。切换模型：`/model gpt-5.5`。Web、Terminal、Telegram、Discord 都支持。
+<div align="center">
 
----
+![看板](docs/screenshots/dashboard-kanban.png)
+
+</div>
 
-## 🧠 记忆
+### 优先级矩阵
 
-三层记忆分别负责不同的回忆范围。
+艾森豪威尔矩阵管理你的任务和提醒。优先处理重要的事。
 
-| 层 | 存什么 | 如何工作 |
-|---|---|---|
-| **History Block** | 最近的会话上下文 | `buildHistoryBlock()` — 最近 10 个会话，最多 8000 字符，按工作目录限定范围。注入到提示开头 |
-| **Memory Flush** | 从对话中提取的结构化知识 | 达到阈值后触发（默认 10 轮）。抽取提示汇总为事件记录、每日日志（`YYYY-MM-DD.md`）、实时笔记，并保存为 markdown 文件 |
-| **Soul + Task Snapshot** | 身份和语义检索 | `soul.md` 定义核心价值、语调、边界。Task Snapshot 每次提示都从 FTS5 index 中搜索最多 4 条语义相关命中（每条 700 字符） |
+<div align="center">
 
-三层都会自动进入系统提示。记忆可搜索：`jaw memory search <query>`，或在任意界面使用 `/memory <query>`。
+![优先级矩阵](docs/screenshots/priority-matrix.png)
 
-高级记忆功能包括资料摘要、初始化/迁移、重建索引流程，可从 Web UI 设置访问。
+</div>
 
----
+### 笔记
 
-## 🎭 编排 — PABCD
+仪表盘内的迷你 Obsidian。文件夹、可视化（WYSIWYG）+ 源码 + 分屏编辑、KaTeX（数学公式渲染）、Mermaid（图表即代码）、语法高亮代码块。
 
-复杂任务使用 CLI-JAW 的 5 阶段状态机。每次状态切换都需要你确认。
+<div align="center">
 
-```
-P (Plan) → A (Audit) → B (Build) → C (Check) → D (Done) → IDLE
-   ⛔         ⛔          ⛔         auto        auto
-```
+![笔记编辑器](docs/screenshots/notes-wysiwyg.png)
 
-| Phase | 发生什么 |
-|---|---|
-| **P** | Boss AI 写出 diff-level plan，并停下来等你 review |
-| **A** | read-only worker 验证 plan 是否可执行 |
-| **B** | Boss 实现。read-only worker 验证结果 |
-| **C** | type-check、docs update、consistency check |
-| **D** | 汇总所有变更，然后回到 idle |
+</div>
 
-状态持久化在 DB 中，server restart 后仍然保留。Workers 不能修改文件。使用 `jaw orchestrate` 或 `/pabcd` 启用。
+### 代理状态
+
+一目了然地监控每个 AI 引擎的健康状况和使用情况。
+
+<div align="center">
+
+![Claude 状态](docs/screenshots/claude-status-widget.png)
+
+</div>
 
 ---
 
-## 📦 技能
+## 员工系统的工作原理
 
-100+ skills，按用途组织。
+核心理念：**你的主 CLI 调用其他 CLI 作为工作者。**
 
-| Category | Skills | 覆盖范围 |
-|---|---|---|
-| **Office** | `pdf`, `docx`, `xlsx`, `pptx`, `hwp` | 读取、创建、编辑文档。通过 OfficeCLI 支持 Korean HWP/HWPX |
-| **Automation** | `browser`, `vision-click`, `screen-capture`, `desktop-control` | Chrome CDP、AI coordinate click、macOS screenshot/camera、Computer Use |
-| **Media** | `video`, `imagegen`, `lecture-stt`, `tts` | Remotion video rendering、OpenAI image generation、lecture transcription、text-to-speech |
-| **Integration** | `github`, `notion`, `telegram-send`, `memory` | issues/PRs/CI、Notion pages、Telegram media delivery、persistent memory |
-| **Visualization** | `diagram` | 在 chat 中渲染 SVG diagrams、charts、interactive visualizations |
-| **Dev guides** | `dev`, `dev-frontend`, `dev-backend`, `dev-data`, `dev-testing`, `dev-pabcd`, `dev-code-reviewer` | 注入 sub-agent prompts 的 engineering guidelines |
+你和一个 AI（Boss）对话。当它需要专业工作时，会向员工分派任务——每个员工运行自己的 CLI 和模型：
+
+```
+你："修复前端样式，并更新 API 端点"
 
-22 个 active skills 始终注入。94+ reference skills 按需加载。
+Boss（Claude）思考中...
+  ├── 分派到 Frontend 员工（OpenCode）→ "修复 dashboard.tsx 中的 CSS grid 布局"
+  ├── 分派到 Backend 员工（Codex）     → "更新 /api/users 以返回分页元数据"
+  └── 综合两方结果返回给你
+```
 
 ```bash
-jaw skill install <name>    # activate a reference skill
+# 底层就是一条命令：
+jaw dispatch --agent "Frontend" --task "修复 dashboard.tsx 中的 CSS grid 布局"
 ```
 
----
+员工是在你的设置中配置的其他 AI CLI。每个有自己的会话、模型和上下文。Boss 审核它们的输出后再呈现给你。
 
-## 🌐 浏览器与桌面自动化
+### 员工 vs 子代理
 
-| Capability | 工作方式 |
-|---|---|
-| **Chrome CDP** | 通过 DevTools Protocol 执行导航、点击、输入、截图、执行 JS、滚动、聚焦、按键等 10 个操作 |
-| **Vision-click** | 截屏后由 AI 提取目标坐标并点击。一个命令即可：`jaw browser vision-click "Login button"` |
-| **DOM reference** | ChatGPT、Grok、Gemini Web UI 的选择器映射文档，覆盖模型选择、停止按钮、工具抽屉 |
-| **Computer Use** | 通过 Codex App Computer Use MCP 自动化桌面应用。DOM 目标走 CDP，桌面应用走 Computer Use |
-| **Diagram skill** | 生成 SVG 图表和交互式 HTML 可视化，并在带复制/保存控件的沙箱化 iframe 中渲染 |
+这是两个不同的东西：
+
+| | 员工 | 子代理 |
+|---|---|---|
+| **是什么** | 配置为工作者的其他 AI CLI（Codex、OpenCode 等） | 单个 CLI 内置的并行任务工具 |
+| **何时用** | 跨不同代码库或领域的多专家协作 | 内部研究、文件读取、并行分析 |
+| **如何用** | `jaw dispatch --agent "Name" --task "..."` | 自动——CLI 在内部生成 |
+
+员工用于"Frontend 做 CSS，Backend 做 API"。子代理用于"做决定前并行读取 5 个文件"。
 
 ---
 
-## 🔌 MCP
+## AI 运行时
 
-[Model Context Protocol](https://modelcontextprotocol.io) 让 AI agents 使用外部工具。CLI-JAW 用一个文件管理五个引擎的 MCP config。
+无按 token 的 API 计费。通过你已有的订阅路由。
 
-```bash
-jaw mcp install @anthropic/context7
-# → syncs to Claude, Codex, Gemini, OpenCode, Copilot config files
-```
+| CLI | 默认模型 | 认证 | 费用 |
+|---|---|---|---|
+| **Claude** | `opus-4-6` | `claude auth login` | Claude Max 订阅 |
+| **Codex** | `gpt-5.5` | `codex login` | ChatGPT Pro 订阅 |
+| **Codex App** | `gpt-5.4` | `codex login` | ChatGPT Pro 订阅 |
+| **Gemini** | `gemini-3.1-pro-preview` | `gemini` | Gemini Advanced 订阅 |
+| **Grok** | `grok-build` | `grok login --oauth` | Grok 订阅；配额仅限认证/状态 |
+| **OpenCode** | `minimax-m2.7` | `opencode` | 有免费模型 |
+| **Copilot** | `gpt-5-mini` | `copilot login` | 有免费层 |
 
-不用再分别编辑五个 JSON 文件。安装一次，所有引擎都会同步。
+**回退链**：当一个引擎被限速时，下一个自动接上。用 `/fallback [cli1 cli2...]` 配置。
 
-```bash
-jaw mcp sync       # re-sync after manual edits
-```
+**OpenCode 通配符**：连接任意模型端点——OpenRouter、本地 LLM（大语言模型）、任何 OpenAI 兼容 API。
+
+> 切换引擎：`/cli codex`。切换模型：`/model gpt-5.5`。Web、终端、Telegram 或 Discord 均可。
 
 ---
 
-## 💬 消息
+## PABCD 编排（Plan → Audit → Build → Check → Done）
 
-### Telegram
+对于复杂任务，CLI-JAW 使用结构化的 5 阶段工作流。每次转换都需要你的批准——没有你的确认什么都不会发布。
 
 ```
-📱 Telegram ←→ 🦈 CLI-JAW ←→ 🤖 AI Engines
+P (Plan) → A (Audit) → B (Build) → C (Check) → D (Done) → IDLE
+   ⛔          ⛔          ⛔         auto        auto
 ```
 
-<details>
-<summary>设置（3 步）</summary>
+| 阶段 | 发生什么 |
+|---|---|
+| **P — Plan** | Boss AI 编写 diff 级别的计划。停下等你审查 |
+| **A — Audit** | 只读工作者验证计划是否可行（imports 存在、签名匹配） |
+| **B — Build** | Boss 实现。只读工作者验证结果 |
+| **C — Check** | 类型检查（`tsc --noEmit`）、文档更新、一致性检查 |
+| **D — Done** | 汇总所有变更。返回空闲状态 |
 
-1. 创建 bot — 给 [@BotFather](https://t.me/BotFather) 发消息 → `/newbot` → 复制 token
-2. 配置 — `jaw init --telegram-token YOUR_TOKEN`，或使用 Web UI settings
-3. 给 bot 发送任意消息。Chat ID 会在第一条消息时自动保存
+状态持久化在数据库中，服务器重启后仍然保留。工作者不能修改文件——只能验证。用 `jaw orchestrate`、`/orchestrate` 或 `/pabcd` 启动。
 
-</details>
+---
 
-Telegram 支持：text chat、voice messages（通过 multi-provider STT 自动转写）、file/photo upload、slash commands（`/cli`、`/model`、`/status`）、scheduled task result delivery。
+## 记忆
 
-### Discord
+三个层次，各覆盖不同的回忆范围。
 
-能力与 Telegram 相同 — text、files、commands。支持 channel/thread routing，并带有用于 agent result broadcast 的 forwarder。通过 Web UI settings 设置。
+| 层 | 存储内容 | 工作方式 |
+|---|---|---|
+| **History Block** | 近期会话上下文 | 最近 10 个会话，最多 8000 字符，按工作目录限定范围。注入到提示开头 |
+| **Memory Flush** | 从对话中提取的结构化知识 | 达到阈值后触发（默认 10 轮）。提取为事件记录、每日日志、语义笔记，保存为 markdown |
+| **Soul + Task Snapshot** | 身份和语义检索 | 核心价值观、语调、边界。全文搜索索引每次提示返回最多 4 条语义相关结果 |
 
-### 语音 & STT
+三层全部自动注入系统提示。记忆可搜索：
 
-语音输入支持 Web（mic button）、Telegram（voice messages）和 Discord。Providers：OpenAI-compatible、Google Vertex AI 或任意 custom endpoint。通过 Web UI settings 配置。
+```bash
+jaw memory search "我们是怎么设置 API 认证的？"
+```
 
 ---
 
-## ⏰ 调度 & heartbeat
+## 技能
 
-| Feature | 做什么 |
-|---|---|
-| **Heartbeat jobs** | 按 cron schedule 运行 unattended tasks。结果发送到 Telegram/Discord |
-| **Service auto-start** | `jaw service install` — 自动检测 systemd（Linux）、launchd（macOS）或 Docker |
-| **Memory auto-reflect** | 用于 structured knowledge extraction 的 optional post-flush reflection |
+230+ 技能覆盖开发工作流、办公文档、自动化和媒体。
 
----
+| 分类 | 技能 | 覆盖范围 |
+|---|---|---|
+| **办公** | `pdf`, `docx`, `xlsx`, `pptx`, `hwp` | 读取、创建、编辑文档。HWP/HWPX（韩国文字处理器格式）原生支持 |
+| **自动化** | `browser`, `vision-click`, `screen-capture`, `desktop-control` | Chrome DevTools Protocol（CDP）浏览器控制、AI 坐标点击、macOS 截屏、Computer Use |
+| **媒体** | `video`, `imagegen`, `lecture-stt`, `tts` | Remotion 视频、OpenAI 图像生成、讲座转录、文字转语音 |
+| **集成** | `github`, `notion`, `telegram-send`, `memory` | Issues/PRs/CI、Notion 页面、Telegram 媒体发送、持久记忆 |
+| **可视化** | `diagram` | 在聊天中渲染 SVG 图表、图形、交互式可视化 |
+| **开发指南** | `dev`, `dev-frontend`, `dev-backend`, `dev-data`, `dev-testing`, `dev-pabcd` | 注入代理提示的工程指南 |
 
-## ⌨️ CLI 命令
+参考技能位于 `skills_ref/`，按需安装到活跃运行时。
 
 ```bash
-jaw serve                         # start server → http://localhost:3457
-jaw chat                          # terminal TUI
-jaw doctor                        # 12-point diagnostics
-jaw service install               # auto-start on boot
-jaw skill install <name>          # activate a skill
-jaw mcp install <package>         # install MCP → syncs to 5 engines
-jaw memory search <query>         # search memory
-jaw browser start                 # launch Chrome (CDP)
-jaw browser vision-click "Login"  # AI-powered click
-jaw clone ~/project               # clone instance
-jaw --home ~/project serve --port 3458  # run second instance
-jaw orchestrate                   # enter PABCD
-jaw dispatch --agent Backend --task "..." # dispatch employee
-jaw reset                         # full reset
+jaw skill install <name>    # 激活参考技能
+jaw skill list              # 查看可用技能
 ```
 
 ---
 
-## 🏗️ 多实例
-
-运行彼此隔离的实例。每个实例都有独立 settings、memory 和 database。
+## 浏览器和桌面自动化
 
-```bash
-jaw clone ~/my-project
-jaw --home ~/my-project serve --port 3458
-```
+| 功能 | 工作方式 |
+|---|---|
+| **Chrome DevTools Protocol** | 导航、点击、输入、截屏、执行 JS、滚动、按键——Chrome 的远程控制 |
+| **Vision-click** | 截屏 → AI 提取目标坐标 → 点击。`jaw browser vision-click "Login button"` |
+| **Computer Use** | 通过 Codex Computer Use 自动化桌面应用。用 Safari 访问 localhost，体验如同 Codex 应用 |
+| **Web-AI 供应商** | `jaw browser web-ai --vendor chatgpt\|gemini\|grok`——会话生命周期、诊断、源码审计支持 |
+| **Diagram 技能** | 生成 SVG 图表和交互式可视化，在聊天中内联渲染 |
 
-每个实例完全独立 — working directory、memory、MCP config 都不同。
+Computer Use 让你用自然语言控制任何 macOS 应用——Finder、Safari、系统设置、Xcode。
 
 ---
 
-## 🔗 远程访问（Tailscale）
+## 消息
 
-```bash
-jaw serve --lan                       # bind 0.0.0.0 + allow tailnet peers
-# settings.json: network.bindHost=0.0.0.0, lanBypass=true
+### Telegram
+
+```
+📱 Telegram ←→ 🦈 CLI-JAW ←→ 🤖 AI Engines
 ```
 
-`lanBypass=true` 时支持的 peer addresses：
+文字聊天、语音消息（通过多供应商 STT——语音转文字 自动转录）、文件/照片上传、斜杠命令（`/cli`、`/model`、`/status`）、定时任务（`every`/`cron`——循环计划）结果自动送达。
 
-- `100.64.0.0/10` — Tailscale CGNAT (RFC 6598)
-- `fd7a:115c:a1e0::/48` — Tailscale ULA
-- `*.ts.net` — MagicDNS hostnames（Host + Origin both pass）
+<details>
+<summary>设置（3 步）</summary>
 
-注意事项：
+1. 给 [@BotFather](https://t.me/BotFather) 发消息 → `/newbot` → 复制 token
+2. `jaw init --telegram-token YOUR_TOKEN` 或在 Web UI 设置中输入
+3. 给 bot 发送任意消息。Chat ID 首次消息时自动保存
 
-- Tailnet peers 已通过 WireGuard + IdP 认证 — 把它们当作 LAN，而不是 public。
-- Shared tailnets：结合 Tailscale ACL（`acl.tailnet`）限制谁能访问 node。
-- Subnet router / exit node：SNAT 会把 peer IP 折叠成 router 的 100.x，trust boundary 会变模糊。建议使用 direct tailnet membership。
-- Production：尽量把 `bindHost` 缩到 `tailscale0` interface address，而不是 `0.0.0.0`。
-- `lanBypass=true` 时，tailnet peers 会跳过 Bearer token（与 RFC 1918 一样按 LAN 处理）。如需让所有非 loopback peer 都提供 `JAW_AUTH_TOKEN`，设置 `lanBypass=false`。
+</details>
 
----
+### Discord
 
-## 🐳 Docker
+与 Telegram 功能相同——文字、文件、命令。频道/线程路由、规范 `/api/channel/send`、代理结果广播转发器。通过 Web UI 设置配置。
 
-```bash
-docker compose up -d       # → http://localhost:3457
-```
+### 语音 & STT
 
-使用非 root 的 `jaw` 用户，并启用 Chromium sandbox。包含两个 Dockerfile：`Dockerfile`（npm install）和 `Dockerfile.dev`（local source）。数据保存在 `jaw-data` named volume 中。
+语音输入支持 Web（麦克风按钮）、Telegram（语音消息）和 Discord。供应商：OpenAI 兼容、Google Vertex AI 或任意自定义端点。
 
-<details>
-<summary>Docker details</summary>
+---
 
-```bash
-# Dev build
-docker build -f Dockerfile.dev -t cli-jaw:dev .
-docker run -d -p 3457:3457 --env-file .env cli-jaw:dev
+## MCP（Model Context Protocol）
 
-# Pin version
-docker build --build-arg CLI_JAW_VERSION=1.0.1 -t cli-jaw:1.0.1 .
+[MCP](https://modelcontextprotocol.io) 是一个让 AI 工具共享能力的标准——就像 AI 代理的插件。CLI-JAW 用一个文件管理所有引擎的 MCP 配置。
 
-# If Chromium sandbox fails
-docker run -e CHROME_NO_SANDBOX=1 -p 3457:3457 cli-jaw
+```bash
+jaw mcp install @anthropic/context7
+# → 同步到 Claude、Codex、Gemini、OpenCode、Copilot 的配置文件
 ```
 
-</details>
+不用再分别编辑多个 JSON 文件。安装一次，每个 MCP 感知引擎都会获得配置。Grok CLI 是标准运行时，但在 Grok 暴露兼容配置面之前不计为 MCP 同步对象。
+
+```bash
+jaw mcp sync       # 手动编辑后重新同步
+```
 
 ---
 
-## 📖 文档
+## CLI 命令
 
-| 文档 | 内容 |
-|---|---|
-| [CHANGELOG.md](CHANGELOG.md) | Release log，包括覆盖 v1.2.0 到 v1.5.1 的 v1.6.0 catch-up |
-| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design、module graph、94 个 endpoints 上的 95 个 API handlers |
-| [TESTS.md](TESTS.md) | Test coverage、counts、test plan |
-| [memory-architecture.md](docs/memory-architecture.md) | 3-layer memory model、indexing、runtime behavior |
-| [env-vars.md](docs/env-vars.md) | Environment variable reference |
-| [skill-router-plan.md](docs/skill-router-plan.md) | Skill routing architecture |
-| [officecli-integration.md](docs/officecli-integration.md) | 面向 HWP/HWPX 和 Office documents 的 OfficeCLI setup |
-| [devlog/structure/](devlog/structure/) | Internal architecture reference — prompt pipeline、agent spawn、frontend、server API、commands、Telegram、memory |
+```bash
+# 核心
+jaw dashboard                     # 启动管理仪表盘
+jaw serve                         # 启动服务器（http://localhost:3457）
+jaw chat                          # 终端聊天 UI
+jaw doctor                        # 12 项诊断
+
+# 实例
+jaw clone ~/project               # 克隆实例到新目录
+jaw --home ~/project serve --port 3458  # 运行第二个实例
+jaw service install               # 开机自启
+
+# AI 和编排
+jaw dispatch --agent "Backend" --task "..."  # 分派员工
+jaw orchestrate                   # 进入/控制 PABCD 工作流
+
+# 技能和 MCP
+jaw skill install <name>          # 激活技能
+jaw skill list                    # 列出可用技能
+jaw mcp install <package>         # 安装 MCP → 同步支持的 MCP 感知引擎
+jaw mcp sync                      # 重新同步 MCP 配置
+
+# 记忆
+jaw memory search <query>         # 跨所有记忆层搜索
+jaw memory save <file> <content>  # 保存到结构化记忆
+
+# 浏览器
+jaw browser start                 # 启动 Chrome 自动化
+jaw browser fetch "https://example.com" --json --trace  # 自适应 URL 读取
+jaw browser snapshot              # 捕获页面状态
+jaw browser vision-click "Login"  # AI 驱动的点击
+
+# 维护
+jaw reset                         # 完全重置
+```
 
 ---
 
-## ⚖️ 对比
+## 多实例
 
-| | CLI-JAW | Hermes Agent | Claude Code |
-|---|---|---|---|
-| **Model access** | OAuth subscriptions（Claude Max、ChatGPT Pro、Copilot、Gemini）+ OpenCode wildcard | API keys（OpenRouter 200+、Nous Portal） | Anthropic only |
-| **Cost model** | 你已经支付的 monthly subscriptions | Per-token API billing | Anthropic subscription |
-| **Primary UI** | Web PWA + Mac app + TUI | TUI only | CLI + IDE plugins |
-| **Messaging** | Telegram（voice）+ Discord | Telegram/Discord/Slack/WhatsApp/Signal | None |
-| **Memory** | 3-layer（History/Flush/Soul）+ FTS5 | Self-improving learning loop + Honcho | File-based auto-memory |
-| **Browser automation** | Chrome CDP + vision-click + DOM ref | Limited | Via MCP |
-| **Orchestration** | PABCD 5-phase FSM | Subagent spawn | Task tool |
-| **Execution** | Local + Docker | Local/Docker/SSH/Daytona/Modal/Singularity | Local |
-| **Skills** | 100+ bundled | Self-creating + agentskills.io | User-configured |
-| **i18n** | English, Korean, Chinese, Japanese | English | English |
-
-CLI-JAW 源自 OpenClaw harness architecture（hybrid search manager、fallback patterns、session indexing）。如果从 OpenClaw 迁移，slash-command surface 和 memory model 会很熟悉。
+运行互相隔离的独立实例，各有独立的设置、记忆和数据库：
+
+```bash
+jaw clone ~/my-project
+jaw --home ~/my-project serve --port 3458
+```
+
+每个实例完全独立——不同的工作目录、记忆、MCP 配置。管理仪表盘可以看到全部。
 
 ---
 
-## 🛠️ 开发
+## 开发
 
 ```bash
 npm run build          # tsc → dist/
-npm run dev            # tsx server.ts (hot-reload)
-npm test               # native Node.js test runner
+npm run dev            # tsx server.ts（热重载）
+npm test               # Node.js 原生测试运行器
+npm run gate:all       # 发布/文档一致性门禁
 ```
 
-Architecture 和 test details 见 [ARCHITECTURE.md](docs/ARCHITECTURE.md)、[TESTS.md](TESTS.md) 和 [devlog/structure/](devlog/structure/)。
+架构详情：[ARCHITECTURE.md](docs/ARCHITECTURE.md) · 测试覆盖：[TESTS.md](TESTS.md) · 内部结构文档：[structure/](structure/)
+
+---
+
+## 对比
+
+| | CLI-JAW 2.0 | Hermes Agent | Claude Code |
+|---|---|---|---|
+| **模型接入** | Claude、Codex、Codex App、Gemini、Grok、OpenCode 和 Copilot（通过厂商认证） | API 密钥（OpenRouter 200+、Nous Portal） | 仅 Anthropic |
+| **费用模型** | 你已经在付的月订阅 | 按 token API 计费 | Anthropic 订阅 |
+| **主 UI** | 管理仪表盘 + Web 应用 + Mac 应用 + 终端 UI | 仅终端 | CLI + IDE 插件 |
+| **仪表盘** | 多实例管理器、看板、笔记工作区 | 无 | 无 |
+| **消息** | Telegram（语音）+ Discord | Telegram/Discord/Slack/WhatsApp/Signal | 无 |
+| **记忆** | 3 层（History/Flush/Soul）+ 全文搜索 | 自我改进循环 + Honcho | 文件型自动记忆 |
+| **多代理** | 员工系统（分派其他 CLI）+ PABCD | 子代理生成 | Task 工具 |
+| **浏览器自动化** | Chrome DevTools + vision-click + Computer Use | 有限 | 通过 MCP |
+| **运行环境** | 本地 + Docker | 本地/Docker/SSH/Daytona/Modal | 本地 |
+| **技能** | 230+ 内置 | 自动创建 + agentskills.io | 用户配置 |
+| **多语言** | 英语、韩语、中文、日语 | 英语 | 英语 |
 
 ---
 
-## ❓ 故障排查
+## 故障排查
 
 | 问题 | 解决办法 |
 |---|---|
-| `cli-jaw: command not found` | 重新运行 `npm install -g cli-jaw`。确认 `npm bin -g` 在 `$PATH` 中 |
+| `cli-jaw: command not found` | 重新运行 `npm install -g cli-jaw`。检查 `~/.local/bin` 或 `npm bin -g` 是否在 `$PATH` 中 |
 | `Error: node version` | 升级到 Node.js 22+：`nvm install 22` |
-| `NODE_MODULE_VERSION` mismatch | `npm run ensure:native`（auto-rebuild） |
-| `EADDRINUSE: port 3457` | 另一个 instance 正在运行。使用 `--port 3458` |
-| Telegram or agent auth fails | 运行 `jaw doctor`，然后重启 `jaw serve` |
-| Browser commands fail | 安装 Chrome。先运行 `jaw browser start` |
+| `NODE_MODULE_VERSION` mismatch | `npm run ensure:native`（自动重编译原生模块） |
+| `EADDRINUSE: port 3457` | 另一个实例正在运行。使用 `--port 3458` 或先停止 |
+| Telegram / Discord 认证失败 | 运行 `jaw doctor`，检查 token，重启 `jaw serve` |
+| 浏览器命令失败 | 安装 Chrome/Chromium。先运行 `jaw browser start` |
+| 员工分派挂起 | 确保员工 CLI 已认证（`jaw doctor`） |
+| Computer Use 不工作 | 仅限 macOS。需要 Codex CLI。在系统设置中检查自动化权限 |
 
 ---
 
-## 🤝 参与贡献
+## 参与贡献
 
-1. 从 `master` fork 并创建 branch
+1. 从 `master` Fork 并创建分支
 2. `npm run build && npm test`
 3. 提交 PR
 
-发现 bug 或有想法？[Open an issue](https://github.com/lidge-jun/cli-jaw/issues)
+Bug 报告和功能建议：[Open an issue](https://github.com/lidge-jun/cli-jaw/issues)
 
 ---
 
 <div align="center">
 
-**[MIT License](LICENSE)**
+**[MIT License](LICENSE)** · 由受够了在 AI 应用间切换标签的开发者们打造。
 
 </div>