@dtt_siye/atool

AI Developer Toolkit — 一条命令，30 秒为 AI IDE 配置完整开发环境。

aTool 为 Claude Code、Cursor、Kiro、OpenAI Codex CLI、GitHub Copilot 五个 AI 辅助 IDE 提供一键配置能力：自动安装编码规范技能、质量门禁钩子、MCP 工具服务器和项目模板，并提供企业级项目深度分析管线。支持 17 种技术栈，无需手动配置，无需管理员权限。

./install.sh --all --yes

设计理念

aTool 的目标是把 AI 辅助研发从"个人手艺"变成"工业化流程"。五条核心理念贯穿所有设计：

1. 研发最佳实践工程化。 编码规范、架构方法、调试纪律、文档标准这些散落在团队老手脑子里的经验，被固化为可安装、可版本化、可分发的技能（Skill）。新项目、新成员、新 IDE，一条命令即可获得同一套实践。

2. 能机械化的绝不依赖 AI 自觉。 AI 会忘记规则，提示词会被稀释。所以 aTool 把关键纪律做成机械门禁：5 个生命周期 Hook 在会话开始、每条请求、每次文件修改、每次提交时自动介入；5 条硬规则（文档同步、完成验证、先找根因、文档先行、测试先行）不可绕过；在没有 Hook 机制的环境（如 GitHub Copilot），门禁下沉到 git 原生 pre-commit / commit-msg 层——对人和 AI 一视同仁。

3. IDE 中立，按能力降级。 同一套技能与门禁内容，自动转换为各 IDE 的原生格式。各 IDE 能力不同（有无 Hook、有无并行子代理、全局还是项目级配置），aTool 按能力矩阵分层降级，而不是只服务能力最强的那个。

4. 零特权、可离线。 所有安装均为用户级（写入 ~/.claude、~/.cursor、~/.atool 等），不需要 sudo、不强制依赖 npm；唯一的外部依赖 jq 缺失时自动下载静态二进制到用户目录。受限网络环境有完整的离线安装路径。

5. 流程闭环：澄清 → 设计 → 实现 → 验证。 从需求澄清分级（避免 AI 拿到模糊需求就开写）、到文档先行（PRD / 架构 / UI 原型先于代码）、到 TDD 实施、再到完成前验证门禁（测试通过 + 文档新鲜 + 无严重质量问题），形成完整研发管线，每个环节有对应技能承接。

功能总览

| 能力 | 说明 | |------|------| | 技能系统 | 59 个技能（47 个自研 + 14 个 Superpowers 方法论技能，其中 2 个由 aTool 定制增强版覆盖），覆盖 Java、Web、Python、Rust、Go、Flutter、HarmonyOS、Android、Swift、React Native、DevOps、数据仓库等 17 种技术栈的编码规范、架构设计、代码审查、SQL 开发、调试与文档协作；按需加载，按项目类型自动触发；由 Skill Registry 集中治理（启用/禁用/角色绑定） | | 质量门禁 | 5 个 Hook：会话上下文注入（session-start）、请求复杂度分级（prompt-guard）、提交前检查（pre-commit）、文档同步提醒（doc-sync-reminder）、任务状态追踪（task-state-tracker）；外加 git 原生门禁（敏感文件阻断、Conventional Commits 校验），供无 Hook 环境使用 | | 研发管线 | 7 阶段开发流程编排：需求澄清（Tier 0-3 分级）→ 设计探索 → 文档化（PRD / 架构文档 / UI 设计画板）→ 计划 → TDD 实施 → 完成验证 → 交付分支管理 | | UI/UX 设计链路 | 从需求澄清直达设计交付：UI 类请求自动触发设计门禁 → 生成设计系统（含 66 个品牌风格模板目录）与交付级全景 HTML 画板（iPhone 15 Pro / Desktop 1280 双框架 + 尺寸标注）→ 浏览器审批 → 实现后 1:1 还原度验收 | | 项目深度分析 | 8 阶段分析管线：扫描 → 源抽取 → 模块文档 → 知识图谱（14 类节点 × 24 类边）→ 交叉验证 → 合并 → 质量门禁 → 导出；L1-L5 五级深度，Token 预算分级，增量分析跳过未变模块 | | 项目模板 | 14 套技术栈模板（CLAUDE.md / README / COMPONENT / UI_STYLE / IDE 规则），初始化时自动检测技术栈并生成 | | MCP 服务器 | 5 个推荐 MCP 工具服务器一键配置（含 Office 文档读写：Word / PDF / PPT / Excel） |

多 IDE 支持矩阵

| | Claude Code | Cursor | Kiro | Codex CLI | GitHub Copilot | |---|---|---|---|---|---| | 配置形态 | 全局，原生 SKILL.md | 全局暂存 + 项目级 .mdc | 项目级 steering | 全局 config.toml + AGENTS.md | 仅项目级（.github/ + git 门禁） | | Hooks | ✅ 全部 5 个 | ✅（项目级） | ⚠️ Agent Hooks 子集 | ✅ 全部 | ❌ → git 原生门禁兜底 | | 技能数 | 59 | 59 | ~9（合并） | 59 | 3 个核心质量 prompt | | 强制执行力 | 高 | 中 | 低 | 高 | 中（git 门禁为硬阻断） |

安装

前置条件：bash 3.2+（macOS / Linux 自带，Windows 用 Git Bash）。不需要管理员权限；jq 缺失时自动下载到 ~/.atool/bin/；Node.js 仅 npm 安装方式和 MCP 服务器运行需要。

方式一：npm 全局安装

npm install -g @dtt_siye/atool
atool install --all

方式二：源码 / 离线安装（无需 npm）

适用于没有 npm、没有管理员权限、或受限网络的环境。

# 2a. 能访问 GitHub 的机器
git clone --recurse-submodules <仓库地址>
cd aTool_package
./install.sh --all --yes

# 2b. 完全离线环境
# 在能联网的机器上打包（--recurse-submodules 确保 Superpowers 子模块完整）：
git clone --recurse-submodules <仓库地址> && tar czf atool.tar.gz aTool_package/
# 拷贝到目标机器解压后：
cd aTool_package && ./install.sh --all --yes

离线说明：所有安装产物写入用户主目录，无任何系统目录操作。jq 自动下载在离线环境会失败——可预先把 jq 静态二进制放到 ~/.atool/bin/jq。内网镜像用户可用 SUPERPOWERS_REPO=<mirror-url> 环境变量替换 Superpowers 子模块源。

方式三：Windows

git clone --recurse-submodules <仓库地址>
cd aTool_package
.\install.ps1 --all --yes

install.ps1 是薄包装：自动定位 Git for Windows 的 bash（或 WSL）后转发给 install.sh，不重复安装逻辑。没有管理员权限装不了 Git for Windows 时，可使用 PortableGit 便携版（解压即用）。

只为某个 IDE 安装

全局安装（用户级，写入 ~/ 下对应目录）：

./install.sh --claude --yes      # 仅 Claude Code（~/.claude/，装完即用）
./install.sh --cursor --yes      # 仅 Cursor（暂存到 ~/.cursor/rules/.atool-staging/，需再跑项目初始化）
./install.sh --kiro --yes        # 仅 Kiro（暂存，需再跑项目初始化）
./install.sh --codex --yes       # 仅 OpenAI Codex CLI（~/.codex/ + ~/.agents/skills/，装完即用）

项目级安装（写入目标项目目录）：

# GitHub Copilot 没有全局配置，只有项目级——在项目根目录执行：
cd /path/to/project && /path/to/aTool/install.sh --copilot
# 生成 .github/copilot-instructions.md + instructions/prompts + .atool/githooks/ git 门禁

# 项目初始化时限定只生成某些 IDE 的配置：
atool init --ide claude,kiro           # 只生成 Claude + Kiro 的项目配置
atool init --ide copilot               # 只生成 Copilot 配置（不接 git 门禁）

各 IDE 全局/项目级生效规则：

| IDE | 全局安装后 | 还需项目级步骤吗 | |-----|-----------|----------------| | Claude Code | 立即可用 | 可选（atool init 补充项目模板与项目级 Hook） | | Codex CLI | 立即可用 | 可选 | | Cursor | 仅暂存模板 | 必须 atool init（Cursor 只加载项目内 .cursor/rules/） | | Kiro | 仅暂存模板 | 必须 atool init（Kiro 只加载项目内 .kiro/steering/） | | GitHub Copilot | （无全局概念） | 必须 --copilot 或 atool init --ide copilot |

初始化项目

cd /path/to/your/project
atool init                      # 自动检测技术栈，生成全套配置
atool init --stack java         # 强制指定技术栈
atool init --ide claude,kiro    # 限定生成哪些 IDE 的配置

生成内容：CLAUDE.md、README.md、COMPONENT.md、UI_STYLE.md、各 IDE 规则文件、项目级 Hook。未指定 --ide 时自动检测本机已安装的 IDE，只为检测到的 IDE 生成产物。

使用方法

CLI 命令

atool [VERB] [OPTIONS]          # npm 安装后
./install.sh [OPTIONS]          # 源码安装（VERB 对应 --flag 形式）

| Verb | 别名 | 说明 | |------|------|------| | atool install | i | 安装到检测到的所有 IDE（默认 --all） | | atool init [PATH] | — | 初始化项目（默认当前目录） | | atool analyze [PATH] | a | 为项目准备深度分析脚手架；--incremental 跳过未变模块 | | atool update | u | 拉取最新版本并增量重装 | | atool check-updates | check | 探测 npm registry 最新版本（不写盘） | | atool doctor | dr | 系统健康检查（环境 / 配置 / 技能漂移 / registry） | | atool registry <sub> | reg | 技能治理：show / resolve <role> / enable / disable / rebind / reconcile | | atool list-projects | ls | 列出已分析项目 | | atool uninstall [PATH] | un | 全局卸载（或卸载某项目残留）；--purge 一并自删 npm 包 |

常用选项：--dry-run（预览不写盘）、--force（覆盖并备份已有配置）、--yes（跳过确认）、--stack NAME（强制技术栈）、--ide LIST（限定 IDE，CSV：claude,cursor,kiro,codex,copilot）、--copilot / --no-copilot、--no-kiro-hooks。

在 IDE 中使用技能

安装后在 Claude Code（及 Cursor / Codex）中通过斜杠命令调用，技能也会根据项目类型与请求内容自动触发：

/atool-analyze             # 深度分析当前项目（8 阶段管线入口）
/development-pipeline      # 走完整研发流程（澄清 → 设计 → 文档 → TDD → 验证）
/java-conventions          # 加载 Java 编码规范（其余 16 种栈各有对应技能）
/code-review               # 8 维度代码质量审查
/requirements-writer       # 撰写 PRD
/software-architecture     # 架构设计
/ui-ux-pro                 # UI/UX 设计（设计系统 + 全景 HTML 画板）
/brainstorming             # 需求/设计头脑风暴

GitHub Copilot 用户在 Copilot Chat 中使用安装到项目里的 prompt：/atool-verify（完成前验证）、/atool-clarify（需求澄清）、/atool-code-review（代码审查）。

典型工作流

开发新功能（自动编排）：直接用自然语言提需求。prompt-guard 会自动给请求分级——简单改动直接做；中等复杂度先做 3-5 个问题的结构化澄清；架构级请求进入头脑风暴。涉及 UI 的请求自动触发设计门禁：先生成设计系统与 HTML 原型画板、经你确认后才开始编码，实现完成后做 1:1 还原度验收。全程受 5 条硬规则约束：PRD / 架构文档先于代码，测试先于实现，完成前必须通过验证门禁。

分析存量项目：atool analyze /path/to/project 准备脚手架，然后在 IDE 中执行 /project-analyze。产出模块文档、知识图谱、架构总览等标准化文档（写入 .atool-docs/），后续可用 /project-query 查询调用链、影响面与数据血缘。

技能治理：atool registry disable pptx 临时下线某个技能（跨 IDE 同步移走，IDE 扫描不到即不加载），enable 原路恢复；rebind 可把管线角色（如 PRD 撰写）换绑到团队自研技能。升级重装不会丢失这些自定义状态。

升级与卸载

atool update                              # 升级（等价 npm install -g @dtt_siye/atool@latest + 重装）
atool uninstall --purge                   # 干净卸载：清全部 IDE 配置 + 自删 npm 全局包

注意两个 npm 行为：① 包名是 scoped 的 @dtt_siye/atool，npm uninstall -g atool 会报找不到包；② 现代 npm 已移除 uninstall 生命周期钩子，先 npm uninstall 再清配置会陷入"命令已删但配置还在"的死锁——所以推荐 --purge 一步完成。升级时若 npm 缓存了旧的 latest 标签，用显式版本号绕开：npm install -g @dtt_siye/atool@<version>。

故障排查

Superpowers 子模块缺失（核心方法论技能的来源）：npm 包已内置；git clone 安装首次运行会自动 git submodule update --init 自愈；仍缺失时按环境恢复——能连 GitHub 直接重跑 atool install --all（自动从 GitHub 缓存）；离线环境从联网机器整体拷贝 skills/_superpowers/ 目录；内网镜像用 SUPERPOWERS_REPO=<mirror-url> 环境变量。

看不到 npm 安装进度：npm 默认隐藏 postinstall 输出，用 npm install -g @dtt_siye/atool --foreground-scripts 实时查看；安装关键事件也会写入 ~/.atool/last-install.log，atool doctor 会兜底展示。

技能没生效 / 怀疑漂移：跑 atool doctor 体检；atool install --force --all --yes 强制重装（旧文件自动备份到 ~/.atool/backups/）。

许可证

MIT License · 当前版本 1.11.0 · 完整文档见仓库 docs/ 目录