docs: 新增 Orcha 终极架构设计（OPC 特化版）

docs/ORCHA_ARCHITECTURE_SUMMARY.md

@@ -0,0 +1,45 @@
+# Orcha 架构思想总结
+
+## 核心定调
+
+Orcha 服务端不进行内容审核，它只是一个中立的协议执行层与密码学公证人。其安全性不来源于“审查权力”，而来源于不可篡改的数学契约与去中心化的信任链。
+
+## 1. 安全基石：GPG 双验（数学契约）
+
+安全性的核心是密码学，而非服务端逻辑。
+
+- **双签机制**：每一个进入仓库的 Commit 都携带两个独立的 GPG 签名——人类 Contributor 的签名（证明所有权）与 Orcha-Bot 的签名（证明执行环境）。
+- **服务端无裁量权**：服务器无法伪造人类签名，也无法篡改已签名的 Commit。它仅仅是持有 Bot 的私钥，在规则触发时（如 CI 通过）自动执行 `git commit -S`。安全由非对称加密算法保证，而非服务器的道德。
+
+## 2. 协作安全：Agit + WS（原子锁协议）
+
+多 Agent 协作的安全性来源于严格的协议约束，防止并发冲突导致仓库腐败。
+
+- **目录级互斥锁**：通过 WebSocket 实时同步锁状态。当一个 Agent 修改特定目录时，协议强制锁定该范围，拒绝其他 Agent 的写入请求。这是一种预防性的原子安全机制，确保 Git 历史的线性与干净。
+- **Patch 原子化**：Agent 提交的是 `"patch"` 对象，服务端仅做事务性的 Apply 操作——要么完整应用，要么完全回滚。这杜绝了部分写入导致的仓库损坏风险。
+
+## 3. 身份安全：签署者模式（权责分离）
+
+Orcha-Bot 的角色是签署者（Signatory），而非审核者（Auditor）。
+
+- **人类主权**：`"Author"` 字段永远属于人类 Contributor，服务端绝不窃取署名权。
+- **Bot 见证**：`"Committer"` 和 `"Signed-off-by"` 仅代表 Orcha-Bot 见证并执行了这次合并操作。这符合 DCO（开发者原创证书）的法律要求，明确了责任归属，而非内容审查。
+- **不可抵赖**：由于双签的存在，人类不能否认自己的提交，Bot 也不能否认自己的执行。这是一种双向的、基于密码学的非抵赖性。
+
+## 4. 运行安全：最小权限原则
+
+- **无 Force Push**：Orcha-Bot 的 GitHub Token 严格禁用 `"--force"` 权限。即使服务端被入侵，也无法篡改已存在的 Git 历史。
+- **隔离执行**：AI 代码生成与 Git 操作在隔离的环境中进行，与宿主机及生产环境物理隔离，杜绝了代码逃逸风险。
+
+## 5. 最终形态：自动化公证人
+
+Orcha 服务端不是一个“管理员”，而是一个全自动的公证人办公室：
+
+1. 接收来自各方的、符合协议的 `"patch"`。
+2. 验证每个 `"patch"` 附带的数字签名是否合法。
+3. 执行预定义的、公开的原子操作（加锁、Apply、签名、推送）。
+4. 记录不可篡改的完整日志。
+
+## 总结
+
+Orcha 的安全性源于“代码即法律”（Code is Law）。服务端放弃了对内容的裁量权，转而拥抱 GPG 双签、原子锁协议和最小权限原则，用数学契约代替人工审核，构建了一个无需信任（Trustless）的 AI 协作环境。

docs/ORCHA_OPC_ARCHITECTURE.md

@@ -0,0 +1,124 @@
+# Orcha 终极架构设计（OPC 特化版）
+
+## 核心设计哲学
+
+**"Kernel Agnosticism（内核无关）" + "Human-in-the-loop via IM（人在回路）"**
+
+- **内核**：全模型自主调度，不依赖任何外部交互界面（CLI/IM/Web）。
+- **界面**：IM（飞书）作为唯一的“控制塔”，仅用于人类决策输入，不参与业务逻辑。
+- **目标**：构建一人公司（OPC）的自动化基石，实现“人在回路外，决策在指尖”。
+
+## 一、 架构全景图（逻辑分层）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     【控制平面】 Human Layer               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                  飞书 (Feishu)                      │   │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │   │
+│  │  │  审批卡片     │  │  状态推送     │  │ /approve │ │   │
+│  │  │  (Diff预览)   │◄─┤  (日志/告警)  │  │  命令    │ │   │
+│  │  └──────────────┘  └──────────────┘  └──────────┘ │   │
+│  └─────────────────────────────────────────────────────┘   │
+│              ▲ Event (Click/Command)          │ Callback   │
+└──────────────┼──────────────────────────────────┼──────────┘
+               │                                 │
+┌──────────────┼──────────────────────────────────┼──────────┐
+│              ▼                                 ▼          │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                  【调度平面】 Brain Layer           │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │         AiDrivenCycleround (Scheduler)      │   │  │
+│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │   │  │
+│  │  │  │ Observer │  │ Planner │  │   Worker    │  │   │  │
+│  │  │  └─────────┘  └─────────┘  └─────────────┘  │   │  │
+│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │   │  │
+│  │  │  │ Tester  │  │ Reviewer│  │   Fixer     │  │   │  │
+│  │  │  └─────────┘  └─────────┘  └─────────────┘  │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │              │ Tool Calling / Decision             │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │         模型资源中心 (Model Registry)        │   │  │
+│  │  │  models.yaml (强项/余量/成本/优先级)         │◄───┘  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  └─────────────────────────────────────────────────────┘  │
+│              │ Execute (Containerized)                  │
+┌──────────────┼──────────────────────────────────┼──────────┐
+│              ▼                                  ▼          │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                  【执行平面】 Runtime Layer          │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │         TRAE 云端 Workspace (Linux)         │   │  │
+│  │  │  ┌──────────────┐  ┌───────────────────┐   │   │  │
+│  │  │  │ GitWorktree  │  │ Shell/Cargo/Node  │   │   │  │
+│  │  │  │ (隔离环境)    │  │ (编译/测试/执行)   │   │   │  │
+│  │  │  └──────────────┘  └───────────────────┘   │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 二、 核心模块详解
+
+### 1. 模型资源中心 (Model Registry)
+
+- **载体**：`models.yaml`（静态配置）+ 内存状态（动态余量）。
+- **核心字段**：
+  - `strengths`: 模型强项列表（如 `"code_gen"`、`"security_audit"`）。
+  - `quota`: 总量、已用量、RPM 限制、单位成本。
+  - `priority`: 强项匹配优先级。
+- **作用**：为 Scheduler 提供“地图”，是实现成本感知、余量感知调度的基础。
+
+### 2. 调度内核 (AiDrivenCycleround)
+
+- **本质**：Meta-Agent（Agent 的 Agent）。
+- **决策逻辑**：
+  1. **任务拆解**：将用户意图拆解为 Sub-Agent 调用序列。
+  2. **模型甄选**：查询 Model Registry，根据 `strengths` 匹配 -> `quota` 过滤 -> `priority`/`cost` 打分，选出最优模型。
+  3. **异常处理**：若 Sub-Agent 执行失败，自主决定是否调用 Fixer 或回滚。
+- **自主性开关**：
+  - `SAFE_MODE=false`: 全自主运行，无需审批。
+  - `SAFE_MODE=true`: 关键操作（Write/Delete/Shell）触发 Approval Flow。
+
+### 3. 审批流 (Approval Flow)
+
+- **双通道触发**：
+  - **Feishu Card**: 原生交互，点击按钮回调 `type:11`。
+  - **CLI/Feishu Cmd**: `/approve <task_id>`。
+- **状态同步**：无论哪种通道触发，均更新内存中的 `PendingTask` 状态，并反向更新 Feishu 卡片（变为只读/已批准状态）。
+- **降级策略**：若无卡片环境，CLI 命令依然有效，保证内核可用性。
+
+### 4. 执行环境 (TRAE Cloud)
+
+- **GitWorktree**：核心安全机制，确保 AI 在主分支外操作，永不污染源仓库。
+- **隔离性**：TRAE 云端容器提供纯净的编译和运行环境，不受本地环境影响。
+
+## 三、 关键交互流程 (Example)
+
+**场景**：用户 @Orcha "给 bit-torch 加 reverse_string 函数"
+
+1. **入口**：飞书消息 -> `feishu_adapter` -> Core。
+2. **调度**：
+   - Scheduler 识别需 `code_gen`。
+   - 查 `models.yaml`：DeepSeek 强项匹配，但余量仅剩 5%。
+   - 决策：降级调用 `qwen-2.5-coder-7b-local`（成本低，余量无限）。
+3. **执行**：
+   - Worker (Qwen) 在 TRAE 云端 Worktree 中写入代码。
+   - Tester 运行 `cargo test`（通过）。
+4. **审批 (Safe Mode)**：
+   - Core 生成 Diff，通过 Feishu Adapter 发送可更新卡片。
+   - 用户操作 A：点击卡片按钮 -> WS 回调 -> Core 唤醒。
+   - 用户操作 B：输入 `/approve xxx` -> Command Parser -> Core 唤醒 -> 卡片自动更新为“已批准”。
+5. **收尾**：Reviewer 检查 -> Git Push -> 飞书推送 "PR #123 Created"。
+
+## 四、 为何这是 OPC 的唯一路径
+
+1. **极致杠杆**：通过 Model Registry，将不同模型的“智力”视为可编程资源，像水电一样按需调用。
+2. **成本可控**：余量感知调度防止预算失控，是商业化的前提。
+3. **异步协同**：IM 作为 UI，允许人类在碎片化时间介入，无需时刻守候终端，真正释放人力。
+4. **鲁棒性强**：CLI 与 IM 双通道审批，确保系统在任何环境下均可运行。
+5. **生态对齐**：全栈字节系（TRAE + Feishu + VolcEngine），符合比赛语境，降低集成摩擦。
+
+## 五、 总结
+
+Orcha 不是一个 ChatBot，而是一个异步的、成本感知的、具备自我纠错能力的分布式任务调度系统。它将 IM 视为人类的“感官延伸”，将云端视为“躯干”，将模型调度视为“大脑”。维护 `models.yaml` 的准确性和 Scheduler 的决策智慧，是 OPC 持有者唯一的核心工作。