Yuxi AGENTS.md

Yuxi Agent 开发约定

Yuxi 是基于 LangGraph、FastAPI、Vue 和多种持久化服务构建的知识库与多智能体平台。Docker Compose 是开发拓扑的事实来源；修改不熟悉的模块前先阅读 ARCHITECTURE.md，再用符号搜索确认真实实现。

每次任务先加载什么

• ARCHITECTURE.md：稳定边界、主链路和架构不变量。
• Yuxi Spec Loop：非平凡变更从提案、证据到收敛的流程。
• 工程信任系统：语义 Owner、证据、决策记录、派生审计和 gate 规则。
• 测试规范：unit、integration、E2E 的职责与命令。
• 贡献指南：分支、独立 Review、commit 和 PR 流程。
• 用户在当前任务中的明确要求优先于本文件；修改 backend/、web/ 或 docs/ 时同时遵循该子树的 AGENTS.md。子树规则只补充本目录，不复制回根文件。

任务与决策

1. 开始实现前，把请求压缩为可验证的目标、非目标和验收主张；多步任务先给出每步带验证方式的简短计划。
2. 假设显式记录后继续；只有当不同解释会改变验收结果、数据、安全或外部状态时才阻塞询问，并把候选解释一并列出而不是默默选择其一。存在明显更简单的方案时，先说明取舍再动手。
3. 把"可以""也可以""类似这样""例如"当作简单方向，不是设计更大机制、配置项或兼容层的许可。
4. 在真实语义 Owner 处闭合受影响的工程主张：源码、数据约束或当前契约拥有事实；独立 oracle 与负向案例证明它；实际 workflow 或可问责 Reviewer 产生拒绝后果。不要建立可独立编辑的中央主张清单或 claim ID 体系。
5. 非平凡变更必须新增或更新一份 tracked 决策记录。记录问题、当前决定、真实替代项、后果和验证，不保存推理流水账或实现过程叙事。
6. docs/vibe/ 只用于本地临时计划，被 Git 忽略，不是组织记忆，也不能作为已完成事实的唯一来源。
7. 只修改验收标准需要的范围；不顺手重构、格式化或添加想象中的配置、兼容层和扩展点。

不能破坏的系统事实

• HTTP 路由保持薄；用例流程属于 yuxi.services，持久化查询属于 yuxi.repositories。
• 普通请求先在 PostgreSQL 中持久化 Message 和 AgentRunRequest；只有 ready FIFO 队头创建 AgentRun，且每次投递 ARQ 前 owning transaction 都已提交。Redis 负责投递、短期事件、取消和缓存，不拥有最终业务状态。
• 同一用户、Agent、线程的普通请求按 FIFO 串行派发；Request 和 Run 是不同状态模型。
• AgentRun 的输出、事件、artifact 和错误必须绑定同一 request/run；禁止从相邻 Run 猜测结果。
• 非终态 Run 必须有明确执行 Owner、lease/heartbeat 或等价机制，以及崩溃后的可观察结局。
• /api/system/health 只表达进程 liveness；接流量前置条件由 /api/system/ready 证明，业务正确性仍由真实链路测试证明。
• LangGraph checkpoint 只使用 PostgreSQL；API、worker 与 Agent 不提供本地后端选择或静默降级。
• 权限在后端依赖与 repository 可见性查询处最终执行；前端守卫、prompt、schema omission 和 UI 隐藏不是授权边界。
• LITE 的 shipping 启动、路由注册和能力发现不得导入或初始化知识库、图谱和评估的重运行时；仍保留的附件解析入口只在真实解析动作发生时惰性加载 parser。
• 沙盒虚拟路径、对象 URL 和宿主机路径不可混用；所有用户路径必须在 owning filesystem boundary 校验。

证据规则

• Agent 的完成报告、HTTP 200、日志关键词或 mock 调用次数都不是最终事实；重新读取数据库、文件、对象、DOM 或协议结果。
• 每个新 guard 都要有一个能恢复目标缺陷并使其在正确原因上失败的负向测试。
• 测试从最小相关集合开始，再按风险扩大；不要用 unit 结果替代真实 PostgreSQL、真实 HTTP、worker 或浏览器语义。
• Expected output、snapshot 和 fixture 只能显式更新并审阅；CI 不得一边生成 oracle 一边验证 oracle。
• 实际执行命令、结果和未执行原因写入 PR；未验证不能写成通过。