ZHCTPROMPT-20260730-AI-QA-API-DOC

智慧食堂助手 AI 问答接口文档 Review

目标是让 PC 前端、测试和后续 Agent 能按当前代码直接联调，不把设计稿或 Coze 上游接口误写成已落地契约。

源码核对完成 63 tests / 408 assertions 真实登录 HTTP 待复验

交付入口

正式接口文档agentAssistant.md

任务契约task-contract.md

验证记录verification.md

原始需求raw-request.md

接口范围

接口	方法	权限	结论
`/p/agent/ask`	POST	登录 + 服务端入口/数据过滤	主问答接口
`/p/agent/history`	GET	仅本人	分页参数放 query
`/p/agent/suggestionClick`	POST	登录	记录失败不阻断跳转
`/p/agent/feedback`	POST	登录	仅 helpful / unhelpful

关键边界

本文档不覆盖旧 Apifox 归档里的 Coze /v3/chat。
不把 askStream、conversation_id、task_id 或动作执行写成现状。
确定性业务数字只允许来自权限校验后的页面上下文或只读工具。
tool_observation 是随能力变化的诊断结构，不建议前端作为固定公共 DTO 依赖。
问题和日志仍应避免携带凭据、个人敏感信息或生产原始 payload。

人工 Review 清单

前端确认使用 answer、suggestions、clarification、action_cards、log_id 即可兼容。
后端确认 page_context 字段与目标页面 Collector 一致。
测试使用完整权限、部门受限、菜单受限三个账号各执行一次真实 HTTP 联调。
若需要 Apifox 或 OpenAPI，再从本文档生成独立导入文件并回读验证。

当前 Review 状态：待人工确认；未收到人的认可或否定反馈，不升级为新的项目规范。