kode-sdk 2.7.0

package/dist/skills/injector.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsInjector = void 0;
+/**
+ * Skills 系统提示注入器
+ *
+ * 将 Skills 元数据转换为 XML 格式并注入系统提示
+ */
+class SkillsInjector {
+    /**
+     * 生成 available_skills XML
+     *
+     * 遵循 Agent Skills 规范的推荐格式
+     *
+     * @param skills - Skills 列表（仅需元数据）
+     * @returns XML 格式的系统提示片段
+     */
+    static toPromptXML(skills) {
+        if (skills.length === 0)
+            return '';
+        const skillsXml = skills
+            .map((skill) => {
+            const location = 'path' in skill ? `${skill.path}/SKILL.md` : '';
+            return `  <skill>
+    <name>${SkillsInjector.escapeXml(skill.name)}</name>
+    <description>${SkillsInjector.escapeXml(skill.description)}</description>${location ? `\n    <location>${SkillsInjector.escapeXml(location)}</location>` : ''}
+  </skill>`;
+        })
+            .join('\n');
+        return `
+<available_skills>
+${skillsXml}
+</available_skills>
+
+When a task matches a skill's description, use skill_activate to load its full instructions.
+`;
+    }
+    /**
+     * 生成激活后的 skill_instructions XML
+     */
+    static toActivatedXML(skill) {
+        if (!skill.body) {
+            return `<skill_instructions name="${SkillsInjector.escapeXml(skill.name)}">
+Skill body not loaded. Use skill_activate to load full content.
+</skill_instructions>`;
+        }
+        let resourcesInfo = '';
+        if (skill.resources) {
+            const parts = [];
+            if (skill.resources.scripts?.length) {
+                parts.push(`Scripts: ${skill.resources.scripts.join(', ')}`);
+            }
+            if (skill.resources.references?.length) {
+                parts.push(`References: ${skill.resources.references.join(', ')}`);
+            }
+            if (skill.resources.assets?.length) {
+                parts.push(`Assets: ${skill.resources.assets.join(', ')}`);
+            }
+            if (parts.length > 0) {
+                resourcesInfo = `\n\n[Available Resources]\n${parts.join('\n')}`;
+            }
+        }
+        return `<skill_instructions name="${SkillsInjector.escapeXml(skill.name)}">
+${skill.body}${resourcesInfo}
+</skill_instructions>`;
+    }
+    /**
+     * 转义 XML 特殊字符
+     */
+    static escapeXml(text) {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    /**
+     * 生成 Skills 总结（用于上下文压缩）
+     */
+    static toSummary(skills) {
+        if (skills.length === 0)
+            return '';
+        const activated = skills.filter((s) => s.activatedAt);
+        const available = skills.filter((s) => !s.activatedAt);
+        let summary = '[Skills Status]\n';
+        if (activated.length > 0) {
+            summary += `Activated: ${activated.map((s) => s.name).join(', ')}\n`;
+        }
+        if (available.length > 0) {
+            summary += `Available: ${available.map((s) => s.name).join(', ')}\n`;
+        }
+        return summary;
+    }
+}
+exports.SkillsInjector = SkillsInjector;

package/dist/skills/loader.d.ts

@@ -0,0 +1,59 @@
+import { Sandbox } from '../infra/sandbox';
+import { Skill, SkillResources, SkillsConfig } from './types';
+/**
+ * Skills 加载器
+ *
+ * 负责发现和加载 Skills
+ */
+export declare class SkillsLoader {
+    private readonly sandbox;
+    private readonly parser;
+    private readonly validator;
+    constructor(sandbox: Sandbox);
+    /**
+     * 发现所有 Skills（仅加载元数据，不加载完整内容）
+     *
+     * 这是 Progressive Disclosure 的第一阶段：
+     * 只加载 name 和 description，用于注入系统提示
+     */
+    discover(config: SkillsConfig): Promise<Skill[]>;
+    /**
+     * 加载 Skill 元数据（不含完整正文）
+     */
+    loadMetadata(skillDir: string, config?: SkillsConfig): Promise<Skill | null>;
+    /**
+     * 加载完整 Skill 内容（包括正文和资源列表）
+     *
+     * 这是 Progressive Disclosure 的第二阶段：
+     * 当 Agent 激活 Skill 时，加载完整内容
+     */
+    loadFull(skillDir: string): Promise<Skill>;
+    /**
+     * 扫描 Skill 的资源目录
+     */
+    scanResources(skillDir: string): Promise<SkillResources>;
+    /**
+     * 加载资源文件内容
+     */
+    loadResource(skillDir: string, resourcePath: string): Promise<string>;
+    /**
+     * 查找包含 SKILL.md 的目录
+     */
+    private findSkillDirs;
+    /**
+     * 列出目录中的文件
+     */
+    private listFiles;
+    /**
+     * 列出目录中的文件，返回相对 skillDir 的路径（用于 skill_resource 的 resourcePath）
+     */
+    private listFilesRelative;
+    /**
+     * 检查路径是否存在
+     */
+    private pathExists;
+    /**
+     * 检查是否应该包含该 Skill
+     */
+    private shouldInclude;
+}

package/dist/skills/loader.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsLoader = void 0;
+const path_1 = __importDefault(require("path"));
+const parser_1 = require("./parser");
+const validator_1 = require("./validator");
+/**
+ * Skills 加载器
+ *
+ * 负责发现和加载 Skills
+ */
+class SkillsLoader {
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+        this.parser = new parser_1.SkillsParser();
+        this.validator = new validator_1.SkillsValidator();
+    }
+    /**
+     * 发现所有 Skills（仅加载元数据，不加载完整内容）
+     *
+     * 这是 Progressive Disclosure 的第一阶段：
+     * 只加载 name 和 description，用于注入系统提示
+     */
+    async discover(config) {
+        const skills = [];
+        for (const searchPath of config.paths) {
+            try {
+                const resolvedPath = this.sandbox.fs.resolve(searchPath);
+                const exists = await this.pathExists(resolvedPath);
+                if (!exists)
+                    continue;
+                const dirs = await this.findSkillDirs(resolvedPath);
+                for (const dir of dirs) {
+                    try {
+                        const skill = await this.loadMetadata(dir, config);
+                        if (skill && this.shouldInclude(skill.name, config)) {
+                            skills.push(skill);
+                        }
+                    }
+                    catch (error) {
+                        // 跳过无效的 Skill 目录，继续处理其他
+                        console.warn(`[SkillsLoader] Failed to load skill from ${dir}:`, error);
+                    }
+                }
+            }
+            catch (error) {
+                console.warn(`[SkillsLoader] Failed to scan path ${searchPath}:`, error);
+            }
+        }
+        return skills;
+    }
+    /**
+     * 加载 Skill 元数据（不含完整正文）
+     */
+    async loadMetadata(skillDir, config) {
+        const skillMdPath = path_1.default.join(skillDir, 'SKILL.md');
+        const exists = await this.pathExists(skillMdPath);
+        if (!exists) {
+            return null;
+        }
+        const content = await this.sandbox.fs.read(skillMdPath);
+        const { metadata } = this.parser.parse(content);
+        // 可选：验证格式
+        if (config?.validateOnLoad) {
+            const validation = this.validator.validate(metadata);
+            if (!validation.valid) {
+                throw new Error(`Skill validation failed: ${validation.errors.join(', ')}`);
+            }
+        }
+        return {
+            ...metadata,
+            path: skillDir,
+            loadedAt: Date.now(),
+        };
+    }
+    /**
+     * 加载完整 Skill 内容（包括正文和资源列表）
+     *
+     * 这是 Progressive Disclosure 的第二阶段：
+     * 当 Agent 激活 Skill 时，加载完整内容
+     */
+    async loadFull(skillDir) {
+        const skillMdPath = path_1.default.join(skillDir, 'SKILL.md');
+        const content = await this.sandbox.fs.read(skillMdPath);
+        const { metadata, body } = this.parser.parse(content);
+        const resources = await this.scanResources(skillDir);
+        return {
+            ...metadata,
+            path: skillDir,
+            body,
+            resources,
+            loadedAt: Date.now(),
+        };
+    }
+    /**
+     * 扫描 Skill 的资源目录
+     */
+    async scanResources(skillDir) {
+        const resources = {};
+        // 扫描 scripts/
+        const scriptsDir = path_1.default.join(skillDir, 'scripts');
+        if (await this.pathExists(scriptsDir)) {
+            resources.scripts = await this.listFilesRelative(skillDir, scriptsDir);
+        }
+        // 扫描 references/
+        const referencesDir = path_1.default.join(skillDir, 'references');
+        if (await this.pathExists(referencesDir)) {
+            resources.references = await this.listFilesRelative(skillDir, referencesDir);
+        }
+        // 扫描 assets/
+        const assetsDir = path_1.default.join(skillDir, 'assets');
+        if (await this.pathExists(assetsDir)) {
+            resources.assets = await this.listFilesRelative(skillDir, assetsDir);
+        }
+        return resources;
+    }
+    /**
+     * 加载资源文件内容
+     */
+    async loadResource(skillDir, resourcePath) {
+        const fullPath = path_1.default.join(skillDir, resourcePath);
+        // 安全检查：防止路径遍历
+        const resolvedFull = path_1.default.resolve(fullPath);
+        const resolvedSkill = path_1.default.resolve(skillDir);
+        if (!resolvedFull.startsWith(resolvedSkill + path_1.default.sep) && resolvedFull !== resolvedSkill) {
+            throw new Error('Path traversal not allowed');
+        }
+        return await this.sandbox.fs.read(fullPath);
+    }
+    /**
+     * 查找包含 SKILL.md 的目录
+     */
+    async findSkillDirs(searchPath) {
+        const skillDirs = [];
+        try {
+            // 使用 glob 查找所有 SKILL.md 文件
+            const pattern = '*/SKILL.md';
+            const matches = await this.sandbox.fs.glob(pattern, {
+                cwd: searchPath,
+                absolute: true,
+            });
+            for (const skillMdPath of matches) {
+                // 获取 SKILL.md 所在目录
+                const skillDir = path_1.default.dirname(skillMdPath);
+                skillDirs.push(skillDir);
+            }
+        }
+        catch {
+            // 搜索路径不存在或无法读取
+        }
+        return skillDirs;
+    }
+    /**
+     * 列出目录中的文件
+     */
+    async listFiles(dirPath) {
+        try {
+            // 使用 glob 列出目录中的文件
+            const pattern = '*';
+            const matches = await this.sandbox.fs.glob(pattern, {
+                cwd: dirPath,
+                absolute: false,
+            });
+            return matches;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 列出目录中的文件，返回相对 skillDir 的路径（用于 skill_resource 的 resourcePath）
+     */
+    async listFilesRelative(skillDir, dirPath) {
+        try {
+            const matches = await this.sandbox.fs.glob('*', {
+                cwd: dirPath,
+                absolute: true,
+            });
+            return matches.map((abs) => path_1.default.relative(skillDir, abs).split(path_1.default.sep).join('/'));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 检查路径是否存在
+     */
+    async pathExists(filePath) {
+        try {
+            await this.sandbox.fs.stat(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 检查是否应该包含该 Skill
+     */
+    shouldInclude(name, config) {
+        // 检查黑名单
+        if (config.exclude?.includes(name)) {
+            return false;
+        }
+        // 如果有白名单，只包含白名单中的
+        if (config.include && config.include.length > 0) {
+            return config.include.includes(name);
+        }
+        return true;
+    }
+}
+exports.SkillsLoader = SkillsLoader;

package/dist/skills/manager.d.ts

@@ -0,0 +1,85 @@
+import { Sandbox } from '../infra/sandbox';
+import { Store } from '../infra/store';
+import { Skill, SkillMetadata, SkillsConfig, SkillActivation } from './types';
+/**
+ * Skills 状态管理器
+ *
+ * 管理 Skills 的发现、激活和持久化状态
+ */
+export declare class SkillsManager {
+    private readonly config;
+    private readonly sandbox;
+    private readonly store?;
+    private readonly agentId?;
+    private readonly discovered;
+    private readonly activated;
+    private readonly loader;
+    constructor(config: SkillsConfig, sandbox: Sandbox, store?: Store | undefined, agentId?: string | undefined);
+    /**
+     * 发现所有 Skills（仅加载元数据）
+     *
+     * 这是 Progressive Disclosure 的第一阶段
+     */
+    discover(): Promise<SkillMetadata[]>;
+    /**
+     * 激活 Skill（加载完整内容）
+     *
+     * 这是 Progressive Disclosure 的第二阶段
+     */
+    activate(name: string, activatedBy?: 'auto' | 'agent' | 'user'): Promise<Skill>;
+    /**
+     * 停用 Skill
+     */
+    deactivate(name: string): Promise<void>;
+    /**
+     * 批量自动激活 Skills
+     *
+     * 用于 Template 配置的 autoActivate Skills
+     * 静默失败：如果 Skill 不存在则跳过，不抛错
+     */
+    autoActivateSkills(names: string[]): Promise<Skill[]>;
+    /**
+     * 获取已发现的 Skills 列表
+     */
+    list(): Skill[];
+    /**
+     * 获取单个 Skill
+     */
+    get(name: string): Skill | undefined;
+    /**
+     * 检查 Skill 是否已激活
+     */
+    isActivated(name: string): boolean;
+    /**
+     * 获取已激活的 Skills
+     */
+    getActivated(): Skill[];
+    /**
+     * 获取 Skill 的激活信息
+     */
+    getActivation(name: string): SkillActivation | undefined;
+    /**
+     * 检查 Skill 是否来自可信来源
+     */
+    isTrusted(name: string): boolean;
+    /**
+     * 获取 Skill 声明的 allowed-tools
+     */
+    getAllowedTools(name: string): string[] | undefined;
+    /**
+     * 加载 Skill 的资源文件
+     */
+    loadResource(skillName: string, resourcePath: string): Promise<string>;
+    /**
+     * 持久化状态到 Store
+     */
+    persistState(): Promise<void>;
+    /**
+     * 从 Store 恢复状态（用于 Resume）
+     */
+    restoreState(): Promise<void>;
+    /**
+     * 获取 Skills 配置
+     */
+    getConfig(): SkillsConfig;
+}

package/dist/skills/manager.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsManager = void 0;
+const loader_1 = require("./loader");
+/**
+ * Skills 状态管理器
+ *
+ * 管理 Skills 的发现、激活和持久化状态
+ */
+class SkillsManager {
+    constructor(config, sandbox, store, agentId) {
+        this.config = config;
+        this.sandbox = sandbox;
+        this.store = store;
+        this.agentId = agentId;
+        this.discovered = new Map();
+        this.activated = new Map();
+        this.loader = new loader_1.SkillsLoader(sandbox);
+    }
+    /**
+     * 发现所有 Skills（仅加载元数据）
+     *
+     * 这是 Progressive Disclosure 的第一阶段
+     */
+    async discover() {
+        const skills = await this.loader.discover(this.config);
+        // Refresh discovery snapshot: remove skills that no longer exist on disk.
+        // Preserve previously loaded bodies/resources when possible.
+        const previous = new Map(this.discovered);
+        this.discovered.clear();
+        // Deduplicate by name while keeping later entries higher priority.
+        // This matters when multiple search paths contain the same skill name
+        // (e.g. bundled skills vs user-level overrides).
+        const unique = new Map();
+        for (const skill of skills) {
+            if (!skill?.name)
+                continue;
+            if (unique.has(skill.name)) {
+                // Move to the end to reflect "last wins" semantics.
+                unique.delete(skill.name);
+                console.warn(`[SkillsManager] Duplicate skill "${skill.name}" discovered; using the later one.`);
+            }
+            unique.set(skill.name, skill);
+        }
+        for (const skill of unique.values()) {
+            const prev = previous.get(skill.name);
+            if (prev) {
+                if (prev.body && !skill.body)
+                    skill.body = prev.body;
+                if (prev.resources && !skill.resources)
+                    skill.resources = prev.resources;
+                if (typeof prev.activatedAt === 'number')
+                    skill.activatedAt = prev.activatedAt;
+            }
+            this.discovered.set(skill.name, skill);
+        }
+        return Array.from(unique.values());
+    }
+    /**
+     * 激活 Skill（加载完整内容）
+     *
+     * 这是 Progressive Disclosure 的第二阶段
+     */
+    async activate(name, activatedBy = 'agent') {
+        const skill = this.discovered.get(name);
+        if (!skill) {
+            throw new Error(`Skill not found: ${name}. Available skills: ${Array.from(this.discovered.keys()).join(', ')}`);
+        }
+        // 如果尚未加载完整内容，则加载
+        if (!skill.body) {
+            const fullSkill = await this.loader.loadFull(skill.path);
+            Object.assign(skill, fullSkill);
+            this.discovered.set(name, skill);
+        }
+        // 记录激活状态
+        skill.activatedAt = Date.now();
+        const activation = {
+            name,
+            activatedAt: skill.activatedAt,
+            activatedBy,
+            toolsGranted: skill.allowedTools,
+        };
+        this.activated.set(name, activation);
+        // 持久化状态
+        await this.persistState();
+        return skill;
+    }
+    /**
+     * 停用 Skill
+     */
+    async deactivate(name) {
+        this.activated.delete(name);
+        const skill = this.discovered.get(name);
+        if (skill) {
+            skill.activatedAt = undefined;
+        }
+        await this.persistState();
+    }
+    /**
+     * 批量自动激活 Skills
+     *
+     * 用于 Template 配置的 autoActivate Skills
+     * 静默失败：如果 Skill 不存在则跳过，不抛错
+     */
+    async autoActivateSkills(names) {
+        const activated = [];
+        for (const name of names) {
+            if (!this.discovered.has(name)) {
+                // 静默跳过不存在的 Skill
+                console.warn(`[SkillsManager] Skill "${name}" not found for auto-activation, skipping`);
+                continue;
+            }
+            if (this.isActivated(name)) {
+                // 已激活则跳过
+                const skill = this.discovered.get(name);
+                if (skill)
+                    activated.push(skill);
+                continue;
+            }
+            try {
+                const skill = await this.activate(name, 'auto');
+                activated.push(skill);
+            }
+            catch (error) {
+                console.warn(`[SkillsManager] Failed to auto-activate skill "${name}":`, error);
+            }
+        }
+        return activated;
+    }
+    /**
+     * 获取已发现的 Skills 列表
+     */
+    list() {
+        return Array.from(this.discovered.values());
+    }
+    /**
+     * 获取单个 Skill
+     */
+    get(name) {
+        return this.discovered.get(name);
+    }
+    /**
+     * 检查 Skill 是否已激活
+     */
+    isActivated(name) {
+        return this.activated.has(name);
+    }
+    /**
+     * 获取已激活的 Skills
+     */
+    getActivated() {
+        return Array.from(this.activated.keys())
+            .map((name) => this.discovered.get(name))
+            .filter((s) => s !== undefined);
+    }
+    /**
+     * 获取 Skill 的激活信息
+     */
+    getActivation(name) {
+        return this.activated.get(name);
+    }
+    /**
+     * 检查 Skill 是否来自可信来源
+     */
+    isTrusted(name) {
+        if (!this.config.trusted || this.config.trusted.length === 0) {
+            return false;
+        }
+        return this.config.trusted.includes(name);
+    }
+    /**
+     * 获取 Skill 声明的 allowed-tools
+     */
+    getAllowedTools(name) {
+        return this.discovered.get(name)?.allowedTools;
+    }
+    /**
+     * 加载 Skill 的资源文件
+     */
+    async loadResource(skillName, resourcePath) {
+        const skill = this.discovered.get(skillName);
+        if (!skill) {
+            throw new Error(`Skill not found: ${skillName}`);
+        }
+        return await this.loader.loadResource(skill.path, resourcePath);
+    }
+    /**
+     * 持久化状态到 Store
+     */
+    async persistState() {
+        if (!this.store || !this.agentId)
+            return;
+        const state = {
+            discovered: Array.from(this.discovered.keys()),
+            activated: Array.from(this.activated.values()),
+            lastDiscoveryAt: Date.now(),
+        };
+        await this.store.saveSkillsState(this.agentId, state);
+    }
+    /**
+     * 从 Store 恢复状态（用于 Resume）
+     */
+    async restoreState() {
+        if (!this.store || !this.agentId)
+            return;
+        const state = await this.store.loadSkillsState(this.agentId);
+        if (!state)
+            return;
+        // 恢复激活状态
+        for (const activation of state.activated) {
+            this.activated.set(activation.name, activation);
+        }
+    }
+    /**
+     * 获取 Skills 配置
+     */
+    getConfig() {
+        return this.config;
+    }
+}
+exports.SkillsManager = SkillsManager;