solo-doc 0.2.0 → 0.2.1

package/README.md

@@ -75,12 +75,23 @@ solo-doc "http://10.1.2.3/docs/index.html" --type acp
 
 ### 🤖 文档对比 (AI VS 模式)
 
-使用本地 AI 模型对比两个文档的内容差异和结构差异。此功能处于 Beta 阶段。
+使用 AI 模型对比两个文档的内容差异和结构差异。此功能处于 Beta 阶段。
 
 > **⚠️ 前置要求**:
-> 1. 本地已安装并运行 [Ollama](https://ollama.com/)。
-> 2. 已拉取所需的模型（推荐 `qwen3-vl:8b` 或类似多模态/大文本模型）。
-> 3. 确保 Ollama 服务监听在 `http://127.0.0.1:11434`。
+> 1. 需要在项目根目录或用户主目录下创建 `.solodocrc.yml` 配置文件。
+> 2. 配置兼容 OpenAI 接口的 AI 服务（支持Azure OpenAI、DeepSeek 等）。
+
+#### ⚙️ AI 配置 (.solodocrc.yml)
+
+在执行对比命令前，请创建 `.solodocrc.yml` 文件配置 AI 服务。
+
+**示例: 使用 Azure OpenAI**
+```yaml
+# 系统会自动识别 Azure 格式并处理 api-version
+MODEL_BASE_URL: "https://your-resource.openai.azure.com/2024-12-01-preview"
+MODEL_API_KEY: "your-azure-api-key"
+MODEL_NAME: "gpt-4o-mini"
+```
 
 #### 用法
 
@@ -92,16 +103,19 @@ solo-doc vs <baseline-url> <target-url> [options]
 
 ```bash
 # 对比 OpenShift 和 Alauda 的文档
+# 将使用 .solodocrc.yml 中的默认模型
 solo-doc vs \
   "https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/building_applications/index" \
-  "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html" \
-  --model qwen3-vl:8b
+  "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html"
+
+# 临时覆盖使用的模型
+solo-doc vs <url1> <url2> --model gpt-4
 ```
 
 此命令将按顺序执行：
 1. **自动爬取**: 分别爬取两个 URL 并保存为 Markdown 文件（如果已存在则跳过）。
 2. **提取目录**: 提取两个文档的目录树结构。
-3. **AI 分析**: 调用本地 Ollama 模型，根据 `solo-doc-prompt.md` 定义的提示词进行两步分析：
+3. **AI 分析**: 调用配置的 AI 模型，根据 `solo-doc-prompt.md` 定义的提示词进行两步分析：
    - 生成 `vs-result.md`: 详细的内容与结构差异分析。
    - 生成 `vs-tree.md`: 包含差异标注的合并目录树。
 
@@ -109,7 +123,7 @@ solo-doc vs \
 
 | 选项 | 描述 | 默认值 |
 |--------|-------------|---------|
-| `--model <name>` | 指定使用的 Ollama 模型名称。 | `qwen3-vl:8b` |
+| `--model <name>` | 临时覆盖配置文件中的模型名称。 | Config中的 `MODEL_NAME` |
 | `-f, --force` | 强制重新爬取文档，即使文件已存在。 | false |
 
 ## ✅ 环境要求

package/dist/bin/solo-doc.js

@@ -43,10 +43,10 @@ program
     .description('Compare two documentation sites using AI (Beta)')
     .argument('<baseline>', 'Baseline documentation URL')
     .argument('<target>', 'Target documentation URL')
-    .option('--model <model>', 'Ollama model to use', 'qwen3-vl:8b')
+    .option('--model <model>', 'AI Model name (overrides .solodocrc.yml)')
     .action(async (baseline, target, options) => {
     try {
-        console.log(chalk_1.default.yellow('⚠️  [Beta Feature] This feature requires a local Ollama instance running at http://127.0.0.1:11434'));
+        console.log(chalk_1.default.yellow('⚠️  [Beta Feature] This feature requires AI configuration in .solodocrc.yml or --model argument'));
         await VSCommand_1.VSCommand.run(baseline, target, options);
     }
     catch (error) {

package/dist/src/ai/AIClient.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class AIClient {
+    constructor(options) {
+        this.isAzure = false;
+        this.apiVersion = '';
+        const { config, modelOverride } = options;
+        // Ensure baseURL doesn't end with slash
+        let url = config.MODEL_BASE_URL || 'http://127.0.0.1:11434/v1';
+        if (url.endsWith('/')) {
+            url = url.slice(0, -1);
+        }
+        // Check for Azure URL pattern (heuristic based on user config format)
+        // User config: https://.../2024-12-01-preview
+        const azureDatePattern = /\/\d{4}-\d{2}-\d{2}(-preview)?$/;
+        if (azureDatePattern.test(url)) {
+            this.isAzure = true;
+            // Extract version from the end of URL
+            const match = url.match(azureDatePattern);
+            if (match) {
+                this.apiVersion = match[0].substring(1); // Remove leading slash
+                this.baseURL = url.substring(0, match.index); // Remove version from base
+            }
+            else {
+                this.baseURL = url;
+            }
+        }
+        else {
+            this.baseURL = url;
+        }
+        this.apiKey = config.MODEL_API_KEY || 'ollama';
+        // Priority: CLI Override > Config > Default
+        this.model = modelOverride || config.MODEL_NAME || 'qwen3-vl:8b';
+    }
+    async generate(prompt, onToken) {
+        try {
+            let requestUrl;
+            let headers = {
+                'Content-Type': 'application/json'
+            };
+            if (this.isAzure) {
+                // Azure Format: {endpoint}/openai/deployments/{model}/chat/completions?api-version={version}
+                requestUrl = `${this.baseURL}/openai/deployments/${this.model}/chat/completions?api-version=${this.apiVersion}`;
+                headers['api-key'] = this.apiKey;
+            }
+            else {
+                // Standard OpenAI Format
+                requestUrl = `${this.baseURL}/chat/completions`;
+                headers['Authorization'] = `Bearer ${this.apiKey}`;
+            }
+            const body = {
+                messages: [{ role: 'user', content: prompt }],
+                stream: true
+            };
+            if (!this.isAzure) {
+                body.model = this.model;
+            }
+            const response = await axios_1.default.post(requestUrl, body, {
+                headers,
+                responseType: 'stream'
+            });
+            let fullResponse = '';
+            return new Promise((resolve, reject) => {
+                const stream = response.data;
+                // console.log('DEBUG: Stream started');
+                let buffer = '';
+                // State for decoding JSON-stringified stream
+                let isJsonStringMode = false;
+                let isEscaping = false;
+                let hasStarted = false;
+                stream.on('data', (chunk) => {
+                    let str = chunk.toString();
+                    // Detect JSON string wrapping on the first chunk
+                    if (!hasStarted) {
+                        const trimmed = str.trimStart();
+                        if (trimmed.startsWith('"')) {
+                            isJsonStringMode = true;
+                            // Remove leading quote and anything before it
+                            const quoteIndex = str.indexOf('"');
+                            str = str.slice(quoteIndex + 1);
+                        }
+                        hasStarted = true;
+                    }
+                    if (isJsonStringMode) {
+                        let decoded = '';
+                        for (let i = 0; i < str.length; i++) {
+                            const char = str[i];
+                            if (isEscaping) {
+                                if (char === 'n')
+                                    decoded += '\n';
+                                else if (char === 'r')
+                                    decoded += '\r';
+                                else if (char === 't')
+                                    decoded += '\t';
+                                else if (char === '"')
+                                    decoded += '"';
+                                else
+                                    decoded += '\\' + char; // Keep other escapes (e.g. \u, \/)
+                                isEscaping = false;
+                            }
+                            else {
+                                if (char === '\\') {
+                                    isEscaping = true;
+                                }
+                                else if (char === '"') {
+                                    // End of JSON string (or segment), ignore or stop
+                                    // In a stream, this likely means EOF or end of wrapper
+                                }
+                                else {
+                                    decoded += char;
+                                }
+                            }
+                        }
+                        buffer += decoded;
+                    }
+                    else {
+                        buffer += str;
+                    }
+                    const lines = buffer.split('\n');
+                    // console.log('DEBUG First line:', lines[0].substring(0, 100));
+                    // Keep the last line in buffer if it's incomplete
+                    buffer = lines.pop() || '';
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed || !trimmed.startsWith('data: '))
+                            continue;
+                        const data = trimmed.slice(6).trim(); // Remove 'data: '
+                        if (data === '[DONE]')
+                            continue;
+                        try {
+                            const json = JSON.parse(data);
+                            const content = json.choices?.[0]?.delta?.content || '';
+                            if (content) {
+                                fullResponse += content;
+                                if (onToken) {
+                                    onToken(content);
+                                }
+                            }
+                        }
+                        catch (e) {
+                            // ignore parse error for partial lines
+                        }
+                    }
+                });
+                stream.on('end', () => {
+                    // console.log('DEBUG Stream ended. Full response length:', fullResponse.length);
+                    // Process remaining buffer if any
+                    if (buffer) {
+                        const trimmed = buffer.trim();
+                        if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
+                            try {
+                                const data = trimmed.slice(6).trim();
+                                const json = JSON.parse(data);
+                                const content = json.choices?.[0]?.delta?.content || '';
+                                if (content) {
+                                    fullResponse += content;
+                                    if (onToken)
+                                        onToken(content);
+                                }
+                            }
+                            catch (e) {
+                                // ignore
+                            }
+                        }
+                    }
+                    resolve(fullResponse);
+                });
+                stream.on('error', (err) => {
+                    reject(err);
+                });
+            });
+        }
+        catch (error) {
+            const msg = error.response?.data ? JSON.stringify(error.response.data) : error.message;
+            // Use the requestUrl if available, otherwise fallback
+            throw new Error(`AI API call failed: ${msg}.`);
+        }
+    }
+}
+exports.AIClient = AIClient;

package/dist/src/commands/VSCommand.js

@@ -14,13 +14,18 @@ const ACPStrategy_1 = require("../strategies/ACPStrategy");
 const StrategyDetector_1 = require("../utils/StrategyDetector");
 const filename_1 = require("../utils/filename");
 const TocExtractor_1 = require("../utils/TocExtractor");
-const OllamaClient_1 = require("../ai/OllamaClient");
+const AIClient_1 = require("../ai/AIClient");
+const config_1 = require("../utils/config");
 class VSCommand {
     static async run(baselineUrl, targetUrl, options) {
         console.log(chalk_1.default.blue(`[VS Mode] Starting comparison between:`));
         console.log(chalk_1.default.gray(`Baseline: ${baselineUrl}`));
         console.log(chalk_1.default.gray(`Target: ${targetUrl}`));
-        console.log(chalk_1.default.gray(`Model: ${options.model}`));
+        const config = config_1.ConfigLoader.load();
+        const client = new AIClient_1.AIClient({
+            config,
+            modelOverride: options.model
+        });
         // 1. Crawl Baseline
         const baselineFile = await VSCommand.crawlUrl(baselineUrl, 'baseline');
         // 2. Crawl Target
@@ -55,7 +60,6 @@ class VSCommand {
         if (prompts.length < 2) {
             throw new Error('Found fewer than 2 prompt templates in solo-doc-prompt.md');
         }
-        const client = new OllamaClient_1.OllamaClient({ model: options.model });
         // 5. Step 1: Independent Comparison
         console.log(chalk_1.default.blue(`[VS Mode] Step 1: Analyzing differences...`));
         // Replace placeholders

package/dist/src/utils/config.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const CONFIG_FILENAME = '.solodocrc.yml';
+class ConfigLoader {
+    static load() {
+        const locations = [
+            path_1.default.join(process.cwd(), CONFIG_FILENAME),
+            path_1.default.join(os_1.default.homedir(), CONFIG_FILENAME)
+        ];
+        for (const location of locations) {
+            if (fs_1.default.existsSync(location)) {
+                try {
+                    const fileContents = fs_1.default.readFileSync(location, 'utf8');
+                    const config = js_yaml_1.default.load(fileContents);
+                    if (config) {
+                        // Trim string values to avoid issues like "model "
+                        Object.keys(config).forEach(key => {
+                            if (typeof config[key] === 'string') {
+                                config[key] = config[key].trim();
+                            }
+                        });
+                        return config;
+                    }
+                    return {};
+                }
+                catch (e) {
+                    console.error(`Failed to load config from ${location}:`, e);
+                }
+            }
+        }
+        return {};
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solo-doc",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "dist/bin/solo-doc.js",
   "bin": {
     "solo-doc": "dist/bin/solo-doc.js"
@@ -12,8 +12,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "tsc",
-    "prepublishOnly": "npm run clean && npm run build",
-    "release": "npm run clean && npm run build && npm version patch --force && npm publish --access=public",
+    "publish": "npm run clean && npm run build && npm version patch --force && npm publish --access=public",
     "start": "node dist/bin/solo-doc.js",
     "dev": "ts-node bin/solo-doc.ts"
   },
@@ -22,10 +21,13 @@
   "license": "ISC",
   "description": "A CLI tool to crawl documentation sites (OCP, ACP) and convert them to a single Markdown file preserving hierarchy.",
   "dependencies": {
+    "@types/js-yaml": "^4.0.9",
     "axios": "^1.6.0",
     "chalk": "^4.1.2",
     "cheerio": "^1.0.0-rc.12",
     "commander": "^12.0.0",
+    "js-yaml": "^4.1.1",
+    "openai": "^6.15.0",
     "ora": "^5.4.1",
     "puppeteer-core": "^24.1.0",
     "turndown": "^7.2.0"

package/dist/src/ai/OllamaClient.js

@@ -1,59 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OllamaClient = void 0;
-const axios_1 = __importDefault(require("axios"));
-class OllamaClient {
-    constructor(options) {
-        // Use 127.0.0.1 instead of localhost to avoid IPv6 issues (ECONNREFUSED ::1)
-        this.endpoint = options.endpoint || 'http://127.0.0.1:11434';
-        this.model = options.model;
-    }
-    async generate(prompt, onToken) {
-        try {
-            const response = await axios_1.default.post(`${this.endpoint}/api/generate`, {
-                model: this.model,
-                prompt: prompt,
-                stream: true
-            }, {
-                responseType: 'stream'
-            });
-            let fullResponse = '';
-            return new Promise((resolve, reject) => {
-                const stream = response.data;
-                stream.on('data', (chunk) => {
-                    const lines = chunk.toString().split('\n').filter(Boolean);
-                    for (const line of lines) {
-                        try {
-                            const json = JSON.parse(line);
-                            if (json.response) {
-                                fullResponse += json.response;
-                                if (onToken) {
-                                    onToken(json.response);
-                                }
-                            }
-                            if (json.done) {
-                                // stream ended
-                            }
-                        }
-                        catch (e) {
-                            // ignore partial JSON
-                        }
-                    }
-                });
-                stream.on('end', () => {
-                    resolve(fullResponse);
-                });
-                stream.on('error', (err) => {
-                    reject(err);
-                });
-            });
-        }
-        catch (error) {
-            throw new Error(`Ollama API call failed: ${error.message}. Is Ollama running at ${this.endpoint}?`);
-        }
-    }
-}
-exports.OllamaClient = OllamaClient;