1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
# HOOK.yaml - Hook 配置示例模板
#
# 此文件为模板示例，展示了 HOOK.yaml 的完整配置格式。
# 创建新 hook 时，复制此目录结构并修改：
# .jcli/hooks/<your_hook_name>/HOOK.yaml
#
# 注意：文件名支持 HOOK.yaml 或 HOOK.yml，两者共存时优先取 HOOK.yaml。
#
# Hook 目录结构：
# .jcli/hooks/<hook_name>/
# ├── HOOK.yaml # hook 定义（也支持 HOOK.yml）
# └── script.sh # 可选脚本（bash hook 可直接用文件名调用）
#
# Hook 支持三级来源：
# 1. 项目级：.jcli/hooks/<hook_name>/HOOK.yaml
# 2. 用户级：~/.jdata/agent/hooks/<hook_name>/HOOK.yaml
# 3. 会话级：通过 RegisterHook 工具动态注册
# ============================================
# 字段说明
# ============================================
# events: [必填] 绑定的事件列表，一个 hook 可绑定多个事件
# 可用事件：
# - pre_send_message # 用户发送消息前（可修改 user_input）
# - post_send_message # 用户发送消息后（仅通知）
# - pre_llm_request # LLM API 请求前（可修改 messages、system_prompt）
# - post_llm_response # LLM 回复完成后（可修改 assistant_output）
# - pre_tool_execution # 工具执行前（可修改 tool_arguments，action=skip）
# - post_tool_execution # 工具执行成功后（可修改 tool_result）
# - post_tool_execution_failure # 工具执行失败后（可修改 tool_error）
# - stop # LLM 即将结束回复
# - pre_micro_compact # 轮次级压缩前
# - post_micro_compact # 轮次级压缩后
# - pre_auto_compact # 全量压缩前
# - post_auto_compact # 全量压缩后
# - session_start # 会话启动时
# - session_end # 会话退出时
# type: [可选] hook 类型，默认 bash
# - bash: 通过 sh -c 执行 Shell 命令
# - llm: 通过 prompt 模板调用 LLM
# command: [type=bash 时必填] Shell 命令
# - hook 目录在 PATH 中，脚本可直接用文件名调用
# prompt: [type=llm 时必填] LLM prompt 模板
# - 支持模板变量：{{event}}, {{user_input}}, {{assistant_output}},
# {{tool_name}}, {{tool_arguments}}, {{tool_result}}, {{model}}, {{cwd}}
# model: [type=llm 时可选] 覆盖当前使用的模型名
# timeout: [可选] 超时秒数，bash 默认 10，llm 默认 30
# retry: [可选] 重试次数，默认 0（bash）/ 1（llm）
# on_error: [可选] 失败策略，默认 skip
# - skip: 记录日志继续执行后续 hook
# - stop: 中止整条 hook 链
# filter: [可选] 条件过滤，仅当匹配时执行
# - tool_name: 工具名精确匹配
# - tool_matcher: 工具名模式匹配（管道分隔，如 "Bash|Write|Edit"）
# - model_prefix: 模型名前缀匹配
# ============================================
# 示例配置（取消注释即可使用）
# ============================================
# --- 示例 1：Bash hook - 基础配置 ---
# events: [pre_send_message]
# type: bash
# command: script.sh
# timeout: 5
# on_error: skip
# --- 示例 2：LLM hook - AI 回复纠查官 ---
# events: [post_llm_response]
# type: llm
# prompt: |
# 检查以下 AI 回复是否包含敏感信息（密码、密钥、token）：
# {{assistant_output}}
# 如果包含敏感信息，返回 {"action":"stop","retry_feedback":"请移除敏感信息"}。
# 如果没有问题，返回空 JSON {}。
# timeout: 30
# retry: 1
# on_error: skip
# --- 示例 3：多事件绑定 ---
# events: [pre_send_message, post_send_message]
# type: bash
# command: log.sh
# timeout: 5
# --- 示例 4：带过滤器的工具审查 ---
# events: [pre_tool_execution]
# type: llm
# prompt: |
# 审查工具调用是否安全：工具={{tool_name}}, 参数={{tool_arguments}}
# 如果不安全，返回 {"action":"skip"}。
# 如果安全，返回 {}。
# filter:
# tool_matcher: "Bash|Shell"
# timeout: 15
# retry: 1
# --- 示例 5：消息审查 + 指定模型 ---
# events: [pre_send_message]
# type: llm
# prompt: |
# 审查用户消息是否合规：{{user_input}}
# 如有违规返回 {"action":"stop","retry_feedback":"消息不合规：原因"}。
# model: gpt-4o-mini
# timeout: 15
# retry: 1
# ============================================
# HookResult JSON 字段参考（脚本 stdout 返回）
# ============================================
#
# 返回的 JSON 只包含要修改的字段，空 {} 表示无修改：
#
# | 字段 | 生效事件 | 说明 |
# |--------------------|-----------------------------------------|------|
# | user_input | pre_send_message | 替换用户消息 |
# | assistant_output | post_llm_response | 替换 AI 回复 |
# | messages | pre_llm_request, post_*_compact | 替换消息列表 |
# | system_prompt | pre_llm_request | 替换系统提示词 |
# | tool_arguments | pre_tool_execution | 替换工具参数 |
# | tool_result | post_tool_execution | 替换工具结果 |
# | tool_error | post_tool_execution_failure | 替换错误信息 |
# | inject_messages | pre_llm_request | 追加消息到末尾 |
# | retry_feedback | pre*/stop/post_llm_response | 带反馈重试 |
# | additional_context | pre_llm_request, stop, pre_auto_compact | 追加到 system_prompt |
# | system_message | 所有事件 | 展示给用户的提示 |
# | action | 大部分事件 | "stop" 中止 / "skip" 跳过 |
#
# 完整文档请运行：jcli ai help hook