linapro

Imported from linaproai/linapro (AGENTS.md). Install upstream with npx skills add linaproai/linapro. Copyright stays with the author.

当前项目是全新项目，没有任何历史负担，在设计方案和实现时不用考虑任何的兼容性。

顶级规范要求

项目定位统一要求

1. 项目统一定位是面向可持续交付的 AI 原生全栈框架。所有功能设计都必须围绕这一定位展开。
2. 默认管理工作台、系统管理模块、用户权限模块等能力属于LinaPro提供的默认入口和内建通用能力，不构成项目的唯一产品边界。

核心宿主边界要求

1. 若项目根目录下不存在.contributing文件，那么在项目开发中，尤其是业务插件开发中，严格禁止修改框架相关的文件内容，例如apps/lina-core/、apps/lina-vben/、hack/目录下的文件内容。
2. apps/lina-core是全栈开发框架的核心宿主服务，负责提供通用模块接口能力、组件能力、系统治理能力与插件扩展能力。该服务的设计必须优先保证通用性、稳定性和可复用性，不得与具体管理工作台页面的展示结构、交互细节或前端框架实现强绑定。
3. 若需求仅来源于表格列、筛选项、树选择器、路由装配、工作台聚合、下拉选项等工作台展示变化，应优先通过工作台适配接口或前端适配层解决，而不是直接修改lina-core的核心领域契约、通用service语义或存储模型。
4. 在开发apps/lina-plugins/<plugin-id>/业务插件时，业务插件的相关前后端功能逻辑应当严格闭环在其内部实现，避免直接修改lina-core目录下的内容。确实需要修改时，必须评估是否会对其他插件或未来插件开发造成影响，并在实施前进行充分的设计和审查，并在用户授权的情况下进行修改。
5. 主框架插件能力发生变更时，必须审查apps/lina-core/pkg/plugin目录下的README文档是否需要同步更新。

接口性能统一要求

1. 功能设计和实现必须把接口性能作为基础约束，列表、详情批量、导出、聚合统计、树形数据、下拉候选、工作台聚合和插件资源扫描等高频或高数据量接口不得把性能优化留到后续补救。
2. 后端实现必须主动降低数据库操作频次，优先采用批量查询、集合化查询、投影查询、缓存或快照等方式完成数据装配，避免产生随返回行数、树节点数、插件数、权限项数或关联对象数线性增长的N+1查询。

外部规则文件

AGENTS.md是项目顶层规范入口；被本文件显式引用的.agents/rules/*.md是对应领域细则的唯一事实来源。AGENTS.md保留规范标题、强制触发场景和执行门禁，具体设计、实现、测试和审查细则必须到对应规则文件中读取。

插件本地规范优先级

• 修改apps/lina-plugins/<plugin-id>/下任意文件内容前，必须先检查该插件根目录是否存在AGENTS.md普通文件或符号链接。若插件根目录存在AGENTS.md文件，必须在修改该插件目录文件内容前优先读取并遵守该插件根目录AGENTS.md。
• 插件根目录AGENTS.md仅作用于该插件目录内的文件变更。其规范与项目顶层AGENTS.md或.agents/rules/*.md存在冲突时，在该插件目录内以插件根目录AGENTS.md为准；未覆盖部分继续遵守项目规范和命中的规则文件。

通用强制规则

• 执行提案、设计、实现、反馈修复、审查或归档时，必须先根据变更内容判断命中的规则域，并在修改代码、修改文档、更新任务状态或输出审查结论前读取所有命中的规则文件。
• 禁止仅凭记忆、历史上下文、摘要、此前读取记录或其他代理的转述替代本次读取。
• 同一任务命中多个规则域时，必须读取所有对应规则文件，并同时满足所有门禁要求。
• 规则文件缺失、无法读取或规则之间存在无法调和的冲突时，不得继续实现、反馈修复、审查或归档；必须先修复规则入口或向用户说明阻断原因。插件根目录AGENTS.md对本插件目录内文件的明确覆盖规则不视为无法调和冲突，按插件本地规范优先级处理。
• 若确认某规则域无影响，必须在任务记录、反馈执行记录或审查结论中明确记录无影响判断。
• 进行问题反馈修复时，必须优先排查并向用户报告问题原因，再进入代码修复；不得在未说明根因或合理假设的情况下直接改代码。
• lina-feedback和lina-review必须以本文件的强制触发场景为入口。未读取命中规则文件的反馈闭环或审查结论无效，不得据此标记任务完成或执行归档。

文档编写规范

文档编写规范细则的唯一事实来源为.agents/rules/documentation.md，以下任一场景命中时，必须在实施、反馈修复、审查或归档前读取并严格遵守该规则：

• 新增或修改仓库内技术文档、目录级说明文档、README.md或README.zh-CN.md
• 新增目录说明文档、变更 Markdown 格式、链接、表格、代码块或图示
• 修改 OpenSpec 文档语言、说明文档镜像关系或文档治理规则

开发流程规范

开发流程规范细则的唯一事实来源为.agents/rules/openspec.md，以下任一场景命中时，必须在实施、反馈修复、审查或归档前读取并严格遵守该规则：

• 创建、修改、执行或归档 OpenSpec 变更
• 编写或更新proposal.md、design.md、tasks.md或specs/增量规范
• 处理用户反馈、缺陷、改进点或治理类问题
• 执行/opsx:explore、/opsx:propose、/opsx:apply、/opsx:archive、lina-feedback或lina-review

架构设计规范

架构设计规范细则的唯一事实来源为.agents/rules/architecture.md。涉及数据权限时还必须读取.agents/rules/data-permission.md；涉及源码插件、动态插件或插件通用资源时还必须读取.agents/rules/plugin.md；涉及缓存时还必须读取.agents/rules/cache-consistency.md。

模块设计规范

以下任一场景命中时，必须读取并严格遵守.agents/rules/architecture.md：

• 新增或修改业务模块、模块能力边界、模块启停或模块间依赖
• 新增或修改模块间接口契约、跨模块调用路径、跨模块依赖注入或内部实现访问边界
• 新增或修改列表、详情批量、导出、聚合统计、树形数据、下拉候选、工作台聚合等接口的数据装配路径或性能边界
• 新增或修改具有枚举语义的业务值、字典类型、字典数据或模块运行配置
• 调整默认工作台、系统管理、用户权限等内建能力与框架宿主边界
• 设计前后端模块降级、隐藏、恢复或按需启用逻辑

数据权限接入规范

以下任一场景命中时，必须读取并严格遵守.agents/rules/data-permission.md：

• 新增或修改列表、详情、导出、下载、聚合统计、批量信息或下拉候选接口
• 新增或修改创建、更新、状态变更、删除、批量删除、授权关系变更或执行类动作
• 新增或修改插件通过宿主发布服务访问数据的路径
• 修改任何可能暴露业务数据存在性、可见性或租户/组织边界的逻辑

插件目录结构规范

开发业务插件，涉及apps/lina-plugins/<plugin-id>/目录下的任何资源创建、修改或删除时应当遵守.agents/rules/plugin.md。

接口设计规范

接口设计规范细则的唯一事实来源为.agents/rules/api-contract.md，以下任一场景命中时，必须在实施、反馈修复、审查或归档前读取并严格遵守该规则：

• 新增或修改 HTTP API、路由、HTTP 方法、资源路径或权限标签
• 修改请求 DTO、响应 DTO、OpenAPI/Swagger 元数据、g.Meta、dc或eg标签
• 新增或修改接口响应中的时间字段、日期字段或前后端 API 调用契约
• 新增或修改列表、详情批量、导出、聚合统计、树形数据、下拉候选、批量获取等高频或高数据量接口契约
• 修改可能改变前端调用频次、后端数据装配成本或数据库访问频次的接口响应结构
• 修改api/接口定义文件拆分、代码生成入口或接口文档语义

代码开发规范

开发工具与脚本规范

开发工具与脚本规范细则的唯一事实来源为.agents/rules/dev-tooling.md，以下任一场景命中时，必须读取并严格遵守该规则：

• 修改Makefile、make.cmd、hack/tools/、hack/scripts/、hack/tests/scripts/或hack/makefiles/
• 修改 CI、构建、测试、代码生成、资源打包、服务启停或仓库治理工具
• 新增或修改.sh、.ps1、.cmd、Node脚本或工具型 Go 代码
• 修改linactl命令文件、子组件、跨平台执行入口或默认开发路径

命中该规范时，必须记录跨平台影响和验证方式；未读取规则文件不得通过审查。

后端代码规范

后端代码规范细则的唯一事实来源为.agents/rules/backend-go.md，以下任一场景命中时，必须读取并严格遵守该规则：

• 新增或修改 Go 后端生产代码或 Go 后端测试
• 修改Controller、Middleware、Service、后端启动装配、路由绑定、依赖注入或运行时初始化逻辑
• 修改源码插件后端、插件宿主服务适配器、动态插件 host service 或WASM host service
• 修改错误处理、日志、公共组件、运行期依赖、缓存敏感服务、权限服务或生成代码边界
• 新增或修改列表、详情批量、导出、聚合统计、树形数据、下拉候选、批量操作等接口实现、数据库查询路径或可能产生N+1查询的循环数据装配逻辑

命中该规范时，必须按规则文件完成 Go 编译门禁、依赖治理和审查记录；未读取规则文件不得开始实现、标记任务完成、通过审查或归档。

Go代码生成流程

Go代码生成流程细则由.agents/rules/backend-go.md、.agents/rules/api-contract.md和.agents/rules/database.md共同承载，以下任一场景命中时，必须读取对应规则文件：

• API 变更、api/{resource}/v1/*.go变更或make ctrl相关变更
• 数据库变更、manifest/sql/变更、make db.init或make dao相关变更
• 生成或修改 Controller、DAO、DO、Entity 等脚手架维护代码

SQL文件管理规范

SQL文件管理规范细则的唯一事实来源为.agents/rules/database.md，以下任一场景命中时，必须读取并严格遵守该规则：

• 新增或修改 SQL 迁移文件、Seed DML、Mock 数据或插件安装/卸载 SQL
• 修改数据库初始化、升级、重试执行、幂等逻辑或 DAO 生成输入
• 修改软删除字段、数据库时间字段、删除语义或自增主键写入策略
• 新增或修改支撑列表、筛选、排序、聚合、关联装配、树形查询或数据权限过滤的索引与查询性能设计

命中该规范时，必须记录 SQL 幂等性、数据分类和验证结果；未读取规则文件不得通过审查。

接口层实现要求

接口层实现要求细则的唯一事实来源为.agents/rules/api-contract.md。修改api/目录、接口文件拆分、DTO 标签、权限标签或接口文档元数据前，必须读取并严格遵守该规则。

服务层实现要求

服务层实现要求细则的唯一事实来源为.agents/rules/backend-go.md。修改internal/service/、插件backend/internal/service/、服务接口、构造函数、文件命名、事务、数据库访问、接口性能、批量数据装配、定时任务或上下文传递前，必须读取并严格遵守该规则。

控制器层实现要求

控制器层实现要求细则的唯一事实来源为.agents/rules/backend-go.md。修改控制器构造、控制器依赖、_new.go结构、路由绑定或请求处理方法前，必须读取并严格遵守该规则。

软删除与时间维护规范

软删除与时间维护规范细则的唯一事实来源为.agents/rules/database.md。修改数据库时间字段、软删除字段、删除语义、查询过滤或 GoFrame 自动时间维护相关逻辑前，必须读取并严格遵守该规则。

前端代码规范

前端代码规范细则的唯一事实来源为.agents/rules/frontend-ui.md。以下任一场景命中时，必须读取并严格遵守该规则：

• 新增或修改前端页面、路由、组件、表格、表单、弹窗、抽屉或操作列
• 修改前端 API 调用、适配器层、权限控制、菜单显示逻辑或模块禁用联动
• 修改用户可观察交互、布局、样式、图标、上传下载或页面工作流

涉及用户可观察行为变化时，还必须读取.agents/rules/testing.md并补充或更新对应验证。

单元测试规范

单元测试规范细则的唯一事实来源为.agents/rules/testing.md。新增或修改单元测试、测试 helper、fixture、清理逻辑、全局状态或后端行为验证前，必须读取并严格遵守该规则。

E2E测试规范

E2E测试规范细则的唯一事实来源为.agents/rules/testing.md。新增或修改 E2E、页面对象、helper、fixture、runner 配置、执行 manifest、测试数据或用户可观察行为验证前，必须读取并严格遵守该规则，并按需使用lina-e2e技能。

I18N治理规范

i18n治理细则的唯一事实来源为.agents/rules/i18n.md。所有功能变更都必须评估i18n影响。以下任一场景命中时，必须读取并严格遵守该规则：

• 修改运行时用户可见文案、菜单、路由、按钮、表单、表格、提示信息或字典文案
• 修改 API 文档源文本、OpenAPI 元数据、错误消息、插件清单、语言包、翻译资源或语言配置
• 修改翻译缓存、manifest/i18n、apidoc i18n JSON或宿主/插件多语言边界

若确认无i18n影响，必须在任务记录或审查结论中明确记录。

UI设计规范

UI设计规范细则的唯一事实来源为.agents/rules/frontend-ui.md。实现任何前端页面、组件、交互、视觉样式、图标、表单、表格、弹窗或抽屉前，必须读取并严格遵守该规则。涉及用户可观察行为变化时，还必须读取.agents/rules/testing.md。