dsh-linux-commander 0.0.0-stage → 1.2.0

package/index.js

@@ -0,0 +1,82 @@
+// Linux 指令器 — Host half.
+// Registers one loopback HTTP route that the browser widget calls.
+// All AI traffic (and the API key) stays in this host process; the client
+// bundle contains no credentials. Local library answers never touch AI.
+import { createPipeline } from './src/core.js';
+import { createAiAdapter } from './src/ai.js';
+
+const ROUTE = '/linux-commander/query';
+const BODY_LIMIT = 16 * 1024;
+
+export const inject = ['webServer'];
+
+function sendJson(res, status, value) {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+  });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > BODY_LIMIT) {
+        reject(Object.assign(new Error('body too large'), { statusCode: 413 }));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+export function apply(ctx, config = {}) {
+  const ai = createAiAdapter(config, ctx.logger);
+  const run = createPipeline({ ai });
+
+  ctx.effect(() => {
+    const dispose = ctx.webServer.register({
+      kind: 'exact',
+      path: ROUTE,
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            sendJson(res, 200, { ok: true, service: 'linux-commander', aiConfigured: ai.configured });
+            return;
+          }
+          if (req.method !== 'POST') {
+            sendJson(res, 405, { ok: false, code: 'method', message: '仅支持 POST' });
+            return;
+          }
+          const type = String(req.headers['content-type'] || '');
+          if (!type.includes('application/json')) {
+            sendJson(res, 415, { ok: false, code: 'content_type', message: '需要 application/json' });
+            return;
+          }
+          let payload;
+          try {
+            payload = JSON.parse(await readBody(req));
+          } catch (err) {
+            sendJson(res, err.statusCode || 400, { ok: false, code: 'bad_request', message: '请求体无效' });
+            return;
+          }
+          const result = await run(payload?.input);
+          sendJson(res, 200, result);
+        } catch (err) {
+          ctx.logger?.warn?.(err instanceof Error ? err : new Error(String(err)));
+          if (!res.headersSent) sendJson(res, 500, { ok: false, code: 'internal', message: '服务内部错误' });
+          else res.end();
+        }
+      },
+    });
+    return dispose;
+  }, 'linux-commander.route');
+}

package/locale/en.json

@@ -0,0 +1,21 @@
+{
+  "meta": {
+    "title": "Linux commands",
+    "description": "A lightweight docked Linux tool: explains commands and turns plain language into commands, local-first with AI fallback."
+  },
+  "ui": {
+    "title": "Linux commands",
+    "placeholder": "Command or task",
+    "open": "Open Linux commands",
+    "close": "Collapse",
+    "copy": "Copy",
+    "copied": "Copied",
+    "copyFailed": "Copy failed",
+    "loading": "Searching",
+    "sourceLocal": "local",
+    "sourceAi": "AI",
+    "errorGeneric": "Query failed, please retry",
+    "errorNetwork": "Cannot reach the local service",
+    "emptyInput": "Type something first"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,21 @@
+{
+  "meta": {
+    "title": "Linux 指令器",
+    "description": "侧边停靠的轻量 Linux 指令工具：解释指令、把自然语言转成指令，本地优先、AI 兜底。"
+  },
+  "ui": {
+    "title": "Linux 指令器",
+    "placeholder": "输入指令或操作",
+    "open": "打开 Linux 指令器",
+    "close": "收起",
+    "copy": "复制",
+    "copied": "已复制",
+    "copyFailed": "复制失败",
+    "loading": "查询中",
+    "sourceLocal": "本地",
+    "sourceAi": "AI",
+    "errorGeneric": "查询失败，请稍后重试",
+    "errorNetwork": "无法连接本地服务",
+    "emptyInput": "请输入内容"
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dsh-linux-commander",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "DSH plugin: a docked Linux command explainer and natural-language-to-command tool, local-first with AI fallback.",
+  "type": "module",
+  "license": "MIT",
+  "author": "yichenbr1888-svg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yichenbr1888-svg/linux-commander.git"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "linux",
+    "command",
+    "cheatsheet"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "src/*.js",
+    "src/client/*.js",
+    "locale/*.json",
+    "icon.svg",
+    "build-client.mjs",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  }
 }

package/src/ai.js

@@ -0,0 +1,190 @@
+// Linux 指令器 — AI fallback adapter (host-side only).
+// Talks to any OpenAI-compatible chat completions endpoint. Endpoint, model
+// and key are supplied per machine via plugin config or environment
+// variables; no vendor-specific values ship with the package. Includes
+// timeout control, tolerant response parsing, an LRU result cache, and
+// in-flight dedupe.
+
+const DEFAULT_MODEL = '';
+// Command knowledge is stable; a long TTL makes repeat queries near-free.
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_MAX = 500;
+
+const SYSTEM_PROMPT = [
+  '你是一个 Linux 指令助手，只输出一行 JSON，不要输出任何其他文字、解释或 Markdown 代码块。',
+  'JSON 格式：{"kind":"explain"或"generate","command":"...","explanation":"...","warning":"..."}',
+  '规则：',
+  '1. kind=explain 时，command 原样返回用户输入的指令，explanation 用通俗简体中文解释这条指令的作用（含参数与管道），不超过 60 字。',
+  '2. kind=generate 时，把用户的操作需求转成一条最常用、兼容性好的 Linux 指令放入 command（单行，可直接复制）；explanation 是一句不超过 30 字的简短说明，可为空字符串。',
+  '3. 缺少路径、用户名、端口等参数时，使用 <路径> <文件> <用户名> <端口> 这类清晰占位符。',
+  '4. 指令有实际风险（删除、覆盖、强制、关机等）时，warning 给出不超过 30 字的简短中文提醒，否则 warning 为空字符串。',
+  '5. 考虑发行版差异，优先 GNU/Linux 通用命令；不确定时如实说明，绝不编造指令或参数。',
+  '6. 绝不执行任何命令，只输出文本。',
+].join('\n');
+
+function userPrompt(input, intent) {
+  const task = intent === 'command'
+    ? '请解释这条 Linux 指令（kind=explain）。'
+    : intent === 'natural'
+      ? '请把这句操作需求转成一条 Linux 指令（kind=generate）。'
+      : '请先判断输入是 Linux 指令还是操作需求：指令则解释（kind=explain），需求则生成指令（kind=generate）。';
+  return `${task}\n输入：${input}`;
+}
+
+/** Pull assistant text out of OpenAI-style and common vendor response shapes. */
+function extractContent(data) {
+  if (!data || typeof data !== 'object') return null;
+  if (data.header && typeof data.header.code === 'number' && data.header.code !== 0) {
+    const err = new Error(data.header.message || `AI 服务错误 ${data.header.code}`);
+    err.aiCode = 'ai_service';
+    throw err;
+  }
+  const candidates = [
+    data.choices?.[0]?.message?.content,
+    data.choices?.[0]?.text,
+    data.payload?.choices?.text?.[0]?.content,
+    data.output_text,
+    data.response,
+    data.result,
+    data.answer,
+    data.content,
+    data.message?.content,
+  ];
+  for (const c of candidates) if (typeof c === 'string' && c.trim()) return c;
+  return null;
+}
+
+/** Parse the model's JSON answer; fall back to tolerant plain-text reads. */
+function parseAnswer(content, input, intent) {
+  let text = content.trim();
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  if (fence) text = fence[1].trim();
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start !== -1 && end > start) {
+    try {
+      const obj = JSON.parse(text.slice(start, end + 1));
+      const kind = obj.kind === 'generate' ? 'generate' : obj.kind === 'explain' ? 'explain' : null;
+      if (kind) {
+        let command = typeof obj.command === 'string' ? obj.command.replace(/[\r\n]+/g, ' ').trim() : '';
+        let explanation = typeof obj.explanation === 'string' ? obj.explanation.replace(/\s+/g, ' ').trim() : '';
+        let warning = typeof obj.warning === 'string' ? obj.warning.replace(/\s+/g, ' ').trim() : '';
+        if (kind === 'explain' && !command) command = input;
+        if (kind === 'generate' && !command) return null;
+        if (command.length > 400) return null;
+        return {
+          kind,
+          command,
+          explanation: explanation.slice(0, 160),
+          ...(warning ? { warning: warning.slice(0, 120) } : {}),
+        };
+      }
+    } catch { /* fall through to plain-text fallback */ }
+  }
+  // Plain-text fallback: a bare command line, or a short Chinese explanation.
+  const oneLine = text.replace(/[\r\n]+/g, ' ').trim();
+  const looksCommand = /^[A-Za-z_./~][A-Za-z0-9_./~+-]*(\s|$)/.test(oneLine) && !/[\u4e00-\u9fff]/.test(oneLine);
+  if ((intent === 'natural' || intent === 'auto') && looksCommand && oneLine.length <= 400) {
+    return { kind: 'generate', command: oneLine, explanation: '' };
+  }
+  if ((intent === 'command' || intent === 'auto') && /[\u4e00-\u9fff]/.test(oneLine) && oneLine.length <= 200) {
+    return { kind: 'explain', command: input, explanation: oneLine };
+  }
+  return null;
+}
+
+export function createAiAdapter(config = {}, logger) {
+  const endpoint = process.env.DSH_LINUX_COMMANDER_ENDPOINT
+    || (typeof config.endpoint === 'string' ? config.endpoint.trim() : '');
+  const model = process.env.DSH_LINUX_COMMANDER_MODEL
+    || (typeof config.model === 'string' && config.model.trim() ? config.model.trim() : DEFAULT_MODEL);
+  const apiKey = process.env.DSH_LINUX_COMMANDER_API_KEY || (typeof config.apiKey === 'string' ? config.apiKey.trim() : '');
+  // Reasoning models may take 20-30s; allow a generous budget.
+  const timeoutMs = Math.min(120000, Math.max(3000, Number(config.timeoutMs) || 45000));
+  const cache = new Map();
+  const inflight = new Map();
+
+  const cacheGet = (key) => {
+    const hit = cache.get(key);
+    if (!hit) return undefined;
+    if (Date.now() - hit.t > CACHE_TTL_MS) { cache.delete(key); return undefined; }
+    return hit.value;
+  };
+  const cacheSet = (key, value) => {
+    cache.set(key, { t: Date.now(), value });
+    if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+  };
+
+  async function request(input, intent) {
+    const body = {
+      model,
+      messages: [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'user', content: userPrompt(input, intent) },
+      ],
+      stream: false,
+      max_completion_tokens: 3000,
+      // Deep thinking is permanently OFF: this tool only answers simple
+      // command questions; thinking adds seconds of latency for no benefit.
+      thinking: { type: 'disabled' },
+    };
+    let res;
+    try {
+      res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      if (err && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+        return { ok: false, code: 'timeout', message: 'AI 响应超时，请稍后重试' };
+      }
+      return { ok: false, code: 'network', message: 'AI 网络请求失败' };
+    }
+    let data = null;
+    try { data = await res.json(); } catch { /* non-JSON body */ }
+    if (!res.ok) {
+      const detail = data?.error?.message || data?.message || data?.header?.message || '';
+      if (res.status === 401 || res.status === 403) return { ok: false, code: 'auth', message: 'AI 接口鉴权失败，请检查 API Key' };
+      if (res.status === 429) return { ok: false, code: 'rate', message: 'AI 请求过于频繁，请稍后重试' };
+      return { ok: false, code: 'ai_http', message: `AI 接口错误（${res.status}）${detail ? '：' + String(detail).slice(0, 60) : ''}` };
+    }
+    let content;
+    try { content = extractContent(data); } catch (err) {
+      return { ok: false, code: err.aiCode || 'ai_error', message: String(err.message || 'AI 服务错误').slice(0, 80) };
+    }
+    if (!content) {
+      if (data?.choices?.[0]?.finish_reason === 'length') {
+        return { ok: false, code: 'truncated', message: 'AI 响应被截断，请重试' };
+      }
+      return { ok: false, code: 'bad_response', message: 'AI 返回格式无法解析' };
+    }
+    const parsed = parseAnswer(content, input, intent);
+    if (!parsed) return { ok: false, code: 'bad_response', message: 'AI 返回内容无法解析' };
+    return { ok: true, source: 'ai', ...parsed };
+  }
+
+  return {
+    configured: Boolean(apiKey && endpoint && model),
+    async query(input, intent) {
+      if (!apiKey || !endpoint || !model) return { ok: false, code: 'not_configured', message: 'AI 接口未配置，仅支持本地查询' };
+      const key = `${intent}\u0000${input}`;
+      const cached = cacheGet(key);
+      if (cached) return { ...cached, source: 'cache' };
+      if (inflight.has(key)) return inflight.get(key);
+      const task = request(input, intent)
+        .then((result) => {
+          if (result.ok) cacheSet(key, result);
+          return result;
+        })
+        .catch((err) => {
+          logger?.warn?.(err instanceof Error ? err : new Error(String(err)));
+          return { ok: false, code: 'ai_error', message: 'AI 服务异常' };
+        })
+        .finally(() => inflight.delete(key));
+      inflight.set(key, task);
+      return task;
+    },
+  };
+}