skill-any-code 1.0.0

package/src/infrastructure/llm/openai.client.ts

@@ -0,0 +1,162 @@
+import OpenAI from 'openai';
+import { ILLMClient } from '../../domain/interfaces';
+import { LLMConfig, LLMCallOptions, LLMResponse } from '../../common/types';
+import { LLMUsageTracker } from './llm.usage.tracker';
+import { AppError, ErrorCode } from '../../common/errors';
+import { logger } from '../../common/logger';
+
+export class OpenAIClient implements ILLMClient {
+  private client: OpenAI;
+  private config: LLMConfig;
+  private tracker?: LLMUsageTracker;
+
+  constructor(config: LLMConfig, tracker?: LLMUsageTracker) {
+    this.config = config;
+    this.tracker = tracker;
+    this.client = new OpenAI({
+      apiKey: config.api_key,
+      baseURL: config.base_url,
+      timeout: config.timeout,
+      dangerouslyAllowBrowser: true,
+    });
+  }
+
+  /**
+   * 连接可用性校验（V2.5）
+   * - 在进入任何解析流程前调用；
+   * - 配置不完整或服务不可用时抛出带有明确 ErrorCode 的 AppError。
+   */
+  async testConnection(config: LLMConfig): Promise<void> {
+    // 保持与最新配置一致（允许运行时通过 CLI/环境变量覆盖）
+    this.config = config;
+    // 基本配置校验：base_url / api_key / model 不能为空
+    if (!this.config.base_url || !this.config.api_key || !this.config.model) {
+      throw new AppError(
+        ErrorCode.LLM_INVALID_CONFIG,
+        'Incomplete LLM config. Please set base_url/api_key/model via config file, env vars, or CLI options.',
+        {
+          missing: {
+            base_url: !this.config.base_url,
+            api_key: !this.config.api_key,
+            model: !this.config.model,
+          },
+        },
+      );
+    }
+
+    try {
+      const res = await this.client.chat.completions.create({
+        model: this.config.model,
+        temperature: 0,
+        max_tokens: 1,
+        messages: [{ role: 'system', content: 'health-check' }],
+      } as any);
+
+      const status = (res as any).status ?? 200;
+      if (status === 401) {
+        throw new AppError(ErrorCode.LLM_CALL_FAILED, 'LLM authentication failed (401)', { status });
+      }
+      if (status === 404) {
+        throw new AppError(ErrorCode.LLM_CALL_FAILED, 'LLM model not found (404)', { status });
+      }
+      if (status < 200 || status >= 300) {
+        throw new AppError(
+          ErrorCode.LLM_CALL_FAILED,
+          `LLM connectivity check returned non-2xx status: ${status}`,
+          { status },
+        );
+      }
+    } catch (e: any) {
+      if (e instanceof AppError) {
+        throw e;
+      }
+      const code = e?.code || e?.status;
+      if (code === 'ETIMEDOUT') {
+        throw new AppError(ErrorCode.LLM_TIMEOUT, 'LLM connectivity check timed out', e);
+      }
+      if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ECONNRESET') {
+        throw new AppError(ErrorCode.LLM_CALL_FAILED, 'Unable to reach LLM service. Check network or base_url.', e);
+      }
+      throw new AppError(
+        ErrorCode.LLM_CALL_FAILED,
+        `LLM connectivity check failed: ${e?.message || String(e)}`,
+        e,
+      );
+    }
+  }
+
+  /**
+   * 向后兼容旧版本/测试中使用的 connectTest 名称。
+   * 内部直接代理到 V2.5 的 testConnection。
+   */
+  async connectTest(): Promise<void> {
+    await this.testConnection(this.config);
+  }
+
+  async call(prompt: string, options?: LLMCallOptions): Promise<LLMResponse> {
+    const startTime = Date.now();
+    const retries = options?.retries ?? this.config.max_retries;
+    
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const response = await this.client.chat.completions.create({
+          model: options?.model ?? this.config.model,
+          temperature: options?.temperature ?? this.config.temperature,
+          max_tokens: options?.maxTokens ?? this.config.max_tokens,
+          messages: [
+            { role: 'user', content: prompt }
+          ]
+        });
+
+        const content = response.choices[0].message.content || '';
+        const usage = response.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+
+        const normalizedUsage = {
+          promptTokens: usage.prompt_tokens ?? 0,
+          completionTokens: usage.completion_tokens ?? 0,
+          totalTokens: usage.total_tokens ?? 0,
+        };
+
+        if (this.tracker) {
+          this.tracker.addUsage(normalizedUsage);
+        }
+
+        return {
+          content,
+          usage: normalizedUsage,
+          model: response.model,
+          responseTime: Date.now() - startTime,
+        };
+      } catch (error: any) {
+        const errorMessage = error?.message || 'Unknown LLM call error';
+        logger.debug(`LLM call attempt ${attempt + 1} failed: ${errorMessage}`);
+
+        if (attempt === retries) {
+          if (error?.status === 429) {
+            throw new AppError(ErrorCode.LLM_RATE_LIMITED, 'LLM service rate limited', error);
+          } else if (error?.code === 'ETIMEDOUT') {
+            throw new AppError(ErrorCode.LLM_TIMEOUT, 'LLM call timeout', error);
+          } else {
+            throw new AppError(ErrorCode.LLM_CALL_FAILED, `LLM call failed: ${errorMessage}`, error);
+          }
+        }
+
+        await this.sleep(this.config.retry_delay * Math.pow(2, attempt));
+      }
+    }
+
+    throw new AppError(ErrorCode.LLM_CALL_FAILED, 'Max retries exceeded');
+  }
+
+  async batchCall(prompts: string[], options?: LLMCallOptions): Promise<LLMResponse[]> {
+    const results: LLMResponse[] = [];
+    for (const prompt of prompts) {
+      results.push(await this.call(prompt, options));
+    }
+    return results;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/src/infrastructure/llm/prompt.template.ts

@@ -0,0 +1,175 @@
+// ===== Three-step protocol: single file =====
+/** Step 1: Extract structure only (classes / globals / functions). No summary/description/basic info. */
+export const FILE_STRUCTURE_PROMPT = `
+Extract ONLY the following structure from the code file. Return STRICT JSON and nothing else.
+Do NOT generate summary/description or any basic info (language, LOC, dependencies, etc.).
+
+File path: {{filePath}}
+File content:
+{{fileContent}}
+
+Return JSON with ONLY these fields:
+{
+  "classes": [
+    {
+      "name": "ClassName",
+      "extends": "ParentClassName or null",
+      "implements": ["InterfaceName", "..."],
+      "methods": [
+        { "name": "methodName", "signature": "methodSignature", "description": "what it does", "visibility": "public|private|protected" }
+      ],
+      "properties": [
+        { "name": "propertyName", "type": "propertyType", "description": "what it represents", "visibility": "public|private|protected" }
+      ]
+    }
+  ],
+  "functions": [
+    { "name": "functionName", "signature": "functionSignature", "description": "what it does" }
+  ]
+}
+
+If nothing is found, return empty arrays. Do NOT output any other fields.
+`;
+
+/** Step 2: Generate description only (<= 200 words) */
+export const FILE_DESCRIPTION_PROMPT = `
+Based on the extracted structure JSON below, describe the overall purpose of this file in <= 200 words.
+Return ONLY one JSON object: {"description": "..."}. No other text.
+
+Structure JSON:
+{{structureJson}}
+`;
+
+/** Step 3: Generate summary only (<= 100 words) */
+export const FILE_SUMMARY_PROMPT = `
+Based on the structure and description below, write a one-sentence high-level summary in <= 100 words.
+Return ONLY one JSON object: {"summary": "..."}. No other text.
+
+Structure JSON:
+{{structureJson}}
+
+Description:
+{{description}}
+`;
+
+/** Retry hint when parsing fails (append to original prompt) */
+export const PARSE_RETRY_HINT = `
+
+[IMPORTANT] Your previous output did NOT match the required format.
+Return STRICTLY the JSON specified above and NOTHING ELSE (no markdown, no explanations, no extra text).
+`;
+
+// ===== Merge stage =====
+/** Merge step: merge and deduplicate multiple chunk results into one structure */
+export const MERGE_STRUCTURE_PROMPT = `
+Below are analysis results for multiple chunks of the same file. Merge and deduplicate them into ONE complete structure (classes and global functions).
+Return ONLY JSON. Do NOT generate description or summary.
+
+File path: {{filePath}}
+Chunk results:
+{{chunkResults}}
+
+Return JSON with ONLY these fields:
+{
+  "classes": [
+    {
+      "name": "ClassName",
+      "extends": "ParentClassName or null",
+      "implements": ["InterfaceName", "..."],
+      "methods": [
+        { "name": "methodName", "signature": "methodSignature", "description": "what it does", "visibility": "public|private|protected" }
+      ],
+      "properties": [
+        { "name": "propertyName", "type": "propertyType", "description": "what it represents", "visibility": "public|private|protected" }
+      ]
+    }
+  ],
+  "functions": [
+    { "name": "functionName", "signature": "functionSignature", "description": "what it does" }
+  ]
+}
+
+Keep item formats consistent with the chunk results. Do NOT output any other fields.
+`;
+
+// ===== Directory two-step protocol =====
+/** Directory step 1: generate description (<= 200 words) */
+export const DIRECTORY_DESCRIPTION_PROMPT = `
+You are a codebase structure analysis assistant. Below is a JSON list of all direct child directories and files (with brief summaries).
+Write an English paragraph (<= 200 words) describing the directory's role and responsibilities in the project.
+
+Return ONLY one JSON object: {"description": "..."}. No other text.
+
+Children (JSON):
+{{childrenJson}}
+`;
+
+/** Directory step 2: generate summary (<= 100 words) */
+export const DIRECTORY_SUMMARY_PROMPT = `
+Based on the directory description and children JSON below, write a one-sentence high-level summary in English (<= 100 words).
+Focus on the big picture and avoid details.
+
+Return ONLY one JSON object: {"summary": "..."}. No other text.
+
+Directory description:
+{{description}}
+
+Children (JSON):
+{{childrenJson}}
+`;
+
+export const CODE_ANALYSIS_PROMPT = `
+(Deprecated legacy prompt. Kept empty for backward compatibility; not used in the main pipeline.)
+`;
+
+export const CHUNK_ANALYSIS_PROMPT = `
+Analyze the following code chunk. Extract ONLY the structure that is confidently present in THIS chunk (classes, global variables, global functions).
+Return STRICT JSON and nothing else. Do NOT generate description, summary, or diagrams.
+
+File path: {{filePath}}
+Chunk ID: {{chunkId}}
+Chunk content:
+{{chunkContent}}
+Context (reference only): {{context}}
+
+Return JSON with ONLY these fields:
+{
+  "classes": [
+    {
+      "name": "ClassName",
+      "extends": "ParentClassName or null",
+      "implements": ["InterfaceName", "..."],
+      "methods": [
+        {
+          "name": "methodName",
+          "signature": "methodSignature",
+          "description": "what it does",
+          "visibility": "public|private|protected"
+        }
+      ],
+      "properties": [
+        {
+          "name": "propertyName",
+          "type": "propertyType",
+          "description": "what it represents",
+          "visibility": "public|private|protected"
+        }
+      ]
+    }
+  ],
+  "functions": [
+    {
+      "name": "functionName",
+      "signature": "functionSignature",
+      "description": "what it does"
+    }
+  ]
+}
+
+Rules:
+1) Output STRICT JSON only (no extra text)
+2) If nothing is found, return empty arrays
+3) Analyze ONLY this chunk; context is reference only
+4) Do NOT output fields like basicInfo, partialDiagrams, summary, description, etc.
+5) Write all descriptions in English
+`;

package/src/infrastructure/llm.service.ts

@@ -0,0 +1,70 @@
+import OpenAI from 'openai';
+import { configManager } from '../common/config';
+import { AppError, ErrorCode } from '../common/errors';
+import { logger } from '../common/logger';
+
+export interface LLMService {
+  generateCompletion(prompt: string, systemPrompt?: string): Promise<string>;
+}
+
+export class OpenAILLMService implements LLMService {
+  private client: OpenAI | null = null;
+
+  private async getClient(): Promise<OpenAI> {
+    if (!this.client) {
+      let config: any;
+      try {
+        config = configManager.getConfig();
+      } catch (e) {
+        await configManager.load();
+        config = configManager.getConfig();
+      }
+      
+      if (!config.llm.api_key) {
+        throw new AppError(
+          ErrorCode.ANALYSIS_EXCEPTION,
+          'LLM API key not configured. Please set it in config file or via SKILL_ANY_CODE_LLM_API_KEY environment variable.',
+        );
+      }
+
+      this.client = new OpenAI({
+        baseURL: config.llm.base_url,
+        apiKey: config.llm.api_key,
+      });
+    }
+    return this.client;
+  }
+
+  async generateCompletion(prompt: string, systemPrompt: string = 'You are a code analysis expert. You help analyze code files, generate summaries, class diagrams, and other analysis results. Be concise and accurate.'): Promise<string> {
+    const client = await this.getClient();
+    const config = configManager.getConfig();
+
+    try {
+      logger.debug(`Calling LLM model ${config.llm.model} with prompt length: ${prompt.length}`);
+      
+      const response = await client.chat.completions.create({
+        model: config.llm.model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: prompt },
+        ],
+        temperature: 0.1,
+        max_tokens: 2048,
+      });
+
+      const result = response.choices[0]?.message?.content?.trim() || '';
+      
+      if (!result) {
+        throw new AppError(ErrorCode.ANALYSIS_EXCEPTION, 'LLM returned empty response');
+      }
+
+      logger.debug(`LLM response received, length: ${result.length}`);
+      return result;
+    } catch (error: any) {
+      logger.error('LLM call failed:', error);
+      throw new AppError(ErrorCode.ANALYSIS_EXCEPTION, `LLM call failed: ${error.message}`);
+    }
+  }
+}
+
+export const llmService = new OpenAILLMService();

package/src/infrastructure/skill/skill.generator.ts

@@ -0,0 +1,53 @@
+import * as fs from 'fs-extra'
+import * as path from 'path'
+import { ISkillGenerator, SkillGenerateOptions, SkillProvider } from '../../domain/interfaces'
+import { getSkillMdContent } from './templates/skill.md.template'
+import { getResolveScriptContent } from './templates/resolve.script'
+import { logger } from '../../common/logger'
+
+const PROVIDER_DIRECTORY_MAP: Record<SkillProvider, string> = {
+  opencode: '.agents/skills/skill-any-code',
+  cursor: '.agents/skills/skill-any-code',
+  codex: '.agents/skills/skill-any-code',
+  claude: '.claude/skills/skill-any-code',
+}
+
+export class SkillGenerator implements ISkillGenerator {
+  async generate(options: SkillGenerateOptions): Promise<string[]> {
+    const { projectRoot, providers } = options
+    const deployedPaths: string[] = []
+
+    const uniqueDirs = new Set<string>()
+    for (const p of providers) {
+      const lowerProvider = p.toLowerCase() as SkillProvider
+      const dir = PROVIDER_DIRECTORY_MAP[lowerProvider]
+      if (dir) {
+        uniqueDirs.add(dir)
+      } else {
+        logger.warn(`Unknown provider: ${p}. Skipped.`)
+      }
+    }
+
+    const skillMd = getSkillMdContent()
+    const resolveScript = getResolveScriptContent()
+
+    for (const relativeDir of uniqueDirs) {
+      const targetDir = path.join(projectRoot, relativeDir)
+      try {
+        await fs.ensureDir(targetDir)
+        await fs.ensureDir(path.join(targetDir, 'scripts'))
+
+        await fs.writeFile(path.join(targetDir, 'SKILL.md'), skillMd, 'utf-8')
+        await fs.writeFile(path.join(targetDir, 'scripts', 'get-summary.py'), resolveScript, 'utf-8')
+
+        deployedPaths.push(targetDir)
+        logger.debug(`Skill deployed to: ${targetDir}`)
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error)
+        logger.warn(`Failed to deploy skill (${targetDir}): ${msg}`)
+      }
+    }
+
+    return deployedPaths
+  }
+}

package/src/infrastructure/skill/templates/resolve.script.ts

@@ -0,0 +1,97 @@
+/**
+ * scripts/get-summary.py 内容模板（部署到 Skill 目录中的独立脚本，仅使用 Python 标准库）
+ *
+ * 约定：
+ * - 输入：命令行参数 argv[1]，应为项目内文件或目录「相对项目根目录」的相对路径
+ * - 行为：遵循主程序的结果 md 命名规则，推导目标对象对应的结果 md 路径；若结果 md 存在则输出其相对项目根路径
+ * - 输出：
+ *   - 命中：stdout 输出对应 Markdown 结果文件的相对路径（相对项目根目录，单行）
+ *   - 未命中：stdout 输出字符串 "N/A"（单行）
+ *   - 参数错误：stderr 输出错误信息并以 exit code 1 退出
+ */
+export function getResolveScriptContent(): string {
+  return `#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path, PurePosixPath
+
+
+DEFAULT_OUTPUT_DIR = ".skill-any-code-result"
+
+
+def _to_posix_rel(s: str) -> str:
+  # 最大兼容：支持 \\、./、尾部 /
+  v = (s or "").strip().replace("\\\\", "/")
+  while v.startswith("./"):
+    v = v[2:]
+  # 保留根目录语义："." / "" 视为项目根目录
+  if v in (".", ""):
+    return "."
+  # 裁剪尾部斜杠（目录也允许输入 xxx/）
+  if v.endswith("/") and len(v) > 1:
+    v = v[:-1]
+  return v
+
+
+def _detect_project_root(script_path: Path) -> Path:
+  # 约定：<projectRoot>/.agents/skills/skill-any-code/scripts/get-summary.py
+  # parents: [scripts, skill-any-code, skills, .agents, projectRoot, ...]
+  return script_path.resolve().parents[4]
+
+
+def _file_md_rel(target_rel: str) -> PurePosixPath:
+  p = PurePosixPath(target_rel)
+  dir_part = str(p.parent) if str(p.parent) not in (".", "") else ""
+  stem = p.stem
+  suffix = p.suffix  # includes leading '.' or ''
+
+  if stem == "index" and suffix:
+    name = f"index{suffix}.md"
+  else:
+    name = f"{stem}.md"
+
+  if dir_part:
+    return PurePosixPath(DEFAULT_OUTPUT_DIR) / dir_part / name
+  return PurePosixPath(DEFAULT_OUTPUT_DIR) / name
+
+
+def _dir_md_rel(target_rel: str) -> PurePosixPath:
+  if target_rel in (".", ""):
+    return PurePosixPath(DEFAULT_OUTPUT_DIR) / "index.md"
+  return PurePosixPath(DEFAULT_OUTPUT_DIR) / target_rel / "index.md"
+
+
+def main() -> int:
+  if len(sys.argv) < 2 or not sys.argv[1]:
+    sys.stderr.write("Usage: python get-summary.py <relative-path>\\n")
+    return 1
+
+  raw = sys.argv[1]
+  raw_posix = raw.replace("\\\\", "/").strip()
+  rel = _to_posix_rel(raw)
+
+  project_root = _detect_project_root(Path(__file__))
+  target_abs = (project_root / PurePosixPath(rel)).resolve()
+
+  if not target_abs.exists():
+    sys.stdout.write("N/A\\n")
+    return 0
+
+  # 输入可能是目录（含尾 /）或真实目录
+  is_dir = target_abs.is_dir() or raw_posix.endswith("/")
+  md_rel = _dir_md_rel(rel) if is_dir else _file_md_rel(rel)
+  md_abs = (project_root / Path(os.fspath(md_rel))).resolve()
+
+  if md_abs.exists():
+    sys.stdout.write(str(md_rel).replace("\\\\", "/") + "\\n")
+  else:
+    sys.stdout.write("N/A\\n")
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())
+`
+}

package/src/infrastructure/skill/templates/skill.md.template.ts

@@ -0,0 +1,45 @@
+export function getSkillMdContent(): string {
+  const lines = [
+    '---',
+    'name: code-atlas-navigator',
+    'description: Use this skill when you need to explore, understand, or search this codebase. Input a file or directory path relative to the project root to retrieve the path to its detailed natural language summary. Use this progressively to navigate from the root directory down to specific target files without reading the full raw source code.',
+    '---',
+    '',
+    '# Codebase Navigation Guide',
+    '',
+    'This repository has been pre-analyzed and summarized into natural language Markdown files. To save context window and improve accuracy, **do not read the raw source code directly**. Instead, use this skill to progressively navigate the repository layer by layer.',
+    '',
+    '## 🧭 How to Explore the Codebase',
+    '',
+    "1. **Start High-Level**: If you don't know the exact file location, begin by querying the summary of the root directory (`.`).",
+    '2. **Progressive Disclosure**: Read the directory summary to understand its sub-components. Identify the next relevant sub-directory or file based on your current task.',
+    '3. **Drill Down**: Query the summaries of those specific sub-components. Repeat this until you locate the target function, class, or logic.',
+    '',
+    '## 🛠️ How to Locate a Summary File',
+    '',
+    'Use the provided Python script to map the original codebase path to its corresponding Markdown summary path.',
+    '',
+    '**Script Specification:**',
+    '* **Input Parameter**: The relative path of the target file or directory with respect to the project root.',
+    '* **Output**: The relative path of the Markdown summary file with respect to the project root.',
+    '* **Fallback**: If the summary Markdown file cannot be found, the script will strictly output `N/A`.',
+    '',
+    '### Execution Commands',
+    '',
+    'Since the execution environment may vary, please use the appropriate command based on your current operating system:',
+    '',
+    '**For Linux / macOS (Bash/Zsh):**',
+    '```bash',
+    'python3 scripts/get_summary.py <relative/path/to/target>',
+    '```',
+    '(Note: If python3 is not found, fallback to python).',
+    '',
+    '**For Windows (CMD/PowerShell):**',
+    '```dos',
+    'python scripts\\get_summary.py <relative\\path\\to\\target>',
+    '```',
+    '(Note: You may also use py or python3 depending on the Windows environment setup).',
+  ]
+
+  return lines.join('\n') + '\n'
+}