奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

TencentDB Agent Memory 的接口条数：面板 55、SDK 54、OpenAPI 54

2026-08-16

翻 TencentCloud/TencentDB-Agent-Memory 这个仓库的时候，有一类数字最容易让人踩空：同一份接口清单，在代码里、在 SDK 里、在 OpenAPI 契约里，数出来的条数不一样。

这篇只讲一处：/v3/meta/* 这批 action 的条数。截至 2026-08-16、我们采集的快照 97f9465（分支 feat/server_team，这也是该仓库的默认分支）里，三个地方分别是 55、54、54。差出来的那一条能定位到具体是哪个 action。

先说清一件事：本文只陈述差异并标明位置，不推断哪一处「才是对的」，也不去猜为什么会这样。

三个数字各自出自哪里

一、MemoryPanel 侧：55

MemoryPanel/src/panel/api/meta-actions.ts 里有个 META_ACTIONS 数组，文件第 2 行的注释写的是「v3.2：55 条」，把数组里的字符串字面量数一遍，实数也是 55 条。注释与实数在这一处是对得上的。

同文件里还有另外两个量：META_LIST_ACTIONS（:7-22）13 条，NOT_IN_SCOPE_PREFIXES = ['agent-fixed-asset/']（:92）对应 4 条 action。所以最终对外放行的 ALLOWED_PANEL_ACTIONS（:98-100）是 51 条——55 减去 agent-fixed-asset/ 前缀那 4 条。这一层减法很关键，后面会用到。

二、SDK 侧：54

sdk/memory-core/python/tencentdb_agent_memory/v3/metadata_client.py 第 14 行写着「54 条（与 Panel Control META_ACTIONS 对齐）」，v3/__init__.py:7 是同样的措辞。按 _V3 前缀拼出来的路径去重统计，实数也是 54，另外还有 5 条 /v3/knowledge/*。

TypeScript 侧口径一致：sdk/memory-core/typescript/src/v3/metadata-client.ts:2 与 typescript/README_CN.md:220 写的也是 54。

三、OpenAPI 契约侧：55 条 path，其中 54 条 POST

MemoryPanel/docs/api/meta-api.openapi.yaml 这份文件 1,839 行，info.version 是 1.3.1（:18）。按缩进两格的路径行数，得到 55 条 path，但其中有 1 条是 GET /api/v1/meta/instances，剩下 54 条是 POST action。

所以标题里那个「55 / 54 / 54」不是三个孤立的数字，而是同一份清单在三层里的三个计数结果：代码数组 55，SDK 覆盖 54，契约里的 POST 条目 54。

差出来的那一条：user/create-with-key

把 Panel 的 55 条与 SDK 的 54 条做集合差，多出来的只有一条：user/create-with-key。反过来，SDK 那边没有 Panel 清单之外的多余条目。

这条 action 在仓库里的踪迹是这样的：

  • 定义在 MemoryPanel/src/panel/api/meta-actions.ts:28，是 META_ACTIONS 那 55 条里的一条；它不落在 agent-fixed-asset/ 前缀下，因此也在 ALLOWED_PANEL_ACTIONS 的 51 条里。
  • 前端有实际调用点：MemoryPanel/web/src/lib/api/users.ts:43-44 的 createWithKey，与同文件里的 create（:31）、delete（:51）并列；页面侧落在 MemoryPanel/web/src/pages/team/components/MemberSection.tsx:241。
  • 在 MemoryPanel/docs/api/meta-api.openapi.yaml 里 grep create-with-key，命中 0 次。
  • 在 Python SDK 的那 54 条里同样找不到它。

也就是说，这一条在 Panel 的白名单和前端调用链上都是存在的，而在 OpenAPI 契约与两侧 SDK 的覆盖清单里我们没有找到。三处的位置都在上面写明了，读者可以自己去对应文件核。

顺带记一笔同一目录下的另一个事实：MemoryPanel/scripts/generate-meta-openapi.ts:194 是按 META_ACTIONS 逐条生成 path 的，:341 打印的文案是 (META_ACTIONS.length POST actions + GET instances)。这是脚本里的逻辑，而快照里那份 yaml 的 POST 条目是 54。差异陈述到这里为止。

SDK 侧那 54 条，还要再看一层

数出 54 只是第一步。Python SDK 自己的说明文档里还有一段口径，跟这个数字放在一起看才完整：sdk/memory-core/python/README_CN.md:232 里 MetadataClient 一节自述，「当前先落地 Knowledge 实体管理 5 个端点（/v3/knowledge/*，类型 wiki 与 code-graph），其余 v3/meta 实体（user / team / agent / task / asset / acl / config）后续再补」。

所以「metadata_client.py 里能数出 54 条 /v3/meta/* 路径」与「SDK 文档自述当前先落地 5 个 knowledge 端点」是并列的两条事实，分别出自源码和该 SDK 的 README。要判断某个具体 action 在 SDK 里是不是已经有对应的公开方法，还是得回到 metadata_client.py 逐个看方法名，不能只看条数。

同一份 SDK 里还有一处类似的落差可以对照：sdk/memory-core/python/tencentdb_agent_memory/v3/__init__.py:10-12 导出了 SkillClient 与 AsyncSkillClient，自述封装 14 条 /v3/skill/* 接口，pyproject.toml:8 的 description 也写了 incl. /v3/skill/*；而在 python/README_CN.md、python/README.md、typescript/README_CN.md 以及两份 AGENT_GUIDE.*.zh-CN.md 里 grep skill，命中都是 0 次，只有 typescript/README.md 命中 1 行，另外两份 CHANGELOG 里有记录。这类「代码里有、文档清单里没提」的情况，本文只做记录。

还有一个更基础的坑，写安装命令时最容易撞：目录名不等于包名。MemoryPanel 这个目录，package.json:2 里的 name 是 team-memory-control，前端 web/package.json:2 又是另一个名字 community-loop-lab-web，版本都还是 0.1.0。所以别把目录名直接当包名往命令里写。

为什么这个数字值得较真

因为 /api/v1/meta/* 在 Panel 这边不是透传一切，而是白名单透传。

MemoryPanel/src/panel/http/routes/meta/proxy.ts:143-194 的处理顺序是：先看是不是命中 NOT_IN_SCOPE_PREFIXES，命中就返回 501 NOT_IN_SCOPE（:149-151）；再看在不在 ALLOWED_PANEL_ACTIONS 里，不在就返回 404 UNKNOWN_META_ACTION（:153-155）。

这意味着「一条 action 在文档里有没有」和「它走不走得通 Panel」是两个独立的问题：

  • 数组里有、但落在 agent-fixed-asset/ 前缀下的那 4 条 → 501；
  • 数组里没有 → 404；
  • 契约文件里没有、但在 ALLOWED_PANEL_ACTIONS 里 → Panel 这一层是放行的。

前端对这两个错误码是分开做了文案的：MemoryPanel/web/src/i18n/zh-CN.ts:1148-1149 两条分别对应 UNKNOWN_META_ACTION 与 NOT_IN_SCOPE。所以你如果照着 OpenAPI 文件去推断「Panel 支持哪些 action」，得到的集合和 meta-actions.ts 里的那份并不相同；反过来照着 META_ACTIONS 全量去调，也会撞上那 4 条 501。以仓库实读的这两个常量为准，是最省事的做法。

另外补一个反面参照，说明这类计数并不必然对不上：同目录的 MemoryPanel/src/panel/api/skill-actions.ts:16-31 是 skill 数据面的白名单，文件头注释写「14 条，全部 POST」，数出来也是 14 条。同一个仓库里，两份清单的注释与实数状态并不一样。

自己去数一遍

三处的统计口径都很轻，不需要跑起任何服务。在你 clone 下来的仓库里（记得 checkout 到 feat/server_team），MemoryPanel/ 目录下：

# META_ACTIONS 条数
python -c "
import re
s=open('src/panel/api/meta-actions.ts',encoding='utf-8').read()
blk=s.split('export const META_ACTIONS = [')[1].split('] as const;')[0]
acts=re.findall(r\"'([^']+)'\",blk); print(len(acts))"

# OpenAPI 契约里的 path 条数
python -c "
import re
ls=open('docs/api/meta-api.openapi.yaml',encoding='utf-8').read().split('\n')
print(len([l for l in ls if re.match(r'^  /', l)]))"

# Python SDK 实际覆盖的 meta action 数（在 sdk/memory-core 下执行）
python -c "
import re
s=open('python/tencentdb_agent_memory/v3/metadata_client.py',encoding='utf-8').read()
u=set(re.findall(r'f\"\{_V3\}(/[a-z0-9\-/]+)\"',s)); print(len(u))"

Windows 上用 PowerShell 或 cmd 时注意引号转义与上面的 Bash 写法不同，把脚本存成 .py 文件再跑最省心；Linux / macOS 直接照抄即可。第三条要在 sdk/memory-core/ 目录下执行，前两条在 MemoryPanel/ 下。这几条只是文本统计，不涉及启动任何服务。

什么情况说明你看到的不是这回事

如果你数出来的三个数都不是 55 / 54 / 54，最可能的原因是版本对不上，而不是数错了：

  • 检查当前分支。该仓库的默认分支是 feat/server_team，不是 main 也不是 master。任何写着「main 分支上的某文件」的引用，在这个仓库里都需要重新确认。
  • 检查快照。本文全部对应 97f9465，采集日 2026-08-16；截至这一天，该仓库 GitHub API 显示的最后一次 push 是 2026-08-15。
  • 检查你在看的是哪一层。META_ACTIONS（55）、ALLOWED_PANEL_ACTIONS（51）、契约里的 POST 条目（54）、SDK 覆盖（54）是四个不同的量，混着数必然对不上。

顺带说一句同类现象，不展开：MemoryPanel/src/panel/http/routes/chat-memory.ts:20 的头注释写「12 endpoints」并在 :21-32 逐条列了 12 条，而该文件里实际用 api.post( 注册的是 15 条，注释未列出的三条是 /chat-memory/set-agent-fixed（:633）、/chat-memory/layer-update（:1548）、/chat-memory/search（:1651）。这类「注释里的条数」在这个仓库里最好都当成需要自己复核的量。

最后提醒本文的适用边界：该项目主模块 MemoryCore/package.json 里的 version 是 2.0.0-beta.1，MemoryPanel/package.json:3 与 MemoryPanel/web/package.json:3 都还是 0.1.0，SDK 两侧是 1.0.1-beta.1。处在 beta 阶段的项目，接口清单、白名单常量和契约文件都可能随版本变动，上面所有条数只对我们采集的这一个快照成立。

延伸阅读

本文依据 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，参数与接口随版本变动，请以仓库最新内容为准。 该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员