TeamAI 数据分区设计详解~/.teamai/projects/ / 目录全图解【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cliTeamAI 是一款让每个团队都能AI 原生化的开源 CLI 工具统一管理团队的 Skills、Rules、MCP 与知识并同步到 Claude Code、Codex、Cursor 等 AI 代理。它最精巧的设计之一是数据分区机制每个项目的机器本地数据都被隔离存放在~/.teamai/projects/slug/目录下业务仓库保持零残留多项目互不串扰。本文将完整图解这个分区目录的命名规则、内部结构和自动迁移流程。为什么需要数据分区在早期版本中TeamAI 的机器数据直接放在业务仓库内的.teamai/目录里。一个真实项目实测该目录高达18 MB团队仓库克隆 12 MB、技能资源 4.1 MB、搜索索引 1.8 MB由此带来三个痛点痛点说明️ 工作区残留机器数据污染业务仓库的工作树git status难以保持干净️ 子目录/工作树盲区从子目录运行时找不到配置git worktree 中完全没有配置️ 跨项目混杂全局单例路径让多个项目的数据无法区分分区的目标很明确把机器本地数据全部搬到~/.teamai/projects/slug/让业务工作区实现零残留且每个项目独立隔离。完整设计思路可参考 docs/designs/data-directory-layout.md。两个锚点分区的路由基石 一个 git 工作树有两个不同的根TeamAI 同时需要它们锚点含义用途projectAnchor主检出目录git worktree list --porcelain的第一条仓库与其所有 worktree共享的稳定身份分区按它命名workspaceRoot当前检出目录git rev-parse --show-toplevelAI 工具资源skills/rules/agents实际写入的位置对于普通非 worktree仓库两者相等。锚点解析逻辑实现在 src/utils/git.ts 的resolveAnchors()中相关测试见 src/tests/anchors.test.ts。 为什么用主检出而不是git-common-dir因为git init --separate-git-dir会让 common dir 落在仓库之外导致不相关仓库发生命名冲突。worktree list的第一条在所有场景下都给出共享且唯一的身份。分区命名规则人类可读 密码学唯一分区目录名slug由两部分拼成slug 路径安全化前缀-sha256(锚点路径) 前16位十六进制 示例/Users/x/Project/app ↓ Users-x-Project-app-a1b2c3d4e5f6a7b8三个关键设计决策源码src/utils/partition.ts前缀取完整路径—— 目录名可以读回它属于哪个项目类似 Claude Code 的~/.claude/projects/命名风格。尾部 16 位哈希保证唯一性—— 单纯把/转成-不是单射/x/my-proj和/x/my/proj转换后会撞车并静默合并两个项目的明文 env 与配置。64 位哈希让故意构造碰撞远超随手可达范围见projectSlug()与anchorHash()的实现注释。前缀限长 180 字符—— 深路径永远不会溢出文件系统的NAME_MAX截断时保留尾部项目名及其父目录最有辨识度由哈希兜底去重。此外还有两个容易被忽略的细节大小写归一化macOS/Windows 文件系统大小写不敏感/foo/Work/Foo与/foo/work/foo应映射到同一分区。normalizeAnchor()会先探测锚点所在卷而非 HOME 所在卷两者可能不同卷的大小写敏感性再决定是否小写化。anchor反查文件slug 是单向哈希无法逆向还原路径所以每个分区内都写入一个anchor文件记录原始项目路径作为权威反查依据writeAnchorFile()。分区目录全图解里面都有什么初始化或迁移完成后一个典型分区长这样~/.teamai/projects/ └── Users-x-Project-app-a1b2c3d4e5f6a7b8/ ← slug 分区目录 ├── anchor # 原始项目路径权威反查 ├── config.yaml # 项目级配置scope: project ├── state.json # 运行时状态 ├── env.local # 机器本地环境变量备份明文务必忽略提交 ├── env.sh ├── search-index.json # 团队知识搜索索引 ├── managed-mcp.json # MCP 托管清单 ├── team-repo/ # 团队仓库克隆pull/push 的数据源 └── workspaces/ # 按 worktree 划分的资源缓存每个文件的作用一览文件/目录角色anchor记录分区对应的项目主检出路径status --all判定孤儿分区的唯一依据config.yaml该项目的 TeamAI 配置包含团队仓库repo.localPath指向分区内的team-repostate.jsonpull/push 同步状态env.local/env.sh机器本地凭据与环境备份绝不进入业务仓库search-index.json团队知识learnings/技能的本地搜索索引managed-mcp.json由 TeamAI 管理的 MCP 服务器清单team-repo/团队仓库克隆pull读取团队配置与资源workspaces/各 worktree 的 AI 工具资源缓存所有读取这些路径的代码都统一走 src/types.ts 中的getDataHome()——它是机器数据家目录的单一事实来源未来调整存储位置只需改一处。与之并列的还有getKnowledgeDir()团队知识资产与resolveBaseDir()AI 工具资源落点三者正交知识 / 资源落点 / 机器数据。自动迁移老数据如何搬进分区 对分区之前安装的用户数据仍留在workspaceRoot/.teamai/。TeamAI 会在下一条写命令仅init/pull/push时自动完成迁移实现零残留迁移引擎在 src/migrate.ts0. 加锁 legacyDir/.sync-lock未迁移的 pull/push 正竞争这把锁 1. 复制 legacyDir → partition.staging跳过一次性 worktree 与锁文件 2. 校验 stagingconfig.yaml 可解析team-repo/.git 完整逐项齐全 3. 原子切换rename(staging → partition) ← 同文件系统原子操作 4. 写入 partition/anchor权威反查 5. 释放锁退役源目录 a. 先向 legacyDir 写入自包含的 .gitignore*防止明文凭据被 git add b. 重命名为第一个空闲的 .teamai.bak[.N] —— 备份永不自动删除三个值得称道的细节中断可恢复staging 是独立兄弟目录步骤 3 前崩溃 → 重跑丢弃 staging 重来3 与 5 之间崩溃 → 下次命令检测到分区已建、旧目录残留返回retire-only计划只清理残留不再复制。self 模式例外单仓库self模式的.teamai/是提交到 main 的团队知识迁移会按白名单选择性搬迁机器数据config.yaml、state.json、env.local、search-index.json、managed-mcp.json、workspaces/绝不动知识目录。降级不支持旧版 TeamAI 无法识别分区式安装.teamai.bak/是手动回滚路径。旧命名兼容与孤儿清理分区命名曾从仅 basename 升级为完整路径。由于哈希不变老命名可以精确计算出来——resolvePartitionDir()通过原子 rename 原地收养旧分区同一父目录的元数据移动不拷贝数据并同步重写 config.yaml 中指向旧team-repo的绝对路径repo.localPath原子写入防止半截写坏唯一副本。清理废弃分区则靠只读命令teamai status --all它枚举~/.teamai/projects/下每个分区并标记状态active正常/ORPHAN项目路径已消失可安全删除/unknown/corrupt。判定只依据anchor文件——没有 anchor 的分区永远标为 unknown 而非 ORPHAN绝不建议删除无法确认已死的数据。小结这套设计好在哪设计点收益按projectAnchor分区一个仓库的所有 worktree 共享一份数据身份稳定路径前缀 16 位哈希人类可读 数学上杜绝静默碰撞anchor反查文件单向哈希也能精确回到项目路径统一走getDataHome()未来调整存储位置只改一处复制→校验→原子切换任何时刻中断都不会数据半在两边status --all只读命令帮用户安全识别可删除的孤儿分区核心源码索引分区身份与命名src/utils/partition.ts迁移引擎src/migrate.ts数据家目录路由src/types.ts设计文档docs/designs/data-directory-layout.md大小写探测与 slug 测试src/tests/partition.test.ts对于多项目开发、频繁使用 git worktree 的团队来说这套数据分区设计让每个项目的 AI 资产都各归各位——这正是 TeamAI 能让每个团队 AI 原生化的底层保障。【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考