From 4c16118712f09ed3c4269efa55b318c9be2127dd Mon Sep 17 00:00:00 2001 From: "guangfei.zhao" Date: Mon, 30 Mar 2026 18:01:34 +0800 Subject: [PATCH] add workflow planning docs --- AGENTS.md | 5 + README.md | 61 +- ..._Feature_Breakdown_and_Replication_Requirements.md} | 2 +- ...erDuty_Information_Architecture_and_Page_Design.md} | 4 +- ...单.md => PagerDuty_MVP_Product_Requirements.md} | 2 +- workflow/AIOps_Workflow_Requirements.md | 531 +++++++++++++++ ...y_Lightweight_Customization_and_Upgrade.md | 639 ++++++++++++++++++ 7 files changed, 1236 insertions(+), 8 deletions(-) rename pagerduty/{PagerDuty_功能拆解与复刻需求.md => PagerDuty_Feature_Breakdown_and_Replication_Requirements.md} (99%) rename pagerduty/{PagerDuty_页面与信息架构设计.md => PagerDuty_Information_Architecture_and_Page_Design.md} (98%) rename pagerduty/{PagerDuty_MVP_产品需求清单.md => PagerDuty_MVP_Product_Requirements.md} (99%) create mode 100644 workflow/AIOps_Workflow_Requirements.md create mode 100644 workflow/Dify_Lightweight_Customization_and_Upgrade.md diff --git a/AGENTS.md b/AGENTS.md index 0bddc04..825a3c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # AGENTS.md + + This file guides agentic coding assistants operating in this repository. Current workspace: `C:\Users\A200477427\Learnings\AIOps-Docs`. @@ -82,6 +84,8 @@ pytest tests/test_example.py::test_specific_case - Use clear heading hierarchy (`##`, `###`) with logical progression. - Keep numeric section prefixes when a document already uses them. - Use `---` only when it improves readability. +- Use English names for new files and directories. +- Chinese content is allowed inside Markdown documents when appropriate. ### 5.3 Terminology consistency - Wrap module/service identifiers in backticks. @@ -142,6 +146,7 @@ If code/scripts are added, apply these defaults unless project configs override - If canonical terms change in one doc, update related docs in the same change. - Keep diagram references and explanation text mutually consistent. - Prefer small, reviewable changes grouped by topic. +- When renaming files, update all local references in the same change. ## 8) Agent Completion Checklist Before finishing a task, verify: diff --git a/README.md b/README.md index b2ae101..cca704e 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,72 @@ 这个仓库用于沉淀 AIOps 项目的产品方案、架构设计、实施路线和配套架构图，作为内部讨论、方案迭代和后续产品化的统一文档入口。 -## 当前文档 +## 快速入口 -- `AIOps_Product_Architecture_and_Commercialization.md`：产品架构与商业化主文档 -- `AIOps_Architecture_Diagram_Explanation.md`：当前架构图逐层详解与推导说明 -- `AIOps_Project_Proposal.md`：项目提案文档 -- `AIOps_Practical_Route_Architecture.png`：当前统一参考架构图 +### 核心架构文档 + +- [`AIOps_Product_Architecture_and_Commercialization.md`](AIOps_Product_Architecture_and_Commercialization.md)：产品架构与商业化主文档 +- [`AIOps_Architecture_Diagram_Explanation.md`](AIOps_Architecture_Diagram_Explanation.md)：当前架构图逐层详解与推导说明 +- [`AIOps_Project_Proposal.md`](AIOps_Project_Proposal.md)：项目提案文档 +- [`AIOps_Practical_Route_Architecture.png`](AIOps_Practical_Route_Architecture.png)：当前统一参考架构图 + +### PagerDuty 参考文档 + +- [`pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md`]( + pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md + )：PagerDuty 功能拆解与复刻需求 +- [`pagerduty/PagerDuty_MVP_Product_Requirements.md`]( + pagerduty/PagerDuty_MVP_Product_Requirements.md + )：PagerDuty 风格 MVP 产品需求清单 +- [`pagerduty/PagerDuty_Information_Architecture_and_Page_Design.md`]( + pagerduty/PagerDuty_Information_Architecture_and_Page_Design.md + )：PagerDuty 页面与信息架构设计 + +### Workflow 文档 + +- [`workflow/AIOps_Workflow_Requirements.md`](workflow/AIOps_Workflow_Requirements.md) + ：`aiops-workflow` 需求清单与范围定义 +- [`workflow/Dify_Lightweight_Customization_and_Upgrade.md`](workflow/Dify_Lightweight_Customization_and_Upgrade.md) + ：基于固定 Dify tag 的轻量定制与升级策略 + +## Dify Baseline Management + +当前与 Dify 相关的轻量定制和升级策略，统一参考： + +- [`workflow/Dify_Lightweight_Customization_and_Upgrade.md`](workflow/Dify_Lightweight_Customization_and_Upgrade.md) + +建议在后续实际落库时，持续维护以下信息： + +| 项目 | 建议记录 | +| --- | --- | +| Dify baseline | 当前采用的官方 tag，例如 `1.13.3` | +| Baseline branch | 对应基线分支，例如 `baseline/dify-1.13.3` | +| Main branch role | 当前稳定定制版本 | +| Upgrade branch | 本次升级分支，例如 `upgrade/dify-1.13.4` | +| Customization scope | 当前只改哪些前端目录 | +| Backend policy | 是否允许修改 Python 后端 | + +当前推荐的分支模型： + +- `baseline/dify-`：保存官方基线快照 +- `main`：保存当前稳定定制版本 +- `upgrade/dify-`：处理升级适配和兼容修复 + +## 目录说明 + +- `pagerduty/`：PagerDuty 对标拆解、MVP 范围与页面设计文档 +- `workflow/`：`aiops-workflow` 相关需求与设计文档 ## 使用建议 - 统一围绕 `AIOps_Practical_Route_Architecture.png` 讨论和更新文档 - 架构图有较大调整时，同步更新 `AIOps_Architecture_Diagram_Explanation.md` - 产品定位、范围、实施路径变化时，同步更新主文档 +- 专题文档优先沉淀到对应目录，并保持 README 快速入口同步 ## 仓库定位 - 这是一个文档仓库，不是代码仓库 - 图中的模块首先表达逻辑职责，不强制等于最终微服务拆分 - MVP 阶段允许多个模块在实现上合并 +- 新建文件和目录默认使用英文名称，内容可以使用中文 diff --git a/pagerduty/PagerDuty_功能拆解与复刻需求.md b/pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md similarity index 99% rename from pagerduty/PagerDuty_功能拆解与复刻需求.md rename to pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md index 4276f81..12ed7ff 100644 --- a/pagerduty/PagerDuty_功能拆解与复刻需求.md +++ b/pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md @@ -845,7 +845,7 @@ PagerDuty 给你的最大启发，不是某个单点功能，而是产品层次 如果继续往下做，我建议下一份文档直接接这个主题，写成： -- `PagerDuty_MVP_产品需求清单.md` +- `PagerDuty_MVP_Product_Requirements.md` 里面把本文件再进一步收敛成： diff --git a/pagerduty/PagerDuty_页面与信息架构设计.md b/pagerduty/PagerDuty_Information_Architecture_and_Page_Design.md similarity index 98% rename from pagerduty/PagerDuty_页面与信息架构设计.md rename to pagerduty/PagerDuty_Information_Architecture_and_Page_Design.md index 8c71afc..ccb526a 100644 --- a/pagerduty/PagerDuty_页面与信息架构设计.md +++ b/pagerduty/PagerDuty_Information_Architecture_and_Page_Design.md @@ -2,7 +2,9 @@ ## 1. 文档目标 -本文档在 `PagerDuty_MVP_产品需求清单.md` 基础上，定义 PagerDuty 风格 Incident Management MVP 的页面结构、导航方式、核心信息组织方式和关键页面布局。 +本文档在 `PagerDuty_MVP_Product_Requirements.md` 基础上， +定义 PagerDuty 风格 Incident Management MVP 的页面结构、导航方式、 +核心信息组织方式和关键页面布局。 目标是帮助产品、设计和研发统一以下内容： diff --git a/pagerduty/PagerDuty_MVP_产品需求清单.md b/pagerduty/PagerDuty_MVP_Product_Requirements.md similarity index 99% rename from pagerduty/PagerDuty_MVP_产品需求清单.md rename to pagerduty/PagerDuty_MVP_Product_Requirements.md index 0f9e2b0..fb0aa4a 100644 --- a/pagerduty/PagerDuty_MVP_产品需求清单.md +++ b/pagerduty/PagerDuty_MVP_Product_Requirements.md @@ -2,7 +2,7 @@ ## 1. 文档目标 -本文档基于 `PagerDuty_功能拆解与复刻需求.md`， +本文档基于 `PagerDuty_Feature_Breakdown_and_Replication_Requirements.md`， 进一步收敛出一个可执行的 PagerDuty 风格 Incident Management MVP 范围。 本文档重点回答四个问题： diff --git a/workflow/AIOps_Workflow_Requirements.md b/workflow/AIOps_Workflow_Requirements.md new file mode 100644 index 0000000..18fc105 --- /dev/null +++ b/workflow/AIOps_Workflow_Requirements.md @@ -0,0 +1,531 @@ +# AIOps Workflow Requirements + +## 1. 文档目标 + +本文档用于定义 `aiops-workflow` 项目的职责边界、MVP 需求范围、核心对象模型、输入输出契约与实施优先级。 + +这份文档基于主架构文档中对三层项目域的划分，重点回答以下问题： + +1. `aiops-workflow` 在整体 AIOps 架构中的定位是什么。 +2. `aiops-workflow` 在 MVP 阶段必须交付哪些能力。 +3. 它和 `aiops-platform`、`aiops-tools` 的边界如何清晰切开。 +4. 如何保证 workflow 输出稳定、可解释、可评测、可演进。 + +本文档默认面向 `workflow-first` 路线，而不是 multi-agent 优先路线。 + +## 2. 项目定位 + +### 2.1 核心定义 + +`aiops-workflow` 负责“如何做诊断、如何组织证据、如何输出结构化 RCA 与建议”。 + +它不是平台主控层，也不是底层工具适配层，而是位于两者之间的智能工作流中枢。 + +其核心职责是： + +- 接收 `aiops-platform` 提供的 Incident 上下文。 +- 按既定 workflow 执行诊断、检索与推理。 +- 调用 `aiops-tools` 暴露的查询类工具补齐证据。 +- 输出平台可直接消费的结构化结果。 + +### 2.2 不负责的事情 + +`aiops-workflow` 明确不负责： + +- 持有 `Incident` 主状态 +- 审批流转 +- 执行动作控制 +- 页面展示 +- 直接对生产环境进行写操作 +- 直接耦合底层监控系统协议细节 + +### 2.3 核心设计原则 + +- Workflow 优先于 multi-agent +- 查询能力可以直接调用 tools +- 执行能力必须回到平台决策 +- 输出必须结构化，不能只返回自由文本 +- 所有 workflow 都要可版本化、可回放、可评测 + +## 3. 目标用户与调用方 + +### 3.1 直接调用方 + +- `aiops-platform` +- 后续可能的复盘任务调度器 +- 评测回归任务调度器 + +### 3.2 主要使用者 + +- AI 工程师：维护 workflow、Prompt、Schema、评测集 +- 平台后端工程师：对接调用契约与任务状态 +- SRE / 运维专家：审核知识库、诊断逻辑、建议动作质量 + +## 4. MVP 成功标准 + +MVP 阶段，`aiops-workflow` 至少应达到以下结果： + +1. 可稳定执行 `incident_diagnosis` 工作流。 +2. 可调用 2-3 个查询类工具补齐证据。 +3. 可返回统一格式的 `RCA Result` 与 `actions`。 +4. 输出结果可被平台直接落库和展示。 +5. 具备基础评测回归能力，避免工作流更新后质量失控。 + +建议的 MVP 指标： + +| 指标 | 说明 | MVP 目标 | +| --- | --- | --- | +| Workflow 成功率 | 工作流执行完成率 | 高于 95% | +| Schema 合法率 | 输出满足平台 schema 的比例 | 高于 99% | +| 诊断 P95 时延 | 从触发到输出结果的时延 | 小于 60 秒 | +| 引证覆盖率 | 结果中包含有效 evidence 的比例 | 高于 90% | +| RCA Top1 准确率 | 在评测集上的首选结论命中率 | 持续追踪 | + +## 5. 范围边界 + +### 5.1 MVP 必须范围 + +- Workflow 注册与版本管理 +- `incident_diagnosis` 工作流 +- `action_planning` 工作流 +- 查询类工具编排 +- RAG 检索策略基础能力 +- 结构化输出 schema +- 任务状态查询 +- 评测样例与回归检查 +- 失败与降级策略 + +### 5.2 MVP 可选增强 + +- `postmortem_summary` 工作流 +- Prompt 模板变量管理界面 +- 多知识域检索重排 +- 更细粒度的步骤级 tracing + +### 5.3 明确不在 MVP + +- Multi-agent 编排框架 +- 执行类动作直连生产系统 +- 复杂可视化管理后台 +- 全自动根因图谱推理平台 +- 训练/微调平台 + +## 6. 核心对象模型 + +建议 `aiops-workflow` 先围绕以下对象建模： + +| 对象 | 说明 | 关键字段 | +| --- | --- | --- | +| `WorkflowDefinition` | 工作流定义 | id, name, purpose, owner | +| `WorkflowVersion` | 工作流版本 | version, status, schema_ref, prompt_refs | +| `SkillDefinition` | 可复用能力单元 | id, workflow_ref, input_schema, output_schema | +| `PromptAsset` | Prompt 模板资产 | id, version, variables, content | +| `KnowledgeCollection` | 知识集合 | id, source_type, tags, index_ref | +| `RetrievalPolicy` | 检索策略 | top_k, filters, rerank_policy | +| `ToolContract` | 工具调用契约 | tool_name, input_schema, output_schema | +| `WorkflowRun` | 一次工作流执行实例 | run_id, workflow_id, status, started_at | +| `WorkflowStepRun` | 步骤运行实例 | step_name, tool_name, status, duration_ms | +| `EvaluationCase` | 评测样例 | case_id, input, expected_output | +| `SchemaContract` | 输出契约 | fields, required, enum_constraints | + +## 7. MVP 功能需求 + +## 7.1 Workflow Registry + +### 7.1.1 能力目标 + +系统应能管理工作流定义与版本，而不是把 workflow 当成散乱脚本。 + +### 7.1.2 必须能力 + +- 注册 workflow +- 维护 workflow 名称、用途、负责人 +- 管理版本状态 + - draft + - active + - deprecated +- 记录 workflow 依赖的 Prompt、Schema、Knowledge、Tools + +### 7.1.3 验收标准 + +1. 可查看某个 workflow 的当前生效版本。 +2. 更新 workflow 时可保留历史版本。 +3. 平台调用时可明确命中哪个版本。 + +## 7.2 `incident_diagnosis` 工作流 + +### 7.2.1 目标 + +这是 MVP 最核心的工作流，用于根据 Incident 上下文给出结构化诊断结果。 + +### 7.2.2 输入要求 + +最小输入建议包含： + +- `incident_id` +- `title` +- `severity` +- `service` +- `env` +- `fingerprint` +- `time_window` +- `recent_changes` +- `related_incidents` +- `topology` + +### 7.2.3 执行步骤 + +建议固定为以下链路： + +1. 解析 Incident 上下文 +2. 决定需要调用的查询工具 +3. 调用 metrics / logs / k8s / changes 查询 +4. 调用 RAG 补充 SOP 和历史案例 +5. 汇总证据并生成候选结论 +6. 输出结构化 RCA + +### 7.2.4 输出要求 + +必须返回： + +- `summary` +- `rca.conclusion` +- `rca.confidence` +- `rca.impact_scope` +- `rca.evidence[]` +- `actions[]` + +### 7.2.5 验收标准 + +1. 输出必须满足平台约定 schema。 +2. 结果中至少包含一条 evidence。 +3. 低置信度时不能输出高风险自动执行模式。 + +## 7.3 `action_planning` 工作流 + +### 7.3.1 目标 + +根据已形成的 RCA 与上下文，给出可执行但受控的动作建议。 + +### 7.3.2 必须能力 + +- 根据 RCA 生成动作建议列表 +- 为每个动作给出风险等级 +- 为每个动作给出推荐模式 + - `auto` + - `approval` + - `suggest_only` +- 提供回滚建议 + +### 7.3.3 约束 + +- 仅输出建议，不直接执行 +- 不允许 workflow 自行持有执行凭证 +- `confidence` 低于阈值时自动降级 + +### 7.3.4 验收标准 + +1. 每个动作都带 `risk` 和 `mode`。 +2. 中高风险动作默认不能为 `auto`。 +3. 建议动作可以被平台直接渲染展示。 + +## 7.4 `postmortem_summary` 工作流 + +### 7.4.1 目标 + +该工作流建议作为 P1 能力，用于在 Incident 关闭后生成复盘初稿。 + +### 7.4.2 建议输出 + +- Incident summary +- 关键时间点摘要 +- 主要证据 +- 初步改进建议 +- 待人工确认的问题清单 + +### 7.4.3 MVP 处理方式 + +MVP 可先保留设计，不强制交付。 + +## 7.5 Prompt 资产管理 + +### 7.5.1 必须能力 + +- Prompt 版本化 +- Prompt 与 workflow 绑定 +- 变量占位支持 +- 记录 Prompt 更新时间和负责人 + +### 7.5.2 设计要求 + +- Prompt 不应散落在代码或平台表单中不可追踪地修改 +- Prompt 变更必须可回溯，并可在评测中验证 + +## 7.6 RAG 管理能力 + +### 7.6.1 范围 + +`aiops-workflow` 需要管理“如何检索”，不一定亲自实现底层向量数据库服务。 + +### 7.6.2 MVP 必须能力 + +- 管理知识集合引用 +- 定义检索过滤条件 +- 定义召回数量 `top_k` +- 定义是否进行 rerank +- 返回引用证据 + +### 7.6.3 知识来源建议 + +- SOP 文档 +- 历史 Incident / Postmortem +- 变更处理手册 +- 常见故障 FAQ + +### 7.6.4 验收标准 + +1. workflow 输出中能引用知识来源。 +2. 检索异常时可降级，不致使整体任务崩溃。 + +## 7.7 Tools 编排能力 + +### 7.7.1 必须支持的查询类工具 + +- `query_metrics` +- `query_logs` +- `query_k8s` +- `query_changes` + +### 7.7.2 调用原则 + +- workflow 只调用标准化工具契约 +- 不直接关心 Prometheus / Loki / K8s 原生协议差异 +- 工具异常要回传为结构化错误 + +### 7.7.3 明确禁止 + +- 直接调用生产执行接口 +- 绕过平台审批去执行变更 +- 将 tool 返回的自由文本直接当最终结论 + +### 7.7.4 验收标准 + +1. tools 调用记录可关联到 workflow run。 +2. tool 错误会降低置信度并触发降级逻辑。 + +## 7.8 输出 Schema 契约 + +### 7.8.1 必须能力 + +- 明确定义 output schema +- 校验 required 字段 +- 校验枚举字段 +- 拒绝不合法输出进入平台主链路 + +### 7.8.2 核心字段建议 + +```json +{ + "summary": "数据库连接池耗尽导致 API 延迟升高", + "rca": { + "conclusion": "连接池配置与突发流量不匹配", + "confidence": 0.86, + "impact_scope": ["api-gateway", "order-service"], + "evidence": [ + {"type": "metric", "ref": "promql://latency_p95"}, + {"type": "log", "ref": "loki://timeout_errors"} + ] + }, + "actions": [ + { + "name": "临时扩容 order-service", + "risk": "low", + "mode": "auto", + "rollback": "scale down deployment/order-service" + } + ] +} +``` + +### 7.8.3 验收标准 + +1. schema 校验失败时返回明确错误码。 +2. 平台侧不需要解析自由文本才能使用结果。 + +## 7.9 运行态与任务管理 + +### 7.9.1 必须能力 + +- 异步任务运行 +- 任务状态查询 +- 步骤级状态展示 +- 超时控制 +- 取消任务 + +### 7.9.2 任务状态 + +- `queued` +- `running` +- `succeeded` +- `failed` +- `timeout` + +### 7.9.3 验收标准 + +1. 平台可以查询任务当前状态。 +2. 失败任务能返回失败原因。 +3. 超时任务进入明确降级路径。 + +## 7.10 评测与回归能力 + +### 7.10.1 必须能力 + +- 保存评测样例 +- 定义期望输出或期望结论 +- workflow 更新后可批量回归 +- 对比关键指标变化 + +### 7.10.2 核心评测维度 + +- RCA 是否正确 +- evidence 是否充分 +- schema 是否合法 +- 动作建议是否越权 +- 置信度是否异常偏高 + +### 7.10.3 验收标准 + +1. 每次重要 workflow 变更前后都能跑回归集。 +2. 回归结果可沉淀为版本发布依据。 + +## 7.11 可观测性与审计 + +### 7.11.1 必须记录的信息 + +- workflow 名称与版本 +- run_id +- 输入摘要 +- tools 调用记录 +- token / cost 使用量 +- 执行耗时 +- 输出摘要 +- 错误信息 + +### 7.11.2 边界说明 + +`aiops-workflow` 可以记录 workflow 运行审计，但 Incident 主审计仍由 `aiops-platform` 持有。 + +## 7.12 失败与降级策略 + +### 7.12.1 必须实现 + +- LLM 超时降级 +- tool 不可用降级 +- 检索失败降级 +- schema 不合法降级 + +### 7.12.2 建议行为 + +- 返回部分结果 + 低置信度标记 +- 阻断自动动作建议 +- 明确提示人工接管 + +### 7.12.3 错误码建议 + +- `AI_TIMEOUT` +- `TOOL_UNAVAILABLE` +- `SCHEMA_INVALID` +- `RAG_UNAVAILABLE` +- `WORKFLOW_FAILED` + +## 7.13 安全要求 + +### 7.13.1 必须约束 + +- 不保存生产执行凭证 +- 不直接调用写操作工具 +- 不暴露敏感原始凭证到 Prompt +- 对输入上下文中的敏感字段进行最小化传递 + +### 7.13.2 合规要求 + +- workflow 运行日志可追踪 +- Prompt 与知识来源可审计 +- 结果生成过程可解释 + +## 8. 与平台的接口要求 + +### 8.1 诊断触发接口 + +- 平台触发 `incident_diagnosis` +- workflow 返回 `task_id` +- 平台异步查询结果 + +### 8.2 结果接口要求 + +成功结果必须包含： + +- `task_id` +- `incident_id` +- `status` +- `summary` +- `rca` +- `actions` + +### 8.3 会话追问能力 + +建议预留人工追问接口，用于平台详情页的补充诊断，但不应影响主 workflow 结果的结构化输出约束。 + +## 9. 推荐的仓库内文档与资产结构 + +如果后续 `aiops-workflow` 独立成仓，可参考如下结构： + +```text +workflow/ + AIOps_Workflow_Requirements.md + workflows/ + incident_diagnosis/ + action_planning/ + postmortem_summary/ + prompts/ + schemas/ + evals/ + knowledge/ +``` + +## 10. 分阶段实施建议 + +### Phase 1 + +- 打通 `incident_diagnosis` +- 接入 `query_metrics`、`query_logs`、`query_k8s` +- 固化结构化 RCA schema + +### Phase 2 + +- 增加 `action_planning` +- 完善 RAG 引用质量 +- 建立评测回归集 + +### Phase 3 + +- 增加 `postmortem_summary` +- 引入更细粒度版本治理 +- 评估局部 agent 化是否有必要 + +## 11. 结论 + +`aiops-workflow` 在整个架构中的价值，不是“单独做一个 AI 服务”， +而是把诊断能力沉淀成稳定、可复用、可评测的 workflow 资产。 + +如果 `aiops-platform` 解决的是“事件怎么流转”， +`aiops-tools` 解决的是“数据怎么查、动作怎么控”， +那么 `aiops-workflow` 解决的就是： + +- 证据如何组织 +- 诊断如何形成 +- 结果如何结构化输出 + +因此它的第一优先级不是做复杂 agent 协作， +而是先把 `incident_diagnosis -> evidence -> RCA -> actions` +这条链路做稳定、做可审计、做可回归。 diff --git a/workflow/Dify_Lightweight_Customization_and_Upgrade.md b/workflow/Dify_Lightweight_Customization_and_Upgrade.md new file mode 100644 index 0000000..e786faa --- /dev/null +++ b/workflow/Dify_Lightweight_Customization_and_Upgrade.md @@ -0,0 +1,639 @@ +# Dify Lightweight Customization and Upgrade + +## 1. 文档目标 + +本文档用于定义当前阶段基于 Dify 的最简定制与升级策略。 + +这份策略专门适用于下面这种现实约束： + +- Dify 官方仓库在 GitHub +- 公司正式仓库必须放在内网 Gitea +- 当前没有时间做复杂的深度二开 +- 主要只打算做轻量前端定制 +- 一般情况下不修改 Python 后端代码 + +本文档的目标不是追求最完美的工程形态，而是提供一套简单、能长期执行、升级成本可控的实践方案。 + +本文内容结合 `langgenius/dify` 官方仓库当前公开信息整理，重点参考： + +- 仓库根目录结构 +- `web/` 前端目录结构 +- `web/package.json` +- 官方 release 中的 upgrade guide + +## 2. 核心结论 + +当前阶段最适合的策略是： + +1. 选择一个稳定的 Dify `tag` 作为基线版本。 +2. 将该版本代码放入公司内网 Gitea 仓库。 +3. 只做轻量前端定制。 +4. 尽量不改 Python 后端逻辑。 +5. 如果后续 Dify 发布新版本，再单独开升级分支进行适配。 +6. 验证通过后合并回主分支，并更新 README 中记录的 Dify 基线版本。 + +一句话概括： + +**把 Dify 当作固定版本的上游产品来使用，只在前端做一层薄定制，升级时再重新适配这层薄定制。** + +## 3. 当前推荐策略为什么成立 + +你的实际目标不是长期深度维护一个 Dify 二开发行版，而是： + +- 借助 Dify 的现成 workflow 能力快速落地 +- 补一层更适合 AIOps 场景的页面 +- 保证后续还能跟上 Dify 的版本演进 + +在这种情况下，最重要的不是“保留最完整的上游工程关系”，而是： + +- 当前基线版本清楚 +- 定制范围足够小 +- 升级时知道要改哪些地方 + +只要这三点明确，直接基于固定 tag 工作就是可行的。 + +## 3.1 结合 Dify 官方仓库的实际情况 + +当前 `langgenius/dify` 官方仓库并不是一个只有前端的仓库，而是一个完整 monorepo，根目录至少包含： + +- `api/` +- `web/` +- `docker/` +- `docs/` +- `scripts/` +- `sdks/` + +这意味着你当前的真实策略应该理解为： + +- 你是基于整个 Dify 仓库选一个稳定 `tag` +- 但你自己的定制重点只放在 `web/` +- 后续升级时，虽然你主要改前端，但仍然要留意官方 release 对 `api/`、数据库迁移、环境变量的升级要求 + +换句话说： + +- 你的定制范围是前端为主 +- 但你的基线版本仍然是整个 Dify 项目版本 + +## 4. 仓库策略 + +## 4.1 推荐的现实做法 + +由于正式仓库必须放在公司内网 Gitea，当前建议采用： + +- GitHub：只作为 Dify 官方代码和版本 tag 的来源 +- Gitea：作为你的正式开发仓库 +- 本地开发环境：用于拉取官方 tag、做定制开发、做升级适配 + +这意味着： + +- 你的正式仓库不一定需要是 GitHub fork +- 直接把某个 Dify tag 的代码放入内网仓库也是可接受的 +- 真正重要的是在文档里记录当前基线版本 + +## 4.2 当前基线管理方式 + +建议在 README 或专门说明文档中记录： + +- 当前 Dify 基线版本 +- 当前对应的 baseline 分支 +- 当前定制范围 +- 当前不做的内容 + +例如： + +- Dify baseline: `v1.0.3` +- Baseline branch: `baseline/dify-1.0.3` +- Customization scope: `frontend only` +- Out of scope: `python backend changes`, `database schema changes` + +## 4.3 推荐分支模型 + +结合你当前的实际情况，推荐使用三类分支： + +- `baseline/dify-` +- `main` +- `upgrade/dify-` + +这三类分支的职责分别如下。 + +### `baseline/dify-` + +用于保存某个 Dify 官方 tag 对应的纯净基线版本。 + +例如： + +- `baseline/dify-1.13.3` +- `baseline/dify-1.13.4` + +这个分支的原则是： + +- 尽量保持和官方 tag 一致 +- 不放你的业务定制 +- 只作为“官方版本快照”存在 + +你可以把它理解成内网里的“官方镜像基线”。 + +### `main` + +用于保存当前稳定可用的定制版本。 + +这个分支的原则是： + +- 是团队默认开发和使用的主分支 +- 已经包含你的轻量前端定制 +- 应该始终保持可运行状态 + +可以理解为： + +- `main = baseline + 你的轻量前端定制` + +### `upgrade/dify-` + +用于处理新版本升级适配。 + +例如： + +- `upgrade/dify-1.13.4` + +这个分支的原则是： + +- 从新的 baseline 分支拉出 +- 在这个分支中把 `main` 的定制重新合进来 +- 专门用于解决冲突、修页面、做验证 + +## 4.4 为什么这个分支模型适合当前阶段 + +这套模型的好处是把三件事拆开了： + +- `baseline`：记录官方原始版本是什么 +- `main`：记录你当前稳定定制版本是什么 +- `upgrade`：记录这次升级是怎么适配的 + +这样做有几个现实好处： + +- 你以后不会搞混“官方基线”和“你的定制版本” +- 升级时不会直接污染 `main` +- 以后回头看某次升级时，更容易知道冲突和改动来自哪里 + +## 4.5 分支命名建议 + +不要使用模糊命名，例如： + +- `dify/1.2.x_baseline` + +更推荐精确版本命名，例如： + +- `baseline/dify-1.13.3` +- `baseline/dify-1.13.4` +- `upgrade/dify-1.13.4` + +原因是： + +- 模糊版本号不利于排查问题 +- 不利于和 README 中记录的版本对应 +- 以后很难快速判断当前分支到底对应哪个官方 tag + +## 5. 定制范围边界 + +## 5.0 结合 Dify 实际目录的定制范围 + +根据 Dify 当前仓库结构，你最可能会接触的是 `web/` 下这些目录： + +- `web/app/` +- `web/app/components/` +- `web/service/` +- `web/hooks/` +- `web/constants/` +- `web/context/` +- `web/i18n/` +- `web/public/` + +其中： + +- `web/app/` 是页面路由和页面组织核心目录 +- `web/app/components/` 是页面组件和基础 UI 组件的重要入口 +- `web/service/` 通常承接前端调用接口的封装 +- `web/i18n/` 和 `web/i18n-config/` 关联国际化内容 + +如果你的目标只是“轻量前端定制”，那你应尽量把改动集中在这些目录，而不是扩散到整个仓库。 + +## 5.1 当前允许的轻量定制 + +建议只在以下范围内修改： + +- 菜单入口 +- 页面导航结构 +- 新增少量业务页面 +- workflow 相关展示页面 +- 结果展示组件 +- AIOps 场景下的说明文案 +- 少量样式调整 + +结合 Dify 当前前端结构，更建议优先改这些地方： + +- `web/app/` 下你新增的页面目录 +- `web/app/components/` 下与你新增页面强相关的组件 +- 少量导航或入口组件 +- 少量 `web/service/` 下的数据读取封装 + +这样做的好处是： + +- 你的改动会更集中 +- 以后升级时更容易定位冲突文件 +- 不容易被 Dify 大量公共组件改动牵连 + +## 5.2 当前不建议做的事情 + +当前阶段尽量不要做以下改动： + +- 修改 Python 后端业务逻辑 +- 修改数据库表结构 +- 修改 Dify 核心 workflow 执行逻辑 +- 修改底层鉴权、任务运行框架、队列机制 +- 大范围重构前端公共基础组件 + +结合 Dify 当前仓库，尤其不建议你现在去碰： + +- `api/` 里的运行逻辑 +- `docker/` 里的部署主逻辑，除非是环境适配 +- `web/package.json` 的大范围依赖调整 +- `web/app/components/base/` 一类全局基础组件的大面积重构 + +原因很简单： + +- 这些改动会显著提高未来升级成本 +- 这些改动也超出了当前“轻量定制”的目标 + +## 5.3 最重要的判断标准 + +以后每做一个改动，都可以先问一句： + +**如果 Dify 升级，我是不是只需要重新适配前端页面？** + +如果答案是“是”，那当前改动通常是安全的。 + +如果答案变成： + +- 还要改 Python +- 还要改数据库 +- 还要改内部运行逻辑 + +那说明这个改动已经开始偏重，需要谨慎。 + +## 6. 推荐的开发流程 + +## 6.1 初始化阶段 + +建议按照以下流程开始： + +1. 从 GitHub 选择一个稳定的 Dify `tag` +2. 将该版本代码放入公司内网 Gitea 仓库 +3. 在 README 中记录当前 Dify 基线版本 +4. 在当前基线上开始轻量前端定制 + +建议在 README 里明确写清楚类似信息： + +- 当前 Dify baseline：例如 `1.13.3` +- 当前定制目录：例如 `web/app/aiops`、`web/app/components/aiops` +- 当前不修改：`api/`、数据库 schema、核心 workflow runtime + +## 6.2 日常开发阶段 + +日常开发时建议： + +- 以当前基线版本为基础 +- 所有新增页面和改动都尽量集中在前端目录 +- 保持改动点尽可能少 +- 尽量避免散落式修改多个不相关页面 + +结合 Dify 官方前端 README，当前前端开发的基本事实也要记住： + +- 前端项目在 `web/` +- 当前前端是 Next.js 项目 +- `web/package.json` 使用 `pnpm` +- `web/package.json` 当前声明的 Node 版本为 `^22.22.1` +- 官方前端 README 提供了 `pnpm run dev`、`pnpm run dev:vinext`、`pnpm run dev:proxy` + +这意味着你后续本地改前端页面时，应该优先围绕 `web/` 这套官方开发方式来跑，而不是自己再造一套目录结构。 + +## 6.3 为什么“集中改动”很重要 + +升级痛苦的根源通常不是“改了前端”，而是“改动散得到处都是”。 + +因此建议： + +- 尽量集中在少数目录 +- 尽量集中在少数页面 +- 尽量把通用 patch 控制在小范围内 + +## 7. 分支策略 + +## 7.1 推荐分支模型 + +建议按下面方式使用分支： + +- `baseline/dify-` + - 官方 tag 的纯净基线快照 +- `main` + - 当前稳定定制版本 +- `feature/...` + - 日常轻量前端功能开发 +- `upgrade/dify-` + - 某次 Dify 升级的适配分支 + +如果当前主线是 Dify `1.13.3`，那么一个典型状态可能是： + +- `baseline/dify-1.13.3` +- `main` +- `feature/aiops-workflow-ui` + +如果准备升级到 `1.13.4`，则新增： + +- `baseline/dify-1.13.4` +- `upgrade/dify-1.13.4` + +## 7.2 为什么升级必须走独立分支 + +因为升级本质上不是普通功能开发，而是： + +- 引入新的上游代码 +- 重新适配已有前端改动 +- 重新验证页面可用性 + +如果直接在 `main` 上升级，很容易把稳定版本打乱。 + +更准确地说，推荐做法是： + +1. 先创建新的 `baseline/dify-` +2. 再从这个新的 baseline 拉出 `upgrade/dify-` +3. 在 upgrade 分支里把当前 `main` 的定制合进来 +4. 在 upgrade 分支里解决兼容问题 +5. 验证通过后再合回 `main` + +## 8. 升级策略 + +## 8.1 什么时候升级 + +不要因为 Dify 发布了新版本就立刻升级。 + +建议只有在以下情况才升级： + +- 需要某个新功能 +- 需要某个关键修复 +- 当前版本存在明显问题 +- 团队决定统一升级基线 + +再补一个很现实的判断条件： + +- 官方 release 明确修复了你实际会碰到的 `workflow`、`knowledge retrieval`、`web` 页面或运行问题 + +## 8.2 升级频率建议 + +建议： + +- 不追 `latest` +- 尽量按明确版本升级 +- 每次升级跨度不要太大 + +例如优先这样升级： + +- `v1.0.3 -> v1.0.5` +- 再视情况评估是否升级到 `v1.1.x` + +## 8.3 升级流程 + +推荐升级流程如下： + +1. 查看 GitHub 上 Dify 新版本 tag +2. 选择目标版本 +3. 创建新的 baseline 分支，例如 `baseline/dify-1.13.4` +4. 在该 baseline 分支中保存新的官方基线代码 +5. 从新的 baseline 分支拉出升级分支，例如 `upgrade/dify-1.13.4` +6. 在 upgrade 分支里把当前 `main` 的定制改动合进来 +7. 解决冲突并重新适配你的前端页面 +8. 本地运行并验证关键页面 +9. 验证通过后把 `upgrade/dify-1.13.4` 合并回 `main` +10. 更新 README 中记录的 Dify 基线版本和 baseline 分支 + +如果你采用的是“把官方 tag 的代码直接放进公司 Gitea”这种方式，那么第 4 步在你这里通常会表现为： + +- 用新的官方 tag 覆盖当前基线代码 +- 再把你自己的前端轻量改动重新适配回来 + +这不是最优雅的 git 方案，但对你当前阶段是可接受的。 + +## 8.3.1 一个完整例子 + +假设你当前状态如下： + +- 当前官方基线：`1.13.3` +- 当前基线分支：`baseline/dify-1.13.3` +- 当前稳定定制分支：`main` + +现在准备升级到 `1.13.4`，推荐流程是： + +1. 新建 `baseline/dify-1.13.4` +2. 把 Dify 官方 `1.13.4` tag 的代码放到这个 baseline 分支 +3. 从 `baseline/dify-1.13.4` 拉出 `upgrade/dify-1.13.4` +4. 在 `upgrade/dify-1.13.4` 上把 `main` 合进来 +5. 处理前端冲突和页面兼容问题 +6. 本地验证通过后，把 `upgrade/dify-1.13.4` 合并回 `main` +7. 更新 README： + - Dify baseline = `1.13.4` + - Baseline branch = `baseline/dify-1.13.4` + +这样做的结果是： + +- 旧基线仍然保留在 `baseline/dify-1.13.3` +- 新基线清晰记录在 `baseline/dify-1.13.4` +- `main` 永远代表“当前稳定可用版本` + +## 8.4 升级的本质理解 + +升级不是“自动同步所有定制”，而是： + +**换一个新的 Dify 上游版本，然后把你那层轻量前端定制重新贴上去。** + +只要这层定制足够薄，升级就不会太痛苦。 + +## 9. 升级时重点检查什么 + +对当前这种轻量定制场景，不需要设计太复杂的验证体系。 + +升级后重点检查以下内容即可： + +- 页面能否正常打开 +- 菜单入口是否正常 +- 新增页面是否还能访问 +- 你修改过的 workflow 相关页面是否还能正常渲染 +- 页面调用的数据接口是否仍然可用 +- 基础流程是否正常 + - 查看 workflow + - 查看结果 + - 查看详情页 + +这本质上就是一次轻量 smoke test。 + +## 9.1 结合 Dify release note 需要特别留意的事项 + +根据 Dify 最近公开 release 的 upgrade guide，后续升级时即使你“不改 Python”，也仍然需要关注这些上游变化： + +- 是否有新的数据库迁移要求 + - 官方 release 中会出现 `uv run flask db upgrade` +- 是否有新的 Python 依赖同步要求 + - 官方 release 中会出现 `cd api && uv sync` +- 是否有 Sandbox 配置变更 + - 例如 release 中提到 Python 和 Node.js 默认路径变化 +- 是否有队列配置要求变化 + - 例如某些版本会要求 `CELERY_QUEUES` 必须包含指定队列 + +这部分非常重要，因为它说明： + +- 你虽然不打算改 Python 代码 +- 但升级整个 Dify 基线时，不能只盯前端页面 +- 仍然要读一下官方 release 的 upgrade guide + +所以你最现实的升级习惯应该是： + +1. 先看 release note +2. 看有没有 backend migration / env 变更 +3. 再做前端适配 +4. 最后一起验证 + +## 9.2 结合 Dify 当前前端结构的检查重点 + +由于 Dify 当前 `web/` 下是 App Router 风格的页面组织，升级时建议重点检查这些位置： + +- `web/app/` 下你新增或修改过的页面目录 +- `web/app/components/` 下你改过的业务组件 +- `web/service/` 下你依赖的数据接口封装 +- `web/i18n/` 下你新增的文案 key +- `web/package.json` 是否有前端主版本依赖升级 + +如果官方 release 里出现下面这些关键词，你要提高警惕： + +- `workflow` +- `web` +- `toast` +- `base ui` +- `knowledge retrieval` +- `streaming` +- `next` +- `react` + +因为这些都很可能直接影响你的页面兼容性。 + +## 10. README 应记录的最小信息 + +建议在 README 中长期保留以下最小信息： + +- 当前 Dify 基线版本 +- 当前 baseline 分支 +- 当前定制范围 +- 当前升级策略 +- 当前 workflow 相关文档入口 + +建议格式示例： + +| 项目 | 当前值 | +| --- | --- | +| Dify baseline | `v1.0.3` | +| Baseline branch | `baseline/dify-1.0.3` | +| Customization scope | `frontend pages, menu, workflow views` | +| Backend policy | `no python customization by default` | +| Upgrade policy | `upgrade in dedicated branch, merge after validation` | + +## 11. 推荐保留的变更记录 + +为了避免以后忘记自己改过什么，建议记录两类信息： + +### 11.1 当前改动范围 + +例如： + +- 修改了哪些前端目录 +- 新增了哪些页面 +- 改了哪些导航入口 + +### 11.2 升级影响记录 + +例如每次升级后记录： + +- 从哪个版本升级到哪个版本 +- 哪些页面需要重新适配 +- 是否发生接口字段变化 +- 是否有已知兼容问题 + +这类记录不需要很长，但会非常有用。 + +建议你把升级记录写得更贴近 Dify 仓库实际结构，例如： + +| 项目 | 记录示例 | +| --- | --- | +| From | `1.13.2` | +| To | `1.13.3` | +| Baseline branch | `baseline/dify-1.13.3` | +| Frontend touched | `web/app/...`, `web/app/components/...` | +| Upstream notes | `workflow editor fix`, `knowledge retrieval fix` | +| Backend actions | `uv sync`, `flask db upgrade` | +| Result | `passed smoke test` | + +这样以后你回头看，会比抽象描述有用得多。 + +## 11.3 建议保留一个“自定义文件清单” + +这个清单非常适合你当前模式。 + +建议维护一个简短列表，记录你实际改过的文件或目录，例如： + +- `web/app/aiops/...` +- `web/app/components/aiops/...` +- `web/app/components/sidebar/...` +- `web/service/...` + +这样以后升级时，你第一时间就知道先检查哪里。 + +## 12. 当前最适合的工程原则 + +结合当前阶段，建议坚持以下原则： + +1. 先把版本固定住，不要追最新。 +2. 先把前端薄定制做好，不要做后端深度二开。 +3. 升级时一定走独立分支。 +4. 升级完成后同步更新 README 和基线版本说明。 +5. 如果未来发现前端定制越来越重，再考虑把更多页面迁到你自己的平台前端。 + +## 13. 什么情况下需要调整当前策略 + +当前这套轻量策略适合“前端轻改 + 后端基本不动”的阶段。 + +当出现下面任一情况时，应考虑升级策略： + +- 你开始频繁修改 Python 后端 +- 你需要控制 Dify 的内部权限或运行逻辑 +- 你需要大量自定义 workflow 管理页面 +- 你发现每次升级都要改很多核心文件 + +如果发生这些情况，说明你已经逐渐从“轻量定制”进入“中度二开”，那时再重新设计仓库与升级策略更合适。 + +## 14. 结论 + +当前阶段，最现实、最省时间、也最适合长期推进的做法就是： + +- 用一个固定 Dify `tag` 做基线 +- 把代码放进公司内网 Gitea +- 只做轻量前端定制 +- 后续如果 Dify 有新版本，就开升级分支重新适配前端改动 +- 验证通过后合并回 `main` +- 最后更新 README 中的基线版本说明 + +这不是最复杂的工程方案，但它是当前最务实、最容易执行、最符合你时间约束的方案。 + +## 15. 参考依据 + +本文主要基于 `https://github.com/langgenius/dify` 官方公开信息整理，重点参考： + +- 根目录结构：`api/`、`web/`、`docker/`、`docs/` +- `web/README.md` +- `web/package.json` +- 官方 release 中的 upgrade guide 与 release notes