mioku-plugin-agent 0.1.0

package/tools/todo.ts

@@ -0,0 +1,136 @@
+import type { AITool, Bot } from "mioku";
+import type { AgentHost } from "../types";
+import type { SessionPlanItem, SessionPlanStatus } from "../db";
+
+const STATUSES: readonly SessionPlanStatus[] = [
+  "pending",
+  "in_progress",
+  "completed",
+];
+
+const MAX_ITEMS = 50;
+
+const MARKER: Record<SessionPlanStatus, string> = {
+  pending: "[ ]",
+  in_progress: "[~]",
+  completed: "[x]",
+};
+
+const DESCRIPTION =
+  "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). " +
+  "Use it to plan multi-step work and show progress: add one todo per concrete step before you start. " +
+  "Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. " +
+  "Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. " +
+  "Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). " +
+  "Every update is pushed to the user in the chat, so keep items short and imperative.";
+
+export function formatPlanText(items: SessionPlanItem[]): string {
+  const count = (status: SessionPlanStatus) =>
+    items.filter((item) => item.status === status).length;
+  const summary = `${count("in_progress")} 进行中 · ${count("pending")} 待办 · ${count("completed")} 已完成`;
+  return [
+    `📋 任务清单已更新（${summary}）`,
+    ...items.map(
+      (item, index) => `${MARKER[item.status]} ${index + 1}. ${item.content}`,
+    ),
+  ].join("\n");
+}
+
+export function createTodoTool(options: {
+  host: AgentHost;
+  userId: number;
+  bot: Bot | undefined;
+  /** yolo 模式：不推送清单，用户只看最终回复 */
+  quiet?: boolean;
+}): AITool {
+  const { host, userId, bot, quiet } = options;
+  return {
+    name: "todo_write",
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      properties: {
+        todos: {
+          type: "array",
+          description: "The COMPLETE task list, replacing any previous list",
+          items: {
+            type: "object",
+            properties: {
+              content: {
+                type: "string",
+                description: "What the task is — a short imperative line",
+              },
+              status: {
+                type: "string",
+                description: "pending (not started) | in_progress (now) | completed (done)",
+              },
+            },
+            required: ["content", "status"],
+          },
+        },
+      },
+      required: ["todos"],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      const raw = args?.todos;
+      if (!Array.isArray(raw)) return { error: "todos must be an array" };
+
+      const items: SessionPlanItem[] = [];
+      const seen = new Set<string>();
+      for (const entry of raw) {
+        if (!entry || typeof entry !== "object") {
+          return { error: "each todo must be an object with content and status" };
+        }
+        const record = entry as Record<string, unknown>;
+        const content = String(record.content ?? "").trim();
+        if (!content) return { error: "todo content must be a non-empty string" };
+        if (seen.has(content)) {
+          return { error: `duplicate todo content: ${content}` };
+        }
+        seen.add(content);
+        const status = String(record.status ?? "").trim() as SessionPlanStatus;
+        if (!STATUSES.includes(status)) {
+          return {
+            error: `invalid status "${record.status}": use pending | in_progress | completed`,
+          };
+        }
+        items.push({ content, status });
+      }
+
+      if (items.length > MAX_ITEMS) {
+        return { error: `too many items (max ${MAX_ITEMS})` };
+      }
+      const inProgress = items.filter((item) => item.status === "in_progress");
+      if (inProgress.length > 1) {
+        return {
+          error:
+            "at most one todo may be in_progress; mark finished work completed before starting the next",
+        };
+      }
+
+      const session = host.sessions.get(userId);
+      host.db.setSessionMeta(session.sessionId, { plan: items });
+
+      if (bot && !quiet) {
+        await bot
+          .sendMessage(
+            { type: "private", user_id: userId },
+            [host.ctx.segment.text(formatPlanText(items))],
+          )
+          .catch((err) =>
+            host.logger.warn(`[agent] failed to push todo update: ${err}`),
+          );
+      }
+
+      return {
+        success: true,
+        todos: items,
+        counts: {
+          pending: items.filter((item) => item.status === "pending").length,
+          inProgress: inProgress.length,
+          completed: items.filter((item) => item.status === "completed").length,
+        },
+      };
+    },
+  };
+}

package/tools/view-image.ts

@@ -0,0 +1,85 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { AITool } from "mioku";
+import { TOOL_RESULT_FOLLOWUP_KEY } from "mioku";
+import { readImageDataUrl } from "../core/download";
+import type { FsPolicy } from "./perm";
+import { resolveWorkspacePath } from "./perm";
+
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp"];
+
+export interface ViewImageDeps {
+  policy: FsPolicy;
+  describeImage?: (filePath: string) => Promise<string>;
+}
+
+export function createViewImageTool(deps: ViewImageDeps): AITool {
+  return {
+    name: "view_image",
+    description:
+      "View a local image file (png/jpeg/webp/gif/bmp) such as a screenshot or a downloaded photo. " +
+      (deps.describeImage
+        ? "The image is sent to the vision model and its description is returned."
+        : "The image is attached to the conversation so you can inspect it directly."),
+    parameters: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Image path (absolute, or relative to the workspace)",
+        },
+      },
+      required: ["file_path"],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      const filePath = resolveWorkspacePath(
+        deps.policy,
+        String(args?.file_path ?? ""),
+      );
+      const ext = path.extname(filePath).toLowerCase();
+      if (ext && !IMAGE_EXTENSIONS.includes(ext)) {
+        return {
+          error: `unsupported image type "${ext}": use ${IMAGE_EXTENSIONS.join(", ")}`,
+        };
+      }
+
+      let stat: fs.Stats;
+      try {
+        stat = await fsp.stat(filePath);
+      } catch {
+        return { error: `File not found: ${filePath}` };
+      }
+      if (!stat.isFile()) return { error: `Not a regular file: ${filePath}` };
+      if (stat.size > MAX_IMAGE_BYTES) {
+        return {
+          error: `Image too large (${stat.size} bytes, max ${MAX_IMAGE_BYTES})`,
+        };
+      }
+
+      if (deps.describeImage) {
+        const description = await deps
+          .describeImage(filePath)
+          .catch((err) => `describe failed: ${err}`);
+        return { file: filePath, size: stat.size, description };
+      }
+
+      let dataUrl: string;
+      try {
+        dataUrl = await readImageDataUrl(filePath);
+      } catch (err) {
+        return { error: `Failed to read image: ${err}` };
+      }
+      return {
+        file: filePath,
+        size: stat.size,
+        seen: true,
+        [TOOL_RESULT_FOLLOWUP_KEY]: {
+          text: `Image attached from ${filePath}.`,
+          images: [{ url: dataUrl }],
+        },
+      };
+    },
+  };
+}

package/tools/web.ts

@@ -0,0 +1,133 @@
+import type { AITool } from "mioku";
+import type { AgentSettingsConfig } from "../types";
+
+interface WebToolDeps {
+  settings: AgentSettingsConfig;
+  onSearch?: () => void;
+}
+
+interface SearxngResult {
+  title?: string;
+  url?: string;
+  content?: string;
+}
+
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<\/(p|div|li|h[1-6]|tr|section|article|blockquote|pre)>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<li[^>]*>/gi, "- ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n\s*\n\s*\n+/g, "\n\n")
+    .trim();
+}
+
+function extractTitle(html: string): string {
+  const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+  return match ? match[1].trim().slice(0, 200) : "";
+}
+
+export function createWebSearchTool(deps: WebToolDeps): AITool {
+  const { settings, onSearch } = deps;
+  return {
+    name: "web_search",
+    description:
+      "Search the web via SearXNG and return a list of results (title, url, snippet).",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        limit: { type: "number", description: `Max results (default ${settings.webSearch.defaultLimit})` },
+      },
+      required: ["query"],
+    },
+    handler: async (args) => {
+      const query = String(args?.query ?? "").trim();
+      if (!query) return { error: "query must be a non-empty string" };
+      if (!settings.webSearch.enabled) {
+        return { error: "web search is disabled in agent settings" };
+      }
+      onSearch?.();
+      const limit = Math.min(
+        Math.max(1, Math.floor(Number(args?.limit) || settings.webSearch.defaultLimit)),
+        settings.webSearch.maxLimit,
+      );
+      const url = new URL(settings.webSearch.baseUrl);
+      url.searchParams.set("q", query);
+      url.searchParams.set("format", "json");
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(settings.webSearch.timeoutMs),
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) {
+        return { error: `Search request failed: HTTP ${response.status}` };
+      }
+      const data = (await response.json()) as { results?: SearxngResult[] };
+      const results = (data.results ?? []).slice(0, limit).map((item) => ({
+        title: item.title ?? "",
+        url: item.url ?? "",
+        snippet: item.content ?? "",
+      }));
+      return { query, count: results.length, results };
+    },
+  };
+}
+
+export function createWebFetchTool(deps: WebToolDeps): AITool {
+  const { settings } = deps;
+  return {
+    name: "web_fetch",
+    description:
+      "Fetch a web page URL and return the extracted main text content (HTML converted to plain text).",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "HTTP(S) URL to fetch" },
+      },
+      required: ["url"],
+    },
+    handler: async (args) => {
+      const target = String(args?.url ?? "").trim();
+      if (!/^https?:\/\//i.test(target)) {
+        return { error: "url must start with http:// or https://" };
+      }
+      if (!settings.webFetch.enabled) {
+        return { error: "web fetch is disabled in agent settings" };
+      }
+      const response = await fetch(target, {
+        signal: AbortSignal.timeout(settings.webFetch.timeoutMs),
+        headers: {
+          "User-Agent":
+            "Mozilla/5.0 (compatible; mioku-agent/0.1; +https://github.com/mioku-lab)",
+          Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.5",
+        },
+        redirect: "follow",
+      });
+      if (!response.ok) {
+        return { error: `Fetch failed: HTTP ${response.status}` };
+      }
+      const contentType = response.headers.get("content-type") ?? "";
+      const raw = await response.text();
+      if (contentType.includes("text/plain")) {
+        return { url: target, contentType, content: raw.slice(0, settings.webFetch.maxChars) };
+      }
+      return {
+        url: target,
+        contentType,
+        title: extractTitle(raw),
+        content: htmlToText(raw).slice(0, settings.webFetch.maxChars),
+      };
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["**/*.ts"]
+}

package/types.ts

@@ -0,0 +1,111 @@
+import type {
+  AIInstance,
+  AIService,
+  ConfigService,
+  MiokuContext,
+  ScreenshotService,
+} from "mioku";
+import type { AgentDatabase } from "./db";
+import type { SessionManager } from "./core/session";
+import type { EmotionManager } from "./core/emotion";
+import type { ApprovalManager } from "./tools/approval";
+
+export type AgentPermissionLevel =
+  | "read-only"
+  | "workspace-write"
+  | "auto"
+  | "full"
+  | "yolo";
+
+export interface AgentAccessConfig {
+  allowAdmins: boolean;
+  users: number[];
+}
+
+export interface AgentBaseConfig {
+  access: AgentAccessConfig;
+  workspaceDir: string;
+  permissionLevel: AgentPermissionLevel;
+  model: string;
+}
+
+export interface CompactionConfig {
+  enabled: boolean;
+  keepRecentMessages: number;
+}
+
+export interface WebSearchConfig {
+  enabled: boolean;
+  baseUrl: string;
+  timeoutMs: number;
+  defaultLimit: number;
+  maxLimit: number;
+  maxSearchCount: number;
+}
+
+export interface WebFetchConfig {
+  enabled: boolean;
+  timeoutMs: number;
+  maxChars: number;
+}
+
+export interface BashConfig {
+  enabled: boolean;
+  timeoutMs: number;
+  approvalTimeoutMs: number;
+}
+
+export interface AgentSettingsConfig {
+  maxIterations: number;
+  temperature: number;
+  maxContextTokens: number;
+  stream: boolean;
+  enableMarkdownScreenshot: boolean;
+  compaction: CompactionConfig;
+  webSearch: WebSearchConfig;
+  webFetch: WebFetchConfig;
+  bash: BashConfig;
+  dataCollection: { enabled: boolean };
+  debug: boolean;
+}
+
+export interface ChatEmotionConfig {
+  defaultEmotion: string;
+  emotions: Record<string, { examples: string[] }>;
+}
+
+export interface ChatSharedConfig {
+  persona: string;
+  replyStyle: string;
+  emotion: ChatEmotionConfig | null;
+}
+
+export interface ResolvedModel {
+  instance: AIInstance;
+  model: string;
+  working: AIInstance;
+  workingModel: string;
+  vision: AIInstance | undefined;
+  visionModel: string;
+  isMultimodal: boolean;
+  contextWindow: number;
+}
+
+export interface AgentHost {
+  ctx: MiokuContext;
+  aiService: AIService;
+  configService: ConfigService | undefined;
+  screenshot: ScreenshotService | undefined;
+  db: AgentDatabase;
+  approvals: ApprovalManager;
+  sessions: SessionManager;
+  emotions: EmotionManager;
+  getBase(): AgentBaseConfig;
+  getSettings(): AgentSettingsConfig;
+  getChatShared(): Promise<ChatSharedConfig>;
+  resolveModel(): ResolvedModel | null;
+  workspaceRoot(userId: number): string;
+  isAllowed(userId: number): Promise<boolean>;
+  updateBase(patch: Partial<AgentBaseConfig>): Promise<void>;
+  logger: MiokuContext["logger"];
+}

package/utils/config.ts

@@ -0,0 +1,31 @@
+function isConfigObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function mergeAgentConfig<T extends object>(
+  defaults: T,
+  overrides: Record<string, unknown>,
+): T {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(defaults as Record<string, unknown>)) {
+    if (isConfigObject(value)) {
+      result[key] = mergeAgentConfig(value, {});
+    } else if (Array.isArray(value)) {
+      result[key] = [...value];
+    } else {
+      result[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(overrides ?? {})) {
+    if (value === undefined || value === null) continue;
+    if (isConfigObject(value)) {
+      const baseValue = isConfigObject(result[key]) ? result[key] : {};
+      result[key] = mergeAgentConfig(baseValue, value);
+    } else if (Array.isArray(value)) {
+      result[key] = [...value];
+    } else {
+      result[key] = value;
+    }
+  }
+  return result as T;
+}

package/utils/json.ts

@@ -0,0 +1,5 @@
+export function extractJsonObject<T = unknown>(text: string): T | undefined {
+  const match = String(text ?? "").match(/\{[\s\S]*\}/);
+  if (!match) return undefined;
+  return JSON.parse(match[0]) as T;
+}