mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-08-21 12:17:15 +02:00
Luong NGUYEN
deb7e5c710
* docs: sync to Claude Code v2.1.233 Bring the tutorial from the v2.1.220 baseline up to v2.1.233 (13 releases) per update-plan-2026-08-15.md. Corrections: - Remove /ultraplan (removed in v2.1.222); point at plan mode instead - Drop the 200-subagent-per-session cap and CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (cap removed in v2.1.224) - Note TaskCompleted/TaskCreated only fire when todo tools are enabled Updates: - /review documented as an alias of /code-review (v2.1.223) - fork subagents default to interactive (v2.1.232) - ultrareview v2.1.227 floor, --post/--no-post - GitLab MR support for -w/--worktree and Agent View New sections: - Cross-session messaging (ListAgents, SendMessage, crossSessionInbound) - Sandbox credential masking (v2.1.221, v2.1.224) - Trust and permission scoping - archive and command plugin sources, conditional plugin activation - claude self-hosted-runner, 7 new env vars Translations (vi/ja/zh/uk) mirrored where the corresponding pages exist. Every modified file carries the 2.1.233 metadata footer; files already at 2.1.220 with no content change were left alone. * docs: address review findings from the v2.1.233 sync - Mirror the /review alias correction (v2.1.223) into vi/ja/uk/zh 01-slash-commands: add the live alias row, drop the stale row from the deprecated table, and rewrite the history bullet. All four still called /review deprecated in favour of a code-review plugin while carrying a 2.1.233 stamp. - Rewrite the 10-cli CLAUDE_CODE_FORK_SUBAGENT row to agree with 04-subagents: fork mode is on by default in interactive sessions on every build since v2.1.232; the variable enables it where it is off by default. - Remove a stray blank line that split the 10-cli environment-variable table, leaving the seven new v2.1.221-v2.1.233 rows without a delimiter row and rendering them as literal pipe text. - Add the todo-tools caveat to the TaskCompleted row alongside TaskCreated in claude_concepts_guide, uk/ja concepts guides, and the uk/vi/zh/ja CATALOGs. - Fix the ja 07-plugins and 09-advanced-features footers, which paired a 2.1.233 version stamp with an April 24 last-updated date. * docs(subagents): correct the stale fork-subagent claim in ja pages (#171) ja/10-cli and ja/04-subagents both stated that CLAUDE_CODE_FORK_SUBAGENT only enables forked subagents on external builds (Bedrock, Vertex, Foundry) with no effect on the Anthropic API. That was true at v2.1.117 but has been wrong since v2.1.232: fork mode is on by default in interactive sessions on every build, first-party or not, and the variable now turns it on where it is off by default (claude -p, the Agent SDK, or Claude Code older than v2.1.232). Both pages remain stamped 2.1.119 on purpose. Only the individual claim was verified and corrected; bumping the page stamp would assert a whole-page verification that has not been done. Do not bump these stamps without a full resync of the pages.
120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
|
||
<img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
|
||
</picture>
|
||
|
||
# Hooks 参考
|
||
|
||
Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令，用来做格式化、校验、通知、审计等自动化工作。
|
||
|
||
## 概览
|
||
|
||
Hooks 是事件驱动的自动化机制。它们会在 Claude Code 发生某些动作时自动运行，不需要你手动触发。
|
||
|
||
常见用途：
|
||
|
||
- 写文件前自动格式化
|
||
- 提交前运行测试
|
||
- 扫描安全问题
|
||
- 记录 bash 命令
|
||
- 校验用户提示词
|
||
- 发送团队通知
|
||
|
||
## Hook 类型
|
||
|
||
Claude Code 支持 31 个 hook 事件，按用途分为以下 4 组。事件的 handler 类型共 5 种：`command`、`http`、`mcp_tool`、`prompt`、`agent`。
|
||
|
||
- **Tool Hooks**：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PostToolBatch`、`PermissionRequest`、`PermissionDenied`
|
||
- **Session Hooks**：`SessionStart`、`Setup`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`
|
||
- **Task Hooks**：`UserPromptSubmit`、`UserPromptExpansion`、`MessageDisplay`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`（`TaskCompleted` 和 `TaskCreated` 仅在启用 todo 工具时触发 —— 在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上默认关闭；`CLAUDE_CODE_ENABLE_TODO_TOOLS=1` 可恢复）
|
||
- **Lifecycle Hooks**：`ConfigChange`、`CwdChanged`、`DirectoryAdded`、`FileChanged`、`PreCompact`、`PostCompact`、`WorktreeCreate`、`WorktreeRemove`、`Notification`、`InstructionsLoaded`、`Elicitation`、`ElicitationResult`
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
mkdir -p ~/.claude/hooks
|
||
cp 06-hooks/*.sh ~/.claude/hooks/
|
||
chmod +x ~/.claude/hooks/*.sh
|
||
```
|
||
|
||
然后在 `~/.claude/settings.json` 里配置：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "Write",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "~/.claude/hooks/format-code.sh"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Write",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "~/.claude/hooks/security-scan.sh"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
Hooks 会在匹配到事件时自动执行。你可以把它理解成 Claude Code 的事件回调。
|
||
|
||
## 常见示例
|
||
|
||
- `format-code.sh` - 写入前自动格式化
|
||
- `pre-commit.sh` - 提交前跑测试
|
||
- `security-scan.sh` - 做安全扫描
|
||
- `log-bash.sh` - 记录 bash 命令
|
||
- `validate-prompt.sh` - 校验输入
|
||
- `notify-team.sh` - 发通知
|
||
|
||
## 最佳实践
|
||
|
||
- 把 hooks 保持短小明确
|
||
- 只做单一职责
|
||
- 先在本地测试
|
||
- 不要在 hook 里放复杂业务逻辑
|
||
- 对副作用保持谨慎
|
||
|
||
## 故障排查
|
||
|
||
- 检查文件路径和权限
|
||
- 确认脚本可执行
|
||
- 检查 settings.json 语法
|
||
- 查看 Claude Code 版本兼容性
|
||
|
||
## 相关概念
|
||
|
||
- [Checkpoints and Rewind](../08-checkpoints/README.md)
|
||
- [Slash Commands](../01-slash-commands/README.md)
|
||
- [Skills](../03-skills/README.md)
|
||
- [Subagents](../04-subagents/README.md)
|
||
- [Plugins](../07-plugins/README.md)
|
||
- [Advanced Features](../09-advanced-features/README.md)
|
||
|
||
## 更多资源
|
||
|
||
- [Memory Guide](../02-memory/README.md)
|
||
- [Official Hooks Documentation](https://code.claude.com/docs/en/hooks)
|
||
- [CLI Reference](https://code.claude.com/docs/en/cli-reference)
|
||
|
||
---
|
||
|
||
**最后更新**: 2026 年 8 月 15 日
|
||
**Claude Code 版本**: 2.1.233
|
||
**来源**:
|
||
- https://code.claude.com/docs/en/hooks
|