# 01_Agent_MCP_轻后台架构原则｜灵犀造物

## 一、本轮新增核心判断

灵犀造物不是一个传统意义上让用户每天登录、逐层点击的大型 Web 后台系统。

它的主要使用入口应当是：

```text
人 ↔ 飞书机器人 Hermes / Agent ↔ MCP 工具层 ↔ 后台服务 / 数据库 / 文件资产 / 单页面前端
```

也就是说：

- 用户日常不是先打开一个复杂后台，再找功能；
- 用户更多是在飞书里和 Hermes 对话；
- Hermes 根据用户意图调用对应的 Skill / MCP 工具 / 后台接口；
- 当确实需要人工查看、选择、标注、确认时，再把用户带到一个轻量、离散的单页面；
- 后台、表结构、状态机、权限、任务队列仍然是系统底层核心，不能因为入口是 Agent 就弱化。

## 二、交互形态：Agent 优先，轻页面辅助

### 2.1 主要入口

主要入口不是大型后台首页，而是飞书机器人对话。

典型触发方式：

```text
“帮我采集这个产品灵感”
“把这些图放进灵感库”
“基于这个方向出几版 AI 图”
“把这张图转成建模打样需求”
“查看这个产品现在打样到哪一步了”
“把这轮样品打回修改”
“提交最终审批”
```

Agent 负责理解用户意图，然后调用结构化工具完成动作。

### 2.2 页面入口

网页界面采用“离散型单页面”思路：

- 每个页面只解决一个具体业务动作；
- 页面可通过机器人发送链接打开；
- 链接最好带上下文参数，例如产品项目 ID、任务 ID、审批 ID、打样轮次 ID；
- 用户不需要进入一个复杂后台再寻找入口；
- 页面完成动作后，结果回写后台，并可由机器人继续通知或推进下一步。

示例：

```text
用户：我要看一下这个产品的 AI 图备选
Hermes：发送 “AI 图筛选页” 链接
用户打开页面：勾选/淘汰/备注
页面提交后：后台记录结果
Hermes：继续询问是否转建模需求
```

## 三、前后端项目结构原则

虽然页面入口是离散的，但工程结构仍应保留前后端分离。

建议结构：

```text
lingxi-zaowu/
├── backend/                 # 后台 API、业务逻辑、数据库模型、任务队列
├── frontend/                # 前端单页应用集合，不是一个复杂后台入口为主
├── mcp-server/              # 面向 Agent 的 MCP Server 封装
├── skills/                  # Hermes/Agent 可加载的业务 Skill 说明
├── docs/                    # PRD、流程、表结构、接口说明
└── storage/                 # 本地开发用文件资产目录，生产可替换为对象存储
```

前端可以是一个项目，但内部按“单页面工具”组织：

```text
frontend/pages/
├── inspiration-capture/     # 灵感采集页
├── inspiration-review/      # 灵感筛选页
├── ai-image-review/         # AI 图筛选页
├── model-brief/             # 建模需求确认页
├── sample-feedback/         # 样品反馈/标注页
├── progress-board/          # 产品进度看板页
└── approval-review/         # 最终审批页
```

这些页面不一定都出现在统一导航里，更多是被 Agent 根据上下文发送给用户。

## 四、MCP 层定位

MCP 层不是简单把后台 API 原样暴露给 Agent，而是把后台能力封装成适合 Agent 调用的“业务动作工具”。

### 4.1 MCP 工具设计原则

MCP 工具应该：

1. 输入结构清晰，避免让 Agent 拼复杂参数；
2. 返回结果可读，适合 Agent 继续对话；
3. 具备幂等性，避免 Agent 重复调用造成重复创建；
4. 对高风险动作有明确确认机制；
5. 不把所有数据库字段直接暴露给 Agent；
6. 把业务状态、权限、校验留在后台服务中执行。

### 4.2 初步 MCP 工具清单

| MCP 工具 | 作用 |
|---|---|
| `create_inspiration` | 创建产品灵感记录 |
| `search_inspirations` | 检索灵感库 |
| `attach_reference_assets` | 给灵感/项目追加参考图、链接、文件 |
| `create_product_project` | 从灵感创建产品项目 |
| `create_ai_generation_task` | 创建 AI 生图任务 |
| `list_ai_generation_results` | 查看某个项目的 AI 图结果 |
| `select_ai_concept` | 选择 AI 图方案进入下一阶段 |
| `create_modeling_brief` | 创建建模需求单 |
| `create_sample_task` | 创建工厂打样任务 |
| `record_sample_feedback` | 记录样品反馈和修改意见 |
| `advance_workflow_state` | 推进流程状态，但需后台校验合法状态跳转 |
| `submit_product_approval` | 提交最终审批 |
| `approve_product` | 审批通过 |
| `reject_product_for_revision` | 审批打回并指定修改环节 |
| `get_product_project_status` | 查询产品项目当前状态 |
| `create_action_page_link` | 生成某个离散页面的上下文链接 |

### 4.3 MCP Resources / Prompts

除了 Tools，还可以考虑：

- MCP Resources：暴露只读资源，例如产品项目详情、某轮打样资料、AI 图候选列表；
- MCP Prompts：沉淀固定业务提示词，例如“把用户口述整理成产品灵感记录”“把图片反馈整理成工厂修改意见”。

但核心业务写入动作仍应通过 Tools 调用后台服务，而不是让 Agent 自由生成 JSON 后直接写库。

## 五、哪些适合 Agent 判断，哪些必须写成明确代码

这是系统设计的关键区分。

### 5.1 适合 Agent / Skill 处理的部分

这些部分可以让 Agent 参与，因为它们偏理解、归纳、建议、草稿生成：

- 用户自然语言意图识别；
- 把聊天内容整理成结构化草稿；
- 从图片/文字中提炼灵感描述；
- 根据灵感生成设计方向建议；
- 辅助生成 AI 图 Prompt；
- 把样品反馈整理成清晰修改意见；
- 生成审批摘要；
- 给用户解释当前项目进度；
- 推荐下一步动作；
- 根据关键词决定发送哪个单页面链接。

### 5.2 必须由明确代码/后台逻辑处理的部分

这些不能只靠 Agent 临场判断，必须写进后台代码、状态机、权限或数据库约束：

- 用户身份识别与权限判断；
- 产品项目 ID、任务 ID、版本 ID 的生成；
- 数据表结构与字段校验；
- 文件上传、归档、关联关系；
- 状态机合法流转，例如不能从“灵感收集中”直接跳到“审批通过”；
- 审批规则，例如谁能审批、是否允许越级审批；
- 打回规则，例如可打回到哪个环节；
- 幂等控制，例如同一消息重复触发不能创建两个相同打样任务；
- 任务队列和异步任务状态；
- AI 生图任务提交、回调、失败重试；
- 工厂打样任务的截止时间、超期判断；
- 审计日志和操作留痕；
- 数据权限隔离；
- 高风险动作确认，例如提交审批、打回、删除、作废；
- 通知触发规则；
- 页面链接 token、有效期、访问控制。

### 5.3 Agent 可以建议，但后台必须裁决的部分

这些可以由 Agent 先提出建议，但最终判断必须走明确规则：

- 是否进入下一阶段；
- 某个产品当前是否允许提交审批；
- 某轮打样是否可关闭；
- 某个修改意见是否已解决；
- 某个页面链接是否允许发给当前用户；
- 当前用户是否有权查看供应商报价、工厂资料、审批意见。

## 六、轻后台的意义

“轻后台”不是没有后台，而是：

1. 用户不需要长期停留在后台里；
2. 后台页面不追求大而全；
3. 页面围绕具体任务打开；
4. 后台底层仍然有完整业务模型；
5. Agent 是主入口，页面是必要时的人工操作界面；
6. 所有关键动作最终回到结构化数据和状态流。

## 七、初步系统分层

```text
飞书 / Hermes 对话层
  ↓
业务 Skill / Prompt 层
  ↓
MCP Server：Agent 可调用的业务工具层
  ↓
Backend API：权限、状态机、业务逻辑、任务队列
  ↓
Database / Object Storage：结构化数据与文件资产
  ↓
Frontend Single Pages：被 Agent 按需发送给用户打开
```

## 八、需要优先设计的底层对象

下一步拆表结构时，建议优先明确这些核心对象：

1. 用户与角色；
2. 产品灵感；
3. 产品项目；
4. 设计灵感/参考资产；
5. AI 生图任务；
6. AI 图结果；
7. 建模需求；
8. 打样任务；
9. 打样轮次；
10. 修改意见；
11. 审批单；
12. 状态流转记录；
13. 页面动作链接；
14. 通知记录；
15. 审计日志。

## 九、下一步建议

下一步建议先拆两张图：

1. **系统分层架构图**：飞书机器人、Skill、MCP、后台、数据库、单页面之间怎么连；
2. **核心业务状态机**：一个产品项目从灵感到最终审批，各状态如何跳转，哪些跳转必须确认、哪些可以自动推进。

然后再进入表结构设计。