From 680c2a07492bf7efbc6ae87f3038021a444c7f6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com> Date: Sun, 13 Sep 2026 19:04:29 +0800 Subject: [PATCH] =?UTF-8?q?=EF=BB=BFdocs(AGENTS):=20=E8=A1=A5=20Worker=20?= =?UTF-8?q?=E5=B8=B8=E9=A9=BB=E4=B8=8E=E5=8F=91=E5=B8=83=E8=84=9A=E6=9C=AC?= =?UTF-8?q?=E7=BB=A7=E6=89=BF=E8=8C=83=E5=9B=B4=E7=9A=84=E8=B8=A9=E5=9D=91?= =?UTF-8?q?=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增一条：客服/风控对话必须有常驻 Worker（python -m app.worker）。没有它时 agent_run 停在 status=queued、worker_id 为空，前端只会显示"客服响应超时/繁忙" —— 看起来像链路慢，实际是没人处理。附排查第一步（查 agent_run 最新那行） 与本机实测延迟（端到端 4.1-4.8 秒，其中受理只占 0.05 秒）。 - 更新发布脚本那条：继承范围必须覆盖全部三张受管表（此前只搬 platform_config_item， 把 customer_service_chitchat 提示词静默漏在旧版本里），并写明知识类意图要同时发 search_knowledge 与 query_knowledge。 --- AGENTS.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 53cb44d..69e9c59 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,10 +102,24 @@ 另注：`sys_user` 已改为「存在则更新、不存在才插入」，故重跑种子**不会**再弄丢演示密码。 - ⚠️ **`config_release` 是环境数据，不随代码合并**：本机 active 版本 id 与架构师环境**不同** （本机是我方发布的客服白名单；他那边还有风控的 9 条白名单）。**"白名单已发布"必须带环境限定**，换环境要重发。 - 发布脚本 `tools/publish_customer_service_config.py`（**同 key 的继承项必须被本次定义覆盖**，否则旧值会被子集校验 422 拦下整次发布）。 + 发布脚本 `tools/publish_customer_service_config.py`：**同 key 的继承项必须被本次定义覆盖**， + 否则旧值会被子集校验 422 拦下整次发布；**继承范围必须覆盖全部三张受管表** —— + 它此前只搬 `platform_config_item`，把 `customer_service_chitchat` 提示词静默漏在了旧版本里 + （Agent 侧有代码默认值兜底，所以功能看着正常、零告警）。现已改用 + `ConfigReleaseService.effective_snapshot()` 并在激活后硬校验条数，不符即失败退出。 + 另：知识类意图要**同时**发 `search_knowledge`（登录客户走）与 `query_knowledge` + （访客令牌只有 `knowledge:query`），缺哪一条对应人群就一问即失败。 - ⚠️ **Milvus 集合 schema 也因环境而异**：本机是 `knowledge_id`/`snippet`（无 `visibility`）， 架构师环境是 `doc_id`/`content`/`visibility`/`chapter`…。**检索层已改为运行时探测字段名** （`app/core/knowledge_schema.py`）——**不要在任何地方硬编码字段名**，那会把另一套环境打挂。 +- ⚠️ **客服/风控对话必须有常驻 Worker**：`python -m app.worker`。Agent 请求是 + 「受理 202 → Worker 领单 → 落结果」三段式；没有 Worker 时 `agent_run` 会一直停在 + `status='queued'`、`worker_id` 为空，而前端只显示"客服响应超时 / 客服繁忙"—— + **看起来像链路慢，实际是没人处理**（2026-09-13 访客浮窗"回答超时"就是栽在这里）。 + 排查第一步：查 `agent_run` 最新那行是不是 `queued`。反过来，跑验收脚本前又要 + **先停掉**它，否则会抢队列（见 `docs/20`）。 + 本机实测（Worker 在跑 + `deepseek-flash`）：访客一问端到端 **4.1–4.8 秒**， + 其中受理只占 0.05 秒，其余是一次意图分类加一次 embedding 检索。 - ⚠️ **Docker Desktop 不会常驻**：它没运行时 Milvus 不可用（`docker` CLI 报连不上守护进程）。 跑真机验证前先确认 Docker Desktop 在运行。 - ⚠️ **`memory_sync_outbox` 的取值必须是小写英文**（`milvus`/`neo4j`、`upsert`、