Comment Task Manager

任务状态管理

⚠️ 数据平面已脚本化：本 Skill 的组装执行入口已切换为 scripts/build_ui_payload.py（白名单裁剪 + 挂载增强字段 + 产出 open_comment_reply_ui 完整入参 + 直连 MCP 调 set_common_data_cache 写后台缓存），Agent 不再手工组装、也不再透传大载荷——只需把脚本返回的 data_cache_id 传给 open_comment_reply_ui。本文档的11 字段白名单、ai_suggestion/process_name/refer_process_num 挂载规则、submit.next_step 契约文案、open_comment_reply_ui schema 约束仍为权威定义，脚本按其实现。

概述

本 Skill 负责组装 Phase 1-4 的输出为前端需要的结构化数据，并管理留言回复任务的状态。

核心功能：

• 组装结构化数据（total / risk_total / list），由 Agent 调用 MCP 工具 open_comment_reply_ui（gongyi-open-mcp）传入该 JSON 展示到留言回复页面
• list 元素为 OrgCommentItem 按最小白名单裁剪后的字段（仅保留 UI 展示 + 提交必需的 12 个协议字段：comment_id / subject_id / content / project_id / project_name / created_at / nick_name / object_type / object_id / risk_audit_status / risk_audit_reason / head_img，其余 21 个字段全部剔除）+ ai_suggestion 增强字段 + process_name 增强字段（仅 process 类型，取自进展标题，供前端展示信息来源）+ refer_process_num 增强字段（int，参考的进展条数，供前端展示信息来源规模）
• 列表顺序保持 MCP 返回的原始数组顺序（后台返回的 tool 数据本身已排好序），Agent 不做任何二次排序
• 管理任务状态（选中状态、编辑内容）

关键约束：

• 不含机构鉴权（MCP Token 自动完成）
• 只负责数据组装，不负责 UI 渲染
• list 元素必须按最小白名单裁剪 OrgCommentItem：只保留 12 个协议字段（comment_id / subject_id / content / project_id / project_name / created_at / nick_name / object_type / object_id / risk_audit_status / risk_audit_reason / head_img），其余字段（status / gy_uid / like_num / comment_type / can_reply / is_recommended / reply_list / audit_type / risk_audit_at / opt_user / parent_comment_content / is_sticky / sticky_expire / can_sticky / can_cancel_sticky / can_delete / org_comment_id / org_reply_content / org_reply_time / parent_comment / audit_reject_reason 共 21 个）一律剔除（UI 不使用）；不得新增业务字段（ai_suggestion、process_name、refer_process_num 三个 Agent 增强字段除外）
• 输出顶层只允许 total / risk_total / list / submit（open_comment_reply_ui schema 不接受 code/msg，additionalProperties: false）；调用工具时另传 schema 唯一必填字段 caller_expert_id（详见参考文档）；Agent 运行状态（processed、ui_push_status、ui_push_error、note 等）禁止写入输出 JSON，由 Agent 文本报告承载
• reply-generator 的 sources（事实来源记录）属内部审计数据，不得挂载到 list 元素，不进入 UI 协议
• 字段类型对齐协议：comment_id（uint64）全程必须是 JSON number——fetch_payload.py 落盘 comments_brief.json 时已将上游字符串形态统一转为 int（Python int 无精度问题），本地文件与 set_common_data_cache 调用均不得出现字符串形态；build_ui_payload.py 保留防御性转换兜底；org_comment_id 等其他字段保持原始类型原样透传
• 输出结构必须与 openspec/changes/comment-assistant/fe-view-protocol.md 协议一定义完全一致

触发场景

Agent 在 Phase 3（组装数据并调用 open_comment_reply_ui 展示留言回复页面）时加载本 Skill。本 Skill 只负责组装输出 JSON；Agent 拿到输出后必须调用 open_comment_reply_ui 将其展示到留言回复页面，不得仅以文本形式输出列表。

输入格式

{
  "comments": [
    {
      "comment_id": 123456789,
      "subject_id": "subj_001",
      "content": "钱都去哪了？...",
      "object_type": "project",
      "object_id": "224328",
      "project_id": "224328",
      "project_name": "春蕾计划她们想上学",
      "nick_name": "爱心网友A",
      "created_at": 1756000000,
      "status": 1,
      "risk_audit_status": 4,
      "risk_audit_reason": "质疑资金去向"
    }
  ],
  "ai_suggestions": {
    "123456789": "您好，感谢您的关注和监督！..."
  },
  "total": 36,
  "risk_total": 2
}

工作流程

采用零转录（no re-transcription）原地增强方式组装，杜绝手工抄写字段导致的错值/丢字段/类型变化：

1. 保留原始对象：Phase 1 MCP 返回的响应对象原样保留在内存中（或原样字节），不重新拼写、不逐字段抄录、不写中间转换脚本/中间 JSON 文件
2. 原地挂载（仅有的三个赋值操作）：
   • list[i].ai_suggestion = ai_suggestions[list[i].comment_id]；未处理到的条目置空串
   • list[i].process_name：仅当 list[i].object_type === 'process' 时赋值，取 contexts['process:' + list[i].object_id]?.process_detail?.content_title；取不到（进展拉取失败/无标题）或 project 类型置空串
   • list[i].refer_process_num（int，参考的进展条数）：object_type === 'project' 时取 contexts['project:' + list[i].object_id]?.process_list?.length ?? 0（0~5，无进展/拉取失败为 0）；object_type === 'process' 时取 1（参考该条进展；process_detail 拉取失败则取 0） 除 ai_suggestion、process_name 与 refer_process_num 外不允许对任何字段重新赋值
3. 最小白名单裁剪（仅有的删除操作）：每个 list[i] 只保留 12 个协议字段（comment_id / subject_id / content / project_id / project_name / created_at / nick_name / object_type / object_id / risk_audit_status / risk_audit_reason / head_img），删除其余全部字段（status / gy_uid / like_num / comment_type / can_reply / is_recommended / reply_list / audit_type / risk_audit_at / opt_user / parent_comment_content / is_sticky / sticky_expire / can_sticky / can_cancel_sticky / can_delete / org_comment_id / org_reply_content / org_reply_time / parent_comment / audit_reject_reason 共 21 个，UI 不使用）；保留字段的值一律原样，不增不改
4. 保持原始顺序：list 不做任何排序/重排——后台返回的 tool 数据本身已排好序，按数组原始顺序直接展示
5. 缓存写入 + key 展示：脚本把组装好的 {total, risk_total, list, submit} 直连 MCP 调 set_common_data_cache 写入后台缓存，返回 data_cache_id；Agent 调 open_comment_reply_ui 只传 caller_expert_id + data_cache_id，大载荷不经过 LLM 输出。submit 固定为 {"next_step": "执行comment-assistant专家的刷新留言列表步骤"}，告知 APP 应发起的专家步骤调用（回复由 APP 直连后台提交并自动删除已提交留言，不经 Agent；仅剩余待回复为 0 时 APP 才通知 Host 发起该步骤）。缓存写入失败时也走相同方式（caller_expert_id + data_cache_id）

⛔ 禁止：

• 把留言字段逐个手写进新 JSON（历史事故：head_img 重复、project_id 乱码、误加 code/msg、list 多余嵌套，均源于手工转录/组装）
• 由 Agent 在上下文内手工执行本 Skill 的组装逻辑——组装的唯一执行入口是 scripts/build_ui_payload.py（在本地完成裁剪与挂载、写出 ui_payload.json，并直连 MCP 把数据写入后台缓存；Agent 只把返回的 data_cache_id 传给 open_comment_reply_ui，无需 Read 载荷文件）；手工组装在大载荷场景已实测发生结构错误与超长输出

输出格式

{
  "total": 36,
  "risk_total": 2,
  "submit": {
    "next_step": "执行comment-assistant专家的刷新留言列表步骤"
  },
  "list": [
    {
      "comment_id": 123456789,
      "subject_id": "subj_001",
      "content": "钱都去哪了？一直没看到进展更新，是不是骗人的？",
      "project_id": "224328",
      "project_name": "春蕾计划她们想上学",
      "created_at": 1756000000,
      "nick_name": "爱心网友A",
      "object_type": "project",
      "object_id": "224328",
      "risk_audit_status": 4,
      "risk_audit_reason": "质疑资金去向",
      "ai_suggestion": "您好，感谢您的关注和监督！项目善款已于7月15日完成拨付...",
      "process_name": "",
      "refer_process_num": 5
    },
    {
      "comment_id": 123456790,
      "subject_id": "subj_002",
      "content": "加油！希望孩子们都能好好读书",
      "project_id": "224328",
      "project_name": "春蕾计划她们想上学",
      "created_at": 1756000100,
      "nick_name": "匿名捐赠人",
      "object_type": "project",
      "object_id": "224328",
      "risk_audit_status": 3,
      "ai_suggestion": "感谢支持，我们会持续努力！",
      "process_name": "",
      "refer_process_num": 5
    }
  ]
}

顶层只含 total / risk_total / list / submit：open_comment_reply_ui 的 schema 为 additionalProperties: false，传入 code/msg 会被参数校验直接拒绝。无论主路径还是降级路径，Agent 都只传 caller_expert_id + data_cache_id（data_cache_id = set_common_data_cache 返回的缓存 key，由脚本写入后台缓存后获得）。submit.next_step 固定为「执行comment-assistant专家的刷新留言列表步骤」，一字不差（格式为可路由句式"执行X专家的Y步骤"，Host 据此解析专家与步骤名并重新调度）。错误信息由 Agent 文本报告承载，不写入输出 JSON。

关键规则：

• list[] 元素必须按最小白名单裁剪：只保留 comment_id / subject_id / content / project_id / project_name / created_at / nick_name / object_type / object_id / risk_audit_status / risk_audit_reason / head_img 共 12 个协议字段 + 3 个增强字段，其余 21 个字段一律剔除（UI 不使用），不得额外裁剪或新增
• process_name 仅 process 类型挂载（取 process_detail.content_title），供前端展示「信息来源：项目名称（项目id）；进展名称（进展id）」；project 类型为空串
• refer_process_num 为 int：project 类型 = 该项目上下文 process_list 条数（0~5，无进展/拉取失败为 0）；process 类型 = 1（参考该条进展，process_detail 拉取失败为 0），供前端展示「参考进展 N 条」
• ai_suggestion 取自输入 ai_suggestions 映射，原样写入；未生成建议的条目置空串（前端做空态展示）
• 不拆分高风险/无风险列表，也不对 list 做二次排序；高风险优先由后台返回的原始数组顺序体现

异常处理

依赖

• 无外部依赖（纯数据组装）

参考文档

• references/tools/open_comment_reply_ui.md：open_comment_reply_ui 工具调用参数定义（仅 caller_expert_id + data_cache_id）
• references/tools/set_common_data_cache.md：set_common_data_cache 写入数据的 JSON 结构定义（total/risk_total/list/submit 字段表、CommentReplyItem / CommentReplyChildItem 元素白名单、调用示例与注意事项）