92444e7eae
- 新增 25+ 条风险规则（预算/报销/申请/通用类），完善风险规则模拟与反馈发布机制 - 引入费用审批动态路由、平台风险分级、预审与风险阶段管理 - 预算中心列表化改造，优化票据夹仪表盘与数字员工工作看板 - 新增 Hermes 风险线索收集器、Agent 链路追踪中心 - 扩展数字员工能力库（18 个领域 Skill）与交通费用自动预估 - 完善报销申请快速预览、权限控制与前端测试覆盖
57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
# X-Financial Agent 协作规范
|
||
|
||
## 语言规范
|
||
|
||
- 所有分析、解释、计划、提交说明和最终回复默认使用简体中文。
|
||
- 技术结论要直击重点，必要时给出可验证的文件、命令或测试结果。
|
||
|
||
## 通用代码拆分规范
|
||
|
||
无论写前端、后端还是算法代码，都必须主动避免“所有方法堆在一个类里 / 一个组件里 / 一个模块里”的写法。遇到类、组件或核心模块持续变大时，优先按职责拆分，而不是继续追加方法和状态。
|
||
|
||
### 行数与复杂度目标
|
||
|
||
- 单个类、核心组件、核心算法模块硬上限为 800 行。
|
||
- 普通文件建议控制在 300-600 行。
|
||
- 复杂业务文件可以接近 800 行，但必须有清晰职责边界。
|
||
- 文件或类超过 800 行必须视为重构预警，不应继续直接追加功能。
|
||
- 单个类不应长期承载几十个无关方法，更不应演化成上百个方法的万能类。
|
||
|
||
### 拆分原则
|
||
|
||
- 对外 API 尽量保持稳定，先把内部实现拆到小模块。
|
||
- 按职责拆分：编排、状态管理、持久化、权限、文件存储、OCR/票据分析、规则审核、响应构建、序列化、UI 交互、算法策略、数据转换。
|
||
- 新增能力时先判断归属模块；没有合适归属时新增小模块，不要默认塞回主类、主组件或主 Service。
|
||
- 拆分必须小步进行，每次提取一个明确职责，并配套运行相关测试。
|
||
|
||
### X-Financial 重点关注对象
|
||
|
||
- `ExpenseClaimService`：优先拆分申请单、明细项、附件、票据分析、草稿、规则审核、权限、序列化。
|
||
- `UserAgentService`：优先拆分知识库问答、报销预审 payload、Markdown 回复、差旅政策、表单槽位、票据分类、建议动作。
|
||
- `OrchestratorService`：优先拆分 agent 路由、工具调用、报销查询、响应构建。
|
||
- 前端大型 Vue 页面：优先拆分 composable、view model、样式分片、业务工具函数和子组件。
|
||
- 算法/规则模块：优先拆分输入解析、规则匹配、评分策略、结果解释和异常处理。
|
||
|
||
## 容器与运行环境（必读）
|
||
|
||
本项目代码是 Docker 容器 `x-financial-main`（镜像 `x-financial-dev:latest`）的源码映射。
|
||
|
||
- **容器映射**：宿主机 `D:\Code\Project\X-Financial` ↔ 容器内 `/app`（`docker-compose.yml` 中 `volumes: - .:/app`，`working_dir: /app`）。
|
||
- **后端 venv**：容器内位于 `/tmp/x-financial-server-venv`（环境变量 `SERVER_VENV_DIR`），不要假设宿主机上有相同的 venv。
|
||
- **外部依赖**：Qdrant（`x-financial-qdrant`）、OnlyOffice（`x-financial-onlyoffice`）也在同一 compose 网络里。
|
||
|
||
## 验证规范（硬性约束）
|
||
|
||
> 本项目代码与运行环境以容器为唯一事实来源。所有后端测试、集成测试、依赖了 Qdrant / OnlyOffice / venv 的验证，都必须在 `x-financial-main` 容器内执行，**不要在宿主机上直接跑 pytest / pip / python**。
|
||
|
||
- **进入容器跑命令**（最常用）：
|
||
```bash
|
||
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main <cmd>
|
||
```
|
||
- 跑后端测试：`docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/pytest -q <path>`
|
||
- 交互式排查：`docker exec -it -w /app x-financial-main bash`（登录后默认已在 `/app`）
|
||
- **容器不可用时**（未启动、健康检查失败、镜像丢失）：先 `docker compose up -d main` 恢复，再继续验证；不要绕开容器在宿主机另装 venv。
|
||
- **单元测试设置合理超时**，避免长时间卡死。涉及外部服务（Qdrant / OnlyOffice / LLM）的测试要么 mock，要么确认 compose 网络中依赖服务在线。
|
||
- **每次重构后至少运行对应服务的定向测试**；涉及公共协议时补充端到端或接口测试。
|
||
- **修改 docker-compose / start.sh / venv 路径相关代码**时，自己也要回容器里跑一次确认改动生效，不要只改文件就声称完成。
|