[Proposal] 团队记忆产品化改进：统一 API/Panel、生命周期、动态模型配置与文档体系

[psiQAQ]

提案摘要

TencentDB Agent Memory 已经具备 Team、Agent、Task、资产、共享记忆和多种 Agent 客户端接入的基础能力。实际从空环境开始搭建并按团队方式使用时，当前阻力主要不在某一个 API，而在于多个产品层面没有形成完整闭环：

• Core API、Panel 代理、页面入口、角色权限和文档没有共同描述同一套能力；
• system admin、Team owner/admin、普通成员和资源 owner 的权责不够清晰；
• 人员离组、账号删除、资源交接、归档、恢复和永久清理缺少统一流程；
• 模型地址、模型名和供应商凭证已有后端配置基础，但缺少安全、可观察、无需重启整套部署的 Panel 操作面；
• 安装、Panel 使用、Agent 接入、API/命令和运维内容混在一起，用户仍需依赖 curl 或配置文件补齐主流程。

本提案希望先就产品边界和优先级达成共识，再把可以实施的内容拆成独立 Issue 和 PR。它不是要求一次合入一个大型改动，也不把下述建议描述为已经完成的上游能力。

1. 团队部署和使用过程中遇到的问题

以“完成部署后，仅通过 Panel 建立一个可工作的团队记忆空间”为目标，理想流程应当是：

system admin 初始化实例和用户 → Team owner 建立团队并邀请成员 → 成员创建 Agent/Task 和资产 → 配置客户端 → 产生并共享记忆 → 完成人员交接、归档和审计

当前流程中常见的中断点包括：

1. 后端已有 API，但 Panel 没有对应入口，管理员必须回到 curl 或自行编写调用。
2. 页面按一种“admin”身份显示操作，但 Core 实际按另一种实例级或 Team 级权限判断。
3. 创建流程相对完整，离组、交接、恢复和安全删除流程不足。
4. 调整模型上游时，使用者难以判断应该改 Panel、Core 还是 Proxy 配置，以及何时真正生效。
5. 安装指南继续承担产品教程、Agent 接入、API 限制、分析和运维说明，难以按身份阅读。

这并不意味着现有 API 没有价值，而是建议把“API 存在”提升为“目标用户可以安全地完成整个任务”。

2. 建立统一的 API–Panel 产品契约

截至本讨论草稿核对的公开分支，Core 已提供用户、User Key、Team、Agent、Task、资产、ACL、Task–Agent 关联和实例模型上游等多类 API；Panel 当前主要提供工作台、Wiki、Code、Skills、Chat Memory、Analytics、成员、Agent、API Key 和 Guide 页面。

部分代表性差距如下：

场景	已有基础	仍需补齐的产品闭环
实例用户管理	Core 有用户创建、列表和删除 API	独立的 system admin 用户管理页、账号状态、依赖预检和 Key 治理入口
Team 成员管理	已有成员添加、移除和列表能力	角色变更、owner 交接、离组阻断原因和页面权限一致性
Task–Agent 关系	Core 有 link、unlink 和 list API	Task 创建/详情页的 Agent 选择、解除关联和关系说明
Agent 生命周期	已有 archive/delete 等接口基础	归档、恢复、永久删除的统一术语、影响预览和入口
实例模型上游	Core 有 set/get/list/reset API	system admin 配置页、连接测试、发布状态、即时生效和回滚

建议维护一份机器可读的 capability inventory。每项管理能力至少标注：

• Core route 和 schema；
• Core 授权角色；
• Panel proxy 是否暴露；
• Panel 页面和入口；
• 状态：Supported、API only、Planned 或 Not exposed；
• 对应文档和验收测试。

CI 可以比较 Core routes/schema、Panel allowlist/OpenAPI 和 capability inventory。这样新增 API 时，即使暂时不做 UI，也能明确公开其产品状态，而不会让“接口已经存在”被误解为“用户流程已经完成”。

公开代码参考：

• Core V3 metadata schemas
• Panel routes

3. 明确人员、Key 和资产生命周期的权责

建议把账号类型、Team 角色和资源 ownership 作为三个独立维度：

身份	应负责	不应默认获得
system admin	实例用户、账号级 User Key、实例模型路由、完整性和平台设置	任意 Team 的日常业务管理权、成员私有资产读取权
Team owner	Team 信息、owner 交接、admin 任命、Team 解散	创建或删除实例账号、管理其他 Team
Team admin	邀请已有账号、成员角色和 Team 日常治理	任意账号 Key、其他 owner 的私有资源处置权
普通成员	本人 Key、Agent、Task、资产、主动共享和本人离组	Team 管理、他人 Key、他人 private 资产
资源 owner	资产共享、绑定、转移、归档和清理	额外的实例或 Team 管理权限

凭证也需要在页面和文档中明确分开：

凭证	用途	推荐管理位置
bootstrap system-admin Key	首次初始化和应急恢复	部署/Secret 管理，不用于日常 Agent
Memory User Key	用户登录及 Agent 访问 Memory/Proxy	Panel 用户与 API Key 页面
模型供应商凭证	Proxy/Memory 调用模型供应商	system admin 模型配置或外部 Secret 系统
服务间凭证	Core、Proxy、Panel、Knowledge 之间的受信调用	部署/Secret 管理，不分发给最终用户

人员和资产退出流程建议统一为：

1. 预检账号在相关 Team 中的角色、owner 资源、归档资源和未完成关系。
2. 指定接收人，先处理 backing data，再提交 metadata ownership。
3. 对 Agent/Task/资产优先提供可恢复归档；永久清理必须单独命名并二次确认。
4. 只有 ownership 阻断清零后才移除 membership、停用账号或解散 Team。
5. 跨服务步骤记录幂等状态，失败后可以安全重试或补偿。
6. 最后吊销或轮换 User Key，并运行精确完整性检查。

Panel 应展示操作影响范围、阻断原因、当前步骤和恢复入口，而不是让用户通过数据库或日志猜测结果。

4. 在 Panel 动态管理模型与上游网关

这项改进已有明确的后端基础。公开代码中的 instance-upstream/set|get|list|reset 支持按客户端来源和 conversation|extraction 类型配置 official|custom_unified|custom_passthrough、上游地址、模型 ID 和凭证；Proxy 会读取这些配置，并采用 5 分钟缓存和 stale-if-error。

当前建议补齐的是 system admin 的“模型与路由”页面，而不是把所有部署配置都变成网页表单。

配置类别	建议位置	示例
模型上游网关	Panel 动态管理	API 兼容地址、模型 ID/别名、conversation/extraction、默认规则和客户端覆盖
模型供应商凭证	Panel 或外部 Secret 系统	平台统一供应商 Key、Secret reference、轮换状态
Memory User Key	用户/API Key 页面	Agent 连接 Memory/Proxy 的业务身份
部署接入网关	安装/运维配置	监听端口、TLS、反向代理、网络暴露和防火墙
服务基础设施	安装/运维配置	数据库、存储、服务间凭证、bootstrap Key 和持久化路径

推荐操作流程：

1. 新建草稿，选择用途、客户端来源、凭证模式、上游地址和模型。
2. 服务端完成 schema、URL/协议和权限校验。
3. 执行受限的连接测试，只返回连通性、鉴权、模型可用性和延迟摘要。
4. 预览最终匹配规则，确认默认配置和客户端覆盖关系。
5. 发布新的配置 revision，并定向刷新相关 Proxy 缓存。
6. 新请求使用新版本，在途请求不被打断；失败继续使用上一有效版本。
7. 从审计记录回滚或轮换供应商凭证。

建议的安全边界：

• 供应商凭证写入后不可回显，读取接口和浏览器状态只返回掩码；
• 使用应用层密文或 Secret reference，Secret 不进入日志、审计正文和导出文件；
• 连接测试校验协议、目标地址、重定向和 DNS 变化，不能成为 SSRF 代理；
• 发布使用乐观版本控制，记录 actor、作用范围、前后 revision 和结果，但不记录 Secret；
• custom_passthrough 只管理策略，不由 Panel 保存客户端实际持有的供应商凭证。

建议验收标准：修改上游地址、模型名或供应商凭证后，不需要重启 Core、Proxy、Panel 或整套部署；配置在明确 SLA 内对新请求生效；测试或发布失败时保持上一有效版本；服务重启后仍能恢复已发布配置。

公开代码参考：

• Instance upstream routes
• Instance upstream schema
• Proxy instance-upstream cache

5. 拆分安装、使用、Agent 接入和 API 手册

当前 INSTALL_CN.md 同时包含安装、Panel 登录和建号、Team/Agent/Task 创建、Claude Code 接入、首次会话、记忆观察、各类 Agent Proxy 接入、/analyse、请求头限制、ClickHouse 可观测性及停止/清理等内容。

建议调整为：

文档	主要读者	核心内容
安装与升级手册	部署/运维	前置条件、安装、Secret、健康检查、升级、回滚和卸载
Panel 管理员手册	system admin	首次登录、账号、Key、模型路由、完整性、审计和运维入口
Team 管理手册	Team owner/admin	建 Team、邀请已有用户、角色、Agent/Task、共享和离职交接
成员使用手册	member/reviewer	本人 Key、Agent/Task、资产、共享、归档和离组
Agent 接入手册	客户端维护者	各客户端配置、endpoint、User Key 占位符、模型映射和会话行为
API 与命令手册	集成开发者	鉴权、schema、错误码、幂等、分页、curl/SDK 示例和限制
运维与故障手册	SRE/管理员	日志、监控、备份恢复、迁移、完整性和安全响应
场景手册	评估者和新团队	从 0 到 1、共享协作、离职交接和故障恢复的完整案例

Panel 使用教程应以身份和页面全流程为主。Agent 命令、curl 和 SDK 示例可以作为链接，但不应替代普通用户在 Panel 上的操作说明。

至少建议提供以下角色化教程：

• system admin：登录、建用户、发放 User Key、配置模型路由、查看健康和审计；
• Team owner/admin：建 Team、邀请成员、设置角色、关联 Agent/Task、治理共享和交接；
• 普通成员：创建 Agent、接入客户端、产生记忆、共享/撤销、转移和归档资源；
• 离职与故障场景：预检、交接、Key 轮换、失败恢复和完整性复核。

公开文档参考：INSTALL_CN.md

6. 建议优先级和验收标准

P0：安全、权限和首次使用闭环

• 对齐 system admin、Team 角色、资源 owner 与 Panel 可见操作；
• 建立 API–Panel capability inventory 和差异检查；
• 补齐人员离组、所有权交接、Team 解散、归档/恢复/永久清理；
• 让新实例从登录到首个 Agent 产生记忆的主流程不依赖手写管理 API；
• 明确各类 Key 的用途、持有人、轮换和泄露响应。

P1：高频治理和可维护性

• 交付 system admin 模型与路由配置中心；
• 补齐 Task–Agent 关联 UI；
• 增加审计、失败恢复和 Key 轮换工作流；
• 发布角色化 Panel 使用手册和真实团队场景；
• 公布客户端、存储后端和部署形态的验证矩阵。

建议共同采用以下完成标准：

1. 页面可见操作与 Core 授权一致，不出现主流程点击后固定 403。
2. 新用户只依赖公开安装手册完成部署和健康检查。
3. 各角色只通过 Panel 即可完成自己的主要产品流程。
4. 离组、删号、解散 Team 和归档均有预检、交接、恢复或永久清理路径。
5. 模型路由可安全发布、定向生效和回滚，不依赖重启整套部署。
6. API、Panel、权限矩阵、文档和验收测试随同一版本发布。

7. 希望维护者共同确认的开放问题

1. 项目是否认可“账号类型、Team 角色、资源 ownership”是三个独立授权维度？
2. 哪些 Core 管理 API 应承诺提供 Panel UI，哪些会长期保持 API only？
3. 人员离组、Team 解散和账号删除的正式 ownership 阻断规则是什么？
4. archive、restore、delete 和 purge 是否可以形成跨服务统一状态机和术语？
5. 模型上游配置是否适合采用 revision + 定向缓存刷新，而不是依赖部署重启或等待缓存自然过期？
6. 模型供应商凭证应由 Core 加密保存，还是只保存外部 Secret reference？
7. 安装、Panel 使用、Agent 接入、API 和运维文档分别由谁维护，如何进入版本验收？
8. 是否可以为上述 P0/P1 项指定 milestone、维护者和分批交付顺序？

8. 相关公开 Issue 和 PR

• #1237 — MemoryPanel Team 删除入口和 system_admin 管理范围
• #1250 — INSTALL_CN.md 的纯 Panel 初始化流程、用户管理和角色/API 权限
• #1259 — 调整 INSTALL_CN.md 的 Panel onboarding 说明

文档更新可以降低误解，但不能单独解决 API、授权和 Panel 行为问题。建议在本讨论确认产品方向后，为各功能域建立独立 Issue，并让对应 PR 同时包含权限说明、页面状态、测试证据、迁移/回滚说明和文档更新。

欢迎维护者和使用者补充：

• 哪些流程已经有推荐做法但文档入口不明显；
• 哪些能力有 API 但不计划提供 UI；
• 哪些生命周期规则需要兼容既有数据；
• 哪些真实团队场景应优先作为公开验收路径。