企业官网建设流程全解析

TeamAI + Git Submodule技能分发：submodules: true配置完整实战指南

【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli

TeamAI 是一个让团队 AI 原生的 CLI 工具（口号是 Make Every Team AI Native），它可以统一管理团队的 skills、rules、agents、hooks 和 MCP，并自动下发到 Claude Code、Codex、Cursor 等多种 AI 工具。本篇带你掌握一个进阶能力：用Git Submodule 分发技能，只需在teamai.yaml里加一行submodules: true，团队成员每次teamai pull时就会自动按团队仓钉住的版本填充子模块内容，无需任何人手动克隆或初始化。

为什么需要 Git Submodule 技能分发 🤔

默认情况下，团队技能是直接提交在团队知识仓里的。但在这些场景下，"把技能做成独立仓库，再以 submodule 挂进团队仓"更优雅：

• 技能需要独立版本节奏：某个技能由专人维护、单独演进，团队仓只负责"钉住"它的版本；
• 技能体积较大或含独立依赖，放进主仓会拖慢日常同步；
• 多个团队仓想共享同一份技能包，submodule 指向同一个技能仓即可，天然去重。

开启submodules: true后，TeamAI 会在每次teamai pull时自动执行git submodule update --init，把子模块检出到团队仓钉住的那个精确 commit 上——版本一致性由 Git 本身保证，团队成员之间永远不会出现"我这边技能是新的、你那边是旧的"。

3 步开启 submodules: true 配置 🚀

第 1 步：在团队仓添加技能 submodule

假设你已经有一个独立维护的技能仓（内含标准的SKILL.md结构），在团队知识仓中执行：

git submodule add <技能仓地址> skills/common git commit -m "add skills submodule" git push

此时skills/common在团队仓里就是一个 submodule 条目，记录了指向技能仓的精确 SHA。

第 2 步：在 teamai.yaml 中开启开关

该配置定义在远端团队配置teamai.yaml中，对应配置 schema 见 src/types.ts（submodules字段，默认关闭）。编辑团队仓根目录的teamai.yaml：

team: my-team description: 团队 AI 资源仓库 provider: git submodules: true # 开启子模块自动填充

提交并合入后，所有成员pull时即生效。

第 3 步：运行 teamai pull 验证

teamai pull

第一次 pull 会把子模块内容完整检出，并部署到各工具的技能目录（例如 Claude 的.claude/skills/）。之后的每次 pull 都会自动保持子模块与团队仓钉住版本一致，无需任何手动操作。

详细说明可参考官方文档的「Git 子模块」一节：docs/usage-guide.zh-CN.md、docs/usage-guide.md

底层机制：为什么它又快又稳 🔍

子模块同步逻辑集中在 src/pull.ts 的refreshTeamRepo中，有三个值得了解的设计细节：

1. 刻意不做浅克隆。子模块钉住的是精确 SHA，而--depth浅取只拉取远端最新提交，检出较旧的 pin 会直接报 "reference is not a tree"。因此 TeamAI 取完整子模块历史，保证任何历史 pin 都能被检出。
2. 失败不污染缓存。如果某次 pull 中子模块更新失败（例如网络或凭据问题），TeamAI 会记录警告并保留旧的同步版本号，下次 pull 会自动重新完整同步并重试，而不会走"版本未变化"的快速路径被跳过。
3. 内容变化也能被感知。子模块更新不会移动父仓的 HEAD，仅靠父仓 rev 做缓存键时可能误判"无变化"而跳过部署。为此 TeamAI 在更新前后对比git submodule status，只要磁盘上的子模块树发生了变化（比如升级 CLI 后首次填充了原本为空的子模块目录），本次 pull 就会强制走完整同步，确保工具目录里一定有内容。这个行为的回归测试见 src/tests/pull-submodule-skip-sync.test.ts。

两个需要注意的边界情况 ⚠️

• 仅 git 仓后端生效：submodules: true只作用于团队仓为 git 后端的安装方式；HTTP 源模式（init --http）没有本地仓库树，不适用。
• 私有子模块的凭据：子模块拉取依赖环境中现成的 git 凭据。如果你的宿主机采用"按命令注入 token"的认证方式（而不是配置 credential helper），私有子模块将无法通过认证——建议为本机配置好 credential helper，或让子模块指向公开仓。

小结

一行配置，换来的是技能分发的版本可控与零手动维护。如果你的团队已经开始用 submodule 管理技能仓库，不妨现在就试试这个开关 🎉

【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli