Imported from caresoft-ricent/beaver-ai-agent (AGENTS.md). Install upstream with npx skills add caresoft-ricent/beaver-ai-agent. Copyright stays with the author.

Beaver AI Agent - 统一约束总纲（Strict v2）

0. 单一主源与优先级

• 根 AGENTS.md 是仓库级唯一主约束源，适用于整个仓库。
• .codex/README.md、CLAUDE.md、.github/copilot-instructions.md、.github/instructions/*.instructions.md、目录级 AGENTS.md 均为同源镜像或目录细则，不得冲突。
• 优先级：根 AGENTS.md > 目录级 AGENTS.md > 工具镜像文件（Claude/Copilot）> docs/skills/* 执行手册；下位规则只允许补充更具体的目录约束，安全红线冲突时按更严格者执行。
• 单一真源：环境/启动/调试见 dev-setup.md，禁止在约束文件复制维护启动命令；生产库 schema 变更见 docs/db-change-policy.md；测试规范见 docs/testing-spec.md；轨道 B 设计见 docs/Ontora-模型配置与推理设计.md。
• 仓库内文本文件统一使用 UTF-8 编码（无 BOM）。
• 读取仓库文本文件时默认按 UTF-8 解码；PowerShell 使用 Get-Content -Encoding UTF8，脚本/程序读取显式传 encoding="utf-8"，避免按系统默认编码读出乱码。

1. 执行方式

• 明确要求做事时立即执行并完成最小闭环验证；问询或商量口吻先给方案，待确认后再执行；拿不准按问询处理。
• 高风险改动必须先确认：数据库结构变更或批量数据迁移、引擎职责边界调整、多租户策略调整或跨租户能力开放、对外 API 破坏性变更、新核心框架/ORM/状态管理/RPC 体系引入。
• 每次编码前先判断改动所属轨道、引擎边界、语义态影响与租户作用域。
• 实现时如发现用户新指令、当前方案、既有代码、设计文档或总纲约束存在冲突，必须先显式列出冲突点与权威来源，待确认后再修改实现或设计；禁止用临时实现反向覆盖已锁定设计。

2. 业务架构边界

2.1 引擎边界

• 模型治理层负责 Domain/Entity/Action/Parameter 元数据治理、生命周期与配置维护；不得执行外部业务 API 或生成最终回调文本。
• 运行时 engine 当前包含两部分：本体消费与调用执行。本体消费负责领域/本体/属性等意图裁决、上下文构建与阶段 Intent 产出；调用执行负责 API 调用、请求/响应适配与回复组装。
• 本体消费阶段可以按阶段职责读取运行时清单并调用 LLM 进行领域/本体/属性裁决；禁止执行外部业务 API、生成最终回调文本或修改本体语义定义。
• 调用执行阶段禁止进行领域/本体意图判断或修改实体语义定义；只能消费上游阶段产物与按需加载的调用契约。
• 禁止将业务规则硬编码到 api/v1/chat.py 主链、P0-P7 阶段或任意旁路链路。
• domain / entity / action 的名称或 id 必须来自数据库，禁止硬编码本体。

2.2 四语义态

• 语义态流转必须走统一入口，禁止旁路语义态逻辑。
• 语义态展示以后端返回为准，前端禁止自定义语义态推断覆盖后端结果。
• 语义态规则变更必须同步后端映射、前端展示与测试用例。

2.3 多租户

• 所有读写必须绑定 tenant 作用域；豁免只适用于明确的全局资源、系统元数据、基线只读资源或启动/注册类基础设施。
• tenant 豁免必须写明资源类型、访问边界与验证方式，且不得降低验证要求：必须证明不承载租户私有数据、不形成跨租户读写入口；涉及接口时仍需覆盖合法访问、越权阻断或无租户上下文处理。
• 涉及租户作用域的数据操作必须显式 tenant 过滤；服务层必须将 tenant_id 作为显性参数传入。
• 跨租户操作必须具备显式授权与审计记录；禁止前后端实现绕过租户隔离的临时逻辑。
• 租户属性只能引用本租户或基线，禁止跨租户引用。
• 基线侧可查看租户侧数据，但不得直接维护租户侧 Domain/Entity/Property；仅允许基线侧生命周期级联间接影响租户侧数据，且不得暴露为手动跨租户操作入口。

2.4 双轨道

• 轨道 A：入口 run_v2_chain，服务包 backend/app/services/engine/，仅修 bug / 小增强；架构级改动先确认，新推理能力不得进入轨道 A。
• 轨道 B：入口 run_v3_chain，服务包 backend/app/services/engine_v3/，按 docs/Ontora-模型配置与推理设计.md 对齐。
• v2/v3 只能在 api/v1/chat.py 的 /stream 单一路由内按租户配置分叉，鉴权 / 会话 / 存库 / SSE 为共享外壳；禁止另起路由或硬编码轨道。
• v3 必须复用 v2 的 AG-UI 异步生成器契约。

3. 工程边界

• 使用既有技术栈：Backend（Python / FastAPI / SQLAlchemy / Alembic / MySQL / Redis / Pytest），Frontend（React / TypeScript / Vite / Axios）。
• 未经明确批准，禁止引入新核心框架、ORM、状态管理或 RPC 体系；新增依赖包必须先说明包名、用途、是否写入 requirements.txt / package.json 并取得确认。已声明依赖允许安装。
• 按顺序实现：数据结构/契约 -> 服务编排 -> 接口适配 -> 前端接入 -> 测试补齐；后端先 Model/Schema，前端先 Type/API Contract。
• 优先复用已有模块；新增模块前说明不可复用原因；保持函数单一职责与可读命名，禁止点状补丁式修复。
• 业务状态、发布状态、语义态、参数状态等固定取值必须放在 backend/app/constants/ 下统一引用，禁止在业务代码和测试中硬编码字符串或数字字面量。
• 涉及业务数据流或持久化的功能，按生产者 / 持久化 / 消费者三要素梳理。
• 删除文件或代码后清理变空目录、__pycache__/、*.pyc、孤立 import 等残留；空壳 __init__.py 仅在确认不影响包导入时删除。

4. 生产数据安全红线

• 开发测试阶段不写生产库；ip + 端口 + 库名三者与生产完全一致的库即生产库。
• 日常操作生产库仅允许 SELECT / SHOW，查询前先 SHOW COLUMNS；生产库 schema 变更只能走 docs/db-change-policy.md 并人工确认，未确认前按只读处理。
• 生产库禁止 UPDATE、DELETE、TRUNCATE、DROP TABLE|INDEX|DATABASE、ALTER ... DROP|MODIFY|CHANGE。
• 三者任一不同（如专用测试库、TEST_DB_NAME、_test 后缀）方可正常读写；含数据库操作的改动必须在测试库跑通。
• 数据库迁移必须可逆（upgrade/downgrade）；数据回填前必须 dry-run 并核验物理字段。

5. 目录级约束入口

• Backend 细则见 backend/AGENTS.md；轨道 A/B 还需分别遵守 backend/app/services/engine/AGENTS.md 与 backend/app/services/engine_v3/AGENTS.md。
• Frontend 细则见 frontend/AGENTS.md。
• 工具镜像文件只做同源入口，不承载独立业务/工程规则。

6. Skills 路由

• 仅在任务意图严格匹配时加载对应 docs/skills 执行手册，不匹配不加载兜底 skill。
• 后端接口新增/改造：docs/skills/backend-api-end2end.md；Alembic 迁移/数据回填：docs/skills/alembic-safe-migration.md；前端契约字段变更：docs/skills/frontend-contract-change.md；多租户相关验证：docs/skills/multi-tenant-test-pack.md。
• 命中 skill 且当前上下文未包含其内容时，必须实际读取对应 skill 文件后再实施；交付整理不走 skill 路由；skills 不得替代仓库级安全与架构边界。
• 可执行任务响应中标注 Applied skills；无命中则标注 none。

7. 测试门禁

• 所有行为变更必须补充或更新测试；Service 逻辑变更补充单元测试，API 行为变更补充集成测试。
• 公共方法默认应有直接用例；简单透传、框架 glue code、纯类型映射或已有集成测试完整覆盖的路径，可在交付说明中写明覆盖来源与不补直接用例的理由。
• 测试例外不得适用于业务规则、租户隔离、语义态流转、引擎边界、数据库写入、错误分支或对外 API 行为；这些路径必须保留直接测试或集成测试证据。
• 关键错误分支至少有一个可复现断言用例；涉及引擎边界、语义态、多租户的改动必须补充对应回归测试。
• 语义态与多租户相关前端改动覆盖成功与失败路径；禁止仅凭单一路径通过或无验证证据即宣称完成。

8. 交付要求

• 非小改动交付必须包含架构映射（轨道 / 引擎 / 语义态 / 租户）、变更清单、测试证据、残余风险、回滚路径。
• 高风险改动必须明确说明 DB、跨租户、架构边界或对外 API 影响。
• 回滚路径按实际改动说明：代码回退、迁移 downgrade、配置恢复、数据回滚方案。
• 仅在准备执行 git 提交时维护一次根目录 CHANGELOG.md，按本次提交聚合记录变更类型与简要描述；禁止同一提交内按每个小改动分别新增记录。
• 目录结构或职责调整后必须更新对应 README / 约束说明；交付说明必须与代码实际状态一致。