wangchuan 4.1.0 → 4.2.0

package/README.md

@@ -2,187 +2,104 @@
 
 [中文文档](README.zh-CN.md)
 
-> In Chinese mythology, Wangchuan (忘川) is the River of Oblivion in the underworld — souls crossing it forget all memories of past lives.
-> **Wangchuan** ensures your AI agent memories are never lost across environments.
-
-Encrypted backup and cross-environment migration for AI agent configs and memories. Supports **7 agents**: OpenClaw, Claude, Gemini, CodeBuddy, WorkBuddy, Cursor, and Codex.
-
 [![npm version](https://img.shields.io/npm/v/wangchuan)](https://www.npmjs.com/package/wangchuan)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.19.0-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
----
-
-## Features
-
-- **AES-256-GCM encryption** — keys stored locally, never committed to Git
-- **7 agents** — OpenClaw, Claude, Gemini, CodeBuddy, WorkBuddy, Cursor, Codex
-- **Cross-agent sharing** — skills and MCP configs auto-distributed across all agents
-- **JSON field-level sync** — extract specific fields (e.g. `mcpServers` from `.claude.json`)
-- **Delete propagation** — items deleted from all agents are pruned from repo
-- **One-click restore** — `init + pull` fully restores all agent configs on a new server
-- **Conflict resolution** — interactive overwrite/skip choices on pull
-- **Auto-rollback** — failed operations don't pollute repo history
-- **i18n** — full English and Chinese CLI support via `wangchuan lang zh|en`
-- **Plaintext token scanning** — auto-detect leaked secrets before push
-- **Config migration** — automatic v1→v2 migration with backup and rollback
-
----
-
-## Commands
+> Encrypted sync for AI agent configs and memories — across machines, across agents, never lost.
 
-| Command | Description |
-|---------|-------------|
-| `init` | Initialize system, generate AES-256-GCM key, clone private repo |
-| `pull` | Pull and decrypt configs from repo, restore to local workspace |
-| `push` | Encrypt and push local configs to repo |
-| `sync` | Two-way sync (pull then push) |
-| `status` | Show repo status, workspace diff and file inventory |
-| `diff` | Line-level diff per file (auto-decrypt) |
-| `list` | List all managed files with local/repo presence |
-| `dump` | Generate plaintext snapshot to temp dir for inspection |
-| `lang` | Switch CLI display language (zh/en) |
-| `watch` | Watch for file changes and auto-sync |
-| `env` | Manage sync environments (create/switch/list/delete) |
-| `agent` | Manage agents (list/enable/disable/set-path/info) |
-| `key` | Key management (export/import/rotate) |
-| `report` | Generate sync report |
-| `doctor` | Diagnose and fix common issues |
-| `history` | Show sync operation history |
-| `snapshot` | Create/restore/list point-in-time snapshots |
-| `summary` | Show sync summary statistics |
-| `setup` | Guided interactive setup wizard |
-| `health` | System health check |
-| `search` | Search across synced files |
-| `config` | Config export/import management |
-| `changelog` | Show sync changelog |
-| `tag` | Memory tagging system |
-| `cleanup` | Clean up expired memory entries |
-| `template` | Apply pre-built sync config templates |
-| `batch` | Run multiple commands in sequence |
-| `completions` | Generate shell completion scripts (bash/zsh) |
-
-All commands support `--agent <name>` filtering (except `lang`).
-
----
-
-## Installation
-
-```bash
-npm install -g wangchuan
-```
-
-Or from source:
-
-```bash
-git clone https://github.com/nicepkg/wangchuan.git
-cd wangchuan
-npm install
-npm run build
-npm link
-```
+Wangchuan encrypts and syncs your AI agent configurations, memories, and skills through a private Git repo. One command to sync, one daemon to keep everything up to date.
 
 ---
 
 ## Quick Start
 
-### 1. Initialize
-
 ```bash
-wangchuan init --repo git@github.com:yourname/your-brain.git
-```
-
-This creates:
-- `~/.wangchuan/config.json` — system configuration
-- `~/.wangchuan/master.key` — master encryption key (**back this up!**)
-- `~/.wangchuan/repo` — local clone of your sync repo
-
-### 2. Push local configs
+npm install -g wangchuan
 
-```bash
-wangchuan push -m "initial sync"
-```
+# 1. Initialize (interactive wizard)
+wangchuan init
 
-### 3. Pull on a new machine
+# 2. Sync everything
+wangchuan sync
 
-```bash
-wangchuan init --repo git@github.com:yourname/your-brain.git --key /path/to/master.key
-wangchuan pull
+# 3. Start background daemon
+wangchuan watch
 ```
 
-### 4. Check status
+On a new machine:
 
 ```bash
-wangchuan status
+wangchuan init --repo git@github.com:you/brain.git --key /path/to/master.key
+wangchuan sync
 ```
 
-### 5. Switch language
-
-```bash
-wangchuan lang en      # English
-wangchuan lang zh      # Chinese
-WANGCHUAN_LANG=en wangchuan status   # env override
-```
+---
 
-### 6. Filter by agent
+## Commands
 
-```bash
-wangchuan push --agent claude -m "update Claude config"
-wangchuan pull --agent openclaw
-wangchuan diff --agent gemini
-```
+| Command | Aliases | Description | Key Flags |
+|---------|---------|-------------|-----------|
+| `init` | — | One-time setup (interactive if no `--repo`) | `--repo`, `--key`, `--force` |
+| `sync` | `s` | Smart bidirectional sync — THE daily command | `-a, --agent`, `-n, --dry-run` |
+| `status` | `st` | One-screen summary + health score | `-v, --verbose` |
+| `watch` | — | Background daemon for continuous sync | `-i, --interval <min>` |
+| `doctor` | — | Diagnose + auto-fix everything | `--key-export`, `--key-rotate`, `--setup` |
+| `memory` | — | Browse/copy memories between agents | `list`, `show`, `copy`, `broadcast` |
+| `env` | — | Multi-environment management | `list`, `create`, `switch`, `current`, `delete` |
+| `lang` | — | Switch display language | `zh`, `en` |
 
 ---
 
 ## Supported Agents
 
-| Agent | Default Path | Sync Files | JSON Fields |
-|-------|-------------|------------|-------------|
-| **OpenClaw** | `~/.openclaw/workspace/` | MEMORY.md (enc), AGENTS.md, SOUL.md | — |
-| **Claude** | `~/.claude/` | CLAUDE.md, settings.json (enc) | `.claude.json` → `mcpServers` (enc) |
-| **Gemini** | `~/.gemini/` | — | `settings.internal.json` → `security`, `model` |
-| **CodeBuddy** | `~/.codebuddy/` | MEMORY.md (enc), CODEBUDDY.md | `mcp.json` → `mcpServers` (enc) |
-| **WorkBuddy** | `~/.workbuddy/` | MEMORY.md (enc), IDENTITY.md, SOUL.md, USER.md (enc) | `mcp.json` → `mcpServers` (enc) |
-| **Cursor** | `~/.cursor/` | rules/ (dir) | `mcp.json` → `mcpServers` (enc), `cli-config.json` → fields (enc) |
-| **Codex** | `~/.codex/` | MEMORY.md (enc), instructions.md | — |
-
-Each agent's `workspacePath` can be customized in `~/.wangchuan/config.json`.
-
----
-
-## Repo Structure (v2)
+| Agent | Default Path | Synced Content |
+|-------|-------------|----------------|
+| **OpenClaw** | `~/.openclaw/workspace/` | MEMORY.md (enc), AGENTS.md, SOUL.md, IDENTITY.md, USER.md (enc), memory/ (enc) |
+| **Claude** | `~/.claude/` | CLAUDE.md, settings.json (enc), `.claude.json` → mcpServers (enc) |
+| **Gemini** | `~/.gemini/` | `settings.internal.json` → security + model + general (enc) |
+| **CodeBuddy** | `~/.codebuddy/` | MEMORY.md (enc), CODEBUDDY.md, mcp.json → mcpServers (enc), settings.json → enabledPlugins (enc) |
+| **WorkBuddy** | `~/.workbuddy/` | MEMORY.md (enc), IDENTITY.md, SOUL.md, USER.md (enc), mcp.json → mcpServers (enc) |
+| **Cursor** | `~/.cursor/` | rules/ (dir), mcp.json → mcpServers (enc), cli-config.json → fields (enc) |
+| **Codex** | `~/.codex/` | AGENTS.md, instructions.md |
 
-```
-repo/
-├── shared/                        Cross-agent shared tier
-│   ├── skills/                    Merged skills from all agents
-│   ├── mcp/                       Extracted MCP configs
-│   └── memory/SHARED.md.enc       Shared memory (encrypted)
-├── agents/
-│   ├── openclaw/
-│   │   ├── MEMORY.md.enc          Long-term memory (encrypted)
-│   │   ├── AGENTS.md              Agent behavior rules
-│   │   └── SOUL.md                Agent persona
-│   ├── claude/
-│   │   ├── CLAUDE.md              Global instructions
-│   │   ├── settings.json.enc      Permissions/plugins/model (encrypted)
-│   │   └── mcpServers.json.enc    Extracted from .claude.json (encrypted)
-│   ├── gemini/
-│   │   └── settings-sync.json     Extracted security + model fields
-│   ├── codebuddy/
-│   ├── workbuddy/
-│   ├── cursor/
-│   └── codex/
-```
+Agent paths are customizable in `~/.wangchuan/config.json`.
 
 ---
 
-## Encryption
+## Features
 
-- **Algorithm**: AES-256-GCM (authenticated encryption, tamper-proof)
-- **Key**: `~/.wangchuan/master.key` (32 bytes, hex-encoded)
-- **Ciphertext format**: `IV(12B) + AuthTag(16B) + CipherText` → Base64 → `.enc` file
-- ⚠️ **Losing `master.key` means losing access to all encrypted history — back it up!**
+### Encryption
+- **AES-256-GCM** authenticated encryption — tamper-proof
+- Key stored locally at `~/.wangchuan/master.key` (never committed)
+- Ciphertext: `IV(12B) + AuthTag(16B) + CipherText` → Base64 → `.enc`
+- Auto-scan for leaked tokens before every sync
+
+### Cross-Agent Sharing
+- Skills and MCP configs auto-distributed to all agents
+- Delete propagation — removed from all agents → pruned from repo
+- Existing entries preserved (no overwrite)
+
+### Multi-Environment
+- Create isolated environments: `wangchuan env create work`
+- Switch instantly: `wangchuan env switch work`
+- Each environment has its own agent configs
+
+### Watch Daemon
+- `wangchuan watch` runs continuous background sync
+- Configurable interval: `wangchuan watch -i 10`
+- PID singleton — only one instance per machine
+
+### Memory Browsing
+- `wangchuan memory list` — overview of all agent memories
+- `wangchuan memory copy openclaw claude` — transfer memories
+- `wangchuan memory broadcast claude` — share to all agents
+
+### Doctor
+- Auto-discovers installed agents
+- Detects stale/phantom files
+- `--key-export` / `--key-rotate` for key management
+- `--setup` generates a migration one-liner for new machines
 
 ---
 
@@ -192,23 +109,22 @@ Config at `~/.wangchuan/config.json`:
 
 ```jsonc
 {
-  "repo": "git@github.com:yourname/your-brain.git",
+  "repo": "git@github.com:you/brain.git",
   "branch": "main",
   "localRepoPath": "~/.wangchuan/repo",
   "keyPath": "~/.wangchuan/master.key",
   "version": 2,
   "profiles": {
     "default": {
-      "openclaw": { "enabled": true, "workspacePath": "~/.openclaw/workspace", ... },
-      "claude":   { "enabled": true, "workspacePath": "~/.claude", ... },
-      "gemini":   { "enabled": true, "workspacePath": "~/.gemini", ... },
-      "codex":    { "enabled": true, "workspacePath": "~/.codex", ... }
+      "openclaw": { "enabled": true, "workspacePath": "~/.openclaw/workspace" },
+      "claude":   { "enabled": true, "workspacePath": "~/.claude" },
+      "gemini":   { "enabled": true, "workspacePath": "~/.gemini" }
     }
   },
   "shared": {
-    "skills": { "sources": [{ "agent": "claude", "dir": "skills/" }, ...] },
-    "mcp":    { "sources": [{ "agent": "claude", "src": ".claude.json", "field": "mcpServers" }, ...] },
-    "syncFiles": [...]
+    "skills": { "sources": [{ "agent": "claude", "dir": "skills/" }] },
+    "mcp":    { "sources": [{ "agent": "claude", "src": ".claude.json", "field": "mcpServers" }] },
+    "syncFiles": []
   }
 }
 ```
@@ -218,35 +134,27 @@ Config at `~/.wangchuan/config.json`:
 ## Security
 
 1. `master.key` is in `.gitignore` — never accidentally committed
-2. Auto-scan for plaintext tokens (`api_key`, `sk-xxx`, `password`, etc.) before push
-3. Transfer keys via encrypted channels only (never plaintext email/IM)
+2. Auto-scan for plaintext tokens (`api_key`, `sk-xxx`, `password`) before sync
+3. Transfer keys via encrypted channels only
+4. ⚠️ **Losing `master.key` means losing access to all encrypted history — back it up!**
 
 ---
 
-## Project Structure
+## Installation
 
+```bash
+npm install -g wangchuan
 ```
-wangchuan/
-├── bin/wangchuan.ts          CLI entry
-├── src/
-│   ├── core/
-│   │   ├── sync.ts           Sync engine (distribute, prune, 3-way ops)
-│   │   ├── json-field.ts     JSON field extraction & merge
-│   │   ├── crypto.ts         AES-256-GCM encrypt/decrypt
-│   │   ├── git.ts            simple-git wrapper
-│   │   ├── config.ts         Config management (v2 profiles + shared)
-│   │   └── migrate.ts        v1→v2 migration (backup + lock + rollback)
-│   ├── agents/               Agent definitions (one file per agent)
-│   ├── commands/             28 CLI commands
-│   ├── utils/                Logger, validator, line diff, prompt
-│   ├── i18n.ts               i18n message dictionary & t() helper
-│   └── types.ts              Global type definitions
-├── skill/                    OpenClaw Skill wrapper
-├── test/                     Unit tests (crypto, json-field, sync engine)
-└── .wangchuan/
-    └── config.example.json   Config example (v2)
+
+From source:
+
+```bash
+git clone https://github.com/nicepkg/wangchuan.git
+cd wangchuan && npm install && npm run build && npm link
 ```
 
+Requires Node.js ≥ 18.19.0.
+
 ---
 
 ## License

package/README.zh-CN.md

@@ -2,213 +2,129 @@
 
 [English](README.md)
 
-> 忘川是中国神话中冥界的遗忘之河，亡魂渡河饮水即忘前世一切记忆。
-> 而 **忘川** 让你的 AI 智能体记忆在环境切换时永不遗失。
-
-AI 记忆同步系统 — 加密备份与跨环境迁移。支持 **7 种智能体**：OpenClaw、Claude、Gemini、CodeBuddy、WorkBuddy、Cursor、Codex。
-
 [![npm version](https://img.shields.io/npm/v/wangchuan)](https://www.npmjs.com/package/wangchuan)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.19.0-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
----
-
-## 功能特性
-
-- **AES-256-GCM 加密** — 密钥本地存储，永不提交 Git
-- **7 种智能体** — OpenClaw、Claude、Gemini、CodeBuddy、WorkBuddy、Cursor、Codex
-- **跨 agent 共享** — Skills 和 MCP 配置自动在所有 agent 间分发
-- **JSON 字段级同步** — 提取指定字段（如从 `.claude.json` 只同步 `mcpServers`）
-- **删除传播** — 所有 agent 都删除的 skill/MCP 自动从仓库清理
-- **一键还原** — 新服务器 `init + pull` 即可完整恢复所有 agent 配置
-- **冲突解决** — 拉取时交互式选择覆盖/跳过
-- **自动回滚** — 失败自动回滚，不污染仓库历史
-- **多语言** — 完整中英文 CLI 支持，通过 `wangchuan lang zh|en` 切换
-- **明文扫描** — 推送前自动检测泄露的 token/密钥
-- **配置迁移** — 自动 v1→v2 迁移，含备份和回滚保护
-
----
-
-## 命令列表
+> AI 记忆加密同步 — 跨机器、跨智能体，永不遗失。
 
-| 命令 | 描述 |
-|------|------|
-| `init` | 初始化系统、生成 AES-256-GCM 密钥、克隆私有仓库 |
-| `pull` | 从仓库拉取并解密配置，还原到本地工作区 |
-| `push` | 将本地配置加密推送到仓库 |
-| `sync` | 双向同步（先拉取再推送） |
-| `status` | 查看仓库状态、工作区差异与文件清单 |
-| `diff` | 逐文件显示本地与仓库的行级差异（自动解密） |
-| `list` | 列出所有托管文件，显示本地/仓库存在状态 |
-| `dump` | 生成明文快照到临时目录，方便检查同步内容 |
-| `lang` | 切换 CLI 显示语言（zh/en） |
-| `watch` | 监听文件变化并自动同步 |
-| `env` | 管理同步环境（创建/切换/列出/删除） |
-| `agent` | 管理智能体（列出/启用/禁用/设置路径/详情） |
-| `key` | 密钥管理（导出/导入/轮换） |
-| `report` | 生成同步报告 |
-| `doctor` | 诊断并修复常见问题 |
-| `history` | 查看同步操作历史 |
-| `snapshot` | 创建/恢复/列出时间点快照 |
-| `summary` | 显示同步统计摘要 |
-| `setup` | 引导式交互初始化向导 |
-| `health` | 系统健康检查 |
-| `search` | 搜索已同步的文件 |
-| `config` | 配置导出/导入管理 |
-| `changelog` | 查看同步变更日志 |
-| `tag` | 记忆标签系统 |
-| `cleanup` | 清理过期记忆条目 |
-| `template` | 应用预设同步配置模板 |
-| `batch` | 批量执行多个命令 |
-| `completions` | 生成 shell 自动补全脚本（bash/zsh） |
-
-所有命令支持 `--agent <name>` 过滤（`lang` 除外）。
-
----
-
-## 安装
-
-```bash
-npm install -g wangchuan
-```
-
-或从源码安装：
-
-```bash
-git clone https://github.com/nicepkg/wangchuan.git
-cd wangchuan
-npm install
-npm run build
-npm link
-```
+忘川通过私有 Git 仓库加密同步你的 AI 智能体配置、记忆和技能。一条命令同步，一个守护进程保持全局最新。
 
 ---
 
 ## 快速开始
 
-### 1. 初始化
-
 ```bash
-wangchuan init --repo git@github.com:yourname/your-brain.git
-```
-
-执行后创建：
-- `~/.wangchuan/config.json` — 系统配置
-- `~/.wangchuan/master.key` — 主密钥（**请妥善保管**）
-- `~/.wangchuan/repo` — 本地仓库克隆
-
-### 2. 推送本地配置
+npm install -g wangchuan
 
-```bash
-wangchuan push -m "初始化配置"
-```
+# 1. 初始化（交互式向导）
+wangchuan init
 
-### 3. 在新环境拉取记忆
+# 2. 同步全部
+wangchuan sync
 
-```bash
-wangchuan init --repo git@github.com:yourname/your-brain.git --key /path/to/master.key
-wangchuan pull
+# 3. 启动后台守护进程
+wangchuan watch
 ```
 
-### 4. 查看同步状态
+在新机器上：
 
 ```bash
-wangchuan status
+wangchuan init --repo git@github.com:you/brain.git --key /path/to/master.key
+wangchuan sync
 ```
 
-### 5. 切换显示语言
-
-```bash
-wangchuan lang en      # 切换到英文
-wangchuan lang zh      # 切换到中文
-WANGCHUAN_LANG=en wangchuan status   # 环境变量覆盖
-```
+---
 
-### 6. 只操作指定智能体
+## 命令列表
 
-```bash
-wangchuan push --agent claude -m "更新 Claude 配置"
-wangchuan pull --agent openclaw
-wangchuan diff --agent gemini
-```
+| 命令 | 别名 | 描述 | 主要参数 |
+|------|------|------|----------|
+| `init` | — | 首次初始化（无 `--repo` 时进入交互向导） | `--repo`、`--key`、`--force` |
+| `sync` | `s` | 智能双向同步 — 日常唯一命令 | `-a, --agent`、`-n, --dry-run` |
+| `status` | `st` | 一屏总览 + 健康评分 | `-v, --verbose` |
+| `watch` | — | 后台守护进程，持续自动同步 | `-i, --interval <分钟>` |
+| `doctor` | — | 诊断 + 自动修复所有问题 | `--key-export`、`--key-rotate`、`--setup` |
+| `memory` | — | 浏览/复制智能体记忆 | `list`、`show`、`copy`、`broadcast` |
+| `env` | — | 多环境管理 | `list`、`create`、`switch`、`current`、`delete` |
+| `lang` | — | 切换显示语言 | `zh`、`en` |
 
 ---
 
 ## 支持的智能体
 
-| 智能体 | 默认路径 | 同步文件 | JSON 字段 |
-|--------|---------|---------|-----------|
-| **OpenClaw** | `~/.openclaw/workspace/` | MEMORY.md（加密）、AGENTS.md、SOUL.md | — |
-| **Claude** | `~/.claude/` | CLAUDE.md、settings.json（加密） | `.claude.json` → `mcpServers`（加密） |
-| **Gemini** | `~/.gemini/` | — | `settings.internal.json` → `security`、`model` |
-| **CodeBuddy** | `~/.codebuddy/` | MEMORY.md（加密）、CODEBUDDY.md | `mcp.json` → `mcpServers`（加密） |
-| **WorkBuddy** | `~/.workbuddy/` | MEMORY.md（加密）、IDENTITY.md、SOUL.md、USER.md（加密） | `mcp.json` → `mcpServers`（加密） |
-| **Cursor** | `~/.cursor/` | rules/（目录） | `mcp.json` → `mcpServers`（加密）、`cli-config.json` → 字段（加密） |
-| **Codex** | `~/.codex/` | MEMORY.md（加密）、instructions.md | — |
-
-每个智能体的 `workspacePath` 均可在 `~/.wangchuan/config.json` 中自定义。
-
----
-
-## 仓库结构 (v2)
+| 智能体 | 默认路径 | 同步内容 |
+|--------|---------|----------|
+| **OpenClaw** | `~/.openclaw/workspace/` | MEMORY.md（加密）、AGENTS.md、SOUL.md、IDENTITY.md、USER.md（加密）、memory/（加密） |
+| **Claude** | `~/.claude/` | CLAUDE.md、settings.json（加密）、`.claude.json` → mcpServers（加密） |
+| **Gemini** | `~/.gemini/` | `settings.internal.json` → security + model + general（加密） |
+| **CodeBuddy** | `~/.codebuddy/` | MEMORY.md（加密）、CODEBUDDY.md、mcp.json → mcpServers（加密）、settings.json → enabledPlugins（加密） |
+| **WorkBuddy** | `~/.workbuddy/` | MEMORY.md（加密）、IDENTITY.md、SOUL.md、USER.md（加密）、mcp.json → mcpServers（加密） |
+| **Cursor** | `~/.cursor/` | rules/（目录）、mcp.json → mcpServers（加密）、cli-config.json → 字段（加密） |
+| **Codex** | `~/.codex/` | AGENTS.md、instructions.md |
 
-```
-repo/
-├── shared/                        跨 agent 共享层
-│   ├── skills/                    所有 agent 的 skills 合并
-│   ├── mcp/                       各 agent 的 MCP 配置提取
-│   └── memory/SHARED.md.enc       跨 agent 共享记忆（加密）
-├── agents/
-│   ├── openclaw/
-│   │   ├── MEMORY.md.enc          永久记忆（加密）
-│   │   ├── AGENTS.md              Agent 行为准则
-│   │   └── SOUL.md                Agent 人格设定
-│   ├── claude/
-│   │   ├── CLAUDE.md              全局指令
-│   │   ├── settings.json.enc      权限/插件/模型（加密）
-│   │   └── mcpServers.json.enc    从 .claude.json 提取（加密）
-│   ├── gemini/
-│   │   └── settings-sync.json     提取的 security + model 字段
-│   ├── codebuddy/
-│   ├── workbuddy/
-│   ├── cursor/
-│   └── codex/
-```
+各智能体的 `workspacePath` 均可在 `~/.wangchuan/config.json` 中自定义。
 
 ---
 
-## 加密说明
+## 功能特性
 
-- **算法**：AES-256-GCM（认证加密，防篡改）
-- **密钥**：`~/.wangchuan/master.key`（32 字节，十六进制存储）
-- **密文格式**：`IV(12B) + AuthTag(16B) + CipherText` → Base64 编码 → `.enc` 文件
-- ⚠️ **master.key 丢失将无法解密历史配置，请做好备份！**
+### 加密
+- **AES-256-GCM** 认证加密 — 防篡改
+- 密钥存储在本地 `~/.wangchuan/master.key`（永不提交）
+- 密文格式：`IV(12B) + AuthTag(16B) + CipherText` → Base64 → `.enc`
+- 每次同步前自动扫描泄露的 token
+
+### 跨智能体共享
+- Skills 和 MCP 配置自动分发到所有智能体
+- 删除传播 — 所有智能体都删除后自动从仓库清理
+- 已有条目不会被覆盖
+
+### 多环境管理
+- 创建隔离环境：`wangchuan env create work`
+- 即时切换：`wangchuan env switch work`
+- 每个环境拥有独立的智能体配置
+
+### Watch 守护进程
+- `wangchuan watch` 持续后台同步
+- 可配置间隔：`wangchuan watch -i 10`
+- PID 单例 — 每台机器只运行一个实例
+
+### 记忆浏览
+- `wangchuan memory list` — 查看所有智能体记忆概览
+- `wangchuan memory copy openclaw claude` — 在智能体间传输记忆
+- `wangchuan memory broadcast claude` — 将记忆广播到所有智能体
+
+### 诊断修复
+- 自动发现已安装的智能体
+- 检测残留/幻影文件
+- `--key-export` / `--key-rotate` 密钥管理
+- `--setup` 生成新机器迁移命令
 
 ---
 
 ## 配置文件
 
-配置位于 `~/.wangchuan/config.json`：
+位于 `~/.wangchuan/config.json`：
 
 ```jsonc
 {
-  "repo": "git@github.com:yourname/your-brain.git",
+  "repo": "git@github.com:you/brain.git",
   "branch": "main",
   "localRepoPath": "~/.wangchuan/repo",
   "keyPath": "~/.wangchuan/master.key",
   "version": 2,
   "profiles": {
     "default": {
-      "openclaw": { "enabled": true, "workspacePath": "~/.openclaw/workspace", ... },
-      "claude":   { "enabled": true, "workspacePath": "~/.claude", ... },
-      "gemini":   { "enabled": true, "workspacePath": "~/.gemini", ... },
-      "codex":    { "enabled": true, "workspacePath": "~/.codex", ... }
+      "openclaw": { "enabled": true, "workspacePath": "~/.openclaw/workspace" },
+      "claude":   { "enabled": true, "workspacePath": "~/.claude" },
+      "gemini":   { "enabled": true, "workspacePath": "~/.gemini" }
     }
   },
   "shared": {
-    "skills": { "sources": [{ "agent": "claude", "dir": "skills/" }, ...] },
-    "mcp":    { "sources": [{ "agent": "claude", "src": ".claude.json", "field": "mcpServers" }, ...] },
-    "syncFiles": [...]
+    "skills": { "sources": [{ "agent": "claude", "dir": "skills/" }] },
+    "mcp":    { "sources": [{ "agent": "claude", "src": ".claude.json", "field": "mcpServers" }] },
+    "syncFiles": []
   }
 }
 ```
@@ -218,35 +134,27 @@ repo/
 ## 安全规范
 
 1. `master.key` 已加入 `.gitignore`，不会意外提交
-2. 推送前自动扫描明文 token（`api_key`、`sk-xxx`、`password` 等）
-3. 迁移密钥请用加密方式传输（不要通过明文邮件/IM）
+2. 同步前自动扫描明文 token（`api_key`、`sk-xxx`、`password` 等）
+3. 迁移密钥请用加密方式传输
+4. ⚠️ **master.key 丢失将无法解密历史配置，请做好备份！**
 
 ---
 
-## 项目结构
+## 安装
 
+```bash
+npm install -g wangchuan
 ```
-wangchuan/
-├── bin/wangchuan.ts          CLI 入口
-├── src/
-│   ├── core/
-│   │   ├── sync.ts           同步引擎（分发、清理、三向操作）
-│   │   ├── json-field.ts     JSON 字段级提取与合并
-│   │   ├── crypto.ts         AES-256-GCM 加解密
-│   │   ├── git.ts            simple-git 封装
-│   │   ├── config.ts         配置管理（v2 profiles + shared）
-│   │   └── migrate.ts        v1→v2 迁移（备份 + 锁 + 回滚）
-│   ├── agents/               智能体定义（每个 agent 一个文件）
-│   ├── commands/             28 个 CLI 命令
-│   ├── utils/                日志、校验、行级差异、交互提示
-│   ├── i18n.ts               国际化消息字典
-│   └── types.ts              全局类型定义
-├── skill/                    OpenClaw Skill 封装
-├── test/                     单元测试（加密、JSON 字段、同步引擎）
-└── .wangchuan/
-    └── config.example.json   配置示例（v2）
+
+从源码安装：
+
+```bash
+git clone https://github.com/nicepkg/wangchuan.git
+cd wangchuan && npm install && npm run build && npm link
 ```
 
+需要 Node.js ≥ 18.19.0。
+
 ---
 
 ## 许可证