Proposal: 基于 Go 的 TeamAI 管理后端（零 Git 接入与多项目管理）

背景

TeamAI 当前主要依赖 Git 仓库管理和同步团队资源。现有 HTTP 模式则更偏向 ClawPro 的 local-agent 场景，只覆盖 report/sync/ack 与命令下发，无法完整承载 Git 模式已有的资源读写、审核发布、知识贡献和团队数据管理能力。

Git 对开发者很自然，但对于不熟悉仓库、凭据、clone、branch、commit、push 和 MR/PR 的用户，接入与日常管理成本仍然较高。多个项目之间的成员、资源、权限和版本也缺少统一的可视化管理入口。

建议设计并逐步建设一个基于 Go 的 TeamAI 管理后端，完整承载现有 Git 团队仓的能力，并把“不会 Git 也能简单接入”作为首要产品约束。

核心目标

• 用户无需理解或安装 Git 即可接入 TeamAI。
• 提供组织、团队和多个项目的统一管理能力。
• 支持全部 TeamAI 资源的版本化读取、写入、审核、发布和回滚。
• 支持方便接入企业内部鉴权系统。
• 保留 CLI 的本地使用体验，并尽量复用现有 ResourceHandler。
• 后端采用 Go，未来放在当前仓库的 server/ 目录中，以 monorepo 方式管理。

用户接入体验

管理员

1. 登录 Web 管理控制台。
2. 创建组织、团队和项目。
3. 配置项目资源、成员及权限。
4. 生成一次性接入命令或短码。
5. 查看成员、设备和工作区的接入及同步状态。

普通成员

1. 安装 TeamAI CLI。
2. 执行接入命令，或通过浏览器登录/输入短码。
3. 选择有权限访问的项目。
4. CLI 自动完成身份授权、工作区绑定和资源同步。

该流程不应要求用户理解：

• 仓库 URL 或 Git 凭据
• clone、branch、commit、push
• MR/PR 或 Git 冲突处理

还需要覆盖首次接入、加入多个项目、项目切换、离线重试、权限失败、设备解绑和卸载等场景。

多项目管理模型

建议采用以下层级：

Organization
└── Team
    ├── Project A
    ├── Project B
    └── Project C

资源可位于组织、团队、项目和用户层级，并定义清晰的继承与覆盖顺序：

组织资源
  ↓
团队资源覆盖
  ↓
项目资源覆盖
  ↓
用户个性化配置

管理控制台至少应支持：

• 项目创建、归档和删除
• 项目成员与角色管理
• 草稿、审核和发布状态
• 版本历史、差异预览与回滚
• 批量发布、批量删除
• 跨项目资源复用
• 接入设备与同步状态
• 操作审计

需要替代的 Git 能力

后端需要覆盖现有团队仓中的全部数据：

• teamai.yaml
• skills/
• rules/
• docs/
• env/env.yaml
• agents/
• hooks/hooks.yaml
• mcp/mcp.yaml
• learnings/
• culture.md
• claudemd/
• tags.yaml
• manifest/roles.yaml
• sources
• members/
• stats/
• votes/
• sessions/

Git 概念应映射为用户更容易理解的后端概念：

• clone/pull → 版本化资源同步
• commit → 变更集
• branch → 草稿
• MR/PR → 审核请求
• merge → 发布
• Git revision → 后端 revision
• Git conflict → 乐观锁冲突
• revert → 版本回滚

领域模型

建议至少包含：

• Organization、Team、Project、WorkspaceBinding
• User、Role、Membership、Device
• Resource、ResourceVersion、Revision
• ChangeSet、Review、Release
• Learning、Vote、UsageEvent、Session、AuditEvent

数据应区分两个平面：

1. 已发布资源面：skills、rules、docs、env、agents、hooks、MCP 等资源同步。
2. 用户上报数据面：members、stats、votes、sessions 和设备状态。

设计需要明确项目层级继承、同名资源覆盖、删除传播、不可变版本、并发冲突和跨项目共享规则。

API 能力

设计独立、版本化的新 HTTP API，至少覆盖：

• 登录、设备授权和令牌刷新
• 组织、团队、项目及成员管理
• 工作区与项目绑定
• 全量快照与增量资源同步
• 资源清单及内容读取
• 批量创建、修改和删除资源
• 变更集、审核、发布和回滚
• 知识贡献
• stats、votes、sessions 上报
• 审计查询

协议需要定义：

• revision 与内容 hash
• ETag / If-Match 乐观锁
• Idempotency-Key
• 分页和批量操作
• 稳定错误码
• 制品完整性校验
• 客户端兼容版本

内部鉴权接入

内部鉴权应作为可插拔能力：

• Web 控制台支持企业 SSO。
• CLI 支持浏览器授权、OAuth Device Flow，以及无浏览器环境的一次性短码。
• 优先支持 OIDC/OAuth 2.1 标准接口。
• 非标准企业鉴权通过 Go IdentityProvider adapter 接入。
• 业务模块只依赖 TeamAI 内部用户 ID、标准 claims 和权限决策，不直接耦合具体企业鉴权 API。

需要进一步定义：

• 外部身份与 TeamAI 用户的稳定映射
• 组织、部门、用户组到 TeamAI 角色的映射
• 首次登录自动建档
• 用户禁用或离职后的权限回收
• 令牌刷新、吊销和设备解绑
• 服务账号
• 鉴权服务不可用时的安全降级策略

CLI 目标数据流

设计需要说明以下命令如何从 Git 操作迁移到后端 API：

• teamai init
• teamai pull
• teamai push
• teamai contribute
• teamai remove
• teamai team-push
• teamai recall
• teamai source

第一阶段可继续将服务端资源 materialize 为本地团队目录，以兼容现有 ResourceHandler，降低 CLI 改造范围。

Go 服务蓝图

建议以分层单体起步，避免过早拆分微服务：

server/
├── cmd/
│   └── teamai-server/
├── internal/
│   ├── identity/
│   ├── organizations/
│   ├── projects/
│   ├── resources/
│   ├── changesets/
│   ├── reviews/
│   ├── sync/
│   ├── telemetry/
│   ├── audit/
│   └── platform/
├── migrations/
├── api/
└── tests/

通过接口隔离基础设施：

• metadata repository
• blob store
• transaction manager
• event publisher
• identity provider
• audit sink

identity 模块负责把不同鉴权系统转换为统一身份和 claims，其他领域模块仅依赖内部身份及授权决策。

安全与运维要求

• 多租户隔离与项目级 RBAC
• 用户令牌、设备令牌和服务账号 scope
• env 与 secret 分离
• 敏感内容脱敏
• 上传文件、内容 hash 和制品签名校验
• 不依赖任意远程命令执行
• 操作审计、限流和幂等处理
• 备份恢复与数据保留策略
• 指标、日志和链路追踪

设计交付物

本 Issue 第一阶段只产出设计，不创建后端服务代码：

• docs/designs/management-backend.md
• docs/designs/management-backend.zh-CN.md

设计文档应包含：

• 完整能力映射和领域模型
• 零 Git 接入用户旅程
• 多项目管理模型
• 内部鉴权扩展点
• API 契约与状态机
• Go monorepo 模块蓝图
• 安全及运维要求
• 阶段化实施顺序
• 验收标准、开放决策和非目标

验收标准

• 对照 src/pull.ts、src/push.ts、src/local-agent.ts、src/team-push.ts 和 src/resources/，确保所有现有读写能力都有后端映射。
• 四条端到端用户旅程完整且不暴露 Git 概念：
  1. 企业用户通过内部 SSO 首次登录并自动获得组织身份。
  2. 非 Git 用户首次加入单个项目。
  3. 同一成员加入并管理多个项目。
  4. 管理员通过控制台审核并发布跨项目资源。
• 鉴权边界覆盖标准 OIDC、非标准内部 provider、用户/用户组同步、CLI Device Flow、令牌吊销和鉴权服务故障场景。
• 中英文设计文档的章节、API 名称、状态机、实施阶段和验收标准保持一致。

非目标

• 本阶段不实现 Go 服务或 Web 管理控制台。
• 本阶段不修改当前 CLI 行为。
• 本阶段不更新仍描述当前行为的 usage guide。

Read src/pull.ts, src/push.ts, src/local-agent.ts, src/team-push.ts, and src/resources/ first to map existing capabilities. Then draft docs/designs/management-backend.md and docs/designs/management-backend.zh-CN.md, covering the requested domain model, API, authentication, implementation phases, acceptance criteria, open decisions, and non-goals. Done means both documents are aligned and map all listed capabilities without implementing the Go service.