Hook 生命周期管理 (hook)
Headless 命令 — 不依赖桌面 GUI，直接使用核心包运行。适用于服务器、CI/CD、容器化等无桌面环境。
核心特性
- 🪝 28 种事件类型: 涵盖笔记、会话、AI、系统等全生命周期事件
- ⚡ 同步/异步执行: 支持 SYNC（阻塞）和 ASYNC（非阻塞）两种执行模式
- 🎯 优先级系统: SYSTEM / HIGH / NORMAL / LOW / MONITOR 五级优先级
- 🔍 通配符匹配: 支持 wildcard 和 regex 两种事件匹配模式
- 📊 执行统计: 自动记录每个 Hook 的执行次数、成功率、平均耗时
- 🔌 热插拔: 运行时动态注册/注销 Hook，无需重启
概述
ChainlessChain CLI 提供完整的生命周期 Hook 管理系统，允许在系统关键事件触发时执行自定义逻辑。Hook 系统支持精细化的事件过滤、优先级排序和执行模式控制，适用于数据同步、自动备份、审计日志、工作流触发等场景。
每个 Hook 绑定一个事件名（支持通配符如 note:*），并在事件触发时按优先级顺序执行。SYNC 模式下 Hook 可以修改事件数据或中止事件传播，ASYNC 模式下 Hook 在后台运行不影响主流程。
命令参考
hook list — 列出已注册的 Hook（默认）
bash
chainlesschain hook list
chainlesschain hook list --event "note:created" # 按事件过滤
chainlesschain hook list --enabled # 仅显示已启用
chainlesschain hook list --json # JSON 输出
chainlesschain hook # 等同于 hook list显示所有已注册的 Hook，包含事件、类型、优先级、启用状态等信息。
hook add — 注册新 Hook
bash
chainlesschain hook add <event> <name> --handler <code>
chainlesschain hook add "note:created" "auto-tag" --handler "console.log('new note')"
chainlesschain hook add "note:*" "note-logger" --type ASYNC --priority LOW
chainlesschain hook add "ai:response" "audit" --matcher regex --pattern ".*:response"注册一个新的 Hook，绑定到指定事件。可通过 --type 设置同步/异步，--priority 设置优先级，--matcher 设置匹配模式。
hook remove — 注销 Hook
bash
chainlesschain hook remove <hook-id>根据 Hook ID 注销指定 Hook，立即生效。
hook run — 手动触发事件
bash
chainlesschain hook run <event>
chainlesschain hook run "note:created" --data '{"noteId":"abc123"}'
chainlesschain hook run "system:startup" --json手动触发指定事件，执行所有匹配的 Hook。可通过 --data 传入事件数据。
hook stats — 查看执行统计
bash
chainlesschain hook stats
chainlesschain hook stats --json显示所有 Hook 的执行统计，包括总执行次数、成功次数、失败次数、平均耗时。
hook events — 列出支持的事件类型
bash
chainlesschain hook events
chainlesschain hook events --json列出所有 28 种支持的事件类型及其说明。
事件类型
| 分类 | 事件 | 说明 |
|---|---|---|
| 笔记 | note:created, note:updated, note:deleted | 笔记生命周期 |
| 会话 | session:started, session:ended | 会话管理 |
| AI | ai:request, ai:response, ai:error | AI 交互事件 |
| 系统 | system:startup, system:shutdown, system:error | 系统级事件 |
| 同步 | sync:push, sync:pull, sync:conflict | 数据同步事件 |
数据库表
| 表名 | 说明 |
|---|---|
hooks | Hook 注册信息（事件、名称、类型、优先级、处理函数） |
hook_stats | 执行统计（执行次数、成功/失败、平均耗时） |
系统架构
用户命令 → hook.js (Commander) → hook-manager.js
│
┌────────────────┼────────────────┐
▼ ▼ ▼
事件匹配引擎 优先级排序器 执行统计收集
│ │ │
▼ ▼ ▼
wildcard/regex SYNC/ASYNC 执行 hooks/hook_stats 表关键文件
packages/cli/src/commands/hook.js— 命令实现packages/cli/src/lib/hook-manager.js— Hook 管理库
使用示例
场景 1：文件修改后自动格式化
bash
# 注册一个 Hook，在文件修改时自动运行 Prettier
chainlesschain hook add --event FileModified \
--type command \
--command "npx prettier --write {filePath}" \
--priority 500 \
--pattern "*.ts|*.js"
# 验证 Hook 是否注册成功
chainlesschain hook list --event FileModified场景 2：工具调用前的安全拦截
bash
# 拦截危险的文件删除操作
chainlesschain hook add --event PreToolUse \
--type sync \
--command "echo BLOCKED: Dangerous operation" \
--pattern "rm -rf*|deltree*"
# 手动触发测试
chainlesschain hook run PreToolUse --context '{"tool":"bash","args":"rm -rf /"}'场景 3：Git 提交前代码检查
bash
chainlesschain hook add --event PreGitCommit \
--type script \
--command "npm run lint && npm test" \
--priority 100故障排查
Hook 未触发
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| Hook 已注册但不执行 | 事件名拼写错误 | 运行 chainlesschain hook events 查看支持的事件列表 |
| Hook 执行但无效果 | 优先级配置不当 | 检查 --priority，SYSTEM(0) 最先执行，MONITOR(1000) 最后 |
| Command 类型 Hook 报错 | 命令路径不正确 | 使用绝对路径或确保命令在 PATH 中 |
| Pattern 不匹配 | 正则/通配符语法错误 | 使用 chainlesschain hook list 查看已注册的 pattern |
常见错误
bash
# 错误: "Hook event not found"
# 原因: 使用了不支持的事件名
# 修复: 查看支持列表
chainlesschain hook events
# 错误: "Database not available"
# 原因: 数据库未初始化
# 修复:
chainlesschain db init安全考虑
- 命令注入防护: Command/Script 类型的 Hook 会执行外部命令，避免将用户输入直接拼接到
--command参数中 - 优先级控制: SYSTEM(0) 级别的 Hook 仅限系统内部使用，用户自定义 Hook 建议使用 NORMAL(500) 或 LOW(900)
- Pattern 验证: 正则表达式 pattern 会编译执行，不信任来源的 pattern 可能导致 ReDoS（正则拒绝服务）
- 审计追踪: 所有 Hook 执行都记录统计信息（执行次数、错误次数、平均耗时），可通过
hook stats监控异常 - 脚本隔离: Script 类型 Hook 应限制文件系统访问范围，避免执行未经审查的外部脚本