From 6e4f328f14c1d16c95f8cb77db94087236a2bb78 Mon Sep 17 00:00:00 2001 From: Ink-dark <209977110+Ink-dark@users.noreply.github.com> Date: Thu, 9 Jul 2026 02:40:02 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Orcha=20?= =?UTF-8?q?=E7=BB=88=E6=9E=81=E6=9E=B6=E6=9E=84=E8=AE=BE=E8=AE=A1=EF=BC=88?= =?UTF-8?q?OPC=20=E7=89=B9=E5=8C=96=E7=89=88=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 描述三层架构（控制/调度/执行平面）、Model Registry、 AiDrivenCycleround 调度内核、双通道审批流及 OPC 设计哲学。 --- docs/ORCHA_OPC_ARCHITECTURE.md | 124 +++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 docs/ORCHA_OPC_ARCHITECTURE.md diff --git a/docs/ORCHA_OPC_ARCHITECTURE.md b/docs/ORCHA_OPC_ARCHITECTURE.md new file mode 100644 index 0000000..2dd9806 --- /dev/null +++ b/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 `。 +- **状态同步**：无论哪种通道触发，均更新内存中的 `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 持有者唯一的核心工作。 From bf166f02052d43ac3fab7a83aa8c25f2a3430e7b Mon Sep 17 00:00:00 2001 From: Ink-dark Date: Thu, 9 Jul 2026 03:04:37 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Orcha=20?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=80=9D=E6=83=B3=E6=80=BB=E7=BB=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ORCHA_ARCHITECTURE_SUMMARY.md | 45 ++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/ORCHA_ARCHITECTURE_SUMMARY.md diff --git a/docs/ORCHA_ARCHITECTURE_SUMMARY.md b/docs/ORCHA_ARCHITECTURE_SUMMARY.md new file mode 100644 index 0000000..a63f791 --- /dev/null +++ b/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 协作环境。