Skip to content

feat: validate result.json schema and show actionable errors #63

@keting

Description

@keting

背景

HALF 当前通过固定任务目录下的 result.json 哨兵判断任务完成。执行 prompt 已要求 Agent 在所有产物写完后原子写入 result.json,并至少包含 task_codesummaryartifacts,但后端轮询目前只检查文件是否存在,不读取、不解析、不校验内容。

这会导致以下无效结果被误判为 completed:

  • result.json 不是合法 JSON
  • 缺少必要字段
  • task_code 与当前任务不匹配
  • artifacts 不是可用的仓库相对路径列表
  • Agent 写入了不符合 HALF 结果契约的结构

相关现状:

  • docs/task-lifecycle.md 明确当前不强制校验 result.json schema,只校验存在性
  • src/backend/services/polling_service.py::_detect_task_result 只调用 git_service.file_exists(...)
  • src/backend/services/prompt_service.py::generate_task_prompt 已要求 result.json 至少包含 task_codesummaryartifacts

目标

让 HALF 从:

发现 result.json 存在 → 认为任务完成

升级为:

发现 result.json 存在
→ 读取并校验
→ 合格则完成
→ 不合格则进入 needs_attention,并展示明确错误

建议范围

  • 在轮询检测到 <collaboration_dir>/<task_code>/result.json 后读取并解析 JSON
  • 定义最小 result.json 契约:task_codesummaryartifacts
  • 校验 task_code 必须等于当前 Task.task_code
  • 校验 artifacts 必须是数组,路径必须是仓库根相对路径,不得越界
  • 校验失败时不要把任务标记为 completed
  • 校验失败时复用当前状态模型:任务进入或保持 needs_attention,写入 Task.last_error,并创建 TaskEvent(event_type="error")
  • 校验成功时才设置 Task.status = "completed"completed_atresult_file_path
  • 前端展示可操作错误,例如 JSON 非法、缺少字段、任务编号不匹配、产物路径非法
  • 更新相关文档和测试

非目标

  • 不在本 Issue 中设计完整实验数据模型
  • 不在本 Issue 中实现 Failure Card
  • 不在本 Issue 中实现 trace / replay / export
  • 不在本 Issue 中讨论 usage.jsonactivity.json 或完整评估数据格式
  • 不新增复杂任务状态,优先复用 needs_attention + last_error + TaskEvent(error)

验收标准

  • 合法 result.json 可以使任务进入 completed
  • 非法 JSON 不会使任务 completed,并显示明确错误
  • 缺少必要字段时不误判完成
  • task_code 与当前任务不匹配时给出错误
  • artifacts 类型非法或路径非法时给出错误或明确 warning
  • 校验失败会写入 Task.last_errorTaskEvent(error)
  • Agent prompt / 文档中的结果写回要求与校验规则一致
  • 后端测试覆盖合法、非法 JSON、缺字段、任务不匹配、路径非法等场景

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:backendBackend / Python / FastAPI relatedarea:frontendFrontend / React / UI relatedstatus:readyTriaged and ready to pick uptype:featureNew user-facing capability

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions