Hook 机制

// hooks/useManagePlugins.ts:72-109
let commands: Command[] = []
let agents: AgentDefinition[] = []

try { commands = await getPluginCommands() }
catch (error) {
  errors.push({
    type: 'generic-error', source: 'plugin-commands',
    error: `Failed to load plugin commands: ${errorMessage}`
  })
}

try { agents = await loadPluginAgents() }
catch (error) {
  errors.push({
    type: 'generic-error', source: 'plugin-agents',
    error: `Failed to load plugin agents: ${errorMessage}`
  })
}

// hooks/useMergedTools.ts:20-44
export function useMergedTools(initialTools, mcpTools, ctx): Tools {
  return useMemo(() => {
    // assembleToolPool: 共享的纯函数，REPL 和 runAgent 都用
    const assembled = assembleToolPool(ctx, mcpTools)
    // mergeAndFilterTools: 按 permission mode 过滤
    return mergeAndFilterTools(initialTools, assembled, ctx.mode)
  }, [initialTools, mcpTools, ctx])
}

// hooks/useNotifyAfterTimeout.ts:23-26
// NOTE: User interaction tracking is now done in App.tsx's
// processKeysInBatch function. This avoids having a separate
// stdin 'data' listener that would compete with the main
// 'readable' listener and cause dropped input characters.

// L49-51 — 仅在 hook 挂载时重置时间戳
useEffect(() => {
  updateLastInteractionTime(true) // true = 立即重置
}, [])

// hooks/useDirectConnect.ts:53-56
const toolsRef = useRef(tools)
useEffect(() => {
  toolsRef.current = tools  // 每次渲染后同步
}, [tools])

// WebSocket 回调中使用 ref
const tool = findToolByName(toolsRef.current, request.tool_name)
  ?? createToolStub(request.tool_name)

// 客服 Hook 生命周期 — 借鉴 CC 的三阶段执行
async function executeToolWithCSHooks(
  toolName: string,
  input: any,
  toolFn: (input: any) => Promise<any>,
  preHooks: CSHook[],
  postHooks: CSHook[]
): Promise<ToolResult> {

  // 阶段 1: Pre-hooks — 审计 + 合规检查
  let currentInput = input
  for (const hook of preHooks) {
    if (!matchPattern(hook.pattern, toolName)) continue

    const result = await safeExecuteHook(hook, toolName, currentInput)

    if (result.decision === "deny") {
      // 合规检查不通过 → 记录 deny 事件并终止
      logger.audit("TOOL_DENIED", { tool: toolName, reason: result.reason })
      return { status: "denied", reason: result.reason }
    }

    if (result.decision === "modify") {
      // 数据脱敏 → 替换输入中的敏感字段
      currentInput = result.updatedInput
    }
  }

  // 阶段 2: 执行工具
  const output = await toolFn(currentInput)

  // 阶段 3: Post-hooks — 通知 + 日志（异步，不阻塞）
  for (const hook of postHooks) {
    safeExecuteHook(hook, toolName, currentInput, output)  // fire-and-forget
  }

  return { status: "success", output }
}

// Hook 返回类型 — 借鉴 CC 的 allow/deny/modify
type CSHookResult =
  | { decision: "allow" }                     // 放行
  | { decision: "deny"; reason: string }      // 合规拦截
  | { decision: "modify"; updatedInput: any } // 数据脱敏

// Hook 1: 合规检查 — deny 无理由的敏感操作
const complianceHook: CSHook = {
  name: "compliance-check",
  pattern: /query_id_card|query_phone|query_address/,
  handler: async (toolName, input) => {
    if (!input.queryReason || input.queryReason.trim() === "") {
      return {
        decision: "deny",
        reason: `查询敏感信息(${toolName})必须填写查询理由`
      }
    }
    return { decision: "allow" }
  }
}

// Hook 2: 数据脱敏 — modify 手机号和身份证
const maskSensitiveDataHook: CSHook = {
  name: "mask-sensitive-data",
  pattern: /query_phone|query_id_card/,
  handler: async (toolName, input, agentRole) => {
    if (agentRole.level < 3) {  // 级别不够
      return {
        decision: "modify",
        updatedInput: {
          ...input,
          fieldsToMask: ["phone", "idCard"]  // 标记需要脱敏的字段
        }
      }
    }
    return { decision: "allow" }
  }
}

// Hook 3: 审计日志 — 记录所有敏感操作
const auditLogHook: CSHook = {
  name: "audit-log",
  pattern: /.*/,  // 匹配所有工具
  handler: async (toolName, input) => {
    await auditLog.write({
      operator: input.operatorName,
      action: toolName,
      customerId: input.customerId,
      timestamp: new Date(),
      queryReason: input.queryReason
    })
    return { decision: "allow" }
  }
}

// 防御性 Hook 执行器 — 借鉴 CC 的独立 try-catch
async function safeExecuteHook(
  hook: CSHook, toolName: string, ...args: any[]
): Promise<CSHookResult> {
  try {
    return await hook.handler(toolName, ...args)
  } catch (error) {
    // 审计日志写入失败不能阻塞退单操作
    logger.error(`Hook "${hook.name}" failed`, { error: error.message })
    return { decision: "allow" }  // 失败时放行，不阻塞主流程
  }
}

// Hook 注册表 — 按优先级排序
class CSHookRegistry {
  private preHooks: RegisteredHook[] = []

  register(name: string, pattern: RegExp, handler: HookHandler, priority: number = 100) {
    this.preHooks.push({ name, pattern, handler, priority })
    this.preHooks.sort((a, b) => a.priority - b.priority)  // 数字小先执行
  }
}

// 注册 — 优先级保证执行顺序
const registry = new CSHookRegistry()
registry.register("compliance-check", /query_/, complianceHandler, 10)    // 最先：合规
registry.register("mask-sensitive-data", /query_/, maskHandler, 20)       // 其次：脱敏
registry.register("audit-log", /.*/, auditHandler, 50)                    // 最后：审计