d4ff79f326
- AGENTS.md 新增变更日志 Skill 规范：变更后增量更新 document/work-log，更新前先做 Git 拉取检查 - 新增 .codex/skills 下 agent-change-log、git-checkpoint-commit 两个 skill - 新增 .githooks/post-commit 与 tools/agent-change-log 自动化脚本，提供提交后最低限度日志追加
5.2 KiB
5.2 KiB
X-Financial Agent 协作规范
语言规范
- 所有分析、解释、计划、提交说明和最终回复默认使用简体中文。
- 技术结论要直击重点，必要时给出可验证的文件、命令或测试结果。
变更日志 Skill 规范
- 每次修复 bug、新增功能、重构、修改配置或编辑项目文档后，必须调用项目级 Skill
agent-change-log，并增量更新document/work-log/YYYY-MM-DD.md。 - 更新日志前必须先执行 Git 拉取检查：默认运行
git fetch --all --prune、git status -sb、git log HEAD..@{u}和git log @{u}..HEAD；如果工作区干净且只落后上游，可以git pull --ff-only。发现其他智能体已提交到上游或本地 ahead 提交时，要先把这些提交摘要分析进当天日志。 - 自动化触发由
tools/agent-change-log/update_change_log.py和.githooks/post-commit提供；新 checkout 需要执行tools/agent-change-log/install_post_commit_hook.sh安装到本地.git/hooks/post-commit后，提交后才会自动追加最低限度日志。 - 如果当前环境无法写
.git或无法执行git fetch，必须把这个限制写进当天日志；不能把 Skill/AGENTS 规则误当成已经有后台自动化。 - 日志必须保留
当日工作内容、遗留问题、TODO三块；TODO 使用 Markdown checkbox，完成项勾选并用删除线保留历史。 - 记录要写清楚具体时间、改了什么、操作了什么、验证了什么、还遗留什么问题，以及建议下一步怎么处理。
通用代码拆分规范
无论写前端、后端还是算法代码，都必须主动避免“所有方法堆在一个类里 / 一个组件里 / 一个模块里”的写法。遇到类、组件或核心模块持续变大时，优先按职责拆分，而不是继续追加方法和状态。
行数与复杂度目标
- 单个类、核心组件、核心算法模块硬上限为 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。
- 进入容器跑命令（最常用）：
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 路径相关代码时，自己也要回容器里跑一次确认改动生效，不要只改文件就声称完成。