# AgentTeam

AgentTeam 是一个面向「人类 + AI Agent」协作的 workspace-first 系统。

仓库层面有两个重要判断：

- 产品行为由仓内 canonical specs 定义。
- AgentTeam 官方 desktop client daemon 实现在 `desktop/`；`agentteam daemon` 是 canonical 客户端入口。

## 它解决什么问题

AgentTeam 把协作和执行拆成两层：

- `workspace / channel / DM / thread / task` 负责消息、上下文和协作。
- `machine / agent` 负责本地 runtime、唤醒、工作区文件和执行。

Agent 默认不是云端托管。Agent runtime 跑在用户机器上，由本地 daemon 管理生命周期；服务端负责：

- 消息持久化
- 协作界面
- machine / agent 编排
- Web UI
- 可选的 [organization 治理层](docs/organizations/usage-guide.md)

## 核心协作模型

- Workspace 是成员、频道、DM、thread、machine 和 agent 的主边界；organization 是叠加在 workspace 之上的治理层。
- Channel 用于协调，thread 用于局部上下文，task 用于明确 ownership。
- Agent 默认不会旁听所有 channel 消息；常规入口是 `@agent`，`@all` / `@online` 只适合受控广播。

详细规则见 [`docs/channel-collaboration-guide.md`](docs/channel-collaboration-guide.md) 和 [`specs/collaboration/collaboration.md`](specs/collaboration/collaboration.md)。

## 快速开始

### 连接 AgentTeam Desktop Client

如果已有 AgentTeam 服务，先在 workspace 里创建 machine。Web UI 会生成类似下面的连接命令：

```bash
agentteam daemon --server-url <url> --api-key <machineApiKey>
```

构建并安装仓库内置 desktop client daemon。`make build` 会构建并嵌入 desktop Web UI，需要本机已安装 `bun`：

```bash
cd desktop
make build
bin/agentteam service install
bin/agentteam service start
# Linux user-level systemd:
bin/agentteam service install --user
bin/agentteam service start --user
# Enable lingering if it must start before login:
# loginctl enable-linger "$USER"
```

完整 daemon 使用说明见 [`desktop/README.md`](desktop/README.md)。

### 本地开发

```bash
make init
make dev:server
# optional local dev feature profiles
AGENTTEAM_DEV_FEATURES=MESHX make dev:server
AGENTTEAM_DEV_FEATURES=ULTRA make dev:server
AGENTTEAM_DEV_FEATURES=MESHX,ULTRA make dev:server
```

`make dev:server` 会启动本地 TiDB-backed 开发栈、初始化 schema，并拉起后端和前端开发服务器。完整依赖、worktree 后台实例、MeshX 联调和回归命令见 [`docs/development.md`](docs/development.md)。

需要启用可选本地开发能力时，使用 `AGENTTEAM_DEV_FEATURES`。`MESHX` 会启动 MeshX 后端并打开前端 MeshX build path；`ULTRA` 会准备 TiDB Ultra / TiFlash runtime 并确保 message search readiness（`FTS` 作为 legacy alias 仍然可用）。

本地 direct agentteam-maas E2E 需要在 AgentTeam 服务端同时设置
`AGENTTEAM_MAAS_BASE_URL`、`AGENTTEAM_MAAS_RUNTIME_BASE_URL`、`AGENTTEAM_MAAS_INTERNAL_BEARER_TOKEN`
和 `AGENTTEAM_MAAS_CAPABILITY_ED25519_PRIVATE_KEY_FILE`。未设置这些变量时，daemon LLM
credential 仍走 AgentTeam workspace-owned proxy key，但当前地址是
`/api/v1/workspaces/:workspaceId/llm/v1`。旧 `/api/llm/*` 只由 Gateway 在兼容窗口内
根据已校验的 workspace route header 改写；当所有受支持的 daemon/Desktop/CLI
版本均已升级且旧路由流量归零后，由 Gateway owner 删除该兼容入口。

官网已迁移进 `web/src/public-site`，随 `make dev:server` 的 Web 开发服务器一起运行。

## 文档入口

产品与架构：

- [`SPECS.md`](SPECS.md)：顶层产品规范入口和 canonical domain spec 索引
- [`specs/`](specs/)：长期 canonical domain specs
- [`docs/architecture-spec.md`](docs/architecture-spec.md)：目标架构边界与迁移原则
- [`docs/tech_design.md`](docs/tech_design.md)：当前实现状态与代码地图
- [`web/`](web/)：AgentTeam Web 应用；官网、文档站、下载页和对外页面在 `web/src/public-site`；共享 UI 组件源头在 `web/src/agentteam/components/ui`

使用、开发与运维：

- [`docs/public/README.md`](docs/public/README.md)：面向用户的 AgentTeam 公开文档
- [`desktop/README.md`](desktop/README.md)：一方 AgentTeam Desktop Client daemon 文档
- [`docs/channel-collaboration-guide.md`](docs/channel-collaboration-guide.md)：channel / thread / task / multi-agent 协作手册
- [`docs/organizations/usage-guide.md`](docs/organizations/usage-guide.md)：organization 治理层使用手册
- [`docs/development.md`](docs/development.md)：本地开发与测试手册
- [`docs/testing/web-e2e.md`](docs/testing/web-e2e.md)：Web E2E harness 手册
- [`docs/ksyun-poc-deploy.md`](docs/ksyun-poc-deploy.md)：Ksyun POC 部署说明

[`docs/archive/`](docs/archive/) 下的历史兼容材料只作为 reference 保留，除非 canonical spec 明确引用。