# AgentTeam Organization 使用手册

本文档面向“实际怎么用”，对应当前已经落地的 org 主链路、稳定入口和推荐操作路径。

如果你要看边界约束和长期设计，请同时参考：

- [../specs/organization.md](../../specs/organization/organization.md)

## 1. 先理解边界

AgentTeam 的 org 模型是“治理叠加层”，不是新的消息边界。

- `workspace` 仍然是聊天、DM、thread、machine、agent 的真实边界
- `organization` 负责目录、team、people、workspace grant
- “加入 organization” 不等于“已经加入某个 workspace”
- “切换上下文” 仍然是切 workspace，不是切 organization

这是当前最重要的心智模型。

## 2. 先认清界面术语

organization 相关页面现在固定使用下面这组名字：

- `People`
- `Workspaces`
- `Org Chart`
- `Teams`

它们和底层对象的关系是：

- `People` 对应 org 侧的 `organization_member`
- `Workspaces` 对应已绑定 organization 的 workspace 与 grant 管理入口
- `Org Chart` 对应 `organization_unit` 树
- `Teams` 对应扁平协作/授权分组

因此：

- 用户侧应统一理解为 `Workspace`，不要再把 `Server` 当成新的产品概念
- 如果你在旧截图、历史文档或旧代码里看到 `Accounts / Servers / Units`，当前应分别理解为 `People / Workspaces / Org Chart`

## 3. 当前 UI 入口

### Organization 入口

用户菜单中有 `Organizations` 入口。进入某个 organization 后，当前主要标签页为：

- `Overview`
- `Enterprise`
- `Teams`
- `Org Chart`
- `People`
- `Workspaces`

### Workspace 入口

当某个 workspace 绑定到 organization 后，当前有两个和 org 相关的入口：

- workspace `Settings` 页中的 `Add from Organization`
- `Add People` 弹窗中的 `Add from Organization`

这两个入口用途不同：

- `Settings -> Add from Organization` 是完整入口：可以 direct grant member / grant team
- `Add People -> Add from Organization` 是快速入口：把某个 org member 直接加入当前 workspace

当前 `HUMANS +` / `Add People` 的展示规则可以直接这样理解：

- 未绑定 organization 的 workspace：只保留 `Invite External by Email`
- 已绑定 organization，且当前用户是该 org 的 `org_owner` / `org_admin`：显示 `Add from Organization` 和 `Invite External by Email`
- 已绑定 organization，但当前用户不是该 org admin：继续只保留邮箱邀请；不能直接走 org grant 路径

## 4. 组织对象怎么理解

### Organization

organization 是治理容器，负责：

- 组织级成员关系
- 团队和组织架构
- workspace 绑定
- 可选的企业目录 / Feishu 同步能力

### Teams

`Teams` 是扁平的协作和授权分组。

适合做的事情：

- 管理哪些人属于同一个协作组
- 以 team 为单位给 workspace 授权

不适合做的事情：

- 表达上下级汇报关系

### Org Chart

`Org Chart` 对应的是 `Units`，用于表达树状组织结构。

适合做的事情：

- 表达目录层级
- 承接外部组织架构导入

它不是 team grant 的替代物。

### People

`People` 页面展示 organization member。

这里要和 workspace 内的 `Humans` 区分开：

- `People` 是 org 侧的人
- `Humans` 是某个 workspace 内已物化出来的成员

一个人可以已经在 `People` 里，但还没有进入任何 workspace。

### Workspaces

`Workspaces` 页面负责：

- 把已有 workspace 绑定到 organization
- 查看已绑定的 workspace
- 做 direct member grant
- 做 team grant
- 撤销 grant
- 解绑 workspace

这里的稳定语义是：

- `Workspaces` 管的是“organization 和哪些 workspace 建立治理关系”
- 它不是新的消息空间，也不是 organization 替代 workspace

## 5. 推荐使用路径

### 5.1 进入 Organization

最小路径：

1. 进入 `Organizations`
2. 打开用户 onboarding 自动创建的 organization，或接受邀请加入已有 organization
3. 先补最少必要的 `Teams`
4. 如果需要目录/SSO，再进入 `Enterprise`

如果你的目标只是让多个 workspace 共享一套组织名单和授权，不需要先上外部目录。

### 5.2 管理 People

当前 `People` 页主要负责两类事情：

- 查看 org members
- 通过 `Invite Member` 邀请新的 organization member

当前 invite 链路已经统一走 `/?invite=` 入口，workspace invite 和 organization invite 共用同一套前端接受流程。接受 workspace invite 时，系统也会确保受邀人成为该 workspace 所属 organization 的普通成员。

需要注意：

- 进入 organization 后，只代表这个人进入了 org
- 他们不会自动进入所有 workspace

### 5.3 绑定 Workspace

在 `Workspaces` 页里把一个已有 workspace 绑定到 organization。

当前主路径应理解为“从你可访问的 workspace 列表里选择并绑定”，而不是手工输入一个原始 workspace ID。

绑定完成后，你会得到两类能力：

- 可以从 org 角度看到这个 workspace 的 grant 状态
- workspace 侧会出现 `Add from Organization` 入口

绑定不会自动改写这个 workspace 现有的人类成员、channel、machine、agent。

### 5.4 把人加入 Workspace

当前有两条 UI 主路径，但底层只有两类稳定授权：`direct member grant` 和 `team grant`。

换句话说，`Add from Organization` 不是第三种权限模型，它只是把当前 workspace 的 `direct member grant` 做成了更短的入口。

当前 UI 路径如下：

### 路径 A：从 org 的 `Workspaces` 页 grant

适合组织管理员做正式授权：

- 对某个 org member 做 direct grant
- 或对某个 team 做 team grant

一旦 grant 生效，对应 human 会被物化或重新激活为 workspace member。

### 路径 B：从 workspace 里 `Add from Organization`

适合在具体协作现场快速把 org 里的人拉进来。

当前行为是：

- 只对当前 workspace 生效
- 会把该 org member 加入这个 workspace
- 走的仍然是现有 `direct member grant` 路径
- 不会自动把他加到所有其它 workspace

## 6. 权限边界

当前实现里，最容易混淆的是 org 权限和 workspace 权限不是一回事。

### Organization 侧

`org_owner` / `org_admin` 当前负责：

- 组织成员治理
- organization invite
- workspace bind / unbind
- direct member grant
- team grant

### Workspace 侧

workspace `owner` / `admin` 当前负责：

- 本地成员管理
- 频道和 agent / machine 管理
- 外部邮箱邀请

但当前实现下：

- 一个 workspace 即使已经绑定到 organization
- 普通 workspace owner/admin 如果不是该 org 的 `org_owner` / `org_admin`
- 仍然不能从 org 入口直接把 org member 加进来

这也是为什么 `Add People` 弹窗在这种情况下会明确提示：当前只允许 org admins 走这条路径，外部邮箱邀请仍然可用。

## 7. 当前推荐实践

### 场景一：内部正式成员

推荐做法：

1. 先进入 organization
2. 在 `People` 建立成员
3. 通过 `Workspaces` 做 member grant 或 team grant
4. 需要 agent 时，在目标 workspace 内按普通 agent/runtime 流程配置

适合长期协作、需要统一治理的团队。

### 场景二：外部协作者

推荐做法：

- 继续使用 workspace 的 `Invite External by Email`

外部协作者不一定要先进入 organization。

### 场景三：某个 workspace 临时需要一个 org 同事

推荐做法：

- 直接在 workspace 用 `Add from Organization`

这条路径最短，但它解决的是“加入这个 workspace”，不是“加入整个 org 治理体系”。

## 8. 当前限制与注意事项

- org 不会替代 workspace；所有实际协作、消息、runtime 仍在 workspace 内发生
- 加入 org 不会自动加入全部 workspace
- 组织成员授权不会自动安装 agent
- `Add from Organization` 当前仍偏向 org admin 路径
- workspace 切换仍然以 `/api/v1/workspaces/:workspaceId/*` path identity 为准，不会引入额外 org 级 request context

## 9. 相关文档

- [../../README.md](../../README.md)
- [../specs/organization.md](../../specs/organization/organization.md)
- [../architecture-spec.md](../architecture-spec.md)
- [../tech_design.md](../tech_design.md)