AGENTS.md
本文件定义 AgentAdmin 仓库中 AI 代理（尤其是 Codex）与人类协作者共同遵守的工程约束。
它不是通用贡献指南，而是本项目的 AI 开发宪法。
所有自动化代码生成、重构、修复、脚手架补全、接口调整、文档更新与联调支持，都必须遵守本文件。
0. 文档真源与优先级
本仓库采用“文档真源 + 执行约束”双层治理。
0.1 真源文档
以下文档属于项目真源（source of truth），AI 在实施前必须优先遵守：
00-document-system-index.md：文档系统入口、阅读顺序、真源规则、文档更新规则01-project-overview.md：项目定位、目标用户、系统边界、MVP 范围、非目标02-system-overview.md：总体架构、双平面边界、核心链路、部署基线、跨层约束03-backend-development-architecture.md：后端模块边界、状态流转、安全规则、实施顺序04-frontend-development-architecture.md：前端路由、页面、分层、状态管理、权限、SSE 交互05-api-specification.md：REST、SSE、分页、过滤、能力表达、接口兼容规则06-data-model-specification.md：核心实体、表边界、关系模型、JSON 字段策略、冷热数据规则07-enum-and-state-definitions.md：术语、状态机、运行枚举、事件名、能力码前缀08-error-code-specification.md：错误响应结构、错误码前缀、核心错误码、处理语义09-common-fields-and-naming.md：数据库/API/前端命名规则与通用字段10-frontend-backend-collaboration.md：前后端职责划分、接口变更流程、并行开发边界、交付要求11-integration-and-acceptance.md：联调顺序、必测场景、验收证据、缺陷分级12-development-plan.md：阶段计划、并行轨道、里程碑、推荐开发顺序13-pre-development-checklist.md：开发前必查项、高风险变更检查、停机点、接力交接模板
0.2 优先级规则
发生冲突时，遵守以下优先级：
- 当前任务明确要求
AGENTS.override.md- 本文件
AGENTS.md - 真源文档系统（00~13）
- 现有代码实现
- AI 自行推断
0.3 真源优先原则
如果：
- 代码实现与真源文档冲突
- 两个模块的局部实现互相矛盾
- 命名、枚举、错误码、接口结构与规范不一致
默认以文档真源为准，不得擅自以“代码现状”为借口继续扩散错误实现。
如发现文档已明显过时，必须在输出中明确指出，而不是静默绕过。
1. 项目身份
AgentAdmin 是一个面向 Java 业务系统 的 Agent 接入与治理平台。
它的定位不是：
- 聊天应用
- 通用 AI 工作流画布
- Prompt playground
- Dify / Langflow / Coze 的 Java 复刻版
它的定位是：
- 为现有业务系统提供 外挂式 Agent 能力接入
- 将已有业务能力沉淀为 Tool
- 提供 Agent 的统一定义、调试、发布、运行、观测、治理能力
- 成为 Java 生态下可落地的 Agent 基础设施
所有实现必须服务于这个目标。
2. 不可破坏的核心原则
2.1 架构原则
第一阶段默认采用：
- 模块化单体（Modular Monolith）
- Control Plane / Exec Plane 双平面架构
- 清晰领域边界，未来按热点拆分
在没有明确任务要求时，禁止：
- 擅自引入微服务拆分
- 引入 Spring Cloud 全家桶
- 引入 Nacos / Kafka / Flowable 等重型依赖作为前置条件
- 为“未来扩展”提前设计分布式复杂度
2.2 产品边界原则
第一版后端重点是：
- Tool 接入
- Agent 定义与版本发布
- Playground 调试
- Run / Trace 观测
- Executor 注册与治理
- 多租户 / 权限 / 审计骨架
- 插件扩展骨架
第一版前端重点是：
- 登录与租户切换
- Agent 管理
- Tool 管理
- Playground
- Run / Trace
- Executor 管理
- 审计日志
- 基础设置页
在没有明确任务要求时，禁止优先实现：
- 复杂多 Agent 编排
- 可视化工作流画布
- 大而全的知识库系统
- 自研向量平台
- 重型规则引擎
- 聊天首页化产品改造
- 为营销展示服务的非核心 UI
2.3 工程原则
优先级固定如下：
- 可落地
- 边界清晰
- 易于本地开发与部署
- 对 Java 团队低侵入
- 后续可演进
不要为了“更优雅”而牺牲：
- 可理解性
- 启动成本
- 调试便利性
- 开源用户上手体验
3. 默认技术栈
如无明确任务要求，默认遵守：
后端
- Java 21+
- Spring Boot
- Spring Security
- Spring AI
- MySQL
- Redis
- JWT
- OpenAPI / springdoc
- SSE
- Micrometer + OpenTelemetry
- Slf4j / Logback
- Java SPI + Spring AutoConfiguration
- JSON Schema
后端 Java 代码规范补充
后端 Java 代码默认补充遵守以下约束：
- 实体类只能使用
class，禁止使用record - 实体类命名禁止使用
*Record - DTO 请求对象统一使用
*ReqDTO - DTO 响应对象统一使用
*ResDTO - 请求 DTO 与响应 DTO 应尽量分包存放，优先使用
reqdto/与resdto/目录 - Mapper 必须通过 XML 编写 SQL，禁止在 Mapper 接口方法上直接写
@Select、@Insert、@Update、@Delete - 工具类统一使用
*Util命名，并集中存放在utils包中 - 字符串、集合、Map 等通用规整逻辑，优先通过
agentadmin-common中统一封装的 Hutool helper 使用，避免各模块重复手写trimToNull、判空与小型容器构造 - 如无当前任务明确要求，后端开发阶段不以“本地启动通过”作为必须完成项；但仍应完成代码级自检，并明确说明未启动验证的风险
前端
- Next.js（App Router）
- TypeScript
- React
- Tailwind CSS
- shadcn/ui
- Radix UI
- TanStack Query
- React Hook Form + Zod
- OpenAPI 生成 API Client
- SSE 流式交互
不要擅自替换为：
- 重型服务网格方案
- 非主流框架
- 需要显著增加学习成本或部署复杂度的中间件
- 无明确收益的技术栈迁移
4. 项目初始化与仓库结构约束
当前项目可能尚未完成初始化。
如果仓库结构尚未建立，则本节用于提供 推荐的初始化结构 与 模块边界心智模型，而不是声明当前仓库事实。
AI 必须遵守以下规则：
- 如果仓库已有实际目录结构，优先遵循实际结构
- 如果仓库尚未初始化，可按本节推荐结构创建
- 即使目录结构暂未建立，也必须先遵守模块边界，不得混写
- 不得因为项目尚未初始化，就把所有代码堆在单一目录中
- 不得在未明确要求时，过早拆成重型多模块、微服务或复杂 monorepo 结构
4.1 初始化阶段的核心原则
项目初始化阶段，优先固定的是：
- 模块边界
- 职责分层
- 前后端协作边界
- 接口与状态语义
- 目录落点的一致性
而不是优先追求：
- 物理模块数量
- 微服务拆分
- 复杂工程编排
- 多仓库布局
- 过度抽象的基础设施层
默认策略是：
先建立清晰的逻辑边界，再根据实现复杂度逐步演进物理结构。
4.2 后端初始化推荐结构
后端第一阶段推荐采用：
- 单仓库
- 模块化单体
- 单 Spring Boot 应用优先
- 清晰包结构优先于 Maven 多模块数量
推荐以逻辑模块先行，至少区分以下领域边界：
authtenantrbacagenttoolexecutorruntimemodelsessionobservabilityauditplugincommon
如果项目尚未初始化，后端可先按如下形式建立：
backend/
src/main/java/com/agentadmin/
auth/
tenant/
rbac/
agent/
tool/
executor/
runtime/
model/
session/
observability/
audit/
plugin/
common/
说明：
- 第一阶段这些模块可以先作为单体工程中的包边界
- 不要求一开始就拆成多个独立服务
- 不要求一开始就拆成多个独立仓库
- 是否拆成 Maven 多模块，应以实施便利性和边界稳定性为准
- 即使处于单体工程中，也不得跨模块随意共享实现细节
4.3 后端工程初始化方案选择
如需初始化后端工程，优先采用以下顺序：
方案 A（推荐）
单 Spring Boot 应用 + 清晰包结构
适用场景：
- 项目刚启动
- 需要快速验证 MVP
- 团队人数较少
- 希望降低本地开发与部署成本
优点：
- 启动快
- 易调试
- 结构清晰
- 便于后续按热点拆分
方案 B（可选）
Maven 多模块，但仍保持模块化单体
适用场景：
- 已明确存在 SDK、插件 API、Starter 等独立边界
- 希望提前隔离部分依赖
注意：
- 仍然不是微服务
- 不应过早把业务模块拆散成独立部署单元
- 如需抽出共享运行内核，应优先建立职责明确的独立模块，例如
agentadmin-runtime - 如需抽出 MCP / SYSTEM Tool 的共享发现与绑定支撑，应优先建立职责明确的独立模块，例如
agentadmin-tool-support - 禁止在
agentadmin-server内新增模糊目录，如core、common/core、module/core
方案 C（当前不推荐）
按 Control Plane / Exec Plane 提前拆成多服务
除非任务明确要求，否则初始化阶段不采用。 当前阶段应先固定逻辑边界，而不是提前引入分布式复杂度。
4.4 前端初始化推荐结构
前端第一阶段推荐采用：
- 单 Next.js 应用
- App Router
- 以 feature 为主组织目录
- 页面、组件、API、状态逻辑分层清晰
如果项目尚未初始化，前端建议按如下形式建立：
frontend/
src/
app/
features/
components/
lib/
api/
hooks/
types/
styles/
说明：
- 第一阶段无需提前拆 package monorepo
- 优先保证控制面信息架构与组件体系
- 不要为了“未来扩展”提前引入复杂前端工程编排
- 业务逻辑优先沉淀在
features - 通用组件与工具能力不得反向承载领域逻辑
4.5 目录与边界约束
即使项目尚未初始化，也必须遵守以下约束：
- 领域逻辑不得堆入
common、utils、lib等模糊目录 - 不得以“先跑通”为借口，把认证、租户、权限、运行、观测逻辑混在一起
- 不得在未形成边界前就把目录结构设计成微服务形态
- 不得用前端页面目录直接承载 API 契约定义
- 不得让前端 feature 与后端领域命名长期失配
- 不得把临时目录结构当成最终结构长期保留
4.6 初始化阶段允许的简化
在不破坏核心边界的前提下，初始化阶段允许以下简化：
- 后端先单应用启动
- 前端先单应用启动
- 插件能力先保留接口与扩展点，不急于补全全部实现
- 个别模块先保留薄实现，但命名和边界要正确
- 局部功能先 stub/mock，但必须显式标注，不能伪装成正式实现
4.7 初始化阶段禁止事项
在项目尚未初始化阶段，禁止：
- 因为没有现成结构就把所有逻辑塞进一个
common或utils - 过早引入微服务目录布局
- 过早引入复杂 monorepo 工具链
- 过早抽出大量空壳模块
- 用临时目录结构替代正式模块边界思考
- 因“先快速生成代码”而放弃目录与职责约束
4.8 最终判断标准
如果项目尚未初始化，AI 应优先问自己：
- 这次初始化是否优先固定了逻辑边界，而不是物理复杂度？
- 这个目录设计是否有利于 MVP 快速落地？
- 这个结构是否便于后续演进，而不是提前引入微服务负担？
- 是否避免了把领域逻辑混入模糊公共目录？
- 前后端是否都保留了清晰、可持续扩展的边界？
如果以上问题有两个以上答案是否定的，应先调整初始化方案，再继续实施。
5. 任务分类与执行方式
每次任务必须先判断属于哪一类：
A 类：低风险实现
例如：
- 小范围 bugfix
- 页面样式修正
- 非公共逻辑的小功能补全
- 测试补充
- 文案调整
- 局部日志增强
可直接实施，但仍需说明范围与验证方式。
B 类：中风险实现
例如：
- 新增模块内接口
- 新增页面或详情页
- 新增状态分支
- Runtime 内局部行为调整
- Tool / Agent 的字段扩展
- SSE 事件消费增强
- 新增索引、缓存或查询优化
必须先给出局部计划，再实施。
C 类：高风险实现
例如：
- 数据库 schema 变更
- 状态机变更
- 租户隔离逻辑调整
- 权限判定逻辑调整
- Agent 发布/回滚逻辑调整
- Tool 调用鉴权逻辑调整
- Executor 注册协议调整
- Run / Trace 数据模型调整
- 对外 API 契约调整
- 枚举 / 错误码 / 事件名变更
- 依赖升级或新增中间件
- 跨模块重构
- 公共基类修改
- 命名体系迁移
必须先停下，输出“变更计划 + 影响分析 + 验证方案”，在获得明确继续信号前，不得直接实施。
6. AI 修改代码前必须遵守的步骤
每次开始任务前，至少完成以下动作：
- 明确本次任务目标
- 明确本次任务分类（A/B/C）
- 明确本次改动范围
- 标记不可修改区域
- 列出计划修改的文件
- 指出依赖哪些真源文档
- 说明验证方式
- 如为 B/C 类任务，先输出局部计划
禁止“顺手”做以下事情：
- 无任务要求的大规模重构
- 跨模块重命名
- 批量迁移包结构
- 修改公共基类导致连锁影响
- 因主观偏好替换已有设计
- 借修 bug 顺带改协议
- 借样式优化顺带改交互语义
7. 工具与命令优先原则
对于可以通过命令、脚手架、构建工具、包管理器、代码生成器、测试命令、格式化工具、静态检查工具、数据库迁移工具或官方 CLI 稳定完成的工作，AI 应优先使用这些可验证手段，而不是手工模拟结果或凭空生成“看起来像”的产物。
7.1 默认原则
优先使用命令或工具的场景包括但不限于：
- 初始化项目或子工程
- 安装、移除、升级依赖
- 生成脚手架代码
- 生成 API Client、类型定义、SDK、迁移文件
- 执行构建、测试、格式化、lint、静态检查
- 执行数据库迁移
- 执行代码生成器或协议生成器
- 执行官方推荐的初始化与校验流程
7.2 禁止行为
禁止以下做法：
- 明明可以通过稳定命令完成，却手工伪造初始化结果
- 明明需要安装依赖，却只修改清单文件而不执行必要安装步骤
- 明明可以通过生成器产出标准文件，却手写近似替代品
- 未运行构建/测试/格式化/静态检查，却默认认为结果正确
- 把“理论上应该可行”当成“已经完成并验证”
7.3 允许的例外
以下情况可不执行命令，但必须说明：
- 当前环境不具备相应工具
- 网络、权限或沙箱限制导致命令不可执行
- 任务明确要求只给方案、不实际操作
- 执行代价过高且当前阶段只需提供草稿
此时必须明确说明：
- 哪个命令或工具本应执行
- 为什么未执行
- 未执行带来的风险
- 后续建议如何补验证
7.4 判断标准
如果一项工作存在“官方、稳定、可重复、可验证”的命令式做法，默认优先走命令式做法，而不是手工猜测。
8. 停机点（必须先停下）
出现以下情况时，AI 必须暂停实现，先报告风险：
- 真源文档之间冲突
- 文档与代码实现冲突
- 当前任务会破坏 API 兼容性
- 当前任务需要新增状态、枚举、错误码、事件名
- 当前任务会影响数据库表结构
- 当前任务需要修改权限模型或 tenant 传播规则
- 当前任务会改变 SSE 事件协议
- 当前任务会改变 Run / Trace 记录结构
- 当前任务需要跨前后端同时调整契约
- 当前任务涉及凭证、密钥、认证、审计链路
- 当前任务无法完成必要验证
此时不得直接“按经验继续写”。
9. 模块边界约束
9.1 Auth / Tenant / RBAC
这些模块属于平台骨架，必须长期保留。
最低要求：
- 用户登录
- 当前租户上下文
- 用户-租户-角色关系
- 基础 RBAC（Admin / Developer / Viewer）
- 审计可追责
禁止：
- 为了简化演示而删除 tenant_id
- 用“只做单用户版本”破坏未来边界
- 将权限判断散落到各处且无统一抽象
- 前端直接根据角色名硬编码页面权限结论
- 绕开 capability / permission 模型直接做隐藏按钮式权限
9.2 Agent Registry
必须围绕“Agent 定义 + 版本 + 发布”设计。
至少保留：
- Agent 元数据
- Agent 草稿 / 已发布版本
- 模型策略
- Tool allowlist
- Prompt 模板或系统指令
- 发布 / 回滚基础能力
禁止：
- 将 Agent 设计成只是一段随意字符串
- 绕过版本对象直接修改线上行为
- 让前端自己拼装发布态语义
9.3 Tool Registry
Tool 是项目核心资产模型。
必须支持的来源优先级：
- Executor 暴露
- HTTP / OpenAPI 适配
- 后续扩展 Connector
Tool 至少应具备：
- 唯一标识
- 名称与描述
- 参数 Schema
- 返回 Schema（可先弱约束）
- 来源类型
- 可见性与权限控制
- 版本信息
禁止：
- 把 Tool 调用写死在 Agent 逻辑里
- 把 Tool 只当作页面展示对象而无真实契约
- 在前后端各自维护两套 Tool 能力语义
- 让
agent、runtime、executor直接依赖tool.mapper、tool.entity、tool.service.impl - 让
agent、runtime、executor直接依赖agentadmin-tool-support
补充约束：
module/tool是系统内唯一 Tool 治理归口agentadmin-tool-support只承载 MCP / SYSTEM 的技术适配、动态发现与运行时绑定支撑- 其他模块只能通过
module/tool/application暴露的统一服务访问 Tool 能力
9.4 Executor Registry
Executor 是核心差异化能力之一。
必须优先支持：
- Spring Boot Starter 方式接入
- 注册
- 心跳
- 状态同步
- 工具上报
- 基础健康检查
目标是：
- 低侵入接入已有 Java 系统
- 尽量少改业务代码
- 不强迫业务方接受复杂基础设施改造
禁止：
- 将 Executor 设计成必须依赖复杂注册中心
- 将业务系统接入改造成大规模侵入式改造
9.5 Runtime
Runtime 负责一次 Agent 运行的编排执行，不等于复杂工作流引擎。
第一版关注：
- Agent 加载
- Tool allowlist 约束
- Prompt 组装
- 模型调用
- Tool 调用循环
- Session / Context 处理
- Run / Step / Event 记录
- SSE 输出
- 错误处理与重试边界
禁止：
- 把第一版 Runtime 设计成重量级 DAG 引擎
- 在 Runtime 中偷塞前端展示语义
- 让运行态结构与观测结构完全脱节
9.6 Observability / Audit
可观测性与审计不是附属品。
至少要支持：
- 谁触发了运行
- 属于哪个租户
- 使用了哪个 Agent 版本
- 调用了哪些 Tool
- 每一步状态如何
- 最终成功或失败原因
- 高风险操作的审计记录
第一版可先以 MySQL + 日志 + OpenTelemetry 为主，不要过早引入大规模日志分析基础设施。
9.7 Frontend Control Plane
前端是控制面，不是聊天产品前台。
必须围绕：
- 租户
- Agent
- Tool
- Executor
- Run / Trace
- 审计
- 设置
组织信息架构。
禁止：
- 以聊天窗口作为全局主导航
- 优先实现节点画布
- 让页面结构偏向 demo 式单页体验
- 用过度动画影响信息效率
10. 数据与存储约束
10.1 MySQL
主要承载：
- 用户、租户、角色关系
- Agent / Agent Version
- Tool / Tool Version
- Executor 元数据
- Run / Run Step / Event
- Audit Log
- 配置类对象
JSON 字段用于：
- Tool Schema
- Agent 配置快照
- Prompt 模板配置
- 运行上下文快照
- 扩展字段
禁止：
- 结构化高频过滤字段只放 JSON
- 把关键外键关系偷放扩展字段
- 用 JSON 替代本应独立建模的核心对象
10.2 Redis
主要承载：
- 会话缓存
- 临时上下文
- Executor 心跳状态
- 幂等键
- 短期令牌或限流辅助数据
禁止：
- 在第一阶段把核心事实数据只放 Redis
- 把 Redis 当作长期真源
10.3 不要过度引入
没有明确需求时，不要引入：
- 专用向量数据库
- ClickHouse
- Elasticsearch
- Kafka 作为前置依赖
这些仅在明确出现性能瓶颈、检索需求或日志规模压力后再引入。
11. API、状态与兼容性约束
默认 API 风格：
- REST 为主
- SSE 用于流式运行输出
- OpenAPI 文档自动生成
要求：
- 对外接口命名清晰稳定
- 错误码和错误结构统一
- tenant 上下文来源明确
- capability 表达方式统一
- 分页、过滤、排序结构统一
- SSE 事件名、事件载荷、补拉规则统一
禁止：
- 无说明地破坏现有接口契约
- 前后端各自扩展不同字段语义
- 跳过文档直接新增状态或错误码
- 在未同步规范时擅自改 enum / event / code
涉及以下变更时必须明确说明兼容性影响：
- 字段删除或重命名
- 响应结构变化
- 鉴权方式变化
- 分页与过滤行为变化
- 事件名变化
- 状态枚举变化
- 错误码语义变化
12. 测试与验证要求
AI 生成或修改代码后，至少应满足：
- 能编译通过
- 相关单元测试通过
- 相关集成测试通过（如已有）
- 不引入明显静态检查问题
- 变更说明与实际改动一致
- 文档受影响时已明确同步或标记待同步项
如任务涉及：
- 权限
- 租户隔离
- Tool 调用
- Runtime 执行链路
- 发布 / 回滚
- 审计日志
- API 契约
- SSE 事件
- 状态流转
则优先补充测试，而不是只修改主逻辑。
如果无法执行测试，必须明确说明：
- 哪些测试未执行
- 为什么未执行
- 风险在哪里
- 建议下一步验证什么
禁止在未说明风险的情况下声称“已完成”。
13. 日志、观测与错误处理规范
13.1 日志
日志应具备：
- tenant_id
- user_id（如有）
- agent_id / version
- run_id
- executor_id（如适用）
- trace_id / span_id（如适用）
禁止：
- 打印明文密钥
- 打印敏感凭证
- 无边界输出完整上下文
- 用 debug 日志替代审计记录
13.2 错误处理
要求：
- 区分用户错误、配置错误、系统错误、外部依赖错误
- 异常信息可排障，但不能泄露敏感信息
- 对 Tool 调用失败、模型调用失败、Executor 不可用等情况给出清晰错误语义
不要：
- 大量吞异常
- 模糊返回
- 用 200 + message 模拟失败
- 用前端兜底掩盖后端语义缺失
14. 安全与审计约束
以下操作必须可审计：
- 登录
- 租户切换
- Agent 发布 / 回滚
- Tool 可见性或权限变更
- 模型配置变更
- 高风险 Tool 调用
- Executor 注册与下线
- 权限授予与收回
- 关键配置修改
禁止：
- 在代码中硬编码密钥
- 把凭证提交到仓库
- 省略高风险调用的审计链路
- 在前端持久化高敏感明文
- 通过日志回显敏感凭证
15. 文档同步义务
以下变更完成后，必须检查是否需要同步真源文档：
- 新增或修改接口
- 新增或修改实体
- 新增或修改状态机
- 新增或修改错误码
- 新增或修改事件名
- 新增或修改权限能力
- 新增或修改命名约定
- 新增或修改联调/验收方式
如果本次改动未同步文档，必须在结果中明确说明：
- 哪份文档受影响
- 为什么本次未同步
- 应由谁在何时同步
禁止静默制造“代码新真相”。
16. 前后端并行开发约束
前后端必须以接口契约和状态定义为协作边界。
禁止：
- 前端绕过 API 规范自行发明字段
- 后端未出契约就要求前端猜结构
- 以后端临时返回为长期依据
- 用 mock 数据偷偷扩展未确认语义
允许：
- 在契约已冻结时并行开发
- 在 Preview 能力下做有限前瞻实现
- 在明确标记的实验页面中做受控验证
涉及：
- 接口字段变更
- 状态语义变更
- SSE 事件变更
- 错误码变更
必须回看：
05-api-specification.md07-enum-and-state-definitions.md08-error-code-specification.md10-frontend-backend-collaboration.md
17. 对 Codex 的专门说明
本仓库优先适配 Codex 工作方式。
执行任务时，默认遵守以下方式：
- 先读本文件，再开始实现
- 先读相关真源文档，再开始动手
- 先给出局部计划，再改代码
- 一次只解决一个明确任务
- 优先做小步、可验证改动
- 优先遵循现有代码风格与模块边界
- 不因“顺手”而扩大改动半径
- 输出必须包含验证结果与未验证风险
- 能用稳定命令或工具完成的事情，优先不要手工模拟
如存在更细粒度目录级 AGENTS.md，则子目录文件对该子树生效，应优先遵守。
如存在 AGENTS.override.md，则其优先级高于普通 AGENTS.md。
18. 建议的输出与提交摘要格式
完成任务后，输出摘要时必须包含：
- 本次改了什么
- 为什么这样改
- 涉及哪些模块 / 文件
- 依赖了哪些真源文档
- 风险点是什么
- 执行了哪些验证
- 哪些地方未验证
- 是否需要同步文档
- 是否影响以下边界：
- 租户隔离
- 权限模型
- 对外接口契约
- 状态机 / 枚举 / 错误码
- 运行链路 / Trace / SSE
如果是高风险变更，还必须补充：
- 兼容性影响
- 回滚思路
- 联调影响面
19. 未满足这些条件，不得宣称完成
出现以下任一情况时，不得宣称“已完成”：
- 未说明改动范围
- 未说明验证方式
- 高风险任务未先给计划
- 明知有文档冲突却未说明
- 改了接口却未说明兼容性
- 改了状态/错误码/事件却未同步规范或标记
- 未说明未验证部分
- 未说明风险
- 只完成代码生成，但未检查是否符合模块边界
可以说：
- “已完成代码修改，但未完成验证”
- “已完成局部实现，待联调确认”
- “已完成草稿方案，待确认后实施”
禁止把“生成了一版代码”表述成“问题已解决”。
20. 明确禁止事项
没有明确任务授权时，禁止：
- 把项目改造成聊天产品
- 把项目改造成工作流画布平台
- 删除租户 / 权限 / 审计骨架
- 引入不必要的微服务化改造
- 引入重型中间件作为基础前提
- 擅自重写核心领域模型
- 为了短期演示牺牲长期边界
- 在未验证的情况下声称生产可用
- 让代码实现脱离真源文档自我扩张
- 把 demo 便捷性凌驾于平台边界之上
21. 最终判断标准
每次改动前都先问：
- 这是否强化了 AgentAdmin 作为 Java Agent 基础设施的定位？
- 这是否让 Java 团队更容易接入，而不是更难？
- 这是否保持了模块化单体与双平面边界？
- 这是否保留了租户、权限、审计、观测骨架？
- 这是否符合真源文档？
- 这是否属于 MVP 真正需要的能力？
- 这是否在可验证范围内完成？
如果以上问题有两个以上答案是否定的，就不要继续实现，先调整方案。