# Day 1：基础模型与工程骨架 TODO 目标：建立后续 6 天开发所需的后端地基。Day 1 不做复杂业务逻辑，只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。 参考文档： - `document/development/agent plan/01_overall_architecture.md` - `document/development/agent plan/02_semantic_ontology.md` - `document/development/agent plan/06_data_contracts_and_governance.md` - `document/development/agent plan/07_capability_registry.md` - `document/development/agent plan/08_permission_confirmation.md` - `document/development/agent plan/09_observability_and_trace.md` ## 0. 开始前检查 - [ ] 确认当前分支和工作区状态。 - [ ] 确认后端目录位置，例如 `/app/server`。 - [ ] 确认前端目录位置，例如 `/app/web`。 - [ ] 确认后端使用的框架、ORM、迁移方式。 - [ ] 找到现有数据库模型目录。 - [ ] 找到现有 API 路由目录。 - [ ] 找到现有启动入口。 - [ ] 找到现有测试目录。 - [ ] 找到现有种子数据或初始化脚本。 - [ ] 记录不应修改的无关文件。 ## 1. 统一命名和边界 - [ ] 确认统一模块名使用 `agent_assets`。 - [ ] 确认资产类型枚举为 `rule`、`skill`、`mcp`、`task`。 - [ ] 确认资产状态枚举为 `draft`、`review`、`active`、`disabled`。 - [ ] 确认审核状态枚举为 `pending`、`approved`、`rejected`。 - [ ] 确认 Agent 枚举为 `orchestrator`、`user_agent`、`hermes`。 - [ ] 确认运行来源枚举为 `user_message`、`schedule`、`system_event`。 - [ ] 确认权限级别枚举为 `read`、`draft_write`、`approval_required`、`forbidden`。 - [ ] 确认所有主键、外键、时间字段命名符合现有代码风格。 验收证据： - [ ] 枚举命名在模型、Schema、服务层保持一致。 - [ ] 没有同时出现 `schedule` 和 `task` 两套用户可见命名。 ## 2. 建立 AgentAsset 模型 - [ ] 新增或扩展模型文件，定义 `AgentAsset`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `asset_type`，取值 `rule | skill | mcp | task`。 - [ ] 增加字段 `code`，作为业务编码。 - [ ] 增加字段 `name`。 - [ ] 增加字段 `description`。 - [ ] 增加字段 `domain`，例如 `expense | ar | ap | knowledge | system`。 - [ ] 增加字段 `scenario_json`，保存适用场景。 - [ ] 增加字段 `owner`。 - [ ] 增加字段 `reviewer`。 - [ ] 增加字段 `status`。 - [ ] 增加字段 `current_version`。 - [ ] 增加字段 `config_json`。 - [ ] 增加字段 `created_at`。 - [ ] 增加字段 `updated_at`。 - [ ] 给 `code` 增加唯一约束。 - [ ] 给 `asset_type` 增加索引。 - [ ] 给 `status` 增加索引。 - [ ] 给 `domain` 增加索引。 验收证据： - [ ] 能创建一条规则资产。 - [ ] 能创建一条技能资产。 - [ ] 能创建一条 MCP 资产。 - [ ] 能创建一条任务资产。 ## 3. 建立 AgentAssetVersion 模型 - [ ] 定义 `AgentAssetVersion`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `asset_id`。 - [ ] 增加字段 `version`，例如 `v1.0.0`。 - [ ] 增加字段 `content`。 - [ ] 增加字段 `content_type`，取值 `markdown | json`。 - [ ] 增加字段 `change_note`。 - [ ] 增加字段 `created_by`。 - [ ] 增加字段 `created_at`。 - [ ] 增加 `asset_id + version` 唯一约束。 - [ ] 建立 `AgentAsset` 到 `AgentAssetVersion` 的关系。 - [ ] 约定规则资产的 `content` 保存 Markdown。 - [ ] 约定技能、MCP、任务资产的 `content` 保存 JSON 快照。 验收证据： - [ ] 同一个资产不能重复创建同一个版本号。 - [ ] 资产详情能拿到最近 5 个版本。 ## 4. 建立 AgentAssetReview 模型 - [ ] 定义 `AgentAssetReview`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `asset_id`。 - [ ] 增加字段 `version`。 - [ ] 增加字段 `reviewer`。 - [ ] 增加字段 `review_status`。 - [ ] 增加字段 `review_note`。 - [ ] 增加字段 `reviewed_at`。 - [ ] 增加字段 `created_at`。 - [ ] 建立资产、版本、审核之间的查询关系。 - [ ] 增加服务层校验：没有 `approved` 审核时不能把规则置为 `active`。 验收证据： - [ ] `pending` 规则上线会被拒绝。 - [ ] `rejected` 规则上线会被拒绝。 - [ ] `approved` 规则可以上线。 ## 5. 建立 AgentRun 模型 - [ ] 定义 `AgentRun`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `run_id`。 - [ ] 增加字段 `agent`。 - [ ] 增加字段 `source`。 - [ ] 增加字段 `user_id`。 - [ ] 增加字段 `task_id`。 - [ ] 增加字段 `ontology_json`。 - [ ] 增加字段 `route_json`。 - [ ] 增加字段 `permission_level`。 - [ ] 增加字段 `status`，取值 `running | succeeded | failed | blocked`。 - [ ] 增加字段 `result_summary`。 - [ ] 增加字段 `error_message`。 - [ ] 增加字段 `started_at`。 - [ ] 增加字段 `finished_at`。 - [ ] 给 `run_id` 增加唯一约束。 - [ ] 给 `agent`、`status`、`started_at` 增加索引。 验收证据： - [ ] 创建任意 Agent 执行记录时必须生成 `run_id`。 - [ ] 失败执行能保存错误信息。 ## 6. 建立 AgentToolCall 模型 - [ ] 定义 `AgentToolCall`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `run_id`。 - [ ] 增加字段 `tool_type`，例如 `mcp | database | llm | ocr | rule_engine`。 - [ ] 增加字段 `tool_name`。 - [ ] 增加字段 `request_json`。 - [ ] 增加字段 `response_json`。 - [ ] 增加字段 `status`。 - [ ] 增加字段 `duration_ms`。 - [ ] 增加字段 `error_message`。 - [ ] 增加字段 `created_at`。 - [ ] 建立 `AgentRun` 到 `AgentToolCall` 的关系。 验收证据： - [ ] 一个 `run_id` 下可以记录多个工具调用。 - [ ] 工具调用失败时不影响主运行日志保存。 ## 7. 建立 SemanticParseLog 模型 - [ ] 定义 `SemanticParseLog`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `run_id`。 - [ ] 增加字段 `user_id`。 - [ ] 增加字段 `raw_query`。 - [ ] 增加字段 `scenario`。 - [ ] 增加字段 `intent`。 - [ ] 增加字段 `entities_json`。 - [ ] 增加字段 `time_range_json`。 - [ ] 增加字段 `metrics_json`。 - [ ] 增加字段 `constraints_json`。 - [ ] 增加字段 `risk_flags_json`。 - [ ] 增加字段 `permission_json`。 - [ ] 增加字段 `confidence`。 - [ ] 增加字段 `created_at`。 验收证据： - [ ] 能保存一条完整 8 字段语义解析日志。 - [ ] 能按 `run_id` 查询语义解析结果。 ## 8. 建立 AuditLog 模型 - [ ] 定义 `AuditLog`。 - [ ] 增加字段 `id`。 - [ ] 增加字段 `actor`。 - [ ] 增加字段 `action`。 - [ ] 增加字段 `resource_type`。 - [ ] 增加字段 `resource_id`。 - [ ] 增加字段 `before_json`。 - [ ] 增加字段 `after_json`。 - [ ] 增加字段 `request_id`。 - [ ] 增加字段 `created_at`。 - [ ] 为规则保存、审核、上线、任务执行创建审计记录接口。 验收证据： - [ ] 保存规则 Markdown 时有审计日志。 - [ ] 审核规则时有审计日志。 - [ ] 修改任务状态时有审计日志。 ## 9. 建立 Schema / DTO - [ ] 定义 `AgentAssetCreate`。 - [ ] 定义 `AgentAssetUpdate`。 - [ ] 定义 `AgentAssetRead`。 - [ ] 定义 `AgentAssetListItem`。 - [ ] 定义 `AgentAssetVersionRead`。 - [ ] 定义 `AgentAssetReviewRead`。 - [ ] 定义 `RuleMarkdownUpdate`。 - [ ] 定义 `AgentRunRead`。 - [ ] 定义 `AgentToolCallRead`。 - [ ] 定义 `SemanticParseRead`。 - [ ] 所有 JSON 字段在 DTO 中保持结构化，不返回字符串化 JSON。 验收证据： - [ ] OpenAPI 文档能展示新增 Schema。 - [ ] 列表 DTO 不返回大块 Markdown 内容。 - [ ] 详情 DTO 返回当前版本内容。 ## 10. 建立 API 骨架 - [ ] 新增 `GET /api/agent-assets`。 - [ ] 新增 `GET /api/agent-assets/{asset_id}`。 - [ ] 新增 `POST /api/agent-assets`。 - [ ] 新增 `PATCH /api/agent-assets/{asset_id}`。 - [ ] 新增 `GET /api/agent-assets/{asset_id}/versions`。 - [ ] 新增 `POST /api/agent-assets/{asset_id}/versions`。 - [ ] 新增 `POST /api/agent-assets/{asset_id}/reviews`。 - [ ] 新增 `POST /api/agent-assets/{asset_id}/activate`。 - [ ] 新增 `GET /api/agent-runs`。 - [ ] 新增 `GET /api/agent-runs/{run_id}`。 - [ ] 新增 `GET /api/audit-logs`。 - [ ] 所有接口先返回真实数据库结果，不使用前端硬编码数据作为最终结果。 验收证据： - [ ] 能调用资产列表接口。 - [ ] 能调用资产详情接口。 - [ ] 能调用版本接口。 - [ ] 能调用运行日志接口。 ## 11. 建立服务层 - [ ] 新增资产查询服务。 - [ ] 新增资产保存服务。 - [ ] 新增版本创建服务。 - [ ] 新增审核服务。 - [ ] 新增上线校验服务。 - [ ] 新增 Agent Run 创建服务。 - [ ] 新增 Tool Call 记录服务。 - [ ] 新增审计日志服务。 - [ ] 所有服务函数返回明确错误，不直接把数据库异常暴露给前端。 验收证据： - [ ] API 路由中不堆业务判断。 - [ ] 上线校验逻辑在服务层。 - [ ] 审计日志通过统一服务写入。 ## 12. 建立种子数据 - [ ] 创建至少 3 条规则资产。 - [ ] 每条规则资产至少有 2 个版本。 - [ ] 至少 1 条规则为 `active`。 - [ ] 至少 1 条规则为 `review`。 - [ ] 至少 1 条规则为 `draft`。 - [ ] 创建至少 2 条技能资产。 - [ ] 创建至少 2 条 MCP 资产。 - [ ] 创建至少 3 条任务资产。 - [ ] 为 active 规则创建 approved 审核记录。 - [ ] 为 review 规则创建 pending 审核记录。 验收证据： - [ ] 资产列表按类型筛选时四类都有数据。 - [ ] 规则详情能看到版本和审核者。 ## 13. 最小测试 - [ ] 编写资产模型创建测试。 - [ ] 编写版本唯一约束测试。 - [ ] 编写未审核不能上线测试。 - [ ] 编写资产列表接口测试。 - [ ] 编写资产详情接口测试。 - [ ] 编写 AgentRun 创建测试。 - [ ] 编写 AuditLog 写入测试。 验收证据： - [ ] 后端核心测试通过。 - [ ] 测试失败时能定位到具体服务。 ## 14. Day 1 验收 - [ ] 数据库能创建所有新增表或等价结构。 - [ ] API 服务能启动。 - [ ] OpenAPI 能看到新增接口。 - [ ] 资产列表接口返回规则、技能、MCP、任务。 - [ ] 规则资产有 Markdown 当前版本。 - [ ] 规则资产有最近版本列表。 - [ ] 未审核规则不能上线。 - [ ] AgentRun 能保存一条运行记录。 - [ ] AuditLog 能保存一条写操作记录。 - [ ] 所有完成项已用 `[x] ~~...~~` 标记。 ## 阻塞记录 - [ ] 暂无。 ## 日终交接 - [ ] 写明已完成模型。 - [ ] 写明已完成 API。 - [ ] 写明未完成问题。 - [ ] 写明 Day 2 前端联调需要使用的接口地址。