dotfiles

dotfiles AI 编程助手在 macOS 上的配置：[Claude Code]、[Codex] 和 [OMX]。 一个本地操作层，包含： - 共享的辅助策略 - 可逆包装和安全钩子 - 具有显式限制牌压力测量 重复的安装验证 起始点： - **策略**：[`configs/AGENTS.md`](configs/AGENTS.md)、[`configs/CLAUDE.md`](configs/CLAUDE.md)、[`configs/codex/config.toml`](x/config.toml) - **测量**：[证据摘要](#证据摘要-2026-07-06)、[`configs/RTK.md`](configs/RTK.md) - **安全**：/hooks/pretool-guard.sh`](configs/hooks/pretool-guard.sh)、[`plugins/local-skills/skills`](plugins/local-skills/skills) - **验证**：[`scripts/verify.sh`](scripts/verify.sh)、[`tests/scripts.bats`](tests/scripts.bats)、[`scripts/doctor.sh`](scripts/doctor.sh) ## 证据~2026-07-06） 这些是独立的计数器，而不是一个累加的节省总额。 | 表面 | 当前证据 | 安全解释 | | --- | --- | --- | | [RTK] 减少输入 | 23,903 个全局命令。估计删除 26.2M 个令牌（57.3%）。在此仓库中：删除 1.26M 个令牌（63.5%）。 | 在转录输入前大幅减少命令/工具输出。不是账单节省百分比。 | | [Headroom] 代理健康状况 | 22,337 个路由请求。18,469 个缓存（82.7%）。54 个失败（0.24%）。0 个速率限制。1 个缓存刷新。 | 活跃的代理遥测和有界故障/缓存刷新计数器。不是反事实输出令牌节省证明。 | | 公共使用账本 | [Tokscale]：93.711B 令牌和 95.8% 缓存读取，截至 2026-07-05。 | 公共令牌混合快照。不是一个仓库更改的因果关系证明。 | 在 `headroom output-savings` 具有基准或对照数据之前，不会声称其输出令牌节省。跨机器总和在每台机器刷新相同捕获窗口之前省略。 ## 安装 全新 macOS 安装： ```curl -fsSL https://raw.githubusercontent.com/voidmatcha/dotfiles/main/bootstrap bash ``` 预览而不更改机器： ```bash curl -fsSL https.githubusercontent.com/voidmatcha/dotfiles/main/bootstrap.sh | bash -s -- --dry-run ``` 从现有克隆 ```bash cd ~/dotfiles .sh ``` 更新现有 ```bash .sh --check #：git pull + install.sh --dry-run --upgradeupdate.sh # git pull --ff-only + install.sh --upgrade ./update.sh --no-pull ``` 状态快照： ./scripts/doctor.sh ``` `bootstrap 在缺少 `git` Xcode 命令行工具，将此仓库克隆到dotfiles`，并移交给 `./install.sh`。`company/` 叠加层仅在本地存在子模块时运行。 <details> <summary>安装内容</summary> | 区域 | 安装/配置 | 来源 | | --- | --- | --- | | macOS 默认设置 | Dock、Finder、键盘、截图、防火墙、Touch ID sudo。 | [`scripts/macos.sh`](scripts/macos.sh) | | CLI 包 | [Homebrew] 工具、[Bats]、[gitleaks]、[uv]、[gettext]、[git-filter-repo]、[Docker CLI]。 | [`Brewfile`](Brewfile) | | 语言运行时 | [nvm]、[Node.js] LTS、[Corepack]、[pyenv]、最新 [Python] 3、[SDKMAN!]、[OpenJDK] LTS、[Maven]。 | [`scripts/dev.sh`](scripts/dev.sh) | | Shell 和 Git | [Zsh] 插件、[direnv]、个人 Git 身份、OpenSSH] 的签名。 | [`scripts/shell.sh`](scripts/shell.sh)、[`scripts/git.sh`](scripts/git.sh) | | 代理 CLI | [Claude Code]、[]、[ Agent]、[]。 | [`aude.sh`](scripts.sh)、[`scripts/codex.sh`](scripts/codex.sh)、[`scripts/hermes.sh`](scripts/hermes.sh)、[`scripts/dev.sh`](scripts/dev.sh) | | 私有远程访问 | [Tailscale]、[Tailscale SSH]、[OpenSSH]、[code-server]、[purplemux]。[Tails] 仍然是可选的。 | [`scriptscale.sh`](scriptscale.sh)、[`scripts`](scripts/services.sh) | 运行一个专注的，当不需要完整的设置时： ```bash /brew.sh ./scripts/macos.sh /dev.sh ./scripts.sh ./scripts/git./scripts/codex.sh ./scripts/cl ./scripts/hermes.sh ./scriptscale.sh ./scripts ``` </details> ## 代理层 使 [Claude Code] 和 [Codex] 相同。目标是保持策略、技能、M由和验证的一致每个工具保持其原生工作流。 Claude 从 `~/.agent/AGENTS.md` 导入/.agent/AGENTS.md`，通过 [`configs/CLAUDE.md`](configs/CLAUDE.md)。直白地说，它导入了 ~/.agent/AGENTS.md。 Codex 设置从 [`configs/codex/config.toml`](configs/codex/config.toml) 编写 `~/.codex/config.toml`。它启用 `[ goals = true`，在生成的 TOML `mcp_servers` 条目，并使用 `ills.sh codex` 安装 Codex 技能。 表面 | 角色 | | --- | --- | | [ Code] | Claude 执行，共享 AGENTS.md 规则、钩子、 和 [RTK策略。 |/claude.sh`](scripts/claude.sh)、[`configs/CLAUDE.md`](configs/CLAUDE.md)、[`configs/claude-settings.json`](configs/claude-settings.json) | | [Codex（带有 OMX）][Codex] | Codex 执行，带有 OMX 工作流、目标、内存和原生子代理。 | [`scripts/codex.sh`](scripts/codex.sh)、[`configs/codex/config.toml`](configs/codex/config.toml) | | [Headroom] | 用于可逆压缩和缓存感知路由的 `claudeh`、`codexh` 和 `omxh` 包装器。 | [`scripts/headroom-agent.sh`](scripts/headroom-agent.sh)、[`scripts/headroom.sh`](scripts/headroom.sh) | | [RTK] | 噪音 shell 输出进入上下文前的命令输出压缩。 | [`configs/.md`](configs/RTK.md)、[`configs/rtk-config.toml`](configs/rtk-config.toml) | | 本地技能 | 仓库拥有的上下文压力、、验证、预览、清理和来源程序。 | [`plugins/local-skills/skills`](plugins/local-skills/skills) | `ResumerBar`/`agent-resumer` 和 `cmux-deck` 是机器本地运行时集成，而不是此仓库安装或配置的组件。不要在此提交它们的生成桩、套接字、状态Agents 或注入的 shell 块。 ### 已安装的外部技能和插件 除了下面列出的本地技能外，还安装或启用了这些技能或插件。`local-skills@dotfiles-local` 插件将这些本地技能暴露给 Claude。 | 用例 | 项目 | 功能 | | --- | --- | --- | | 压力测试计划。 | [`grill-me`](scripts/skills.sh) | 从固定的上游引用安装的独立 Claude 和 Codex 技能。 | | 从 Figma 实现。 | [`figma-implement-design`](scripts/skills.sh) | 从固定的上游引用安装的 Codex 技能。 | | 查看 Claude 会话状态。 | [`claude-hud@claude-hconfigs/claude-settings.json) | 显示本地 Claude。 | | 审核技能库存。 | [`skills-janitor@skills-janitor`](configs/cl.json) | 和清理已技能。 | | 包装 Claude 会话。 | [`session-wrap`](scripts/skills.sh) | 安装程序固定的 Claude 会话包装插件。 | | 使用 Claude 工作流助手。 | [`superpowers`](configs/claude-settings.json) | 在嘈杂的子技能保持禁用时启用官方工作流助手。 | | 审查前端设计。 | [`frontend-design`](configs/claude-settings.json) | 添加官方前端设计指导。 | | 管理 CLAUDE.md 文件。 | [`claude-md-management`](configs/claude-settings.json) | 为 CLAUDE.md 样式文件添加官方指导。 | | 使用钩子。 | [`hookify`](configs/claude-settings.json) | 添加官方钩子工作流助手。 | | 审查安全基础知识。security-guidance`](configs/claude-settings.json) | 添加官方安全指导。 | | 广泛审查代码。 | [`comprehensive-review`](configs/claude-settings.json) | 添加 Claude 代码审查工作流包。 | | 生成文档。 | [`documentation-generation`](configs/claude-settings.json) | 添加 Claude 文档工作流包。 | | 保留 Claude 内存。 | [`claude-mem`](configs/claude-settings.json) | 通过本地设置启用 Claude 内存插件。 | | 使用 Codex 移交审查。 | [`review-loop@hamel-review`](configs/claude-settings.json) | 在审查循环工作流中列出，默认禁用。 | | 使用 Obsidian 笔记。 | [`obsidian-skills`](scripts/claude.sh) | 从 `kepano/obsidian-skills` 安装的 Claude 插件。 | ## 本地技能：为什么它们存在 本地技能将重复出现的会话决策转换为命名的、可检查的程序。它们一一列出，以便稍后可以审计每个技能。 | 用例 | 项目 | 功能 | | --- | --- | --- | | 需要超出仓库的公共互联网证据。 | [`agent-reach`](plugins/local-skills/skills/agent-reach/SKILL.md) | 路由公共网络、GitHub、社交、视频和 RSS 研究，同时将内部 URL 排除在托管读取器之外。 | | 清理卡住或失控的代理进程。 | [`agent-reap`](plugins/local-skills/skills/agent-reap/SKILL.md) | 查找孤立的 Claude、Codex 或 OMX 相关进程。杀死仍然是显式的。 | | 决定要修剪哪些代理表面。 | [`agent-usage-audit`](plugins/local-skills/skills/agent-usage-audit/SKILL.md) | 审计已安装的代理、技能、命令、MCP 和最近的使用情况。 | | 诊断陈旧代码智能。 | [`code-intel-doctor`](plugins/local-skills/skills/code-intel-doctor/SKILL.md) | 检查代码图和 serena 设置、Codex 配置、每个仓库索引和实时 CodeGraph 状态；`--strict` 在未知状态字段上失败并关闭。 | | 决定继续、压缩、清除或移交。 | [`context-check`](plugins/local-skills/skills/context-check/SKILL.md) | 读取上下文、缓存、Headroom 和移交压力，然后更改会话状态。 | | 验证安装或发布前的 dotfiles。 | [`dotfiles-verify`](plugins/local-skills/skills/dotfiles-verify/SKILL.md) | 运行此仓库的安装、配置和插件烟雾检查。 | | 将工作转移到另一个会话。 | [`handover`](plugins/local-skills/skills/handover/SKILL.md) | 创建持久的移交工件和失败关闭的 ACK 或 READY 检查。 | | 调试错误、回归或不稳定故障。 | [`hypothesis-debugging`](plugins/local-skills/skills/hypothesis-debugging/SKILL.md) | 将事实与假设分离并跟踪可证伪的假设。 | | 从本地代理会话中挖掘重复反馈。 | [`session-feedback-audit`](plugins/local-skills/skills/session-feedback-audit/SKILL.md) | 使用可扩展的短语模式包从本地 JSONL 中提取重复的更正和重新请求，然后仅从跨文件证据中生成规则。 | | 审查韩语技术写作中的术语。 | [`korean-technical-terminology`](plugins/local-skills/skills/korean-technical-terminology/SKILL.md) | 在精度重要的地方保留规范英语，遵循已建立的韩语用法，并重写不雅的直译而不成为通用语法检查器。 | | 提供本地报告或构建预览。 | [`local-preview-server`](plugins/local-skills/skills/local-preview-server/SKILL.md) | 启动已验证的 localhost 或 tailnet 预览 URL。默认绑定为 `127.0.0.1`。 | | 压力测试高风险计划。 | [`premortem`](plugins/local-skills/skills/premortem/SKILL.md) | 在执行前列出可能的故障模式。 | | 跟踪导入的工作流资产。 | [`source-provenance`](plugins/local-skills/skills/source-provenance/SKILL.md) | 记录标准代理技能的元数据并审计源、许可证、导入模式和本地修改。 | | 事实核查 README、PR 或报告声明。 | [`verifyplugins/local-skills/verify-output/SKILL.md) |声明，尝试驳斥它们，并分类结果。 | | 避免错误表面数据路由。 |-scope-guard`](-skills/skills/work-scope-guard/SKILL.md) | 在敏感数据进入错误工具之前显示工作和公司范围提醒。 | | 在浏览器 VS Code 中打开工作树。 | [`worktree-open`](plugins/local-skills/skills/worktree-open/SKILL.md) | 为一个工作树或所有工作树构建确定性的 code-server 链接。 | `handover` 拥有上下文/会话转移。对于可见的后端，请使用 [`display-adapter-contract.md`](plugins/local-skills/skills/handover/references/display-adapter-contract.md) 和 [`purplemux-display.md`](plugins/local-skills/skills/handover/references/purplemux-display.md)。`cmux` 和 `purplemux` 保持显示/控制后端。 `asset-improver` 在 [`plugins/local-skills/quarantine/`](plugins/local-skills/quarantine/) 下保留，以备可能恢复，但不作为技能发布。其旧工作流依赖已安装运行时不可移植的技能名称，包含机器特定的评估路径，并可以执行破坏性的 Git。 保持 `ach` 健康检查非变异：使用 `agent-reach --version`，而不是 `agent doctor`。医生可以重新创建共享技能根目录下的通用副本并遮蔽此仓库的公共适应。如果上游设置故意重新运行，请使用 `scripts/skills.sh claude` 和 `scripts/skills.sh codex` 重新安装两个本地目标，然后重启活动的 Claude/Codex 会## MCP 治理和工具路由 | 表面 | 配置 | 策略 | | --- | --- | --- | | [Claude Code] MCP | [`configs/mcp.json`](configs/mcp.json) | 为 Claude Code 注册本地和托管的 MCP。钩子和拒绝规则捕获常见错误。 | | [Codex] MCP | [`configs/codex/config.toml`](configs/codex/config.toml) | 注册 [Chrome DevTools MCP][chrome-devtools-mcp]、[serena[codegraph]、[context7]、[OpenAI Docs MCP] 和个人/默认 [Figma 主机 MCP][Figma MCP]。 | | 公司/本地后备 | 存在时的 `company/` 叠加层 | 当托管工具不合适时，使用公司范围的 MCP 或本地浏览器表面。 | 不要通过 [Exa]、[Jina Reader] 或个人/默认 [Figma 主机 MCP][Figma MCP] 等托管工具路由内部 URL。公司 Figma 上下文是分开的。使用公司后备（`figma-developer-mcp`）或本地浏览器表面。 [agent-browser] 是一种用于有针对性的浏览器观察和身份验证浏览的定性令牌压力控制。它不是一个数字节省声明。 ### 工具路由 | 任务 | 默认工具 | 原因 | | --- | --- | --- | | 解释代码流、路由处理程序或符号跟踪。 | [codegraph] | 用于跨文件流的预索引图。 | | 重命名、编辑或检查引用。 | [serena] | 基于 LSP 的符号感知编辑和引用。 | | 清洁的公共网页提取。 | [Jina Reader] 或 [defuddle] | 用于公共页面的快速 Markdown 提取。示例：`defuddle parse <url> --markdown`。 | | 广泛的公共网络研究。 | [Exa] | 仅限公共搜索，不适用于敏感或内部 URL。 | | 身份验证或敏感浏览。 | [agent-browser] 或本地浏览器 | 将身份验证和内部上下文保留在托管读取器之外。 | | 临时浏览器自动化。 | [Chrome DevTools MCP][chrome-devtools-mcp] | 本地目标的干净浏览器自动化。 | | 知识图谱探索。 | [graphify] | 作为 Claude/Codex 技能安装，`graphify install --platform claude` 和 `graphify install --platform codex`。 | | 会话上下文策略。 | [`context-check`](plugins/local-skills/skills/context-check/SKILL.md) | 返回继续、压缩、清除或移交建议。 | 网络工具提示：[defuddle] 使用 `npm install -g defuddle` 安装。[graphify] 由 [`scripts/dev.sh`](scripts/dev.sh) 安装。 ## Claude Code 操作陷阱，而非安全控制 一些本地会话故意以广泛的文件系统权限运行。这些 Claude Code 陷阱不是安全边界。它们不保护单独的 [Codex] `danger-full-access` 会话。它们捕获常见错误。sandboxing、review 和机密管理仍然是安全工作。 | 守卫 | 表面 | 捕获 | | --- | --- | --- | | [`pretool-guard`](configs/hooks/pretool-guard.sh) | Bash 的 Claude `PreToolUse` 钩子。 | 工具调用运行前的大范围破坏性 Bash 模式。 | | [`skill-md-edit-warn`](configs/hooks/-edit-warn.sh) | ClaudeToolUse` 警告。 | 会话已经加载技能指令后编辑的 `SKILL.md`。 | | `permissions.deny` | [`configs/claude-settings.json`](configs/claude-settings.json) | Claude Code 中的已知机密路径和风险托管工具表面。 | | [`work-scope-guard`](plugins/local-skills/skills/work-scope-guard/SKILL.md) | 本地技能。 | 公司/工作范围路由提醒。 | ## 安全性和本地预览 优先使用 localhost 和私有 tailnet 路径。本地预览默认绑定到 localhost。来自另一台机器的访问通过 [Tailscale Serve] 和 tailnet ACL。 | 需要 | 默认路径 | 暴露 | | --- | --- | --- | | 打开工作树浏览器的 IDE。 | [`worktree-open`](plugins/local-skills/skills/worktree-open/SKILL.md) | 本地 [code-server] URL，或 [Tailscale] URL（当可用时）。 | | 提供报告或静态构建。 | [`local-preview-server`](plugins/local-skills/skills/local-preview-server/SKILL.md) | 默认绑定地址为 `127.0.0.1`。 | | 在 tailnet 内共享预览。 | `--tailscale-serve` | 使用 [Tailscale Serve] 和 tailnet ACL。 | | 可选的 LaunchAgents 门控。 | [`scripts/services.sh`](scripts/services.sh) | 如果依赖项丢失，它会跳过加载 LaunchAgents，因此部分安装仍然可用```bash plugins/local-skills/skills/local-preview-server/scripts/local-preview-server.sh start --path ./report.html --port 8377 plugins/local-skills/skills/local-preview-server/scripts/local-preview-server.sh start --path ./dist --tailscale-serve plugins/local-skills/skills/local-preview-server/scripts/local-preview-server.sh status --port 8377 plugins/local-skills/skills/local-preview-server/scripts/local-preview-server.sh stop --port 8377 ``` ## 验证 在声称安装程序行为之前，请运行完整的验证程序： ```bash bash scripts/verify.sh --full ``` 有用的聚焦检查： ```bash bats tests/ bash scripts/verify.sh --quick bash scripts/secret-scan.sh --required bash scripts/doctor.sh python3 scripts/code_intel_doctor.py --json --strict . python3 scripts/source_provenance_audit.py --strict --format json omx doctor ``` 当本地技能内容发生变化时，请在重新安装之前保持市场、Claude 插件和 Codex 插件清单版本一致。安装直到发布的 `plugins/local-skills/skills/` 树与 Claude 插件缓存和每个对应的 `~/.codex/skills/<name>` 目录匹配才算完成。隔离的资产必须保持在发布的 `skills/` 根目录之外。 预推送保护由 [lefthook] 管理。`install.sh` 在可用时运行 `lefthook install`，而 `lefthook.yml` 运行 `scripts/verify.sh` 和所需的 [gitleaks] 对工作树和所有可从本地引用（`--all`）访问的提交的扫描，包括非签出的分支和标签。使用 `./scripts/brew.sh` 安装缺少的钩子工具。 测试涵盖 Shell 和 Python 语法、ShellCheck、Python 单元测试、JSON/TOML/plist 解析、技能/插件清单、钩子行为、[Codex] TOML 验证、`Brewfile` 解析、输出历史秘密扫描、医生/状态检查和本地技能助手。当 ShellCheck 或 [Bats] 不可用时，`--full` 关闭；仅当完整的 lint/Bats 网关故意不在范围内时，才使用 `--quick`。 ## 布局 ```text dotfiles/ ├── install.sh ├── Brewfile ├── README.md ├── scripts/ ├── configs/ ├── plugins/local-skills/ ├── tests/ └── company/ ``` ## 公司叠加层 对于具有内部包注册表、私有插件市场或范围限定 MCP 配置的环境，`install.sh` 在存在 `company/` 子模块时调用 `company/install.sh`。将公司存储库保持在 `~/work/` 下，以便项目范围的 MCP 工作范围指导适用。 ```bash git clone --recurse-submodules https://github.com/voidmatcha/dotfiles.git ~/dotfiles ``` 如果您先克隆，请在稍后初始化叠加层： ```bash git -C ~/dotfiles submodule update --init ``` 请参阅 [`company/README.md`](company/README.md) 以进行叠加层维护。 [lefthook]: https://lefthook.dev/ [gitleaks]: https://github.com/gitleaks/gitleaks [Bats]: https://github.com/bats-core/bats-core [Codex]: https://github.com/openai/codex