X-Financial/document/development/agent week plan/day_1_foundation_models.md

Day 1：基础模型与工程骨架

当前状态

• Day 1 已完成（2026-05-11）。
• 后端基础模型、API 骨架、种子数据、审计能力和 Day 2 联调入口均已落地。

今天的大开发点

Day 1 只做地基，不做复杂 Agent 智能。

核心是把后面 6 天都会用到的基础对象建出来：资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志，以及最小财务业务数据来源。

为什么第一天做这个

如果没有稳定的数据模型，后面的任务规则中心、语义本体、Orchestrator、User Agent、Hermes 都会各自临时造结构，后期会很难合并。

今天主要交付

• 统一资产模型：规则、技能、MCP、任务。
• 版本模型：规则 Markdown 和其他资产配置快照。
• 审核模型：未审核不能上线。
• Agent 运行日志：所有 Agent 执行都有 run_id。
• 工具调用日志：MCP、数据库、LLM、OCR、规则引擎调用都可追踪。
• 语义解析日志：后续语义本体结果可回放。
• 审计日志：所有写操作可追责。
• 最小财务业务数据来源：报销、应收、应付。

实际落地结果

• 新增 AgentAsset、AgentAssetVersion、AgentAssetReview、AgentRun、AgentToolCall、SemanticParseLog、AuditLog、ExpenseClaim、ExpenseClaimItem、AccountsReceivableRecord、AccountsPayableRecord。
• 新增 /api/v1/agent-assets、/api/v1/agent-runs、/api/v1/audit-logs 相关接口。
• 种子数据已覆盖 3 条规则、2 条技能、2 条 MCP、3 条任务，以及报销 / 应收 / 应付示例数据。
• 旧开发库启动时会自动补齐新增资产和版本，不需要手动清库。

相关架构文档：

• 整体架构
• 语义本体
• 数据契约与治理
• 能力注册
• 权限与确认
• 观测与 Trace
• 财务单据标准模型

当天验收门槛

• 数据库或等价存储能创建基础对象。
• API 服务能启动。
• 资产列表能返回规则、技能、MCP、任务。
• 规则资产能关联 Markdown 当前版本。
• 未审核规则不能上线。
• AgentRun 能保存一条运行记录。
• AuditLog 能保存一条写操作记录。

Day 2 联调入口

• GET /api/v1/agent-assets
• GET /api/v1/agent-assets/{asset_id}
• GET /api/v1/agent-assets/{asset_id}/versions?limit=5
• POST /api/v1/agent-assets/{asset_id}/reviews
• POST /api/v1/agent-assets/{asset_id}/activate
• GET /api/v1/audit-logs

今天不做

• 不做完整 Agent 对话。
• 不做完整 Hermes 调度。
• 不做真实 OCR。
• 不做复杂规则推理。

详细执行清单

以下内容为合并后的详细执行清单。

0. 开始前检查

• 确认后端目录为 /app/server，模型、路由、启动入口和测试目录已定位。
• 确认本次改动以增量方式落到现有 FastAPI + SQLAlchemy 工程，不回退无关文件。

验收证据：

• 模型注册位于 server/src/app/db/base.py，路由注册位于 server/src/app/api/v1/router.py，启动入口位于 server/src/app/main.py，测试位于 server/tests。

1. 统一命名和边界

• 统一枚举：rule | skill | mcp | task、draft | review | active | disabled、pending | approved | rejected、orchestrator | user_agent | hermes。
• 统一运行来源、权限级别、内容类型、运行状态和工具类型命名，避免出现第二套并行语义。

验收证据：

• server/src/app/core/agent_enums.py 已成为模型、Schema 和服务层的统一枚举入口。

2. 设计最小财务业务数据模型

• 建立 expense_claims、expense_claim_items、accounts_receivable、accounts_payable。
• 字段覆盖时间、地点、理由、金额、员工、部门、状态，以及应收 / 应付的金额、到期日、账龄、风险标记。

验收证据：

• server/src/app/models/financial_record.py 与 document/development/agent plan/14_financial_document_canonical_model.md 形成直接映射。

3. 建立 AgentAsset 模型

• 建立 AgentAsset，包含 asset_type、code、name、description、domain、scenario_json、owner、reviewer、status、current_version、config_json 等核心字段。
• 对 code、asset_type、status、domain 建立唯一约束或索引。

验收证据：

• 资产列表可按 rule、skill、mcp、task 四类过滤返回。

4. 建立 AgentAssetVersion 模型

• 建立 AgentAssetVersion，规则版本保存 Markdown，其余资产版本保存 JSON 快照。
• 对 asset_id + version 建立唯一约束，并支持按资产读取最近版本列表。

验收证据：

• 规则详情接口可返回 current_version_content 和 recent_versions。

5. 建立 AgentAssetReview 模型

• 建立 AgentAssetReview，保存版本、审核人、审核状态、审核备注和审核时间。
• 服务层实现规则版本未 approved 时禁止上线。

验收证据：

• POST /api/v1/agent-assets/{asset_id}/activate 对待审规则返回 400 拦截。

6. 建立 AgentRun 模型

• 建立 AgentRun，包含 run_id、agent、source、ontology_json、route_json、permission_level、status、result_summary、error_message 等字段。
• 所有运行记录统一生成 run_id，并允许失败态保存错误信息。

验收证据：

• AgentRunService.create_run() 会自动生成 run_ 前缀标识，并可回读失败摘要。

7. 建立 AgentToolCall 模型

• 建立 AgentToolCall，可记录工具类型、工具名、请求 / 响应 JSON、耗时和错误信息。
• 同一个 run_id 下支持多次工具调用追踪。

验收证据：

• 种子运行数据已覆盖数据库查询、MCP 调用和权限规则引擎调用。

8. 建立 SemanticParseLog 模型

• 建立 SemanticParseLog，覆盖场景、意图、实体、时间范围、指标、约束、风险、权限和置信度。
• 支持按 run_id 回放 Day 3 语义结果。

验收证据：

• GET /api/v1/agent-runs/{run_id} 已能携带 semantic_parse 返回。

9. 建立 AuditLog 模型

• 建立 AuditLog 和统一 AuditLogService。
• 资产创建、版本保存、审核、上线等写操作都会留下审计记录。

验收证据：

• GET /api/v1/audit-logs 可返回种子审计日志，服务层新建资产也会落审计。

10. 建立 Schema / DTO

• 建立 AgentAssetCreate / Update / Read / ListItem、AgentAssetVersionRead、AgentAssetReviewRead、RuleMarkdownUpdate、AgentRunRead、AgentToolCallRead、SemanticParseRead。
• 所有 JSON 字段以结构化对象返回，不回传字符串化 JSON。

验收证据：

• 列表 DTO 不返回大块 Markdown，详情 DTO 返回当前版本正文和最近版本。

11. 建立 API 骨架

• 建立 GET/POST/PATCH /api/v1/agent-assets、GET /api/v1/agent-assets/{asset_id}、GET/POST /api/v1/agent-assets/{asset_id}/versions、POST /api/v1/agent-assets/{asset_id}/reviews、POST /api/v1/agent-assets/{asset_id}/activate。
• 建立 GET /api/v1/agent-runs、GET /api/v1/agent-runs/{run_id}、GET /api/v1/audit-logs。

验收证据：

• 所有接口已挂到 server/src/app/api/v1/router.py，并通过 create_app() 自动暴露。

12. 建立种子数据

• 种子资产补齐到 3 条规则、2 条技能、2 条 MCP、3 条任务。
• 三条规则都具备至少 2 个版本，并覆盖 approved / pending / rejected 三种审核样本。
• 旧开发数据库启动时会自动增量补齐新增资产和版本，不要求手动清库。

验收证据：

• Smoke：GET /api/v1/agent-assets 返回 10 条资产，GET /api/v1/agent-runs 返回 3 条运行日志，GET /api/v1/audit-logs 返回 4 条审计日志。

13. 最小测试

• 新增 Day 1 服务层与接口层测试，覆盖种子完整性、版本历史、未审核不能上线、运行日志生成和审计日志写入。
• Ruff 校验通过，Day 1 新增文件保持可检查状态。

验收证据：

• /app/server/.venv/bin/pytest -q /app/server/tests/test_agent_asset_service.py /app/server/tests/test_agent_foundation_endpoints.py -> 11 passed。
• /app/server/.venv/bin/pytest -q tests 已通过全量后端测试。

14. Day 1 验收

• 数据库能创建所有新增表或等价结构。
• API 服务能启动，OpenAPI 能看到新增接口。
• 资产列表接口返回规则、技能、MCP、任务；规则详情带 Markdown 当前版本和最近版本列表。
• 未审核规则不能上线；AgentRun 和 AuditLog 均可保存记录。
• 所有 Day 1 TODO 已改为完成态。

阻塞记录

• 暂无阻塞。

日终交接

• 已完成模型：资产、版本、审核、运行日志、工具调用、语义解析、审计、报销、应收、应付。
• 已完成 API：/api/v1/agent-assets、/api/v1/agent-runs、/api/v1/audit-logs。
• Day 2 前端联调应优先使用 GET /api/v1/agent-assets、GET /api/v1/agent-assets/{asset_id}、GET /api/v1/agent-assets/{asset_id}/versions?limit=5、POST /api/v1/agent-assets/{asset_id}/reviews、POST /api/v1/agent-assets/{asset_id}/activate。
• 后续 Day 4 及以后运行时方向按用户要求转向 LangChain + LangGraph，Hermes 继续作为内部数字员工入口；Day 1 保留为数据与治理底座。