wangys/K12Study
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
master
K12Study/AGENT.md
wangys 2476655b28 更新
2026-04-17 16:31:32 +08:00

4.8 KiB
Raw Permalink Blame History

K12Study Agent 工程规范

本文件是所有自动化 agent（Claude Code / Cursor / Copilot 等）在本仓库工作时必须遵守的项目级规范。 细则源文件位于 .agents/skills/*/SKILL.md，本文件是汇总入口，改动时两处保持一致。

1. 统一响应体契约（API Response）

来源：.agents/skills/k12-api-response-standard/SKILL.md

适用场景

  • 新增或改造后端 API
  • 改动前端 / 小程序请求层
  • 修复“后端已报错但前端当成功处理”的联调问题

契约

响应体结构固定为 code / message / data / traceId 四字段。

  • 成功：code === 0
  • 业务失败：code !== 0，前端必须抛错并使用 message 透出
  • traceId 必须保留用于链路追踪

强制项

  1. 后端 Controller 与全局异常处理统一返回 ApiResponse（位于 common-api）
  2. 前端 frontend/src/utils/http.ts、小程序 app/src/utils/request.js 必须同时校验 HTTP 状态码与业务 code
  3. 新接口落地时同步检查类型声明与调用方解包方式，避免重复定义结构
  4. 同步更新 docs/architecture/api-design.md 中响应体约定

禁止项

  • 禁止字段重命名（如 message → msg）
  • 禁止去掉 traceId

2. RESTful 接口风格

来源：.agents/skills/k12-restful-api-style/SKILL.md

适用场景

  • 新增 API 设计
  • 旧接口路径改造（如 current-user、*/tree）
  • 同步网关白名单与客户端调用路径

设计规则

  • 路径优先使用资源名（名词），不是动作名
  • 集合资源使用复数：/users、/departments、/classes
  • “当前用户”使用语义路径：/users/current
  • 树形结构通过资源路径表达：/areas、/tenants、/departments
  • 统一入口前缀：/api/*，不得更改

强制项

  1. Controller 使用 RESTful 主路径
  2. 改路径必须同步更新：前端 API、小程序 API、网关白名单、docs/architecture/api-design.md、docs/architecture/logical-view.md
  3. Feign 契约（apis/api-*/remote/*RemoteApi.java）与 Controller 路径必须一致；启动时 FeignContractValidator 会校验

禁止项

  • 旧接口不兼容，禁止保留/恢复兼容别名
  • 禁止动词化路径（如 /getUser、/doLogin）

3. 注释头规范

来源：.agents/skills/k12-comment-header-standard/SKILL.md

适用场景

  • 任务涉及 global.code-snippets、.fileheader/fileheader.config.yaml
  • 用户要求统一文件头 / 函数注释规范
  • @author 对齐 git user.name

强制项

  1. 以 git config user.name 为 @author 基线（当前：wangys）
  2. 更新 global.code-snippets 中 FileHeader 与 Method 的 author 默认值
  3. 使用 turbo-file-header 的项目须检查 .fileheader/fileheader.config.yaml 的 @author
  4. 修改后验证 JSON / YAML 可解析
  5. 保留字段顺序：description / filename / author / copyright / since

禁止项

  • 不在此规范下修改业务逻辑代码

4. 前端导入别名规范

来源：.agents/skills/k12-frontend-import-alias/SKILL.md

适用场景

  • 修改 frontend/src 下任意 ts/tsx/js 文件
  • 新增组件、页面、路由、API、store、utils 模块
  • 代码评审指出存在 ../、../../ 上跳导入

强制项

  1. 跨目录导入统一使用 @/ 别名路径（例如 @/api、@/pages、@/utils）。
  2. 禁止使用 ../、../../ 等上跳相对导入。
  3. 禁止使用以 / 开头的模块导入路径（如 from "/utils/http"）。
  4. 同目录导入允许使用 ./（例如 ./index.scss）。
  5. 改动后执行 pnpm --dir frontend build 验证。

禁止项

  • 禁止新增任何 ../、../../ 或以 / 开头的导入写法。

5. Feign 契约与微服务边界（补充）

非 skills 原有条款，但属于本仓库架构约束，agent 工作时必须遵守。

  • apis/api-* 模块只放 DTO + @FeignClient 接口 + 路径常量 + FallbackFactory，不得依赖 service / jdbc / redis
  • 新业务模块同时做 Provider + Consumer 时引 common-feign，自动启用 @EnableFeignClients(basePackages="com.k12study.api") + OkHttp + Authorization 透传 + 启动契约自检
  • 微服务模式通过 Nacos（spring-cloud-starter-alibaba-nacos-discovery）寻址，单体 / 本地联调通过 k12study.remote.<module>.url 走直连 URL 兜底
  • 熔断降级统一返回 ApiResponse.failure(503, reason)，前端按标准响应体处理

6. Agent 协作约定

  • 任务拆解与进度跟踪优先使用 TaskCreate / TaskUpdate，而不是把进度写进 memory
  • 任何对本文件、.agents/skills/*、docs/architecture/* 的改动都必须在同一次提交中同步
  • 本文件若与 .agents/skills/*/SKILL.md 冲突，以 SKILL.md 为准（SKILL.md 是细则源头）