笔言: 这是一次关于“AI如何更好地传授复杂知识”的探索。我们选择TOGAF这一成熟框架作为“试金石”，利用AutoAgent技术打造了一个多角色互动的虚拟课堂。TOGAF仅是起点，我们已验证的核心架构，能够灵活承载更多领域的专业知识，开启智能化专业培训的新模式；

TOGAF专家视角：关于“基于AutoAgent的TOGAF多角色互动教学平台”的正式立项建议书

---

1. 项目背景与问题陈述

TOGAF作为企业架构的权威框架，其知识体系庞大，角色分工精细，传统学习方式存在显著痛点：

• 角色理解抽象：学员难以在孤立阅读中体会“业务架构师”、“解决方案架构师”等角色在实际企业环境中的互动、权衡与协作。
• 方法论与实践脱节：ADM循环、制品、元模型等核心概念静态枯燥，缺乏动态、情境化的应用演示。
• 学习反馈滞后：缺乏一个能够即时提供多角度专业反馈、模拟评审与辩论的互动环境。

2. 项目愿景与目标

愿景：构建一个由AI多智能体驱动的、高度情境化的TOGAF互动教学与演练平台，使学员如同置身于一个真实的虚拟企业架构团队中学习。
核心目标：

1. 角色化情境理解：通过专属智能体角色，深度解析TOGAF中各类架构师的职责、视角和工作产出。
2. 动态流程推演：将ADM各阶段转化为可交互、可决策的模拟过程，展示输入、输出与角色间的动态协作。
3. 个性化能力评估：提供基于TOGAF标准的模拟评审、问答与案例练习，并给予符合角色视角的针对性反馈。

3. 项目范围与核心交付物

• 交付物一：TOGAF多智能体知识引擎
  • 基于TOGAF 10标准及官方指南，构建结构化、可追溯的知识图谱。
  • 为每个核心角色（业务/数据/应用/技术架构师、架构治理者、项目群经理等）定义专属的系统提示词、职责边界和交互协议。
• 交付物二：多角色互动教学场景库
  • 场景1：ADM阶段引导式演练。针对特定阶段（如Phase B业务架构），由主控智能体协调，相关角色智能体依次介入，讲解其贡献的制品（如业务场景、架构愿景）。
  • 场景2：架构制品评审会。学员提交一份架构定义文档草案，由不同角色的智能体分别从业务一致性、技术可行性、合规性等角度进行模拟评审并提出修改意见。
  • 场景3：认证模拟与答疑。智能体扮演考官与教练，进行真题解析、模拟考试，并对错误答案从多角度进行剖析。
• 交付物三：可扩展的AutoAgent平台集成模块
  • 提供与主流AutoAgent框架（如AutoGen, CrewAI）的集成方案，使智能体角色能稳定协作并调用工具（如绘图、文档生成）。

4. 专业可行性分析（业务与技术视角）

• 业务架构视角（必要性）：本项目直接针对TOGAF学习中的核心业务需求——提升架构思维与协作能力，而非单纯记忆知识。它解决了“能力转化”这一高阶培训目标，市场区分度显著。
• 技术架构视角（可行性）：
  • 技术栈成熟：多智能体框架、大语言模型API、知识图谱技术均已达到商用成熟度。
  • 模式已验证：TOGAF官方Eagle AI助理已初步验证“角色化AI答疑”模式的用户接受度。本项目将其深化为“多角色协作互动”，是模式的自然演进。
  • 风险可控：主要风险在于智能体“幻觉”可能导致知识错误。缓解措施为建立严格的知识溯源机制，所有关键论述需锚定至TOGAF官方文本段落，并提供引用来源。

5. 初步实施路线图（基于ADM思维）

1. 预备阶段：成立项目，明确项目愿景、范围与治理结构。
2. 架构愿景（Phase A）：详细定义各智能体角色描述、核心交互场景与平台功能蓝图。
3. 业务/信息系统架构（Phase B/C）：
   • 业务架构：优先开发“业务架构导师”与“ADM流程引导员”智能体，覆盖ADM前期核心。
   • 信息系统架构：开发“数据/应用架构导师”智能体，并构建基础的知识图谱。
4. 技术架构与实施（Phase D-E）：
   • 完成“技术架构导师”等全部角色智能体开发。
   • 集成多智能体协作引擎，实现场景化对话流程。
5. 迁移规划与治理（Phase F-G）：
   • 内测与迭代，基于反馈优化智能体交互逻辑与知识准确性。
   • 建立架构治理机制，即对智能体输出的知识质量进行持续审计与更新的流程。
6. 变更管理（Phase H）：制定平台运营与知识库迭代的长期计划。

6. 成功度量标准

• 学习效果指标：学员在模拟架构评审中的决策合理度提升、认证考试模拟通过率。
• 系统能力指标：智能体角色交互的准确性与流畅度、知识回溯的准确率。
• 用户体验指标：学员对“角色情境代入感”和“知识理解深度”的正面反馈率。

7. 结论与建议

从TOGAF专业视角看，此项目并非简单的技术应用，而是一次 “以企业架构思维构建企业架构学习工具” 的深度实践。它极具先进性与示范价值。

建议：批准立项，并成立一个由TOGAF专家、AI工程师和教学设计师组成的跨界项目团队，采用敏捷架构开发模式，尽快启动原型开发，首先在ADM预备阶段至Phase A（架构愿景）的互动推演上实现突破，验证核心价值。

---

TOGAF专家兼架构师
（此立项书遵循TOGAF架构开发方法的精神，将项目本身视为一次架构实践，确保目标、交付物与治理结构清晰可执行。）

---

TOGAF多角色互动教学平台——软件详细设计文档

文档编号: SDD-TOGAF-AGENT-20231028
版本: 1.0
技术栈: RuoYi-Vue3-FastAPI + AutoGen/CrewAI + RAG
目标: 指导AI编程工具生成符合企业级标准的可执行代码
首席架构师: 李林/首席技术架构师
日期: 2025年12月26日

---

第一章：项目总览与架构映射

1.1 项目目标转换（TOGAF ADM到技术实施）

本项目是以TOGAF架构开发方法构建TOGAF教学工具的元架构实践。基于RuoYi-Vue3-FastAPI（简称RY框架）这一成熟脚手架，我们将ADM阶段映射为具体的开发阶段：

• 预备阶段 ➔ 本设计文档，确立技术愿景、原则与治理。
• 架构愿景（A） ➔ 第2、3章，定义业务场景与系统功能。
• 业务架构（B） ➔ 第4章，设计核心业务流程与角色交互。
• 信息系统架构（C） ➔ 第5、6章，设计应用架构（模块）与数据架构（数据库）。
• 技术架构（D） ➔ 第7章，定义API、组件与集成技术栈。
• 实施与治理（E-H） ➔ 第8、9章，制定部署、安全与演进规范。

1.2 技术架构总览

平台采用前后端分离与AI微服务混合架构。RY框架处理传统CRUD与用户会话，AI Agent引擎作为独立的智能服务层。

第二章：核心业务功能模块设计（AI指导）

2.1 模块一：TOGAF角色智能体管理中心

AI编程指导： 在ry-module-system基础上，创建新模块ry-module-agent-center。

1. 智能体角色定义管理

   • 数据表设计指导：
     • 表名: togaf_agent_definition
     • 字段要求:
       • agent_key (VARCHAR，唯一标识，如 business_architect)
       • agent_name (VARCHAR，角色名，如 业务架构导师)
       • system_prompt (TEXT，定义角色、职责、语气的完整Prompt)
       • capabilities (JSON，描述技能，如 ["业务建模", "利益相关者分析"])
       • knowledge_boundary (TEXT，知识边界描述)
       • base_llm_config (JSON，默认使用的LLM模型及参数)
       • is_active (BOOLEAN，是否启用)
   • AI生成代码任务：
     • 生成此表的SQL DDL语句。
     • 生成FastAPI的Pydantic模型（用于请求/响应验证）。
     • 生成CRUD API接口：/agent/definition/{create, update, list, detail}。
     • 生成前端Vue3页面：包含表单（支持Markdown编辑system_prompt）和列表。

2. 智能体会话实例管理

   • 业务逻辑: 用户开始一个教学场景时，根据场景需求，从定义库中实例化多个Agent，形成一次专属会话。
   • 数据表设计指导:
     • 表名: togaf_agent_session
     • 字段要求:
       • session_id (UUID，主键)
       • scene_id (关联教学场景)
       • agent_list (JSON，本次会话启用的agent_key列表及配置)
       • conversation_history (TEXT或外链，存储对话历史，建议仅存元数据)
       • status (ENUM, ‘running’, ‘paused’, ‘ended’)
   • AI生成代码任务:
     • 生成FastAPI服务层函数 AgentSessionService.create_session(scene_config)。
     • 函数逻辑：接收场景配置 -> 查询togaf_agent_definition表 -> 组装Agent配置 -> 调用底层Agent引擎初始化会话 -> 返回session_id。

2.2 模块二：结构化知识库与RAG引擎

AI编程指导： 创建新模块ry-module-knowledge-base。

1. TOGAF知识源管理

   • 数据表设计指导:
     • 表名: togaf_knowledge_source
     • 字段要求:
       • doc_id (VARCHAR，如 TOGAF10-4.2-BusinessArch)
       • doc_title (VARCHAR)
       • doc_type (ENUM, ‘official_standard’, ‘white_paper’, ‘case_study’)
       • content_hash (VARCHAR，用于去重)
       • raw_file_path (VARCHAR)
       • chunk_count (INT)
   • AI生成代码任务:
     • 开发一个KnowledgeIngestionService。
     • 核心函数ingest_pdf(file_path, metadata)：调用PyPDF2或pdfplumber解析PDF -> 使用langchain.text_splitter.RecursiveCharacterTextSplitter进行智能分块 -> 为每个文本块生成向量嵌入（调用OpenAI Embeddings API） -> 将向量和元数据存入向量数据库（Chroma）-> 在关系表togaf_knowledge_source中记录元数据。

2. 混合检索服务

   • AI生成代码任务:
     • 创建HybridRetrievalService。
     • 函数retrieve(query, agent_role, top_k=5):
       a. 向量检索: 使用查询文本的向量，在向量数据库中搜索相似块。
       b. 角色过滤: 根据agent_role，在元数据中过滤与该角色最相关的文档类型（如技术架构师优先检索技术架构章节）。
       c. 关键词增强: 并行执行一次基于Elasticsearch或数据库全文索引的关键词检索，作为补充。
       d. 结果重排: 使用简单规则（如向量相似度权重0.7 + 角色相关度权重0.3）对结果进行重排，返回top_k个最相关的文本块及准确的原文引用位置（章节、页码）。

2.3 模块三：多角色互动教学场景引擎

AI编程指导： 创建核心模块ry-module-scene-engine。

1. 场景定义与流程编排

   • 数据表设计指导:
     • 表名: togaf_teaching_scene
     • 字段要求:
       • scene_key (VARCHAR，如 adm_phase_b_walkthrough)
       • scene_name (VARCHAR)
       • description (TEXT)
       • scene_graph (JSON，定义场景流程的状态机或流程图)
       • required_agents (JSON，默认需要的角色列表)
   • 场景图（JSON）示例:

     {
       "start": "phase_b_intro",
       "states": {
         "phase_b_intro": {
           "agent": "process_guide",
           "message": "欢迎来到ADM阶段B（业务架构）。我们的目标是...",
           "transitions": [
             {"trigger": "user_input", "condition": "contains('业务能力')", "next": "biz_capability_discussion"},
             {"trigger": "auto", "timeout": 30, "next": "biz_capability_discussion"}
           ]
         },
         "biz_capability_discussion": {
           "agent": "business_architect",
           "action": "call_retrieval", // 触发知识检索
           "transitions": [
             {"trigger": "agent_response", "condition": "completed", "next": "invite_tech_architect"}
           ]
         }
       }
     }
     

   • AI生成代码任务:
     • 设计一个SceneStateMachine类，能够加载并解释上述JSON格式的场景图。
     • 实现状态流转逻辑，根据trigger和condition决定下一步状态，并调用指定的Agent进行响应。

2. 多智能体对话编排器

   • AI编程指导： 这是集成AutoGen/CrewAI的核心。
   • 使用CrewAI的指导思路:
     a. 创建Agent Crew: 基于togaf_agent_definition表中的system_prompt，为每个激活的角色动态创建CrewAI Agent对象。
     b. 定义Tasks: 根据当前场景状态，将用户问题或预设目标转化为CrewAI Task。例如，任务描述为：“作为业务架构师，向学员解释‘业务能力矩阵’的概念，并举例说明。”
     c. 流程执行: 使用Crew对象的kickoff()方法执行任务。在config中为每个Agent设置llm和tools参数，其中必须包含HybridRetrievalService作为核心工具，确保回答基于TOGAF知识库。
     d. 结果处理: 捕获每个Agent的输出，将其格式化为前端可展示的对话消息，并关联引用的知识来源。
   • AI生成代码任务:
     • 编写AgentOrchestratorService，其核心函数process_turn(session_id, user_input)：
       1. 根据session_id获取会话状态和场景图。
       2. 判断当前状态，决定由哪个或哪些Agent响应。
       3. 动态组装CrewAI Agents和Tasks。
       4. 执行Crew，获取结果。
       5. 更新会话历史与状态。
       6. 返回结构化的响应{speaker_agent, message, citations: [...], next_state}。

第三章：数据库详细设计（AI指导）

3.1 核心实体关系图（ERD）指导

AI提示： 根据以下描述，生成完整的MySQL 8.0兼容的DDL语句。

-- 1. 用户与场景核心表 (基于RY框架的sys_user扩展)
CREATE TABLE `togaf_learning_scenario` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `user_id` BIGINT NOT NULL COMMENT '关联sys_user.id',
  `scene_key` VARCHAR(100) NOT NULL COMMENT '场景标识',
  `title` VARCHAR(255) NOT NULL COMMENT '学习任务标题',
  `current_state` VARCHAR(100) COMMENT '当前场景状态节点',
  `agent_session_id` CHAR(36) COMMENT '关联的智能体会话ID',
  `status` VARCHAR(20) DEFAULT 'in_progress',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (`user_id`) REFERENCES `sys_user`(`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户学习场景实例';

-- 2. 对话历史记录表（与会话分离，便于追溯）
CREATE TABLE `togaf_dialogue_turn` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `session_id` CHAR(36) NOT NULL COMMENT '关联agent会话',
  `turn_index` INT NOT NULL COMMENT '对话轮次序号',
  `speaker_type` ENUM('user', 'agent', 'system') NOT NULL,
  `speaker_agent_key` VARCHAR(100) NULL COMMENT '若speaker为agent，则记录其key',
  `message_content` TEXT NOT NULL,
  `citations` JSON NULL COMMENT '引用的知识片段，格式：[{"doc_id":"...", "excerpt":"..."}]',
  `metadata` JSON NULL COMMENT '附加信息，如LLM调用参数',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX `idx_session_turn` (`session_id`, `turn_index`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='对话轮次明细';

第四章：关键API接口设计（AI指导）

4.1 会话管理API

AI编程指导： 在FastAPI的router/agent中创建以下端点。

1. POST /api/agent/sessions

   • 描述: 初始化一个新的多角色教学会话。
   • 请求体 (JSON):

     {
       "scene_key": "adm_phase_b_walkthrough",
       "custom_parameters": {
         "business_domain": "金融保险"
       }
     }
     

   • AI生成代码任务:
     • 创建Pydantic模型SessionCreateRequest。
     • 实现路由函数：验证场景 -> 调用AgentSessionService.create_session() -> 调用SceneStateMachine.initialize() -> 返回{“session_id”: “…”, “welcome_message”: “…”}。

2. POST /api/agent/sessions/{session_id}/turn

   • 描述: 提交用户输入，获取智能体团队的响应。
   • 请求体:

     { "user_message": "业务能力如何映射到应用系统？" }
     

   • AI生成代码任务:
     • 实现路由函数：调用AgentOrchestratorService.process_turn(session_id, user_message)。
     • 关键逻辑: 处理过程中，必须将本次user_message和返回的agent_response作为一个完整的对话轮次（Turn），记录到togaf_dialogue_turn表中，并存储citations。

第五章：前端组件设计指导（Vue3 + TypeScript）

5.1 多角色对话界面组件

AI编程指导： 在src/views/togaf目录下创建AgentDialogueView.vue。

• 组件结构：

  <template>
    <div class="dialogue-container">
      <!-- 左侧：角色面板 -->
      <div class="agent-panel">
        <div v-for="agent in activeAgents" :key="agent.key" class="agent-avatar">
          <el-avatar :src="agent.avatar">{{ agent.name[0] }}</el-avatar>
          <span>{{ agent.name }}</span>
        </div>
      </div>
      <!-- 中间：对话主区域 -->
      <div class="dialogue-history">
        <div v-for="turn in history" :key="turn.id" :class="['message-bubble', turn.speaker_type]">
          <div class="message-header">
            <strong>{{ getSpeakerName(turn) }}</strong>
            <el-button v-if="turn.citations" size="mini" @click="showCitations(turn)">查看依据</el-button>
          </div>
          <div class="message-content" v-html="formatMessage(turn.message_content)"></div>
        </div>
      </div>
      <!-- 右侧：当前场景状态与知识卡片 -->
      <div class="context-panel">
        <SceneStateVisualizer :state="currentState" />
        <KnowledgeCard v-if="activeCitation" :citation="activeCitation" />
      </div>
      <!-- 底部：输入框 -->
      <div class="input-area">
        <el-input v-model="userInput" placeholder="向架构师团队提问..." @keyup.enter="sendMessage"/>
        <el-button type="primary" @click="sendMessage">发送</el-button>
      </div>
    </div>
  </template>
  

• AI生成代码任务：
  • 使用Composition API (<script setup lang="ts">) 编写组件逻辑。
  • 实现sendMessage函数：调用POST /api/agent/sessions/{session_id}/turn，将返回的响应添加到history响应式数组中。
  • 实现formatMessage函数，将Agent返回的Markdown内容安全地渲染为HTML。

第六章：安全性、性能与部署指导

6.1 安全设计（集成到RY框架）

• 身份认证与授权： 复用RY的JWT认证。所有/api/agent/*接口必须要求有效Token。在router中使用depends(get_current_user)。
• Agent访问控制： 在AgentOrchestratorService中增加检查，确保用户只能访问自己创建的会话(session_id关联的user_id与当前用户匹配)。
• Prompt注入防护： 对用户输入进行基础的恶意指令检测和长度限制，避免其篡改Agent的system_prompt。

6.2 性能优化指导

• Agent会话缓存： 使用Redis缓存活跃的AgentOrchestrator实例和会话状态，避免每次对话轮次都重新初始化CrewAI。
• LLM调用异步化： FastAPI端点使用async/await，LLM API调用使用httpx.AsyncClient，避免阻塞。
• 向量检索优化： 为Chroma配置持久化存储和索引，对高频查询的知识块进行缓存。

6.3 容器化部署指导

AI编程指导： 基于RY的Docker配置进行扩展。

• 编写多服务docker-compose.yml:

  version: '3.8'
  services:
    backend:
      build: ./backend
      ports:
        - "8000:8000"
      depends_on:
        - redis
        - chromadb
    frontend:
      build: ./frontend
      ports:
        - "80:80"
    chromadb:
      image: chromadb/chroma
      volumes:
        - chroma_data:/chroma/chroma
    redis:
      image: redis:alpine
  volumes:
    chroma_data:
  

第七章：AI编程工具的具体指令示例

目标： 指导AI生成AgentOrchestratorService的核心函数。

指令示例：
“请用Python编写一个AgentOrchestratorService类中的_create_crewai_crew方法。该方法输入参数为：agent_definitions: List[Dict]（来自数据库的角色定义列表）和task_description: str（当前任务描述）。请使用CrewAI库，为每个agent_definitions创建一个Agent对象，其role、goal、backstory从system_prompt中解析。然后创建一个Task，其描述为task_description。最后，将这些Agent和Task组装成一个Crew对象并返回。请确保为每个Agent配置一个Tool，这个Tool是一个能调用HybridRetrievalService.retrieve的函数，用于知识检索。”

---

结论与交付物清单
本设计文档将TOGAF方法论、多智能体协作模式与RuoYi-Vue3-FastAPI企业级框架深度结合，提供了从概念到可执行代码指令的完整蓝图。

AI编程工具应交付的代码文件清单：

1. 后端 (backend/app/)：
   • models/togaf_*.py (Pydantic及SQLAlchemy模型)
   • service/agent_center_service.py
   • service/knowledge_retrieval_service.py
   • service/agent_orchestrator_service.py (集成CrewAI)
   • router/togaf_agent.py
   • router/togaf_knowledge.py
2. 前端 (frontend/src/views/togaf/)：
   • AgentDialogueView.vue
   • AgentManagement.vue
   • KnowledgeBaseManagement.vue
3. 数据库迁移脚本 (backend/alembic/versions/)。
4. 更新的 docker-compose.yml 和 Dockerfile。

请AI编程工具根据以上结构化指导，按模块顺序生成符合RuoYi-Vue3-FastAPI编码规范、具备完整类型注解、错误处理和日志记录的生产级代码。每一段生成的代码都应确保与TOGAF知识权威性、多角色协作逻辑以及企业级应用的安全性、性能要求严格对齐。

---

UI设计初稿(用户端)截图:





UI设计初稿(后台管理端)截图:

版权声明
TOGAF多角色互动教学平台——软件详细设计文档与UI设计 © [李林] [2025]。

本作品采用 知识共享 署名-非商业性使用 4.0 国际许可协议 进行授权。
这意味着您可以：

• 在注明原作者并附上原文链接的前提下，免费分享、复制本文档与设计。
• 在个人学习、研究或非营利项目中基于此进行再创作。

这意味着您不可以：

• 将本作品或衍生作品用于任何商业目的，包括企业培训、商业产品开发、宣传性质等。

如需商业用途或宣传性质授权，请务必事先联系作者。
作者联系方式：[1357759132@qq.com]