@qlingzzy/qling 1.0.0

package/dist/tools/skill.js

@@ -0,0 +1,181 @@
+// ============================================================
+// 轻灵 - s05 Skill 加载
+// 动态加载 .md 知识文件，通过 tool_result 注入上下文
+// 格言：用到什么知识，临时加载什么知识，不塞 system prompt
+// ============================================================
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, join } from "path";
+import { toolError, toolSuccess } from "./error-utils.js";
+import { listSkills, searchSkills } from "../skills/registry.js";
+// Skill 查找路径
+// 支持两种格式：
+//   name="foo"        → 搜索 skills/foo.md
+//   name="@scope/foo" → 搜索 skills/scopes/scope/foo.md
+export function getSkillDirs() {
+    const dirs = [
+        resolve(process.cwd(), "skills"),
+        resolve(process.cwd(), ".qling/skills"),
+    ];
+    const hermesHome = process.env.HERMES_HOME;
+    if (hermesHome && hermesHome.trim()) {
+        dirs.push(join(hermesHome.trim(), "skills"));
+    }
+    return dirs;
+}
+function resolveSkillPath(name) {
+    const dirs = getSkillDirs();
+    // @scope/name 格式
+    const scoped = name.match(/^@([^/]+)\/(.+)$/);
+    if (scoped) {
+        const [, scope, base] = scoped;
+        for (const dir of dirs) {
+            // scopes/scope/name.md
+            const p = join(dir, "scopes", scope, `${base}.md`);
+            if (existsSync(p))
+                return p;
+            // scopes/scope/name/index.md
+            const p2 = join(dir, "scopes", scope, base, "index.md");
+            if (existsSync(p2))
+                return p2;
+        }
+        return null;
+    }
+    // 普通 name 格式
+    for (const dir of dirs) {
+        const p = join(dir, `${name}.md`);
+        if (existsSync(p))
+            return p;
+        // name/index.md
+        const p2 = join(dir, name, "index.md");
+        if (existsSync(p2))
+            return p2;
+        const p3 = join(dir, name, "SKILL.md");
+        if (existsSync(p3))
+            return p3;
+    }
+    return null;
+}
+export const skillTool = {
+    name: "skill",
+    description: "Dynamically load a skill/knowledge file (.md). Use when encountering unfamiliar tools, APIs, or frameworks. Use 'list' to discover available skills, 'search query=X' to find skills, or 'name=X' to load one.",
+    longDescription: `动态加载技能/知识文件（SKILL.md），内容通过 tool_result 注入上下文。
+
+**核心原则**: "用到什么知识，临时加载什么知识，不塞 system prompt"
+
+**三种操作**:
+- skill list — 列出所有可用技能
+- skill search query="docker" — 搜索技能
+- skill name="docker" — 加载技能内容
+
+**查找路径**:
+- skills/{name}.md
+- skills/{category}/{name}.md
+- @scope/name → scopes/{scope}/{name}.md
+
+**使用场景**:
+- 调用 docker 但不熟悉命令 → skill(name="docker")
+- 调用 Kubernetes API → skill(name="k8s-debug")
+- 不确定有哪些技能 → skill list
+- 搜索特定领域技能 → skill search query="api"
+
+**返回内容**:
+- 文件的 markdown body（不含 frontmatter）
+- 包含使用说明、命令示例、已知陷阱`,
+    parameters: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Skill name without .md extension (e.g. 'docker', '@k8s/debug'), or 'list' to list all skills",
+            },
+            query: {
+                type: "string",
+                description: "Search query for finding skills by name/description/tags (used with search action)",
+            },
+        },
+        required: [],
+    },
+    paramSchema: {
+        name: {
+            type: "string",
+            description: "技能名称（不含 .md 后缀）。支持普通格式和 @scope/name 格式。传 'list' 列出所有技能。",
+            minLength: 1,
+            pattern: "^[a-zA-Z0-9_/@-]+$",
+        },
+        query: {
+            type: "string",
+            description: "搜索关键词，按名称/描述/标签模糊匹配。",
+        },
+    },
+    examples: [
+        'skill list',
+        'skill search query="docker"',
+        'skill name="docker"',
+        'skill name="python-async"',
+        'skill name="@k8s/debug"',
+    ],
+    seeAlso: ["bash", "todo"],
+    scenes: ["knowledge", "planning"],
+    priority: 6,
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+    effortHint: "minimal",
+};
+export async function runSkill(args) {
+    const name = String(args.name ?? "").trim();
+    const query = String(args.query ?? "").trim();
+    // list mode
+    if (name === "list") {
+        const dirs = getSkillDirs();
+        const skills = await listSkills(dirs);
+        if (skills.length === 0) {
+            return toolSuccess("No skills found. Create .md files in skills/ directory to add skills.");
+        }
+        const lines = skills.map((s) => {
+            const tags = s.tags.length > 0 ? ` [${s.tags.join(", ")}]` : "";
+            return `- ${s.name}: ${s.description || "(no description)"}${tags}`;
+        });
+        return toolSuccess(`Available skills (${skills.length}):\n${lines.join("\n")}`);
+    }
+    // search mode
+    if (query) {
+        const dirs = getSkillDirs();
+        const results = await searchSkills(query, dirs);
+        if (results.length === 0) {
+            return toolSuccess(`No skills matching "${query}".`);
+        }
+        const lines = results.map((s) => {
+            const tags = s.tags.length > 0 ? ` [${s.tags.join(", ")}]` : "";
+            return `- ${s.name}: ${s.description || "(no description)"}${tags}`;
+        });
+        return toolSuccess(`Skills matching "${query}" (${results.length}):\n${lines.join("\n")}`);
+    }
+    // load mode
+    if (!name) {
+        return toolError("SKILL_MISSING_NAME", "name is required (or use 'list' to list skills)");
+    }
+    const filePath = resolveSkillPath(name);
+    if (!filePath) {
+        const dirs = getSkillDirs();
+        const available = await listSkills(dirs);
+        const hint = available.length > 0
+            ? `\nAvailable skills: ${available.map((s) => s.name).join(", ")}`
+            : "\nNo skills found. Create .md files in skills/ directory.";
+        return toolError("SKILL_NOT_FOUND", `skill not found: ${name}${hint}`);
+    }
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const lines = content.split("\n");
+        const startIdx = lines.findIndex((l) => l.trim() === "---");
+        const endIdx = startIdx >= 0 ? lines.findIndex((l, i) => i > startIdx && l.trim() === "---") : -1;
+        const body = startIdx >= 0 && endIdx >= 0
+            ? lines.slice(endIdx + 1).join("\n").trim()
+            : content;
+        return toolSuccess(`📖 Skill: ${name}\n\n${body}`);
+    }
+    catch (err) {
+        return toolError("SKILL_READ_FAILED", `failed to read skill: ${err.message}`);
+    }
+}

package/dist/tools/subtask.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition, ToolResult } from "../types.js";
+export declare const subtaskTool: ToolDefinition;
+export declare function runSubtask(args: {
+    task: string;
+    context?: string;
+    max_iterations?: number;
+    timeout_ms?: number;
+}): Promise<ToolResult>;
+//# sourceMappingURL=subtask.d.ts.map

package/dist/tools/subtask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtask.d.ts","sourceRoot":"","sources":["../../src/tools/subtask.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAa9D,eAAO,MAAM,WAAW,EAAE,cAyBzB,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwFtB"}

package/dist/tools/subtask.js

@@ -0,0 +1,120 @@
+// ============================================================
+// 轻灵 - Subtask 工具定义
+// ============================================================
+import { SubtaskRunner } from "../agent/subtask.js";
+import { toolError, toolSuccess } from "./error-utils.js";
+import { bashTool } from "./bash.js";
+import { readTool } from "./read.js";
+import { writeTool } from "./write.js";
+import { todoTool } from "./todo.js";
+import { skillTool } from "./skill.js";
+import { searchTool } from "./search.js";
+import { plannerTool } from "./planner.js";
+import { urlFetchTool } from "./url-fetch.js";
+import { getRuntimeRootsFromEnv } from "../runtime-paths.js";
+export const subtaskTool = {
+    name: "subtask",
+    description: "Spawn an isolated sub-agent for an independent subtask. The sub-agent has its own context but shares memory with the parent.",
+    parameters: {
+        type: "object",
+        properties: {
+            task: {
+                type: "string",
+                description: "The subtask description",
+            },
+            context: {
+                type: "string",
+                description: "Additional context to pass to the sub-agent",
+            },
+            max_iterations: {
+                type: "number",
+                description: "Max iterations (default 10)",
+            },
+        },
+        required: ["task"],
+    },
+    readOnly: false,
+    destructive: false,
+    scenes: ["planning"],
+    effortHint: "high",
+};
+export async function runSubtask(args) {
+    const task = String(args.task ?? "").trim();
+    if (!task) {
+        return toolError("SUBTASK_MISSING_TASK", "task is required");
+    }
+    const apiKey = process.env.QLING_LLM_API_KEY ??
+        process.env.DEEPSEEK_API_KEY ??
+        process.env.OPENAI_API_KEY ??
+        "";
+    if (!apiKey) {
+        return toolError("SUBTASK_MISSING_API_KEY", "missing API key for subtask agent");
+    }
+    const maxIterationsRaw = Number(args.max_iterations ?? 10);
+    const maxIterations = Number.isFinite(maxIterationsRaw) && maxIterationsRaw > 0
+        ? Math.min(50, Math.max(1, Math.floor(maxIterationsRaw)))
+        : 10;
+    const timeoutRaw = Number(args.timeout_ms ?? 120_000);
+    const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? Math.min(600_000, timeoutRaw) : 120_000;
+    const roots = getRuntimeRootsFromEnv();
+    const runner = new SubtaskRunner({
+        apiKey,
+        provider: process.env.QLING_LLM_PROVIDER ?? "deepseek",
+        endpoint: process.env.QLING_LLM_ENDPOINT ??
+            process.env.OPENAI_BASE_URL ??
+            process.env.DEEPSEEK_BASE_URL ??
+            "https://api.deepseek.com",
+        model: process.env.QLING_LLM_MODEL ?? "deepseek-chat",
+        tools: [
+            bashTool,
+            readTool,
+            writeTool,
+            todoTool,
+            skillTool,
+            searchTool,
+            plannerTool,
+            urlFetchTool,
+        ],
+        runtime: {
+            workspaceDir: roots.workspaceDir,
+            fileCacheDir: roots.fileCacheDir,
+            fileStateDir: roots.fileStateDir,
+            maxSteps: maxIterations,
+            parseRetries: 2,
+            maxTokenBudget: 120_000,
+            toolRepeatLimit: 6,
+            timeoutMs,
+        },
+        logging: {
+            level: "info",
+            format: "text",
+            inspectPrompt: false,
+            inspectRequest: false,
+            inspectDumpDir: roots.fileStateDir,
+        },
+    });
+    try {
+        const result = await runner.run({
+            task,
+            parentContext: args.context,
+            maxIterations,
+            depth: 1,
+            timeoutMs,
+        });
+        if (!result.success) {
+            return toolError("SUBTASK_FAILED", result.output, { retriable: false, category: "runtime" });
+        }
+        return toolSuccess([
+            `subtask completed in ${result.durationMs}ms`,
+            `iterations=${result.iterations}`,
+            "",
+            result.output,
+        ].join("\n"));
+    }
+    catch (err) {
+        return toolError("SUBTASK_RUN_FAILED", err instanceof Error ? err.message : String(err), {
+            retriable: false,
+            category: "runtime",
+        });
+    }
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,8 @@
+import { ToolDefinition, ToolResult } from "../types.js";
+export declare const todoTool: ToolDefinition;
+export declare function runTodo(args: {
+    action: string;
+    content?: string;
+    id?: string;
+}): Promise<ToolResult>;
+//# sourceMappingURL=todo.d.ts.map

package/dist/tools/todo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo.d.ts","sourceRoot":"","sources":["../../src/tools/todo.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4BzD,eAAO,MAAM,QAAQ,EAAE,cA0EtB,CAAC;AAEF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,OAAO,CAAC,UAAU,CAAC,CA+EtB"}

package/dist/tools/todo.js

@@ -0,0 +1,170 @@
+import { writeFile, readFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve } from "path";
+const TODO_FILE = resolve(process.cwd(), ".qling-todos.json");
+async function readTodos() {
+    if (!existsSync(TODO_FILE))
+        return [];
+    try {
+        return JSON.parse(await readFile(TODO_FILE, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+async function saveTodos(todos) {
+    await mkdir(resolve(process.cwd(), ".qling-todos.json").replace(/[/\\][^/\\]+$/, ""), {
+        recursive: true,
+    });
+    await writeFile(TODO_FILE, JSON.stringify(todos, null, 2), "utf-8");
+}
+export const todoTool = {
+    name: "todo",
+    description: "Manage a persistent task list (stored in .qling-todos.json). Create, update, list, or remove tasks. Use for planning multi-step tasks and tracking session progress.",
+    longDescription: `管理持久化任务列表，存储在 .qling-todos.json 中。**不会直接执行任何操作**。
+
+**Action 类型**:
+- list: 列出所有任务（默认）
+- add: 添加新任务
+- done: 标记任务为已完成
+- cancel: 标记任务为已取消
+- remove: 删除单个任务
+- clear: 清空所有任务
+
+**任务状态**:
+- pending（待处理，默认）
+- in_progress（进行中）
+- completed（已完成）
+- cancelled（已取消）
+
+**使用建议**:
+- 复杂任务先用 todo add 创建计划
+- 每完成一步用 todo done 标记
+- 用 todo list 查看整体进度
+
+**注意**: 任务列表在会话之间持久化，清空操作需谨慎。`,
+    parameters: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["list", "add", "done", "cancel", "remove", "clear"],
+                description: "Action: list | add | done | cancel | remove | clear",
+            },
+            content: {
+                type: "string",
+                description: "Task content (required for action=add)",
+            },
+            id: {
+                type: "string",
+                description: "Task ID (required for action=done/cancel/remove)",
+            },
+        },
+        required: ["action"],
+    },
+    paramSchema: {
+        action: {
+            type: "string",
+            description: "操作类型：list=列表，add=添加，done=完成，cancel=取消，remove=删除，clear=清空",
+            enum: ["list", "add", "done", "cancel", "remove", "clear"],
+            required: true,
+        },
+        content: {
+            type: "string",
+            description: "任务内容描述（仅 action=add 时需要）",
+        },
+        id: {
+            type: "string",
+            description: "任务 ID（action=done/cancel/remove 时需要）",
+        },
+    },
+    examples: [
+        'todo action="list"',
+        'todo action="add" content="完成登录功能"',
+        'todo action="done" id="abc123"',
+        'todo action="remove" id="abc123"',
+    ],
+    seeAlso: ["bash"],
+    scenes: ["planning"],
+    priority: 7,
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: false,
+    effortHint: "minimal",
+};
+export async function runTodo(args) {
+    try {
+        const todos = await readTodos();
+        switch (args.action) {
+            case "list": {
+                if (todos.length === 0) {
+                    return { tool_call_id: "", output: "📋 暂无任务" };
+                }
+                const lines = todos.map((t) => {
+                    const icon = t.status === "completed"
+                        ? "✅"
+                        : t.status === "in_progress"
+                            ? "🔄"
+                            : t.status === "cancelled"
+                                ? "❌"
+                                : "⬜";
+                    return `${icon} [${t.id}] ${t.content}`;
+                });
+                return { tool_call_id: "", output: "📋 任务列表:\n" + lines.join("\n") };
+            }
+            case "add": {
+                const id = Date.now().toString(36);
+                const now = new Date().toISOString();
+                const item = {
+                    id,
+                    content: args.content ?? "",
+                    status: "pending",
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                todos.push(item);
+                await saveTodos(todos);
+                return { tool_call_id: "", output: `✅ 已添加任务 [${id}]: ${item.content}` };
+            }
+            case "done": {
+                const todo = todos.find((t) => t.id === args.id);
+                if (!todo)
+                    return { tool_call_id: "", output: `未找到任务 [${args.id}]`, is_error: true };
+                todo.status = "completed";
+                todo.updatedAt = new Date().toISOString();
+                await saveTodos(todos);
+                return { tool_call_id: "", output: `✅ 已完成 [${args.id}]: ${todo.content}` };
+            }
+            case "cancel": {
+                const todo = todos.find((t) => t.id === args.id);
+                if (!todo)
+                    return { tool_call_id: "", output: `未找到任务 [${args.id}]`, is_error: true };
+                todo.status = "cancelled";
+                todo.updatedAt = new Date().toISOString();
+                await saveTodos(todos);
+                return { tool_call_id: "", output: `❌ 已取消 [${args.id}]: ${todo.content}` };
+            }
+            case "remove": {
+                const idx = todos.findIndex((t) => t.id === args.id);
+                if (idx === -1)
+                    return { tool_call_id: "", output: `未找到任务 [${args.id}]`, is_error: true };
+                todos.splice(idx, 1);
+                await saveTodos(todos);
+                return { tool_call_id: "", output: `🗑️ 已删除 [${args.id}]` };
+            }
+            case "clear": {
+                await saveTodos([]);
+                return { tool_call_id: "", output: "🗑️ 任务列表已清空" };
+            }
+            default:
+                return {
+                    tool_call_id: "",
+                    output: `未知 action: ${args.action}`,
+                    is_error: true,
+                };
+        }
+    }
+    catch (err) {
+        return { tool_call_id: "", output: `Error: ${err.message}`, is_error: true };
+    }
+}

package/dist/tools/url-fetch.d.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition, ToolResult } from "../types.js";
+export declare const urlFetchTool: ToolDefinition;
+export declare function runUrlFetch(args: {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeout_seconds?: number;
+    follow_redirects?: boolean;
+}): Promise<ToolResult>;
+//# sourceMappingURL=url-fetch.d.ts.map

package/dist/tools/url-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/url-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9D,eAAO,MAAM,YAAY,EAAE,cA0E1B,CAAC;AAEF,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,UAAU,CAAC,CAoItB"}