refactor: 统一 Git/HTTP resource provider,ClawPro 改为 HTTP adapter
@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
git和http是资源同步机制层的 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
primaryProvider是teamai 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
规则:
- 同名资源按显式
priority选择 active provider; - provider 只能修改或移除自己拥有的 manifest 记录;
- 删除 active provider 后,自动回退到下一个候选来源;
- skills、rules、CLAUDE.md、hooks、MCP、plugins 使用一致的归属策略;
- 单个 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 --httpteamai source add-httpteamai source remove-http
新的输出、文档和配置统一使用 HTTP provider / ClawPro adapter,不再称为 HTTP local agent。
迁移阶段
- 引入
ResourceProvider、capability 和 registry,将现有 Git 行为包装为gitprovider,保持行为不变; - 把
local-agent.ts拆入providers/http/adapters/clawpro/,迁移命名与状态目录; - 将单后端配置升级为 provider 列表,支持多个 Git/HTTP provider;
- 引入 ownership ledger、priority 和 failover;
- 废弃
repo.kind: http、add-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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.