feat: Add HookOutput class hierarchy and documentation for hook system

tt-a1i · tt-a1i · commit 5af76878c72a · 2026-01-01T23:23:09.000+08:00
Added comprehensive HookOutput class hierarchy with specialized implementations for different hook events (BeforeTool, BeforeModel, AfterModel, BeforeToolSelection). Included factory function for creating appropriate HookOutput instances and detailed documentation explaining each class's capabilities and methods. This enhances the hook system's flexibility and provides clear patterns for hook output handling and modification.
diff --git a/src/pages/HookSystem.tsx b/src/pages/HookSystem.tsx
@@ -272,6 +272,81 @@ export class BeforeModelHookOutput extends DefaultHookOutput {
   }
 }`;
 
+  // 完整的 HookOutput 类层次结构
+  const hookOutputHierarchyCode = `// packages/core/src/hooks/types.ts
+
+// 基类：DefaultHookOutput
+export class DefaultHookOutput implements HookOutput {
+  constructor(
+    public readonly continue?: boolean,
+    public readonly stopReason?: string,
+    public readonly suppressOutput?: boolean,
+    public readonly systemMessage?: string,
+    public readonly decision?: HookDecision,
+    public readonly reason?: string,
+    public readonly hookSpecificOutput?: Record<string, unknown>,
+  ) {}
+
+  // 是否是阻止性决策（block/deny）
+  isBlockingDecision(): boolean {
+    return this.decision === 'block' || this.decision === 'deny';
+  }
+
+  // 是否应该停止执行
+  shouldStopExecution(): boolean {
+    return this.continue === false || this.isBlockingDecision();
+  }
+
+  // 获取有效的停止原因
+  getEffectiveReason(): string | undefined {
+    return this.reason ?? this.stopReason;
+  }
+}
+
+// AfterModel Hook 输出：可修改模型响应
+export class AfterModelHookOutput extends DefaultHookOutput {
+  getModifiedResponse(): GenerateContentResponse | undefined {
+    if (this.hookSpecificOutput?.['llm_response']) {
+      return defaultHookTranslator.fromHookLLMResponse(
+        this.hookSpecificOutput['llm_response'] as LLMResponse
+      );
+    }
+    return undefined;
+  }
+}
+
+// BeforeToolSelection Hook 输出：可修改工具配置
+export class BeforeToolSelectionHookOutput extends DefaultHookOutput {
+  applyToolConfigModifications(
+    toolConfig: ToolConfig
+  ): ToolConfig {
+    if (this.hookSpecificOutput?.['tool_config']) {
+      const modifications = this.hookSpecificOutput['tool_config'] as ToolConfig;
+      return { ...toolConfig, ...modifications };
+    }
+    return toolConfig;
+  }
+}
+
+// 工厂函数：根据事件类型创建对应的 HookOutput
+export function createHookOutput(
+  eventName: HookEventName,
+  rawOutput: HookOutput
+): DefaultHookOutput {
+  switch (eventName) {
+    case HookEventName.BeforeTool:
+      return new BeforeToolHookOutput(...);
+    case HookEventName.BeforeModel:
+      return new BeforeModelHookOutput(...);
+    case HookEventName.AfterModel:
+      return new AfterModelHookOutput(...);
+    case HookEventName.BeforeToolSelection:
+      return new BeforeToolSelectionHookOutput(...);
+    default:
+      return new DefaultHookOutput(...);
+  }
+}`;
+
   return (
     <div className="space-y-8">
       <QuickSummary
@@ -542,6 +617,54 @@ export class BeforeModelHookOutput extends DefaultHookOutput {
         </div>
       </Layer>
 
+      {/* 6.5. HookOutput 类层次结构 */}
+      <Layer title="HookOutput 类层次结构" icon="🏗️">
+        <div className="space-y-4">
+          <HighlightBox title="专用 HookOutput 类" variant="purple">
+            <div className="text-sm space-y-2 text-gray-300">
+              <p>不同事件类型有对应的专用 HookOutput 类，提供特定的修改能力：</p>
+              <div className="grid grid-cols-1 md:grid-cols-2 gap-2 mt-3">
+                <div className="bg-black/30 p-2 rounded">
+                  <code className="text-cyan-300">BeforeToolHookOutput</code>
+                  <p className="text-xs text-gray-400 mt-1">getModifiedToolInput() - 修改工具输入</p>
+                </div>
+                <div className="bg-black/30 p-2 rounded">
+                  <code className="text-purple-300">BeforeModelHookOutput</code>
+                  <p className="text-xs text-gray-400 mt-1">getSyntheticResponse() - 绕过 LLM 调用</p>
+                </div>
+                <div className="bg-black/30 p-2 rounded">
+                  <code className="text-green-300">AfterModelHookOutput</code>
+                  <p className="text-xs text-gray-400 mt-1">getModifiedResponse() - 修改模型响应</p>
+                </div>
+                <div className="bg-black/30 p-2 rounded">
+                  <code className="text-amber-300">BeforeToolSelectionHookOutput</code>
+                  <p className="text-xs text-gray-400 mt-1">applyToolConfigModifications() - 修改工具配置</p>
+                </div>
+              </div>
+            </div>
+          </HighlightBox>
+
+          <CodeBlock code={hookOutputHierarchyCode} language="typescript" title="HookOutput 类层次结构与工厂函数" />
+
+          <HighlightBox title="DefaultHookOutput 基类方法" variant="blue">
+            <div className="grid grid-cols-1 md:grid-cols-3 gap-3 text-sm">
+              <div className="bg-black/30 p-3 rounded">
+                <code className="text-cyan-300 font-semibold">isBlockingDecision()</code>
+                <p className="text-gray-400 mt-1">判断是否为阻止性决策（block/deny）</p>
+              </div>
+              <div className="bg-black/30 p-3 rounded">
+                <code className="text-cyan-300 font-semibold">shouldStopExecution()</code>
+                <p className="text-gray-400 mt-1">判断是否应停止执行</p>
+              </div>
+              <div className="bg-black/30 p-3 rounded">
+                <code className="text-cyan-300 font-semibold">getEffectiveReason()</code>
+                <p className="text-gray-400 mt-1">获取有效的停止原因</p>
+              </div>
+            </div>
+          </HighlightBox>
+        </div>
+      </Layer>
+
       {/* 7. 与 Policy 集成 */}
       <Layer title="与 Policy Engine 集成" icon="🔗">
         <div className="space-y-4">
diff --git a/src/pages/MessageBus.tsx b/src/pages/MessageBus.tsx
@@ -183,73 +183,120 @@ export class MessageBus extends EventEmitter {
     super();
   }
 
-  // 发布消息
+  // 发布消息（带完整错误处理）
   async publish(message: Message): Promise<void> {
-    if (!this.isValidMessage(message)) {
-      throw new Error(\`Invalid message structure\`);
-    }
-
-    if (message.type === MessageBusType.TOOL_CONFIRMATION_REQUEST) {
-      // 工具确认请求：先经过 Policy 检查
-      const { decision } = await this.policyEngine.check(
-        message.toolCall,
-        message.serverName,
-      );
+    try {
+      if (!this.isValidMessage(message)) {
+        throw new Error(\`Invalid message structure: \${safeJsonStringify(message)}\`);
+      }
 
-      switch (decision) {
-        case PolicyDecision.ALLOW:
-          this.emitMessage({
-            type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
-            correlationId: message.correlationId,
-            confirmed: true,
-          });
-          break;
+      if (message.type === MessageBusType.TOOL_CONFIRMATION_REQUEST) {
+        // 工具确认请求：先经过 Policy 检查
+        const { decision } = await this.policyEngine.check(
+          message.toolCall,
+          message.serverName,
+        );
+
+        switch (decision) {
+          case PolicyDecision.ALLOW:
+            this.emitMessage({
+              type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+              correlationId: message.correlationId,
+              confirmed: true,
+            });
+            break;
+
+          case PolicyDecision.DENY:
+            this.emitMessage({
+              type: MessageBusType.TOOL_POLICY_REJECTION,
+              toolCall: message.toolCall,
+            });
+            this.emitMessage({
+              type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+              correlationId: message.correlationId,
+              confirmed: false,
+            });
+            break;
+
+          case PolicyDecision.ASK_USER:
+            // 传递给 UI 层处理
+            this.emitMessage(message);
+            break;
+
+          default:
+            throw new Error(\`Unknown policy decision: \${decision}\`);
+        }
+      } else if (message.type === MessageBusType.HOOK_EXECUTION_REQUEST) {
+        // Hook 执行请求：经过 Hook 策略检查
+        const decision = await this.policyEngine.checkHook(message);
+
+        // 发送策略决策事件（用于可观测性）
+        this.emitMessage({
+          type: MessageBusType.HOOK_POLICY_DECISION,
+          eventName: message.eventName,
+          hookSource: getHookSource(message.input),
+          decision: decision === PolicyDecision.ALLOW ? 'allow' : 'deny',
+          reason: decision !== PolicyDecision.ALLOW
+            ? 'Hook execution denied by policy'
+            : undefined,
+        });
 
-        case PolicyDecision.DENY:
-          this.emitMessage({
-            type: MessageBusType.TOOL_POLICY_REJECTION,
-            toolCall: message.toolCall,
-          });
+        if (decision === PolicyDecision.ALLOW) {
+          this.emitMessage(message);
+        } else {
+          // Hook 不支持交互式确认，直接返回错误
           this.emitMessage({
-            type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+            type: MessageBusType.HOOK_EXECUTION_RESPONSE,
             correlationId: message.correlationId,
-            confirmed: false,
+            success: false,
+            error: new Error('Hook execution denied by policy'),
           });
-          break;
-
-        case PolicyDecision.ASK_USER:
-          // 传递给 UI 层处理
-          this.emitMessage(message);
-          break;
-      }
-    } else if (message.type === MessageBusType.HOOK_EXECUTION_REQUEST) {
-      // Hook 执行请求：经过 Hook 策略检查
-      const decision = await this.policyEngine.checkHook(message);
-
-      this.emitMessage({
-        type: MessageBusType.HOOK_POLICY_DECISION,
-        eventName: message.eventName,
-        hookSource: getHookSource(message.input),
-        decision: decision === PolicyDecision.ALLOW ? 'allow' : 'deny',
-      });
-
-      if (decision === PolicyDecision.ALLOW) {
-        this.emitMessage(message);
+        }
       } else {
-        this.emitMessage({
-          type: MessageBusType.HOOK_EXECUTION_RESPONSE,
-          correlationId: message.correlationId,
-          success: false,
-          error: new Error('Hook execution denied by policy'),
-        });
+        // 其他消息类型直接转发
+        this.emitMessage(message);
       }
-    } else {
-      // 其他消息类型直接转发
-      this.emitMessage(message);
+    } catch (error) {
+      // 错误不抛出，而是通过 'error' 事件发送
+      this.emit('error', error);
     }
   }
 }`;
 
+  // 错误处理机制代码
+  const errorHandlingCode = `// 错误处理机制
+
+// 1. 订阅错误事件
+messageBus.on('error', (error: Error) => {
+  console.error('[MessageBus Error]', error.message);
+  // 可以发送到日志系统或监控平台
+  telemetry.recordError('message_bus', error);
+});
+
+// 2. ToolExecutionFailure 接口
+export interface ToolExecutionFailure<E = Error> {
+  type: MessageBusType.TOOL_EXECUTION_FAILURE;
+  correlationId: string;
+  error: E;
+}
+
+// 3. HookExecutionResponse 可包含错误
+export interface HookExecutionResponse {
+  type: MessageBusType.HOOK_EXECUTION_RESPONSE;
+  correlationId: string;
+  success: boolean;
+  error?: Error;  // 失败时包含错误信息
+}
+
+// 4. 使用示例：处理工具执行失败
+messageBus.subscribe(
+  MessageBusType.TOOL_EXECUTION_FAILURE,
+  (message: ToolExecutionFailure) => {
+    console.error(\`Tool execution failed: \${message.error.message}\`);
+    // 可以触发重试逻辑或通知用户
+  }
+);`;
+
   const subscribePatternCode = `// 订阅消息
 subscribe<T extends Message>(
   type: T['type'],
@@ -556,7 +603,50 @@ if (response.confirmed) {
         </div>
       </Layer>
 
-      {/* 7. 策略更新 */}
+      {/* 7. 错误处理机制 */}
+      <Layer title="错误处理机制" icon="⚠️">
+        <div className="space-y-4">
+          <HighlightBox title="错误不抛出，通过事件传递" variant="red">
+            <div className="text-sm space-y-2 text-gray-300">
+              <p>
+                MessageBus 的 <code className="bg-black/30 px-1 rounded">publish()</code> 方法将整个逻辑包裹在 try-catch 中，
+                错误不会抛出导致程序崩溃，而是通过 <code className="bg-black/30 px-1 rounded">'error'</code> 事件发送。
+              </p>
+              <p className="text-amber-400">
+                这保证了消息总线的稳定性，即使某个消息处理失败，其他消息仍可正常处理。
+              </p>
+            </div>
+          </HighlightBox>
+
+          <CodeBlock code={errorHandlingCode} language="typescript" title="错误处理示例" />
+
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <HighlightBox title="错误类型" variant="blue">
+              <div className="text-sm space-y-2">
+                <ul className="text-gray-400 space-y-1">
+                  <li>• <code className="text-red-300">Invalid message structure</code>: 消息格式错误</li>
+                  <li>• <code className="text-red-300">Unknown policy decision</code>: 未知策略决策</li>
+                  <li>• <code className="text-red-300">Request timed out</code>: 请求超时</li>
+                  <li>• <code className="text-red-300">Hook execution denied</code>: Hook 执行被拒绝</li>
+                </ul>
+              </div>
+            </HighlightBox>
+
+            <HighlightBox title="错误观测性" variant="green">
+              <div className="text-sm space-y-2">
+                <ul className="text-gray-400 space-y-1">
+                  <li>• 订阅 <code className="text-cyan-300">'error'</code> 事件监控错误</li>
+                  <li>• 错误可发送到遥测系统</li>
+                  <li>• 支持自定义错误处理逻辑</li>
+                  <li>• 可结合日志系统记录</li>
+                </ul>
+              </div>
+            </HighlightBox>
+          </div>
+        </div>
+      </Layer>
+
+      {/* 8. 策略更新 */}
       <Layer title="动态策略更新" icon="🔄">
         <div className="space-y-4">
           <CodeBlock
diff --git a/src/pages/PolicyEngine.tsx b/src/pages/PolicyEngine.tsx
@@ -162,6 +162,14 @@ export type SafetyCheckerConfig =
 // 内置 Checker 类型
 export enum InProcessCheckerType {
   ALLOWED_PATH = 'allowed-path', // 路径白名单检查
+}
+
+// Hook Checker 规则（用于 Hook 执行的安全检查）
+export interface HookCheckerRule {
+  eventName?: string;      // Hook 事件名（BeforeTool, AfterModel 等）
+  hookSource?: HookSource; // Hook 来源（project, user, system, extension）
+  checker: string;         // 检查器名称
+  priority?: number;       // 优先级（越高越先匹配）
 }`;
 
   const policyEngineCode = `// packages/core/src/policy/policy-engine.ts
