文档: 插件机制设计(grammar静态/集成切入点/通用远期)

复杂度=架构成本框架评估可扩展性(持续+复利负债)。
决策: grammar 静态编译+集中 lookup(当前,红利未兑现不承担动态加载成本)/
外部 API 集成(云效禅道)是插件正确切入点(窄契约窄插件,真实高价值)/
通用插件系统(VSCode式)远期(无生态=过早=负债)。
渐进路径: 静态grammar→云效集成直接实现→抽 IntegrationProvider trait→禅道印证抽象→插件化。
单向同步起步(双向冲突是分布式级难题,远期)。

docs/02-架构设计/专项设计/插件机制-设计-2026-06-24.md

@@ -0,0 +1,108 @@
+# 插件机制设计 — DevFlow 可扩展性
+
+> 日期:2026-06-24 | 状态:方向定稿(grammar 静态 + 集成渐进,通用插件远期)
+> 关联:[AST 符号解析设计](AST符号解析-设计-2026-06-24.md) / memory devflow-ast-code-intel-design / devflow-product-positioning / no-patch-groundwork
+
+## Context(为什么有这文档)
+
+grammar 动态加载讨论 → 引出"插件机制"概念 → 评估通用插件系统 → 落到"外部 API 集成(云效/禅道)"真场景 → 用"架构成本"统一评估。本文档沉淀可扩展性决策:何时插件化、怎么渐进、什么是正确切入点。
+
+## 一、动态加载 grammar(技术可行性)
+
+tree-sitter grammar 是 C 解析器,可编译成共享库运行期加载:
+- grammar → `.dll`/`.so`/`.dylib`(tree-sitter CLI 或 cc 编译)
+- Rust `libloading` 运行期 dlopen + 查 `tree_sitter_<lang>` 符号 → `Language`
+- Helix / Neovim / Zed 行业先例
+
+**但**:跨平台分发(每平台 × 每 grammar 共享库)+ ABI 版本管理(grammar 编译时 tree-sitter 版本须匹配运行期,错则崩)+ 加载机制 ~100-200 行。复杂度中-高。
+
+## 二、插件形态谱系(窄 → 通用)
+
+| 形态 | 契约 | 能力 | 复杂度 | 例子 |
+|---|---|---|---|---|
+| grammar 动态加载 | 单(一个函数) | 单(源码→AST) | 中 | Helix language |
+| 集成插件 | 单(IntegrationProvider 几操作) | 中(API 调用+映射+同步) | 中 | 云效/禅道 |
+| 通用插件系统 | 多(extension points) | 任意(命令/UI/规则...) | 极高 | VSCode 扩展 |
+
+通用插件要:manifest / 生命周期 / 沙箱 / 权限 / 依赖图 / 市场 / API 稳定性。软件工程最难子系统之一。
+
+## 三、复杂度 = 架构成本(评估框架)
+
+复杂度不是抽象的"难",是**架构投资决策**。每个抽象/机制/插件点付架构成本,价值须覆盖:
+
+| 成本 | 性质 |
+|---|---|
+| 抽象边界 | 间接层,理解/调试;抽象错束缚未来 |
+| 契约维护 | 接口定义了就要养(兼容枷锁) |
+| 运行时状态 | 故障模式 ×N |
+| 耦合传播 | 改一处影响多少 |
+| 演化阻力 | 架构固化后改方向成本(锁死) |
+| 认知 | 上手成本 |
+
+**持续 + 复利**:每个未来改动都付。投资回报判断。统一 [[no-patch-groundwork]](成本不被覆盖=补丁堆砌)/ [[ai-improvement-principles]](易迭代=架构成本低)。
+
+## 四、三方案评估(grammar 视角)
+
+| 方案 | 架构成本 | 价值 | 当前覆盖? |
+|---|---|---|---|
+| **静态 + 集中 lookup** | 最低 | 中 | ✅ 覆盖 |
+| grammar 动态加载 | 中高(运行时状态+ABI+分发) | 中(红利未兑现) | ❌ |
+| 通用插件系统 | 极高(沙箱/契约/演化枷锁) | 高(但无生态) | ❌ |
+
+**决策:静态 + 集中 lookup**。grammar 获取集中到普通函数 `grammar_for(ext)`,不抽 trait(YAGNI,无第二实现不抽象)。
+
+## 五、外部 API 集成:插件正确切入点
+
+通用插件当前不做,但**集成是插件能力的正确起点**——真实高价值场景 + 低复杂度形态。
+
+**需求**:DevFlow 工作流枢纽,任务/缺陷/需求也在云效/禅道 → 数据孤岛 + 重复录入。打通 = 双向同步 + aichat 跨系统操作。
+
+**技术可行**:云效(阿里云 OpenAPI)/ 禅道(ZenTao REST)都有 API。Rust reqwest 调用,难度低于 LSP/沙箱插件。
+
+**集成 vs 通用插件**:集成是"窄插件"(单契约 IntegrationProvider,无沙箱——受控 API 调用非执行任意代码)。有扩展红利,无重框架复杂度。
+
+**架构成本(诚实)**:主要在**同步语义**(双向 DevFlow↔云效:冲突/时序/幂等/一致性,分布式级难题),非插件框架。其他:认证/凭证(中)、数据映射(中,每集成一套)、API 边界稳定性(中,外部依赖持续)。
+
+**价值**:自用(省重复,aichat 跨系统)+ 分发(集成生态=差异化/粘性/护城河)。成本高但价值高,值得——同步是核心难点,单向起步。
+
+## 六、渐进路径
+
+```
+1. 静态 grammar + 集中 lookup(现在,Phase1)
+   Rust/TS/JS/Vue(借TS),3 grammar 覆盖 4 类
+   不动态/不 trait
+
+2. 首个集成:云效(近期,memory 已有 yunxiao 同向)
+   直接代码实现,验证打通价值
+   单向同步起步(避双向冲突复杂度)
+
+3. 抽 IntegrationProvider trait(云效跑通后)
+   标准接口:sync_tasks/list_bugs/create_requirement
+   窄契约,低架构成本
+
+4. 第二集成:禅道按接口实现(中期)
+   印证抽象可复用
+
+5. 插件化(远期,集成 3+)
+   动态加载/分发;通用插件系统:产品有规模/生态后
+```
+
+每步独立有价值,不依赖后续。先具体后抽象,避免预先建空框架。
+
+## 七、决策汇总
+
+| 项 | 决策 | 理由 |
+|---|---|---|
+| grammar 加载 | 静态 + 集中 lookup | 架构成本最低,红利未兑现 |
+| grammar trait | 不抽(YAGNI) | 无第二实现不抽象 |
+| 通用插件系统 | 远期(有生态后) | 当前无生态,过早=负债 |
+| 集成方向 | 定(云效/禅道,工作流打通) | 真实高价值,窄插件正确起点 |
+| 集成实现 | 渐进(云效→trait→禅道) | 先具体后抽象 |
+| 集成同步 | 单向起步 | 双向冲突分布式难题,远期 |
+
+**核心**:插件愿景对(可扩展=产品长期价值),但时机/复杂度决定——从集成低复杂度高价值场景切入,静态 grammar 当前够,通用插件远期。不为假想需求建重框架。
+
+## 关键文件(集成实施时)
+
+- grammar 集成:`src-tauri/Cargo.toml` 加 tree-sitter + grammar crate;新模块 `code_intel.rs` 内 `grammar_for(ext)` 集中 lookup
+- 集成(云效):新 crate `df-integration` 或 df-execute 内;IntegrationProvider trait;凭证存储复用 KV