# 插件机制设计 — 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