Yuxi-Know

# Yuxi Agent 开发约定

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

## 每次任务先加载什么

- [ARCHITECTURE.md](ARCHITECTURE.md)：稳定边界、主链路和架构不变量。
- [Yuxi Spec Loop](docs/develop-guides/spec-loop.md)：非平凡变更从提案、证据到收敛的流程。
- [工程信任系统](docs/develop-guides/engineering-trust.md)：语义 Owner、证据、决策记录、派生审计和 gate 规则。
- [测试规范](docs/develop-guides/testing-guidelines.md)：unit、integration、E2E 的职责与命令。
- [贡献指南](docs/develop-guides/contributing.md)：分支、独立 Review、commit 和 PR 流程。
- [并行工作树与隔离运行环境](docs/develop-guides/parallel-worktree-environments.md)：同时运行多个分支、复用长期数据或处理 Schema 不兼容时加载。
- 用户在当前任务中的明确要求优先于本文件；修改 `backend/`、`web/` 或 `docs/` 时同时遵循该子树的 `AGENTS.md`。子树规则只补充本目录，不复制回根文件。

## 任务与决策

1. 开始实现前，把请求压缩为可验证的目标、非目标和验收主张；多步任务先给出每步带验证方式的简短计划。
2. 假设显式记录后继续；只有当不同解释会改变验收结果、数据、安全或外部状态时才阻塞询问，并把候选解释一并列出而不是默默选择其一。存在明显更简单的方案时，先说明取舍再动手。
3. 把"可以""也可以""类似这样""例如"当作简单方向，不是设计更大机制、配置项或兼容层的许可。
4. 在真实语义 Owner 处闭合受影响的工程主张：源码、数据约束或当前契约拥有事实；独立 oracle 与负向案例证明它；实际 workflow 或可问责 Reviewer 产生拒绝后果。不要建立可独立编辑的中央主张清单或 claim ID 体系。
5. 非平凡变更必须新增或更新一份 tracked [决策记录](docs/develop-guides/decisions/README.md)。记录问题、当前决定、真实替代项、后果和验证，不保存推理流水账或实现过程叙事。
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 隐藏不是授权边界。
- Shipping 启动、路由注册和能力发现始终包含知识库、图谱与评估能力；附件解析入口只在真实解析动作发生时惰性加载 parser。
- 沙盒虚拟路径、对象 URL 和宿主机路径不可混用；所有用户路径必须在 owning filesystem boundary 校验。

## 证据规则

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

提交前在仓库根目录至少运行：

```bash
python3 scripts/verify_engineering_contracts.py
python3 -m unittest scripts.test_verify_engineering_contracts
docker compose exec api uv run --group test pytest test/unit -m "not slow"
```

改动面按下表选择最低证据，并按升级条件扩大；不要用低层级结果替代高风险语义。

| 改动面 | 最低证据 | 何时升级 |
|---|---|---|
| 纯 Python / JS 逻辑 | 相关 unit，断言业务结果 | 触及数据库、缓存或文件副作用时补 integration |
| API / 权限 / 持久化 | 真实 HTTP integration | 跨 worker、队列或用户主链路时补 E2E |
| Run / FIFO / SSE / 沙盒 / 恢复 | E2E，验证最终状态与产物 | 依赖外部可选服务时记录环境与未验证范围 |
| 前端交互 | lint + unit（[web/AGENTS.md](web/AGENTS.md)） | 行为关键时补 build 与真实页面验证 |
| 文档与导航 | 相对链接检查 + docs build | 公开行为变化时与代码验证一起执行 |

完整命令由 [测试规范](docs/develop-guides/testing-guidelines.md) 维护。

## 实现与安全

- 使用满足验收标准的最小、线性实现。抽象、状态机、fallback、兼容路径和依赖都要有当前 consumer 与 Owner；仓库外用户、持久数据和部署承诺也算 consumer。
- 实现明显长于问题本身，或一半行数可以清楚表达同样行为时，先简化再提交；自检"高级工程师是否会认为这段代码过度设计、过度防御或过于零碎"。
- 不可信输入只在 parser、配置、模型/tool JSON、持久化、worker、process、wire 和用户路径等真实信任边界校验；授权与隔离在产生副作用的 executor/repository fail-closed，直接或替代调用路径都不能绕过。
- 预设条件不成立时显式失败。可选能力可以降级，但必须结构化、可观察，且不把未就绪伪装为成功。
- 新增函数/类使用简洁中文 docstring；注释只解释非显然约束、时序、Owner 和安全用法，不复述代码。
- 不输出或提交 `.env`、账号、Token、用户数据、运行目录和构建产物。
- 文件以一个换行结尾；提交前运行 `git diff --check`。

## Review 与交付

所有代码变更在 commit 前必须由不继承开发上下文的全新 Reviewer Agent 审查完整需求、diff、测试和规范；修复所有影响功能、边界、证据可信度或认知负担的问题。提交信息使用中文 Conventional Commit，PR 使用仓库模板，以自然语言列出受影响主张、语义 Owner、证据、风险和未验证范围，不引用中央 claim ID。

More agent context in xerrors/Yuxi-Know

4 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• xerrors/Yuxi7.3k