内容
# dotai
克劳德代码和开放代码的全局配置工具。您可以将此仓库克隆到任何地方；它通过符号链接部署到 `~/.claude/` 和 `~/.config/opencode/`。与项目本地配置共存 — 两个工具都 **合并** 全局和本地层（项目在名称冲突时优先）。
## 安装
**首先Fork**（推荐）。该仓库通过AI工具在您的机器上运行代码 - 如果有人获得上游的提交访问权限，您的AI配置就会被泄露，您的AI就会获得shell访问权限。Fork让您掌控：您在每次更改落地前都需要审查，确保不会有意外的更新。与您对待在机器上运行的任何代码的相同规范。
```bash
git clone https://github.com/YOU/dotai.git ~/dotai
cd ~/dotai
just init # 交互式向导（配置文件、语言、MCP）
just install # 部署所有符号链接
just validate # 验证一切是否健康
```
**直接克隆**（如果您正在评估或信任源）：
```bash
git clone https://github.com/rguiu/dotai.git ~/dotai
cd ~/dotai
just init && just install && just validate
```
如果您跳过向导，请直接运行脚本：
```bash
bash scripts/install.sh
bash scripts/uninstall.sh # 删除所有dotai文件
```
需要 [`just`](https://github.com/casey/just) (`brew install just`).
## 命令
```bash
just init # 交互式向导
just install # 部署所有符号链接
just uninstall # 删除所有符号链接
just validate # 健康检查
just status # 显示链接/缺失状态
just direnv-setup # 在父目录中安装共享密钥direnv层
just direnv-project # 启用当前项目通过source_up继承密钥
just smoke-test # 非破坏性套件完整性检查
just token-cost # 估计每个会话的令牌消耗
just marketplace-check # 检查依赖项更新（只读）
just session-save # 捕获当前状态
just session-load foo # 恢复已保存的会话
just mcp-list # 列出可用的MCP服务器
just mcp-status # 显示活动/非活动 + 先决条件
just mcp-add <server> # 添加服务器（检查环境变量）
just mcp-remove <srv> # 删除服务器
```
Tab补全:
```bash
source completions/just.bash # bash 或 zsh
```
## 结构
```
├── skills/dotai/ # 命名空间技能 → 调用为 /dotai:xxx
│ ├── readme-gen/ # /dotai:readme-gen — 从项目扫描生成 README.md
│ ├── pr-review/ # /dotai:pr-review — 从 git diff 生成 PR 描述
│ ├── debug/ # /dotai:debug — 系统调试工作流
│ ├── adr/ # /dotai:adr — 架构决策记录
│ ├── handoff/ # /dotai:handoff — 会话状态捕获用于移交
│ ├── onboard/ # /dotai:onboard — 用图表记录新项目
│ └── doctor/ # /dotai:doctor — 诊断和修复套件问题
├── claude/CLAUDE.md # → ~/.claude/CLAUDE.md （全局规则 — 唯一真实来源）
├── opencode/
│ ├── config.json # → ~/.config/opencode/opencode.json （首选项，权限）
│ │ # ~/.config/opencode/AGENTS.md → claude/CLAUDE.md （共享）
│ └── agents/ # → ~/.config/opencode/agents/ （自定义子代理）
│ ├── reviewer.md # 只读差异审查
│ ├── planner.md # 仅计划 — 设计代理
│ └── test-writer.md # 仅测试代理
├── rules/ # → ~/.config/opencode/rules/ （语言特定规则）
│ ├── python.md
│ ├── rust.md
│ ├── typescript.md
│ └── go.md
├── mcp/
│ ├── claude_desktop_config.json # → ~/Library/Application Support/Claude/ （活动MCP服务器）
│ ├── templates/ # 复制到项目MCP样板
│ └── available/ # 可选MCP服务器（有条件添加）
├── tools/ # → ~/.local/bin/ （令牌效率 + 维护脚本）
│ ├── token-cost # 估计每个会话的令牌消耗
│ ├── bootstrap # 交互式设置向导
│ ├── repo-outline # 代码库的紧凑结构索引
│ ├── strip-comments # 从源文件剥离注释
│ ├── marketplace-check # 报告过时的市场依赖（只读）
│ ├── session-save # 将会话状态捕获到JSON
│ ├── session-load # 从保存的会话打印恢复提示
│ └── mcp-manage # 有条件地添加/删除MCP服务器
├── hooks/ # Git钩子（由install.sh安装）
│ └── pre-commit # 阻止包含密钥或无效JSON的提交
├── completions/ # Shell补全
│ └── just.bash # just命令的bash/zsh选项补全
├── demo/ # 终端演示（presenterm）
│ ├── beginner.md # 概念优先的演练
│ └── presenterm.md # 完整功能演练
├── defaults/ # 默认配置文件和规则模板
│ ├── profiles/ # 严格，务实，极简
│ └── claude/ # 每个配置文件的CLAUDE.md
├── marketplace.json # 外部MCP，技能，插件依赖
└── scripts/
├── install.sh
├── uninstall.sh
├── validate.sh
├── status.sh
└── smoke-test.sh
```
## 合并方式
克劳德代码和开放代码都 **合并** 全局 + 项目本地配置 — 它们不会覆盖：
| 层级 | 克劳德代码 | 开放代码 |
|---|---|---|
| 全局 | `~/.claude/skills/`，`~/.claude/CLAUDE.md` | `~/.config/opencode/skills/`，`~/.config/opencode/AGENTS.md`，`~/.config/opencode/rules/` |
| 项目 | `.claude/skills/`，`CLAUDE.md` | `.opencode/skills/`，`AGENTS.md`，`opencode.json` |
| 结果 | **合并** — 两个都可用 | **合并** — 非冲突键保留 |
开放代码还读取 `~/.claude/skills/` 作为备用，因此单个技能目录在两个工具中都适用。`~/.config/opencode/AGENTS.md` 符号链接到同一个 `CLAUDE.md` — 全局规则的单一真实来源。
## 技能
当上下文匹配时，AI会加载技能 — 描述您需要的内容（例如“创建架构决策记录”）。AI从 `description` 字段中选择正确的技能。 `dotai-` 前缀避免与现有技能冲突。
| 开放代码 | 克劳德代码 | 自动？ | 描述 |
|---|---|---|---|
| `/dotai-adr` | `/dotai:adr` | 自动 | 架构决策记录 |
| `/dotai-debug` | `/dotai:debug` | 手动 | 系统调试工作流 |
| `/dotai-doctor` | `/dotai:doctor` | 自动 | 诊断套件问题 |
| `/dotai-onboard` | `/dotai:onboard` | 自动 | 用图表记录新项目 |
| `/dotai-handoff` | `/dotai:handoff` | 手动 | 会话状态捕获 |
| `/dotai-pr-review` | `/dotai:pr-review` | 手动 | 从git差异生成PR描述 |
| `/dotai-readme-gen` | `/dotai:readme-gen` | 手动 | 从项目扫描生成README |
“自动”表示AI可以主动调用它。“手动”表示您需要输入命令或描述任务。
### 添加新技能
```bash
mkdir -p skills/dotai/my-skill
cat > skills/dotai/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill does.
disable-model-invocation: true
---
# /dotai:my-skill
Instructions for the AI agent here.
EOF
```
## 规则
开放代码从 `~/.config/opencode/rules/` 加载语言特定约定。编辑 `opencode/config.json` 中的 `instructions` 字段以添加或删除文件。
## 代理
`opencode/agents/` 中的自定义开放代码子代理。 通过 `/agent <name>` 调用或配置为默认值。
| 代理 | 目的 |
|---|---|
| `reviewer` | 只读差异审查 — 正确性，安全性，约定 |
| `planner` | 设计和计划 — 无代码更改，仅架构 |
| `test-writer` | 编写和运行测试 — 无法修改生产代码 |
## MCP服务器管理
有条件地添加/删除MCP服务器。 先决条件（环境变量，二进制文件）在添加之前会进行检查。
```bash
just mcp-list # 显示所有可用的服务器
just mcp-status # 显示活动/非活动 + 先决条件是否满足
just mcp-add gmail # 添加服务器（检查环境变量）
just mcp-add gmail --force # 跳过先决条件检查
just mcp-remove gmail # 删除服务器
```
添加/删除后，运行 `just install` 以部署更新的配置。
可用服务器：`gmail`，`slack`，`brave-search`，`linear`，`jira`，`notion`，`sqlite`，`puppeteer`，`google-maps`，`postgres`。
每个服务器配置都存放在 `mcp/available/<name>.json` 中，包含其描述，环境变量要求和设置说明。
## 添加新的MCP服务器（手动）
在 `mcp/claude_desktop_config.json` 中添加一个条目，位于 `mcpServers` 下。 为密钥使用 `{env:VAR}`。 然后再次运行 `install.sh` 以重新链接。
## 工具
令牌效率和维护实用程序符号链接到 `~/.local/bin/`。
### `repo-outline`
代码库的紧凑结构索引 — 目录树 + 函数/类签名。
```bash
repo-outline # 当前目录
repo-outline /path/to/repo
MAX_DEPTH=2 repo-outline # 较浅的树
```
### `strip-comments`
从源代码中剥离注释。 减少上下文大小约20-40%。
```bash
strip-comments file.py # 从扩展名推断语言
strip-comments --lang=python file.py # 显式语言
cat file.js | strip-comments # stdin
```
### `marketplace-check`
检查已安装的MCP服务器，技能和插件与 `marketplace.json` 的匹配情况。 **只读 — 绝不安装或更新任何内容。**
```bash
marketplace-check
```
### `session-save` / `session-load`
捕获和恢复终端会话状态以进行上下文移交。
```bash
session-save # 自动命名：session-20260703-143000
session-save my-fix # 命名会话
session-load my-fix # 打印恢复提示（stdout）
session-load my-fix | pbcopy # macOS：复制到剪贴板
```
会话存储在 `~/.claude/sessions/` 中的JSON文件中。
### Shell补全
`just` 命令的选项补全：
```bash
source completions/just.bash # bash 或 zsh
```
添加到您的 `.zshrc` / `.bashrc` 以保持持久性。
### `token-cost`
估计每个会话的上下文令牌消耗，由规则，技能，配置决定。 显示始终在上下文中与按需加载的内容。
```bash
just token-cost
```
如果有 `tiktoken` 可用（`pip install tiktoken`），则使用它进行准确计数，否则回落到基于字符的估计。
示例输出：
```
全局规则
CLAUDE.md 823 tokens
语言规则
rules/python.md 142 tokens
...
总计（始终开启） 1240 tokens 每次会话的基本成本
~$0.004（Sonnet）
```
### 烟雾测试
非破坏性套件完整性检查。 验证目录结构，JSON配置，技能前置，执行文件和shebang。 **不运行 `install.sh`。
```bash
just smoke-test
```
## Git钩子
`pre-commit` 阻止包含API密钥，令牌或无效JSON的提交。 如果此仓库有 `.git/` 目录，则自动安装。 在 `git init` 后重新运行 `install.sh`。
## 启动新项目
在开放代码（或支持的克劳德代码）中运行 `/init`。 它扫描您的代码库并生成明智的 `AGENTS.md` / `CLAUDE.md`。 提交结果。
## 演示
终端演练：
```bash
brew install presenterm
presenterm demo/beginner.md # 概念优先
presenterm demo/presenterm.md # 完整功能演练
```
两者都是纯Markdown — 无需 `presenterm` 即可阅读。
## `bootstrap` — 全新设置向导
适用于全新用户或重置为默认值。 交互式提示：
1. 哪些AI工具？（克劳德代码，开放代码，两者）
2. 工作流风格：**严格**（完整门控），**务实**（平衡），**最小**（快速）
3. 哪些语言？
4. 哪些可选MCP服务器？
从 `defaults/` 中的配置文件模板生成您的 `CLAUDE.md`，`rules/` 选择，MCP配置和开放代码配置。 备份现有文件并添加 `.pre-init` 后缀。
```bash
just init
```
## 密钥
永远不要在 `.zshrc` 中放置令牌 — 它们对机器上的任何进程都可读。
**推荐（选择一个）：**
```bash
# 选项A：.env文件（最简单，gitignored）
cp .env.example .env
# 填写您的密钥。 .env被gitignored，永远不会被提交。
# 选项B：macOS密钥链
security add-generic-password -a "$USER" -s 'github-token' -w 'ghp_...'
# 然后在.zshrc中（无原始令牌）：
export GITHUB_TOKEN=$(security find-generic-password -w -s 'github-token')
# 选项C：1Password CLI
export GITHUB_TOKEN=$(op read 'op://private/github/token')
# 选项D：direnv + source_up（在所有项目中共享一组密钥）
brew install direnv
# 添加到.zshrc：eval "$(direnv hook zsh)"
cp .env.example .env # 填写您的密钥（gitignored）
just direnv-setup # 编写.envrc.dotai + 父目录中的source块
# 然后，在任何应该继承密钥的项目中：
just direnv-project # 将`source_up`放入.envrc并允许它
```
`just direnv-setup` 在父目录中 **一次** 安装密钥（默认为：
您的项目根目录，覆盖范围：`~/some/dir`）。 它创建
`.envrc.dotai` （加载此仓库的 `.env`）并将一个小的
`source_env .envrc.dotai` 块附加到该目录的 `.envrc` — 您自己的密钥在该
`.envrc` 中保持不变。 每个项目在其下方都继承密钥，只需一个 `.envrc` 包含 `source_up`，因此您永远不会复制每个项目的密钥。
预提交钩子捕获意外提交的API密钥模式。
