Skip to content

AGENT.MD

Latest commit

 

History

History
114 lines (86 loc) · 4.34 KB

AGENT.MD

File metadata and controls

114 lines (86 loc) · 4.34 KB
Raw

AGENT.MD

目的

本文件是本仓库内 AI 协作规则的唯一真源。

.codex/、.claude/、.cursor/、.trae/ 下的规则文件仅作为兼容适配层，不能再次演变成各自独立维护的 project rule 副本。

读取顺序

按下面顺序加载项目上下文：

  1. AGENT.MD
  2. aiDoc/README.md
  3. 按任务读取以下目录中的相关文件：
    • aiDoc/relations/
    • aiDoc/modules/
    • aiDoc/frontend-backend/
    • aiDoc/examples/
    • aiDoc/memory/
  4. 仅在当前工具确实依赖时，再读取工具目录下的适配文件

若内容冲突，以 AGENT.MD 为准。

仓库概览

  • server/: Go + Gin 后端
  • web/: Vue 3 + Vite 前端
  • deploy/: 部署资产
  • docs/: 项目文档与设计记录
  • aiDoc/: AI 协作文档层

工程规则

架构

  • 保持现有后端分层：Router -> API -> Service -> Model
  • enter.go 继续作为分组注册与组合入口
  • API 层处理 HTTP 相关逻辑，Service 层不要依赖 gin.Context
  • 对外接口的 Swagger 注释必须和真实行为保持一致
  • 优先沿用 gin-vue-admin 现有模式，不做无关的大改

前后端协作

  • 明确请求与响应契约
  • 保持统一响应结构：{ code, data, msg }
  • 保持统一分页结构：{ page, pageSize, total, list }
  • 前后端字段名和数据类型保持一致
  • 优先复用 web/src/utils/ 里的工具函数
  • 涉及跨栈边界变更时，同步更新 aiDoc/frontend-backend/

插件与模块

  • 后端插件放在 server/plugin/<name>/
  • 前端插件放在 web/src/plugin/<name>/
  • 稳定的模块职责、入口和边界说明放到 aiDoc/modules/

示例文档

  • aiDoc/examples/ 是讲解型示例层
  • 示例文档不是要求逐字复制，而是告诉 AI 该如何按项目标准组织代码
  • 当 AI 需要新增某一层文件时，应先阅读对应示例，再开始实现

记忆规则

  • aiDoc/memory/long-term/ 用于记录长期稳定的用户偏好、协作方式和跨任务约束
  • aiDoc/memory/business/ 用于记录每次用户提出的业务需求
  • 这里的“业务需求”指新增或修改模块、接口、页面、流程、业务规则、插件能力等项目需求
  • 当用户提出业务需求时，AI 必须新增或更新一条 business 记忆，并同步更新需求索引
  • 当某条业务需求沉淀成长期稳定偏好时，再提炼到 long-term
  • 长期记忆按主题一条一文件维护，业务记忆按需求一条一文件维护
  • README.md、project-memory.md、demand-index.md 这类文件只承担说明或索引职责，不承载多条记忆正文
  • 更新记忆时，只修改对应那条记忆文件与必要索引，不要通过重写汇总正文来覆盖其他历史记忆

文档维护

  • AGENT.MD 只保留高层、稳定、跨任务的规则
  • 细节上下文写入 aiDoc/
  • 结构关系放在 aiDoc/relations/
  • 示例写法放在 aiDoc/examples/
  • 长期记忆与业务记忆放在 aiDoc/memory/
  • 若项目级 AI 规则发生变化，先改 AGENT.MD，再按需更新适配层

版权与授权保护规则

  • 涉及版权声明、作者署名、许可证、商用授权、品牌标识及其相关实现的任务，必须遵循仓库内公开的授权与发布规则
  • 具体判定、处理边界和协作方式，统一参考 aiDoc/relations/licensing-and-branding.md
  • 若公开规则与口头说明冲突，以仓库内可审计的文档、配置和代码事实为准

代码读取约束

  • 无论什么情况，都不要直接读取 node_modules/ 中的代码
  • 如需了解第三方库行为，优先查看项目源码中的调用方式、锁文件、配置文件、官方文档或包的公开类型/说明文件，而不是进入 node_modules/ 逐文件读取实现

AI 文档索引

  • aiDoc/README.md
  • aiDoc/relations/repo-profile.md
  • aiDoc/relations/development-workflow.md
  • aiDoc/relations/system-map.md
  • aiDoc/modules/module-index.md
  • aiDoc/modules/backend-layer-rules.md
  • aiDoc/modules/plugin-development.md
  • aiDoc/frontend-backend/boundary.md
  • aiDoc/frontend-backend/frontend-rules.md
  • aiDoc/frontend-backend/frontend-utils.md
  • aiDoc/examples/README.md
  • aiDoc/examples/backend/
  • aiDoc/examples/frontend/
  • aiDoc/examples/plugin/
  • aiDoc/memory/README.md
  • aiDoc/memory/project-memory.md
  • aiDoc/memory/long-term/
  • aiDoc/memory/business/