[atoncooper]

概述

本次提交包含三块工作：app-kg 分层重构 + 云盘文档知识点（KG 新来源）、交互式产物（图表/流程图）工具与前端渲染、以及若干可靠性/运维修复。

1. app-kg 分层重构（app-go/app-kg）

• 目录收敛为 internal/{infra,repo,service,transport}：infra 只做数据库初始化/连接配置，repo 只放 SQL/Cypher，service 承载业务规则，transport 做 proto↔service / HTTP 映射；config 为 YAML/env 唯一入口。
• 全部 Go 测试移入独立 tests/ 包（不在被测包混放），新增分层依赖方向守护与 Cypher/SQL 契约守护测试，无需真实 DB 即可跑。
• 删除旧的 db/ / graph/ / neo4jstore/ / server/ 包。

2. 云盘文档 → 知识点（新来源，与视频共用同一张知识图）

• proto（proto/kg/v1/kg.proto，21→24 RPC）：新增 LinkCloudDocAppearances / DeleteCloudDocAppearances / FetchCloudDocEvidence；Stats 增 cloud_docs / cloud_evidence。证据边指向复用云盘 L1 路由图的 (:CloudDoc {uid, upload_uuid})，uid 多租户隔离在 Cypher 内完成。
• app-cloud：新增 M2M 只读接口 GET /internal/cloud/kg/documents（分页枚举已解析文档）与 GET /internal/cloud/kg/document（读取正文，200k 字符截断），沿用 internal.api_key + uid 校验；新增黑盒 HTTP 契约测试。
• app-ts：kg-cloud-sources 仓储（http/memory 双实现）、自有 Mongo kg_docs 账本（upload_uuid + content_hash 幂等 skip）、startCloudBuild/runCloud/processCloudDoc 编排、/knowledge/kg/build 增 source 与 upload_uuids、kg_search 同时回捞视频与云盘证据；gRPC 消息键改为 camelCase（修正此前 snake_case 请求键被静默丢弃的问题）。

3. 交互式产物（plot / diagram）

• 工具：新增 render_plot / render_diagram，模型只输出声明式 spec（不写 HTML），服务端做表达式标识符、连线端点、spec 大小上限校验，非法输入返回可读错误供 ReAct 重试。
• 前端：InteractiveArtifact 用受信 canvas/SVG 组件渲染（无 iframe 沙箱、不执行任意 HTML），artifact 帧随消息历史持久化，新增 /lab/interactive 原型页。
• 聊天 UI：route 帧不再展示 agent 名称（协议保留用于清排队态）；运行中的整轮保持展开，工具步骤可见。

4. 可靠性 / 运维

• app-ts 聊天：整轮硬超时（agent.turnTimeoutMs，默认 30 分钟）+ 客户端断连 abort，保证 assistant 消息在断连/超时/异常下一定 finalize（此前断连会留下 pending 消息并占会话锁）。
• app-auth：B 站绑定状态 60s TTL 缓存 + 2.5s 硬超时兜底，账号页不再被 api.bilibili.com 抖动拖住；bind/unbind 即时失效缓存。
• app-note：宿主调试口 8008 → 8018（8008 被 app-cloud 端口池抢占），容器内仍 8008，APISIX 路由不变。
• 文档同步（app-kg / app-cloud / architecture / configuration / deployment / getting-started / api）。

验证

• app-ts：npx tsc --noEmit + npx vitest run（70 文件 / 717 测试通过，23 个 Mongo 条件跳过）
• app-go/app-kg：gofmt -l . + go vet ./... + go test ./... + go build（本地验证中，CI 为准）
• frontendv2：npx tsc --noEmit + npm run build（本地验证中，CI 为准）
• GitHub Actions：等待 CI 全绿后合并

风险 / 注意

• kg.proto 与 Go 生成产物同步提交（CI 无 protoc 依赖）；app-ts 侧依赖 camelCase 消息键。
• 云盘知识点依赖 app-cloud 的 M2M 文档接口与 app-ts Mongo kg_docs；未配置时按降级路径处理。
• app-note 宿主端口变更仅影响本地调试，容器/网关不变。