@optima-chat/optima-agent 0.4.27 → 0.4.29

package/dist/src/validation/suggestions.js

@@ -0,0 +1,144 @@
+/**
+ * 从 Zod 错误生成修复建议
+ */
+export function generateSuggestionsFromZodError(zodError) {
+    const suggestions = [];
+    for (const issue of zodError.issues) {
+        switch (issue.code) {
+            case "invalid_type":
+                suggestions.push(`字段 "${issue.path.join(".")}" 的类型应该是 ${issue.expected}，但实际是 ${issue.received}`);
+                break;
+            case "invalid_enum_value":
+                suggestions.push(`字段 "${issue.path.join(".")}" 只能是以下值之一: ${issue.options.join(", ")}`);
+                break;
+            case "too_small":
+                if (issue.type === "string") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 至少需要 ${issue.minimum} 个字符`);
+                }
+                else if (issue.type === "array") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 至少需要 ${issue.minimum} 个元素`);
+                }
+                else if (issue.type === "number") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 的值不能小于 ${issue.minimum}`);
+                }
+                break;
+            case "too_big":
+                if (issue.type === "string") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 最多 ${issue.maximum} 个字符`);
+                }
+                else if (issue.type === "array") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 最多 ${issue.maximum} 个元素`);
+                }
+                else if (issue.type === "number") {
+                    suggestions.push(`字段 "${issue.path.join(".")}" 的值不能大于 ${issue.maximum}`);
+                }
+                break;
+            case "invalid_literal":
+                suggestions.push(`字段 "${issue.path.join(".")}" 必须是 "${issue.expected}"`);
+                break;
+            case "unrecognized_keys":
+                suggestions.push(`未识别的字段: ${issue.keys.join(", ")}。请检查拼写是否正确`);
+                break;
+            default:
+                suggestions.push(issue.message);
+        }
+    }
+    return suggestions;
+}
+/**
+ * 为 YAML 语法错误生成建议
+ */
+export function generateYamlSyntaxSuggestions(errorMessage) {
+    const suggestions = [];
+    if (errorMessage.includes("indent") || errorMessage.includes("缩进")) {
+        suggestions.push("检查 YAML 缩进是否正确（应使用 2 个空格）");
+        suggestions.push("确保同级元素的缩进对齐");
+    }
+    if (errorMessage.includes("unexpected") || errorMessage.includes("意外")) {
+        suggestions.push("检查是否有多余的冒号、逗号或引号");
+        suggestions.push("确保字符串包含特殊字符时使用引号");
+    }
+    if (errorMessage.includes("mapping") || errorMessage.includes("键值对")) {
+        suggestions.push("确保每个键后面有冒号和空格（key: value）");
+        suggestions.push("检查是否有重复的键");
+    }
+    if (errorMessage.includes("sequence") || errorMessage.includes("列表")) {
+        suggestions.push("列表项应以 '- ' 开头（破折号后有空格）");
+        suggestions.push("确保列表项的缩进一致");
+    }
+    // 通用建议
+    if (suggestions.length === 0) {
+        suggestions.push("检查 YAML 语法是否正确");
+        suggestions.push("可以使用在线 YAML 验证工具检查格式");
+    }
+    return suggestions;
+}
+/**
+ * 为 JSON 语法错误生成建议
+ */
+export function generateJsonSyntaxSuggestions(errorMessage) {
+    const suggestions = [];
+    if (errorMessage.includes("Unexpected token") || errorMessage.includes("意外的标记")) {
+        suggestions.push("检查是否有多余的逗号（特别是最后一个元素后）");
+        suggestions.push("确保所有字符串都用双引号包裹");
+        suggestions.push("检查括号、方括号是否成对");
+    }
+    if (errorMessage.includes("Expected") || errorMessage.includes("期望")) {
+        suggestions.push("检查是否缺少逗号、冒号或引号");
+        suggestions.push("确保对象的键都是字符串（用双引号包裹）");
+    }
+    if (errorMessage.includes("position") || errorMessage.includes("位置")) {
+        suggestions.push("检查指定位置附近的语法");
+    }
+    // 通用建议
+    suggestions.push("可以使用 JSON 格式化工具检查格式");
+    suggestions.push("JSON 不支持注释，请删除所有注释");
+    return suggestions;
+}
+/**
+ * 为 Skill 配置生成特定建议
+ */
+export function generateSkillConfigSuggestions(path) {
+    const suggestions = [];
+    const field = path.join(".");
+    if (field === "name") {
+        suggestions.push("name 是必需字段，用于标识 skill");
+        suggestions.push("name 应该使用小写字母和连字符，如 'my-skill'");
+    }
+    if (field === "description") {
+        suggestions.push("description 建议填写，用于说明 skill 的功能");
+    }
+    if (field.includes("hooks")) {
+        suggestions.push("hooks 支持的事件类型: SessionStart, PreToolUse, PostToolUse, Stop");
+        suggestions.push("每个事件可以包含多个钩子配置");
+    }
+    if (field.includes("hooks") && field.includes("command")) {
+        suggestions.push("command 应该是有效的 shell 命令");
+        suggestions.push("可以使用 ${CLAUDE_PLUGIN_ROOT} 引用 skill 目录");
+    }
+    if (field.includes("matcher")) {
+        suggestions.push("matcher 是可选的正则表达式，用于匹配特定的工具调用");
+        suggestions.push("如果不需要匹配，可以省略 matcher 字段");
+    }
+    return suggestions;
+}
+/**
+ * 为 Optima 配置生成特定建议
+ */
+export function generateOptimaConfigSuggestions(path) {
+    const suggestions = [];
+    const field = path.join(".");
+    if (field === "model") {
+        suggestions.push("model 指定使用的 Claude 模型");
+        suggestions.push("建议使用最新的模型以获得最佳性能");
+    }
+    if (field === "theme") {
+        suggestions.push("theme 只能是 'dark' 或 'light'");
+    }
+    if (field.includes("server.port")) {
+        suggestions.push("端口号必须是 1-65535 之间的整数");
+        suggestions.push("确保端口未被其他程序占用");
+    }
+    return suggestions;
+}
+//# sourceMappingURL=suggestions.js.map

package/dist/src/validation/suggestions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.js","sourceRoot":"","sources":["../../../src/validation/suggestions.ts"],"names":[],"mappings":"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"}

package/dist/src/validation/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 配置验证模块类型定义
+ */
+export interface ValidationError {
+    /** 错误类型 */
+    type: "syntax" | "schema" | "semantic";
+    /** 文件路径 */
+    filePath: string;
+    /** 错误消息 */
+    message: string;
+    /** 详细描述 */
+    details?: string;
+    /** 错误位置（行号） */
+    line?: number;
+    /** 错误位置（列号） */
+    column?: number;
+    /** 问题字段路径 */
+    path?: string[];
+    /** 修复建议 */
+    suggestions: string[];
+    /** 相关文档链接 */
+    docUrl?: string;
+    /** 示例配置路径 */
+    examplePath?: string;
+}
+export interface ValidationResult {
+    /** 是否验证成功 */
+    valid: boolean;
+    /** 验证错误列表 */
+    errors: ValidationError[];
+    /** 警告列表 */
+    warnings?: ValidationError[];
+}
+export interface Validator<T> {
+    /** 验证配置 */
+    validate(content: string, filePath: string): ValidationResult;
+    /** 解析配置（验证成功后） */
+    parse(content: string): T | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/validation/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,WAAW;IACX,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IACvC,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW;IACX,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa;IACb,KAAK,EAAE,OAAO,CAAC;IACf,aAAa;IACb,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,WAAW;IACX,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC9D,kBAAkB;IAClB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC;CAClC"}

package/dist/src/validation/types.js

@@ -0,0 +1,5 @@
+/**
+ * 配置验证模块类型定义
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/validation/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/validation/yaml-validator.d.ts

@@ -0,0 +1,25 @@
+import type { Validator, ValidationResult } from "./types.js";
+import { type SkillYamlFrontmatter } from "./schema.js";
+export declare class YamlValidator implements Validator<SkillYamlFrontmatter> {
+    /**
+     * 从内容中提取 YAML frontmatter
+     */
+    private extractFrontmatter;
+    /**
+     * 解析 YAML 内容
+     */
+    private parseYaml;
+    /**
+     * 从 YAML 错误中提取行号
+     */
+    private extractLineNumber;
+    /**
+     * 验证 YAML frontmatter
+     */
+    validate(content: string, filePath: string): ValidationResult;
+    /**
+     * 解析配置（验证成功后调用）
+     */
+    parse(content: string): SkillYamlFrontmatter | null;
+}
+//# sourceMappingURL=yaml-validator.d.ts.map

package/dist/src/validation/yaml-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-validator.d.ts","sourceRoot":"","sources":["../../../src/validation/yaml-validator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAA8B,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQpF,qBAAa,aAAc,YAAW,SAAS,CAAC,oBAAoB,CAAC;IACnE;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAmH7D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;CAiBpD"}

package/dist/src/validation/yaml-validator.js

@@ -0,0 +1,177 @@
+/**
+ * YAML 配置验证器
+ */
+import yaml from "js-yaml";
+import { ZodError } from "zod";
+import { SkillYamlFrontmatterSchema } from "./schema.js";
+import { generateSuggestionsFromZodError, generateYamlSyntaxSuggestions, generateSkillConfigSuggestions, } from "./suggestions.js";
+export class YamlValidator {
+    /**
+     * 从内容中提取 YAML frontmatter
+     */
+    extractFrontmatter(content) {
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!match) {
+            return null;
+        }
+        return {
+            yaml: match[1],
+            line: 1, // frontmatter 从第一行开始
+        };
+    }
+    /**
+     * 解析 YAML 内容
+     */
+    parseYaml(yamlContent) {
+        try {
+            const data = yaml.load(yamlContent);
+            return { data };
+        }
+        catch (error) {
+            return { data: null, error: error };
+        }
+    }
+    /**
+     * 从 YAML 错误中提取行号
+     */
+    extractLineNumber(error) {
+        // js-yaml 的错误消息通常包含 "at line X, column Y"
+        const match = error.message.match(/at line (\d+)/);
+        if (match) {
+            return parseInt(match[1], 10);
+        }
+        return undefined;
+    }
+    /**
+     * 验证 YAML frontmatter
+     */
+    validate(content, filePath) {
+        const errors = [];
+        const warnings = [];
+        // 1. 检查是否存在 frontmatter
+        const frontmatter = this.extractFrontmatter(content);
+        if (!frontmatter) {
+            errors.push({
+                type: "syntax",
+                filePath,
+                message: "未找到 YAML frontmatter",
+                details: "SKILL.md 文件应该以 YAML frontmatter 开头（用 --- 包裹）",
+                suggestions: [
+                    "在文件开头添加 YAML frontmatter",
+                    "格式应为: ---\\n配置内容\\n---",
+                    "参考示例: .claude/skills/planning-with-files/SKILL.md",
+                ],
+                examplePath: ".claude/skills/planning-with-files/SKILL.md",
+            });
+            return { valid: false, errors, warnings };
+        }
+        // 2. 解析 YAML
+        const { data, error: yamlError } = this.parseYaml(frontmatter.yaml);
+        if (yamlError) {
+            const line = this.extractLineNumber(yamlError);
+            errors.push({
+                type: "syntax",
+                filePath,
+                message: "YAML 语法错误",
+                details: yamlError.message,
+                line,
+                suggestions: generateYamlSyntaxSuggestions(yamlError.message),
+                examplePath: ".claude/skills/planning-with-files/SKILL.md",
+            });
+            return { valid: false, errors, warnings };
+        }
+        // 3. 使用 Zod 验证 schema
+        try {
+            SkillYamlFrontmatterSchema.parse(data);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                for (const issue of error.issues) {
+                    const zodSuggestions = generateSuggestionsFromZodError(error);
+                    const skillSuggestions = generateSkillConfigSuggestions(issue.path.map(String));
+                    errors.push({
+                        type: "schema",
+                        filePath,
+                        message: issue.message,
+                        path: issue.path.map(String),
+                        suggestions: [...zodSuggestions, ...skillSuggestions],
+                        examplePath: ".claude/skills/planning-with-files/SKILL.md",
+                    });
+                }
+            }
+            else {
+                errors.push({
+                    type: "schema",
+                    filePath,
+                    message: "未知的验证错误",
+                    details: String(error),
+                    suggestions: ["请检查配置文件格式"],
+                });
+            }
+            return { valid: false, errors, warnings };
+        }
+        // 4. 语义检查和警告
+        if (!data.description) {
+            warnings.push({
+                type: "semantic",
+                filePath,
+                message: "建议添加 description 字段",
+                suggestions: ["description 可以帮助用户理解 skill 的功能", "建议填写清晰的功能描述"],
+            });
+        }
+        // 检查 hooks 中的命令
+        if (data.hooks) {
+            for (const [eventType, configs] of Object.entries(data.hooks)) {
+                if (Array.isArray(configs)) {
+                    for (const config of configs) {
+                        if (config.hooks) {
+                            for (const hook of config.hooks) {
+                                if (hook.command && hook.command.includes("${CLAUDE_PLUGIN_ROOT}")) {
+                                    // 检查命令中的路径引用
+                                    const scriptPath = hook.command.match(/\$\{CLAUDE_PLUGIN_ROOT\}\/(.+?)(?:\s|$)/)?.[1];
+                                    if (scriptPath) {
+                                        warnings.push({
+                                            type: "semantic",
+                                            filePath,
+                                            message: `确保脚本文件存在: ${scriptPath}`,
+                                            path: ["hooks", eventType, "hooks", "command"],
+                                            suggestions: [
+                                                "检查脚本文件是否在 skill 目录中",
+                                                "确保脚本文件有执行权限（chmod +x）",
+                                            ],
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * 解析配置（验证成功后调用）
+     */
+    parse(content) {
+        const frontmatter = this.extractFrontmatter(content);
+        if (!frontmatter) {
+            return null;
+        }
+        const { data, error } = this.parseYaml(frontmatter.yaml);
+        if (error) {
+            return null;
+        }
+        try {
+            return SkillYamlFrontmatterSchema.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=yaml-validator.js.map

package/dist/src/validation/yaml-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-validator.js","sourceRoot":"","sources":["../../../src/validation/yaml-validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",