ฟังก์ชันช่วย (Utilities)

ภาพรวม

ชั้นฟังก์ชันช่วยให้ ~331 ไดเรกทอรีย่อยของโมดูลอรรถประโยชน์ ที่รองรับฟังก์ชันหลักของแอปพลิเคชัน

โครงสร้างไดเรกทอรีฟังก์ชันช่วย

src/utils/
├── permissions/ - ฟังก์ชันช่วยระบบ permission
├── settings/ - การจัดการการตั้งค่า
├── plugins/ - ฟังก์ชันช่วยระบบ plugins
├── model/ - การตั้งค่าโมเดล
├── api/ - ฟังก์ชันช่วย API
├── git/ - การดำเนินการ Git
├── file/ - ฟังก์ชันช่วยระบบไฟล์
├── [331+ โมดูลอรรถประโยชน์]
└── index.ts - การส่งออกฟังก์ชันช่วย

หมวดหมู่ฟังก์ชันช่วยหลัก

ฟังก์ชันช่วย Permission (src/utils/permissions/)

// src/utils/permissions/PermissionMode.ts
export const PERMISSION_MODES = {
  DEFAULT: 'default',
  PLAN: 'plan',
  AUTO: 'auto',
  BYPASS: 'bypassPermissions',
} as const;

// src/utils/permissions/permissionSetup.ts
export function initialPermissionModeFromCLI(): PermissionMode {
  // วิเคราะห์โหมด permission จาก flags ของ CLI
}

export function checkAndDisableBypassPermissions(): void {
  // ตรวจสอบและปิดการข้าม permission ถ้าจำเป็น
}

export function verifyAutoModeGateAccess(): boolean {
  // ยืนยันการเข้าถึงโหมด auto
}

ฟังก์ชันช่วยการตั้งค่า (src/utils/settings/)

// src/utils/settings/settings.ts
export function getInitialSettings(): Settings {
  // ดึงการตั้งค่าเริ่มต้นจาก config
}

export function getSettingsForSource(source: SettingSource): Settings {
  // ดึงการตั้งค่าจากแหล่งเฉพาะ
}

export function getSettingsWithErrors(): { settings: Settings; errors: ValidationError[] } {
  // ดึงการตั้งค่าพร้อมข้อผิดพลาดของการตรวจสอบ
}

// src/utils/settings/mdm/settings.ts
export function ensureMdmSettingsLoaded(): Promise<void> {
  // รับประกันว่าการตั้งค่า MDM โหลดแล้ว
}

ฟังก์ชันช่วย Plugins (src/utils/plugins/)

// src/utils/plugins/pluginLoader.ts
export async function loadAllPluginsCacheOnly(): Promise<PluginLoadResult> {
  // โหลด plugins จาก cache
}

export function clearPluginCache(reason: string): void {
  // ล้าง cache ของ plugin
}

// src/utils/plugins/managedPlugins.ts
export function getManagedPluginNames(): string[] {
  // ดึงรายการชื่อ plugins ที่จัดการ
}

ฟังก์ชันช่วยโมเดล (src/utils/model/)

// src/utils/model/model.ts
export function getDefaultMainLoopModel(): string {
  // ดึงโมเดลเริ่มต้นสำหรับ main loop
}

export function parseUserSpecifiedModel(modelString: string): ModelInfo {
  // วิเคราะห์สตริงโมเดลที่ผู้ใช้ระบุ
}

export function getModelDeprecationWarning(model: string): string | null {
  // ดึงคำเตือนการเลิกใช้ของโมเดล
}

// src/utils/model/modelCapabilities.ts
export function refreshModelCapabilities(): void {
  // รีเฟรช cache ของความสามารถของโมเดล
}

ฟังก์ชันช่วยระบบไฟล์ (src/utils/fsOperations.ts)

export function getFsImplementation(): FsImplementation {
  // ดึงการดำเนินการของระบบไฟล์
}

export function safeResolvePath(fs: FsImplementation, path: string): {
  resolvedPath: string;
  exists: boolean;
} {
  // วิเคราะห์เส้นทางไฟล์อย่างปลอดภัย
}

ฟังก์ชันช่วย Git (src/utils/git.ts)

export function findGitRoot(cwd: string): string | null {
  // ค้นหา root ของ repository Git
}

export function getBranch(): string | null {
  // ดึง branch ปัจจุบันของ Git
}

export function getIsGit(): boolean {
  // ตรวจสอบว่าไดเรกทอรีปัจจุบันเป็น Git repo
}

export function getWorktreeCount(): number {
  // ดึงจำนวน worktrees ของ Git
}

รูปแบบฟังก์ชันช่วย

ฟังก์ชันช่วยใช้รูปแบบที่สม่ำเสมอ:

// ฟังก์ชันช่วย
export function utilityFunction(params: Params): Result {
  // ตรรกะของฟังก์ชันช่วย
  return result;
}

// คลาสฟังก์ชันช่วย
export class UtilityClass {
  private state: StateType;
  
  initialize(): void {
    // เริ่มต้นฟังก์ชันช่วย
  }
  
  performOperation(params: Params): Promise<Result> {
    // ดำเนินการการดำเนินการของฟังก์ชันช่วย
  }
}

แนวปฏิบัติที่ดีของฟังก์ชันช่วย

1. ฟังก์ชันบริสุทธิ์: ฟังก์ชันช่วยที่ไร้สถานะเท่าที่เป็นไปได้
2. การจัดการข้อผิดพลาด: การลดผลกระทบจากข้อผิดพลาดอย่างนุ่มนวล
3. Caching: ผลลัพธ์ถูก cache เพื่อประสิทธิภาพ
4. Lazy Loading: โหลดฟังก์ชันช่วยหนักเมื่อต้องการ
5. ความปลอดภัยของ Type: การพิมพ์ TypeScript ที่เข้มงวด

การผสานรวมฟังก์ชันช่วย

ฟังก์ชันช่วยถูกนำเข้าและใช้ทั่วทั้งโค้ดเบส:

import { getInitialSettings } from './utils/settings/settings.js';
import { findGitRoot } from './utils/git.js';
import { loadAllPluginsCacheOnly } from './utils/plugins/pluginLoader.js';

// ใช้ฟังก์ชันช่วยในส่วนประกอบหรือบริการ
const settings = getInitialSettings();
const gitRoot = findGitRoot(cwd);
const plugins = await loadAllPluginsCacheOnly();

ประสิทธิภาพของฟังก์ชันช่วย

1. การโหลดแบบขนาน: การเริ่มต้นฟังก์ชันช่วยที่ไม่บล็อกการทำงาน
2. Caching: การดำเนินการที่หนักถูก cache
3. การประเมินแบบ Lazy: ฟังก์ชันช่วยถูกโหลดเมื่อจำเป็น
4. Event-Driven: ฟังก์ชันช่วยปล่อย events สำหรับการเปลี่ยนแปลงสถานะ

ความปลอดภัยของฟังก์ชันช่วย

1. การตรวจสอบ Permission: ฟังก์ชันช่วยเคารพโหมด permission
2. ไดเรกทอรีการทำงาน: ฟังก์ชันช่วยเคารพข้อจำกัดของ cwd
3. Feature Flags: ความพร้อมใช้งานของฟังก์ชันช่วยตามเงื่อนไข
4. ขอบเขตข้อผิดพลาด: การจัดการข้อผิดพลาดแบบแยกออกมา

ตัวอย่างฟังก์ชันช่วย

ฟังก์ชันช่วยการตั้งค่า Permission

// src/utils/permissions/permissionSetup.ts
export function initialPermissionModeFromCLI(): PermissionMode {
  const cliArgs = process.argv.slice(2);
  const modeIndex = cliArgs.indexOf('--permission-mode');
  
  if (modeIndex !== -1 && cliArgs[modeIndex + 1]) {
    return cliArgs[modeIndex + 1] as PermissionMode;
  }
  return 'default';
}

export function checkAndDisableBypassPermissions(): void {
  // ตรวจสอบว่าควรปิดการข้าม permission
  // อัปเดตการตั้งค่าตามนั้น
}

ฟังก์ชันช่วยการจัดการการตั้งค่า

// src/utils/settings/settings.ts
export function getInitialSettings(): Settings {
  // โหลดการตั้งค่าจาก settings.json หรือสภาพแวดล้อม
  const settingsPath = getSettingsPath();
  const settings = loadSettingsFromFile(settingsPath);
  return settings;
}

export function getSettingsForSource(source: SettingSource): Settings {
  // กรองการตั้งค่าตามแหล่ง (user, policy, ฯลฯ)
  return settings.filter(s => s.source === source);
}

เอกสารฟังก์ชันช่วย

แต่ละฟังก์ชันช่วยมีเอกสารในตัว:

/**
 * findGitRoot - ค้นหา root ของ repository Git
 * 
 * @param cwd - ไดเรกทอรีการทำงานปัจจุบัน
 * @returns เส้นทาง root ของ Git หรือ null ถ้าไม่พบ
 */
export function findGitRoot(cwd: string): string | null {
  // การดำเนินการ
}

การทดสอบฟังก์ชันช่วย

ฟังก์ชันช่วยถูกทดสอบผ่าน:

• การทดสอบหน่วย: พฤติกรรมของฟังก์ชันช่วยแต่ละตัว
• การทดสอบการผสานรวม: การโต้ตอบของฟังก์ชันช่วย
• การทดสอบประสิทธิภาพ: ตัวชี้วัดเวลาการดำเนินการ