Tencent / Tencent/teamai-cli

refactor: 统一 Git/HTTP resource provider,ClawPro 改为 HTTP adapter

Open
#404 0 comments 0 reactions 1 assignee View on GitHub

@jeff-r2026 is already working on this.

Since Sep 9, 2026.

Dominant language
TypeScript
Stars
4.8k
Forks
342
Avg merge
13h 48m
Merged PRs (30d)
211

Description

背景

当前 HTTP 后端在 CLI 中以 local-agent / repo.kind: http / HTTP source 等多个特殊概念存在:

  • src/local-agent.ts 同时承担 HTTP 请求、ClawPro 协议解析、资源安装、插件管理和项目绑定;
  • HTTP 后端是全局单例,状态固定存放在 ~/.teamai/local-agent/
  • Git 主仓、Git source 和 HTTP source 走不同分支,难以同时挂载多个后端;
  • local-agent 实际上是 ClawPro 服务端协议的客户端实现,不适合作为本地架构名称;
  • 后续还会出现开源管理后端(参见 #341),不应继续为每个 HTTP 后端复制一套特殊流程。

ClawPro 产品说明:https://cloud.tencent.com/document/product/1759/128832

目标

建立统一的资源后端抽象:

ResourceProvider
├── git
└── http
    ├── clawpro adapter
    ├── teamai/open-source adapter
    └── other adapters
  • githttp 是资源同步机制层的 provider;
  • GitHub、TGit、GitLab 等作为 Git provider 内部的 host adapter;
  • ClawPro 作为 HTTP provider 的协议 adapter;
  • 支持同时配置多个 Git provider 和多个 HTTP provider;
  • 将来停止维护 ClawPro 时,可以删除 http/adapters/clawpro/,不影响 HTTP provider 和其他后端。

建议目录结构

src/providers/
├── types.ts
├── registry.ts
├── git/
│   ├── provider.ts
│   └── hosts/
│       ├── github/
│       ├── tgit/
│       └── gitlab/
└── http/
    ├── provider.ts
    ├── client.ts
    ├── types.ts
    └── adapters/
        ├── clawpro/
        ├── teamai/
        └── generic/

当前 src/providers/* 中的 GitHub/TGit 等实现需要逐步下沉为 Git host adapter,不应让 ClawPro 实现现有的 GitProvider 接口。

Provider 与 adapter 接口

Provider 使用 capability 表达能力,不要求 HTTP 后端实现 Git clone/PR 等无关方法:

interface ResourceProvider {
  readonly name: string;
  readonly type: 'git' | 'http';
  readonly capabilities: {
    pull: boolean;
    push: boolean;
    report: boolean;
    commands: boolean;
  };

  sync(context: SyncContext): Promise<ProviderResult>;
  describe(): Promise<ProviderSummary>;
  teardown(): Promise<void>;
}

HTTP adapter 只负责协议差异:

interface HttpBackendAdapter {
  readonly name: string;

  routes(config: HttpProviderConfig): HttpRoutes;
  buildReport(context: SyncContext): unknown;
  buildSync(context: SyncContext): unknown;
  parseCommands(response: unknown): ProviderCommand[];
  buildAck(command: ProviderCommand, result: CommandResult): unknown;

  listProjects?(): Promise<BackendProject[]>;
}

HTTP provider 统一负责请求、鉴权、超时、重试、并发控制和错误隔离;adapter 将各后端响应转换成统一的 ProviderCommand

ClawPro 协议中的 local_agent_id 可以继续作为 wire-format 字段保留,但本地模块、配置、日志和 CLI 不再使用 local-agent 作为产品/架构名称。

配置建议

每个 provider 必须有唯一名称:

providers:
  - name: core-team
    type: git
    repo: https://github.com/acme/teamai.git
    priority: 100

  - name: shared-skills
    type: git
    repo: https://github.com/acme/shared-skills.git
    priority: 50

  - name: company-clawpro
    type: http
    adapter: clawpro
    endpoint: https://clawpro.example.com/api
    priority: 80

  - name: community-backend
    type: http
    adapter: teamai
    endpoint: https://teamai.example.org/api
    priority: 40

primaryProvider: core-team
  • primaryProviderteamai push 的默认写入目标;
  • 多个 writable provider 且没有 primary 时,应拒绝模糊写入;
  • Token 不写入 YAML,按 provider 名独立存储,例如 ~/.teamai/credentials/company-clawpro
  • 每个 HTTP provider 的 manifest、bindings、plugins 和缓存独立存放:
~/.teamai/providers/http/company-clawpro/
~/.teamai/providers/http/community-backend/

多后端资源归属

多个 provider 不能仅按顺序直接修改工具目录,否则同名资源的更新/卸载会互相覆盖。

建议引入统一 ownership ledger:

resource key = scope + tool + kind + slug

规则:

  1. 同名资源按显式 priority 选择 active provider;
  2. provider 只能修改或移除自己拥有的 manifest 记录;
  3. 删除 active provider 后,自动回退到下一个候选来源;
  4. skills、rules、CLAUDE.md、hooks、MCP、plugins 使用一致的归属策略;
  5. 单个 provider 超时或失败不得阻塞其他 provider。

CLI 建议

teamai provider add git <repo> \
  --name core-team

teamai provider add http <endpoint> \
  --adapter clawpro \
  --name company-clawpro \
  --token xxx

teamai provider add http <endpoint> \
  --adapter teamai \
  --name community

teamai provider list
teamai provider sync
teamai provider remove company-clawpro
teamai provider set-primary core-team

现有命令先保留为兼容别名并给出弃用提示:

  • teamai init --http
  • teamai source add-http
  • teamai source remove-http

新的输出、文档和配置统一使用 HTTP provider / ClawPro adapter,不再称为 HTTP local agent

迁移阶段

  1. 引入 ResourceProvider、capability 和 registry,将现有 Git 行为包装为 git provider,保持行为不变;
  2. local-agent.ts 拆入 providers/http/adapters/clawpro/,迁移命名与状态目录;
  3. 将单后端配置升级为 provider 列表,支持多个 Git/HTTP provider;
  4. 引入 ownership ledger、priority 和 failover;
  5. 废弃 repo.kind: httpadd-http 等特殊分支和旧入口。

验收标准

  • 同一 scope 可同时挂载至少两个 Git provider 和两个 HTTP provider;
  • 一次 hook dispatch 会同步全部启用的 provider,且不会重复执行;
  • 一个 provider 超时/失败不影响其他 provider;
  • 每个 HTTP provider 的 token、项目绑定、manifest、plugin 状态完全隔离;
  • 同名资源按 priority 生效,删除当前来源后可正确回退;
  • 删除一个 provider 不会卸载或破坏其他 provider 的资源;
  • push 明确使用 primaryProvider 或显式 --provider
  • 旧的 ~/.teamai/local-agent/repo.kind: http 和现有命令可以平滑迁移;
  • ClawPro 代码集中在独立 adapter 目录,通用层不包含 if (adapter === 'clawpro') 分支;
  • #341 中的开源后端可以通过实现新的 HTTP adapter 或兼容统一协议接入。

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.