文档: 设计文档入库与构建配套收尾

- 云化两设计文档入库(devflow-core 抽取三步收口/云化架构 html) - 看板销账: T1-T4 逐件附验收 - D4 工具 schema 空 description 清理(渐进披露配套,~10KB/轮) - 换装脚本验证修复: 安装后装机 exe 版本核对,防 NSIS 静默失败误报成功 - capabilities/锁文件随批
2026-10-26 01:36:55 +08:00
parent d97cbb4439
commit 070223baa5
7 changed files with 236 additions and 15 deletions
@@ -0,0 +1,64 @@
+# devflow-core 抽取设计（云化阶段2）
+
+> 任务 711e1390 · 2026-10-22 · 勘察依据：workspace 9 个 crate Cargo.toml 实测
+
+## 一、现状 crate 依赖图（实测）
+
+```
+                    df-types (零依赖: serde/thiserror/chrono/uuid)
+                   ┌────┴──────────────────────┐
+              df-ai-core                   df-workflow
+          (零tauri, trait层)          (DAG/条件引擎, 仅依赖df-types)
+                   │                             │
+              df-storage ←──df-ai─────┐     df-nodes ──┐
+        (rusqlite+keyring,      (reqwest流式)  (聚合5crate) │
+         依赖df-types/df-ai-core)     │              │
+                   └──────┬───────────┴──────────────┘
+                          ▼
+                     src-tauri (Tauri 壳, 68 IPC commands)
+
+  隧道链: df-tunnel(出站WS) → df-relay(云端中继镜像) → df-im-gateway(IM适配)
+  工具链: df-execute(零依赖) / df-mcp / df-ideas / df-project(依赖df-types)
+```
+
+## 二、核心发现：devflow-core 已基本存在，无需「抽取」只需「收口」
+
+关键事实：**UI 无关的 crate 已经全部独立**——df-types/df-ai-core/df-workflow/df-storage/df-ai/df-nodes/df-project/df-execute/df-tunnel 均零 tauri 依赖，tauri 只在 src-tauri 壳层。昨天的「抽取」假设（需要从 8-crate 里剥离 UI 耦合）不成立，工作量大幅下降。
+
+## 三、设计（三步收口，非重构）
+
+### S1. 虚拟 target：workspace 内定义 `devflow-core` 集合（0.5 天）
+不建新 crate，先以约定划界：`crates/df-{types,ai-core,workflow,storage,ai,nodes,project,execute}` = core 集合。云端服务直接 path 依赖这组 crate。**零代码改动**。
+
+### S2. 存储层 trait 化（2-3 天，唯一实质改造）
+- 现状：df-storage 直用 rusqlite（bundled），SQL 内嵌
+- 改造：定义 `StorageProvider` trait（项目/任务/工作流/知识 CRUD 切面），SQLite 为默认实现；PostgreSQL 实现放独立 `df-storage-pg`（feature-gated，云端服务才编译）
+- 保留双库分歧模式（devflow.db / devflow-dev.db 的 cfg! 分支语义）
+- 风险：rusqlite 与 sqlx-tokio-postgres 的异步模型差异 → trait 方法全部 async（workspace 已有 async-trait）
+
+### S3. AI Provider 双模式（1 天）
+- df-ai/df-ai-core 已是 trait 层（reqwest 直连，key 本机）——天然支持云端托管：新增 `RemoteProvider` 实现（key 由 df-cloud-server 下发），编译期 feature 切换，个人版行为零变更
+
+### 云端落地形态（阶段2 末期）
+- `df-cloud-server`：新 crate（或独立仓），path 依赖 core 集合 + df-storage-pg，Axum/actix 暴露 HTTP+WS，部署同主机 Nginx 后
+- 复用 df-tunnel 协议与 u-relay 管道层，拓扑不变
+
+## 四、迁移步骤
+
+1. S1 约定划界 + `cargo check` 全绿验证（不动代码）
+2. S2 StorageProvider trait 引入，SQLite 实现先行，桌面端切到 trait 调用（行为零变更，IPC 68 commands 不动）
+3. df-storage-pg 新 crate + 集成测试（本地 docker postgres）
+4. S3 RemoteProvider feature
+5. df-cloud-server 骨架（healthz + 只读任务查询先行）
+
+## 五、风险 Top3
+
+| 风险 | 缓解 |
+|---|---|
+| rusqlite 同步 API vs PG 异步驱动的 trait 撕裂 | trait 全 async + SQLite 实现内 spawn_blocking |
+| df-storage 依赖 df-ai-core（ModelConfig 反序列化）造成边界混杂 | 接受（同属 core 集合，不跨集合） |
+| 与阶段1 联调互踩 src-tauri | S2 改动收敛在 df-storage 内部 + 调用方，分批提交攒批 |
+
+## 六、工作量总估
+
+S1 0.5d + S2 2-3d + S3 1d + cloud-server 骨架 1-2d ≈ **5-7 天**（远低于原「抽取重构」预期）。
@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DevFlow 云化架构 — 2026-10-21</title>
+<style>
+  :root{
+    --bg:#0d1117; --bg2:#161b22; --border:#30363d; --text:#e6edf3; --muted:#8b949e;
+    --blue:#58a6ff; --green:#3fb950; --orange:#d29922; --red:#f85149; --purple:#bc8cff; --pink:#ff7b72;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:var(--bg);color:var(--text);font-family:"JetBrains Mono","Cascadia Code",Consolas,"Microsoft YaHei",monospace;font-size:14px;line-height:1.7;padding:32px 16px}
+  .wrap{max-width:1080px;margin:0 auto}
+  h1{font-size:26px;margin-bottom:4px}
+  .meta{color:var(--muted);font-size:12px;margin-bottom:28px}
+  h2{font-size:18px;margin:34px 0 14px;padding-bottom:8px;border-bottom:1px solid var(--border);color:var(--blue)}
+  h3{font-size:15px;margin:20px 0 10px;color:var(--purple)}
+  .card{background:var(--bg2);border:1px solid var(--border);border-radius:10px;padding:18px 20px;margin:12px 0}
+  .tag{display:inline-block;padding:1px 9px;border-radius:20px;font-size:12px;margin-right:6px;border:1px solid}
+  .t-blue{color:var(--blue);border-color:var(--blue);background:rgba(88,166,255,.1)}
+  .t-green{color:var(--green);border-color:var(--green);background:rgba(63,185,80,.1)}
+  .t-orange{color:var(--orange);border-color:var(--orange);background:rgba(210,153,34,.1)}
+  .t-red{color:var(--red);border-color:var(--red);background:rgba(248,81,73,.1)}
+  .t-purple{color:var(--purple);border-color:var(--purple);background:rgba(188,140,255,.1)}
+  table{width:100%;border-collapse:collapse;margin:10px 0;font-size:13px}
+  th,td{border:1px solid var(--border);padding:8px 12px;text-align:left;vertical-align:top}
+  th{background:var(--bg2);color:var(--muted);font-weight:600}
+  pre{background:var(--bg2);border:1px solid var(--border);border-radius:10px;padding:20px;overflow-x:auto;font-size:12.5px;line-height:1.55}
+  .ascii{color:var(--green)}
+  .ascii .cloud{color:var(--blue)}
+  ul{margin:8px 0 8px 22px}
+  li{margin:4px 0}
+  .warn{border-left:3px solid var(--orange);padding-left:14px;color:var(--orange);font-size:13px;margin:10px 0}
+  .ok{color:var(--green)} .no{color:var(--red)} .hl{color:var(--blue)}
+  .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:12px}
+  .phase{border-top:3px solid var(--border)}
+  .p1{border-top-color:var(--green)} .p2{border-top-color:var(--orange)} .p3{border-top-color:var(--purple)}
+  code{background:#21262d;padding:1px 6px;border-radius:4px;font-size:12.5px;color:var(--pink)}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<h1>DevFlow 云化架构方案</h1>
+<div class="meta">拍板日期 2026-10-21 · 阶段1 已在飞书实机闭环验证 · 状态源：任务 711e1390 / 6e13f49b</div>
+
+<h2>一、核心决策（已拍板）</h2>
+<div class="card">
+  <ul>
+    <li><span class="tag t-blue">决策1</span><b>中继不新建</b>：复用生产 <code>u-relay</code>（:9180，纯中继零改动），df-im-gateway 以 <span class="hl">WS Commander</span> 身份接入</li>
+    <li><span class="tag t-blue">决策2</span><b>df-im-gateway 走方案 A</b>：先落在 devflow workspace 当第 9 个 crate，四端全通后再拆独立仓（避免模块 vs 实际代码脱节坑）</li>
+    <li><span class="tag t-blue">决策3</span><b>云端零业务逻辑零落盘</b>：任务/AI对话/审批状态全留桌面端 SQLite；AI Provider key 不上云，本机直连</li>
+    <li><span class="tag t-blue">决策4</span><b>语言对齐 Rust</b>：复用 df-tunnel 类型与 systemd 原子切换发布模式（publish-u-relay 同款）</li>
+  </ul>
+</div>
+
+<h2>二、部署拓扑总览</h2>
+<pre><span class="ascii">  用户四端                ┌─────────────────── 云端（已有云主机复用，不新购）──────────────────┐
+  ┌────────┐             │                                                                 │
+  │ 飞书   │──WS 长连接──┼──▶ ┌─────────────────────────────┐                              │
+  │ 钉钉   │─Stream Mode─┼──▶ │ <span class="cloud">df-im-gateway</span> (Rust, 新增)   │                              │
+  │ 企微   │──WS 长连接──┼──▶ │ · 四端协议适配(验签/AES/卡片)  │                              │
+  │ Web    │─HTTPS/WSS───┼──▶ │ · WS Commander 身份          │                              │
+  └────────┘             │    │ · 审批转发                    │                              │
+                         │    └────────────┬────────────────┘                              │
+                         │                 │ df-tunnel 协议                                │
+  <span class="cloud">u-relay :9180</span>  ◀──────┼─────────────────┘  (纯中继：WS 长连接管理/路由/Commander 注册表)   │
+                         │                                                                 │
+                         │    Nginx :443 (TLS 终结 + 反代, 后续挂 df-cloud-server 用)         │
+                         │                                                                 │
+                         └────────┬──────────────────────────────┬──────────────────────────┘
+                                  │ 出站 WS（穿透 NAT）             │ 出站 WS
+                                  ▼                              ▼
+                   ┌── 用户本机 ─────────────────────────────────────────────────┐
+                   │  DevFlow 桌面端 (Tauri 2, 唯一执行引擎 + 状态源)              │
+                   │  · AI Provider 直连 (GLM/DeepSeek, key 本机)                 │
+                   │  · SQLite (任务/对话/审批 全量状态)                           │
+                   │  · 8-crate workspace (+未来第9 crate df-im-gateway)          │
+                   └─────────────────────────────────────────────────────────────┘</span></pre>
+
+<h2>三、数据流</h2>
+<table>
+<tr><th>方向</th><th>路径</th><th>用途</th></tr>
+<tr><td>下行指令</td><td>IM/Web → df-im-gateway → u-relay → 桌面端</td><td>发消息 / 审批 / 停止</td></tr>
+<tr><td>上行事件</td><td>桌面端 → u-relay → df-im-gateway → 各端</td><td>流式回复 / 状态广播</td></tr>
+</table>
+<div class="warn">⚠ 桌面端全程<b>主动出站</b>，不开任何入站端口——NAT 友好，家里/公司网络都能用；云端被攻破也拿不到业务数据（无状态管道）。</div>
+
+<h2>四、阶段路线</h2>
+<div class="grid">
+  <div class="card phase p1">
+    <h3 style="margin-top:0">阶段1 · IM 远程接入 <span class="tag t-green">进行中·飞书实机</span></h3>
+    <ul>
+      <li>飞书单端 E2E 闭环（握手→事件→卡片流式→审批回调→流式回复）——<span class="ok">代码已全落地，实机验证中</span></li>
+      <li>df-im-gateway 作为 workspace 第 9 crate 承载</li>
+      <li>钉钉/企微/Web = <span class="no">后续扩展，不阻塞</span></li>
+      <li>唯一动 u-relay 的点：Commander 身份注册（配置级）</li>
+    </ul>
+  </div>
+  <div class="card phase p2">
+    <h3 style="margin-top:0">阶段2 · devflow-core 抽取 <span class="tag t-orange">设计启动</span></h3>
+    <ul>
+      <li>UI 无关 crate 界定为 devflow-core（工作流引擎/任务管理/存储层）</li>
+      <li>存储 trait 双实现：SQLite（本地）/ PostgreSQL（云端）</li>
+      <li>AI Provider 双模式：key 本机直连（个人版）/ 云端集中托管（团队版）</li>
+      <li>同主机 Nginx 后追加 df-cloud-server，管道层不动</li>
+    </ul>
+  </div>
+  <div class="card phase p3">
+    <h3 style="margin-top:0">阶段3 · 完整云端化 <span class="tag t-purple">预留</span></h3>
+    <ul>
+      <li>云端接管全部业务逻辑，桌面端降级薄客户端</li>
+      <li>多用户 / 多设备 / 团队协作（任务池/审批/知识库共享）</li>
+      <li>可选本地引擎保离线能力</li>
+    </ul>
+  </div>
+</div>
+
+<h2>五、组件清单与状态</h2>
+<table>
+<tr><th>组件</th><th>形态</th><th>部署位置</th><th>状态</th></tr>
+<tr><td>u-relay :9180</td><td>Rust 二进制（已有）</td><td>云端主机，systemd 原子切换</td><td class="ok">✅ 复用零改动</td></tr>
+<tr><td>df-im-gateway</td><td>Rust crate（新增，方案A先驻 workspace）</td><td>联调期本机 → 常驻期云端主机</td><td class="ok">✅ 飞书端已通，实机验证</td></tr>
+<tr><td>Nginx :443</td><td>TLS 终结 + 反代（已有）</td><td>云端主机</td><td class="ok">✅ 复用</td></tr>
+<tr><td>DevFlow 桌面端</td><td>Tauri 2 应用</td><td>用户本机</td><td class="ok">✅ 唯一状态源</td></tr>
+<tr><td>df-cloud-server</td><td>Rust 服务（规划）</td><td>云端主机，Nginx 后</td><td>阶段2 拍板后立项</td></tr>
+</table>
+
+<h2>六、风险与关键点</h2>
+<div class="card">
+  <ul>
+    <li><span class="tag t-red">风险1</span><b>飞书卡片版本</b>：审批按钮回调仅新版卡片 <code>card.action.trigger</code> 生效，旧版 card 帧被 SDK 直接丢弃——联调最大坑（已知已沉淀）</li>
+    <li><span class="tag t-red">风险2</span><b>假活自愈</b>：断流约 13 分钟由看门狗 notify_waiters 唤醒（45f0560f），云端常驻部署后需关注长连接巡检参数</li>
+    <li><span class="tag t-orange">注意1</span><b>双库分歧</b>：devflow.db vs devflow-dev.db 是刻意设计（cfg! 分支），云化时存储层抽象需保留该模式</li>
+    <li><span class="tag t-orange">注意2</span><b>钉钉/企微降级</b>：P3/P4 保持 todo，不阻塞阶段1 验收与阶段2 并行</li>
+  </ul>
+</div>
+
+<div class="meta" style="margin-top:36px;border-top:1px solid var(--border);padding-top:12px">DevFlow 云化架构 · 生成于 2026-10-21 · 依据知识库拍板记录 978a3cf0 · 相关任务 6e13f49b / 711e1390</div>
+</div>
+</body>
+</html>