feat: 统一 Public v1 Agent 会话与 Knowledge 查询接口

[xerrors]

变更说明

原有 Agent 调用由产品路由、Invocation 路由和前端各自拼接 Request/Run 生命周期；外部知识库查询也缺少版本化入口和可限定的凭据。本 PR 将 Agent 对话与只读 Knowledge 查询收敛到 Public v1，并让前端及 yuxi-cli 使用对应新接口。

• 任务类型：feature / architecture
• 目标：提供按 Request 读取结果、Public Thread/Session/Turn 与 SSE、APP/终端用户隔离、受限 API Key，以及六个共享 Knowledge 查询工具；前端会话创建、追加、取消和恢复改用 Public API，默认追加模式保持 follow_up。
• 非目标：迁移知识库管理/上传、开放沙盒下载工具、实现官方 tool_result 或完整 OpenAI Agents API、立即移除旧 Invocation/External 路由。
• substantial / trivial 判断：跨鉴权、持久化、队列、SSE、前端和 CLI，为 substantial。

工程主张与 Owner

• Request 先持久化并按既有 FIFO 派发；结果只读取其明确绑定的 Run。Owner：agent_request_service.py、Request/Run repositories；commit point 为数据库事务提交；通过结果 API 与持久记录观察。
• Public Session/Turn 对同一轮输入、steer、审批恢复及多个 Run 保持明确归属；状态从 Request/Run 投影，SSE 可在断流后按持久结果恢复。Owner：services/agents/public_api.py、session_input.py、session_events.py、repositories/agents 和业务 Schema；commit point 为输入事务提交；通过 Public API、SSE 和 PostgreSQL 观察。
• agents / knowledge Key 只能访问各自允许的 Public 路径；APP Key 的 End-User-Id 解析为独立、不可登录的用户，只能使用 Public Agent API，其资源访问在后端隔离。Owner：认证依赖、auth_middleware.py、User/Agent repositories 与数据库唯一约束；通过 HTTP 403/404 和持久 UID 观察。Knowledge 不额外解释 End-User-Id。
• Knowledge external 查询和六个只读工具由 Public v1 暴露，Agent toolkit 与 HTTP 共用 services/knowledge/tools.py 的查询语义；JWT、full Key 和 knowledge Key 按其权限可调用。Owner：public_v1/knowledge.py、Knowledge service、repository 可见性查询；通过 HTTP 响应和知识库数据观察。
• 数据升级以当前 main 的 business Schema v9 为基线，只新增 v10；Owner：models_business.py、storage/postgres/manager.py、storage_migration.py；通过 PostgreSQL 升级后结构和旧数据回读观察。
• 决策记录：Agent 请求结果、Agents Public API、Session/Turn 生命周期、Knowledge Public v1。

验证情况

Public Agent 的作用域、请求归属与 Schema 升级

• 失败面：产品 metadata 伪造 APP、首条输入漏写归属、跨 APP/用户读取、Steer 并发错绑 Turn、v9 旧数据误获授权。
• 语义 Owner：Conversation.app_id 与 v9→v10 migration、Public Agent service、Request/Run repositories 和鉴权依赖。
• 直接证据 / 命令：docker compose exec -T api uv run --no-sync --group test pytest test/integration/api/test_public_agents_key_boundary.py test/integration/services/test_agent_request_queue_concurrency.py test/integration/services/test_schema_migration_version.py -q：29 passed；test_public_agents_api.py 等相关 unit：39 passed。独立 PostgreSQL 迁移用例回读旧 metadata 仍在、专用 app_id 列为 NULL。
• 负向案例：产品 JWT 提交 metadata.app_id 返回 400；历史双标记产品线程对 APP Key 返回 404；跨 APP/用户 404；并发 Steer 的 Turn 归属和同键不同意图冲突。
• 结果：Passed。

真实 API、worker、FIFO 与 SSE

• 失败面：Public /threads 与兼容 /sessions 带输入创建的 APP 归属分叉、Run/Request 结果错绑、队列流错误交接。
• 语义 Owner：agent_request_service.py、Public Session/Turn/SSE service、持久化 Request/Run 和 worker。
• 直接证据 / 命令：启动确定性 replay 后，test_public_agents_key_request_and_run_keep_source_and_result 1 passed；参数化 test_public_agents_queued_sse_keeps_public_run_url 2 passed。真实 HTTP→worker→PostgreSQL 回读两种创建入口的 conversations.app_id、同一 Request/Run 结果及 SSE URL。
• 负向案例：同键不同输入 409、跨 APP 404、排队期间只能观察当前 Public Run URL；完整 E2E 文件未全量执行。
• 结果：Passed（上述 3 项）。

Knowledge Public 查询与工具

• 失败面：knowledge Key 扩权、跨用户知识库可见、无效查询静默成功、Agent 与外部工具语义分叉。
• 语义 Owner：public_v1/knowledge.py、services/knowledge/tools.py、认证中间件与 Knowledge 可见性查询。
• 直接证据 / 命令：docker compose exec -T api uv run --no-sync --group test pytest test/integration/api/test_knowledge_external_router.py test/integration/api/test_public_knowledge_key_boundary.py test/integration/api/test_public_knowledge_tools.py -q：18 passed、1 setup error；该错误是本地 MinIO 数据盘触发 XMinioStorageFull，测试没有进入断言。此前同组 19 项曾通过；最终版本不能据此记为全组通过。
• 负向案例：knowledge Key 访问下载/管理/Agent API 被拒、跨用户知识库不可见、无效正则返回 400。
• 结果：Inspected（本次 18 项通过；1 项环境阻断）。

CLI、前端与文档契约

• 失败面：旧 external/Invocation 路径残留、Request SSE 断线后错误恢复、前端新增权限选项失效。
• 语义 Owner：packages/yuxi-cli、web/src/apis、会话 composables 与对应文档。
• 直接证据 / 命令：CLI 定向测试 45 passed；Web 容器 lint、398 项 unit 和 build 通过；本次 cd docs && pnpm run build 通过。真实浏览器网络流程未复核。
• 负向案例：断流回读 Request 结果、external 请求路径/方法、API Key 权限选项和线程队列交接有对应 unit。
• 结果：Inspected（自动化检查通过；浏览器为 Not run）。

工程契约与全量后端单测

• 失败面：决策记录、路由、代码格式和工程约束漂移；无关单测回归。
• 语义 Owner：tracked 决策记录、工程契约检查器与后端测试。
• 直接证据 / 命令：python3 scripts/verify_engineering_contracts.py 通过；python3 -m unittest scripts.test_verify_engineering_contracts 62 passed；Ruff package check/import/format 与 git diff --check 通过。docker compose exec -T -e SANDBOX_RUNTIME_PROFILE=core api uv run --no-sync --group test pytest test/unit -m 'not slow' -q 在 1955 passed、58 skipped 后停滞，213 秒时人工中断，无断言失败；之前最终补丁前曾全量通过 2455 passed、58 skipped。
• 负向案例：工程契约检查器自身测试与各变更对应定向负向用例。
• 结果：Inspected（最终版本全量未完成）。

简化 / 删除验收

不涉及。旧 Invocation 与 external 路由仍保留弃用窗口；本 PR 不宣称旧能力已删除。

独立语义 Review

全新、未继承开发上下文的 Reviewer 审查了完整 89 文件 diff、需求、测试和规范，发现并推动修复了 Steer 测试前置条件、APP metadata 伪造授权边界及首条输入漏写 APP 归属；最终复核无剩余代码阻断项。Review 不替代运行证据。

未验证范围与风险

• 最终版本的全量 unit 在 1955 passed、58 skipped 后因停滞人工中断；仓库要求的未加 --no-sync 命令在当前挂载环境因 yuxi.egg-info 时间戳无法开始测试。定向 unit 和真实链路已通过。
• 本地 Knowledge 测试一项被 MinIO 数据盘最低剩余空间限制阻断。未清理其他数据；完整 19 项需在有充足存储的环境或 CI 复核。
• 未运行完整 deterministic E2E 文件、真实 provider、真实浏览器和并发连接池压测。SSE/取消/恢复的其他情景及前端交互仍需 CI 和人工验收。
• 本地开发数据库曾从本分支过渡版本调整到 main v9，再运行正式 v9→v10 迁移；生产迁移路径只有 v9→v10，隔离 PostgreSQL 升级测试已覆盖。

事故反馈

不涉及已上线高影响逃逸事故。

界面变更

API Key 管理选项与 Agent 对话网络交互已调整；无布局设计变更。本次未生成真实浏览器截图或录屏，需在 Review 阶段补充交互验证。

关联事项

无。

补充说明

存量 API Key 和省略权限的程序化创建仍为 full；Web 新建 Key 默认 agents。Knowledge 的 JWT 调用可用；knowledge Key 仅放行明确列出的只读路径。旧 Invocation 与 external 路由暂保留弃用标记。download_kb_file 仍只在 Agent 会话沙盒内可用。