git-a2a

git-a2a

将 Git 组件与负责它的 Agent 关联起来。

git-a2a 是一款跨平台组件依赖管理器。组件仓库会发布代码、一个指向其所有者的 A2A Agent Card 引用，以及可选的可读内容，例如 API 文档、示例或源代码。使用方通过其自身平台的适配器关联代码，并记录确切的提交、适配器和包管理器变体。

git-a2a 不会发送消息、管理任务、运行 Agent 或托管 Agent Card。请将 git a2a whose NAME 显示的可用 Agent Card 引用用于外部 A2A 客户端：这是一个 HTTPS URL，或来自已应用提交的仓库相对路径卡片的本地副本。

快速开始

直接运行二进制文件 git-a2a，或将其安装到 PATH 并使用 Git 的等效形式 git a2a：

git a2a init
git a2a add https://github.com/acme/lib-utils.git --name lib-utils
git a2a list
git a2a whose lib-utils
git a2a pull lib-utils
git a2a remove lib-utils

2.1.0 版引入了 whose NAME，并移除了 list 的位置参数。使用 list NAME --json 的脚本必须改用 list --json，然后从数组中选取别名。

确切地说，只有六个领域命令：

命令	结果
init	创建一个最简的 schema 2 a2amodule.yml，且不会覆盖现有清单。
add SOURCE	解析一个提交，选择适用的适配器，关联组件，并记录其所有者和可读内容。
pull [NAME]	通过 add 选择的适配器和变体更新一个或所有依赖项；如果没有依赖项，则报告 No dependencies. 并成功退出，不进行任何修改。
remove NAME	仅移除所选依赖项所拥有的集成和本地物化内容。
list	报告每个直接依赖项、提交、适配器、Agent Card、可读内容和本地问题；--json 返回现有数组格式。
whose NAME	报告一个依赖项的负责 Agent、可用 Agent Card 引用、可选的本地可读内容，以及可恢复的元数据问题；--json 返回一个对象。

pull 是适配器生命周期操作，并非 git pull 的封装。多语言组件的所有绑定都使用同一个已解析提交。适配器和管理器的选择会持久保存：后续 PATH 或使用方标记文件的变化不会悄然改变这些选择。

端到端演示

ACME 应用演练展示了完整流程：关联组件、发现负责该组件的 Agent、通过 A2A 发送请求、由所有者修改库、运行 git-a2a pull，并查看新结果。应用仓库和库仓库必须克隆到彼此相邻的位置。唯一的运行时要求是 Docker 和 Compose：

git clone https://github.com/neprel/git-a2a-demo-acme-lib.git
git clone https://github.com/neprel/git-a2a-demo-acme-app.git
cd git-a2a-demo-acme-app
./demo/run.sh

# Short npm-only profile
DEMO_PROFILE=npm ./demo/run.sh

该演示使用无需 LLM API 密钥的确定性 Agent、真实的 A2A 传输、已发布的 git-a2a 2.0.0，以及临时本地 Git 远程仓库。独立的演示客户端负责 A2A 通信；git-a2a 管理依赖代码和元数据。这些 Agent 仅在本地运行期间存在，并非永久可用的公共服务。完整配置的演示结果已记录在验证记录中。

组件契约

a2amodule.yml 使用架构 2：

schema: 2
component:
  id: lib-utils
  description: Shared parsing and validation utilities.
  repository: https://github.com/acme/lib-utils.git
  exports:
    - adapter: npm
      name: "@acme/lib-utils"
    - adapter: pypi
      name: acme-lib-utils
  surface: docs/public
agent:
  name: lib-utils-owner
  card: https://agents.acme.example/lib-utils/.well-known/agent-card.json

Agent Card 仍是 Agent 接口、技能和身份验证的权威来源。 清单不会刻意重复这些内容。init 可以创建不完整的本地清单，其中没有 agent；由 add 或 pull 使用的仓库必须声明 agent.card。

可选的 component.surface 是来自同一已应用提交的已发布数据，并会在 .git-a2a/surfaces/NAME 下生成。如果未声明 surface，则不会隐式发布任何仓库内容。Surface 不是安装机制，也不是子模块。

请参阅清单参考、编写指南、使用指南和架构 1 迁移指南。

适配器矩阵

保留所有现有的平台集成。原生适配器通过平台自身的管理器应用依赖项，并更新声明、原生锁定文件以及已安装或已解析的状态；构建系统适配器通过一次子模块检出进行组合，而不是将源代码复制到第二棵目录树中。

模式	适配器
原生 Git 依赖项	npm（npm、Yarn、pnpm、Bun）、Python（uv、Poetry、PDM、PEP 621/pip）、Go、Cargo、SwiftPM、Pub、Bundler、Composer、Mix、Cabal/Stack、Zig、Clojure、Nix
子模块 + 构建集成	CMake、Gradle、MSBuild、Maven、Meson
仅子模块	无适用集成，或原生管理器无法表示该源时的回退方式

Git 子模块是普通适配器，具有相同的 add/pull/remove/inspect 生命周期。原生锁定文件仍由各自的包管理器负责。详细矩阵和适用范围请参阅支持情况。

安装

保留以下现有安装渠道。命令会跟踪最新稳定版本；请在 CI 中固定版本。

渠道	命令
Go	go install github.com/neprel/git-a2a/v2/cmd/git-a2a@latest
Go 零安装	go run github.com/neprel/git-a2a/v2/cmd/git-a2a@latest --version
macOS/Linux 安装程序	curl -fsSL https://git-a2a.com/install.sh | bash
Windows 安装程序	irm https://git-a2a.com/install.ps1 | iex
Homebrew	brew install neprel/tap/git-a2a
Scoop	scoop bucket add git-a2a https://github.com/neprel/scoop-bucket; scoop install git-a2a
npm	npx git-a2a@latest --version
使用 uv 安装 PyPI 包	uvx git-a2a --version
使用 pipx 安装 PyPI 包	pipx run git-a2a --version
容器	docker run --pull=always --rm ghcr.io/neprel/git-a2a:latest --version
Nix flake	nix run github:neprel/git-a2a -- --version

Linux .deb、.rpm 和 .apk 包附在 GitHub Releases 中。发行档案涵盖 amd64/arm64 架构的 Darwin、Linux 和 Windows，并包含校验和与 SBOM。独立安装程序会验证校验和，并支持固定版本、选择目标位置和试运行。 通过包管理器安装的内容由相应包管理器更新；该二进制没有自更新器。

维护者和来源信息请参阅发行指南。

文档

• CLI 参考
• 清单参考
• 编写组件
• 使用组件
• Agent 和外部 A2A 客户端
• 支持的适配器
• 从架构 1 迁移
• 常见问题
• 发行与安装维护

便携式 Agent Skill 会教编码 Agent 使用这套包含六条命令的工作流。它不会配置 MCP 服务或 Agent 框架。

以规范为准

仓库决策和不变量保存在其所约束的制品旁边的 .hint 文件中。 hint <path> 会返回约束某个路径的知识，hint check <path...> 会验证关联的研究记录。仓库和 CI 使用 HINT 2.0.1。有关工具和格式，请参阅 HINT。

许可证：MIT。