客服 Agent 接入底座：访客身份、画像候选、转人工工单（含底座合规清理） #7

2026-09-12T11:35:41+08:00

Zsy_0626 commented

2026-09-12 11:35:41 +08:00

合并内容

将 ZSY_develop 的客服 Agent 能力接入 qyqy_develop，基线为 qyqy_develop 最新提交 c4a73b7。

1. 提交构成

e85989b：把 c4a73b7（账号密码登录 + RBAC 只读查询等 7 个提交）合入 ZSY_develop，无冲突（增量合并，复用此前已解决的语义冲突）。
9aaacc2：按 AGENTS.md 与底座文档逐条核对后，移除撞到底座规则的内容。

2. 底座合规清理（`9aaacc2`，9 文件 +189/−483）

删除 app/service/knowledge_tool_service.py、app/infrastructure/milvus_knowledge_adapter.py：后者硬编码 Milvus 字段名，违反 AGENTS.md §E；两者均为生产死代码。生产检索实际走 knowledge_search_tool -> KnowledgeSearchService -> app/core/knowledge_schema.py 的运行时字段探测，无任何硬编码字段名。
app/service/knowledge_retrieval_service.py 整文件回退为底座版本，移除 legacy 双构造与重复检索实现。
docs/05-接口文档.md：新增的「客服画像候选」由误占的 §8.2 改登记为 §8.5，恢复 ### 8.2 解析知识引用；§8.1–§8.4 原编号一字未动。
app/model/profile.py：current_customer_id 改为普通可空列映射。原来按「生成列」写成 Computed(...)，会让 SQLAlchemy 从 INSERT 中排除该列，与真实 schema 不符。

3. 需评审确认的底座扩展

详见 docs/客服Agent接入底座扩展说明_v1.md（A 纯新增 / B 默认行为不变的扩展 / C 需确认 / D 已移除 / E 明确未改动 / F 环境约束）：

C1 访客身份：app/core/security.py（visitor: true 声明分支）+ app/api/dependencies/auth.py（访客跳过 IdentityService.resolve）。
C2 客服 Agent 角色与行为：app/service/agent/implementations/customer_service.py。
C3 画像快照 ORM 去重与 current_customer_id 映射：app/model/profile.py、app/model/risk_questionnaire.py。
C4 Milvus 双地址：MILVUS_LOCAL_URI 在团队/生产环境须留空。

4. 验证结果

pytest tests/unit tests/contract -q -p no:cacheprovider -> 1275 passed, 2 skipped, 0 failed
ruff check app tests tools alembic -> All checks passed
mypy app -> 244 个源文件无问题

5. 遗留事项

待确认：访客令牌 sub 是否纯数字（是，且走底座原有校验、未放宽）；recalls_customer_memory 默认值（True，仅 customer_service 显式关闭）。
docs/00 第 783 行把 profile_snapshots.current_customer_id 描述为「生成列」，与 docs/02/alembic 基线 DDL 及真实库不一致，请底座侧决定以哪侧为准。
本 PR 不包含对 docs/00、docs/02、alembic/ 的任何改动。

6. 评审后修订（`f68b052`）

按 qyqy 在评审中提出的两项要求处理：

docs/05 §19 端点编号去重：客服画像候选的两个端点由 A034/A035 改为 A039/A040（原编号与 qyqy 侧登录 / RBAC 只读接口 A034–A038 重复；docs 守卫脚本只校验文档文件名编号、不校验 §19 端点编号，故会静默遗留）。改后全表 55 个端点编号全唯一。
milvus-lite 降为可选依赖：由 [project] dependencies 移到 [project.optional-dependencies] dev；requirements.txt 不再作为生效依赖，仅留说明注释。

修订后复验（origin/qyqy_develop 已推进至 ade5e0c）：

git merge-tree --write-tree f68b052 ade5e0c → 无冲突（c4a73b7 是 ade5e0c 的祖先，属增量推进）
pytest tests/unit tests/contract -q -p no:cacheprovider → 1275 passed, 2 skipped, 0 failed
ruff check app tests tools alembic → All checks passed；mypy app → 244 个源文件无问题

7. 环境数据对齐（`sys_permission`）

我方库 sys_permission 共 18 条（id 9001–9018）；handover:read 在 9018（历史残留，重跑 seed_test_rbac.py 会被清理），两个 memory:candidate:* 不存在。
故 qyqy 的 tools/grant_customer_service_phase2_permissions.py 按 9036/9037/9038 原样即可，无号段冲突。

## 合并内容将 `ZSY_develop` 的客服 Agent 能力接入 `qyqy_develop`，基线为 `qyqy_develop` 最新提交 `c4a73b7`。 ### 1. 提交构成 - `e85989b`：把 `c4a73b7`（账号密码登录 + RBAC 只读查询等 7 个提交）合入 `ZSY_develop`，**无冲突**（增量合并，复用此前已解决的语义冲突）。 - `9aaacc2`：按 `AGENTS.md` 与底座文档逐条核对后，移除撞到底座规则的内容。 ### 2. 底座合规清理（`9aaacc2`，9 文件 +189/−483） - 删除 `app/service/knowledge_tool_service.py`、`app/infrastructure/milvus_knowledge_adapter.py`：后者**硬编码 Milvus 字段名**，违反 `AGENTS.md` §E；两者均为**生产死代码**。生产检索实际走 `knowledge_search_tool -> KnowledgeSearchService -> app/core/knowledge_schema.py` 的运行时字段探测，无任何硬编码字段名。 - `app/service/knowledge_retrieval_service.py` 整文件回退为底座版本，移除 legacy 双构造与重复检索实现。 - `docs/05-接口文档.md`：新增的「客服画像候选」由误占的 `§8.2` 改登记为 `§8.5`，恢复 `### 8.2 解析知识引用`；`§8.1–§8.4` 原编号一字未动。 - `app/model/profile.py`：`current_customer_id` 改为普通可空列映射。原来按「生成列」写成 `Computed(...)`，会让 SQLAlchemy 从 INSERT 中排除该列，与真实 schema 不符。 ### 3. 需评审确认的底座扩展详见 `docs/客服Agent接入底座扩展说明_v1.md`（A 纯新增 / B 默认行为不变的扩展 / C 需确认 / D 已移除 / E 明确未改动 / F 环境约束）： - **C1 访客身份**：`app/core/security.py`（`visitor: true` 声明分支）+ `app/api/dependencies/auth.py`（访客跳过 `IdentityService.resolve`）。 - **C2 客服 Agent 角色与行为**：`app/service/agent/implementations/customer_service.py`。 - **C3 画像快照 ORM 去重与 `current_customer_id` 映射**：`app/model/profile.py`、`app/model/risk_questionnaire.py`。 - **C4 Milvus 双地址**：`MILVUS_LOCAL_URI` 在团队/生产环境须留空。 ### 4. 验证结果 - `pytest tests/unit tests/contract -q -p no:cacheprovider` -> **1275 passed, 2 skipped, 0 failed** - `ruff check app tests tools alembic` -> All checks passed - `mypy app` -> 244 个源文件无问题 ### 5. 遗留事项 - **待确认**：访客令牌 `sub` 是否纯数字（**是**，且走底座原有校验、未放宽）；`recalls_customer_memory` 默认值（**True**，仅 `customer_service` 显式关闭）。 - `docs/00` 第 783 行把 `profile_snapshots.current_customer_id` 描述为「生成列」，与 `docs/02`/`alembic` 基线 DDL 及真实库不一致，请底座侧决定以哪侧为准。 - 本 PR **不包含**对 `docs/00`、`docs/02`、`alembic/` 的任何改动。 --- ### 6. 评审后修订（`f68b052`）按 qyqy 在评审中提出的两项要求处理： 1. **`docs/05` §19 端点编号去重**：客服画像候选的两个端点由 `A034`/`A035` 改为 **`A039`/`A040`**（原编号与 qyqy 侧登录 / RBAC 只读接口 `A034–A038` 重复；docs 守卫脚本只校验文档文件名编号、不校验 §19 端点编号，故会静默遗留）。改后全表 **55 个端点编号全唯一**。 2. **`milvus-lite` 降为可选依赖**：由 `[project] dependencies` 移到 `[project.optional-dependencies] dev`；`requirements.txt` 不再作为生效依赖，仅留说明注释。修订后复验（`origin/qyqy_develop` 已推进至 `ade5e0c`）： - `git merge-tree --write-tree f68b052 ade5e0c` → **无冲突**（`c4a73b7` 是 `ade5e0c` 的祖先，属增量推进） - `pytest tests/unit tests/contract -q -p no:cacheprovider` → **1275 passed, 2 skipped, 0 failed** - `ruff check app tests tools alembic` → All checks passed；`mypy app` → 244 个源文件无问题 ### 7. 环境数据对齐（`sys_permission`） - 我方库 `sys_permission` 共 18 条（id 9001–9018）；`handover:read` 在 **9018**（历史残留，重跑 `seed_test_rbac.py` 会被清理），两个 `memory:candidate:*` **不存在**。 - 故 qyqy 的 `tools/grant_customer_service_phase2_permissions.py` 按 **9036/9037/9038** 原样即可，无号段冲突。

Zsy_0626 added 30 commits 2026-09-12 11:35:42 +08:00

chore: ignore local worktrees c6be99078e

feat: add limited visitor tokens ad7172367a

docs: add safe foundation migration design 5ebed374c4

docs: add foundation migration implementation plan d0793355fc

test: record pre-migration workspace evidence a789872c79

merge: preserve existing business features on new foundation 8e36a9941d

feat: preserve isolated visitor agent runtime ba22a2220f

feat: add governed public knowledge retrieval 511a8ca18f

feat: add governed customer service agent e9b3d272f0

feat: add knowledge import preflight 24f75636a0

feat: add guarded knowledge publication tool bc2f521c2e

feat: configure local customer service knowledge runtime c76b763101

docs: add phase one integration gate a229ec276e

feat: integrate customer service agent into ZSY develop 9220b7b47c

# Conflicts:
#	app/core/config.py
#	app/main.py
#	app/service/agent/bootstrap.py

fix: persist visitor handover tickets anonymously 0059701509

feat: complete customer service safety and handover flow ef098e6a4b

feat: add customer profile candidate flow 3a21afa847

feat: add profile candidate review workflow a769130658

feat: generate approved profile snapshots 27174b9ce2

test: fix mysql profile snapshot cleanup 1eb04f28b1

docs: define profile projection protocol 2de1735673

feat: include memory sources in profile sync events 5777f0f86e

feat: add neo4j profile projection adapter f167390a8a

feat: add memory sync outbox worker 6c605ec3c1

feat: wire neo4j projection into worker 5e848f5690

feat: target memory sync event replay 50a611274a

feat: add milvus profile projection cbcf7c7444

merge: integrate ZSY customer service and profile capabilities ef701c844c

merge: integrate latest qyqy_develop (auth login + RBAC read) into ZSY branch e85989b344

Incremental merge on top of ef701c8, which already integrated the earlier qyqy base bbf623a. qyqy_develop only added commits on top of bbf623a, so this merge is conflict-free. Incoming: account/password login (POST /api/v1/auth/tokens), RBAC read-only query API, rate limit dependency, login test console and user management tools. Additive changes in app/main.py, requirements.txt and pyproject.toml from both sides are all preserved. ZSY side capabilities (visitor tokens, customer service agent, knowledge retrieval, profile projection) are unchanged.

chore: 清理违反底座规则的死代码并修正接口文档编号 9aaacc242f

- 删除生产死代码 app/service/knowledge_tool_service.py 与
  app/infrastructure/milvus_knowledge_adapter.py：后者硬编码 Milvus 字段名，
  违反 AGENTS.md §E，且仅被前者引用；生产检索链路实际走
  knowledge_search_tool -> KnowledgeSearchService -> knowledge_schema 运行时探测。
- 删除上述两模块的单测，以及依赖 legacy 位置参数构造的
  tests/unit/service/test_knowledge_retrieval.py。
- app/service/knowledge_retrieval_service.py 整文件回退底座版本，
  移除 legacy 双构造与重复检索实现。
- docs/05-接口文档.md：客服画像候选改登记为 §8.5，恢复 §8.2 解析知识引用；
  既有 §8.1-§8.4 编号全部保持，修复此前出现两个 8.3 的问题。
- app/model/profile.py：current_customer_id 改为普通可空列映射，与
  alembic/baseline_generated.sql 及真实库一致；原 Computed 声明会让 ORM 把该列
  从 INSERT 中排除，与「必须显式写入」的实际 schema 不符。
- 新增 docs/客服Agent接入底座扩展说明_v1.md，供集成分支评审逐项确认。

验证：pytest tests/unit tests/contract -> 1275 passed, 2 skipped, 0 failed；
ruff check app tests tools alembic 通过；mypy app 通过（244 个源文件）。

Zsy_0626 referenced this issue from a commit

2026-09-12 11:53:57 +08:00

fix: 端点编号去重与 milvus-lite 降为可选依赖

Zsy_0626 added 1 commit 2026-09-12 11:53:57 +08:00

fix: 端点编号去重与 milvus-lite 降为可选依赖 f68b052a69

按 qyqy 在 PR #7 评审中的要求处理两项：

- docs/05-接口文档.md §19：客服画像候选的两个端点由 A034/A035 改为 A039/A040。
  原编号与 qyqy 侧登录 / RBAC 只读接口（A034-A038）重复；docs 守卫脚本只校验
  文档文件名编号、不校验 §19 端点编号，因此该重复会静默遗留。改后全表 55 个
  端点编号唯一。
- pyproject.toml / requirements.txt：milvus-lite 由主 dependencies 挪到
  [project.optional-dependencies] dev；requirements.txt 只保留说明性注释，
  不再作为生效依赖。理由：它仅用于本地开发（Docker Milvus 未运行时的本地
  持久化向量库），进主依赖会让生产环境多背一个包。

验证：pytest tests/unit tests/contract -> 1275 passed, 2 skipped, 0 failed；
ruff check app tests tools alembic 通过；mypy app 通过（244 个源文件）。

lzf_0626 referenced this issue from a commit

2026-09-12 12:10:07 +08:00

merge: 合并 ZSY 的客服 Agent 接入（访客身份、画像候选、转人工工单）—— PR #7

lzf_0626 referenced this issue from a commit

2026-09-12 12:10:07 +08:00

docs: 记录 PR #7 合并门禁结果、两处顺手修正与权限号段冲突的来龙去脉

Zsy_0626 commented

2026-09-12 12:44:25 +08:00

合并完成记录

本次内容已由 qyqy 通过本地合并提交 4413644 落地到 qyqy_develop（未走 Gitea 的 PR 合并按钮），因此 PR diff 现已为 0。为保持看板整洁，此处按「已合并」关闭并留下合并坐标。

合并坐标

合并提交：4413644（merge: 合并 ZSY 的客服 Agent 接入（访客身份、画像候选、转人工工单）—— PR #7）
被合并的分支头：f68b052（origin/ZSY_develop）
目标分支：qyqy_develop，合并后继续推进到 4d8edb4

合并后在 qyqy_develop(4d8edb4) 上的复核结果

复核项	结果
两个违反底座规则的死模块	保持删除（`knowledge_tool_service.py`、`milvus_knowledge_adapter.py`）
`docs/05` §19 端点编号	62 个 / 62 唯一 / 重复 0，`A039`/`A040` 就位
`milvus-lite`	不在主 `dependencies`；在 `[project.optional-dependencies] dev`；`requirements.txt` 非生效依赖
本次新增模块与文档	均已在分支上

qyqy 在合并后顺手修正的两项（特此记录，谢谢）

tests/unit/core/test_security.py 两处密钥路径漂移（漏 dev/）——本次改动带入的回归，已由 qyqy 在 2bb056e 修正。
docs/05 §19 端点编号计数更正：正确口径是 62（前缀 A40 / C7 / K4 / M4 / O3 / R4），此前描述的 55 系扫描正则漏掉 O、R 两个号段所致；重复为 0 的结论不受影响。

遗留待办（我方）

补一条走 HTTP + RBAC 的用例，覆盖「权限码在库中缺失导致 403」这类环境数据问题（服务层用例天然测不出）。
回复 qyqy 提出的只读冒烟脚本方案。

## 合并完成记录本次内容已由 qyqy 通过**本地合并提交** `4413644` 落地到 `qyqy_develop`（未走 Gitea 的 PR 合并按钮），因此 PR diff 现已为 0。为保持看板整洁，此处按「已合并」关闭并留下合并坐标。 **合并坐标** - 合并提交：`4413644`（`merge: 合并 ZSY 的客服 Agent 接入（访客身份、画像候选、转人工工单）—— PR #7`） - 被合并的分支头：`f68b052`（`origin/ZSY_develop`） - 目标分支：`qyqy_develop`，合并后继续推进到 `4d8edb4` **合并后在 `qyqy_develop`(`4d8edb4`) 上的复核结果** | 复核项 | 结果 | |---|---| | 两个违反底座规则的死模块 | 保持删除（`knowledge_tool_service.py`、`milvus_knowledge_adapter.py`） | | `docs/05` §19 端点编号 | **62 个 / 62 唯一 / 重复 0**，`A039`/`A040` 就位 | | `milvus-lite` | 不在主 `dependencies`；在 `[project.optional-dependencies] dev`；`requirements.txt` 非生效依赖 | | 本次新增模块与文档 | 均已在分支上 | **qyqy 在合并后顺手修正的两项（特此记录，谢谢）** 1. `tests/unit/core/test_security.py` 两处密钥路径漂移（漏 `dev/`）——本次改动带入的回归，已由 qyqy 在 `2bb056e` 修正。 2. `docs/05` §19 端点编号计数更正：正确口径是 **62**（前缀 `A`40 / `C`7 / `K`4 / `M`4 / `O`3 / `R`4），此前描述的 55 系扫描正则漏掉 `O`、`R` 两个号段所致；重复为 0 的结论不受影响。 **遗留待办（我方）** - 补一条走 HTTP + RBAC 的用例，覆盖「权限码在库中缺失导致 403」这类环境数据问题（服务层用例天然测不出）。 - 回复 qyqy 提出的只读冒烟脚本方案。

Zsy_0626 closed this pull request

2026-09-12 12:44:25 +08:00

Zsy_0626 referenced this pull request

2026-09-12 12:58:08 +08:00

test: 补 §19 端点编号守卫与端点权限判定的 HTTP 层用例 #8

wangjianlong_0626 referenced this issue from a commit

2026-09-12 13:15:13 +08:00

merge: 合并主干 qyqy_develop（PR #7 之后）并对齐两套投影实现

wangjianlong_0626 referenced this issue from a commit

2026-09-12 13:23:45 +08:00

docs: 标明 neo4j_profile_projection 当前未被生产装配（方案 A 取舍）及启用前提

wangjianlong_0626 referenced this pull request