# kaitools

**Repository Path**: konghy/kaitools

## Basic Information

- **Project Name**: kaitools
- **Description**: 个人 AI 辅助工具集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kaitools

个人 AI 辅助工具集，以插件形式统一管理 Cursor 和 Claude Code 的规则（Rules）、技能（Skills）和智能体（Agents）配置。

## 安装

```bash
git clone https://github.com/your-username/kaitools.git ~/AIProjects/kaitools
cd ~/AIProjects/kaitools
./install.sh
```

安装会把 kaitools 管理的文件复制到目标目录，同名文件会直接覆盖。`git pull` 更新仓库后需重新运行 `./install.sh` 以同步最新内容。

推荐流程：

```bash
./install.sh --list
./install.sh --dry-run
./install.sh             # 同时安装 Cursor 和 Claude Code（默认）
./install.sh --qoder     # 可选：安装 Qoder（skills/agents/commands/rules）
./install.sh --verify
./install.sh --status    # 查看当前安装状态
./install.sh --uninstall # 卸载 Cursor 和 Claude Code
```

高频命令：

```bash
./install.sh --cursor
./install.sh --claude
./install.sh --verify --cursor
./install.sh --token-report [git-ref]
./install.sh --uninstall --qoder
```

完整 CLI 选项、影响范围、verify 语义、卸载边界和 Claude marketplace 机制见 [INSTALL.md](INSTALL.md)。

当前安装行为要点：
- Cursor 插件、Claude marketplace staging、`CLAUDE.md`、各平台 `rules/*.mdc` 都是逐文件复制，不是链接
- uninstall 只删除 kaitools 管理范围内的文件，不会 merge 或回滚手工改动
- verify 只检查文件和 CLI 可观测状态，不保证当前打开会话已热加载
- Claude Code 的插件安装机制详见 [docs/claude-plugin-install.md](docs/claude-plugin-install.md)

## Rules 说明

`rules/` 使用 `.mdc` 格式，Cursor 读取 frontmatter 中的激活字段决定何时启用；Claude Code 安装时会将 `claude.global.md` 复制为 `~/.claude/CLAUDE.md`，再通过其中的 `@rules/xxx.mdc` 引用导入。两者共用同一份文件。

| 文件 | 说明 | 类型 |
|------|------|------|
| `assistant-communication.mdc` | AI 助手与用户沟通规范，并吸收工具/API 问答的表达要求 | 常驻 |
| `coding-best-practices.mdc` | 代码复用、质量、错误处理、性能、安全等通用原则 | 常驻 |
| `system-safety-common.mdc` | 跨平台系统操作安全底线、只读命令白名单、临时文件和回滚原则 | 常驻 |
| `git-conventions.mdc` | Commit 格式、分支命名、.gitignore 规范 | 按需 |
| `auto-subagent-dispatch.mdc` | 子 Agent 自动调度规则 | 按需 |
| `python-coding-standards.mdc` | Python 代码风格、类型注解、文档规范 | 按需 |
| `system-safety-unix.mdc` | Unix/Linux/macOS 环境安全规范 | 按需 |
| `system-safety-windows.mdc` | Windows 环境安全规范 | 按需 |

## Agents 说明

`agents/` 使用 `model: inherit`，各平台使用各自的默认模型，无需维护平台专属版本。

| 文件 | 说明 |
|------|------|
| `code-quality-reviewer.md` | 规格通过后的代码质量审查 |
| `debugger.md` | 系统性根因分析和 Bug 修复 |
| `documentation-engineer.md` | API 文档、README、架构文档编写 |
| `git-workflow-manager.md` | 提交管理、分支操作、冲突解决 |
| `performance-engineer.md` | 性能瓶颈定位和优化 |
| `qa-expert.md` | 测试策略设计、覆盖率分析、质量标准 |
| `refactoring-specialist.md` | 代码结构改善、复杂度降低 |
| `spec-compliance-reviewer.md` | 对照需求和验收标准进行规格符合性审查 |
| `test-runner.md` | 测试运行、失败分析、结果报告 |

## Commands 说明

`commands/` 提供跨平台 slash command（`/review-current`、`/git-commit`、`/pycovtest-current`）。正文只描述「做什么」，不写平台分支；安装后随插件加载，需**手动**调用（`disable-model-invocation: true`）。

| 文件 | 说明 |
|------|------|
| `review-current.md` | 并行委派 `spec-compliance-reviewer` 与 `code-quality-reviewer` 审查当前修改 |
| `git-commit.md` | 委派 `git-workflow-manager` 按 git 规范完成暂存与提交 |
| `pycovtest-current.md` | 默认检测当前改动，也支持指定 Git 提交范围（如“最新一个提交”或 `HEAD~2..HEAD`）的 Python 源码覆盖率，并报告未覆盖的改动行或分支 |

更新仓库后运行 `./install.sh` 同步；Cursor 新增 command 后若 `/` 菜单未出现，可 `Cmd+Q` 完全退出后重开。

## Skills 说明

`skills/` 存放跨平台通用 Skill，Cursor 和 Claude Code 共用同一份内容。

| 目录 | 触发场景 | 说明 |
|------|---------|------|
| `article-writing` | 技术文章写作、博客草稿润色时 | 技术文章与文学作品写作指导 |
| `backend-models-standards` | 创建/修改数据库模型、ORM、Schema 时 | 命名、类型、约束、关系、验证等模型规范 |
| `code-quality-review` | 审查代码变更、执行质量标准时 | 正确性、设计、可读性、安全性、性能等综合审查 |
| `brief-mode` | 用户明确要求回答更短、输出更简洁、更省 token，或使用 `/brief-mode` 时 | 可选启用的紧凑回答模式，含清晰优先例外 |
| `context-optimization` | 提到上下文优化、token 成本、KV 缓存等 | 上下文压缩、遮蔽、分区等优化技术 |
| `doc-coauthoring` | 写文档、起草提案、创建规范时 | 协作文档撰写的结构化工作流 |
| `goal-driven-execution` | 多步骤任务、目标模糊、需拆分验证路径时 | 将复杂任务转化为可验证的目标驱动执行计划 |
| `grill-me` | 动手前想理清思路、验证方案时，使用 `/grill-me` | 对计划或设计进行深度追问，逐步澄清关键决策；关键分歧消除后停止 |
| `handoff` | 需要生成交接文档时，显式使用 `/handoff` | 将对话压缩为交接文档，含建议 skills 和下一步行动 |
| `pua` | 用户沮丧/多次失败时，或使用 `/pua` 指令时 | 大厂 PUA 压力驱动的高能动性 Agent |
| `shell-scripting` | 编写 Shell 脚本时 | 防御性编程、ShellCheck 合规、安全实践 |
| `skill-authoring` | 创建、审查、裁剪或迁移 Agent Skill 时 | SKILL.md 编写、触发描述优化、查重和维护验证 |
| `systematic-debugging` | 遇到 bug、测试失败、意外行为时 | 四阶段系统化调试方法，强制根因分析 |
| `tdd` | 编写或修改生产代码前自动触发，要求测试先行 | 纵向切片 Red-Green-Refactor 工作流 |
| `zoom-out` | 不熟悉某段代码需要全局视图时，使用 `/zoom-out` | 先探索相关代码，再提升一层抽象，给出模块、调用关系与下一步阅读建议 |

## Token 优化

本仓库的 token 优化目标是降低长期提示和多 Agent 协作的固定开销，同时保留安全、质量和可读性边界。默认启用的优化包括：

- 常驻规则和 `claude.global.md` 已压缩重复表达，减少每轮都可能进入上下文的文本
- 高频 `commands/` 和 `agents/` 收紧输出契约，默认先给结论、阻塞项和验证状态
- `brief-mode` 是可选 Skill，仅在用户明确要求更短、更简洁、更省 token，或显式使用 `/brief-mode` 时触发

不会为了省 token 压缩危险操作、不易回滚步骤、多步易误解流程、失败根因说明、需求澄清或用户明确要求的详细解释。此类场景优先保证清晰、风险提示和可执行性。

### 验证方法

使用安装脚本的只读统计命令，对固定热点文件集合输出行数和字符数：

```bash
./install.sh --token-report
./install.sh --token-report HEAD~3
diff -u <(./install.sh --token-report HEAD~3) <(./install.sh --token-report)
```

统计范围包括常驻入口规则、三个高频 commands、四个高频 agents 和 `brief-mode`。字符数只是 token 的近似指标；同一批文件、同一命令、同一 Git ref 之间对比才有意义。

解读时优先看分类合计：`always-on` 代表固定输入成本，`command` 和 `agent` 代表协作输出契约，`optional-skill` 代表显式启用的紧凑模式。新增文件在旧版本中会显示为 `MISSING`，不会计入旧版本合计。

## 配置备份

`config/` 目录存放各类配置备份，详见 [config/README.md](config/README.md)。

| 文件 | 说明 |
|------|------|
| `config/command-allowlist.txt` | Cursor Command Allowlist，每行一个命令，逗号结尾 |

## Skills 来源

| Skill | 来源 |
|-------|------|
| `article-writing` | 自定义 |
| `backend-models-standards` | 自定义 |
| `code-quality-review` | [rsmdt/the-startup](https://github.com/rsmdt/the-startup/tree/main/plugins/team/skills/quality/code-quality-review)（已翻译为中文并补充内容） |
| `brief-mode` | 自定义 |
| `context-optimization` | [muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)（已翻译为中文） |
| `doc-coauthoring` | 自定义 |
| `goal-driven-execution` | [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)（源自 Goal-Driven Execution 原则，已翻译并扩展） |
| `grill-me` | [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me)（已翻译为中文） |
| `handoff` | [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff)（已翻译为中文，临时目录规范按项目约定调整） |
| `pua` | [tanweai/pua](https://github.com/tanweai/pua)（已翻译并按本仓库场景裁剪） |
| `shell-scripting` | 自定义 |
| `skill-authoring` | [rsmdt/the-startup](https://github.com/rsmdt/the-startup/tree/main/plugins/start/skills/writing-skills)（参考其 skill 编写/审查流程，已按本仓库结构裁剪） |
| `systematic-debugging` | [obra/superpowers](https://github.com/obra/superpowers)（已翻译为中文并精简） |
| `tdd` | 综合参考 [obra/superpowers](https://github.com/obra/superpowers/tree/main/skills/test-driven-development)、[mattpocock/skills](https://github.com/mattpocock/skills/tree/HEAD/skills/engineering/tdd)、[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills/tree/main/skills/test-driven-development)、[glebis/claude-skills](https://github.com/glebis/claude-skills/tree/main/tdd)（已按本仓库结构裁剪） |
| `zoom-out` | 源自 `mattpocock/skills` 已删除的 `zoom-out` skill（已翻译为中文并按本仓库场景调整） |

## 参考资料

- [Cursor Rules 文档](https://docs.cursor.com/context/rules)
- [Agent Skills 介绍](https://docs.cursor.com/context/skills)
- [SkillHub - Skills 社区](https://www.skillhub.club/)
- [obra/superpowers](https://github.com/obra/superpowers)