150 lines
3.7 KiB
Markdown
150 lines
3.7 KiB
Markdown
|
# Copilot 工程化配置设计
|
|||
|
|
|
|||
|
|
> 本文档定义面向插件开发的工程化配置方案：支持 GitHub Copilot、兼容 Gemini CLI，并引入“反重力开发”模式。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 目标
|
|||
|
|
|
|||
|
|
- 建立统一、可落地的 AI 协同开发标准。
|
|||
|
|
- 支持双通道助手体系：
|
|||
|
|
- GitHub Copilot（编辑器内主通道）
|
|||
|
|
- Gemini CLI（外部补充通道）
|
|||
|
|
- 在高迭代速度下保障可回滚、可审计、可发布。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 适用范围
|
|||
|
|
|
|||
|
|
适用于以下类型开发：
|
|||
|
|
|
|||
|
|
- 插件代码（`actions` / `filters` / `pipes` / `pipelines` / `tools`）
|
|||
|
|
- 文档同步与发布准备
|
|||
|
|
- OpenWebUI 文件创建与交付流程
|
|||
|
|
- 流式输出与工具卡片兼容性
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Copilot 工程化主配置
|
|||
|
|
|
|||
|
|
### 3.1 规范来源
|
|||
|
|
|
|||
|
|
- 主规范：`.github/copilot-instructions.md`
|
|||
|
|
- 工作流：`.agent/workflows/plugin-development.md`
|
|||
|
|
- 运行时开发指南：
|
|||
|
|
- `docs/development/plugin-guide.md`
|
|||
|
|
- `docs/development/plugin-guide.zh.md`
|
|||
|
|
|
|||
|
|
### 3.2 强制开发契约
|
|||
|
|
|
|||
|
|
- 单文件 i18n 插件源码。
|
|||
|
|
- README 双语（`README.md` + `README_CN.md`）。
|
|||
|
|
- 上下文统一入口（`_get_user_context`、`_get_chat_context`）。
|
|||
|
|
- 事件标准化（`status`、`notification`、`execute`）。
|
|||
|
|
- 禁止静默失败（用户可见状态 + 后端日志）。
|
|||
|
|
|
|||
|
|
### 3.3 Copilot SDK 工具契约
|
|||
|
|
|
|||
|
|
- 参数必须 `pydantic.BaseModel` 显式定义。
|
|||
|
|
- 工具注册必须声明 `params_type`。
|
|||
|
|
- 保留默认值语义，避免把未传参数强制覆盖为 `null`。
|
|||
|
|
- 工具名需可预测、可规范化。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Gemini CLI 兼容配置
|
|||
|
|
|
|||
|
|
Gemini CLI 作为补充通道，而不是替代主规范。
|
|||
|
|
|
|||
|
|
### 4.1 使用边界
|
|||
|
|
|
|||
|
|
- 适合：草案生成、方案对照、迁移校验。
|
|||
|
|
- 不得绕过仓库规范与插件契约。
|
|||
|
|
|
|||
|
|
### 4.2 输出归一化
|
|||
|
|
|
|||
|
|
Gemini CLI 输出合入前必须完成：
|
|||
|
|
|
|||
|
|
- 命名与结构对齐仓库约束。
|
|||
|
|
- 保留 OpenWebUI 插件标准签名与上下文方法。
|
|||
|
|
- 将“建议性文字”转换为可执行、可验证实现点。
|
|||
|
|
|
|||
|
|
### 4.3 冲突决策
|
|||
|
|
|
|||
|
|
Copilot 与 Gemini 建议冲突时按优先级处理：
|
|||
|
|
|
|||
|
|
1. 规范一致性优先
|
|||
|
|
2. 安全回退优先
|
|||
|
|
3. 低集成风险优先
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 反重力开发（Antigravity）模式
|
|||
|
|
|
|||
|
|
反重力开发 = 高速迭代 + 强回退能力。
|
|||
|
|
|
|||
|
|
### 5.1 核心原则
|
|||
|
|
|
|||
|
|
- 小步、隔离、可逆变更
|
|||
|
|
- 接口稳定、行为可预测
|
|||
|
|
- 多级回退链路
|
|||
|
|
- 支持前滚与回滚
|
|||
|
|
|
|||
|
|
### 5.2 强制模式
|
|||
|
|
|
|||
|
|
- 前端执行调用必须设置超时保护。
|
|||
|
|
- 工作区文件操作必须做路径沙箱校验。
|
|||
|
|
- 上传链路采用 API 优先 + 本地/DB 回退。
|
|||
|
|
- 长任务必须分阶段状态反馈。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 文件创建与交付标准
|
|||
|
|
|
|||
|
|
### 6.1 创建范围
|
|||
|
|
|
|||
|
|
- 交付文件仅在受控 workspace 内创建。
|
|||
|
|
- 禁止将交付产物写到 workspace 边界之外。
|
|||
|
|
|
|||
|
|
### 6.2 三步交付协议
|
|||
|
|
|
|||
|
|
1. 本地写入
|
|||
|
|
2. 从 workspace 发布
|
|||
|
|
3. 返回并展示 `/api/v1/files/{id}/content`
|
|||
|
|
|
|||
|
|
### 6.3 元数据策略
|
|||
|
|
|
|||
|
|
- 需要绕过检索时为产物标记 `skip_rag=true`。
|
|||
|
|
- 文件名采用确定性策略：`chat_title -> markdown_title -> user+date`。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 多助手并行下的插件开发规范
|
|||
|
|
|
|||
|
|
- 在统一契约下同时兼容 GitHub Copilot 与 Gemini CLI。
|
|||
|
|
- 流式输出保持 OpenWebUI 原生兼容（`<think>`、`<details type="tool_calls">`）。
|
|||
|
|
- 工具卡片属性严格转义（`"`）保证解析稳定。
|
|||
|
|
- 全链路保持异步非阻塞。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 文档同步规则
|
|||
|
|
|
|||
|
|
插件工程化变更发生时，至少同步：
|
|||
|
|
|
|||
|
|
1. 插件代码
|
|||
|
|
2. 插件双语 README
|
|||
|
|
3. docs 详情页（EN/ZH）
|
|||
|
|
4. docs 索引页（EN/ZH）
|
|||
|
|
5. 发布准备阶段同步根 README 日期徽章
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 验收清单
|
|||
|
|
|
|||
|
|
- Copilot 配置与工作流引用有效。
|
|||
|
|
- Gemini CLI 输出可无缝合入且不破坏规范。
|
|||
|
|
- 反重力安全机制完整。
|
|||
|
|
- 文件创建/发布流程可复现。
|
|||
|
|
- 流式与工具卡片格式保持 OpenWebUI 兼容。
|