嵌入式产品软件往往由数十个 Git 仓库组成：内核、BSP、应用、文档、预编译产物……如何让它们整体可构建、可维护、好上手？这套实践采用 West manifest + monorepo 架构 统一管理，manifest 仓库只放"怎么组合"的元信息，不含业务代码。

一、West Manifest 作为"缝合器"

核心思想

West 的价值不在于构建，而在于把分散的 Git 仓库缝合成一个可整体操作的工作区。manifest 仓库不包含业务代码，只包含"怎么组合"的元信息。

实践要点

• 一个 west.yml = 一种产品变体：不同配置独立 yml 文件，不堆在一个文件里加条件判断
• project 命名带前缀（如 <soc>-kernel、<soc>-scripts）：一眼看出项目归属，防止多项目混用时冲突
• 路径扁平化：path: kernel 而非 path: chips/<soc>/kernel，减少 cd 层级
• 按领域组织 project 列表：核心系统 / BSP / 文档 / 应用 / Prebuilts / External，每个只做一件事

目录结构

manifest/
├── linux_full_west.yml       # Linux 完整版组合
├── rtos_rtthread_west.yml    # RT-Thread 精简版组合
├── docs/                      # 所有开发文档
├── skills/                    # 团队共享的 AI Skills
└── README.md                  # 快速开始

适用场景判断

二、代码组合（Combo）的组织方式

目录约定

每个代码组合在 manifest 仓库中独占一个子目录，自包含，不依赖外部约定：

manifest/
├── <combo-name>/
│   ├── west.yml              # 清单文件
│   ├── README.md             # 该组合的说明
│   └── workspace/            # 需放置到 workspace 根目录的文件
│       ├── CLAUDE.md
│       ├── .claude/
│       ├── .cursor/
│       └── .github/
├── <another-combo>/
│   └── ...
└── skills/                   # 所有组合共享

设计意图

• 一个目录 = 一个独立的环境定义
• workspace/ 子目录承载需要在 workspace 根目录出现的所有文件（Agent 配置、AI 规则等）
• 不同组合的 workspace/ 内容可以不同——每个组合定义自己的 Agent 上下文

三、Workspace 根目录的配置分发

问题

West 将 manifest 仓库克隆到 self.path 子目录（如 .manifest/），AI Agent 默认在 workspace 根目录查找配置——看不到埋在子目录里的文件。

解法：symlink 分发

workspace/                    (开发者工作目录)
├── CLAUDE.md       ──symlink──→  .manifest/workspace/CLAUDE.md
├── .claude/         ──symlink──→  .manifest/workspace/.claude/
├── .cursor/         ──symlink──→  .manifest/workspace/.cursor/
├── west.yml                    (west init 生成)
└── .manifest/                  (manifest 仓库本体)

通过 setup.sh 脚本在 west update 后自动创建符号链接。

多 Agent 适配

所有文件的核心信息一致，只是格式适配各 Agent 的要求。

四、统一构建入口：West 扩展

原则

无论底层构建系统是什么，对开发者暴露的命令统一为 west <verb>。不应要求开发者"cd 到子目录再执行构建"。

实现

# 在 manifest 中引用扩展
- name: <soc>-scripts
  path: scripts
  west-commands: west-commands.yml

提供统一命令：

好处

• 对开发者：操作习惯统一
• 对 AI Agent：只需理解 west build 一个入口
• 对 CI：构建命令可复用

五、集中式 Skills 管理

团队共用的 AI Agent Skills 集中放在 manifest 仓库的 skills/ 目录，通过符号链接安装到各成员的本地 Agent 配置目录。

目录结构

skills/
├── README.md
└── <skill-name>/
    ├── SKILL.md                # Skill 定义
    └── reference/              # 参考文档
        └── <补充文档>.md

亮点：分层文档结构

以 git-commit skill 为例：

• SKILL.md：通用的 git commit 规范（commit 格式、Assisted-by 标注、确认流程）
• reference/west-project-commit.md：项目专用的补充（manifest-rev 分支、开发分支策略）

基础 skill + 项目专用补充 的分层结构，复用性强。

安装方式

# 全局安装（所有项目可用）
ln -s <manifest-path>/skills/* ~/.claude/skills/

# 项目级安装
mkdir -p .claude/skills
ln -s ../../skills/* .claude/skills/

六、Git Commit 规范要点

参考 Linux Kernel AI 协作规范：

• 人类全权负责：只有人类能加 Signed-off-by

• AI 参与标注：使用 Assisted-by 标签

  Assisted-by: Claude Code v2.1.114:<model-name>
  

• West 注意事项：manifest-rev 分支由 west 自动管理，不要在上面开发或推送

七、这套设计解决的问题

参考

• West 官方文档：West (Zephyr’s meta-tool)