Hook 系统技术文档

1. 概述

Hook 系统允许 Skill 在 Agent 流程的 5 个检查点声明式注入/拔出提示词消息。

设计理念：insert → remove（源自酒馆破限模式）。非持久 hook 在 LLM 调用前插入、调用后拔出；持久 hook 注入后 yield 回前端，由前端持久化到 conversationHistory。

核心约束：后端无状态。持久 hook 必须经前端存储才能跨请求生存。

---

2. 模块结构

skills_engine/
├── hooks_config.py       HookInfo dataclass + scan_hooks()
├── hook_manager.py       HookManager（inject / remove 逻辑）
├── skills_config.py      已有
├── skills_context_manager.py  已有
└── __init__.py           导出 HookInfo, scan_hooks, HookManager

文件级配置位于各 Skill 目录：

skills/<skill-name>/hooks/
├── hooks.json            元数据
└── *.md                  提示词文本

---

3. hooks.json 配置

{
  "hooks": [
    {
      "name": "truncated-content-hint",
      "file": "truncated-content-hint.md",
      "timing": "after_tool_call",
      "role": "system",
      "persistent": false,
      "tool_filter": ["read_file", "search_text"]
    }
  ]
}

字段	类型	必填	说明
name	string	✓	hook 唯一标识
file	string	✓	.md 文件名（相对于 hooks/）
timing	string	✓	5 种检查点之一
role	string	✓	"system" 或 "user"
persistent	bool	✓	是否持久
tool_filter	string[]	否	仅 after_tool_call 时有效

---

4. 检查点总览

timing	代码位置	作用域
after_user_input	chat_stream() 开头	整个请求
before_planning	_run_planning_round() 开头	规划轮
before_first_agent	Agent 循环第一轮	整个 Agent loop
before_each_agent	Agent 循环每一轮	当轮
after_tool_call	工具执行完毕后	当轮注入 → 下一轮 LLM 可见

before_first_agent 和 before_each_agent 不互斥，第一轮同时触发。

---

5. Agent 流程与检查点位置

---

6. 各 Hook 类型完整生命周期

6.1 after_user_input（非持久）

请求级作用域。整个 chat_stream() 期间存活，不主动 remove。

6.2 after_user_input（持久）

与非持久版本相同的注入位置，但额外 yield 回前端存储。每次请求都注入（无去重），跨请求通过前端 conversationHistory 带回。

6.3 before_planning

规划轮作用域。仅影响规划轮 LLM 调用。

6.4 before_each_agent

单轮作用域。每轮 inject 前先 remove 上一轮的。

6.5 before_first_agent

Agent loop 作用域。第一轮注入，所有轮次可见，循环结束后 remove。

6.6 after_tool_call

跨轮作用域。当轮工具完成后注入 → 下一轮 LLM 可见 → 下一次 inject 前 remove。

---

7. Remove 规则总表

timing	remove 时机	代码位置	设计意图
after_user_input	不主动 remove	—	函数返回时 GC 回收
before_planning	规划轮 LLM 调用后	_run_planning_round() 末尾	仅规划轮可见
before_each_agent	下一轮 inject 前	循环体开头	每轮 LLM 看完再拔
before_first_agent	Agent 循环结束后	while 之后	生命周期 = 整个 loop
after_tool_call	下一次 inject 前	工具执行分支内	下一轮 LLM 看完再拔
系统 step_ref	每步末尾	两个分支各自 remove	与 hook 系统独立

通用原则：remove 紧跟在对应 inject 之前，保证 LLM 在调用时能看到 hook。

---

8. 持久 hook 行为

持久 hook 与非持久 hook 的区别：

	非持久	持久
inject()	注入 messages，不返回	注入 messages，返回 hook 信息供 yield 给前端
remove()	从 messages 移除	不移除（no-op，放回 _injected 记录）
去重	无	无（每次触发都注入，不做任何去重）
跨请求	不跨请求（函数返回即消失）	前端存入 conversationHistory，下次请求带回

注意：持久 hook 不去重意味着跨请求时 messages 中可能存在多份相同 hook（前端带回的 + 本次新注入的）。这是设计如此——hook 内容通常是短小提示，冗余不影响效果。

---

9. 数据流

---

10. 核心 API

HookManager

class HookManager:
    def __init__(self, full_messages: list, hooks: List[HookInfo])
    def inject(self, timing: str, **kwargs) -> List[dict]
    def remove(self, timing: str) -> None
    def inject_prompt(self, content: str, role: str = "system") -> dict
    def remove_prompt(self, msg_ref: dict) -> None

方法	作用	返回
inject(timing)	注入匹配 hook（无去重，每次触发都注入）。持久 hook 返回信息供 yield	[{"name", "role", "content"}, ...]
remove(timing)	非持久 hook：从 messages 移除；持久 hook：不移除（no-op）	None
inject_prompt(content)	插入系统内置提示词	消息引用（dict）
remove_prompt(ref)	按引用移除	None

scan_hooks

def scan_hooks(enabled_skills: List[str], skills_dir: str = None) -> List[HookInfo]

扫描已启用 skills 的 hooks/ 目录，校验并加载 hooks.json + .md 文件。

---

11. 与系统内置提示词的关系

系统内置 3 个提示词（planning_prompt、first_step_prompt、agent_loop_prompt）通过 inject_prompt() / remove_prompt() 管理。两者共用 HookManager 操作同一个 full_messages，但逻辑独立：

	系统提示词	Skill Hook
配置方式	config.py 硬编码	hooks.json 声明式
生命周期	每步结束必拔	按 timing 规则管理
持久化	不持久	可选
前端感知	无	type: "hook" 消息