# qc 通过 zhctprompt 控制协作

## 1. 定位

`qc` 是智慧食堂售前轻采集系统。它本身负责采集客户基础信息、现场照片、访谈音频、项目痛点和导出资料；`zhctprompt` 负责用这些资料驱动售前方案、产品判断、项目任务和后续交付资产。

`qc` 不应变成一个孤立前端仓库。后续协作应按下面链路运行：

```text
qc 采集项目资料
-> zhctprompt work_qc 记录证据和运行状态
-> zhct-presales-solution-agent 生成售前方案 brief / 缺口清单
-> zhct-codex-project-collaboration-agent 路由到产品、微盘、交付、开发 specialist
-> 人工 review
-> 回传目标项目资料区或成熟售前系统
```

## 2. Agent 分工

| Agent | 职责 | 不做什么 |
| --- | --- | --- |
| `zhct-codex-project-collaboration-agent` | 管控 `qc` 任务契约、运行证据、任务索引、队列和 specialist 路由 | 不直接承诺客户、不绕过代码/发布/云效门禁 |
| `zhct-presales-solution-agent` | 读取 `qc` 采集结果，回调 `zhctprompt` 知识和项目证据，生成方案 brief、证据等级、gap list、人审页 | 不直接外发客户、不承诺价格/合同/医疗效果/未授权案例 |
| `zhct-wedrive-knowledge-agent` | 根据客户类型、项目场景和方案目标，从微盘派生索引定位来源资料 | 不复制原始大文件、不暴露敏感数据 |
| `zhct-product-strategy-agent` | 把售前采集内容映射到产品包、控标参数、AI 营养价值链和样板运营逻辑 | 不把 D 级假设写成确认事实 |
| `zhct-development-agent` | 当 `qc` 本身需要改代码时，创建任务契约、分支、验证和证据包 | 不在无任务契约时改业务代码 |

## 3. 输入输出协议

当 `qc` 采集到一个客户项目后，进入售前方案生成前，至少补齐：

| 字段 | 来源 | 用途 |
| --- | --- | --- |
| 项目名称 / 客户类型 | `qc` 表单或售前人员 | 判断方案模板和产品包 |
| 决策人 / 使用方 / 运维方 | `qc` 表单或访谈音频 | 判断价值主张和演示脚本 |
| 就餐规模 / 餐次 / 业务模式 | `qc` 表单 | 判断软件、硬件、设备和交付复杂度 |
| 现场照片 | `qc` 上传 | 判断动线、硬件点位、施工和演示素材 |
| 访谈音频 / 转写 | `qc` 录音或外部转写 | 抽取真实痛点和客户原话 |
| 导出 JSON / Excel / ZIP | `qc` 导出 | 作为方案生成的结构化来源 |
| 禁止承诺项 | 售前负责人 | 限制价格、合同、健康效果、客户案例等外发表达 |

方案请求可映射到：

```text
work/2026-06-02-two-ai-agent-callback-system/presales-callback-request-schema.csv
```

## 4. 本地运行门禁

`develop_0512` 当前需要 API + MySQL：

- 前端：`http://localhost:5173/`
- API：`http://localhost:3001/`
- 健康检查：`GET /api/health`
- 数据库：`smart_canteen_collection`

本地试跑不得连接生产库或 `.env.example` 中的远程数据库。没有真实开发库时，用隔离 Docker MySQL 容器。

## 5. 证据写回

每次运行或改动后写回：

- 本地运行记录：`work_qc/worklog/`
- 问答和风险：`work_qc/qa/`
- API / DB 变化：`work_qc/api-docs/`、`work_qc/db/`
- 任务索引：`control/task-index/items/<task_id>.tsv`
- 恢复面：`HEARTBEAT.md`、`tasks/QUEUE.md`

## 6. 当前待改进

- `.env` 当前在目标仓库中可见并被 Git 跟踪。后续应由代码任务单独处理：改为只提交 `.env.example`，真实 `.env` 加入 `.gitignore`，并确认历史提交中是否含敏感值。
- 微信登录需要真实 `WECHAT_APP_ID`、`WECHAT_APP_SECRET` 和回调域名；当前本地只验证 API 和前端启动，不验证真实微信授权闭环。
- Browser 自动化工具当前未接入本线程，浏览器层 smoke 只做了 HTTP 级验证。