Heym 团队协作指南：工作流共享、凭证共享与权限管理一次讲清

Heym 是一款自托管的 Agent 系统运行时与编排平台，支持将工作流、凭证、全局变量、向量库等资产按用户或团队进行共享，并用 read / write 两级权限精细控制协作边界。本指南带你从共享机制、操作流程到权限模型，一次搞懂 Heym 的工作流共享、凭证共享与权限管理。

为什么团队协作需要共享机制 🤝

在 Heym 中，一个生产级 Agent 系统往往由多个人共同维护：有人负责画布编排，有人负责接入凭证（如 Slack、GitHub、Supabase），还有人负责观测与分析。如果每个资源都只属于创建者，团队协作就会变成"复制粘贴"的噩梦。

Heym 的解法是：所有核心资产都支持两种共享方式：

这种"个人 + 团队"双层设计，让 Heym 既能覆盖小项目的点对点协作，也能支撑大组织的规模化共享。

工作流共享：read 和 write 两种权限

工作流是 Heym 的核心资产。创建工作流后，只有**所有者（Owner）**可以管理共享列表，共享对象则根据权限级别获得不同能力：

• write（默认）：可以打开、编辑画布、修改设置、运行工作流——与所有者几乎同权；
• read（只读）：可以查看画布并运行工作流，但无法编辑。此时打开编辑器的用户会看到醒目的 Read-only 徽标，避免误触保存：

前端在标题旁渲染只读标记，提示"you can view and run this workflow, but not edit it"（EditorView.vue）。

权限的强制校验在后端统一完成：所有会修改工作流的接口（画布、设置、备注、Agent 记忆等）都会先经过require_workflow_write检查，只读协作者尝试写入时会收到403 You have read-only access to this workflow（workflows.py）。

对应的 API 入口：

• 按用户共享：POST /{workflow_id}/shares，请求体可携带permission: "read" | "write"（workflows.py）
• 按团队共享：POST /{workflow_id}/team-shares
• 撤销共享：DELETE /{workflow_id}/shares/{user_id}与DELETE /{workflow_id}/team-shares/{team_id}

权限字段的定义可以在 schemas.py 中查看，WorkflowSharePermission = Literal["read", "write"]一目了然。

凭证共享：密钥安全地交给该看的人 🔑

凭证（Credential）是工作流访问外部系统的钥匙，比如 OAuth 令牌、API Key。Heym 允许把凭证共享给指定用户或团队：

• 被共享者可以在自己的凭证列表中看到该凭证（标记为共享，并显示提供者邮箱或团队名）；
• 可以在自己的节点配置中选用它，但密钥值始终不会明文回显给非所有者；
• 所有者可随时撤销共享，被共享者立即失去访问权。

相关实现：

• 共享/撤销接口：POST /{credential_id}/shares、POST /{credential_id}/team-shares（credentials.py）
• 数据模型CredentialShare与CredentialTeamShare（models.py）
• 前端共享表单位于凭证面板（CredentialsPanel.vue），支持按邮箱和按团队两种方式添加

💡协作技巧：共享凭证后，把它填进工作流，再连同工作流一起分享给协作者——对方只需"运行"即可，不必知道任何密钥细节。

团队管理：把共享做成"批处理" 🏢

团队是共享的效率放大器。Heym 的 Teams 模块提供：

1. 创建团队：POST /teams，仅需name和可选的description（teams.py）；
2. 管理成员：通过邮箱添加成员（POST /{team_id}/members），也可随时移除（teams.py）；
3. 查看团队共享清单：GET /{team_id}/shared-entities会汇总该团队拥有的工作流、凭证、全局变量、向量库、数据表、文件与模板（schemas.py）；
4. 前端面板：在 Teams 页签中即可创建团队、增删成员并查看共享资产（TeamsPanel.vue）。

成员变动后无需手动调整任何共享关系——成员加入即获得访问权，退出即自动失去访问权，这正是团队共享相比"逐个加人"最大的省心之处。

全景视图：共享之后，谁都能看懂运行状态 👀

共享不只是"能打开"，还包括"能理解"。被共享的工作流同样享有完整的观测能力：执行历史、Traces、成本与 Token 消耗、分析看板对所有协作者可见，团队可以基于同一份数据讨论优化。

还有哪些资源可以共享？ 📦

Heym 的共享能力覆盖整个平台资产，以下资源的 API 都遵循同一套"个人共享 + 团队共享 + 撤销"模式：

此外，文件夹、文件等资产也支持团队共享，形成完整的协作闭环。

权限管理最佳实践 ✅

1. 最小权限原则：给"只看数据、跑跑任务"的同事分read工作流，把write留给真正的维护者；
2. 凭证不轻易共享：优先共享"配置好凭证的工作流"，而非凭证本身；必须共享时限定到个人或必要团队；
3. 以团队为单位授权：人员流动频繁的资源（如数据表、仪表盘）共享给团队，成员变动自动生效；
4. 定期审计共享列表：所有者可随时在共享面板中查看"谁在共享列表里"，并一键撤销；
5. 理解只读边界：只读协作者可以运行工作流但无法修改定义，敏感配置字段（如auth_header_value）对协作者也会被自动掩码（schemas.py）。

快速上手清单 🚀

1. 在Teams页签创建团队并添加成员（TeamsPanel.vue）
2. 为关键凭证执行团队共享（credentials.py）
3. 把共享好的工作流按read/write授权给成员（workflows.py）
4. 协作者登录 Heym，即可在自己的列表中看到共享资源并开箱使用
5. 需要回收权限时，直接删除对应共享记录，立即生效

小结

Heym 用统一的"个人共享 + 团队共享 + read/write 权限"模型，把工作流共享、凭证共享与权限管理收敛到同一套简单心智中：共享给谁、能看还是能改、何时回收，三个问题都有清晰答案。把这套机制用起来，你的团队就能在同一套自托管基础设施上放心地构建和运行 Agent 系统。

📚延伸阅读：

• 共享数据模型：backend/app/db/models.py
• 共享权限 Schema：backend/app/models/schemas.py
• 团队管理 API：backend/app/api/teams.py
• 前端团队面板：frontend/src/components/Teams/TeamsPanel.vue