TencentDB Agent Memory 的权限：README 4 种可见性，代码有 5 种

读一个带权限模型的项目，最容易踩的坑是：把 README 那张权限表当成完整枚举，照着它去设计自己的接入层，然后在代码里撞见一个表上没有的取值。

TencentDB Agent Memory 就有两处这样的落差。截至 2026-08-16 我们在快照 97f9465 上核对，README 的资产可见性表列了 4 个取值，源码类型定义里是 5 个；README 说团队内角色分两种，源码的 TeamRole 是 3 个。下面把两处的确切位置、代码里那两个”多出来的”取值各自挂在什么判定分支上、以及你怎么自己去仓库里翻到同一行，都摆出来。

先交代一个前提：这个仓库的默认分支是 feat/server_team，不是 main 也不是 master。 本文引用的所有文件路径都在这个分支上。仓库主模块 MemoryCore 的 package.json 版本是 2.0.0-beta.1，另外三个模块还停在 0.1.0，接口与枚举随版本变动，下面这些行号只对我们采集的这个快照负责。

第一处：可见性，文档 4 个，代码 5 个

README 中文版 README_CN.md:226 的小节标题是「一支 Agent 团队，共享经验，不共享隐私」，:228 那句话是「新 Chat Memory 和 Skill 默认私有。分享是一个明确动作，不是默认泄漏。」紧接着 :230-235 是一张四行的表：

可见性	语义（README 原文）
private	只有 Owner 可读，团队管理员也不例外
team	团队成员可读，Owner / Admin 负责管理
restricted	通过 User / Role / Agent ACL 精确授权
agent	用于同团队 Agent 的定向装配

而源码 MemoryCore/src/metadata/types.ts:25 的类型是这样写的：

export type AssetVisibility = "private" | "team" | "restricted" | "agent" | "task";

五个。对应的 Zod 校验在 MemoryCore/src/metadata/router/v3-meta-schemas.ts:12，同样是五值。多出来的那个是 task。

task 不是一个悬空的枚举值，它在权限判定里有自己的分支。MemoryCore/src/metadata/service/permission-checker.ts:102-107 的 case 写的是：action !== "read" && membership.role !== "admin" 就 DENY。换成人话是，非 admin 对 task 可见性的资产只放行读动作，写、分配、分享这些都会被这条挡掉。这条分支之后还有什么，我们这次没有逐行核到，不做断言。

顺带一提，CHANGELOG.md:82-83 对可见性的说法是「三级可见性：private / team / restricted……外加 agent 定向装配」——同样没有 task。所以这里其实是三处口径：README 表 4 个、CHANGELOG 4 个、类型定义与 Zod 5 个。我们只并列陈述这个差异，以实读的仓库状态为准，不去推断哪一处该改。

private 的语义，代码注释比 README 写得细

README 那格写的是「只有 Owner 可读，团队管理员也不例外」。permission-checker.ts:73-81 的注释把这件事的影响面摊开写了三条：list-accessible 不返回其他人的 private asset（对 admin 也生效）；permission-checker.check 对 admin 访问他人 private 也返回 DENY；「若管理员确实需要看，让 owner 主动切到 team 或通过 acl/grant 授权」。

这三条和 README 那一格不矛盾，是同一件事的展开。真正值得你在接入前看一眼的是第三条：代码给的口子是 owner 主动改可见性、或者走 ACL 授权，而不是给 admin 开后门。

一个容易被漏掉的连带：restricted 能读，但不能绑

README :233 说 restricted 是「通过 User / Role / Agent ACL 精确授权」，这讲的是读写权限。但同一个可见性值在绑定这条链路上是另一套判定。

permission-checker.ts:155-171 有个和 checkPermission 并列的函数 canBindAsset，它管的是「Fixed Binding」这条链路上的绑定合法性判定。:159-171 按可见性取值分支：

• team → 要求资产与 agent 同 team
• agent → 要求同 team
• private → 要求同 owner 且同 team
• task 与 restricted → 一律返回 false

也就是说，一个 restricted 的资产哪怕通过 ACL 拿到了读权限，走不到”固定绑定到某个 Agent”这一步。README 的可见性表不涉及绑定，这两处讲的是不同的动作，我们只把它们并列摆出来，不推断哪一个覆盖哪一个。

要顺着绑定这条线继续看，落点是 meta_agent_fixed_assets 表（MemoryCore/src/metadata/store/sqlite-adapter.ts:252-261），列有 agent_id / asset_id / asset_type / injection_mode（DEFAULT 'summary'）/ priority（DEFAULT 50），并带 UNIQUE(agent_id, asset_id)。对应的四条路由是 /v3/meta/agent-fixed-asset/set、/list、/list-with-detail、/summary-by-agents（MemoryCore/src/metadata/router/v3-meta-router.ts:264-273）。

第二处：角色，README 2 个，代码 3 个

README_CN.md:136 那句写的是：「Team 内角色 分为 Admin（团队管理员）和 Member（普通成员）」——两种。

源码 MemoryCore/src/metadata/types.ts:18：

export type TeamRole = "admin" | "member" | "reviewer";

三个，多出来的是 reviewer。同样的三值 Zod 枚举在 v3-meta-schemas.ts:16。

有意思的是判定那一侧。permission-checker.ts:37-38 硬编码了两档默认权限：

const ADMIN_ACTIONS: Permission[] = ["read", "write", "assign", "share"];
const MEMBER_ACTIONS: Permission[] = ["read"];

而 :117 处的取值写法是 membership.role === "admin" ? ADMIN_ACTIONS : MEMBER_ACTIONS。所以在默认权限这一层，判定只分 admin 与非 admin 两档——reviewer 落在非 admin 那一侧，拿到的默认动作集合和 member 相同。至于 reviewer 在别处是否另有分支，我们这次没有逐处核到，不做断言。

再往下还有一处值得记一笔。Permission 枚举一共 6 个（types.ts:37-43）：read / write / delete / assign / share / use。对照上面两档默认权限会发现，delete 与 use 不在任何一档的默认集合里——要拿到这两个动作，只能走显式 ACL。

ACL 这条路自己也有限制。主体类型是三类（types.ts:45）：AclSubjectType = "user" | "team_role" | "agent"；效果类型 AclEffect = "allow" | "deny" 看着是两个，但 :44 的注释写的是「一期仅 allow，deny 预留」，permission-checker.ts:127 的匹配代码也确实只认 acl.effect === "allow"。这属于典型的「枚举里出现 ≠ 功能已可用」，别照着枚举去设计一条依赖 deny 的规则。

同一份类型文件里还有第三处值得对一眼：资产状态

既然打算照着枚举做接入，AssetStatus 也顺手核一下。types.ts:26-32 一共 6 个取值：draft / candidate / approved / deprecated / archived / failed，CreateAssetInput.status?: AssetStatus 在 :408。列表侧还有一个过滤常量 FILTERED_STATUSES: AssetStatus[] = ["archived", "deprecated", "failed"]（metadata-service.ts:220）。

而创建资产的两处调用写的是别的值：metadata-service.ts:1301（chat_memory 资产）与 :1415（skill 资产）都传了 status: "active"，这个字面量不在上面那 6 个取值里。我们没有运行过类型检查、也没有构建过这个仓库，这里只记录读到的文本差异，不断言它会不会报错、更不推断哪一处该改。对接入方的实际影响只有一层：你若按 6 值枚举去做状态映射，得预先想好遇到枚举外的字符串怎么处理。

你自己怎么核这两处

不需要装任何东西，五步都是读文件：

1. 确认你手上的分支是 feat/server_team——这个仓库的默认分支就是它，克隆下来不切分支也是这个。
2. 打开 MemoryCore/src/metadata/types.ts，看第 18 行的 TeamRole 和第 25 行的 AssetVisibility，各数一遍字面量个数。
3. 打开 MemoryCore/src/metadata/router/v3-meta-schemas.ts，第 12 行和第 16 行是对应的 Zod 枚举，确认与类型定义一致（我们核到的是一致的）。
4. 打开 README_CN.md，跳到 :230-235 的可见性表和 :136 的角色描述，和上一步的枚举逐个对。
5. 打开 MemoryCore/src/metadata/service/permission-checker.ts，看 :102-107 的 task 分支、:37-38 的两档默认动作、:117 的三元判定、:155-171 的 canBindAsset。

这五步走完，你会看到差异落在哪几行，而不是只知道”文档和代码对不上”。

这件事对接入方意味着什么

只说一层，不往下延伸：如果你要在自己的系统里镜像一份可见性或角色枚举，别抄 README 那张表，去抄 types.ts 的类型定义与 v3-meta-schemas.ts 的 Zod 枚举。 README 的表是给人读的语义说明，Zod 那份才是接口实际校验的边界——请求里带一个不在 Zod 枚举里的 visibility，被挡下来的位置是校验层，不是文档。

另外记住可见性和角色是两条独立的轴，而且同一个可见性值在”能不能读”和”能不能绑到 Agent”这两个问题上走的是不同函数。restricted 就是这样一个例子。

最后提醒一句语境：这些取值管的是团队记忆资产的可见范围，而这个项目会采集并存储团队的对话、文档与代码。可见性枚举本身只是代码里的判定分支，它是什么值、拦在哪一步，和你的数据落到哪里、谁能拿到，是两个层面的问题——后者要按你自己的合规要求单独评估。

延伸阅读

• 从头读起：TencentDB Agent Memory 是什么：团队级 Agent 记忆中枢怎么读
• 本专题共 40 篇，完整分组目录见专题页
• TencentDB Agent Memory 的资产类型枚举：源码四值、契约三值
• TencentDB Agent Memory 的 config.ts：三处注释默认值与代码不符

---

本文依据 TencentDB Agent Memory 官方仓库（github.com/TencentCloud/TencentDB-Agent-Memory） feat/server_team 分支上的 README、INSTALL、CHANGELOG、ROADMAP 与四个模块的源码整理， 核对日 2026-08-16，对应仓库快照 97f9465。该仓库的默认分支即为 feat/server_team。 本文内容为仓库源码与文档口径，我们没有部署、也没有运行过该项目的任何一个模块， 因此不涉及运行效果、检索质量与性能的任何描述。 该项目主模块处于 beta 阶段、其余模块版本号仍为 0.1.0，参数与接口随版本变动，请以仓库最新内容为准。 该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。