taruvi-app-developer

Taruvi 应用开发者（后端）

Taruvi 的单一后端技能。涵盖两个层面：

• 控制平面（MCP）——配置数据表、策略、角色、存储桶、密钥、函数元数据、分析查询和经过审计的原始 SQL。
• 数据平面（函数运行时）——在 Celery 工作器上运行的 Python 函数体，签名为 def main(params, user_data, sdk_client)，并使用经过预认证的 sdk_client。

如果任务涉及在前端接入 React/Refine 提供程序或钩子，请切换到 taruvi-refine-providers。

决策：使用函数，还是只通过 MCP 配置？

以下场景只需配置：架构更改、策略／角色／用户管理、创建存储桶、密钥管理、注册分析查询、一次性管理 SQL。

任务涉及以下任一内容时，需要函数体：

• 运行时涉及 2 个或更多资源（数据库 + 存储、用户 + 数据库等）
• 事件触发器（RECORD_CREATE、RECORD_UPDATE、RECORD_DELETE、POST_USER_CREATE、……）
• 定时任务／cron
• 使用已存储密钥调用外部 API
• 长时间运行的任务（>30 秒 → async_mode=True）
• 公开的未认证端点（is_public=True）
• 超出普通 Cerbos 资源策略范围的授权门控
• 函数间流水线

如有疑问，请参阅 when-not-to-use-functions.md。

工作流

1. 阅读一次 architecture-overview.md，了解运行时划分；对于全新应用，还要根据 agents-md-template.md 创建 AGENTS.md。
2. 决定使用函数还是配置（见上文）。编写函数代码前，请阅读 function-authoring.md 和 function-sdk-reference.md 中的相关部分。
3. 处理 MCP 工作时，打开 mcp-tool-quickref.md 和下方与任务相关的参考文档。
4. 对于破坏性操作，请遵循破坏性操作流程（见下文）。
5. 通过重新读取资源（get_datatable_schema、manage_policies(action="get") 等），并端到端执行函数／分析查询进行验证，然后再报告完成。

参考索引

任务	阅读
MCP 工具签名	mcp-tool-quickref.md
无摩擦架构（外键、索引、层级、图）	datatable-schema-patterns.md
Cerbos 策略编写	cerbos-policy-cookbook.md — 或 get_ai_docs(category="policies", topic="guide")
密钥和自定义密钥类型	secrets-and-types.md
经过审计的原始 SQL	raw-sql-safety.md
分析查询（注册 + Jinja2 参数）	analytics-queries.md
筛选运算符／查询能力	backend-capabilities.md
函数运行时契约、模式、触发器	function-authoring.md
sdk_client 模块和方法	function-sdk-reference.md
事件触发器、CEL 筛选器	function-events.md
函数示例（8 种场景）	function-scenarios.md
跨层功能示例	feature-workflow-examples.md
集成注意事项	integration-pitfalls.md
前端 Worker 部署	frontend-worker-deploy.md
导出后端配置	backend-export.md
环境变量设置	env-setup.md

不可妥协事项

其中大多数也已写入参考资料——此处列出，是因为忽略它们会导致实际故障。

1. 相信 MCP 工具，而不是记忆。 工具响应中包含后续所需的 ID、slug 和状态。不要臆造端点或方法名。
2. create_update_schema 会丢弃负载中缺失的字段。 务必先调用 get_datatable_schema，然后发送完整且保留所有字段的列表。
3. manage_policies(action="create_update") 会替换，而非合并。 先获取现有策略，进行修改，然后发回完整内容。
4. 函数签名必须完全是 def main(params, user_data, sdk_client):。 任何偏差都会立即触发 SandboxError。
5. 切勿重新验证 sdk_client。 它已预先完成身份验证。不要调用 client.auth()、client.login()，也不要传入 API 密钥。
6. 切勿硬编码机密。 使用 sdk_client.secrets.get("KEY")。
7. 函数返回值必须可序列化为 JSON。 返回 datetime、set、Decimal 和自定义类会导致崩溃——请先转换。
8. 耗时超过 30 秒的任务需要设置 is_async=True。 同步调用会在 30 秒后超时，并导致 UI 加载指示器卡住。
9. 使用 log()，不要使用 print()。 print() 会输出非结构化的 stdout，且无法查询。
10. 前端多资源级联操作属于 bug。 将其移至函数中——操作期间浏览器导航会导致数据库状态不一致。

破坏性操作规范

适用于：delete_datatable（尤其是 force=True）、对现有策略调用 manage_policies(action="create_update")、user_attributes_schema(action="update")、manage_secret_types(action="delete")、manage_function(action="delete")、manage_roles(action="delete")，以及任何包含 DROP、TRUNCATE、破坏性 ALTER 或不带 WHERE 的 DELETE 的 execute_raw_sql。

1. 规划——检查当前状态（get_datatable_schema、manage_policies(action="get") 等），并说明将删除或替换什么，以及有哪些内容依赖于它。
2. 验证——用通俗语言说明影响范围（“这会删除 orders，以及 invoices 中 3 个依赖它的外键”）。取得用户的明确确认。
3. 执行——仅在获得确认后执行。逐字报告工具的响应。

始终创建测试用户

完成配置后，创建测试用户，以便用户验证应用是否正常运行：

• 启用了访问控制： 每个角色创建一个测试用户，用户名格式为 qa_<role_slug>_<YYYYMMDD>（例如 qa_warehouse_staff_20260422），密码长度至少为 12 个字符，并包含大小写字母、数字和符号。向用户提供所有用户名和密码。
• 未启用访问控制： 创建一个默认超级管理员测试用户，并报告密码。
• 提供清理指引： 验证后停用或删除 qa_* 用户，或轮换其密码。

始终通过执行来验证

在报告函数或分析查询已完成之前：

1. 使用真实的示例参数运行 execute_function(function_slug=..., params={...}) 或 execute_query(query_slug=..., params={...})。
2. 检查实际响应的结构。
3. 确认所有前端代码都使用返回结果中的确切字段名和结构——如果不匹配，请修复前端。

版本漂移检查

node scripts/check-versions.js 会在固定的 SDK/提供商版本与 PyPI/npm 上的最新版本不一致时发出警告。