内容
# AI 工作空间
在多仓库工作空间中管理共享的 AI 代理技能、配置和自动化。适用于 Cursor、Claude Code、Codex、Amp 和 40 多种 AI 编码工具。
<a href="https://npmjs.com/package/aiworkspace">
<img src="https://img.shields.io/npm/v/aiworkspace.svg" alt="npm 版本" />
<img src="https://img.shields.io/npm/dt/aiworkspace.svg" alt="npm 下载量" />
</a>
<a href="https://twitter.com/intent/follow?screen_name=ahmedtokyo"><img src="https://img.shields.io/twitter/follow/ahmedtokyo.svg?label=Follow%20@ahmedtokyo" alt="关注 @ahmedtokyo" /></a>
<br />
**问题**: AI 代理只能看到它们运行的仓库。在前端仓库中工作的代理无法看到后端、API 合同或共享约定，因此它会进行假设和臆测。此外，每个开发人员都以不同的方式配置 AI 工具，因此技能、指令和规则在项目和团队成员之间漂移。
**解决方案**: 一个单独的 `workspace/` 仓库，作为规范的源。运行 `npm install` 会将配置镜像到父根目录，为每个 AI 工具创建技能符号链接，并安装 git 钩子以保持所有内容同步。
## 快速开始
**创建新的工作空间**（一次性，由设置者执行）：
```bash
mkdir ~/dev/<your-org> && cd ~/dev/<your-org>
npx aiworkspace init
cd workspace
git remote add origin <your-repo-url>
git push -u origin main
```
**加入现有工作空间**（其他团队成员）：
```bash
cd ~/dev/<your-org>
git clone <your-teams-workspace-repo> workspace
cd workspace && npm install
```
`npm install` 会从锁定文件中恢复技能，将配置镜像到父根目录，创建技能符号链接，并安装 git 钩子。参见 [setup.md](setup.md) 以获取完整指南，包括 [MCP 密钥](setup.md#41-mcp-secrets)（`cp .env.example .env.local`，重启编辑器）。
## 工作原理
```
~/dev/<your-org>/ <- 在此处打开 Cursor / 编辑器
├── workspace/ <- 此仓库
│ ├── root-config/ <- 根级 AI 配置的规范源
│ │ ├── AGENTS.md <- 所有 AI 工具的永久指令
│ │ ├── .agents/skills/ <- 工作空间范围的技能
│ │ └── skills-lock.json <- 工作空间范围的技能锁定文件
│ ├── .agents/skills/ <- 项目特定的技能
│ ├── scripts/ <- 自动化（设置、钩子、技能包装器）
│ └── package.json
├── <project-a>/ <- 您的应用 / 服务 / 库
├── <project-b>/
└── ...
```
设置脚本会遍历 `root-config/`。添加新的配置类型（Cursor 规则、Claude 设置、Codex 配置），它们会自动同步，无需更改脚本。
## 知识层次
所有内容都遵循 **最近胜出**：文件距离更改的代码越近，其优先级越高。
| 项目 | 工作空间范围 | 项目范围 |
|------|---------------|-------------|
| 指令 | `root-config/AGENTS.md` 同步到根目录 | `<project>/AGENTS.md` |
| 技能 | `root-config/.agents/skills/` 符号链接到所有地方 | `<project>/.agents/skills/` |
| Cursor 规则 | `root-config/.cursor/rules/` 符号链接 | `<project>/.cursor/rules/` |
| 文档 | `docs/` 仓库（兄弟节点） | `<project>/docs/` |
## 技能
```bash
npm run skills:add -- <source> [--project <repo>] # 从注册表添加
npm run skills:add -- owner/repo --skill <name> # 从多技能仓库中选择
npm run skills:remove -- [<skill>] [--project <repo>] # 删除
npm run skills:create -- --name my-skill # 手动创建
npm run skills:list # 列出已安装的
npm run skills:find # 搜索技能注册表
npm run skills:update # 更新所有
npm run skills:check # 检查可用更新
npm run skills:setup # 重新同步配置和符号链接
```
如果没有 `--project`，技能将安装到 `root-config/.agents/skills/`（工作空间范围）。如果有 `--project <repo>`，技能将安装到 `<repo>/.agents/skills/`（项目范围）。
技能在 `skills-lock.json` 中跟踪（源 + 哈希）。在 `npm install` 时，它们会自动从锁定文件中恢复。
## 升级
**模板升级** — 当发布新的 aiworkspace 版本时，拉取最新的托管 `scripts/`：
```bash
npm run upgrade
```
**配置同步** — 编辑 `root-config/`（尤其是 `.agents/mcp.json`）后，在不更新模板的情况下重新生成 MCP 双胞胎和父根符号链接：
```bash
npm run sync
```
如果 `aiworkspace` 在 `devDependencies` 中，`upgrade` 会更新该包并将其 `scripts/` 复制到您的（您团队的 `version` 字段保持独立）。否则，工作空间会回退到 git：`upstream` 远程 + `upstream/main` 用于 `scripts/`。`upgrade` 会自动链接 `sync`。`npx aiworkspace init` 会自动设置 `upstream`。有关详细信息，请参见 [setup.md](setup.md)。
## 需求
- Node.js >= 18
- Git
## 相关资源
[agent-skills](https://github.com/a-tokyo/agent-skills) 是一个配套的 AI 代理技能集合 — 在 [skills.sh](https://www.skills.sh/a-tokyo/agent-skills) 上浏览。可以使用上述相同的 `skills:add` 工作流程安装其中任何一个。
| 技能 | 功能 |
|-------|-------------|
| [production-grade](https://skills.sh/a-tokyo/agent-skills/production-grade) | 非琐碎工作的工程化姿态：编码前规划，尽可能简单的正确解决方案，生产强化模式。 |
| [tribunal](https://skills.sh/a-tokyo/agent-skills/tribunal) | 执行者 → 验证者面板 → 共识循环，以在交付前控制。 |
更多技能集合 — 参见 [完整目录](https://github.com/a-tokyo/agent-skills#skills)。
```bash
npm run skills:add -- a-tokyo/agent-skills --skill production-grade
```
## 许可证
Apache-2.0
MCP 市场