给 Agent 一张地图,而不是一座迷宫:前端 monorepo 目录结构重构实录

引言

当项目同时包含 Agent 应用和管理后台,且希望 AI Agent 能稳定参与迭代时,目录结构的设计目标会发生根本变化。传统目录结构服务的是"人类开发者的协作与长期维护",而 AI 稳定迭代的目录结构服务的是"Agent 的上下文获取成本与修改边界约束"。两者不是深浅之别,而是优化目标不同。

本文从目录结构设计出发,说明它与传统编程开发所需目录结构的差异点、差异的成因,以及复用问题如何在新结构下得到解决。


一、总体结构:双应用 + 共享契约 + Agent 操作层

采用 monorepo 风格的工作区,将 Agent 应用与管理后台物理隔离,但共享类型与基础组件。根目录放置 Agent 的"操作入口",使其无需遍历全仓即可理解项目规则。

text 复制代码
project-root/
├── AGENTS.md                  # Agent 唯一入口:技术栈、命令、目录安全边界
├── .agent/
│   ├── skills/                # 可复用操作流程(新增页面、改路由、跑验证)
│   ├── specs/                 # 当前迭代的验收标准(按 feature 分文件)
│   └── contexts/              # 只读上下文:路由表、菜单树、组件清单快照
├── apps/
│   ├── agent-web/             # Agent 用户侧应用
│   └── admin/                 # 管理后台
├── packages/
│   ├── shared-types/          # 跨应用共享的 API 类型与领域模型
│   ├── ui-core/               # 无业务逻辑的基础组件(Button、Modal、Table)
│   └── request-client/        # 统一请求实例、错误码映射、拦截器
├── scripts/
│   └── verify                 # 唯一验证入口:typecheck + lint + test + build
└── pnpm-workspace.yaml

设计证明 :Agent 在修改代码前需要知道"路由怎么注册、组件放哪里、验证命令是什么"。如果这些信息分散在各个 src 目录里,Agent 每次都要重新推断,容易产生不一致的改动。根目录的 AGENTS.md 配合 .agent/ 目录,相当于给 Agent 一张地图和一套可执行的检查清单,而不是让它靠猜测工作。

Agent 应用目录:会话状态与工具调用分离

Agent 应用的特殊性在于:它既有传统前端 UI,又有会话管理、工具调用渲染、流式响应处理等逻辑。目录需要让 Agent 能清晰区分"纯展示"与"有副作用的状态逻辑"。

text 复制代码
apps/agent-web/src/
├── app/                       # 路由与页面组装
│   ├── (chat)/                # 会话主界面
│   ├── (history)/             # 历史会话
│   └── layout.tsx
├── features/
│   ├── conversation/          # 会话域:消息列表、输入框、流式渲染
│   │   ├── components/
│   │   ├── hooks/             # useStreamingResponse, useMessageQueue
│   │   └── stores/            # 会话状态
│   ├── tools/                 # 工具调用渲染
│   │   ├── registry.ts        # 工具名 → 渲染组件的映射表
│   │   └── renderers/
│   └── artifacts/             # Agent 产出物预览
├── lib/
│   ├── agent-client/          # 与 Agent 后端通信的客户端(SSE/WebSocket)
│   └── guardrails/            # 前端侧安全兜底:输出过滤、超时处理
└── shared/

设计证明 :Agent 应用最易出问题的地方是"工具调用渲染"与"会话状态"的耦合。将 tools/registry.ts 作为唯一注册点,Agent 新增一个工具渲染器时,只需在 registry 中加一行映射,而不需要改动会话主流程。lib/agent-client 集中处理流式协议,避免每个 feature 各自实现一套 SSE 解析,降低迭代时的连锁风险。

管理后台目录:按领域拆分,限制共享扩散

管理后台的迭代频率通常高于 Agent 应用,但它的变更不应影响 Agent 应用的稳定性。通过 packages/ 的依赖方向约束来实现:管理后台可以依赖共享包,但共享包不能反向依赖管理后台。

text 复制代码
apps/admin/src/
├── app/
│   ├── (dashboard)/
│   ├── (agent-config)/        # Agent 配置管理(模型、提示词、工具权限)
│   └── (audit)/               # 审计日志、调用记录
├── domains/                   # 按业务领域拆分,每个域自包含
│   ├── agent-config/
│   │   ├── api/
│   │   ├── components/
│   │   └── hooks/
│   ├── audit-log/
│   └── user-management/
├── components/                # 仅 admin 使用的布局组件
└── lib/
    └── permissions/           # RBAC 权限判断

设计证明 :管理后台常见的失败模式是"所有业务组件堆在 components/ 下,半年后没人知道哪个组件属于哪个功能"。按 domains/ 拆分后,每个域的边界清晰,Agent 在修改"Agent 配置"相关页面时,只需关注 domains/agent-config/,不会误改审计日志的代码。


二、Agent 操作层的具体约定

目录之外还需要几条硬性规则,写在 AGENTS.md 中:

唯一验证入口 。scripts/verify 必须存在且可执行,Agent 完成任何修改后只运行这一条命令。内部按顺序执行 typecheck、lint、相关包的 test、build。验证失败则不得提交。

路由与菜单的快照机制 。管理后台的菜单和权限路由通常由后端动态返回,Agent 在本地开发时看不到全貌。在 .agent/contexts/ 下放置一份从开发环境导出的路由/菜单快照,Agent 修改路由相关代码前先读这份快照,避免凭空编造路由名或权限码。

禁止 Agent 修改的目录 。packages/shared-types/ 中的类型由后端契约决定,Agent 不应自行修改。如需新增类型,必须在 .agent/specs/ 中说明需求,由人工确认后更新,或通过代码生成从后端 schema 产出。

每轮迭代的 Spec 落盘 。不要让 Agent 仅凭聊天记录工作。每个迭代任务在 .agent/specs/ 下建一个 markdown 文件,写清:涉及哪个应用、预期行为、验收命令、禁止触碰的目录。Agent 开始前读 spec,结束后对照 spec 自检。

跨应用契约类型统一 。管理后台中"Agent 配置"模块的接口返回结构,与 Agent 应用运行时实际读取的配置结构,往往存在细微差异。将这类跨应用契约类型统一放在 packages/shared-types/agent-config.ts,两端都从这里导入。管理后台改了字段,TypeScript 会立刻在 Agent 应用的消费处报错,防止"后台改了配置但前端运行时解析失败"这类隐性破坏。


三、与传统目录结构的差异点及成因

差异的根源在于:传统目录结构服务的是"人类开发者的协作与长期维护",而 AI 稳定迭代的目录结构服务的是"Agent 的上下文获取成本与修改边界约束"。

1. 根目录多了"Agent 操作入口层"

传统项目根目录通常是 src/、public/、package.json、README.md。README 写给人看,格式自由,Agent 读它要猜测哪些是规则、哪些是说明。

AI 友好结构增加了 AGENTS.md 和 .agent/ 目录。AGENTS.md 是机器可解析的规则文件:命令、安全边界、禁止修改的目录,条目化、无歧义。.agent/skills/、.agent/specs/、.agent/contexts/ 把"操作流程""本轮验收标准""路由菜单快照"从聊天记录和人的记忆里落盘成版本化文件。

成因:人类开发者可以通过口头沟通、Code Review、团队惯例传递这些信息。Agent 没有这些隐性渠道,每次会话都是冷启动,所以必须把隐性知识显性化、文件化。

2. 验证入口从"多个脚本"收敛为"唯一命令"

传统项目 package.json 里常有 dev、build、test、lint、typecheck 多个脚本。人类知道改完代码该跑哪几个,Agent 不知道,容易漏跑或跑错顺序。AI 友好结构要求 scripts/verify 作为唯一验证入口。

成因:人类会自己判断验证顺序,Agent 不会。传统项目没有动力把"验证的确定性"做到这个程度。

3. 目录拆分依据从"技术分层"转向"修改边界"

传统前端常见 components/、hooks/、utils/、services/ 按技术类型分层。这对人类友好,因为人找东西靠"这是组件还是工具函数"的直觉。

但对 Agent 而言,按技术分层意味着一次业务修改要横跨多个目录。改"Agent 配置"功能时,组件、hook、接口、类型分散在各处,Agent 必须理解整个项目的技术分层惯例才能改对,上下文成本高,且容易漏改某一层。

AI 友好结构改用 features/ 或 domains/ 按业务领域自包含。Agent 改一个功能时,修改范围收敛在一个目录内,边界清晰。

成因:传统分层优化的是"人类按类型检索",AI 结构优化的是"按修改范围隔离"。

4. 共享包有了"依赖方向约束"

传统 monorepo 也会抽 packages/shared,但依赖方向往往靠约定,偶尔出现共享包反向引用业务代码也没人拦。

AI 友好结构把依赖方向变成硬约束:packages/ 只能被 apps/ 依赖,不能反向依赖;shared-types/ 由后端契约决定,Agent 不得自行修改。

成因:Agent 缺乏"这个改动会不会造成循环依赖"的全局判断力,一旦共享包被污染,所有应用一起坏。传统项目靠人的架构意识兜底,AI 项目必须靠目录和规则兜底。

5. 跨应用契约类型被提升为独立包

传统项目里,管理后台和用户端共享的类型常放在某一端的 types/ 下,另一端 import 过来,或各写一份靠联调对齐。AI 友好结构把跨应用契约提升到 packages/shared-types/,两端都从这里导入。

成因:Agent 改代码时不会主动想到"另一端还在用这个字段"。传统项目靠联调和测试发现这类问题,AI 项目靠类型系统在编译期拦截。

6. 快照文件成为目录的一部分

传统项目里,后端动态返回的菜单、权限路由,前端开发时靠登录开发环境查看,没有落盘习惯。AI 友好结构在 .agent/contexts/ 下放路由/菜单快照。

成因:人类开发者打开浏览器就能看到菜单,Agent 看不到运行时状态,只能靠快照文件补上这个信息差。

差异对照表

维度 传统目录结构 AI 稳定迭代目录结构
服务对象 人类开发者 Agent + 人类
知识载体 口头沟通、惯例、Code Review 版本化文件(AGENTS.md、specs、快照)
拆分依据 技术类型分层 业务领域自包含(修改边界)
验证方式 多脚本、人判断顺序 唯一命令、固定顺序
依赖约束 靠架构意识 靠目录规则硬约束
契约同步 联调、测试发现 共享类型包、编译期报错

本质:AI 友好目录结构把一部分"人的职责"转移给了"项目结构本身"。传统结构的稳定性依赖人类开发者的隐性知识和主动判断,Agent 没有这些,所以必须把隐性知识显性化、把判断规则固化成目录和文件。


四、复用怎么办

按领域自包含最容易被质疑的点是:难道每个域都复制一份组件?答案是:复用没有消失,而是被重新分层了------复用发生在"稳定的下层",域内自包含的是"易变的业务组合"。

复用的三个层次

第一层:无业务语义的基础件 → packages/ui-core/ Button、Modal、Table、Form 控件。不依赖任何领域状态,接口稳定,变更频率低。Agent 可放心复用,因为契约由 props 定义。

第二层:跨应用的契约与客户端 → packages/shared-types/、packages/request-client/ API 类型、错误码映射、统一请求实例。这是"逻辑复用"最该发生的地方------请求拦截、鉴权、错误处理只写一次。

第三层:域内的业务组合 → features/xxx/ 或 domains/xxx/ 会话消息列表、工具调用渲染器、Agent 配置表单。这些是"业务组装",复用范围通常就在本域内。域内组件默认不跨域复用,除非被证明稳定。

跨域复用:提升,而不是复制

当两个域都需要同一个业务组件时,传统做法是挪到公共 components/。AI 友好结构的做法是提升(promote):

  1. 先在本域内存在,被第二个域引用时不直接跨域 import,先评估是否已剥离业务语义。
  2. 若只依赖 props、不依赖特定域状态和接口,提升到 packages/ui-core/ 或新建 packages/ui-business/。
  3. 若仍带业务语义,提升到 packages/ 下按业务命名的包,而不是塞回某个域的目录。

复用是被"证明"出来的,不是被"预设"的 。传统项目常见的失败是过早抽象------建一个巨大的 components/,谁都能往里放,半年后没人知道哪个组件稳定。提升机制让每个共享件都有明确的"晋升记录",Agent 在 packages/ 里看到的就是已被验证的稳定件。

逻辑复用的两类处理

无业务状态的工具逻辑 (日期格式化、防抖、SSE 解析、权限码匹配)→ packages/utils/ 或 packages/request-client/。纯函数化,复用零风险。

带业务状态的 hooks (useStreamingResponse、useMessageQueue、useAgentConfigForm)→ 留在域内 features/xxx/hooks/。这类 hook 依赖本域的状态管理和接口,强行提升会把业务状态泄漏到共享层。如果两个域都要用,说明它们共享同一套业务模型,应考虑是否该合并域,而不是抽公共 hook。

硬规则:packages/ 下的代码不得 import apps/ 下的任何东西。依赖方向单向,保证共享层纯净。Agent 想"图省事"把业务 hook 提到公共包时,这条规则会阻止它。

Agent 如何知道"该复用哪个"

在 .agent/contexts/ 下放置组件清单快照:

text 复制代码
.agent/contexts/component-registry.md

内容不是全量组件列表,而是分层清单:

  • packages/ui-core/ 下有哪些基础组件、各自 props 契约一句话说明
  • packages/ 下有哪些业务共享包、适用场景
  • 各域内有哪些"已标记为可提升候选"的组件

Agent 开始任务前读这份快照,就知道"消息气泡组件已存在于 conversation 域,不要新建""日期格式化在 packages/utils 里,直接 import"。快照可由脚本生成(扫描导出 + 读注释),避免手工维护过期。

复用场景对照表

复用场景 传统做法 AI 友好做法
基础组件 放全局 components/ 放 packages/ui-core/,契约稳定
业务组件跨域用 直接挪到公共目录 先证明稳定,再提升到 packages/
业务 hook 常被抽到全局 hooks/ 留在域内,跨域用说明该合并域
工具函数 utils/ 大杂烩 按职责进 packages/utils/ 或 request-client
Agent 找复用 靠人告知或搜索 读 .agent/contexts/ 组件清单快照

结论

AI 友好结构不是不要复用,而是把复用从"空间上的集中"改成"分层上的收敛" 。基础件和契约在 packages/ 里集中复用,业务组合在域内自包含、按需提升。

这样做的代价是提升时多一步评估,收益是 Agent 每次改代码时,修改范围和可复用件都是确定的------它不需要理解整个项目的抽象习惯,只需要读快照和遵守依赖方向。传统结构的复用依赖人的判断力,AI 结构的复用依赖目录规则和快照文件,把"该不该抽公共组件"这个判断从人的经验转移成了可执行的流程。

一句话概括:AI 友好目录结构的核心,是把隐性知识显性化、把判断规则固化成文件、把修改边界收敛到目录,让 Agent 在确定的范围内稳定迭代。

相关推荐
樊小肆8 分钟前
agent 不报错才最吓人:自研编码工具半年,我踩了 10 个"看着正常"的运行时坑
前端·人工智能·agent
鲸鹏芯海微电子科技上海有限公司13 分钟前
手机直连卫星,射频前端到底要解决什么?
前端·后端
FungLeo14 分钟前
FengCMS · PHP+MySQL 升级实录 · Web 入口收敛:Apache/Nginx 白名单挡住配置、安装 SQL、上传脚本直连
前端·mysql·php·安全加固·fengcms
Jvav练习生23 分钟前
别再让Agent互相传话:多Agent协作的3个致命错误(附120行可运行代码)
agent
费曼学习法29 分钟前
12 个工具调用改成并发,耗时从 94 秒掉到 23 秒:DeepSeek 并行调用工程细节
前端
修炼的dance34 分钟前
qpdf四个结构开关逐个开,只有对象流明显省
前端
测试员周周37 分钟前
【agent评测】:真实系统演示工具调用长什么样,用例怎么设计,怎么测
前端·后端·github
张明君644511 小时前
在 Astro SSR 项目中实现服务启动前初始化
前端·后端
再吃一根胡萝卜2 小时前
从零实现 DSH 用户信息插件
前端