# @claude-flow/hooks 中文文档

规范地址：https://npmcn.com/package/%40claude-flow/hooks/

版本：3\.0\.3
npm 元数据更新时间：2026-11-09T08:36:04.892Z
中文译文更新时间：2026-11-10T00:05:57.942Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40claude-flow/hooks
原文对照：https://npmcn.com/package/%40claude-flow/hooks/?lang=original
项目主页：https://ruv.io/
源码仓库：https://github.com/ruvnet/ruflo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：687 kB，80 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- peer 依赖：@claude-flow/shared ^3\.0\.0
- 首次发布：2026-01-06T21:45:22.683Z
- 最新版本发布：2026-11-09T08:36:04.617Z
- 近 30 天下载量：6325（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

V3 Hooks System - 事件驱动的生命周期钩与理性银行学习融合

## 安装

```sh
npm install @claude-flow/hooks
```

也可以使用：`pnpm add @claude-flow/hooks`、`yarn add @claude-flow/hooks`、`bun add @claude-flow/hooks`

## README

# @ claude- flow/ hooks

![Animated diagram: a lifecycle event reaches the HookRegistry, the HookExecutor runs hooks in priority order, and ReasoningBank learns from the outcome](https://raw.githubusercontent.com/ruvnet/ruflo/main/v3/@claude-flow/hooks/assets/hooks-flow.svg)

**@ claude- flow/ hooks** ——按优先秩序登记并运行生命周期钩(PreEdit,Post Task,会话起止等),并将其结果反馈给ReasoningBank模式学习.

**支持的环境 :** 节点.js 20+- 无害环境管理

## 快速启动

```bash
npm install @claude-flow/hooks
```

```js
import { HookRegistry, HookEvent, HookPriority } from '@claude-flow/hooks';

const registry = new HookRegistry();
registry.register(HookEvent.PreEdit, async () => ({ success: true }), HookPriority.Normal, { name: 'log-edit' });
console.log(registry.getForEvent(HookEvent.PreEdit).map((h) => h.name));
```

预期产出:

```text
[ 'log-edit' ]
```

建造在 [`@claude-flow/shared`](https://www.npmjs.com/package/@claude-flow/shared); 用于 [`@claude-flow/plugins`](https://www.npmjs.com/package/@claude-flow/plugins)。 。 。 .

[![npm version](https://img.shields.io/npm/v/@claude-flow/hooks.svg)](https://www.npmjs.com/package/@claude-flow/hooks) [![npm downloads](https://img.shields.io/npm/dm/@claude-flow/hooks.svg)](https://www.npmjs.com/package/@claude-flow/hooks) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)

> Claude Flow V3 事件驱动的生命周期钩与理性银行学习融合

这个 `@claude-flow/hooks` 软件包为Claude Flow业务的拦截和扩展提供了全面的钩子系统。 它能够实现智能任务路由,模式学习,背景度量衡收集,以及实时状态线集成.

## 特征

-   🎣 **Hook 书记官处** - 优先登记有过滤和管理的钩子
-   ⚡ **Hook 执行器** - 超时处理、错误恢复和结果汇总
-   🤖 **背景守护进程** - 计量收集、群集监测、模式学习
-   👷 **背景工人** - 从事分析、优化和自动化的12名专业人员
-   📊 **状态整合** - 克劳德代码的实时状态显示
-   🧠 **银行学习** - 根据学到的规律确定智能任务路线
-   🔧 **MCP 工具** - 13个MCP工具,用于程序接通
-   🔄 **V2 兼容性** - 向后兼容V2钩命令

## 安装

```bash
# Using npm
npm install @claude-flow/hooks

# Using pnpm
pnpm add @claude-flow/hooks

# Using yarn
yarn add @claude-flow/hooks
```

## 快速启动

### 基本用途

```typescript
import {
  HookRegistry,
  HookExecutor,
  HookEvent,
  HookPriority,
} from '@claude-flow/hooks';

// Create registry and executor
const registry = new HookRegistry();
const executor = new HookExecutor(registry);

// Register a pre-edit hook
registry.register(
  HookEvent.PreEdit,
  async (context) => {
    console.log(`Editing file: ${context.file?.path}`);
    return { success: true };
  },
  HookPriority.Normal,
  { name: 'log-edits' }
);

// Execute hooks
const result = await executor.preEdit('src/app.ts', 'modify');
console.log(`Hooks executed: ${result.hooksExecuted}`);
```

### 以守护进程初始化

```typescript
import { initializeHooks } from '@claude-flow/hooks';

// Initialize full system with background daemons
const { registry, executor, statusline } = await initializeHooks({
  enableDaemons: true,
  enableStatusline: true,
});

// Generate statusline
console.log(statusline.generateStatusline());
```

### 使用 MCP 工具

```typescript
import { hooksMCPTools, getHooksTool } from '@claude-flow/hooks';

// Get specific tool
const routeTool = getHooksTool('hooks/route');

// Execute routing
const result = await routeTool.handler({
  task: 'Implement user authentication',
  includeExplanation: true,
});

console.log(`Recommended agent: ${result.recommendedAgent}`);
console.log(`Confidence: ${result.confidence}%`);
```

## CLI 命令

### 虎克守护进程

管理用于衡量和学习的背景守护进程.

```bash
# Start daemon with default 60s interval
hooks-daemon start

# Start with custom interval (30 seconds)
hooks-daemon start 30

# Stop daemon
hooks-daemon stop

# Check status
hooks-daemon status

# Run pattern consolidation
hooks-daemon consolidate

# Export learned patterns
hooks-daemon export json

# Rebuild HNSW index
hooks-daemon rebuild-index

# Notify activity (for hook integration)
hooks-daemon notify-activity
```

### 现状

为 Claude 代码集成生成状态线输出 .

```bash
# Display formatted statusline
statusline

# Output JSON data
statusline --json

# Compact JSON (single line)
statusline --compact

# Show help
statusline --help
```

**示例输出 :**

```
▊ Claude Flow V3 ● agentic-flow@alpha  │  ⎇ v3
─────────────────────────────────────────────────────
🏗️  DDD Domains    [●●●●●]  5/5    ⚡ 1.0x → 2.49x-7.47x
🤖 Swarm Agents    ◉ [ 5/15]      🟢 CVE 3/3    💾 156 patterns
🔧 Architecture    DDD ●93%  │  Security ●CLEAN  │  Hooks ●ACTIVE
📊 Routing         89% accuracy │  Avg 4.2ms │  1547 operations
─────────────────────────────────────────────────────
```

## 钩子事件

| 活动 | 说明 |
| --- | --- |
| `PreToolUse` | 在任何工具执行之前 |
| `PostToolUse` | 工具执行完成后 |
| `PreEdit` | 文件修改前 |
| `PostEdit` | 在文件修改后 |
| `PreRead` | 文件读取前 |
| `PostRead` | 文件后读取 |
| `PreCommand` | 在 shell 命令执行前 |
| `PostCommand` | 完成 shell 命令后 |
| `PreTask` | 任务开始前 |
| `PostTask` | 任务完成后 |
| `TaskProgress` | 任务执行期间 |
| `SessionStart` | 当会话开始时 |
| `SessionEnd` | 当会话结束时 |
| `SessionRestore` | 恢复上一个会话时 |
| `AgentSpawn` | 当物剂被产出时 |
| `AgentTerminate` | 代理终止时 |
| `PreRoute` | 在任务路径之前 |
| `PostRoute` | 路线决定后 |
| `PatternLearned` | 当学习出新模式时 |
| `PatternConsolidated` | 当模式得到巩固时 |

## 虎克优先事项

| 优先权 | 数值 | 使用大小写 |
| --- | --- | --- |
| `Critical` | 1 000个 | 安全验证,必须先运行 |
| `High` | 100个 | 预处理、准备 |
| `Normal` | 第50条 | 标准钩 |
| `Low` | 10个 | 伐木、计量 |
| `Background` | 1个 | Async 操作, 最后运行 |

## 背景工人

钩子系统包括12个专业背景工人,可以自动或手动地被触发.

### 现有工人

| 工人 | 优先权 | 东. 时间 | 说明 |
| --- | --- | --- | --- |
| `ultralearn` | 常规 | 60岁 | 二. 深入获取和学习知识 |
| `optimize` | 高级 | 30岁 | 性能优化和调整 |
| `consolidate` | 低级 | 20 岁 | 内存合并和清理 |
| `predict` | 常规 | 15岁 | 预装和预期 |
| `audit` | 关键事项 | 45岁 | 安全分析和脆弱性扫描 |
| `map` | 常规 | 30岁 | 编码基础绘图和结构分析 |
| `preload` | 低级 | 10岁 | 资源预装和缓存变暖 |
| `deepdive` | 常规 | 60岁 | 深密码分析和检查 |
| `document` | 常规 | 45岁 | 自动文档生成 |
| `refactor` | 常规 | 30岁 | 代码重构建议 |
| `benchmark` | 常规 | 60岁 | 业绩基准 |
| `testgaps` | 常规 | 30岁 | 测试覆盖面分析 |

### 工人 CLI 命令

```bash
# List all available workers
claude-flow hooks worker list

# Detect triggers from prompt text
claude-flow hooks worker detect --prompt "optimize performance"

# Auto-dispatch when triggers match (confidence ≥0.6)
claude-flow hooks worker detect --prompt "deep dive into auth" --auto-dispatch --min-confidence 0.6

# Manually dispatch a worker
claude-flow hooks worker dispatch --trigger refactor --context "auth module"

# Check worker status
claude-flow hooks worker status

# Cancel a running worker
claude-flow hooks worker cancel --id worker_refactor_1_abc123
```

### 绩效目标

| 度量衡 | 目标 |
| --- | --- |
| 触发检测 | < 5 ms 时 |
| 工人产卵 | < 50 分钟 |
| 最大并行数 | 10个 |

### 用户Prompt 提交集成

工人通过 `UserPromptSubmit` 当即时图案与工人的触发方式相匹配时,有自信的-0.6. 将此添加到您的 Claude 设置 :

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "timeout": 6000,
        "command": "claude-flow hooks worker detect --prompt \"$USER_PROMPT\" --auto-dispatch --min-confidence 0.6"
      }]
    }]
  }
}
```

## MCP 工具

| 工具 | 说明 |
| --- | --- |
| `hooks/pre-edit` | 在文件编辑前获取上下文和建议 |
| `hooks/post-edit` | 记录用于学习的编辑结果 |
| `hooks/route` | 通往最佳代理的路由任务 |
| `hooks/metrics` | 查询学习尺度 |
| `hooks/pre-command` | 评估命令风险 |
| `hooks/post-command` | 记录命令结果 |
| `hooks/daemon-status` | 获取守护进程状态 |
| `hooks/statusline` | 获取状态线数据 |
| `hooks/worker-list` | 列出所有12名背景工作者 |
| `hooks/worker-dispatch` | 按触发类型派遣工人 |
| `hooks/worker-status` | 获得经营工人的地位 |
| `hooks/worker-detect` | 从快速文本中检测工人触发 |
| `hooks/worker-cancel` | 取消运行中的工人 |

## API 参考

### 虎克注册

```typescript
class HookRegistry {
  // Register a hook
  register(
    event: HookEvent,
    handler: HookHandler,
    priority: HookPriority,
    options?: HookRegistrationOptions
  ): string;

  // Unregister a hook
  unregister(hookId: string): boolean;

  // Get hooks for event
  getForEvent(event: HookEvent, enabledOnly?: boolean): HookEntry[];

  // Enable/disable hooks
  enable(hookId: string): boolean;
  disable(hookId: string): boolean;

  // List hooks with filtering
  list(filter?: HookListFilter): HookEntry[];

  // Get statistics
  getStats(): HookRegistryStats;
}
```

### Hook 执行器

```typescript
class HookExecutor {
  // Execute hooks for any event
  execute<T>(
    event: HookEvent,
    context: Partial<HookContext<T>>,
    options?: HookExecutionOptions
  ): Promise<HookExecutionResult>;

  // Convenience methods
  preToolUse(toolName: string, parameters: Record<string, unknown>): Promise<HookExecutionResult>;
  postToolUse(toolName: string, parameters: Record<string, unknown>, duration: number): Promise<HookExecutionResult>;
  preEdit(filePath: string, operation: 'create' | 'modify' | 'delete'): Promise<HookExecutionResult>;
  postEdit(filePath: string, operation: 'create' | 'modify' | 'delete', duration: number): Promise<HookExecutionResult>;
  preCommand(command: string, workingDirectory?: string): Promise<HookExecutionResult>;
  postCommand(command: string, exitCode: number, output?: string, error?: string): Promise<HookExecutionResult>;
  sessionStart(sessionId: string): Promise<HookExecutionResult>;
  sessionEnd(sessionId: string): Promise<HookExecutionResult>;
  agentSpawn(agentId: string, agentType: string): Promise<HookExecutionResult>;
  agentTerminate(agentId: string, agentType: string, status: string): Promise<HookExecutionResult>;
}
```

### 守护进程管理器

```typescript
class DaemonManager {
  // Register and manage daemons
  register(config: DaemonConfig, task: () => Promise<void>): void;
  start(name: string): Promise<void>;
  stop(name: string): Promise<void>;
  restart(name: string): Promise<void>;

  // Bulk operations
  startAll(): Promise<void>;
  stopAll(): Promise<void>;

  // Status
  getState(name: string): DaemonState | undefined;
  getAllStates(): DaemonState[];
  isRunning(name: string): boolean;
}
```

### 状态化

```typescript
class StatuslineGenerator {
  // Register data sources
  registerDataSources(sources: StatuslineDataSources): void;

  // Generate output
  generateData(): StatuslineData;
  generateStatusline(): string;
  generateJSON(): string;
  generateCompactJSON(): string;

  // Configuration
  updateConfig(config: Partial<StatuslineConfig>): void;
  invalidateCache(): void;
}
```

## 环境变量

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `CLAUDE_FLOW_HOOK_TIMEOUT` | Hook 执行超时 | `5000` |
| `CLAUDE_FLOW_REASONINGBANK_ENABLED` | 启用正因银行 | `true` |
| `CLAUDE_FLOW_HOOKS_NAMESPACE` | 学习命名空间 | `hooks-learning` |
| `CLAUDE_FLOW_HOOKS_LOG_LEVEL` | 日志级别 | `info` |
| `CLAUDE_FLOW_SHOW_HOOKS_METRICS` | 在状态行中显示钩子 | `true` |
| `CLAUDE_FLOW_SHOW_SWARM_ACTIVITY` | 在状态行中显示群集 | `true` |
| `CLAUDE_FLOW_SHOW_PERFORMANCE` | 显示绩效目标 | `true` |

## 与克洛德代码合并

添加到您的 Claude 设置(`~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "timeout": 5000,
        "command": "hooks-daemon start"
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "timeout": 3000,
        "command": "hooks-daemon stop"
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "timeout": 100,
        "command": "hooks-daemon notify-activity"
      }]
    }]
  },
  "statusLine": {
    "type": "command",
    "command": "statusline"
  }
}
```

## 相关软件包

-   [@ claude- flow/ 分享](https://npmcn.com/package/%40claude-flow/shared) - 共享公用事业和类型
-   [@ claude- flow/ 神经](https://npmcn.com/package/%40claude-flow/neural) - 神经网络和SONA学习
-   [@ claude- flow/ swarm (英语)](https://npmcn.com/package/%40claude-flow/swarm) - 多机构协调
-   [@ claude- flow/ 记忆](https://npmcn.com/package/%40claude-flow/memory) - AgentDB记忆系统

## 许可证

麻省理工学院 [克洛德流动小组](https://github.com/ruvnet/claude-flow)

* * *

由 [尔 紫外线](https://ruv.io/) • 妇女 [卢夫.io](https://ruv.io/) • 妇女 [来源](https://github.com/ruvnet/ruflo/tree/main/v3/@claude-flow/hooks)

## 常见问题

### @claude-flow/hooks 是什么？

V3 Hooks System - 事件驱动的生命周期钩与理性银行学习融合

### 如何安装 @claude-flow/hooks？

在项目目录运行 npm install @claude-flow/hooks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@claude-flow/shared（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 guidance、statusline、hooks-daemon、claude-flow-hooks，可以用 npx guidance 直接运行。

### @claude-flow/hooks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @claude-flow/hooks 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @claude-flow/hooks 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @claude-flow/hooks 可以商用吗？

@claude-flow/hooks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @claude-flow/hooks 的下载量有多少？

根据 npm 官方下载统计，@claude-flow/hooks 在 2026/10/10 – 2026/11/08 这 30 天内被下载 6,325 次，日均约 211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @claude-flow/hooks 还在维护吗？

最新版本 3\.0\.3 发布于 2026/11/09（今天）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/01/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。