调研对象：feature/agent-architecture-migration 分支（MAF Agent 架构）· 结合 Microsoft Agent Framework 官方文档 · 只读调研，未改动任何代码
项目刚从「固定流水线」迁移到「Agent 自主规划」架构。三个概念一句话区分：
agent_contract_* 表里。agent_plans 表。PlanWorkflow，构建在微软 Agent Framework 之上）真正跑起来的过程——并行调度、断点续跑、逐级审核，最终交付报告。关系一句话：Contract 约束 Plan 的生成 → Plan 冻结后成为 Workflow 的执行图 → Workflow 执行并经过三级质量审核后交付报告。
项目模型层基于微软 Microsoft Agent Framework（Python 包 agent-framework-core==1.11.0）。对照官方文档（learn.microsoft.com/agent-framework），三方边界如下：
| 概念 | MAF 官方提供什么 | PackHorizon 自建了什么 |
|---|---|---|
| Workflow | 图执行引擎原语：WorkflowBuilder / Executor / Edge；按 superstep 并发推进；每个 superstep 边界自动 checkpoint；FileCheckpointStorage 支持断点恢复；@step / @workflow 函数式写法。不含任何业务语义。 |
agent_engine/workflow/engine.py 的 PlanWorkflow：把 PlanSpec 编译成 MAF @workflow 执行图；每个任务包在 MAF @step 里获得天然 checkpoint；首个 step 做 Plan 哈希身份校验防篡改。 |
| Agent 与工具 | Agent(client, instructions, tools)、函数即工具、response_format 结构化输出、middleware 拦截。 |
agent_producer.py 按 Skill 契约组装 Agent；ToolBroker 在调用点强制工具越权检查并落审计。 |
| Plan / Planner | 官方没有内置 Planner / Plan 概念（Semantic Kernel 时代的 Planner 未进入 MAF；仅编排模式 MagenticBuilder 内部有 plan-and-execute，非独立 API）。 | 整个 Plan 层都是项目自建：agent_engine/plan/（模型规划器、确定性校验器、冻结与指纹）+ agent_plans 表 + 规划 API。 |
| Business Contract | 无此概念。 | 完全项目自建：三张 agent_contract_* 表 + 管理后台「Workflow」配置页 + seed 机制。 |
本质：版本化的配置事实，全局只有一份生效（active，由数据库唯一索引保证）。
| 数据表 | 职责 | 关键字段 |
|---|---|---|
agent_contract_versions | 契约版本壳 | version、status（draft / active / superseded） |
agent_contract_project_types | 业务路径（kind × scope 唯一） | kind（new-packaging / upgrade）、scope（full / partial）、planning_policy_json（规划约束：必备交付物、恰好 3 张图、升级必须含差异审查等） |
agent_contract_skill_parts | 该路径允许使用的 Skill 白名单 | skill_name、required、sort_order |
初始数据来源：启动时幂等 seed（agent_configuration/seed.py），来源是内核代码——业务路径来自 agent_engine/plan/project_path.py，规划约束来自 plan/policy.py，Skill 本体来自 9 个内置 SKILL.md（agent_engine/skills/library.py）。
管理端配置入口：后台「Agent 设置 → Workflow」标签页（AdminAgentSettingsPanel.tsx contracts 视图）：Workflow 版本激活/归档、业务路径维护、Skill 组成维护。API：POST /api/v1/agent/contracts/{id}/status、/contracts/{id}/project-types、/project-types/{id}/skill-parts。
本质：AI 为单个项目生成的任务 DAG（PlanSpec：goal、tasks[]、workflowMode、工具授权清单），带完整「出生证明」。
| 项目 | 内容 |
|---|---|
| 数据表 | agent_plans（spec_json 全量计划、plan_hash 防篡改哈希、status、planner_json 规划出处：模型/Skill/Tool/上下文快照 + 六维指纹 + 修复次数） |
| 状态机 | draft → validated → frozen（旧冻结版自动 superseded）；一个 frozen Plan 至多一个 Run |
| 生成 API | POST /api/v1/agent-runtime/projects/{id}/plan（要求需求卡已 frozen） |
| 校验 API | POST .../plan/{planId}/validate（重跑 11 类确定性校验：依赖无环、Skill 在白名单、交付物覆盖、图片数等） |
| 冻结 API | POST .../plan/{planId}/freeze（事务内重算六维指纹逐项比对，任何输入漂移即拒绝冻结） |
| 后端模块 | agent_engine/plan/：model_planner.py（模型起草）、model_planning.py（起草→校验→修复环，最多 3 次模型调用）、dynamic_validator.py、catalog.py（可用技能目录 = 生效 Skill ∩ 契约白名单）、frozen.py、spec.py |
| 管理端查看 | 「Agent 运行」面板打开某次 Run 可看到「动态 Plan」区块（任务列表 + 规划依据 + 校验结果），API：GET /api/v1/agent/plans/{planId}（Skill 正文脱敏为哈希） |
规划方式：模型按 strict schema 起草（只能用目录内 Skill、必须恰好一个终局报告任务、图片数严格按 policy）→ 确定性校验器给出机器可读问题清单 → 回喂模型修复，超限直接明确失败，绝不退回固定模板。
项目中「Workflow」有三个对应物，注意区分：
agent_engine/workflow/engine.py）= 真正的执行体：把冻结 Plan 编译成 MAF @workflow 执行图，Kahn 拓扑分层、同层 asyncio.gather 并行、支持条件分支与质量门循环；每个任务包在 MAF @step 中，配合 FileCheckpointStorage 实现断点续跑（恢复时先核对 Plan 哈希身份，防跨计划注入）。调度链路：创建 Run 只写一条 outbox 记录（agent_run_dispatches，幂等键）→ Celery beat 周期认领（FOR UPDATE SKIP LOCKED）→ agent_execution 队列 → worker 中 RunExecutor 执行。API 不直接跑长任务。
WorkspaceProjectIntakePanel / WorkspaceProjectConfirmationCard；API POST /sessions/{id}/messages、/projects/{id}/card/confirm|freeze。agent_runs，写幂等 outbox。此后配置改动不再影响本次运行。PlanWorkflow 按拓扑分层并行执行；每个任务：确定性预执行必需工具注入真实证据 → MAF Agent 产出结构化结果。每步可 checkpoint，失败可 resume。final_gate：模块覆盖、六方向、图片防伪（从文件字节重算 SHA、生产拒绝非模型来源）。任何一层不过都明确失败，不降级。agent_reports + 六方向 + 图片）→ 发布。用户全程通过 SSE 看到五个公开阶段进度（需求 20% → 规划 40% → 策略 60% → 视觉 80% → 报告 100%）；内部任务/工具/评审事件对用户不可见，仅供管理员。| 时机 | 页面 / 组件 | 用户看到 | 用户能做 | 对应 API |
|---|---|---|---|---|
| 开始 | 工作台「创建方案」WorkspacePage | 新包装方案 / 现有包装优化 | 选类型、开对话 | POST /api/v1/projectsPOST /api/v1/agent-runtime/sessions |
| 需求澄清 | WorkspaceProjectIntakePanel | AI 对话 + 需求卡草稿 | 多轮对话补充信息、上传素材 | POST /sessions/{id}/messages |
| 确认需求 | WorkspaceProjectConfirmationCard | 结构化需求卡（可编辑） | 改字段、点「进入研究」 | GET/PATCH /projects/{id}/card |
| 规划与执行 | 工作台进度区 | 五阶段进度条（Plan 细节不可见） | 等待；失败可重试 | plan / validate / freeze / runs（前端自动串行调用）GET /runs/{id}/events（SSE）POST /runs/{id}/resume |
| 交付 | 报告页 ReportPage | 完整报告、六个设计方向、效果图（前 3 张含图） | 阅读、分享 | GET /runs/{id}/reportGET /runs/{id}/images/{imageId}/content |
{planId, status, ready, summary}，不含 DAG 与内部推理。| 标签页 | 配什么 | 与三概念的关系 | 主要 API |
|---|---|---|---|
| 模型与提供商 | Provider（Base URL、加密密钥、发现模型目录）、模型（text / image 角色、激活、测试） | 决定 Plan 由哪个模型生成、Workflow 由哪个模型执行与评审 | /api/v1/agent/providers*、/models* |
| Skills | Skill 版本（SKILL.md 正文）创建、激活、停用 | Plan 可用的「技能积木」本体 | /api/v1/agent/skills* |
| Tools | 声明式 Tool 上传、测试、启停 | Plan 任务被授权调用的「工具」 | /api/v1/agent/tools* |
| Workflow | Workflow 版本、业务路径、Skill 组成 | 这就是 Business Contract 的配置界面 | /api/v1/agent/contracts*、/project-types/* |
管理员在这里能看到每一次运行的完整内部真相（对用户隐藏的部分）：
GET /api/v1/agent/plans/{planId}）；POST /api/v1/agent/runs/{id}/resume）；GET /api/v1/agent/runs/{id}/timeline）；Plan 冻结时记录模型/Skill/Tool/契约等六维 sha256 指纹；创建 Run 只用冻结快照。管理员改配置不影响进行中的运行；改了模型或密钥后旧 Plan 必须重新生成——每次运行都可审计、可复现。
缺模型、缺契约、校验不过、指纹漂移、图片来路不明——一律明确失败并给出错误码，不用模板顶替、不静默降级。规划修复超限（3 次）即 409。
任务内：Schema 校验 → Skill 规则闸 → 独立 LLM Reviewer（出图任务带图多模态评审）；Run 末：终闸校验模块覆盖与图片防伪（字节级 SHA 复核）。
同一事件流按 visibility 分流：用户只看五阶段进度（SSE，支持断点续传）；管理员看全量内部时间线与工具审计。安全闸 PHMAF_ALLOW_REAL_IMAGE 可全局关闭真实出图。
planning_policy_json）目前主要由 seed 写入，后台界面只能改路径名称/类型/范围。agent-framework-core==1.11.0，官方在线文档对应最新稳定版，个别 API 命名以项目环境内包导出为准。| 类别 | 位置 |
|---|---|
| Plan 内核 | backend/app/agent_engine/plan/（spec / model_planner / model_planning / dynamic_validator / catalog / policy / frozen / project_path） |
| Workflow 内核 | backend/app/agent_engine/workflow/（engine / agent_executor / agent_producer / reviewer / output_gate / tool_broker） |
| Contract 存储 | backend/app/models/agent.py（agent_contract_versions / project_types / skill_parts，另 agent_plans / agent_runs / agent_events 等） |
| 运行域 API | backend/app/domains/agent_runtime/api.py（/api/v1/agent-runtime/*：sessions、card、plan、runs、events） |
| 配置域 API | backend/app/domains/agent_configuration/api.py + management_api.py（/api/v1/agent/*：providers、models、skills、tools、contracts、runs、plans） |
| 异步调度 | backend/app/tasks/agent_tasks.py（dispatch_pending / execute_run / resume_run，队列 agent_execution） |
| 用户端 | frontend/src/components/workspace/（WorkspaceProjectIntakePanel、WorkspaceProjectConfirmationCard、useWorkspaceAgentRuntime、agentReportAdapter） |
| 管理端 | frontend/src/components/admin/（AdminAgentSettingsPanel、AdminAgentRunsPanel）+ frontend/src/lib/agentClient.ts |
| MAF 官方文档 | learn.microsoft.com/en-us/agent-framework（workflows / executors / checkpoints / agents 章节） |