

> 摘要：在 TencentDB-Agent-Memory 中，当成员被移出团队或用户被删除时，其创建的 Agent 会变成 owner 悬空的「孤儿 Agent」，且任何角色都无法删除，最终导致前端 403、团队资源卡死。本文记录 issue #1321 的根因分析、修复方案和验证过程，并分享我们用于组织开源贡献的工作流。

关键词：TencentDB-Agent-Memory, Agent Memory, 开源贡献, 级联删除, 数据一致性

---

## 一、项目背景

TencentDB-Agent-Memory 是腾讯开源的 Agent 记忆层项目，提供 L0–L3 四层记忆、Memory Hub、知识库等能力，供大模型 Agent 在长期对话中保持上下文。它采用 Node/TypeScript 服务层 + SQLite/MongoDB 持久化的架构。

最近我围绕该项目参与了一次开源贡献挑战，选题是 [#1321 孤儿 Agent 级联删除](https://github.com/TencentCloud/TencentDB-Agent-Memory/issues/1321)。这个问题影响面比较典型：团队人员流动后，旧 Agent 既占资源又无法清理，属于「看着小、踩坑深」的类型。

## 二、问题现象

移出团队成员或删除用户后：

- 该用户创建的 Agent 的 `owner_user_id` 仍然指向已被删除的用户；
- Agent 删除接口原本只校验「是否为 owner」，没有考虑 admin / team admin 的兜底权限；
- 结果是：任何角色（包括系统管理员）都删不掉这些 Agent；
- 团队面板里残留可见的「孤儿 Agent」，访问时前端返回 403，相关 skill 也被卡死。

## 三、根因分析

issue 里把问题拆成三条互相咬合的缺陷链：

1. `removeTeamMemberForCaller` 只删除成员行，**没有级联清理**该成员的 Agent；
2. `deleteUsers` 清除了 keys、members、acl，却**漏了 `meta_agents`**；
3. `deleteAgentsForCaller` 直接调用 `assertCallerIsAgentOwner`，没有参考 `isSystemAdmin`；而 `assertCallerIsAgentOwnerOrTeamAdmin` 其实已经存在，只是没被用上。

简单说：删人时忘了删 Agent；删 Agent 时又只认 owner，不认管理员。

## 四、修复方案

基于 issue 给出的预期，我在 `代码厂/m3-orphan-agent-fix` 做了以下改动（核心 5 步）：

1. **人员删除前级联收集 Agent**：在 `removeTeamMemberForCaller` / `deleteUsersForCaller` 里，先收集目标用户的 Agent 列表，再执行硬删除（admin 校验已在前置流程建立）。
2. **放宽删除权限校验**：`deleteAgentsForCaller` / `archiveAgentForCaller` 改用 `assertCallerIsAgentOwnerOrTeamAdmin`；当 `isSystemAdmin` 为 true 时直接跳过 owner 校验。
3. **Panel 权限对齐**：`delete-cascade` 权限从 owner-only 放宽到 owner / team admin / system admin。
4. **团队删除时完整级联**：`deleteTeams`（sqlite + mongodb 同步实现）先收集该团队下所有 `agent_ids`，再调用 `deleteAgents()` 走完整级联，避免残留 `task_agents`、`fixed_assets`、`chat_memory`。
5. **补契约测试**：新增 `IMetadataStore` 级联删除契约测试，覆盖 sqlite / mongodb 两种存储形态。

额外考虑的**安全兜底**：与其直接硬删，未来可以更温和地先做 ownership transfer（把孤儿 Agent 转给 team admin），避免误删活跃资产。这次先按 issue 预期完成级联清理，transfer 作为后续优化点。

## 五、验证证据

本地与测试服务器都跑了一遍：

- **服务层**：`metadata-service.agent-access.test.ts` 8/8 通过；
- **SQLite 契约测试**：`sqlite-adapter.test.ts` 61/61 通过（58 个存量 + 3 个新增级联场景）；
- **MemoryCore 全量**：69 passed / 61 skipped（mongodb 无 URI 自动 skip）/ 0 failed；
- **类型检查**：改动生产代码无新增 TypeScript 错误；
- **诚实声明**：`memory-core/hub/proxy` 三件套完整部署联调、MongoDB 真实服务端持久化验证尚未覆盖，已在成果卡中标注为「未验证」。

## 六、我们的组织方式：四厂 + 多方向并行

这次贡献不是「看 issue 直接改代码」的线性流程。为了能在 90 分钟现场里同时推进多个方向，我们把工作区分成四厂：

- **规划厂**：放总控手册、经验复用指南、成果卡模板；
- **代码厂**：每个选题生成一个独立的方向文件夹（如 `pi-profile-fix`、`m3-orphan-agent-fix`）；
- **文章厂 / 分类**：放成果卡草稿、技术短文、00-总索引；
- **统一产出物**：每方向以 `成果展示卡.html` + `设计说明.md` + `参展贴.md` 交卷。

工作流上，选方向可以多选；复刻公开 PR / issue 根因是**可选**环节，没有现成经验就直接进入本地开发验证。所有成果在「向外审批」前都由人工确认。

![工作区整体架构与生产工作流.png](https://developer.qcloudimg.com/http-save/yehe-11827391/5817729acf32885ad22ee8ff8b5a73b0.png)

## 七、结语

1321 是一个典型的「删除语义不完整」问题：人员级联删除缺一环，权限校验又过严，结果导致资源悬空。修复它的核心不是加功能，而是把「谁该被删、谁能删、删的时候还要清什么」这三件事对齐。这次修复和验证给了我一个比较干净的闭环，也验证了「四厂 + 方向文件夹 + 可选复刻」这种工作流在短时间开源贡献里的可行性。

如果你也在做 Agent Memory 相关贡献，欢迎在 issue 下交流，或者一起聊聊 ownership transfer 这类更安全的清理策略。


摘要：在 TencentDB-Agent-Memory 中，当成员被移出团队或用户被删除时，其创建的 Agent 会变成 owner 悬空的「孤儿 Agent」，且任何角色都无法删除，最终导致前端 403、团队资源卡死。本文记录 issue #1321 的根因分析、修复方案和验证过程，并分享我们用于组织开源贡献的工作流。

TencentDB-Agent-Memory 开源贡献手记：#1321 孤儿 Agent 级联删除的修复与验证

数据库

后端

TencentDB-Agent-Memory修复issue#1321孤儿Agent级联删除问题，根因是删人时未级联清理Agent且删除接口仅校验owner权限。方案包括人员删除前级联收集Agent、放宽管理员权限校验、补齐契约测试，实现SQLite/MongoDB双存储完整清理，防止资源残留及前端403。

数据一致性

测试服务

TypeScript 

服务器

MongoDB

SQLite

Agent

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

TencentDB-Agent-Memory 开源贡献手记：#1321 孤儿 Agent 级联删除的修复与验证-腾讯云开发者社区-腾讯云

TencentDB-Agent-Memory 开源贡献手记：#1321 孤儿 Agent 级联删除的修复与验证

TencentDB-Agent-Memory 开源贡献手记：#1321 孤儿 Agent 级联删除的修复与验证

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐