Hook 生命周期

// hookResponseSchema: Hook 统一返回结构
const hookResponseSchema = {
  type: 'object',
  properties: {
    ok: { type: 'boolean', description: 'Hook 是否执行成功' },
    reason: { type: 'string', description: '失败原因描述' }
  },
  required: ['ok']
};

// Hook 配置定义示例 (settings.json)
const hookConfig = {
  hooks: {
    PreToolUse: [
      {
        // 匹配特定工具
        matcher: 'Bash',
        // 使用 prompt 方式执行
        type: 'prompt',
        prompt: '检查即将执行的命令是否安全: $ARGUMENTS'
      },
      {
        matcher: '*',
        type: 'http',
        url: 'https://audit.example.com/hook',
        timeout: 5000
      }
    ],
    PostToolUse: [
      {
        matcher: 'Write',
        type: 'prompt',
        prompt: '验证写入的文件内容是否符合规范'
      }
    ],
    SessionStart: [
      {
        type: 'command',
        command: 'echo "Session initialized at $(date)"'
      }
    ]
  }
};

// addArgumentsToPrompt: 参数替换引擎
function addArgumentsToPrompt(
  prompt: string,
  args: string[]
): string {
  let result = prompt;
  // 替换 $ARGUMENTS 为完整参数字符串
  result = result.replace(
    /\$ARGUMENTS/g,
    args.join(' ')
  );
  // 替换 $0, $1, $2... 为对应位置参数
  for (let i = 0; i < args.length; i++) {
    result = result.replace(
      new RegExp('\\$' + i, 'g'),
      args[i]
    );
  }
  return result;
}

// Hook 事件分发核心逻辑
async function dispatchHookEvent(
  event: HookEvent,
  context: HookContext
): Promise<HookResponse[]> {
  const configs = hooksConfigManager
    .getHooksForEvent(event.type);
  const results: HookResponse[] = [];

  for (const config of configs) {
    // 检查 matcher 是否匹配当前工具
    if (config.matcher && !matchTool(
      config.matcher, event.toolName
    )) continue;

    let result: HookResponse;
    switch (config.type) {
      case 'agent':
        result = await execAgentHook(config, context);
        break;
      case 'http':
        result = await execHttpHook(config, context);
        break;
      case 'prompt':
        result = await execPromptHook(config, context);
        break;
    }
    results.push(result);
    // 如果任何 Hook 返回不通过则中断
    if (!result.ok) break;
  }
  return results;
}

// AsyncHookRegistry: 异步 Hook 注册表
class AsyncHookRegistry {
  private hooks: Map<string, HookHandler[]> = new Map();

  register(event: string, handler: HookHandler): void {
    const handlers = this.hooks.get(event) || [];
    handlers.push(handler);
    this.hooks.set(event, handlers);
  }

  unregister(event: string, handler: HookHandler): void {
    const handlers = this.hooks.get(event) || [];
    this.hooks.set(
      event,
      handlers.filter(h => h !== handler)
    );
  }

  async execute(
    event: string,
    context: HookContext
  ): Promise<HookResponse[]> {
    const handlers = this.hooks.get(event) || [];
    return Promise.all(
      handlers.map(h => h(context))
    );
  }
}

// registerFrontmatterHooks: 从 Skill frontmatter 注册
function registerFrontmatterHooks(
  skill: SkillDefinition,
  registry: AsyncHookRegistry
): void {
  const frontmatter = skill.frontmatter;
  if (!frontmatter?.hooks) return;

  for (const [event, hookDefs] of
    Object.entries(frontmatter.hooks)
  ) {
    for (const def of hookDefs) {
      registry.register(event, async (ctx) => {
        // 使用 skill 上下文执行 hook
        return execPromptHook({
          prompt: addArgumentsToPrompt(
            def.prompt, ctx.args || []
          ),
          skillContext: skill.name
        }, ctx);
      });
    }
  }
}

// registerStructuredOutputEnforcement
function registerStructuredOutputEnforcement(
  registry: AsyncHookRegistry
): void {
  registry.register('PostToolUse', async (ctx) => {
    if (!ctx.expectedSchema) return { ok: true };
    const valid = validateSchema(
      ctx.result, ctx.expectedSchema
    );
    return {
      ok: valid,
      reason: valid ? undefined
        : 'Output does not match expected schema'
    };
  });
}