# AI 工单平台设计沟通记录

日期：2026-06-30  
项目目录：`E:\JavaCode\ai-ticket-platform`  
参考旧项目：`E:\JavaCode\finance-it-support`

## 1. 文档目的

本文记录从“现有工单系统 AI 能力增强”到“新建 AI-native 技术支持工单产品”的完整讨论过程。它不是逐字聊天稿，而是面向后续产品设计、架构实现和新会话接管的中文决策日志。

后续回顾某个功能点时，优先按本文的主题章节查找讨论背景，再阅读正式设计文档和实施计划。

相关文档：

| 文档 | 用途 |
|---|---|
| `docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md` | 第一版正式产品与架构设计 |
| `docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md` | 分阶段实施路线图 |
| `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` | 阶段 0 详细实施计划 |

## 2. 初始背景：从现有系统 AI 工单识别开始

最开始的问题是：AI Agent 已经从 prompt 演进到具备一定自主决策能力的 agent，现有项目是否还应该只用工作流实现工单填写和技术支持分析。

对旧项目 `finance-it-support` 做了上下文调研：

| 观察点 | 内容 |
|---|---|
| 当前分支 | `feat_260626_agent` |
| 近期提交 | `feat: 优化AI工单识别回填` |
| 后端 AI 能力 | `IssueWorkOrderServiceImpl#createAiApplicationChat` 根据配置路由到 Dify 或 MaxKB |
| MaxKB 接入 | `AiMaxKbService` / `AiMaxKbServiceImpl` 负责创建会话和发送消息 |
| Dify 接入 | `AiDifyService` 工作流返回 outputs 后解析 JSON |
| 当前能力本质 | 输入描述，调用 Dify/MaxKB，解析 JSON，回填工单草稿字段 |
| 关键限制 | 更像“字段抽取和回填”，还不是完整 Agent |

讨论结论：

现有能力适合继续作为参考，但不应该成为新产品的架构上限。真正有价值的方向是让 AI 围绕工单生命周期进行受控分析、追问、知识检索、方案推荐、沉淀知识和执行审计。

## 3. 第一轮产品方向：建单 Agent 与技术支持 Agent

最初提出两个方向：

| 方向 | 目标 |
|---|---|
| 建单 Agent | 帮用户把问题描述转成完整、规范、可处理的工单 |
| 技术支持分析 Agent | 帮技术人员快速理解问题、查找相似工单、推荐方案、生成排查清单 |

用户反馈：

两者都需要，但建单人员填写工单占比可能更高，因为很多技术问题仍然需要技术人员手动排查，不能完全交给 Agent。

形成的判断：

- 建单侧更适合第一批落地，因为它主要做信息结构化、补全、追问和推荐，风险较低。
- 技术支持侧应定位为辅助分析，不替代人工排查，不默认给最终结论。
- Agent 的价值不是“自动处理一切”，而是减少返工、提升信息质量、缩短技术人员进入排查状态的时间。

## 4. 关键转向：从旧系统增强转为新建长期产品

用户提出新的设想：

新建一个项目，主要目标是技术支持工单。除了工单查询、导出等正常功能外，重点支持配置 Agent、Skill、MCP，并内置向量知识库。后端倾向 Python，AI 接入参考 OpenAI SDK，同时支持自定义渠道的大语言模型、图片理解模型、混合模型和向量模型。

讨论后形成的产品定位：

| 项目定位 | 决策 |
|---|---|
| 产品类型 | 面向技术支持场景的 AI-native 工单系统 |
| 是否通用 Agent 平台 | 否，Agent/Skill/MCP 都围绕工单和知识库服务 |
| 是否旧系统外挂 AI | 否，这是长期新产品 |
| AI 能力边界 | 可配置、可审计、可替换模型，但业务写入默认人工确认 |

## 5. 方案 A 与方案 B：替代旧系统还是 AI 工单中台

讨论了两种路线：

| 路线 | 含义 | 优点 | 缺点 |
|---|---|---|---|
| 方案 A：替代当前系统 | 新 Python 项目负责工单、权限、知识库、AI、审计等全套能力 | 架构干净，适合长期产品化，AI 可以深度嵌入工单生命周期 | 初期成本高，需要重做用户、权限、菜单、审计、基础工单能力 |
| 方案 B：AI 工单中台 | 当前 Java 系统仍是主系统，Python 项目只提供 AI/Agent/知识库能力 | 落地快、风险低、复用现有工单和权限 | 长期体验容易割裂，受旧系统数据模型限制 |

用户最终选择：

选择 **方案 A：替代当前系统**。

用户理由：

- 想做长期新产品。
- 不希望被现有系统结构限制。
- 数据迁移只计划迁移历史工单，其他数据可以重新设计。

对应设计影响：

- 新项目必须独立目录、独立 Git 仓库。
- 不追求旧系统字段完全兼容。
- 历史工单迁移服务于检索、知识沉淀和方案复用，而不是还原旧系统所有业务细节。

## 6. 后端基础框架讨论

用户担心方案 A 初期成本高，尤其是用户、角色、权限、菜单等基础能力，询问是否可以用 GitHub 现有基础框架。

讨论了三条 Python 技术路线：

| 路线 | 判断 |
|---|---|
| Django + Django Ninja | 推荐。Django 自带用户、组、权限、Admin、ORM、迁移，适合企业后台底座；Django Ninja 补 API 和 OpenAPI 能力 |
| FastAPI + SQLAlchemy + SQLAdmin + FastAPI Users | AI 服务体验灵活，但基础后台能力需要拼装，产品底座成本更高 |
| Frappe Framework | 企业 CRUD 和权限很快，但框架约束强，与 PostgreSQL + pgvector 路线不完全一致 |

最终建议：

采用 **Django + Django Ninja + PostgreSQL/pgvector + Celery/Redis + MinIO**。

原因：

- 新产品首先是企业工单系统，不是纯 AI API 服务。
- Django 能显著降低用户、组、权限、后台管理、迁移、审计等基础成本。
- AI 能力可以作为独立模块设计，不和 Django Admin 强绑定。

## 7. 前端框架与 UI 风格讨论

用户表达：

- 前端希望好看一些。
- 可以接受 React，不必须使用 Vue。
- 产品风格更偏企业后台管理系统，因为这是本企业的单独业务场景。
- UI 风格偏简约。

讨论过的前端方向：

| 技术方向 | 判断 |
|---|---|
| Vue 3 + Arco Design Vue | 适合 Vue 团队，后台组件完整，视觉比 Element Plus 更新 |
| Vue 3 + Element Plus | 稳妥但默认视觉较传统，需要额外主题设计 |
| React + Ant Design Pro | 企业后台成熟，但视觉容易偏传统 |
| React + shadcn/ui + Tailwind | 更适合做有设计感的新产品，组件可控性强 |

最终方向：

采用 **React + Vite + Tailwind CSS + shadcn/ui/Radix UI + TanStack Table**。

后续用户进一步强调：

前端应拥有自己的组件库，或基于开源组件库建立自己的产品级组件库。所有新开发 UI 必须先有统一主题标准，再进行业务页面开发。

形成硬性原则：

```text
shadcn/ui / Radix UI / Tailwind
        ↓
产品级 Design System
        ↓
业务组件
        ↓
页面
```

开发规则：

- 不允许业务页面随意写颜色值。
- 不允许每个页面自己定义按钮、状态标签、表格样式。
- 统一主题 token、状态色、优先级色、风险色、表格密度、表单规范。
- AI 面板也必须使用统一的 Agent 执行轨迹、知识引用和方案推荐组件。

## 8. 部署与权限边界

用户确认：

- 当前只做单企业私有化部署。
- 不做多租户 SaaS。
- 用户只需要添加用户组，确保不同角色有不同访问权限。

设计结论：

| 项目 | 决策 |
|---|---|
| 部署形态 | 单企业私有化部署 |
| 租户模型 | 不做租户表，不做租户隔离 |
| 权限模型 | RBAC：用户、用户组、角色、权限点、菜单权限、按钮权限 |
| 企业治理 | 权限和审计一次到位，不作为后期优化项 |

预置角色：

- 系统管理员
- 知识库管理员
- 技术支持
- 普通建单人
- 只读审计员

## 9. MVP 范围选择

提出过三种 MVP 范围：

| 方案 | 内容 | 结论 |
|---|---|---|
| A | 工单主流程 + 建单 Agent + 知识库检索 | 太保守，不能体现完整产品架构 |
| B | 工单主流程 + 建单 Agent + 支持分析 Agent + Agent 配置台 | AI 特征明显，但平台骨架不完整 |
| C | 工单、知识库、模型网关、Agent、Skill、MCP、审计都做基础版本 | 用户选择 |

用户选择 **C：完整平台雏形**。

进一步确认：

- 第一版不是每个模块都做深，而是把系统整体架构布局确定下来。
- 后续只需要针对具体模块优化升级。
- 工单和业务知识库是核心重点。
- AI 平台能力必不可缺，且必须灵活配置，方便尝试不同模型并比较差异。
- 企业后台权限应一步落地。

## 10. 整体架构确定

最终架构从三层扩展为四层：

| 层级 | 职责 |
|---|---|
| 工单业务层 | 工单、分类、状态、处理记录、评论、附件、导入导出、统计 |
| 业务知识库层 | 文档知识、历史工单、解决方案、FAQ、系统手册、排查模板 |
| AI 平台能力层 | 模型渠道、模型配置、Agent、Skill、MCP、向量检索、执行轨迹 |
| 企业后台治理层 | 用户、用户组、角色、菜单权限、按钮权限、操作审计、系统配置 |

核心原则：

```text
工单和知识库是业务资产，
AI 平台是能力放大器，
权限审计是可信边界。
```

关键设计边界：

- Agent 不直接成为业务主表的主人。
- Agent 产生建议、草稿、分析和执行记录。
- 真正改变工单状态、发布知识、确认解决方案，默认需要用户确认。

## 11. 核心模块与 MVP 边界

第一版必须具备完整闭环，但每个模块只做必要深度。

| 模块 | 第一版必须包含 |
|---|---|
| 工单 | 创建、列表、详情、编辑、状态流转、评论、附件、导出、AI 建单辅助、AI 支持分析 |
| 知识库 | 知识分类、文档上传、解析、切片、Embedding、检索、工单转知识草稿 |
| 模型网关 | 供应商配置、OpenAI-compatible 接口、模型类型、默认模型、Agent 级模型选择、模型测试 |
| Agent | 建单 Agent、支持分析 Agent、知识沉淀 Agent |
| Skill | 配置型 Skill，包含 prompt 模板、输入 schema、输出 schema |
| MCP | 服务注册、工具同步、权限控制、工具调用日志、风险等级 |
| 企业后台 | 用户、用户组、角色、菜单权限、按钮权限、操作审计、系统配置 |

明确不做：

- 多租户 SaaS
- 复杂 BPMN 工作流
- 自动派单闭环
- 自动关闭工单
- 任意 Python 代码型 Skill
- 多 Agent 自主协作
- 高风险 MCP 自动执行
- 旧系统字段完全兼容

## 12. 技术架构与服务边界

最终采用模块化单体，而不是一开始拆微服务。

原因：

- 第一版模块多，但数据模型和需求仍在定型。
- 微服务会增加认证、权限、事务、部署、调试和日志复杂度。
- 模块化单体可以先把边界设计清楚，后续再拆 Agent worker、document worker、embedding worker 等重任务模块。

推荐 Django app：

```text
apps/accounts
apps/tickets
apps/knowledge
apps/solutions
apps/modelhub
apps/agents
apps/skills
apps/tools
apps/audit
apps/system
```

关键服务边界：

| 边界 | 决策 |
|---|---|
| 工单服务与模型 | 工单服务不直接调用模型，只发起 AI 分析请求 |
| Agent Runtime | 负责模型、知识库、Skill、工具调用 |
| 知识库 | 同时服务人和 Agent，引用必须可追溯 |
| 模型网关 | 业务层不关心具体供应商 |
| MCP 工具 | 默认受控，需绑定 Agent 权限和审计 |
| Agent 输出 | 默认是建议、草稿和可采纳产物 |

## 13. 数据模型讨论：从宽表到瘦主表

最初的数据模型建议里，`ticket` 主表包含较多字段，例如：

- `legacy_ticket_id`
- `legacy_source`
- `legacy_raw_data`
- `solution`
- `ai_summary`
- `collaborator_ids`

用户指出：

- `legacy_ticket_id` 和 `legacy_source` 不需要，因为这是新系统，不与旧系统匹配。
- 这些字段会让核心表过于臃肿。
- 数据可能堆积，主表不应该什么都放。

修正后的原则：

```text
瘦主表 + 强子表 + AI 产物独立 + 迁移临时化
```

`ticket` 主表只回答：

- 这张工单是什么？
- 当前处于什么状态？
- 谁提出？
- 谁负责？
- 什么时间创建、解决、关闭？

从主表移出的内容：

| 内容 | 目标表或处理方式 |
|---|---|
| 旧系统 ID、旧来源、旧原始 JSON | 仅放临时迁移 staging，不进入正式业务表 |
| 协作人 | `ticket_collaborator` |
| 附件 | `ticket_attachment` |
| 评论 | `ticket_comment` |
| 状态变化和字段变更 | `ticket_event` |
| 解决方案 | `ticket_resolution` 和 `solution` |
| AI 摘要和 AI 建议 | `ticket_ai_artifact` 和 `agent_run` |

## 14. 解决方案复用设计

用户进一步指出：

解决方案很容易重复。同一个问题经常出现时，解决方案通常相同。

因此将“本次处理结果”和“可复用解决方案”拆开：

| 表 | 作用 |
|---|---|
| `ticket_resolution` | 记录某张工单最终怎么处理，属于实例级记录 |
| `solution` | 记录可复用解决方案，属于知识资产 |
| `ticket_solution_link` | 记录工单和解决方案之间的推荐、采纳或参考关系 |

形成的长期价值：

- 高频问题可以自然沉淀。
- Agent 可以推荐已有 solution。
- 技术人员采纳后增加引用关系。
- 可以统计哪些方案最常用、最有效、需要更新。
- 避免每张工单重复复制大段解决方案文本。

## 15. 知识库定位

知识库不是 AI 的附属品，而是和工单同级的业务资产。

知识类型分成两类：

| 类型 | 内容 |
|---|---|
| 文档型知识 | 手册、FAQ、制度、接口文档、日志说明、系统说明 |
| 解决方案型知识 | 从工单处理中沉淀出来的高价值方案 |

知识库必须支持：

- 文档上传
- 文档解析
- 文档切片
- 向量化
- 结构化知识条目维护
- 来源追溯
- Agent 引用来源展示

## 16. Agent、Skill、MCP 边界

用户确认继续进入 Agent、Skill、MCP 设计边界。

最终定义：

```text
Agent = 负责任务目标和决策流程
Skill = 可复用的专业能力模板
MCP = 可调用的外部工具接口
```

内置 Agent：

| Agent | 目标 | 自动写业务数据 |
|---|---|---|
| 建单 Agent | 帮用户补全工单、追问缺失信息、推荐分类和相似工单 | 否 |
| 支持分析 Agent | 帮技术人员生成可能原因、排查步骤、推荐方案和回复草稿 | 否 |
| 知识沉淀 Agent | 从已解决工单生成解决方案草稿和知识条目草稿 | 否 |

Skill 第一版只做配置型：

- 名称
- 描述
- 适用场景
- Prompt 模板
- 输入 schema
- 输出 schema
- 可用知识库和工具范围
- 启用状态

不做代码型 Skill，原因：

- 安全风险高。
- 沙箱复杂。
- 权限边界难。
- 审计和回滚成本高。

MCP 第一版原则：

| 原则 | 说明 |
|---|---|
| 只读优先 | 先接日志、监控、CMDB、文档等查询类工具 |
| 工具授权 | Agent 只能调用绑定过的工具 |
| 风险分级 | low、medium、high |
| 高风险确认 | 修改配置、执行命令、重启服务等不进入 MVP，或必须人工确认 |
| 全量审计 | 每次调用进入 `tool_call` 和 `agent_step` |

## 17. 前端产品形态

前端定位：

简约、有设计感的企业 AI 工单工作台。

不是传统蓝白后台，也不是聊天工具。核心是让技术支持人员快速理解工单、处理工单、复用知识，并可信地使用 Agent。

导航分组：

```text
工作台
工单
知识库
解决方案
Agent
模型与工具
系统管理
```

最重要的三个体验：

| 体验 | 说明 |
|---|---|
| 工单详情 + AI 支持分析 | 在一个页面中查看工单、评论、附件、相似工单、推荐方案、AI 排查建议和引用来源 |
| 创建工单 + 建单 Agent | 用户输入自然语言和截图，Agent 生成字段草稿、追问缺失信息、推荐分类和相似问题 |
| 模型/Agent 配置与调试 | 管理员配置模型渠道，对比模型效果，调整 Agent、Skill、知识库和工具权限 |

设计系统要求：

- 先建立主题 token，再开发业务页面。
- 所有业务页面必须使用项目封装组件。
- AI 面板不是普通聊天框，而是结构化分析面板。
- Agent 执行过程、知识引用、方案推荐必须有统一组件。

## 18. 开发阶段拆分

最终阶段拆分：

| 阶段 | 名称 | 目标 |
|---|---|---|
| 阶段 0 | 产品骨架与设计系统 | 项目初始化、后端/前端底座、RBAC、审计、主题和组件标准 |
| 阶段 1 | 工单主流程 | 工单闭环、评论、附件、事件、导出、解决方案复用 |
| 阶段 2 | 知识库与向量检索 | 文档上传、解析、切片、Embedding、检索、知识条目 |
| 阶段 3 | 模型网关与 Agent/Skill | 模型供应商、模型测试、多模型对比、Skill、内置 Agent、执行轨迹 |
| 阶段 4 | MCP 工具与企业可信边界 | MCP 注册、工具同步、风险等级、Agent 工具调用、人工确认 |
| 阶段 5 | 历史工单迁移与产品打磨 | 历史工单导入、向量化、解决方案/知识草稿、统计和试运行打磨 |

用户确认认可该阶段划分。

## 19. 新项目仓库创建

用户提出：

这是一个新项目，不希望污染当前项目目录。应新建工程目录，并且所有代码都应该适应 Git 作为版本管理。

实际执行：

| 项目 | 内容 |
|---|---|
| 新目录 | `E:\JavaCode\ai-ticket-platform` |
| Git 仓库 | 已执行 `git init` |
| 当前分支 | `master` |
| 旧项目影响 | 未修改 `finance-it-support` 中既有变更 |

已提交：

| Commit | 内容 |
|---|---|
| `3a5953c docs: add AI ticket platform design` | 创建 README、`.gitignore` 和正式设计文档 |
| `cd20d59 docs: add implementation roadmap and stage 0 plan` | 创建实施路线图和阶段 0 详细计划 |

## 20. 正式设计文档产出

正式设计文档保存到：

```text
docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md
```

文档内容包括：

- 产品定位
- 核心原则
- 四层架构
- MVP 范围
- 推荐技术栈
- 数据模型基线
- Agent/Skill/MCP 边界
- 前端产品形态
- 设计系统要求
- 开发里程碑
- 历史工单迁移
- 第一版架构验收标准
- 未决问题

## 21. 实施计划产出

总路线图保存到：

```text
docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md
```

阶段 0 详细计划保存到：

```text
docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md
```

阶段 0 计划目标：

建立可运行项目底座，包括：

- Django 后端项目
- Django Ninja API root
- health endpoint
- accounts/audit/system app
- 权限种子命令
- audit model 和 API
- Vite React 前端
- Tailwind 主题 token
- 产品组件预览页
- Docker Compose 本地运行环境
- `.env.example`
- 本地启动文档

## 22. 当前已经明确的产品约束

| 主题 | 约束 |
|---|---|
| 产品形态 | 单企业私有化部署 |
| 长期路线 | 新产品替代旧系统，不做 AI 中台外挂 |
| 数据迁移 | 只迁历史工单，不迁旧权限和旧组织结构 |
| 工单表 | 瘦主表，避免堆积 |
| 解决方案 | 通用 solution 独立，工单通过 link 复用 |
| 知识库 | 与工单同级，是核心业务资产 |
| Agent | 默认只建议和生成草稿，不自动写业务数据 |
| Skill | MVP 只做配置型，不做代码型 |
| MCP | 只读优先，高风险工具不自动执行 |
| 权限 | RBAC、用户组、菜单权限、按钮权限一步落地 |
| 前端 | React 可接受，必须先有统一设计系统 |
| UI 风格 | 简约、有设计感、企业后台 |
| 版本管理 | 新项目独立 Git 仓库 |

## 23. 后续新会话接管建议

建议新会话按以下顺序读取：

1. `README.md`
2. `docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md`
3. `docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md`
4. `docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md`
5. `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md`

如果要开始编码，建议从阶段 0 计划执行，并遵守计划文档顶部说明：

- 使用 `superpowers:subagent-driven-development` 或 `superpowers:executing-plans`
- 按 task 逐项执行
- 每个可验证任务单独提交
- 不跳过测试和构建验证

## 24. 当前未决问题

| 问题 | 当前状态 | 建议处理时机 |
|---|---|---|
| 主键使用 bigint 还是 uuid | 尚未最终决定 | 阶段 0/1 建模前决定 |
| 前端是否保留 Vite 还是改 Next.js | 当前倾向 Vite | 阶段 0 开始前确认即可 |
| 代码型 Skill | MVP 不做 | 第二阶段以后重新评估沙箱 |
| 高风险 MCP 工具 | MVP 不做自动执行 | MCP 阶段再设计确认流 |
| 工作流引擎 | MVP 只做简单状态流转 | 如果 SLA/升级复杂再引入 |

## 25. 复盘结论

本次讨论完成了三个关键收敛：

1. 从“旧系统 AI 增强”收敛为“新建长期 AI-native 技术支持工单产品”。
2. 从“AI 功能堆叠”收敛为“工单 + 知识库 + AI 平台 + 企业治理”的四层架构。
3. 从“泛泛方案”落地为独立 Git 仓库、正式设计文档、实施路线图和阶段 0 执行计划。

后续重点不再是继续扩大愿景，而是从阶段 0 开始把项目底座、设计系统和可运行开发环境做扎实。