Kimi Code CLI 贡献指南：prek 钩子与 `make` 驱动的开发工作流全解析-创锋一号

Kimi Code CLI 贡献指南：prek 钩子与`make`驱动的开发工作流全解析

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli

本文基于 CONTRIBUTING.md 编写，系统讲解如何向 Kimi Code CLI（一个运行在终端中的 Python CLI 智能体）提交高质量的 Pull Request：从贡献准则、prek git 钩子的两种安装方式，到仓库底层由make format-*/make check-*目标构成的格式化与静态检查流水线，并延伸介绍提交信息规范、版本策略与测试入口。读完本文，你将掌握一套"克隆即用、提交即检"的仓库级开发规范，能够以符合项目预期的方式参与开发。

一、贡献准则：先对齐路线图，再动手写代码

Kimi Code CLI 欢迎所有类型的贡献，包括 bug 修复、新特性、文档改进和错别字修正。但为了维护高质量的代码库与用户体验，CONTRIBUTING.md 明确了两条硬性准则：

只合并与项目路线图对齐的 PR：任何改动超过 100 行的 Pull Request，强烈建议在动手前先通过 issue 与维护者讨论，否则 PR 可能被直接关闭或忽略而不进入评审流程。
坚持高代码质量：提交的代码质量应达到（甚至超过）前沿编码智能体写出的水平；合并前可能被要求修改。

这两条准则背后有仓库实际工程实践的支撑——从根目录 Makefile 可以看到，项目为代码质量配备了完整的工具链：ruff（lint + format）、pyright（类型检查）、ty（类型注释检查）、pytest+pytest-asyncio（测试）、biome + tsc（web 前端），并全部通过统一的make目标对外暴露。

二、prek 钩子：让格式化和检查在每次提交时自动执行

2.1 prek 是什么

项目使用 prek 作为 git hooks 运行器来执行格式化与检查。与传统的 pre-commit 不同，prek 支持workspace 模式：在多包仓库中，只对"发生了文件变更"的子项目运行对应的钩子，从而避免每次提交都对全部包做全量检查。

Kimi Code CLI 是一个 uv workspace 仓库，根目录 pyproject.toml 的[tool.uv.workspace]声明了 4 个成员包：

packages/kosong（LLM 抽象层）
packages/kaos（pykaos，操作系统交互抽象层）
packages/kimi-code
sdks/kimi-sdk

因此 prek 的 workspace 模式正好匹配仓库结构——只有改动的包会跑自己的钩子。

2.2 推荐安装方式：一条`make prepare`

仓库为开发者提供了推荐的一键配置，直接执行：

make prepare

查看 Makefile 可知该目标实际做了两件事：

.PHONY: prepare prepare: download-deps install-prek ## Sync dependencies for all workspace packages and install prek hooks. @echo "==> Syncing dependencies for all workspace packages" @uv sync --frozen --all-extras --all-packages

download-deps：通过 src/kimi_cli/deps/Makefile 下载 ripgrep 二进制（rg，供 grep 工具使用，默认版本 15.0.0，支持 macOS/Linux/Windows 的多架构映射）；
install-prek：uv tool install prek安装 prek，再用uv tool run prek install把钩子安装进当前 git 仓库；
最后用uv sync --frozen --all-extras --all-packages同步所有 workspace 包的依赖（--frozen表示严格按uv.lock锁定版本，不做升级）。

安装完成后，每次git commit都会自动运行钩子。在发送 PR 前，还可以手动对所有文件做一次全量检查：

prek run --all-files

2.3 手动安装方式：不想用`make prepare`时

如果不希望引入make prepare，也可以手动安装（任选其一安装 prek）：

# 方式一：通过 uv 安装（推荐，仓库本身基于 uv 管理） uv tool install prek # 方式二：通过 pipx 安装 pipx install prek # 方式三：通过 pip 安装 pip install prek

然后在本仓库中安装钩子：

prek install

2.4 钩子到底执行了什么

CONTRIBUTING.md 明确指出：钩子执行的是对应的make format-*和make check-*目标，因此必须确保依赖已安装（通过make prepare或uv sync）。

从 Makefile 可以看到这些目标的真实构成。以主包 kimi-cli 为例：

format-kimi-cli: ## Auto-format Kimi Code CLI sources with ruff. @uv run ruff check --fix @uv run ruff format check-kimi-cli: ## Run linting and type checks for Kimi Code CLI. @uv run ruff check @uv run ruff format --check @uv run pyright @uv run ty check || true

也就是说，一次提交钩子背后实际跑的是：

ruff check --fix / ruff check：lint 并尽可能自动修复；
ruff format / ruff format --check：代码格式化；
pyright：类型检查（根 pyproject.toml 中typeCheckingMode = "standard"，src/kimi_cli/**/*.py走 strict 模式）；
ty check（非阻塞）：类型注释检查，注意|| true让它失败也不阻塞提交。

仓库级的总入口还有：

make format # 依次格式化 kimi-cli / kosong / pykaos / kimi-sdk / web 五个包 make check # 依次对五个包执行 lint + 类型检查

其中 web 前端包使用npm run format/npm run lint+npm run typecheck（biome + tsc），且会在缺少 npm 时明确报错提示先安装 Node.js。

2.5 如何跳过钩子

对于中间提交（例如"先存个档再继续改"的场景），可以用：

git commit --no-verify

跳过钩子；但最终提交前仍建议手动执行一次prek run --all-files或make format/make check确认全绿。

三、一次完整的贡献流程：从 clone 到 PR

结合 CONTRIBUTING.md、根 Makefile 与 AGENTS.md，一次规范的贡献流程如下：

# 1. 克隆仓库（只读浏览时可跳过前两步） git clone <仓库地址> cd kimi-cli # 2. 安装依赖 + prek 钩子 make prepare # 3. 创建特性分支、完成代码修改 git checkout -b fix/xxx # 4. 提交前本地全量自检 make format make check make test # 运行 kimi-cli 与 tests_e2e 两套测试 # 可选的 AI 测试：make ai-test（用 Kimi Code CLI 自身跑 tests_ai 测试集） # 5. 提交（prek 钩子会自动再次格式化与检查） git add . git commit

其中make test的具体构成（见 Makefile）：

test-kimi-cli: ## Run Kimi Code CLI tests. @uv run pytest tests -vv @uv run pytest tests_e2e -vv

即主测试套件 tests/ 与端到端测试套件 tests_e2e/ 都会执行；pytest.ini 中asyncio_mode = auto表明异步测试无需显式标记即可自动以 asyncio 模式运行。其他 workspace 包（kosong、pykaos、kimi-sdk）也有各自的测试目标，例如 kosong 会以--doctest-modules模式同时执行 doctest。

四、代码风格与质量基线（工具链速查）

根目录 pyproject.toml 定义了全仓库统一的代码风格基线：

工具	职责	关键配置
ruff	lint + format	行宽 100；规则集 E（pycodestyle）、F（Pyflakes）、UP（pyupgrade）、B（flake8-bugbear）、SIM（flake8-simplify）、I（isort）
pyright	类型检查	`typeCheckingMode = "standard"`，pythonVersion 3.14，`src/kimi_cli/*/.py`为 strict
ty	类型注释检查	非阻塞（`\|\| true`），python-version 3.14
typos	拼写检查	通过 pyproject.toml 的`[tool.typos]`配置扩展词表与排除文件
pytest	单元/集成测试	pytest.ini：`asyncio_mode = auto`

测试侧有两点值得注意：

tests/conftest.py 提供了一整套可复用的 fixture（config、llm、session、runtime、toolset、各工具实例等），说明仓库对"工具级测试"有成熟的基建，新增工具时可以复用这些 fixture 快速编写测试；
发布构建前会执行 scripts/inject_build_sha.py 把 git commit SHA 注入包内，用于遥测溯源——这也从侧面说明项目对可追溯性的重视。

五、提交信息与版本管理约定

虽然 CONTRIBUTING.md 正文没有展开，但 AGENTS.md 为贡献者补充了两条直接影响 PR 能否顺利合并的约定：

提交信息使用 Conventional Commits 格式：

<type>(<scope>): <subject>

允许的 type：feat、fix、test、refactor、chore、style、docs、perf、build、ci、revert。

版本采用"只升 minor"策略（适用于仓库内所有包与发布流程）：

Patch 永远是0，绝不手动递增（如0.68.0→0.69.0，绝不出现0.68.1）；
任何变更（特性、改进、bug 修复）都通过递增 minor 体现；
Major 版本仅在显式人工决策时变更。

六、常见问题速查

Q1：make prepare提示 uv 未安装？项目依赖uv管理依赖与工具链（见 Makefile 中大量uv run/uv sync），请先安装 uv 再执行。

Q2：提交时钩子报错、无法通过怎么办？钩子执行的是make format-*与make check-*，先确认依赖已同步（make prepare或uv sync），再手动跑make format修复格式问题、make check定位 lint/类型错误；ty check因|| true不会阻塞提交。

Q3：中间提交不想跑钩子？使用git commit --no-verify，最终提交前再手动prek run --all-files全量检查一遍。

Q4：改动涉及 web 前端（web/目录）？web 包使用 npm 生态（biome + tsc），make format/make check会调用npm --prefix web run ...，需提前安装 Node.js/npm；缺少 npm 时钩子会报错提示而不是静默跳过。

Q5：如何确认改动只触发对应包的钩子？prek 运行在 workspace 模式下，只有发生文件变更的子项目会执行自己的钩子，这正好与仓库的 uv workspace 结构（kosong、kaos、kimi-sdk、kimi-cli）一一对应。

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析