内容
# 马厩
**所有智能代理的统一管理。**
如果你同时使用多种 AI 编码工具——今天的 Claude Code、第二意见的 Codex、服务器上的 OpenCode，或下个月发布的其他工具——你都会遇到多马厩的共同问题：装备数量增加。
技能被复制到四个配置文件目录中，MCP 服务器以四种不同的方式注册，操作说明静默地为每个工具分叉，API 密钥分散在各个配置文件中。
马厩是马厩中存放所有马鞍、马辔和缰绳的地方：一个房间，维护一次，适合任何马。这就是这个仓库——**技能、子代理、斜杠命令、MCP 服务器、操作说明、环境变量和启动器**的单一真实来源，通过一个安装程序和一个医生程序，统一连接到每个智能代理中。
## 方法
1. **标准、工具中立的内容。** 技能存放在 `skills/` 目录中，不包含工具名称或机器路径（`tack lint` 强制执行）。
共享的操作说明存放在 `AGENTS.md` 中。
2. **渲染，而不是分叉。** 工具特定的格式是**生成的**：一个 MCP 注册表 (`mcp/servers.json`) 渲染成 Codex TOML、OMP `mcp.json`、OpenCode 片段和 `claude mcp` 注册命令。你再也不需要手动编辑四个配置文件。
3. **适配器在工具真正不同时使用。** `adapters/<tool>/<skill>/` 覆盖了该工具的标准技能。设计上很少使用。
4. **您的内容的私有覆盖层。** 引擎是公开的；您的技能、项目和凭证存放在第二个私有仓库中，布局相同，在安装时合并——覆盖层优先。`git pull` 上游改进，无需清理您的历史记录。请参阅 [docs/overlay.md](docs/overlay.md)。
5. **封闭的验证循环。** `tack install` 是幂等的，并备份它所替换的任何内容；`tack doctor` 在临时目录中重新派生整个构建并进行差异比较——陈旧链接、缺失的前置条件、跟踪的机密、错误的权限都会使灯变红。Git 钩子在每次拉取后重新安装和验证。
## 设置
前提条件：`bash`、`jq`、`git`、`rg`，以及您使用的任何智能代理。
```bash
git clone https://github.com/staz6/tackroom ~/tackroom
cd ~/tackroom
cp env/.env.example .env && chmod 600 .env # 填写您需要的
./scripts/install.sh all
echo 'source "$HOME/tackroom/shell/bashrc.snippet.sh"' >> ~/.bashrc
```
打开一个新终端并运行 `tack doctor` — 它必须全部显示绿色。
克隆可以放在任何地方；每个路径都是派生的，没有硬编码。
## 每日使用
| 命令 | 功能 |
|---|---|
| `tack install [tool\|all]` | 装配 + 连接所有内容（幂等） |
| `tack doctor` | 验证链接、技能、环境卫生、构建新鲜度 |
| `tack render` | 编辑注册表后重新渲染 MCP 配置 |
| `tack new-skill [--overlay] <name>` | 搭建技能 |
| `tack lint` / `tack catalog` | 校验技能 / 重新生成下面的目录 |
| `tack overlay [<path>]` | 显示或设置您的私有覆盖层 |
| `project id\|info\|env\|list` | 从当前工作目录解析项目上下文 |
| `advised claude\|codex ["task"]` | 监督工作 TUI — 另一个模型家族提供建议 |
| `advisor --to claude\|codex "<packet>"` | 向另一个模型请求只读裁决 |
## 支持的智能代理
| 工具 | 技能 | 说明 | MCP |
|---|---|---|---|
| **Claude Code** | `~/.claude/skills` → 构建农场 | `~/.claude/CLAUDE.md` | `claude mcp` 用户范围，自动注册 |
| **Codex** | `~/.codex/skills` 中的每个技能链接 | `~/.codex/AGENTS.md` | `config.toml` 中的托管块 |
| **Oh My Pi** | 每个技能链接，适配器感知 | `~/.omp/agent/AGENTS.md` | 渲染的 `mcp.json` |
| **OpenCode** | 通过 Claude 兼容路径 | `~/.config/opencode/AGENTS.md` | 渲染片段，手动合并 |
添加一个智能代理是一个自包含的插件 — 两个小脚本，无需核心更改。请参阅 [docs/adding-a-tool.md](docs/adding-a-tool.md)。
## 顾问工作流程
一个模型完成工作；另一个模型家族的模型在它后面具有**只读**的仓库访问权限，在定义的检查点（方向 → 计划 → 最终）处判断方向并以固定格式回答：
`VERDICT: CONTINUE | ADJUST | STOP`，以及风险和具体指导。
跨家族配对是关键 — 不同的训练打破了共享的盲点。
使用 `advised claude` 或 `advised codex` 启动监督会话，或在任何会话中手动检查 `advisor --to claude|codex "<packet>"`。顾问在您的仓库中无头运行 — 为 codex 提供沙盒只读权限，为 claude 提供只读工具允许列表 — 每次裁决都被追加到 gitignored 审计日志中。使用 `.env` 中的 `ADVISOR_*` 变量固定顾问模型；未设置意味着每个 CLI 的默认模型。协议：
[skills/advisor/SKILL.md](skills/advisor/SKILL.md)。
## 如何添加技能
1. `tack new-skill <name>` （添加 `--overlay` 以获取私有技能）— 创建 `skills/<name>/SKILL.md`，包含前置条件：`name:` 加上一个触发器导向的 `description:` （何时使用，而不是是什么）。
2. 编写方法为带明确退出条件的编号步骤。工具中立：无 TUI 名称，无机器路径 — `tack lint` 强制执行。
3. 在拉取后在其他机器上运行 `tack install` = 所有地方都已完成。
## 如何更改 MCP 服务器
1. 编辑 `mcp/servers.json` （或您的覆盖层的副本 — 相同的形状，深合并，覆盖层优先）。每个服务器都指定哪些工具接收它。
2. `tack install` — 将每个工具的原生格式渲染到 `build/mcp/` 并应用。永远不要编辑渲染后的输出。
对于需要 API 密钥的标准服务器，请将 `command` 指向一个包装脚本，该脚本在启动时读取 gitignored 根目录 `.env` ([mcp/bin/example-wrapper.sh](mcp/bin/example-wrapper.sh)) — 密钥从未出现在渲染的配置文件中，也无需全局导出 shell。
## 项目
`projects/registry.json` 将目录映射到项目；每个项目都有一个 `PROJECT.md` 上下文卡（堆栈、不变性、验证命令），代理在工作开始时通过 `project info` 加载，gitignored 环境配置文件通过 `source "$(project env dev)"` 加载。您的实际注册表位于您的覆盖层中。
## 安全立场
- 机密：一个 gitignored `.env` （chmod 600，由 `env/.env.example` 记录），每个项目的配置文件 gitignored，gitleaks + shellcheck + 技能 lint 在 CI 中，医生检查权限和跟踪的文件泄漏每次运行。
- `.env` 默认情况下**不**导出到每个 shell 中 — 包装脚本在启动时读取它。如果您想要全局环境，请设置 `TACK_EXPORT_ENV=1`。
- 默认情况下，权限提示保持**开启**。如果您接受无审批提示运行智能代理的权衡，`TACK_YOLO=1` 添加跳过权限别名 — 在设置之前请阅读该标志的作用。
## 技能目录
引擎带有小型工具中立的核心：工程操作方式（`principles*`）、仅计划工件（`plan`）、独立审查（`second-opinion` + `file-map`）和项目上下文（`project-context`）。您自己的技能放在覆盖层中 — 或完全替换它们。
<!-- CATALOG:START -->
- **`advisor`** — 用于规划和审查的两模型顾问工作流程 — 当前模型完成大部分工作，而来自不同家族的模型在后面具有只读仓库访问权限，在定义的检查点处判断方向并在需要时提供指导。
- **`file-map`** — 构建一个紧凑的文件映射上下文数据包 — 一个目录树，带有标记的相关文件、目标代码摘录、技术栈和说明 — 以便外部模型可以从单个附加文件中审查仓库工作。
- **`plan`** — 当用户想要将功能映射到确切的文件更改时，创建仅计划实现工件，而不编辑源树。
- **`principles-implement`** — 在编写或修改代码时使用。
- **`principles-plan`** — 在设计实施、迁移或调查策略之前使用。
- **`principles-review`** — 在审查差异、提交、PR 或设计时使用。
- **`principles-search`** — 在定位任何内容时使用 — 代码、配置、文档或系统行为原因。
- **`principles`** — 工程操作方式 — 原则技能集的索引。
- **`project-context`** — 解析当前目录属于哪个项目，并加载其上下文卡和环境凭证。
- **`second-opinion`** — 在最终确定之前，对候选答案、计划、补丁、诊断或审查提供独立的高推理审查。
<!-- CATALOG:END -->
## 许可证
MIT
