1. 项目概述AI Workspace 是什么以及它解决了什么痛点如果你和你的团队已经开始在日常开发中大量使用 Cursor、Claude Code、GitHub Copilot 这类 AI 编程工具那你大概率已经遇到了一个非常具体且恼人的问题上下文割裂。想象一下你正在一个前端项目里让 AI 帮你写一个调用后端 API 的函数。AI 会基于它当前“看到”的这个前端仓库的代码来生成但它完全不知道后端 API 的准确路径、请求参数格式、错误码定义甚至不知道团队内部约定的命名规范。结果就是它要么“幻觉”出一个不存在的接口要么生成一个不符合规范的函数签名你拿到代码后还得花时间去查文档、问同事甚至手动调试。这就是a-tokyo/aiworkspace这个项目要解决的核心问题。它不是一个全新的 AI 工具而是一个团队级的 AI 工具配置与技能管理平台。你可以把它理解为一个“中央情报局”专门为你的 AI 编程助手们服务。它的核心思想是创建一个独立的、版本化的workspace仓库作为整个团队所有 AI 配置、指令和共享技能的“单一事实来源”。这个workspace仓库里你可以定义全局指令比如“所有 TypeScript 项目必须使用interface而非type定义对象类型”或者“所有 API 调用必须使用我们内部的httpClient封装”。共享技能比如一个“生成符合 OpenAPI 规范的 API Client”的技能或者一个“自动为组件添加 Storybook 故事”的技能。工具配置比如 Cursor 的自定义规则、Claude Code 的偏好设置等。然后通过一个简单的npm install这个workspace仓库里的所有配置和技能都会以符号链接的方式“分发”到你的多仓库工作区monorepo 或 polyrepo的每一个子项目中。这样一来无论 AI 助手在哪个项目里工作它都能“看到”并遵循这些统一的、共享的上下文和规则。这解决了两个关键痛点上下文孤岛AI 不再局限于单个仓库的视野拥有了跨项目的“全局视角”。配置漂移避免了每个开发者、每个项目都有一套自己的 AI 配置和技能导致团队协作时标准不一、效率低下。简单说aiworkspace的目标是让团队的 AI 助手们从“单兵作战”升级为“协同作战”让 AI 生成的代码从一开始就更准确、更一致、更符合团队规范。2. 核心设计思路与架构解析2.1 设计哲学基于“最近优先”的配置继承体系aiworkspace的设计非常聪明它没有采用“一刀切”的强制全局配置而是实现了一个灵活的、基于路径的配置继承与覆盖体系官方称之为“nearest-wins”最近者胜出。这是什么意思呢我们来看一个典型的目录结构~/dev/my-company/ ├── workspace/ # 中央配置仓库 │ ├── root-config/ │ │ ├── AGENTS.md # 全局指令 │ │ └── .agents/skills/ # 全局技能 │ └── package.json ├── frontend-app/ # 项目A │ └── .agents/skills/ # 项目A特定技能 (符号链接自 workspace) ├── backend-service/ # 项目B │ ├── AGENTS.md # 项目B特定指令 (覆盖全局) │ └── .agents/skills/ # 项目B特定技能 └── shared-lib/ # 项目C工作流程如下当你在frontend-app目录下使用 Cursor 时AI 会首先读取frontend-app/.agents/skills/下的技能如果有。如果没找到它会向上查找最终找到并应用workspace/root-config/.agents/skills/下的全局技能。对于AGENTS.md指令文件如果backend-service目录下有自己的AGENTS.md那么它将完全覆盖workspace/root-config/AGENTS.md中的全局指令。如果shared-lib目录下没有则继承全局指令。这种设计带来了巨大的灵活性团队一致性通过根目录的全局配置确保所有项目的基础规则和核心技能一致。项目特异性允许每个项目根据自身技术栈React vs. VueNode.js vs. Go或业务逻辑定义自己独有的 AI 指令和技能覆盖全局设置。清晰的责任边界全局配置由团队技术负责人或架构师维护项目特定配置由项目负责人维护互不干扰。实操心得在实际团队中我建议将workspace/root-config/AGENTS.md定义为团队的“开发宪法”只写入最通用、最基础的原则如代码风格、安全规范。而项目级的AGENTS.md则用于描述具体的业务逻辑、架构约束和领域知识。这样既能保证底线又不失灵活性。2.2 技术实现符号链接与 Git 钩子的巧妙结合aiworkspace的实现非常轻巧主要依赖两个核心机制符号链接和Git 钩子。1. 符号链接实现配置分发运行npm install后aiworkspace的安装脚本会执行一个关键操作遍历workspace/root-config/目录下的所有配置文件夹如.agents/skills/,.cursor/rules/并在工作区根目录~/dev/my-company/以及每一个子项目目录下创建指向这些中央配置目录的符号链接。例如# 在 ~/dev/my-company/ 目录下 ls -la .agents lrwxr-xr-x 1 user staff 67B Apr 10 10:00 skills - workspace/root-config/.agents/skills # 在 ~/dev/my-company/frontend-app/ 目录下 ls -la .agents lrwxr-xr-x 1 user staff 67B Apr 10 10:00 skills - ../workspace/root-config/.agents/skills这样做的好处是零拷贝所有项目共享同一份物理文件节省磁盘空间。实时同步在workspace仓库中更新一个技能所有链接了它的项目会立即“看到”更新。工具无感对于 Cursor、Claude Code 等 AI 工具来说它们只是读取了一个普通的本地目录完全感知不到符号链接的存在兼容性极佳。2. Git 钩子保障配置同步符号链接解决了“读”的问题但“写”呢如果一个开发者直接在项目目录下修改了符号链接指向的技能文件会发生什么他实际上修改的是workspace仓库里的源文件。这可能会带来两个问题一是修改可能不符合规范二是其他开发者可能在他提交前就拉取了旧的配置。aiworkspace通过安装 Git 钩子主要是pre-commit来优雅地解决这个问题。这个钩子的核心逻辑是检查所有即将提交的、位于符号链接路径下的文件变更。自动将这些变更“移动”回它们在workspace仓库中的原始位置。确保变更被提交到正确的仓库即workspace仓库从而保证配置的版本化管理在源头进行。注意事项这个机制要求团队所有成员在克隆workspace仓库后都必须运行npm install以安装钩子。如果有人在没有钩子的环境下直接修改并提交了workspace里的文件虽然不会出错但破坏了通过项目目录进行修改的流畅体验。因此在团队 onboarding 文档中必须强调这一步。2.3 技能管理基于锁文件的依赖管理技能是aiworkspace的核心资产。一个技能本质上是一组文件通常是提示词模板、代码片段、配置文件告诉 AI 如何执行一个特定任务。aiworkspace借鉴了现代包管理器如 npm、yarn的思想为技能引入了注册表和锁文件的概念。技能注册表一个集中的、可搜索的技能仓库。你可以通过npm run skills:find来搜索社区共享的技能。技能锁文件(skills-lock.json)这个文件记录了当前工作区安装的所有技能的确切来源Git URL 或注册表名称和内容哈希值。它的作用与package-lock.json类似确定性安装无论何时何地运行npm install都能根据锁文件还原出完全相同的技能文件集合避免了“在我机器上是好的”这类问题。版本控制技能的变更会被记录在锁文件中方便代码审查和回滚。技能可以安装在两个层级工作区全局使用npm run skills:add -- axios-client-generator。该技能会被安装到workspace/root-config/.agents/skills/并添加到全局锁文件对所有项目生效。项目特定使用npm run skills:add -- storybook-react-stub --project frontend-app。该技能仅被安装到frontend-app/.agents/skills/通过符号链接实现并记录在项目级的锁文件中只对该项目生效。这种设计让技能的管理变得模块化和可复用极大地提升了 AI 助手的“工具箱”丰富度。3. 从零开始团队工作区的搭建与初始化实操3.1 环境准备与前置条件在开始之前请确保团队满足以下基础要求Node.js版本 18。这是运行aiworkspace管理脚本的最低要求。Git用于版本控制。团队需要有一个可以托管workspace仓库的 Git 服务如 GitHub, GitLab, Gitee。统一的父目录建议团队约定一个共同的父目录来存放所有项目代码和workspace。例如~/dev/company-name/。这能确保符号链接路径的一致性。3.2 初始化中央工作区仓库团队负责人操作这一步通常由团队的技术负责人或最早引入此工具的开发者执行。步骤 1创建父目录并初始化工作区# 1. 创建并进入团队统一的代码目录 mkdir -p ~/dev/my-awesome-team cd ~/dev/my-awesome-team # 2. 使用 npx 初始化 aiworkspace # 这会在当前目录下创建一个名为 workspace 的文件夹 npx aiworkspace init执行init命令后你会看到workspace目录被创建里面包含了预设的目录结构、package.json和初始脚本。步骤 2关联远程仓库并推送# 进入 workspace 目录 cd workspace # 在 GitHub/GitLab 上创建一个新的空仓库例如 my-awesome-team/ai-workspace # 然后将其添加为远程仓库并推送代码 git remote add origin https://github.com/my-awesome-team/ai-workspace.git git add . git commit -m feat: initial aiworkspace setup git push -u origin main至此团队的“AI 配置中枢”就已经建立并托管到了远程可供其他成员克隆。步骤 3定制你的全局配置关键步骤初始化后的workspace目录结构是空的你需要填充它。最核心的是root-config/目录。# 进入配置目录 cd root-config # 1. 编辑全局 AI 指令文件 # 这是最重要的文件AI 会优先读取它。内容应该是 Markdown 格式。 echo # 全局 AI 助手指令 ## 代码风格 - 使用 TypeScript严格模式。 - 函数和变量使用 camelCase类名使用 PascalCase。 - 使用 async/await 处理异步避免 .then()。 - 导出使用命名导出Named Exports。 ## 安全规范 - 禁止将敏感信息API Keys密码硬编码在代码中。 - 所有用户输入必须经过验证和清理。 - 数据库查询使用参数化查询或 ORM防止 SQL 注入。 ## 通用约定 - 每个新文件顶部需要有文件头注释说明模块职责。 - 错误处理使用 try-catch并记录到日志系统。 - ...根据团队情况补充 AGENTS.md # 2. 创建技能和规则目录 mkdir -p .agents/skills mkdir -p .cursor/rules # 3. 可以开始添加一些初始技能 cd .. # 回到 workspace 根目录 # 例如添加一个用于生成 REST API 客户端代码的技能假设存在 npm run skills:add -- rest-api-client-generator完成初步配置后记得提交并推送更改git add root-config/ git commit -m feat: add initial global agents.md and skills git push3.3 团队成员接入工作区其他团队成员在加入已有工作区时流程非常简单。步骤 1克隆工作区仓库# 进入团队约定的统一父目录 cd ~/dev/my-awesome-team # 克隆中央工作区仓库 git clone https://github.com/my-awesome-team/ai-workspace.git workspace步骤 2安装依赖与同步配置# 进入 workspace 目录并安装 cd workspace npm install这个npm install是关键。它会安装aiworkspace包本身作为 devDependency。根据skills-lock.json恢复所有已记录的技能。运行安装后脚本将root-config/下的配置符号链接到父目录 (~/dev/my-awesome-team/) 以及所有现有的同级子项目目录下。安装 Git 钩子确保后续对技能/配置的修改能正确提交回workspace仓库。步骤 3验证安装安装完成后可以在父目录下检查符号链接是否创建成功# 在 ~/dev/my-awesome-team/ 目录下 ls -la .cursor # 应该能看到 rules - workspace/root-config/.cursor/rules 这样的符号链接现在当你在~/dev/my-awesome-team/frontend-app/项目中打开 Cursor 时它就能自动加载来自workspace的全局规则和技能了。实操心得对于已经存在大量项目的团队首次运行npm install后可能需要手动为每个已有项目创建指向父目录配置的符号链接或者写一个简单的脚本批量创建。aiworkspace的安装脚本通常只处理workspace的同级目录。确保你的项目目录都在~/dev/my-awesome-team/下面。4. 核心功能深度使用指南4.1 技能的全生命周期管理技能是提升 AI 效率的利器。aiworkspace提供了一套完整的命令行工具来管理它们。1. 技能的搜索与发现在添加技能前可以先在社区注册表中搜索npm run skills:find -- keyword # 例如npm run skills:find -- react这会列出所有名称或描述中包含 “react” 的公共技能。2. 技能的安装与层级安装技能时必须明确其作用范围。# 安装一个全局技能所有项目可用 npm run skills:add -- unit-test-generator # 安装一个仅针对特定项目的技能 npm run skills:add -- vue3-composition-api-helper --project frontend-vue-app全局技能安装在workspace/root-config/.agents/skills/记录在根skills-lock.json。项目技能会在目标项目目录下创建.agents/skills/目录如果需要并在该目录下创建指向workspace内某个位置的符号链接。同时会在项目根目录生成一个skills-lock.json文件来记录此项目特有的技能。3. 技能的创建与开发除了使用社区技能团队完全可以创建自己的私有技能。# 创建一个技能脚手架 npm run skills:create -- --name my-team-eslint-rule-fixer # 这会在 workspace/root-config/.agents/skills/ 下创建 my-team-eslint-rule-fixer/ 目录 # 目录内通常包含 # - README.md: 技能描述和使用方法 # - prompt.md: 给 AI 的核心提示词 # - example-input.md / example-output.md: 输入输出示例 # - config.json: 技能的元数据作者、版本等创建后你需要精心编写prompt.md。一个好的技能提示词应该目标明确清晰定义技能要完成的任务。上下文清晰提供必要的背景信息如项目技术栈、相关文件路径。格式规范明确指定输出格式如代码块、JSON、Markdown 列表。示例驱动通过example-input.md和example-output.md提供高质量范例这是 AI 学习的关键。4. 技能的更新与维护# 列出所有已安装技能及其状态 npm run skills:list # 检查所有技能是否有可用更新 npm run skills:check # 更新所有技能到最新版本 npm run skills:update # 移除一个技能 npm run skills:remove -- unit-test-generator # 或移除项目特定技能 npm run skills:remove -- vue3-helper --project frontend-vue-app注意事项更新技能尤其是全局技能可能会影响所有项目。建议在非关键时期进行并在更新后通知团队成员。对于关键技能可以考虑在skills-lock.json中锁定特定版本如果技能源支持版本化。4.2 编写高效的 AGENTS.md 指令文件AGENTS.md是直接与 AI 对话的“章程”。它的质量直接决定了 AI 输出的代码是否符合预期。结构建议# [项目/团队名称] AI 开发助手指令 ## 项目概述 - **项目类型**React SPA 前端应用 - **核心栈**TypeScript, React 18, Vite, Tailwind CSS, Zustand - **代码仓库**https://github.com/team/frontend - **核心目标**构建高性能、可访问的管理后台。 ## 绝对规则Must 1. 所有组件必须使用函数式组件和 React Hooks。 2. API 调用必须使用 src/lib/api-client.ts 封装的 request 函数。 3. 禁止使用 any 类型必须为所有变量和函数提供明确的 TypeScript 类型或接口。 ## 代码风格与规范Should - 使用 ESLint (Airbnb 配置扩展) 和 Prettier。 - 组件文件结构ComponentName.tsx (主组件), ComponentName.module.css (样式), ComponentName.test.tsx (测试), index.ts (导出)。 - 状态管理局部状态用 useState跨组件共享状态用 Zustand store。 ## 业务逻辑与模式Context - 用户权限模型admin, editor, viewer。相关组件请参考 src/components/RBAC/。 - 表单验证使用 react-hook-form 配合 zod 模式。 - 错误处理网络错误由 api-client 统一弹出通知业务逻辑错误在组件内用 toast.error 显示。 ## 如何寻求帮助When Unsure 如果你不确定如何实现 1. 首先查看 src/components/ 下类似的现有组件。 2. 其次参考 docs/patterns.md 中的设计模式文档。 3. 如果仍不确定请**输出一个清晰的问题列表**而不是猜测的代码。编写技巧分层级从“绝对禁止”到“最佳实践”再到“业务背景”信息优先级分明。具体化避免“写出高质量的代码”这种模糊描述替换为“函数长度不超过 50 行”、“组件 props 必须定义接口”。提供示例对于复杂规则直接给出代码片段示例。保持更新当团队引入新工具或改变模式时及时更新AGENTS.md。4.3 与各类 AI 开发工具的集成实践aiworkspace的通用设计使其能与几乎所有基于文件系统读取配置的 AI 工具集成。1. 与 Cursor 深度集成Cursor 的 Rules 功能是其核心。你可以将团队规则集中管理。# 在 workspace/root-config/ 下创建 Cursor 规则目录 mkdir -p .cursor/rules # 创建一个规则文件例如 typescript-strict.md echo # TypeScript 严格模式规则 - 启用 strict: true 编译选项。 - 必须处理可能的 undefined 或 null。 - 使用 as 断言时需要添加 // ts-ignore 注释并说明理由。 .cursor/rules/typescript-strict.md运行npm install后此规则会被符号链接到所有项目的.cursor/rules/下在 Cursor 中自动生效。2. 与 Claude Code / Codex 配合这些工具通常通过读取项目根目录下的特定配置文件如.claude/或自定义提示词文件来获得上下文。你可以将这类配置文件也放在root-config/下通过符号链接共享。# 假设 Claude Code 支持读取 .claude/context.md mkdir -p root-config/.claude echo 项目通用上下文... root-config/.claude/context.md同样通过符号链接每个项目都能共享这份上下文。3. 与其他工具的适配对于任何通过读取本地文件来获取配置或上下文的 AI 工具集成模式都是类似的在该工具的官方文档中找到其配置文件的默认路径和格式。在workspace/root-config/下创建对应的目录和配置文件。aiworkspace的安装脚本会自动将其同步到各项目目录。实操心得不是所有工具的配置都适合全局共享。例如项目的tsconfig.json或vite.config.ts通常是项目特定的。aiworkspace管理的是AI 工具的行为配置而不是项目本身的构建配置。要清晰区分这两者。5. 高级场景、问题排查与团队协作指南5.1 在 Monorepo 与 Polyrepo 混合环境下的部署现实中的团队代码库往往更复杂可能是多个独立仓库Polyrepo和一个或多个单体仓库Monorepo的混合。场景公司有一个主产品是 Monorepo (~/dev/product-monorepo/)同时还有几个独立的工具库或实验性项目放在其他位置。~/dev/ ├── product-monorepo/ # 使用 pnpm workspaces │ ├── apps/web │ ├── apps/admin │ └── packages/ui ├── internal-tools/ # 独立仓库 A ├── legacy-system/ # 独立仓库 B └── ai-workspace/ # 我们的中央配置仓库挑战aiworkspace默认的npm install脚本只在workspace的同级目录创建符号链接。它无法自动处理像product-monorepo内部子包这样的嵌套结构。解决方案自定义安装后脚本。在workspace/scripts/目录下创建自定义脚本例如custom-link.js。在workspace/package.json的scripts.postinstall中调用它。在这个脚本中你可以编写逻辑来遍历复杂的目录结构为需要的地方创建符号链接。// workspace/scripts/custom-link.js const fs require(fs); const path require(path); const { execSync } require(child_process); const workspaceRoot path.resolve(__dirname, ..); const parentRoot path.resolve(workspaceRoot, ..); // 需要链接配置的目标项目路径数组 const targetPaths [ path.join(parentRoot, product-monorepo/apps/web), path.join(parentRoot, product-monorepo/apps/admin), path.join(parentRoot, product-monorepo/packages/ui), path.join(parentRoot, internal-tools), path.join(parentRoot, legacy-system), ]; const configDirs [.agents, .cursor]; // 需要链接的配置目录 targetPaths.forEach(targetPath { if (fs.existsSync(targetPath)) { configDirs.forEach(dir { const sourceDir path.join(workspaceRoot, root-config, dir); const linkPath path.join(targetPath, dir); const relativeSource path.relative(path.dirname(linkPath), sourceDir); try { if (fs.existsSync(linkPath)) { fs.unlinkSync(linkPath); // 移除旧的链接或文件 } fs.symlinkSync(relativeSource, linkPath, dir); console.log(Linked ${dir} to ${targetPath}); } catch (err) { console.error(Failed to link ${dir} to ${targetPath}:, err.message); } }); } });然后在package.json中{ scripts: { postinstall: node scripts/custom-link.js node scripts/setup.js } }这样每次团队成员运行npm install时都会自动为这些指定的复杂路径创建符号链接。5.2 常见问题与排查技巧在实际使用中你可能会遇到以下问题问题 1符号链接创建失败或 AI 工具读取不到配置症状在项目目录下AI 工具如 Cursor没有应用workspace中定义的规则或技能。排查步骤检查符号链接在项目目录下运行ls -la .cursor或.agents。确认rules和skills是否是有效的符号链接显示为-指向workspace目录。如果显示为普通文件夹或链接断开说明安装脚本未正确运行。重新运行同步在workspace目录下执行npm run skills:setup。这个命令会重新创建所有符号链接。检查路径确认项目目录确实是workspace目录的同级目录。如果项目目录层级更深需要参考 5.1 节配置自定义链接脚本。检查工具配置有些 AI 工具可能需要重启或刷新配置缓存才能识别新的符号链接。尝试重启你的编辑器或 AI 工具插件。问题 2Git 钩子未生效修改技能后提交到了错误仓库症状在项目目录下修改了一个技能文件git status显示变更在项目仓库而不是workspace仓库。原因最可能的原因是workspace目录下的 Git 钩子没有正确安装或没有执行权限。解决进入workspace/.git/hooks/目录检查是否存在pre-commit文件并且其内容包含处理符号链接的逻辑。如果没有在workspace目录下重新运行npm install。如果有检查其是否有可执行权限chmod x .git/hooks/pre-commit。也可以手动运行npm run skills:setup它通常会重新安装钩子。问题 3技能安装或更新失败症状运行npm run skills:add或npm run skills:update时出现网络错误或哈希校验失败。排查网络问题技能可能托管在 GitHub 等平台检查网络连接和代理设置。锁文件冲突如果多人同时修改skills-lock.json可能导致合并冲突。解决 Git 冲突后需要运行npm run skills:setup来重新同步物理文件。技能源失效社区技能可能被作者移除或仓库改名。此时需要从skills-lock.json中手动移除该技能条目或寻找替代技能。问题 4性能考虑症状workspace仓库中技能和配置非常多导致npm install时间变长或者 AI 工具启动时加载缓慢。优化建议精简技能定期审查和清理不再使用或效果不佳的技能。项目级隔离将非常庞大或专用的技能设置为项目级技能而非全局技能避免所有项目都加载。使用.gitignore在workspace仓库中确保skills-lock.json被跟踪但技能源文件本身如果是通过 Git 子模块或直接克隆的可以考虑是否纳入版本控制。aiworkspace的锁文件机制保证了可复现性理论上技能源文件可以不进 Git除非你想离线可用。这需要根据团队网络环境权衡。5.3 团队协作流程与最佳实践引入aiworkspace不仅是引入一个工具更是引入一种团队协作规范。1. 权限与职责划分工作区维护者通常由团队 Tech Lead 或架构师担任负责workspace主分支的合并、全局AGENTS.md的更新、核心技能的审核与添加。项目负责人负责维护其项目目录下的项目级AGENTS.md和项目特定技能。普通开发者可以提出技能需求、提交技能改进的 Merge Request在项目级添加临时或实验性技能。2. 代码审查流程将workspace仓库视为重要的基础设施代码库。技能变更任何新增、更新或移除技能的 PR都需要审查。审查重点技能提示词的质量、是否与现有技能重复、是否有潜在安全或性能风险。配置变更对root-config/AGENTS.md或全局规则文件的修改需要团队核心成员批准因为会影响所有项目。锁文件更新skills-lock.json的变更应伴随技能变更的 PR 一起提交和审查。3. 持续集成考量可以考虑在 CI 流水线中加入对workspace的检查格式校验确保AGENTS.md符合 Markdown 规范。技能健康检查运行一个脚本尝试加载所有技能确保没有语法错误或损坏的引用。配置同步测试在一个沙箱环境中模拟npm install验证符号链接能否正确创建。4. 培训与推广编写内部文档详细说明aiworkspace的理念、安装步骤、日常操作如何加技能、写指令。举办分享会展示一个从零开始利用共享技能快速完成一个复杂任务的例子例如“如何使用共享的‘数据库迁移生成’技能让 AI 根据 PRD 直接生成 SQL 文件”。建立反馈渠道创建一个频道或标签让团队成员可以分享好用的技能、提出对指令文件的改进建议。我个人在实际推动团队使用这类工具时最大的体会是成功的核心不在于工具本身有多强大而在于是否形成了“配置即代码共享即效率”的团队文化。开始时可能会有些繁琐但一旦团队习惯了在workspace中沉淀和复用 AI 知识整个开发流程的规范性和效率的提升将是显而易见的。从 AI 生成代码的“可用”到“好用”再到“符合团队心智模型的精准”aiworkspace提供了一条切实可行的路径。