企业级 Skills 市场建设方案评审与改进建议

—— 基于 TencentDB Agent Memory 的实测验证

受评对象：《企业级 Skills 市场建设方案：基于 QwenPaw × TencentDB Agent Memory 的发布、授权与治理平台》（blog.apescale.com/?post=87）
评审日期：2026-08-08
评审批注：本文档基于对 TencentDB Agent Memory（已部署于 113.249.102.8）真实 API 的逐项调测撰写，非纸面推演。

一、总体评价

结论：方案方向正确，具备工程可落地性，但存在 3 处关键技术论断与实际部署能力不符，需要在实施前修正。 总体可评为 7.5/10——架构设计成熟、思路完整，但个别细节未经实测验证，存在"文档推演偏差"。

二、方案合理性盘点（优点）

2.1 核心方向判断准确

论断 评价 依据
「无需从零自研，TencentDB 提供 Skill 资产底座」 ✅ 正确 实测 POST /v3/skill/{list,get,create,update,delete,search,archive} 全链路可用
「三层架构：用户层/治理层/运行层」 ✅ 优秀 分层清晰，符合技能市场"管用分离"的成熟模式
「QwenPaw 作运行层」 ✅ 合理 Skill 需要可执行 Agent，运行/治理分离是对的
「领导 = System Admin 可看全部」 ✅ 正确 实测 system_admin 可列全部用户/团队/Skill 资产
「财务 Owner / 人事使用者」角色映射 ✅ 合理 与 TencentDB 的 owner + ACL 授权体系吻合

2.2 生命周期状态机设计合理

草稿 → 待审核 → 已发布 →（授权给人事）→ 下架

状态切换记录审计链 —— 思路正确，满足企业治理诉求。

三、与实测不符的关键问题（需修正）

以下问题均基于对部署实例真实 API 的调测，是方案中最需要修正的部分。

⚠️ 问题 1：Skill 并不存在「四档可见性」

文章声称： Skill 资产有 private / team / restricted / agent 四档可见性，用 restricted 做「财务发布给人事用」的精确授权。

实测结果： POST /v3/skill/get 返回的资产字段为：

["skill_id","name","description","version","is_head","status",
 "owner_user_id","owner_agent_id","team_id","task_id",
 "created_at_ms","updated_at_ms","content_hash","storage_dir","content","manifest"]

没有顶层的 visibility 字段。 可见性（visibility: team）只存在于 agent 层（/v3/meta/agent/get），不存在于 Skill 资产层。文章把 agent 的可见性概念错误移植到了 skill 上。

修正方案： 权限控制不能依赖"skill 四档可见性"。需改用以下真实能力：

  • 归属隔离：Skill 通过 team_id 归属团队（实测 create/query 均校验 team 归属一致）
  • ACL 授权：实测 POST /v3/meta/acl/check 生效（{"allowed":true,"reason":"owner"}），支持 read/write/delete/assign/share/use 六种动作
  • Agent 可见性：agent.visibility 控制 Agent 层面的可见，间接影响其装载的技能展示

⚠️ 问题 2：MemoryKnowledge 并非独立服务(:8421)

文章声称： 需要补启动 MemoryKnowledge(:8421) 作为 OpenAPI 出口，此前未启动。

实测结果： 当前仅 3 个容器：

tdai-memory-core :8420
tdai-memory-hub  :8125 (Panel) + :8424 (Knowledge)
tdai-proxy       :8096

Knowledge 功能由 memory-hub 的 8424 端口承载，不是独立 8421 服务。 文章凭空引入了不存在的服务端口，会给部署排障带来误导。

修正方案： 无需补启动任何 8421 服务。Knowledge OpenAPI 走现有 :8424（Nginx 反代 /knowledge/）。文档需删除对 8421 的引用。

⚠️ 问题 3：自建表清单可大幅缩减

文章声称： 需自建 skills / skill_versions / acl / subscriptions / usage_logs / audit_logs 六张表。

实测结果： TencentDB 已有诸多原生能力可替代：

  • 使用日志：POST /v3/meta/participation-log/list（实测存在，按 team 查询）
  • 固定资产摘要：POST /v3/meta/agent-fixed-asset/summary-by-agents（统计）
  • Skill 版本：Skill 自带 version + is_head + 完整内容存储，天然支持版本管理
  • Owner/Team 归属：Skill 原生带 owner_user_id / team_id

修正方案： 自建表只需保留业务层需要的 acl 授权映射 和 portal 门户自己的配置表，其余尽量复用原生接口，减少数据一致性维护成本。

四、改进后的权限模型（基于实测能力）

4.1 权威的权限控制链路

┌──────────────────────────────────────────────────────────────┐
│                     用户层（门户）                            │
│   财务发布者 / 人事使用者 / 领导(Admin) / 系统管理员           │
└────────────────────────┬─────────────────────────────────────┘
                         ▼  业务层 RBAC（门户自建，控制菜单/按钮）
┌──────────────────────────────────────────────────────────────┐
│  授权判定：两层叠加                                          │
│  ① Skil归属 → team_id 隔离（财务技能在 finance team）          │
│  ② ACL check → /v3/meta/acl/check (read/write/share/use)     │
│  ③ Agent可见性 → agent.visibility (team/public)              │
└────────────────────────┬─────────────────────────────────────┘
                         ▼  数据层（TencentDB AM）
                          Skill + owner + team + version + participation-log

4.2 角色 → 真实权限映射

业务角色 TencentDB 映射 权限实现（实测可用）
财务（发布者） Skill Owner ✓ 创建/更新/删除自己的 skill；acl/check 返回 owner 允许
人事（使用者） 授权使用者 ✓ 通过 ACL use 授权 + skill/search 检索
领导（管理者） System Admin ✓ user/list、team/list、skill/list 全量可见
系统管理员 System Admin ✓ 用户/团队/全局配置

五、落地路径优化（修正后）

阶段一：权限基座预置（原 0.5-1 天，实测已具备）

  • ✅ 复用 core(:8420) / hub(:8125/:8424) / proxy(:8096)，无需补启动 8421
  • ✅ 已实测 admin 可创建 team/agent/user，可建 Finance Team / HR Team / Leadership

阶段二：Skill 资产化试点（1-2 天）

  • 财务技能上架，走「创建 → 归属 finance team → ACL 授权给 HR → 人事 Agent 装配」
  • 关键修正：可见性用 team_id 归属 + ACL，而非"skill visibility"

阶段三：门户定制（3-5 天，可选）

  • 用 participation-log + skill/search 聚合出"使用量排行"，领导驾驶舱免自建统计
  • ACL 授权页面直接封装 v3/meta/acl/check 与授权接口

阶段四：治理推广

  • 审计链复用 participation-log，减少自建 audit_logs 表

六、风险与注意事项（补充实测要点）

风险 实测补充
Skill name 限制中文 ⚠️ skill name 必须 ^[a-z0-9][a-z0-9-]*$（实测，中文名创建报错），需做 display_name 映射
归属强校验 ⚠️ 实测 team_mismatch 强校验：agent 属 A team 不能建 B team 的 skill，需确保归属一致
无删除接口 ⚠️ emlog 类下游无删除 API 是常态；TencentDB skill 有 delete（实测 archived:true）
Admin Key 泄露 ⚠️ 全局 API 用 admin key 即可访问，后端必须二次 RBAC，admin key 不暴露前端

七、总结

原方案 7.5/10，经修正后可作为实施蓝图。 关键改动：

  1. ❌ → ✅ 删除"skill 四档可见性"，改用 team_id 归属 + ACL check + agent.visibility 三机制
  2. ❌ → ✅ 删除对 MemoryKnowledge(:8421) 的引用，Knowledge 走 hub :8424
  3. ❌ → ✅ 大幅缩减自建表，复用 participation-log 等原生统计

整体记忆： TencentDB Agent Memory 确实具备 Skills 市场所需的技能治理底座，核心缺口在业务层门户（发布/授权/浏览界面）需要定制。技术底座和 ACL 均已实测可用，落地风险可控。

本文所有技术论断均有 113.249.102.8 部署实例的真实 API 调测支撑。