skill-any-code 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# 🛠️ Skill Any Code (sac)
+
+**Redefines codebase indexing by Agent Skills**.
+
+**Skill Any Code** is a high-performance CLI tool designed to transform complex code repositories into "Skill Maps" that Large Language Models (LLMs) and AI Agents can actually navigate. By generating natural language summaries and adhering to the standard **Agent Skills** protocol, it enables LLMs to explore code through **Progressive Disclosure**. No more context-window bloat; no more AI hallucinations caused by overwhelming raw source code.
+
+
+## ✨ Why Skill Any Code?
+
+* **🗺️ Progressive Understanding, Zero Context Bloat**: Traditional methods "dump" the entire codebase into the LLM, wasting tokens and causing confusion. **sac** generates hierarchical Markdown summaries, allowing the LLM to navigate layer-by-layer—only diving deep when necessary.
+* **🤖 Native Agent Skills Support**: Automatically generates `SKILL.md` and routing scripts compatible with the [Agent Skills](https://agentskills.io/) specification. Works out-of-the-box with AI-native editors like Cursor, Claude Code, and GitHub Copilot.
+* **🧠 Natural Language Indexing**: Translates dry code files into rich descriptions—including overviews, core purposes, key functions, and class definitions—dramatically increasing the LLM's reasoning accuracy.
+
+
+## 📦 Quick Start
+
+### 1. Install the CLI:
+
+```Bash
+npm i -g skill-any-code
+
+npm init
+# Config your LLM API Key in ~/.config/skill-any-code/config.yaml
+```
+
+### 2. Generate Summaries:
+
+```Bash
+cd <your_project_path>
+
+# Start generating summaries
+sac
+```
+
+
+## 🚀 How it Works
+
+1.  **Bottom-Up Recursive Analysis**: The CLI starts from the deepest files in your project. It uses LLM power to extract **classes, functions, and core logic** from raw code. As it moves up, it aggregates these snippets into high-level directory summaries, ensuring every layer of your project has a concise "executive summary."
+2.  **Semantic Indexing**: The process results in a structured Markdown knowledge base. This is not just a file list; it’s a **Semantic Index** where top-level folders explain "Why" and "What," while leaf-node files explain "How."
+3.  **Skill Injection**: **sac** deploys a `SKILL.md` and a cross-platform routing script (`get_summary.py`) to your root. This grants any AI Agent the "Skill" to navigate your codebase intelligently without reading every line of code.
+4.  **Progressive Discovery**: Instead of a "Big Bang" context dump, the AI explores your repo layer-by-layer:
+    * **Identify**: Check the root summary to find the relevant module.
+    * **Drill-down**: Use the Skill script to fetch sub-directory summaries.
+    * **Locate**: Reach the target file summary with surgical precision.
+
+<p align="center">
+  <img src="docs/readme_img.png" alt="Skill Any Code Bottom-Up Parsing and Navigation Workflow" width="90%" />
+</p>

package/dist/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const picocolors_1 = __importDefault(require("picocolors"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const package_json_1 = require("../package.json");
+const analysis_app_service_1 = require("./application/analysis.app.service");
+const config_1 = require("./common/config");
+const logger_1 = require("./common/logger");
+const ui_1 = require("./common/ui");
+const errors_1 = require("./common/errors");
+const constants_1 = require("./common/constants");
+const program = new commander_1.Command();
+// 主命令配置
+program
+    .name('skill-any-code')
+    .alias('sac')
+    .description('Skill Any Code: a CLI for large codebase understanding and analysis')
+    .version(package_json_1.version, '-v, --version', 'Show version number')
+    .helpOption('-h, --help', 'Show help information')
+    .option('--log-level <level>', 'Log level: debug/info/warn/error')
+    .option('--path <path>', 'Project root path to analyze', process.cwd())
+    .option('-m, --mode <mode>', 'Analysis mode: full/incremental/auto', 'auto')
+    .option('-d, --depth <number>', 'Max directory depth (-1 = unlimited)', '-1')
+    .option('-C, --concurrency <number>', 'Max concurrent workers (default: CPU*2, capped by analyze.max_concurrency)')
+    .option('--output-dir <path>', 'Custom output directory for results')
+    .option('--skills-providers <list>', 'Comma-separated AI tool providers (opencode/cursor/claude/codex)')
+    .option('--no-skills', 'Skip skill generation')
+    // LLM相关参数
+    .option('--llm-base-url <url>', 'LLM API base URL')
+    .option('--llm-api-key <key>', 'LLM API key')
+    .option('--llm-model <model>', 'LLM model name')
+    .option('--llm-temperature <number>', 'LLM temperature (0-2)', parseFloat)
+    .option('--llm-max-tokens <number>', 'LLM max output tokens', parseInt)
+    .option('--llm-timeout <ms>', 'LLM request timeout (ms)', parseInt)
+    .option('--llm-max-retries <number>', 'LLM max retries', parseInt)
+    .option('--llm-retry-delay <ms>', 'LLM retry delay (ms)', parseInt)
+    .option('--llm-context-window-size <number>', 'LLM context window size', parseInt)
+    .option('--no-llm-cache', 'Disable LLM result cache')
+    .option('--llm-cache-dir <path>', 'LLM cache directory')
+    .option('--clear-cache', 'Clear existing LLM cache before analyzing');
+// init 子命令：显式初始化配置文件（V2.5）
+program
+    .command('init')
+    .description('Initialize or reset the config file')
+    .action(async () => {
+    try {
+        const resolvedPath = '~/.config/skill-any-code/config.yaml';
+        const fsPath = resolvedPath.replace('~', process.env.HOME || process.env.USERPROFILE || '');
+        const exists = await fs_extra_1.default.pathExists(fsPath);
+        await config_1.configManager.init();
+        logger_1.logger.success(exists ? `Config file reset: ${fsPath}` : `Config file created: ${fsPath}`);
+        process.exit(0);
+    }
+    catch (error) {
+        logger_1.logger.error('Failed to initialize config', error);
+        process.exit(1);
+    }
+});
+// 默认解析（不带子命令时直接执行）
+program.action(async () => {
+    const os = require('os');
+    try {
+        // 加载配置（V2.5：配置未初始化时直接失败，提示先执行 init）
+        let config;
+        try {
+            config = await config_1.configManager.load();
+        }
+        catch (e) {
+            if (e instanceof errors_1.AppError && e.code === errors_1.ErrorCode.CONFIG_NOT_INITIALIZED) {
+                process.stderr.write(`Config is not initialized. Run "skill-any-code init" to create: ~/.config/skill-any-code/config.yaml\n`);
+                process.exit(1);
+                return;
+            }
+            throw e;
+        }
+        const cliLogLevel = program.opts().logLevel;
+        if (cliLogLevel) {
+            logger_1.logger.setLevel(cliLogLevel);
+        }
+        // 合并LLM命令行参数
+        const options = program.opts();
+        if (options.llmBaseUrl)
+            config.llm.base_url = options.llmBaseUrl;
+        if (options.llmApiKey)
+            config.llm.api_key = options.llmApiKey;
+        if (options.llmModel)
+            config.llm.model = options.llmModel;
+        if (options.llmTemperature !== undefined)
+            config.llm.temperature = options.llmTemperature;
+        if (options.llmMaxTokens !== undefined)
+            config.llm.max_tokens = options.llmMaxTokens;
+        if (options.llmTimeout !== undefined)
+            config.llm.timeout = options.llmTimeout;
+        if (options.llmMaxRetries !== undefined)
+            config.llm.max_retries = options.llmMaxRetries;
+        if (options.llmRetryDelay !== undefined)
+            config.llm.retry_delay = options.llmRetryDelay;
+        if (options.llmContextWindowSize !== undefined)
+            config.llm.context_window_size = options.llmContextWindowSize;
+        if (options.llmCache !== undefined)
+            config.llm.cache_enabled = options.llmCache;
+        if (options.llmCacheDir)
+            config.llm.cache_dir = options.llmCacheDir;
+        // 处理清空缓存选项
+        if (options.clearCache) {
+            const { FileHashCache } = await Promise.resolve().then(() => __importStar(require('./infrastructure/cache/file.hash.cache')));
+            const homeDir = os.homedir();
+            const cache = new FileHashCache({
+                cacheDir: config.llm.cache_dir.replace(/^~(?=\/|\\|$)/, homeDir),
+                maxSizeMb: config.llm.cache_max_size_mb,
+            });
+            await cache.clear();
+            logger_1.logger.info('LLM cache cleared');
+        }
+        // 默认并发：CPU*2，但不超过配置中的 analyze.max_concurrency
+        const cpuBasedConcurrency = constants_1.DEFAULT_CONCURRENCY;
+        const configuredMax = Number(config.analyze.max_concurrency ?? constants_1.DEFAULT_CONCURRENCY);
+        const defaultConcurrency = configuredMax > 0 ? Math.min(cpuBasedConcurrency, configuredMax) : cpuBasedConcurrency;
+        const analysisParams = {
+            path: options.path,
+            mode: options.mode,
+            depth: Number(options.depth),
+            concurrency: options.concurrency !== undefined ? Number(options.concurrency) : defaultConcurrency,
+            outputDir: options.outputDir || config.global.output_dir,
+            llmConfig: config.llm,
+            skillsProviders: options.skillsProviders
+                ? options.skillsProviders.split(',').map((s) => s.trim().toLowerCase())
+                : undefined,
+            noSkills: options.skills === false,
+        };
+        // V2.5：解析前执行 LLM 连接可用性校验，失败则立即退出（需求文档 13.4.2 / 测试文档 ST-LLM-CONNECT-001）
+        const { OpenAIClient } = await Promise.resolve().then(() => __importStar(require('./infrastructure/llm/openai.client')));
+        const llmClient = new OpenAIClient(config.llm);
+        logger_1.logger.info(`LLM client initialized. Testing connectivity and config (url=${config.llm.base_url}, model=${config.llm.model})`);
+        try {
+            await llmClient.testConnection(config.llm);
+        }
+        catch (e) {
+            const detail = e?.message || String(e);
+            process.stderr.write(`LLM connectivity/config validation failed: ${detail}\n`);
+            process.exit(1);
+        }
+        const analysisService = new analysis_app_service_1.AnalysisAppService();
+        // 在 analyze 生命周期内，将所有 logger 输出通过 CLI 渲染器固定到进度块下方，
+        // 避免产生额外的进度/对象/Tokens 区域块。
+        logger_1.logger.setSink((line) => {
+            ui_1.cliRenderer.logBelow(line);
+        });
+        const paramsWithProgress = {
+            ...analysisParams,
+            onTotalKnown: (total) => {
+                ui_1.cliRenderer.setTotal(total);
+            },
+            onProgress: (done, total, current) => {
+                ui_1.cliRenderer.updateProgress(done, total, current?.path, analysisParams.concurrency);
+            },
+            onTokenUsageSnapshot: (stats) => {
+                ui_1.cliRenderer.updateTokens(stats);
+            },
+            onScanProgress: (scannedFiles) => {
+                ui_1.cliRenderer.updateScanProgress(scannedFiles);
+            },
+        };
+        let result;
+        // 执行解析（V2.4+：不再在 CLI 中做交互式错误处理，所有 LLM 错误由应用层统一抛出）
+        result = await analysisService.runAnalysis(paramsWithProgress);
+        if (result.success) {
+            const files = result.data?.analyzedFilesCount || 0;
+            const dirs = result.data?.analyzedDirsCount || 0;
+            const objects = files + dirs;
+            logger_1.logger.success(`Analysis completed. Processed ${objects} object(s)`);
+            const summaryPath = result.data?.summaryPath || '';
+            const summaryLabel = summaryPath ? `Entry file: ${path_1.default.basename(summaryPath)}` : 'Entry file: index.md';
+            logger_1.logger.success(`Project analysis result. ${summaryLabel}`);
+            const usage = result.data?.tokenUsage;
+            if (usage) {
+                logger_1.logger.info(`LLM calls: ${usage.totalCalls}, prompt tokens: ${usage.totalPromptTokens}, ` +
+                    `completion tokens: ${usage.totalCompletionTokens}, total tokens: ${usage.totalTokens}`);
+            }
+        }
+        else {
+            logger_1.logger.error(`Analysis failed: ${result.message}`);
+            if (result.errors && result.errors.length > 0) {
+                result.errors.forEach(err => logger_1.logger.error(`- ${err.path}: ${err.message}`));
+            }
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        const err = error;
+        // V2.5：LLM 连接/配置校验失败时统一输出明确前缀，满足 ST-LLM-CONNECT-001/002/003
+        if (err && err.code && (err.code === errors_1.ErrorCode.LLM_INVALID_CONFIG ||
+            err.code === errors_1.ErrorCode.LLM_CALL_FAILED ||
+            err.code === errors_1.ErrorCode.LLM_TIMEOUT)) {
+            const detail = err.message || '';
+            process.stderr.write(`LLM connectivity/config validation failed: ${detail}\n`);
+        }
+        else if (err instanceof errors_1.AppError) {
+            logger_1.logger.error(`Execution failed: ${err.message}`, err);
+        }
+        else {
+            logger_1.logger.error('Execution failed', err);
+        }
+        process.exit(1);
+    }
+});
+// resolve 子命令（V2.6：根据相对路径推导分析结果 Markdown 路径，不依赖索引）
+program
+    .command('resolve')
+    .description('Resolve the analysis result Markdown path for a file/directory')
+    .argument('<relative-path>', 'Relative path of the file/directory (from project root)')
+    .option('-p, --project <path>', 'Project root path', process.cwd())
+    .action(async (relativePath, options) => {
+    try {
+        logger_1.logger.setLevel(program.opts().logLevel);
+        const projectRoot = options.project || process.cwd();
+        const DEFAULT_OUTPUT_DIR = '.skill-any-code-result';
+        const normalizeRel = (input) => {
+            const raw = (input || '').trim();
+            const rawPosix = raw.replace(/\\/g, '/');
+            const rawHadTrailingSlash = rawPosix.endsWith('/') && rawPosix.length > 1;
+            let rel = rawPosix;
+            while (rel.startsWith('./'))
+                rel = rel.slice(2);
+            if (rel.endsWith('/') && rel.length > 1)
+                rel = rel.slice(0, -1);
+            if (rel === '')
+                rel = '.';
+            return { rel, rawHadTrailingSlash };
+        };
+        const { rel, rawHadTrailingSlash } = normalizeRel(relativePath);
+        const targetAbs = path_1.default.resolve(projectRoot, rel);
+        if (!(await fs_extra_1.default.pathExists(targetAbs))) {
+            process.stdout.write('N/A\n');
+            process.exit(0);
+            return;
+        }
+        const stat = await fs_extra_1.default.stat(targetAbs);
+        const isDir = stat.isDirectory() || rawHadTrailingSlash || rel === '.';
+        let mdRel;
+        if (isDir) {
+            mdRel =
+                rel === '.'
+                    ? path_1.default.posix.join(DEFAULT_OUTPUT_DIR, 'index.md')
+                    : path_1.default.posix.join(DEFAULT_OUTPUT_DIR, rel, 'index.md');
+        }
+        else {
+            const parsed = path_1.default.posix.parse(rel);
+            const dirPart = parsed.dir;
+            const name = parsed.name === 'index' && parsed.ext
+                ? `index${parsed.ext}.md`
+                : `${parsed.name}.md`;
+            mdRel = dirPart ? path_1.default.posix.join(DEFAULT_OUTPUT_DIR, dirPart, name) : path_1.default.posix.join(DEFAULT_OUTPUT_DIR, name);
+        }
+        const mdAbs = path_1.default.resolve(projectRoot, mdRel);
+        if (await fs_extra_1.default.pathExists(mdAbs)) {
+            process.stdout.write(mdRel + '\n');
+        }
+        else {
+            process.stdout.write('N/A\n');
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Resolve failed: ${msg}\n`);
+        process.exit(1);
+    }
+});
+// 全局错误处理
+program.showSuggestionAfterError();
+program.configureHelp({
+    sortSubcommands: true,
+    sortOptions: true,
+});
+// 解析命令行参数
+program.parseAsync(process.argv).catch((error) => {
+    console.error(picocolors_1.default.red(`\nExecution failed: ${error.message}`));
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common/types"), exports);
+__exportStar(require("./common/errors"), exports);
+__exportStar(require("./domain"), exports);
+__exportStar(require("./application/analysis.app.service"), exports);
+__exportStar(require("./infrastructure/git.service"), exports);
+__exportStar(require("./infrastructure/storage.service"), exports);

package/jest.config.js

@@ -0,0 +1,27 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: '.',
+  // Windows 下大量文件/子进程/临时目录操作容易触发 EBUSY，串行执行更稳定
+  maxWorkers: 1,
+  testMatch: [
+    '<rootDir>/tests/**/*.test.ts'
+  ],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: 'tsconfig.test.json' }]
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts'
+  ],
+  coverageDirectory: '<rootDir>/tests/coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  cacheDirectory: '<rootDir>/tests/.cache/jest',
+  testTimeout: 300000, // 5分钟超时，适配大型项目测试
+  // 旧版 OpenCode/Skill 的测试辅助已废弃（V2.x 使用 CLI + LLM Mock Server）
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1'
+  }
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "skill-any-code",
+  "version": "1.0.0",
+  "description": "Skill Any Code: CLI tool for large codebase understanding and analysis",
+  "main": "dist/index.js",
+  "bin": {
+    "skill-any-code": "dist/cli.js",
+    "sac": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "jest"
+  },
+  "keywords": [
+    "code-analysis",
+    "cli",
+    "code-understanding",
+    "project-analyzer"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@types/mustache": "^4.2.6",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.3",
+    "crypto-js": "^4.2.0",
+    "fs-extra": "^11.3.4",
+    "ignore": "^5.3.0",
+    "inquirer": "^13.3.0",
+    "js-yaml": "^4.1.1",
+    "mustache": "^4.2.0",
+    "openai": "^6.27.0",
+    "picocolors": "^1.1.1",
+    "simple-git": "^3.22.0",
+    "workerpool": "^9.1.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/crypto-js": "^4.2.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.9",
+    "@types/jest": "^29.5.11",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "@types/pidusage": "^2.0.5",
+    "@types/workerpool": "^6.4.7",
+    "jest": "^29.7.0",
+    "pidusage": "^4.0.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.3.3"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "type": "commonjs"
+}

package/src/adapters/command.schemas.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod'
+
+export const AnalyzeProjectCommandSchema = z.object({
+  path: z.string().optional().describe('Project root path to analyze (default: current working directory)'),
+  mode: z.enum(['full', 'incremental', 'auto']).default('auto').describe('Analysis mode'),
+  depth: z.number().int().min(1).optional().describe('Max directory depth (-1 = unlimited)'),
+  concurrency: z.number().int().min(1).optional().describe('Max concurrency (default: CPU cores * 2)'),
+  outputDir: z.string().optional().describe('Output directory for analysis results'),
+  skillsProviders: z.array(z.string()).optional().describe('AI tool providers to deploy the skill to'),
+  noSkills: z.boolean().optional().describe('Skip skill generation')
+})
+
+export type AnalyzeProjectCommandParams = z.infer<typeof AnalyzeProjectCommandSchema>
+
+export const ProjectCodeQuerySkillSchema = z.object({
+  path: z.string().describe('Relative path of the file/directory from the project root'),
+  type: z.enum(['summary', 'full', 'diagram']).default('summary').describe('Query type'),
+  projectSlug: z.string().optional().describe('Project identifier (default: current project)')
+})
+
+export type ProjectCodeQuerySkillParams = z.infer<typeof ProjectCodeQuerySkillSchema>