diff --git a/README.md b/README.md
index f06f55f..7c6ca16 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,10 @@
[](https://www.rust-lang.org)
[](https://github.com/New1Direction/korg)
+
+ English · 简体中文 · 繁體中文
+
+
---
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..c195ccc
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,209 @@
+# korg
+
+**一个为自主 AI 智能体打造的、按因果排序、可回退的事件账本。**
+*你的 AI 智能体走的每一步,都记进一本可独立验证的哈希链账本——防篡改、零信任、不用区块链。*
+
+[](https://opensource.org/licenses/MIT)
+[](https://www.rust-lang.org)
+[](https://github.com/New1Direction/korg)
+
+
+ English · 简体中文 · 繁體中文
+
+
+---
+
+
+
+---
+
+> AI 智能体是黑盒。出错时,你无法调试;成功时,你无法复现;做错事时,你无法撤销。
+>
+> **Korg 解决这个问题。**
+
+---
+
+## Korg 做什么
+
+> [!NOTE]
+> **通用接入模式:**
+> korg v1 是一个可通过 MCP 调用的审计接收端。任何兼容 MCP 的编程智能体(Claude Code、Codex 等)都可以调用 korg 的工具,把自己的会话记录成一本按因果相连、可重放、可回退的账本。需要让该智能体记录自己的动作——通常通过系统提示词或 MCP 服务配置实现。无需智能体配合的完全被动审计已列入后续版本的路线图。
+
+> [!WARNING]
+> **信任边界与部署范围:**
+> korg v1 严格面向本地、单用户的工作区。多租户与联网部署所需的加密认证与权限边界尚未提供。在不受信任或公开的网络上运行该服务,会暴露工作区的读写权限。
+
+Korg 是一个**认知管理程序(cognitive hypervisor)**——一个位于你的 AI 智能体之下、管控它们每一个决策的运行时层。
+
+它不替代你的 LLM,而是管控 LLM 所做的事。
+
+```
+基础模型 → 预测、建议、生成
+────────────────────────────────────────────────────────────
+Korg 认知运行时 → 调度、校验、隔离、对账、重放、自愈、治理
+```
+
+每一个智能体动作都会:
+- **追加**到一本不可变、带密码学签名的账本
+- 用混合逻辑时钟(HLC)**排序**(因果、确定、全局一致)
+- **可重放**——在历史上任意一点重建出精确的状态
+- **可逆**——回退、分叉,或为任意决策开一条新分支
+
+---
+
+## 试试时间旅行演示
+
+运行内置的沙箱演示,亲眼看看“认知时间旅行”:它会建一个临时工作区(含一个有 bug 的 Python 脚本),让一个模拟的编程智能体做出错误改动,捕获测试失败,把工作区和账本回退到改动之前,再推测性地提交正确的修复:
+
+```bash
+cargo run -- demo
+```
+
+你会看到完整的彩色时间旅行过程(完整输出见[英文 README](README.md)):错误路径 → 回退到 seq 391 → 沿正确路径重新推进 → 测试通过。
+
+> *没有别的 AI 智能体运行时能做到这一点。*
+
+---
+
+## 核心架构
+
+Korg 建立在那些让数据库与操作系统可靠的理论基础之上——这是首次把它们用于 AI 认知。
+
+| 不变量 | 含义 |
+|:---|:---|
+| **仅追加 WAL** | 每个认知事件都是一条账本记录。只追加,绝不就地修改——像数据库的 WAL,但记录的是 AI 的“思考”。 |
+| **HLC 因果排序** | 混合逻辑时钟保证全局一致、按因果排序的事件流——即使跨分布式集群工作者也成立。 |
+| **确定性重放** | 任意一次行动都能从账本逐字节重放。相同输入,每次都得到相同输出。 |
+| **推测性分支** | 把执行分叉成多条并行的假设路径,提交前先预览,可随意丢弃。 |
+| **执行检查点** | 快照整个运行时状态(账本偏移、投影视图、租约表、工作区树),O(1) 还原。 |
+| **微自愈** | 瞬时故障(锁冲突、过期状态)在副作用层自动修复,并留下完整的重试审计轨迹。 |
+| **语义治理** | 集群动作以 BERT 嵌入的余弦相似度校验——靠语义对齐,而非关键字匹配。 |
+
+---
+
+## 快速开始
+
+### 从源码构建
+
+该 crate 暂未发布到 crates.io,请从源码安装:
+
+```bash
+git clone https://github.com/New1Direction/korg
+cd korg
+cargo build --release
+./target/release/korg-tui --help
+```
+
+> 在中国大陆?用 cargo 国内镜像更快——见 korgex 文档的[在中国安装](https://korgex-docs.pages.dev/zh-CN/docs/install-china)(rsproxy.cn / 清华)。
+
+### Python 桥接(供 korgex / korgchat 使用)
+
+```bash
+cd crates/korg-bridge
+maturin develop # 把 PyO3 扩展构建进当前 venv
+python3 -c "import korg_bridge; print(korg_bridge.__version__)"
+```
+
+### 跑你的第一个 campaign
+
+```bash
+# 交互式 TUI 仪表盘
+korg campaign --tui --prompt "把鉴权层重构为使用 JWT"
+
+# localhost:8080 的 Web 驾驶舱
+korg campaign --web --prompt "优化数据库连接池"
+
+# 纯自主目标模式
+korg goal "为 src/parser.rs 编写并验证一整套测试"
+
+# 预览但不提交(推测性沙箱)
+korg run --preview "重构主事件循环"
+```
+
+### 回退与分叉
+
+```bash
+korg rewind --seq 4 # 回退到指定的账本序号
+korg checkpoints list # 列出当前会话的所有检查点
+korg checkpoints restore --id # 从指定检查点还原
+```
+
+---
+
+## 认知模式
+
+Korg 会按任务复杂度切换智能层级。模式只通过能力解析器(capability resolver)切换,每次切换都会记进账本。
+
+| 模式 | 适用场景 |
+|:---|:---|
+| `instant` | 极低延迟。跳过协商,乐观执行。 |
+| `balanced` | 默认。结构化的多轮合约协商。 |
+| `heavy` | 深度多智能体研议,多轮评估。 |
+| `research` | 广度发散探索,跨所有 crate 扫描语义索引。 |
+| `recovery` | 安全回滚模式,每次变更前先建检查点。 |
+| `autonomous` | 完全目标模式,自我导航并自动重新规划。 |
+| `heavy-consciousness` | 最大深度,注入完整的 HeavyConsciousness 上下文。 |
+
+---
+
+## 为什么需要 Korg
+
+如今的 AI 编程智能体是概率黑盒。它们:
+- **无法重放**——同样的提示词,每次输出都不同
+- **无法回退**——一个错误动作,你就得手动去 diff git 历史
+- **无法审计**——没有任何关于智能体决定了什么、为什么这么决定的记录
+- **无法治理**——没有办法在运行时设定策略边界
+
+Korg 对待 AI 认知的方式,就像管理程序对待算力、Git 对待代码:
+
+> **不在账本里,就等于没发生过。**
+
+---
+
+## 对比
+
+| 能力 | Korg | LangChain / LangGraph | CrewAI | 普通 CLI 智能体 |
+|:---|:---:|:---:|:---:|:---:|
+| 确定性重放 | ✅ | ❌ | ❌ | ❌ |
+| HLC 因果排序 | ✅ | ❌ | ❌ | ❌ |
+| 回退执行 | ✅ | ❌ | ❌ | ❌ |
+| 推测性分支 | ✅ | ❌ | ❌ | ❌ |
+| 执行检查点 | ✅ | ❌ | ❌ | ❌ |
+| 密码学审计轨迹 | ✅ | ❌ | ❌ | ❌ |
+| 微自愈 | ✅ | ❌ | ❌ | ❌ |
+| 不挑模型 | ✅ | ✅ | ✅ | ✅ |
+
+> **Korg 不是一个智能体框架,而是跑在所有框架之下的治理内核。**
+
+---
+
+## 技术栈
+
+| 组件 | 技术 |
+|:---|:---|
+| 核心运行时 | Rust 2021、Tokio 异步 |
+| 账本排序 | 混合逻辑时钟(HLC) |
+| 工作区快照 | Git Merkle 树(`write-tree`/`read-tree`,O(1) 还原) |
+| 密码学证明 | Ed25519(ed25519-dalek) |
+| 语义治理 | BERT 余弦相似度(Candle / Hugging Face) |
+| TUI 仪表盘 | Ratatui + Crossterm |
+| Web 驾驶舱 | Axum + SSE |
+| 语法高亮 | Syntect + tree-sitter |
+
+---
+
+## 状态
+
+Korg 正在积极开发中。当前测试覆盖:**175 个测试,0 失败**(8 个 crate 共 162 个 cargo 测试 + PyO3 桥接的 13 个 pytest)。完整的功能清单与路线图见[英文 README](README.md)。
+
+---
+
+## 许可证
+
+在 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 中任选其一。
+
+---
+
+
+ 用 Rust 构建。由不变量治理。没有黑盒。
+
diff --git a/README.zh-TW.md b/README.zh-TW.md
new file mode 100644
index 0000000..b8d74e7
--- /dev/null
+++ b/README.zh-TW.md
@@ -0,0 +1,209 @@
+# korg
+
+**一個為自主 AI 代理打造的、按因果排序、可回退的事件帳本。**
+*你的 AI 代理走的每一步,都記進一本可獨立驗證的雜湊鏈帳本——防竄改、零信任、不用區塊鏈。*
+
+[](https://opensource.org/licenses/MIT)
+[](https://www.rust-lang.org)
+[](https://github.com/New1Direction/korg)
+
+
+ English · 简体中文 · 繁體中文
+
+
+---
+
+
+
+---
+
+> AI 代理是黑盒。出錯時,你無法除錯;成功時,你無法重現;做錯事時,你無法復原。
+>
+> **Korg 解決這個問題。**
+
+---
+
+## Korg 做什麼
+
+> [!NOTE]
+> **通用接入模式:**
+> korg v1 是一個可透過 MCP 呼叫的稽核接收端。任何相容 MCP 的編程代理(Claude Code、Codex 等)都可以呼叫 korg 的工具,把自己的工作階段記錄成一本按因果相連、可重放、可回退的帳本。需要讓該代理記錄自己的動作——通常透過系統提示詞或 MCP 伺服器設定實現。無需代理配合的完全被動稽核已列入後續版本的路線圖。
+
+> [!WARNING]
+> **信任邊界與部署範圍:**
+> korg v1 嚴格面向本機、單一使用者的工作區。多租戶與聯網部署所需的加密認證與權限邊界尚未提供。在不受信任或公開的網路上執行該服務,會暴露工作區的讀寫權限。
+
+Korg 是一個**認知管理程式(cognitive hypervisor)**——一個位於你的 AI 代理之下、管控它們每一個決策的執行時層。
+
+它不取代你的 LLM,而是管控 LLM 所做的事。
+
+```
+基礎模型 → 預測、建議、生成
+────────────────────────────────────────────────────────────
+Korg 認知執行時 → 排程、校驗、隔離、對帳、重放、自癒、治理
+```
+
+每一個代理動作都會:
+- **追加**到一本不可變、帶密碼學簽章的帳本
+- 用混合邏輯時鐘(HLC)**排序**(因果、確定、全域一致)
+- **可重放**——在歷史上任意一點重建出精確的狀態
+- **可逆**——回退、分叉,或為任意決策開一條新分支
+
+---
+
+## 試試時間旅行示範
+
+執行內建的沙箱示範,親眼看看「認知時間旅行」:它會建一個臨時工作區(含一個有 bug 的 Python 指令稿),讓一個模擬的編程代理做出錯誤改動,捕捉測試失敗,把工作區和帳本回退到改動之前,再推測性地提交正確的修復:
+
+```bash
+cargo run -- demo
+```
+
+你會看到完整的彩色時間旅行過程(完整輸出見[英文 README](README.md)):錯誤路徑 → 回退到 seq 391 → 沿正確路徑重新推進 → 測試通過。
+
+> *沒有別的 AI 代理執行時能做到這一點。*
+
+---
+
+## 核心架構
+
+Korg 建立在那些讓資料庫與作業系統可靠的理論基礎之上——這是首次把它們用於 AI 認知。
+
+| 不變量 | 含義 |
+|:---|:---|
+| **僅追加 WAL** | 每個認知事件都是一條帳本紀錄。只追加,絕不就地修改——像資料庫的 WAL,但記錄的是 AI 的「思考」。 |
+| **HLC 因果排序** | 混合邏輯時鐘保證全域一致、按因果排序的事件流——即使跨分散式叢集工作者也成立。 |
+| **確定性重放** | 任意一次行動都能從帳本逐位元組重放。相同輸入,每次都得到相同輸出。 |
+| **推測性分支** | 把執行分叉成多條並行的假設路徑,提交前先預覽,可隨意丟棄。 |
+| **執行檢查點** | 快照整個執行時狀態(帳本偏移、投影檢視、租約表、工作區樹),O(1) 還原。 |
+| **微自癒** | 瞬時故障(鎖衝突、過期狀態)在副作用層自動修復,並留下完整的重試稽核軌跡。 |
+| **語義治理** | 叢集動作以 BERT 嵌入的餘弦相似度校驗——靠語義對齊,而非關鍵字比對。 |
+
+---
+
+## 快速開始
+
+### 從原始碼建置
+
+該 crate 暫未發佈到 crates.io,請從原始碼安裝:
+
+```bash
+git clone https://github.com/New1Direction/korg
+cd korg
+cargo build --release
+./target/release/korg-tui --help
+```
+
+> 在中國大陸?用 cargo 國內鏡像更快——見 korgex 文件的[在中國安裝](https://korgex-docs.pages.dev/zh-TW/docs/install-china)(rsproxy.cn / 清華)。
+
+### Python 橋接(供 korgex / korgchat 使用)
+
+```bash
+cd crates/korg-bridge
+maturin develop # 把 PyO3 擴充建置進當前 venv
+python3 -c "import korg_bridge; print(korg_bridge.__version__)"
+```
+
+### 跑你的第一個 campaign
+
+```bash
+# 互動式 TUI 儀表板
+korg campaign --tui --prompt "把驗證層重構為使用 JWT"
+
+# localhost:8080 的 Web 駕駛艙
+korg campaign --web --prompt "最佳化資料庫連線池"
+
+# 純自主目標模式
+korg goal "為 src/parser.rs 編寫並驗證一整套測試"
+
+# 預覽但不提交(推測性沙箱)
+korg run --preview "重構主事件迴圈"
+```
+
+### 回退與分叉
+
+```bash
+korg rewind --seq 4 # 回退到指定的帳本序號
+korg checkpoints list # 列出當前工作階段的所有檢查點
+korg checkpoints restore --id # 從指定檢查點還原
+```
+
+---
+
+## 認知模式
+
+Korg 會依任務複雜度切換智慧層級。模式只透過能力解析器(capability resolver)切換,每次切換都會記進帳本。
+
+| 模式 | 適用場景 |
+|:---|:---|
+| `instant` | 極低延遲。跳過協商,樂觀執行。 |
+| `balanced` | 預設。結構化的多輪合約協商。 |
+| `heavy` | 深度多代理研議,多輪評估。 |
+| `research` | 廣度發散探索,跨所有 crate 掃描語義索引。 |
+| `recovery` | 安全回滾模式,每次變更前先建檢查點。 |
+| `autonomous` | 完全目標模式,自我導航並自動重新規劃。 |
+| `heavy-consciousness` | 最大深度,注入完整的 HeavyConsciousness 上下文。 |
+
+---
+
+## 為什麼需要 Korg
+
+如今的 AI 編程代理是機率黑盒。它們:
+- **無法重放**——同樣的提示詞,每次輸出都不同
+- **無法回退**——一個錯誤動作,你就得手動去 diff git 歷史
+- **無法稽核**——沒有任何關於代理決定了什麼、為什麼這麼決定的紀錄
+- **無法治理**——沒有辦法在執行時設定策略邊界
+
+Korg 對待 AI 認知的方式,就像管理程式對待算力、Git 對待程式碼:
+
+> **不在帳本裡,就等於沒發生過。**
+
+---
+
+## 對比
+
+| 能力 | Korg | LangChain / LangGraph | CrewAI | 一般 CLI 代理 |
+|:---|:---:|:---:|:---:|:---:|
+| 確定性重放 | ✅ | ❌ | ❌ | ❌ |
+| HLC 因果排序 | ✅ | ❌ | ❌ | ❌ |
+| 回退執行 | ✅ | ❌ | ❌ | ❌ |
+| 推測性分支 | ✅ | ❌ | ❌ | ❌ |
+| 執行檢查點 | ✅ | ❌ | ❌ | ❌ |
+| 密碼學稽核軌跡 | ✅ | ❌ | ❌ | ❌ |
+| 微自癒 | ✅ | ❌ | ❌ | ❌ |
+| 不挑模型 | ✅ | ✅ | ✅ | ✅ |
+
+> **Korg 不是一個代理框架,而是跑在所有框架之下的治理核心。**
+
+---
+
+## 技術堆疊
+
+| 元件 | 技術 |
+|:---|:---|
+| 核心執行時 | Rust 2021、Tokio 非同步 |
+| 帳本排序 | 混合邏輯時鐘(HLC) |
+| 工作區快照 | Git Merkle 樹(`write-tree`/`read-tree`,O(1) 還原) |
+| 密碼學證明 | Ed25519(ed25519-dalek) |
+| 語義治理 | BERT 餘弦相似度(Candle / Hugging Face) |
+| TUI 儀表板 | Ratatui + Crossterm |
+| Web 駕駛艙 | Axum + SSE |
+| 語法突顯 | Syntect + tree-sitter |
+
+---
+
+## 狀態
+
+Korg 正在積極開發中。當前測試覆蓋:**175 個測試,0 失敗**(8 個 crate 共 162 個 cargo 測試 + PyO3 橋接的 13 個 pytest)。完整的功能清單與路線圖見[英文 README](README.md)。
+
+---
+
+## 授權
+
+在 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 中任選其一。
+
+---
+
+
+ 用 Rust 建置。由不變量治理。沒有黑盒。
+