架构概览（前端 + 后端 + Agent 运行时）

先画块，再给 AI 划改动边界——平台仓库大，最怕「整仓 @」。

AI CODING · 场景四 · 架构

三块足够开始：控制台、业务 API、Agent 运行时。备忘写清「试跑」请求路径后，派活才不会改错包。

产出 一页备忘时间 20–40 分钟

写备忘 →

本节要点

• 三块职责 + 一次「试跑」请求路径
• 排错时该先看哪一层
• 可贴的备忘模板（给人填、给 AI @）

三块试跑给 AI模板

三块

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ 前端控制台       │────▶│ 业务 API        │────▶│ Agent 运行时     │
│ 编排 / 配置 / 试跑│     │ 鉴权·CRUD·调度   │     │ 模型·工具·轨迹   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                        │                        │
         └──────────── 持久化 / 对象存储 / 日志 ←───────────┘

块	典型职责	给 AI 改时
前端控制台	配置 Agent、试跑、看结果	一次一页；别顺手改协议
业务 API	持久化、权限、调用运行时	契约先写；密钥走 env
Agent 运行时	调模型、工具、记轨迹	要可回放、可观测；人审优先

备选做法

整仓 @ +「修试跑」——分不清错在控制台、API 还是运行时。

推荐做法

先画三块 + 写清试跑路径，再决定 @ 哪一层。

选型说明： 你要能指出错误文案是前端造的，还是 API/运行时返回的——这决定纠错时打开哪一层。

一次「试跑」请求路径（口述版）

用户在控制台点「试跑」
  → 前端带上 agentId / 输入
  → 业务 API 鉴权、取配置、写请求记录
  → 调用运行时执行
  → 轨迹与结果写回
  → 前端展示成功或错误

排错决策树（简）

控制台白屏？ → 先查前端构建与网关
按钮无响应？ → 看网络面板状态码
API 200 但结果空？ → 查运行时轨迹 / 工具失败
401/403？ → 停 AI 改业务；查鉴权（人审）

读架构时的三个问题

1. 控制台点一下，请求打到哪一层？
2. 状态存在哪（库表 / 对象存储 / 仅内存）？
3. 失败时谁展示错误、谁负责重试？

给 AI 的 Prompt · 写架构备忘

给 AI · Prompt · 一页架构备忘先列将阅读的路径，再写；不要生成业务代码

【目标】写 architecture-platform.md（不超过一页正文）。
【包含】
- 三块职责（各 2～3 句）
- 一次「试跑」请求路径（5～8 步）
- 两处「禁止 AI 擅自改」并说明为什么
- （有仓则写）三块对应的包/目录路径
【不要】生成业务代码、重构目录、猜测密钥位置并打印
【请你】先列出将阅读的文件或文档路径，再写备忘

备忘模板（可直接填）

填完后这份既给人扫，也可 @ 给 AI。

给 AI · 平台架构备忘骨架复制后填空；路径写「待对照仓库」也可以出门

# 平台架构备忘
- 控制台包路径：
- API 包路径：
- 运行时包路径：
- 试跑入口（路由或页面）：
- 配置存在哪：
- 禁止 AI 改：（1）鉴权 （2）…
- 适合 AI 改：只读展示、文案、单测草稿
- 健康检查 URL：
- 日志怎么打开：

下一页用这份备忘 @ 后派活 → 关键模块。