100% 兼容 `@raycast.*` 注释规范！手把手实现支持进程树级管控与双编码容错的本地脚本引擎

#!/usr/bin/env bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title 清理端口占用进程
# @raycast.mode compact

# Optional parameters:
# @raycast.icon ⚡
# @raycast.packageName Developer Utils
# @raycast.argument1 { "type": "text", "placeholder": "输入端口号 (如 3000)", "percentEncoded": false }

PORT=$1
echo "正在查找并清理端口 $PORT ..."

export interface ScriptCommandMetadata {
  schemaVersion: number;
  title: string;
  mode: 'silent' | 'compact' | 'fullOutput' | 'inline';
  packageName?: string;
  icon?: string;
  refreshTime?: string;
  currentDirectoryPath?: string;
  needsConfirmation?: boolean;
  arguments: ScriptArgumentDef[];
}

const META_LINE_REGEX = /^(?:#|\/\/|REM\s)\s*@(?:ztools|raycast)\.([a-zA-Z0-9_]+)\s+(.+)$/;

export function parseScriptHeader(fileContent: string, filePath: string): ScriptCommandMetadata {
  const lines = fileContent.split(/\r?\n/, 60); // 仅扫描前 60 行，复杂度严格 O(1)
  const rawMeta: Record<string, string> = {};
  const args: ScriptArgumentDef[] = [];

  for (const line of lines) {
    const trimmed = line.trim();
    const match = META_LINE_REGEX.exec(trimmed);
    if (!match) continue;

    const [, key, val] = match;
    if (key.startsWith('argument')) {
      const parsedArg = safeParseArgumentJson(val, filePath);
      if (parsedArg) args.push(parsedArg);
    } else {
      rawMeta[key] = val.trim();
    }
  }

  if (!rawMeta.title) {
    throw new Error(`脚本缺少必填的 @ztools.title 或 @raycast.title 声明: ${filePath}`);
  }

  return {
    schemaVersion: Number(rawMeta.schemaVersion || 1),
    title: rawMeta.title,
    mode: validateMode(rawMeta.mode),
    packageName: rawMeta.packageName,
    icon: rawMeta.icon,
    refreshTime: rawMeta.refreshTime,
    needsConfirmation: rawMeta.needsConfirmation === 'true',
    arguments: args,
  };
}

import { TextDecoder } from 'node:util';

const strictUtf8Decoder = new TextDecoder('utf-8', { fatal: true });
const gbkFallbackDecoder = new TextDecoder('gb18030', { fatal: false });

/**
 * 智能双编码容错解码器：
 * 优先按严格 UTF-8 验证字节序列，一旦遇到非法 UTF-8 多字节序列（如 Windows 命令吐出的 GBK 中文），
 * 毫秒级自动切换至 GB18030/GBK 解码，100% 根除中文 Windows 控制台乱码！
 */
export function decodeProcessOutputBuffer(rawBuffer: Buffer): string {
  if (rawBuffer.length === 0) return '';
  try {
    // 严格模式：若包含任何非 UTF-8 字节序列（如 GBK 编码汉字），将立即抛出 TypeError
    return strictUtf8Decoder.decode(rawBuffer);
  } catch {
    // 自动降级为 GB18030/GBK 解码
    return gbkFallbackDecoder.decode(rawBuffer);
  }
}

import { spawn } from 'node:child_process';

/**
 * 跨平台整棵进程树级联终止，严防孙子进程残留
 */
export async function killProcessTree(pid: number, signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
  if (!pid || pid <= 0) return;

  if (process.platform === 'win32') {
    // Windows: 使用 /T (Tree) 递归终止该 PID 及其派生的所有子孙进程，/F 强制终结
    await new Promise<void>((resolve) => {
      const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
        windowsHide: true,
        stdio: 'ignore',
      });
      killer.on('close', () => resolve());
      killer.on('error', () => resolve());
    });
  } else {
    // macOS / Linux: 向进程组 ID (-pid) 发送信号，一次性终结整个 Process Group
    try {
      process.kill(-pid, signal);
    } catch {
      try {
        process.kill(pid, signal);
      } catch {
        // 进程已退出
      }
    }
  }
}