add workflow planning docs

2026-03-30 18:01:34 +08:00
parent 32c7c7840d
commit 4c16118712
7 changed files with 1236 additions and 8 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,7 @@
 # AGENTS.md
 <!-- markdownlint-disable MD013 MD022 MD032 -->
 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:
--- 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_Product_Architecture_and_Commercialization.md`](AIOps_Product_Architecture_and_Commercialization.md)：产品架构与商业化主文档
- `AIOps_Practical_Route_Architecture.png`：当前统一参考架构图
+- [`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-<version>`：保存官方基线快照
 - `main`：保存当前稳定定制版本
 - `upgrade/dify-<version>`：处理升级适配和兼容修复
 ## 目录说明
 - `pagerduty/`：PagerDuty 对标拆解、MVP 范围与页面设计文档
 - `workflow/`：`aiops-workflow` 相关需求与设计文档
 ## 使用建议
 - 统一围绕 `AIOps_Practical_Route_Architecture.png` 讨论和更新文档
 - 架构图有较大调整时，同步更新 `AIOps_Architecture_Diagram_Explanation.md`
 - 产品定位、范围、实施路径变化时，同步更新主文档
 - 专题文档优先沉淀到对应目录，并保持 README 快速入口同步
 ## 仓库定位
 - 这是一个文档仓库，不是代码仓库
 - 图中的模块首先表达逻辑职责，不强制等于最终微服务拆分
 - MVP 阶段允许多个模块在实现上合并
 - 新建文件和目录默认使用英文名称，内容可以使用中文
--- a/pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md
+++ b/pagerduty/PagerDuty_Feature_Breakdown_and_Replication_Requirements.md
@@ -845,7 +845,7 @@ PagerDuty 给你的最大启发，不是某个单点功能，而是产品层次
 如果继续往下做，我建议下一份文档直接接这个主题，写成：
- `PagerDuty_MVP_产品需求清单.md`
+- `PagerDuty_MVP_Product_Requirements.md`
 里面把本文件再进一步收敛成：
--- a/pagerduty/PagerDuty_Information_Architecture_and_Page_Design.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 的页面结构、导航方式、
 核心信息组织方式和关键页面布局。
 目标是帮助产品、设计和研发统一以下内容：
--- a/pagerduty/PagerDuty_MVP_Product_Requirements.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 范围。
 本文档重点回答四个问题：
--- a/workflow/AIOps_Workflow_Requirements.md
+++ 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`
 这条链路做稳定、做可审计、做可回归。
--- a/workflow/Dify_Lightweight_Customization_and_Upgrade.md
+++ 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-<version>`
 - `main`
 - `upgrade/dify-<version>`
 这三类分支的职责分别如下。
 ### `baseline/dify-<version>`
 用于保存某个 Dify 官方 tag 对应的纯净基线版本。
 例如：
 - `baseline/dify-1.13.3`
 - `baseline/dify-1.13.4`
 这个分支的原则是：
 - 尽量保持和官方 tag 一致
 - 不放你的业务定制
 - 只作为“官方版本快照”存在
 你可以把它理解成内网里的“官方镜像基线”。
 ### `main`
 用于保存当前稳定可用的定制版本。
 这个分支的原则是：
 - 是团队默认开发和使用的主分支
 - 已经包含你的轻量前端定制
 - 应该始终保持可运行状态
 可以理解为：
 - `main = baseline + 你的轻量前端定制`
 ### `upgrade/dify-<version>`
 用于处理新版本升级适配。
 例如：
 - `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-<version>`
  - 官方 tag 的纯净基线快照
 - `main`
  - 当前稳定定制版本
 - `feature/...`
  - 日常轻量前端功能开发
 - `upgrade/dify-<version>`
  - 某次 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-<version>`
 2. 再从这个新的 baseline 拉出 `upgrade/dify-<version>`
 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