用途:本技能是 Taruvi 后端的控制面,用于通过 Taruvi MCP 服务器配置与修改后端资源,包括数据表、存储桶、用户、角色、Cerbos 策略、密钥、函数注册和分析查询。若编写运行在已部署函数内的 Python,应改用 taruvi-functions;构建 Refine 前端应改用 taruvi-refine-frontend。
主要能力:共 24 个工具,按域分组。数据表(5):get_datatable_schema、create_update_schema、datatable_data、datatable_edges、delete_datatable;存储(1):manage_storage(子动作 list_buckets、create_bucket、list_objects、get_quota);密钥(4):list_secrets、get_secret、create_update_secret、manage_secret_types;用户(3):list_users、create_user、update_user;用户属性(1):user_attributes_schema;角色(2):manage_roles、manage_role_assignments;函数(2):manage_function、execute_function;策略(1):manage_policies;分析(2):manage_query、execute_query;原始 SQL(1):execute_raw_sql;元(2):manage_tags、get_ai_docs。
使用方式:数据表采用 Frictionless Data Package 模式,由 create_update_schema 自动物化 PostgreSQL 表。Frictionless 到 Postgres 的类型映射:string→TEXT、integer→INTEGER、number→NUMERIC、boolean→BOOLEAN、date→DATE、datetime→TIMESTAMP WITH TIME ZONE、object/array→JSONB。行级操作示例:datatable_data(action="query", table_name="orders", filters={"total__gte": 100}, limit=100);upsert 与 delete 同理,limit 默认 100、上限 1000。过滤运算符遵循 DRF 约定,如 field__gte、field__in、field__contains、field__null。图边操作使用 datatable_edges 的 list/create/delete。
关键限制:create_update_schema 是整体替换而非合并,缺失字段会被删除,操作前须先 get_datatable_schema。manage_policies(action="create_update") 完全替换策略体,不合并。delete_datatable 为破坏性操作,不加 force=True 会在存在外键依赖时失败;force=True 危险,须先向用户确认。execute_raw_sql 拒绝跨租户访问、系统模式及视图/触发器/函数 DDL;同一批次中 DDL 会先于后续 DML 提交。租户上下文由会话环境解析,除接受 app_slug 的工具外不要手动传入租户标志。create_bucket 必须提供 app_category(assets 或 attachments)。密钥类型创建后不可重命名,系统类型不可修改。用户更新不接受密码更改。list_users 默认 is_active=True 会隐藏非活跃用户。is_public=True 的函数未认证运行,user_data 为 None,需在函数体内验证共享密钥或签名。
适用场景:为数据平面消费者创建或更新数据表并配套启用 Cerbos 策略、创建角色与分配、创建存储桶、注册函数元数据、定义分析查询与受控原始 SQL。
核验与排障:完成配置后需核验模式、策略启用状态、角色父子关系、角色分配、存储桶可见性、函数元数据与密钥类型。工具级文档可用 get_ai_docs(category="policies"|"sdk"|"users", topic="guide"|"attributes");参考文件包括 references/mcp-tool-quickref.md、references/datatable-schema-patterns.md、references/cerbos-policy-cookbook.md、references/secrets-and-types.md、references/raw-sql-safety.md、references/analytics-queries.md;版本漂移检查为 bash scripts/check-versions.sh。