feat(builtin): modularize builtin SDK and add environment/task management capability with updated examples and docs

.gitignore

@@ -52,6 +52,7 @@ bin/
 *.log
 
 # VitePress
+docs/.vitepress/dist/
 docs/.vitepress/cache/
 docs/node_modules/
 docs/public/swagger.json
@@ -63,3 +64,6 @@ openapi_docs/
 # Builtin SDK (Force Include)
 !builtin/
 !builtin/**
+builtin/**/__pycache__/
+builtin/**/*.pyc
+

builtin/nodejs/env.js

@@ -0,0 +1,182 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+/**
+ * 内部 API 请求辅助函数
+ */
+function request(urlStr, method = 'GET', data = null) {
+    const token = process.env.BHPKG_OPENAPI_TOKEN || process.env.OPENAPI_TOKEN || process.env.BHPKG_NOTIFY_TOKEN;
+    if (!token) {
+        throw new Error("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量，无法使用环境管理操作");
+    }
+
+    const parsedUrl = new URL(urlStr);
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+    
+    let payload = '';
+    const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`
+    };
+
+    if (data !== null) {
+        payload = JSON.stringify(data);
+        headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+
+    const options = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port,
+        path: parsedUrl.pathname + (parsedUrl.search || ''),
+        method: method,
+        headers: headers
+    };
+
+    return new Promise((resolve, reject) => {
+        const req = protocol.request(options, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => body += chunk);
+            res.on('end', () => {
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    try {
+                        resolve(body ? JSON.parse(body) : {});
+                    } catch (e) {
+                        resolve(body);
+                    }
+                } else {
+                    let errMsg = body;
+                    try {
+                        const parsed = JSON.parse(body);
+                        errMsg = parsed.msg || parsed.message || body;
+                    } catch(e) {}
+                    reject(new Error(`请求失败 [${res.statusCode}]: ${errMsg}`));
+                }
+            });
+        });
+        
+        req.on('error', (e) => reject(e));
+        if (payload) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}
+
+function getEnvsUrl() {
+    const url = process.env.BHPKG_OPENAPI_URL || process.env.OPENAPI_URL;
+    if (url) return url;
+
+    const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send';
+    const targets = ['/api/v1/notify/send/', '/api/v1/notify/send', '/api/v1/notify/', '/api/v1/notify'];
+    for (const target of targets) {
+        if (notifyUrl.includes(target)) {
+            return notifyUrl.replace(target, '/open2api/v1/env');
+        }
+    }
+    return 'http://localhost:8052/open2api/v1/env';
+}
+
+/**
+ * 获取所有的环境变量列表
+ */
+async function getEnvs() {
+    const url = `${getEnvsUrl()}/all`;
+    const res = await request(url, 'GET');
+    return res.data || [];
+}
+
+/**
+ * 根据变量名获取环境变量，不存在则返回 null
+ */
+async function getEnv(name) {
+    const envs = await getEnvs();
+    for (const env of envs) {
+        if (env.name === name) {
+            return env;
+        }
+    }
+    return null;
+}
+
+/**
+ * 批量添加环境变量
+ */
+async function addEnvs(envsList) {
+    const url = getEnvsUrl();
+    const addedEnvs = [];
+    for (const env of envsList) {
+        if (!env.name || !env.value) {
+            throw new Error("环境变量必须包含 'name' 和 'value'");
+        }
+        const res = await request(url, 'POST', env);
+        if (res.data) {
+            addedEnvs.push(res.data);
+        }
+    }
+    return addedEnvs;
+}
+
+/**
+ * 添加单个环境变量
+ */
+async function addEnv(name, value, remark = "", type = "normal", hidden = true, enabled = true) {
+    const url = getEnvsUrl();
+    const payload = {
+        name,
+        value,
+        remark,
+        type,
+        hidden,
+        enabled
+    };
+    const res = await request(url, 'POST', payload);
+    return res.data;
+}
+
+/**
+ * 根据 ID 更新环境变量
+ */
+async function updateEnv(id, name, value, remark = null, type = null, hidden = null, enabled = null) {
+    const url = `${getEnvsUrl()}/${id}`;
+    const payload = {};
+    if (name !== null) payload.name = name;
+    if (value !== null) payload.value = value;
+    if (remark !== null) payload.remark = remark;
+    if (type !== null) payload.type = type;
+    if (hidden !== null) payload.hidden = hidden;
+    if (enabled !== null) payload.enabled = enabled;
+
+    const res = await request(url, 'PUT', payload);
+    return res.data;
+}
+
+/**
+ * 批量删除环境变量
+ */
+async function deleteEnvs(ids) {
+    for (const id of ids) {
+        await deleteEnv(id);
+    }
+    return true;
+}
+
+/**
+ * 根据 ID 删除指定环境变量
+ */
+async function deleteEnv(id) {
+    const url = `${getEnvsUrl()}/${id}`;
+    await request(url, 'DELETE');
+    return true;
+}
+
+module.exports = {
+    getEnvs,
+    getEnv,
+    addEnvs,
+    addEnv,
+    updateEnv,
+    deleteEnvs,
+    deleteEnv
+};

builtin/nodejs/index.js

@@ -1,57 +1,37 @@
-const http = require('http');
+const { notify } = require('./notify');
-const https = require('https');
+const {
-const { URL } = require('url');
+    getEnvs,
+    getEnv,
+    addEnvs,
+    addEnv,
+    updateEnv,
+    deleteEnvs,
+    deleteEnv
+} = require('./env');
+const {
+    getTasks,
+    getTask,
+    updateTask,
+    deleteTask,
+    executeTask,
+    stopTask,
+    getLastResults
+} = require('./task');
 
-/**
+module.exports = {
- * 环境变量强校验：导入期进行
+    notify,
- */
+    getEnvs,
-const TOKEN = process.env.BHPKG_NOTIFY_TOKEN;
+    getEnv,
-const CHANNEL = process.env.BHPKG_NOTIFY_CHANNEL;
+    addEnvs,
-
+    addEnv,
-if (!TOKEN || !CHANNEL) {
+    updateEnv,
-    const missing = [];
+    deleteEnvs,
-    if (!TOKEN) missing.push("BHPKG_NOTIFY_TOKEN");
+    deleteEnv,
-    if (!CHANNEL) missing.push("BHPKG_NOTIFY_CHANNEL");
+    getTasks,
-    
+    getTask,
-    throw new Error(`缺少必要的环境变量以使用 baihu 模块: ${missing.join(", ")}。请在白虎面板的任务设置中配置这些 Key。`);
+    updateTask,
-}
+    deleteTask,
-
+    executeTask,
-/**
+    stopTask,
- * 发送通知的辅助函数 (仅使用 Node.js 标准库)
+    getLastResults
- */
+};
-function notify(title, text, channelId) {
-    const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send';
-    const cid = channelId || CHANNEL;
-
-    if (!notifyUrl || !TOKEN || !cid) return;
-
-
-        const parsedUrl = new URL(notifyUrl);
-        const protocol = parsedUrl.protocol === 'https:' ? https : http;
-        
-        const data = JSON.stringify({
-            channel_id: cid,
-            title: title || '系统通知',
-            text: text
-        });
-
-        const options = {
-            hostname: parsedUrl.hostname,
-            port: parsedUrl.port,
-            path: parsedUrl.pathname + (parsedUrl.search || ''),
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'notify-token': TOKEN,
-                'Content-Length': Buffer.byteLength(data)
-            }
-        };
-
-        const req = protocol.request(options);
-        req.on('error', (e) => {});
-        req.write(data);
-        req.end();
-    
-}
-
-module.exports = { notify };

builtin/nodejs/notify.js

@@ -0,0 +1,51 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+/**
+ * 发送通知的辅助函数 (仅使用 Node.js 标准库)
+ */
+function notify(title, text, channelId) {
+    const token = process.env.BHPKG_NOTIFY_TOKEN;
+    const channel = process.env.BHPKG_NOTIFY_CHANNEL;
+
+    if (!token || !channel) {
+        const missing = [];
+        if (!token) missing.push("BHPKG_NOTIFY_TOKEN");
+        if (!channel) missing.push("BHPKG_NOTIFY_CHANNEL");
+        throw new Error(`缺少必要的环境变量以使用 notify 函数: ${missing.join(", ")}。请在白虎面板的任务设置中配置这些 Key。`);
+    }
+
+    const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send';
+    const cid = channelId || channel;
+
+    if (!notifyUrl || !token || !cid) return;
+
+    const parsedUrl = new URL(notifyUrl);
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+    
+    const data = JSON.stringify({
+        channel_id: cid,
+        title: title || '系统通知',
+        text: text
+    });
+
+    const options = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port,
+        path: parsedUrl.pathname + (parsedUrl.search || ''),
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'notify-token': token,
+            'Content-Length': Buffer.byteLength(data)
+        }
+    };
+
+    const req = protocol.request(options);
+    req.on('error', (e) => {});
+    req.write(data);
+    req.end();
+}
+
+module.exports = { notify };

builtin/nodejs/task.js

@@ -0,0 +1,170 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+/**
+ * 内部 API 请求辅助函数
+ */
+function request(urlStr, method = 'GET', data = null) {
+    const token = process.env.BHPKG_OPENAPI_TOKEN || process.env.OPENAPI_TOKEN || process.env.BHPKG_NOTIFY_TOKEN;
+    if (!token) {
+        throw new Error("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量，无法使用任务管理操作");
+    }
+
+    const parsedUrl = new URL(urlStr);
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+    
+    let payload = '';
+    const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`
+    };
+
+    if (data !== null) {
+        payload = JSON.stringify(data);
+        headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+
+    const options = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port,
+        path: parsedUrl.pathname + (parsedUrl.search || ''),
+        method: method,
+        headers: headers
+    };
+
+    return new Promise((resolve, reject) => {
+        const req = protocol.request(options, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => body += chunk);
+            res.on('end', () => {
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    try {
+                        resolve(body ? JSON.parse(body) : {});
+                    } catch (e) {
+                        resolve(body);
+                    }
+                } else {
+                    let errMsg = body;
+                    try {
+                        const parsed = JSON.parse(body);
+                        errMsg = parsed.msg || parsed.message || body;
+                    } catch(e) {}
+                    reject(new Error(`请求失败 [${res.statusCode}]: ${errMsg}`));
+                }
+            });
+        });
+        
+        req.on('error', (e) => reject(e));
+        if (payload) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}
+
+function getBaseUrl() {
+    const url = process.env.BHPKG_OPENAPI_URL || process.env.OPENAPI_URL;
+    if (url) {
+        if (url.endsWith('/env')) return url.slice(0, -4);
+        if (url.endsWith('/env/')) return url.slice(0, -5);
+        return url;
+    }
+
+    const notifyUrl = process.env.BHPKG_NOTIFY_URL || 'http://localhost:8052/api/v1/notify/send';
+    const targets = ['/api/v1/notify/send/', '/api/v1/notify/send', '/api/v1/notify/', '/api/v1/notify'];
+    for (const target of targets) {
+        if (notifyUrl.includes(target)) {
+            return notifyUrl.replace(target, '/open2api/v1');
+        }
+    }
+    return 'http://localhost:8052/open2api/v1';
+}
+
+/**
+ * 获取全部任务列表
+ */
+async function getTasks() {
+    const url = `${getBaseUrl()}/tasks`;
+    const res = await request(url, 'GET');
+    return res.data || [];
+}
+
+/**
+ * 根据 ID 获取单个任务信息
+ */
+async function getTask(id) {
+    const url = `${getBaseUrl()}/tasks/${id}`;
+    const res = await request(url, 'GET');
+    return res.data;
+}
+
+/**
+ * 根据 ID 更新指定任务
+ */
+async function updateTask(id, name, command, remark, pin_type, trigger_type, schedule, timeout, work_dir, retry_count, retry_interval, random_range, enabled) {
+    const url = `${getBaseUrl()}/tasks/${id}`;
+    const payload = {};
+    if (name !== undefined) payload.name = name;
+    if (command !== undefined) payload.command = command;
+    if (remark !== undefined) payload.remark = remark;
+    if (pin_type !== undefined) payload.pin_type = pin_type;
+    if (trigger_type !== undefined) payload.trigger_type = trigger_type;
+    if (schedule !== undefined) payload.schedule = schedule;
+    if (timeout !== undefined) payload.timeout = timeout;
+    if (work_dir !== undefined) payload.work_dir = work_dir;
+    if (retry_count !== undefined) payload.retry_count = retry_count;
+    if (retry_interval !== undefined) payload.retry_interval = retry_interval;
+    if (random_range !== undefined) payload.random_range = random_range;
+    if (enabled !== undefined) payload.enabled = enabled;
+
+    const res = await request(url, 'PUT', payload);
+    return res.data;
+}
+
+/**
+ * 根据 ID 删除任务
+ */
+async function deleteTask(id) {
+    const url = `${getBaseUrl()}/tasks/${id}`;
+    await request(url, 'DELETE');
+    return true;
+}
+
+/**
+ * 触发运行指定任务
+ */
+async function executeTask(id) {
+    const url = `${getBaseUrl()}/execute/task/${id}`;
+    const res = await request(url, 'POST');
+    return res.data;
+}
+
+/**
+ * 根据日志 ID 停止正在运行的任务
+ */
+async function stopTask(logId) {
+    const url = `${getBaseUrl()}/tasks/stop/${logId}`;
+    const res = await request(url, 'POST');
+    return res.data;
+}
+
+/**
+ * 获取最近的任务执行结果列表
+ */
+async function getLastResults() {
+    const url = `${getBaseUrl()}/execute/results`;
+    const res = await request(url, 'GET');
+    return res.data || [];
+}
+
+module.exports = {
+    getTasks,
+    getTask,
+    updateTask,
+    deleteTask,
+    executeTask,
+    stopTask,
+    getLastResults
+};

builtin/python/baihu/__init__.py

@@ -1,5 +1,23 @@
 import os
 from .notify import notify as _notify
+from .env import (
+    get_envs,
+    get_env,
+    add_envs,
+    add_env,
+    update_env,
+    delete_envs,
+    delete_env
+)
+from .task import (
+    get_tasks,
+    get_task,
+    update_task,
+    delete_task,
+    execute_task,
+    stop_task,
+    get_last_results
+)
 
 def notify(title, text):
     """
@@ -19,4 +37,20 @@ def notify(title, text):
     
     return _notify(title, text)
 
-__all__ = ['notify']
+__all__ = [
+    'notify',
+    'get_envs',
+    'get_env',
+    'add_envs',
+    'add_env',
+    'update_env',
+    'delete_envs',
+    'delete_env',
+    'get_tasks',
+    'get_task',
+    'update_task',
+    'delete_task',
+    'execute_task',
+    'stop_task',
+    'get_last_results'
+]

builtin/python/baihu/env.py

@@ -0,0 +1,129 @@
+import os
+import json
+import urllib.request
+import urllib.error
+
+def _get_headers():
+    token = os.environ.get("BHPKG_OPENAPI_TOKEN") or os.environ.get("OPENAPI_TOKEN") or os.environ.get("BHPKG_NOTIFY_TOKEN")
+    if not token:
+        raise RuntimeError("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量，无法使用环境管理操作")
+    return {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {token}"
+    }
+
+def _get_envs_url():
+    url = os.environ.get("BHPKG_OPENAPI_URL") or os.environ.get("OPENAPI_URL")
+    if url:
+        return url
+    
+    notify_url = os.environ.get("BHPKG_NOTIFY_URL", "http://localhost:8052/api/v1/notify/send")
+    for target in ["/api/v1/notify/send/", "/api/v1/notify/send", "/api/v1/notify/", "/api/v1/notify"]:
+        if target in notify_url:
+            return notify_url.replace(target, "/open2api/v1/env")
+            
+    return "http://localhost:8052/open2api/v1/env"
+
+def _request(url, method="GET", data=None):
+    headers = _get_headers()
+    payload = None
+    if data is not None:
+        payload = json.dumps(data).encode("utf-8")
+    
+    req = urllib.request.Request(url, data=payload, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            body = resp.read().decode("utf-8")
+            if not body:
+                return {}
+            return json.loads(body)
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8")
+        try:
+            err_json = json.loads(err_body)
+            msg = err_json.get("msg") or err_json.get("message") or err_body
+        except Exception:
+            msg = err_body
+        raise RuntimeError(f"请求失败 [{e.code}]: {msg}")
+    except Exception as e:
+        raise RuntimeError(f"请求发生异常: {e}")
+
+def get_envs():
+    """
+    获取所有的环境变量列表。
+    """
+    url = f"{_get_envs_url()}/all"
+    res = _request(url, "GET")
+    return res.get("data", [])
+
+def get_env(name):
+    """
+    根据变量名获取环境变量。如果不存在则返回 None。
+    """
+    envs = get_envs()
+    for env in envs:
+        if env.get("name") == name:
+            return env
+    return None
+
+def add_envs(envs_list):
+    """
+    批量添加环境变量。
+    envs_list: 包含环境变量字典的列表，如 [{"name": "KEY", "value": "VAL", "remark": "备注"}]
+    """
+    url = _get_envs_url()
+    added_envs = []
+    for env in envs_list:
+        if "name" not in env or "value" not in env:
+            raise ValueError("环境变量必须包含 'name' 和 'value'")
+        res = _request(url, "POST", env)
+        if "data" in res:
+            added_envs.append(res["data"])
+    return added_envs
+
+def add_env(name, value, remark="", type="normal", hidden=True, enabled=True):
+    """
+    添加单个环境变量。
+    """
+    url = _get_envs_url()
+    payload = {
+        "name": name,
+        "value": value,
+        "remark": remark,
+        "type": type,
+        "hidden": hidden,
+        "enabled": enabled
+    }
+    res = _request(url, "POST", payload)
+    return res.get("data")
+
+def update_env(id, name, value, remark=None, type=None, hidden=None, enabled=None):
+    """
+    根据 ID 更新环境变量。
+    """
+    url = f"{_get_envs_url()}/{id}"
+    payload = {}
+    if name is not None: payload["name"] = name
+    if value is not None: payload["value"] = value
+    if remark is not None: payload["remark"] = remark
+    if type is not None: payload["type"] = type
+    if hidden is not None: payload["hidden"] = hidden
+    if enabled is not None: payload["enabled"] = enabled
+
+    res = _request(url, "PUT", payload)
+    return res.get("data")
+
+def delete_envs(ids):
+    """
+    批量删除环境变量。
+    """
+    for fid in ids:
+        delete_env(fid)
+
+def delete_env(id):
+    """
+    根据 ID 删除指定的环境变量。
+    """
+    url = f"{_get_envs_url()}/{id}"
+    _request(url, "DELETE")
+    return True

builtin/python/baihu/task.py

@@ -0,0 +1,124 @@
+import os
+import json
+import urllib.request
+import urllib.error
+
+def _get_headers():
+    token = os.environ.get("BHPKG_OPENAPI_TOKEN") or os.environ.get("OPENAPI_TOKEN") or os.environ.get("BHPKG_NOTIFY_TOKEN")
+    if not token:
+        raise RuntimeError("缺少 BHPKG_OPENAPI_TOKEN 或 BHPKG_NOTIFY_TOKEN 环境变量，无法使用任务管理操作")
+    return {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {token}"
+    }
+
+def _get_base_url():
+    url = os.environ.get("BHPKG_OPENAPI_URL") or os.environ.get("OPENAPI_URL")
+    if url:
+        # If openapi_url ends with /env, replace it with nothing or use base
+        if url.endswith("/env"):
+            return url[:-4]
+        elif url.endswith("/env/"):
+            return url[:-5]
+        return url
+    
+    notify_url = os.environ.get("BHPKG_NOTIFY_URL", "http://localhost:8052/api/v1/notify/send")
+    for target in ["/api/v1/notify/send/", "/api/v1/notify/send", "/api/v1/notify/", "/api/v1/notify"]:
+        if target in notify_url:
+            return notify_url.replace(target, "/open2api/v1")
+            
+    return "http://localhost:8052/open2api/v1"
+
+def _request(url, method="GET", data=None):
+    headers = _get_headers()
+    payload = None
+    if data is not None:
+        payload = json.dumps(data).encode("utf-8")
+    
+    req = urllib.request.Request(url, data=payload, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            body = resp.read().decode("utf-8")
+            if not body:
+                return {}
+            return json.loads(body)
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8")
+        try:
+            err_json = json.loads(err_body)
+            msg = err_json.get("msg") or err_json.get("message") or err_body
+        except Exception:
+            msg = err_body
+        raise RuntimeError(f"请求失败 [{e.code}]: {msg}")
+    except Exception as e:
+        raise RuntimeError(f"请求发生异常: {e}")
+
+def get_tasks():
+    """
+    获取全部任务列表。
+    """
+    url = f"{_get_base_url()}/tasks"
+    res = _request(url, "GET")
+    return res.get("data", [])
+
+def get_task(id):
+    """
+    根据 ID 获取单个任务的详细信息。
+    """
+    url = f"{_get_base_url()}/tasks/{id}"
+    res = _request(url, "GET")
+    return res.get("data")
+
+def update_task(id, name=None, command=None, remark=None, pin_type=None, trigger_type=None, schedule=None, timeout=None, work_dir=None, retry_count=None, retry_interval=None, random_range=None, enabled=None):
+    """
+    根据 ID 更新任务。
+    """
+    url = f"{_get_base_url()}/tasks/{id}"
+    payload = {}
+    if name is not None: payload["name"] = name
+    if command is not None: payload["command"] = command
+    if remark is not None: payload["remark"] = remark
+    if pin_type is not None: payload["pin_type"] = pin_type
+    if trigger_type is not None: payload["trigger_type"] = trigger_type
+    if schedule is not None: payload["schedule"] = schedule
+    if timeout is not None: payload["timeout"] = timeout
+    if work_dir is not None: payload["work_dir"] = work_dir
+    if retry_count is not None: payload["retry_count"] = retry_count
+    if retry_interval is not None: payload["retry_interval"] = retry_interval
+    if random_range is not None: payload["random_range"] = random_range
+    if enabled is not None: payload["enabled"] = enabled
+
+    res = _request(url, "PUT", payload)
+    return res.get("data")
+
+def delete_task(id):
+    """
+    根据 ID 删除指定任务。
+    """
+    url = f"{_get_base_url()}/tasks/{id}"
+    _request(url, "DELETE")
+    return True
+
+def execute_task(id):
+    """
+    触发执行特定任务。
+    """
+    url = f"{_get_base_url()}/execute/task/{id}"
+    res = _request(url, "POST")
+    return res.get("data")
+
+def stop_task(log_id):
+    """
+    根据日志 ID 停止正在运行的任务。
+    """
+    url = f"{_get_base_url()}/tasks/stop/{log_id}"
+    res = _request(url, "POST")
+    return res.get("data")
+
+def get_last_results():
+    """
+    获取最近的执行结果列表。
+    """
+    url = f"{_get_base_url()}/execute/results"
+    res = _request(url, "GET")
+    return res.get("data", [])

docs/.vitepress/config.mts

@@ -43,7 +43,7 @@ export default defineConfig({
                         link: '/guide/examples/',
                         items: [
                             { text: '浏览器示例', link: '/guide/examples/browser' },
-                            { text: '消息通知示例', link: '/guide/examples/notify' }
+                            { text: '内置库示例', link: '/guide/examples/builtin' }
                         ]
                     }
                 ]

docs/guide/examples/builtin.md

@@ -0,0 +1,296 @@
+# 内置库示例
+
+白虎面板提供了一个名为 `baihu` 的内建包（Built-in SDK），支持 Python 和 Node.js。通过该内置库，您可以在脚本中实现**消息推送**、**环境变量管理**以及**任务执行控制**等高级功能。
+
+---
+
+## 准备工作
+
+在运行内置库脚本之前，请确保完成了以下步骤：
+
+### 1. 安装内置包
+在白虎面板的「终端」页面中，或者通过创建临时任务执行以下命令，为面板管理的所有语言环境安装 `baihu` 包：
+
+```bash
+baihu builtininstall
+```
+
+### 2. 配置环境变量
+根据您需要调用的功能，在定时任务的“环境变量”或“机密”中配置以下对应 Key：
+
+#### 消息推送所需环境变量
+- **`BHPKG_NOTIFY_TOKEN`**：进入「消息推送」->「脚本调用说明」页面即可找到。
+- **`BHPKG_NOTIFY_CHANNEL`**：进入「消息推送」->「渠道列表」页面，查看对应渠道的 **ID**。
+- **`BHPKG_NOTIFY_URL`** (可选)：默认为 `http://localhost:8052/api/v1/notify/send`。如果修改了主服务端口，需要同步修改。
+
+#### 环境变量管理与定时任务控制所需环境变量
+- **`BHPKG_OPENAPI_TOKEN`** (或 `OPENAPI_TOKEN`)：用于 OpenAPI 接口鉴权，进入「系统设置」->「OpenAPI」页面，生成并复制 Token。
+- **`BHPKG_OPENAPI_URL`** (或 `OPENAPI_URL`，可选)：默认为本地面板 API 地址。若在非标准环境下运行，可手动指定（例如 `http://localhost:8052`）。
+
+---
+
+## 消息通知示例
+
+只需要一行代码即可触发零配置推送。
+
+::: code-group
+
+```python [Python]
+import baihu
+
+def main():
+    print("正在尝试发送 Python 内建通知...")
+    try:
+        # 调用内置 notify 函数
+        # 内部会自动使用环境变量进行鉴权和投递
+        response = baihu.notify(
+            title="Python 任务提醒",
+            text="这是一条来自 Python 示例脚本的通知消息。调用非常简单！"
+        )
+        print("发送请求已处理。")
+        if response:
+            print(f"服务器响应: {response}")
+            
+    except Exception as e:
+        print(f"发送过程发生异常: {e}")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const baihu = require('baihu');
+
+console.log("正在尝试发送 Node.js 内建通知...");
+
+try {
+    // 简单的一行代码即可完成推送，内置包采用异步非阻塞发送
+    baihu.notify(
+        "Node.js 任务提醒", 
+        "这是一条来自 Node.js 示例脚本的通知消息。无需配置 API 地址或 Token。"
+    );
+    console.log("发送请求已提交。");
+    
+} catch (e) {
+    console.error(`通知失败: ${e.message}`);
+}
+```
+
+:::
+
+---
+
+## 环境变量管理
+
+内置库支持对面板的环境变量进行增删改查。
+
+### 支持方法
+
+* **Python**: 
+  - `get_envs()`: 获取所有环境变量列表。
+  - `get_env(name)`: 根据变量名称获取详情。
+  - `add_env(name, value, remark)`: 添加新的环境变量。
+  - `update_env(id, name, value, remark)`: 更新指定 ID 的环境变量值。
+  - `delete_env(id)`: 根据 ID 删除环境变量。
+* **Node.js**:
+  - `getEnvs()`: 获取所有环境变量列表。
+  - `getEnv(name)`: 根据变量名称获取详情。
+  - `addEnv(name, value, remark)`: 添加新的环境变量。
+  - `updateEnv(id, name, value, remark)`: 更新指定 ID 的环境变量值。
+  - `deleteEnv(id)`: 根据 ID 删除环境变量。
+
+### 代码示例
+
+::: code-group
+
+```python [Python]
+import baihu
+
+def main():
+    print("====== 开始运行 Python 环境变量管理示例 ======")
+    try:
+        # 1. 获取全部环境变量
+        envs = baihu.get_envs()
+        print(f"当前共有 {len(envs)} 个环境变量")
+        
+        # 2. 新增一个临时环境变量
+        new_env_name = "BHPKG_TEST_KEY"
+        new_env_val = "HelloBaihu"
+        print(f"正在创建环境变量: {new_env_name}...")
+        created_env = baihu.add_env(
+            name=new_env_name,
+            value=new_env_val,
+            remark="Python SDK 测试自动创建"
+        )
+        print(f"创建成功: ID={created_env.get('id')}, Name={created_env.get('name')}")
+
+        # 3. 查询刚才创建的环境变量详情
+        checked_env = baihu.get_env(new_env_name)
+        if checked_env:
+            print(f"成功查询到变量: {checked_env.get('name')} = {checked_env.get('value')}")
+
+            # 4. 修改该环境变量的值
+            updated_val = "HelloBaihu_Updated"
+            print(f"正在修改环境变量的值为: {updated_val}...")
+            updated_env = baihu.update_env(
+                id=checked_env.get("id"),
+                name=new_env_name,
+                value=updated_val,
+                remark="Python SDK 测试自动更新"
+            )
+            print(f"更新成功: Value={updated_env.get('value')}")
+
+            # 5. 删除该临时环境变量
+            print(f"正在删除临时环境变量: ID={checked_env.get('id')}...")
+            baihu.delete_env(checked_env.get("id"))
+            print("删除成功！")
+            
+    except Exception as e:
+        print(f"环境变量操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const baihu = require('baihu');
+
+async function main() {
+    console.log("====== 开始运行 Node.js 环境变量管理示例 ======");
+    try {
+        // 1. 获取全部环境变量
+        const envs = await baihu.getEnvs();
+        console.log(`当前共有 ${envs.length} 个环境变量`);
+
+        // 2. 新增一个临时环境变量
+        const newEnvName = "BHPKG_TEST_KEY_JS";
+        const newEnvVal = "HelloBaihuJS";
+        console.log(`正在创建环境变量: ${newEnvName}...`);
+        const createdEnv = await baihu.addEnv(
+            newEnvName,
+            newEnvVal,
+            "Node.js SDK 测试自动创建"
+        );
+        console.log(`创建成功: ID={createdEnv.id}, Name={createdEnv.name}`);
+
+        // 3. 查询该环境变量
+        const checkedEnv = await baihu.getEnv(newEnvName);
+        if (checkedEnv) {
+            console.log(`成功查询到变量: ${checkedEnv.name} = ${checkedEnv.value}`);
+
+            // 4. 修改该环境变量的值
+            const updatedVal = "HelloBaihuJS_Updated";
+            console.log(`正在修改环境变量的值为: ${updatedVal}...`);
+            const updatedEnv = await baihu.updateEnv(
+                checkedEnv.id,
+                newEnvName,
+                updatedVal,
+                "Node.js SDK 测试自动更新"
+            );
+            console.log(`更新成功: Value=${updatedEnv.value}`);
+
+            // 5. 删除该临时环境变量
+            console.log(`正在删除临时环境变量: ID={checkedEnv.id}...`);
+            await baihu.deleteEnv(checkedEnv.id);
+            console.log("删除成功！");
+        }
+
+    } catch (e) {
+        console.error(`环境变量操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();
+```
+
+:::
+
+---
+
+## 定时任务管理与控制
+
+内置库支持查询面板的任务列表、最近的执行结果以及手动触发特定任务的运行。
+
+### 支持方法
+
+* **Python**: 
+  - `get_tasks()`: 获取所有定时任务列表。
+  - `execute_task(id)`: 立即触发指定 ID 任务的运行。
+  - `get_last_results()`: 获取最近任务的执行记录。
+* **Node.js**:
+  - `getTasks()`: 获取所有定时任务列表。
+  - `executeTask(id)`: 立即触发指定 ID 任务的运行。
+  - `getLastResults()`: 获取最近任务的执行记录。
+
+### 代码示例
+
+::: code-group
+
+```python [Python]
+import baihu
+
+def main():
+    print("====== 开始运行 Python 任务管理与执行控制示例 ======")
+    try:
+        # 1. 获取所有任务列表
+        tasks = baihu.get_tasks()
+        print(f"成功获取到 {len(tasks)} 个定时任务:")
+        for task in tasks[:5]:  # 仅打印前5个
+            print(f"  - [{task.get('id')}] {task.get('name')} (表达式: {task.get('schedule')}, 备注: {task.get('remark')})")
+
+        # 2. 尝试触发第一个任务的运行
+        if tasks:
+            target_task = tasks[0]
+            print(f"\n尝试手动触发任务运行: [{target_task.get('id')}] {target_task.get('name')}...")
+            baihu.execute_task(target_task.get("id"))
+            print("执行指令发送成功。")
+
+        # 3. 获取最近的执行结果列表
+        results = baihu.get_last_results()
+        print(f"\n最近共有 {len(results)} 条任务执行记录。")
+            
+    except Exception as e:
+        print(f"任务操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const baihu = require('baihu');
+
+async function main() {
+    console.log("====== 开始运行 Node.js 任务管理与执行控制示例 ======");
+    try {
+        // 1. 获取所有任务列表
+        const tasks = await baihu.getTasks();
+        console.log(`成功获取到 ${tasks.length} 个定时任务:`);
+        tasks.slice(0, 5).forEach(task => { // 仅展示前5项
+            console.log(`  - [${task.id}] ${task.name} (表达式: ${task.schedule || ''}, 备注: ${task.remark || ''})`);
+        });
+
+        // 2. 尝试触发第一个任务的运行
+        if (tasks.length > 0) {
+            const targetTask = tasks[0];
+            console.log(`\n尝试手动触发任务运行: [${targetTask.id}] ${targetTask.name}...`);
+            await baihu.executeTask(targetTask.id);
+            console.log("执行指令发送成功。");
+        }
+
+        // 3. 获取最近的执行结果列表
+        const results = await baihu.getLastResults();
+        console.log(`\n最近共有 ${results.length} 条任务执行记录。`);
+
+    } catch (e) {
+        console.error(`任务操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();
+```
+
+:::

docs/guide/examples/index.md

@@ -23,5 +23,4 @@ example/
 目前文档已经整理出的示例类型：
 
 - [浏览器示例](./browser.md)
-
+- [内置库示例](./builtin.md)
-后面如果继续增加 HTTP、数据库、通知推送等示例，也会按这个目录结构继续扩展。

docs/guide/examples/notify.md

@@ -1,87 +0,0 @@
-# 消息通知示例
-
-白虎面板提供了一个名为 `baihu` 的内建包，让您可以在脚本（Python 或 Node.js）中通过一行代码实现零配置推送。
-
----
-
-## 准备工作
-
-在运行消息通知脚本之前，请确保已经完成了必要的初始化工作。
-
-### 1. 安装内建包
-在白虎面板的在线终端或通过任务执行以下命令，为您当前的所有语言环境安装 `baihu` 包：
-
-```bash
-baihu builtininstall
-```
-
-### 2. 配置环境变量
-前往 **「定时任务」** -> **「编辑任务」** -> **「环境变量」**，添加以下两个键值对：
-
-- `BHPKG_NOTIFY_TOKEN`: 进入「消息推送」->「脚本调用说明」标签即可找到。
-- `BHPKG_NOTIFY_CHANNEL`: 进入「消息推送」->「渠道列表」标签即可查看对应的 **ID**。
-
-> [!TIP]
-> 如果您更改了容器内部的服务端口（默认 8052），还需要额外添加 `BHPKG_NOTIFY_URL` 变量。详情请参考 [消息中心说明](../notify.md)。
-
----
-
-## 代码示例
-
-### Python (同步)
-
-```python
-import baihu
-
-# 内建通知测试示例 (Python)
-def main():
-    print("正在尝试发送 Python 内建通知...")
-    try:
-        # 调用内建 notify 函数
-        # 内部会自动使用环境变量进行鉴权和投递
-        response = baihu.notify(
-            title="Python 任务提醒",
-            text="这是一条来自 Python 示例脚本的通知消息。调用非常简单！"
-        )
-        print(f"服务器响应: {response}")
-            
-    except Exception as e:
-        print(f"发送过程发生异常: {e}")
-
-if __name__ == "__main__":
-    main()
-```
-
-### Node.js (异步)
-
-```javascript
-const baihu = require('baihu');
-
-/**
- * 内建通知测试示例 (Node.js)
- */
-console.log("正在尝试发送 Node.js 内建通知...");
-
-try {
-    // 简单的一行代码即可完成推送
-    baihu.notify(
-        "Node.js 任务提醒", 
-        "这是一条来自 Node.js 示例脚本的通知消息。无需配置 API 地址或 Token。"
-    );
-    
-    console.log("发送请求已提交。");
-    console.log("提示：内建包采用异步非阻塞发送，不会干扰主逻辑执行。");
-    
-} catch (e) {
-    console.error(`通知失败: ${e.message}`);
-}
-```
-
----
-
-## 运行与验证
-
-1. **保存脚本**：将上述代码保存为 `.py` 或 `.js` 文件。
-2. **创建任务**：在面板中创建新任务并关联该文件。
-3. **注入配置**：在任务配置中填入 `BHPKG_NOTIFY_TOKEN` 等变量。
-4. **立即运行**：点击「运行」按钮，检查对应的消息渠道是否收到了推送消息。

docs/guide/notify.md

@@ -37,14 +37,17 @@
 
 ### 路径二：脚本手动调用 (内置助手库 - 推荐)
 
-白虎面板提供了一套**零配置**的内建助手库（Built-in SDK），支持 Python 和 Node.js。它会自动读取系统注入的环境变量，让您在脚本中只需一行代码即可实现通知投递。
+白虎面板提供了一套**零配置**的内建助手库（Built-in SDK），支持 Python 和 Node.js。除了支持极简的消息通知投递外，它还支持管理面板的**环境变量**与**定时任务控制**。
 
 #### 1. 如何获取配置 Key？
-在使用助手库前，请确保您已经在任务设置的“环境变量”或“机密”中配置了以下两个同名 Key：
+在使用助手库前，请确保您已经在任务设置的“环境变量”或“机密”中配置了以下对应 Key：
-- **BHPKG_NOTIFY_TOKEN**：进入「消息推送」->「脚本调用说明」标签，您可以直接复制此处的 Token（如未生成请先点击生成）。
+- **消息推送相关**：
-- **BHPKG_NOTIFY_CHANNEL**：进入「消息推送」->「渠道列表」标签，可以查看每个渠道对应的 **ID**。如果您希望使用默认渠道，也可直接在「脚本调用说明」页面的代码示例中找到默认 ID。
+  - `BHPKG_NOTIFY_TOKEN`：进入「消息推送」->「脚本调用说明」标签，可以直接复制此处的 Token。
-- **BHPKG_NOTIFY_URL** (可选)：内建通知 API 的地址。默认为 `http://localhost:8052/api/v1/notify/send`。**如果您更改了容器内部的服务监听端口（如通过 `BH_SERVER_PORT`），则需要同步设置此变量为 `http://localhost:{您的端口}/api/v1/notify/send`。**
+  - `BHPKG_NOTIFY_CHANNEL`：进入「消息推送」->「渠道列表」标签，可以查看每个渠道对应的 **ID**。
-
+  - `BHPKG_NOTIFY_URL` (可选)：内置通知 API 的地址。默认为 `http://localhost:8052/api/v1/notify/send`。
+- **环境与任务管理相关**：
+  - `BHPKG_OPENAPI_TOKEN` (或 `OPENAPI_TOKEN`)：OpenAPI 鉴权 Token，在「系统设置」->「OpenAPI」中生成。
+  - `BHPKG_OPENAPI_URL` (可选)：默认为本地面板 API 地址。
 
 #### 2. 环境初始化
 在开始编写脚本前，您需要在终端执行以下命令，为面板管理的所有语言环境安装 `baihu` 包：
@@ -54,24 +57,38 @@ baihu builtininstall
 ```
 *该操作会将助手库安装到 mise 管理的所有版本中，确保 import 成功。*
 
-#### 2. 代码示例
+#### 3. 代码示例
 
 ##### Python (同步调用)
 ```python
 import baihu
 
-# 内部自动通过环境变量鉴权，无需填 TOKEN 和 URL
+# 消息通知
 baihu.notify("任务标题", "通知正文内容")
+
+# 环境变量与任务管理（详细用法见内置库示例）
+envs = baihu.get_envs()
+tasks = baihu.get_tasks()
 ```
 
 ##### Node.js (异步调用)
 ```javascript
 const baihu = require('baihu');
 
-// 极简调用，支持在 CommonJS/ESM 中使用
+// 消息通知
 baihu.notify("任务标题", "通知正文内容");
+
+// 环境变量与任务管理（详细用法见内置库示例）
+(async () => {
+    const envs = await baihu.getEnvs();
+    const tasks = await baihu.getTasks();
+})();
 ```
 
+> [!TIP]
+> 关于环境变量增删改查以及任务触发控制的完整 API 列表与更详尽的代码，请参考 [内置库示例](./examples/builtin.md)。
+
+
 ---
 
 ### 路径三：其他语言/高级调用 (原始 API)

example/builtin/test_env.js

@@ -0,0 +1,58 @@
+const baihu = require('baihu');
+
+/**
+ * 内建工具环境变量管理测试示例 (Node.js)
+ * 
+ * 使用说明：
+ * 1. 确保已在该 Node.js 环境下安装过内建包。
+ * 2. 运行时系统需要注入有效的 OpenAPI 凭证 (BHPKG_OPENAPI_TOKEN 或 OPENAPI_TOKEN)。
+ */
+
+async function main() {
+    console.log("====== 开始运行 Node.js 环境变量管理示例 ======");
+
+    try {
+        // 获取全部环境变量
+        const envs = await baihu.getEnvs();
+        console.log(`当前共有 ${envs.length} 个环境变量`);
+
+        // 新增一个临时环境变量
+        const newEnvName = "BHPKG_TEST_KEY_JS";
+        const newEnvVal = "HelloBaihuJS";
+        console.log(`正在创建环境变量: ${newEnvName}...`);
+        const createdEnv = await baihu.addEnv(
+            newEnvName,
+            newEnvVal,
+            "Node.js SDK 测试自动创建"
+        );
+        console.log(`创建成功: ID=${createdEnv.id}, Name=${createdEnv.name}`);
+
+        // 查询该环境变量
+        const checkedEnv = await baihu.getEnv(newEnvName);
+        if (checkedEnv) {
+            console.log(`成功查询到变量: ${checkedEnv.name} = ${checkedEnv.value}`);
+
+            // 修改该环境变量的值
+            const updatedVal = "HelloBaihuJS_Updated";
+            console.log(`正在修改环境变量的值为: ${updatedVal}...`);
+            const updatedEnv = await baihu.updateEnv(
+                checkedEnv.id,
+                newEnvName,
+                updatedVal,
+                "Node.js SDK 测试自动更新"
+            );
+            console.log(`更新成功: Value=${updatedEnv.value}`);
+
+            // 删除该临时环境变量
+            console.log(`正在删除临时环境变量: ID=${checkedEnv.id}...`);
+            await baihu.deleteEnv(checkedEnv.id);
+            console.log("删除成功！");
+        }
+
+    } catch (e) {
+        console.error(`环境变量操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();

example/builtin/test_env.py

@@ -0,0 +1,55 @@
+import baihu
+
+# 内建工具环境变量管理测试示例 (Python)
+# 
+# 前提条件：
+# 1. 已经在环境中安装了 baihu 包（例如通过 `baihu builtininstall`）
+# 2. 环境中已注入有效环境变量：
+#    - BHPKG_OPENAPI_TOKEN (必填，用于管理接口鉴权)
+
+def main():
+    print("====== 开始运行 Python 环境变量管理示例 ======")
+
+    try:
+        # 获取全部环境变量
+        envs = baihu.get_envs()
+        print(f"当前共有 {len(envs)} 个环境变量")
+        
+        # 新增一个临时环境变量
+        new_env_name = "BHPKG_TEST_KEY"
+        new_env_val = "HelloBaihu"
+        print(f"正在创建环境变量: {new_env_name}...")
+        created_env = baihu.add_env(
+            name=new_env_name,
+            value=new_env_val,
+            remark="Python SDK 测试自动创建"
+        )
+        print(f"创建成功: ID={created_env.get('id')}, Name={created_env.get('name')}")
+
+        # 查询刚才创建的环境变量详情
+        checked_env = baihu.get_env(new_env_name)
+        if checked_env:
+            print(f"成功查询到变量: {checked_env.get('name')} = {checked_env.get('value')}")
+
+            # 修改该环境变量的值
+            updated_val = "HelloBaihu_Updated"
+            print(f"正在修改环境变量的值为: {updated_val}...")
+            updated_env = baihu.update_env(
+                id=checked_env.get("id"),
+                name=new_env_name,
+                value=updated_val,
+                remark="Python SDK 测试自动更新"
+            )
+            print(f"更新成功: Value={updated_env.get('value')}")
+
+            # 删除该临时环境变量
+            print(f"正在删除临时环境变量: ID={checked_env.get('id')}...")
+            baihu.delete_env(checked_env.get("id"))
+            print("删除成功！")
+            
+    except Exception as e:
+        print(f"环境变量操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()

example/builtin/test_task.js

@@ -0,0 +1,40 @@
+const baihu = require('baihu');
+
+/**
+ * 内建工具任务管理测试示例 (Node.js)
+ * 
+ * 使用说明：
+ * 1. 确保已在该 Node.js 环境下安装过内建包。
+ * 2. 运行时系统需要注入有效的 OpenAPI 凭证 (BHPKG_OPENAPI_TOKEN 或 OPENAPI_TOKEN)。
+ */
+
+async function main() {
+    console.log("====== 开始运行 Node.js 任务管理与执行控制示例 ======");
+
+    try {
+        // 获取所有任务列表
+        const tasks = await baihu.getTasks();
+        console.log(`成功获取到 ${tasks.length} 个定时任务:`);
+        tasks.slice(0, 5).forEach(task => { // 仅展示前5项
+            console.log(`  - [${task.id}] ${task.name} (表达式: ${task.schedule || ''}, 备注: ${task.remark || ''})`);
+        });
+
+        // 尝试触发第一个任务的运行
+        if (tasks.length > 0) {
+            const targetTask = tasks[0];
+            console.log(`\n尝试手动触发任务运行: [${targetTask.id}] ${targetTask.name}...`);
+            await baihu.executeTask(targetTask.id);
+            console.log("执行指令发送成功。");
+        }
+
+        // 获取最近的执行结果列表
+        const results = await baihu.getLastResults();
+        console.log(`\n最近共有 ${results.length} 条任务执行记录。`);
+
+    } catch (e) {
+        console.error(`任务操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();

example/builtin/test_task.py

@@ -0,0 +1,36 @@
+import baihu
+
+# 内建工具任务管理与执行控制测试示例 (Python)
+# 
+# 前提条件：
+# 1. 已经在环境中安装了 baihu 包（例如通过 `baihu builtininstall`）
+# 2. 环境中已注入有效环境变量：
+#    - BHPKG_OPENAPI_TOKEN (必填，用于管理接口鉴权)
+
+def main():
+    print("====== 开始运行 Python 任务管理与执行控制示例 ======")
+
+    try:
+        # 获取所有任务列表
+        tasks = baihu.get_tasks()
+        print(f"成功获取到 {len(tasks)} 个定时任务:")
+        for task in tasks[:5]:  # 仅打印前5个
+            print(f"  - [{task.get('id')}] {task.get('name')} (表达式: {task.get('schedule')}, 备注: {task.get('remark')})")
+
+        # 示例：尝试触发第一个任务的运行
+        if tasks:
+            target_task = tasks[0]
+            print(f"\n尝试手动触发任务运行: [{target_task.get('id')}] {target_task.get('name')}...")
+            result = baihu.execute_task(target_task.get("id"))
+            print("执行指令发送成功。")
+
+        # 获取最近的执行结果列表
+        results = baihu.get_last_results()
+        print(f"\n最近共有 {len(results)} 条任务执行记录。")
+            
+    except Exception as e:
+        print(f"任务操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()