Plandex 组织（Orgs）与团队协作指南：多用户项目中的 Org、邀请与权限管理

Plandex 组织（Orgs）与团队协作指南：多用户项目中的 Org、邀请与权限管理

【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex

Plandex 是一款面向大型项目与真实世界任务的开源 AI 编码代理（AI coding agent）。本文围绕 docs/docs/core-concepts/orgs.md 讲解的Collaboration and Orgs（协作与组织）主题，系统说明 Plandex 中 Org 的定位、多用户场景下的.plandex配置冲突问题、域名自动加入（Domain Access）机制，以及invite/sign-in/users/revoke四条团队管理命令的完整用法。读完本文，你将掌握在 Plandex 中创建与加入组织、邀请成员、查看成员与待处理邀请、撤销邀请或移除用户的完整流程，并理解这些操作在 CLI 与服务器端的真实实现细节。

Org 是什么：Plandex 协作的基础

Plandex 目前主要面向单用户体验，但官方文档明确指出，共享、协作与团队管理能力已经在规划之中，且部分基础设施已经落地——Org（组织）就是 Plandex 中协作的基础（orgs.md）。

从源码实现看，Org 的模型存储在服务端数据库中，核心字段包括id、name、domain、auto_add_domain_users、owner_id、is_trial等（见 app/server/db/org_helpers.go）。其中：

• owner_id标识组织创建者，创建者会以Owner 角色写入orgs_users成员表（org_helpers.go）；
• domain与auto_add_domain_users支撑后面要讲的“域名自动加入”能力；
• is_trial标记试用组织，试用组织在邀请、列出邀请等协作操作上会受到限制（见 app/server/handlers/invites.go）。

组织与用户之间通过orgs_users关联表建立成员关系，每个成员绑定一个组织角色（Org Role）；角色本身保存在org_roles表中，且支持“全局预置角色 + 组织自定义角色”两种来源（org_helpers.go）。

多用户场景：为什么必须处理.plandex文件

官方文档给出了一个非常实际的警告：Plandex 会在每个创建了 plan 的目录里输出一个.plandex文件，其中包含少量非敏感配置数据。当多个用户在同一项目中使用 Plandex 时，如果没有正确处理这个文件，就会出现严重问题：

除非让每个用户进入同一个 Org，或者把.plandex加入.gitignore，否则每次 push 时每个用户都会覆盖别人的.plandex文件，结果就是“没人会开心”。

因此，多用户协作有两条必选路径：

1. 让所有用户进入同一个 Org——这是文档推荐的协作前提，也是 Org 存在的直接意义；
2. 将.plandex加入.gitignore——如果团队成员不需要共享计划配置，直接忽略该文件可以避免无谓的冲突。

从 CLI 的文件系统处理逻辑看，.plandex相关的目录（.plandex、.plandex-dev、.plandex-v2等）都被列入skipDirs，在扫描项目路径时会被自动跳过（app/cli/fs/paths.go），说明这类目录被设计为本地运行期产物而非应提交的共享内容，这从侧面印证了文档建议的合理性。

Domain Access：创建 Org 时的域名自动加入

在 Plandex 中新建 Org 时，你会看到一个可选项：自动授予任何使用你所在域名邮箱的人访问权限（Domain Access）。

该交互在 CLI 端由 app/cli/auth/org.go 的promptAutoAddUsersIfValid实现，其逻辑要点是：

• 从当前登录用户的邮箱中提取@之后的域名；
• 如果该域名不是邮箱服务商域名（shared.IsEmailServiceDomain判断，如 gmail 等公共邮箱服务），就会提示：

With domain auto-join, you can allow any user with an email ending in @yourdomain.com to auto-join this org. Enable auto-join for yourdomain.com? [y/n]

• 确认后，createOrg会将AutoAddDomainUsers: true随CreateOrgRequest发送给服务端（org.go）。

服务端 CreateOrgHandler 在事务中完成组织创建，并做两件关键事情：

1. 校验域名合法性（邮箱服务域名不能作为自动加入域名），然后把domain写入 Org 记录；
2. 调用db.AddOrgDomainUsers(org.Id, *org.Domain, tx)，把当前已注册且邮箱属于该域名的所有用户一次性批量加入组织，以 Member 角色写入orgs_users，并通过ON CONFLICT ... DO NOTHING保证幂等（org_helpers.go）。

而在用户侧，服务端注册/登录流程中还有AddToOrgForDomain：当某用户用该域名邮箱注册时，会自动查找匹配的 Org，若其AutoAddDomainUsers为真则自动加入（org_helpers.go）。这意味着域名自动加入是双向的：既会批量吸纳存量用户，也会自动接纳后续注册的同域名新用户。

邀请成员：plandex invite

如果不想开放整个域名，或者需要邀请组织域名之外的人，可以使用plandex invite（orgs.md）：

plandex invite

参数与交互

从 app/cli/cmd/invite.go 的源码看，该命令完整签名是：

plandex invite [email] [name] [org-role]

• 最多接受 3 个位置参数：邮箱、姓名、组织角色；
• 每个参数都可以省略：省略时 CLI 会依次以交互方式要求输入——Email 与 Name 使用term.GetRequiredUserStringInput强制输入，Org role 则通过term.SelectFromList从ListOrgRoles()返回的角色列表中单选（invite.go）；
• 角色选择器里的 Label 会映射回角色的Id，随shared.InviteRequest{Email, Name, OrgRoleId}一起提交（invite.go）。

执行成功后终端输出✅ Invite sent。

服务端邀请流程与校验

服务端InviteUserHandler（app/server/handlers/invites.go）在处理邀请时依次做如下校验，值得每一位团队管理员了解：

1. 本地模式限制：GOENV=development且LOCAL_MODE=1时，邀请功能被禁用，返回“Local mode is not supported for invites”；
2. 试用组织限制：org.IsTrial为真时禁止邀请（Trial user can't invite other users）；
3. 权限检查：当前用户必须持有PermissionInviteUser且角色匹配的权限组合（auth.HasPermission）；
4. 邮箱规范化：req.Email = strings.ToLower(req.Email)，统一转为小写；
5. 域名冲突检查：若目标邮箱域名与 Org 已开启自动加入的域名相同，则拒绝邀请（该用户本应通过域名自动加入）；
6. 成员去重：目标邮箱已注册且已是组织成员时拒绝；
7. 邀请去重：同一 Org 下该邮箱已有激活中的邀请时拒绝。

通过全部校验后，邀请记录（OrgId、OrgRoleId、Email、Name、InviterId）与邀请邮件（email.SendInviteEmail）在同一个数据库事务中完成，保证“建记录 + 发邮件”要么都成功、要么都失败（invites.go）。

加入组织：plandex sign-in

被邀请的用户如何加入组织？官方文档给出的答案是使用plandex sign-in（orgs.md）：

plandex sign-in

sign-in命令（app/cli/cmd/sign_in.go）实际执行auth.SelectOrSignInOrCreate()，即“选择账户 / 登录 / 创建”的完整流程，另外还支持--pin参数（plandex sign-in --pin <pin>），用于从 Plandex Cloud Web 界面复制 PIN 码完成登录。

登录完成后，CLI 会读取本地的 auth 文件并解析当前组织。关键逻辑在 app/cli/auth/auth.go 的MustResolveAuth：

• 若本地 auth 尚未绑定 Org（Current.OrgId == ""），CLI 会调用ListOrgs()获取当前账户可访问的组织列表；
• 可访问组织的来源有两类（见 org_helpers.go 的GetAccessibleOrgsForUser）：一是orgs_users中的直接成员关系，二是针对该用户邮箱的待处理邀请（Pending Invites）；
• 若没有任何 Org 可访问，CLI 会提示“To join an existing org, ask an admin to either invite you directly or give your whole email domain access”，并询问是否新建 Org（auth/org.go）；
• 若只有一个 Org 则直接选中；若有多个则弹出选择列表（selectOrg），列表中始终附带“Create a new org”选项（auth/org.go）。

也就是说，收到邀请的用户只需plandex sign-in，其待处理邀请对应的 Org 就会出现在可选组织列表中，选中即完成加入。

查看成员与邀请：plandex users

要查看当前 Org 的成员和待处理邀请，使用（orgs.md）：

plandex users

该命令（app/cli/cmd/users.go）会并发拉取三类数据：

• ListUsers()：组织成员列表；
• ListPendingInvites()：待处理邀请列表；
• ListOrgRoles()：组织角色，用于把角色 Id 翻译成可读的 Label。

最后以表格形式渲染输出，表头为Email | Name | Role | Status，其中成员状态为Active、待处理邀请状态为Pending（users.go）。

撤销邀请与移除成员：plandex revoke

撤销一个邀请，或把某成员移出组织，使用（orgs.md）：

plandex revoke

该命令（app/cli/cmd/revoke.go）的处理策略非常友好：

• 支持可选参数revoke [email]；
• 若未提供邮箱，CLI 会把成员与待处理邀请合并成一个选择列表，其中邀请条目带(invite pending)后缀，供交互式选择（revoke.go）；
• 根据选中的邮箱判断目标属于成员还是邀请：邀请走DeleteInvite（输出✅ Invite revoked），成员走DeleteUser（输出✅ User removed）（revoke.go）。

服务端的DeleteInviteHandler（invites.go）在删除邀请前还会做双重权限校验：当前用户要么持有该角色对应的PermissionRemoveUser权限，要么是邀请发起人（InviterId）且持有PermissionInviteUser权限，否则返回 403。移除成员的删除操作同样发生在orgs_users表上（DeleteOrgUser，见 org_helpers.go）。

团队管理命令速查表

试用组织与本地模式的限制

从服务端源码（invites.go）可以确认两类重要的功能边界：

• 试用组织（Trial Org）：is_trial为真的组织不能邀请用户、不能列出/删除邀请，服务端会返回TrialActionNotAllowed类错误；
• 本地模式（Local Mode）：以GOENV=development+LOCAL_MODE=1运行时，邀请相关的所有接口均被禁用（Local mode is not supported for invites）。因此团队协作功能面向的是非本地模式、非试用的 Plandex 部署。

小结

Org 是 Plandex 协作能力的地基：它既是多用户避免.plandex互相覆盖的解决方案，也是邀请、角色与域名自动加入等机制的唯一入口。围绕 Org 的invite、sign-in、users、revoke四条命令构成了完整的团队生命周期管理闭环——从创建组织、邀请成员、成员加入，到查看状态、撤销邀请与移除成员，每一步都有 CLI 层的交互引导和服务端层的权限、去重与事务保证。相关实现可进一步查阅 app/cli/cmd/invite.go、app/cli/cmd/users.go、app/cli/cmd/revoke.go 与 app/server/handlers/invites.go，以及数据库层 app/server/db/org_helpers.go。

【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex