my-opencode-toolkit 0.0.0-stage → 0.2.1

package/src/i18n/index.ts

@@ -0,0 +1,28 @@
+import { en } from "./en.ts"
+import type { Messages } from "./types.ts"
+import { zh } from "./zh.ts"
+
+export type { Messages }
+
+/**
+ * 输入：locale 字符串（可为空）。
+ * 输出：对应语言的消息表。
+ * 预期：`zh*` 用中文，其余一律英文；空值回退到系统 locale。
+ */
+export function resolveMessages(locale: string | undefined): Messages {
+  const value = (locale ?? detectLocale()).toLowerCase()
+  return value.startsWith("zh") ? zh : en
+}
+
+/**
+ * 输入：无。
+ * 输出：系统 locale。
+ * 预期：运行时拿不到时回退 `en`，保证始终有文案。
+ */
+export function detectLocale(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale
+  } catch {
+    return "en"
+  }
+}

package/src/i18n/types.ts

@@ -0,0 +1,57 @@
+/**
+ * 界面文案。
+ *
+ * 源码里只引用键名，所有用户可见文字都来自语言文件。
+ */
+export type Messages = {
+  readonly command: {
+    readonly title: string
+    readonly description: string
+    readonly group: string
+  }
+  readonly menu: {
+    readonly title: string
+    readonly enabled: string
+    readonly language: string
+    readonly notifications: string
+    readonly goal: string
+    readonly scheduling: string
+    readonly sidebar: string
+    readonly on: string
+    readonly off: string
+    readonly auto: string
+    readonly chinese: string
+    readonly english: string
+    readonly showCache: string
+    readonly showTools: string
+    readonly showSubagents: string
+    readonly collapsed: string
+  }
+  readonly panel: {
+    readonly title: string
+    readonly goal: string
+    readonly noGoal: string
+    readonly loops: string
+    readonly jobs: string
+    readonly cache: string
+    readonly tools: string
+    readonly subagents: string
+    readonly status: Readonly<Record<string, string>>
+  }
+  readonly sidebar: {
+    readonly title: string
+    readonly on: string
+    readonly off: string
+  }
+  readonly notification: {
+    readonly title: string
+    readonly completed: string
+    readonly question: string
+    readonly permission: string
+    readonly user: string
+    readonly assistant: string
+  }
+  readonly tool: {
+    readonly pingResult: (enabled: boolean, lang: string) => string
+  }
+}

package/src/i18n/zh.ts

@@ -0,0 +1,61 @@
+import type { Messages } from "./types.ts"
+
+/** 中文文案。 */
+export const zh: Messages = {
+  command: {
+    title: "工具包设置",
+    description: "打开 my-opencode-toolkit 设置",
+    group: "插件",
+  },
+  menu: {
+    title: "my-opencode-toolkit",
+    enabled: "启用",
+    language: "语言",
+    notifications: "通知",
+    goal: "目标",
+    scheduling: "定时任务",
+    sidebar: "侧栏",
+    on: "开",
+    off: "关",
+    auto: "自动",
+    chinese: "中文",
+    english: "English",
+    showCache: "缓存",
+    showTools: "工具",
+    showSubagents: "子代理",
+    collapsed: "折叠",
+  },
+  panel: {
+    title: "工具包",
+    goal: "目标",
+    noGoal: "无",
+    loops: "循环",
+    jobs: "定时",
+    cache: "缓存",
+    tools: "工具",
+    subagents: "子代理",
+    status: {
+      active: "进行中",
+      paused: "已暂停",
+      blocked: "已阻塞",
+      budget_limited: "预算用尽",
+      complete: "已完成",
+    },
+  },
+  sidebar: {
+    title: "工具包",
+    on: "已启用",
+    off: "已禁用",
+  },
+  notification: {
+    title: "OpenCode",
+    completed: "任务完成",
+    question: "代理正在提问",
+    permission: "需要权限确认",
+    user: "用户",
+    assistant: "助手",
+  },
+  tool: {
+    pingResult: (enabled, lang) => `my-opencode-toolkit：启用=${enabled ? "是" : "否"}，语言=${lang}`,
+  },
+}

package/src/index.ts

@@ -0,0 +1,150 @@
+import { Plugin } from "@opencode/plugin"
+
+import { hideGoalTools } from "./goal/filter.ts"
+import { registerGoal } from "./goal/index.ts"
+import { createGoalController } from "./goal/controller.ts"
+import { createSessionRoles } from "./goal/session-role.ts"
+import { createNotifier } from "./notification/index.ts"
+import { hideSchedulingTools } from "./scheduling/filter.ts"
+import { registerScheduling } from "./scheduling/index.ts"
+import { dispatchEvent, type EventHandler } from "./shared/events.ts"
+import { asRecord } from "./shared/json.ts"
+import { ToolkitRpc } from "./shared/rpc.ts"
+import { loadSettings, saveSettings } from "./shared/settings-store.ts"
+import { normalizeSettings } from "./shared/settings.ts"
+import { buildStats, createStatsTracker, hitRatePercent, trackEvent } from "./stats.ts"
+import { registerPingTool } from "./tools/ping.ts"
+
+export default Plugin.define({
+  id: "my-opencode-toolkit",
+
+  /**
+   * 输入：OpenCode 注入的插件上下文。
+   * 输出：设置/面板 RPC、`toolkit_ping`、Goal、定时任务、通知，以及卸载回调。
+   * 预期：首次启动把 options 归一化后写入存储；之后以存储里的设置为准。
+   */
+  async setup(ctx) {
+    await loadSettings(ctx.storage, ctx.options)
+
+    const roles = createSessionRoles(ctx)
+    const goalController = createGoalController(ctx.storage)
+    const tracker = createStatsTracker()
+
+    const tool = await registerPingTool(ctx)
+    const goal = await registerGoal(ctx, ctx.storage, roles, goalController)
+    const scheduling = await registerScheduling(ctx, ctx.storage, roles, async (sessionID) => {
+      const current = await goalController.getGoal(sessionID)
+      return current?.status === "active"
+    })
+
+    const rpc = await ctx.rpc.register(ToolkitRpc, {
+      settingsGet: async () => loadSettings(ctx.storage, ctx.options),
+      settingsSet: async (input) => {
+        // RPC 定义是 PortableDefinition，运行时才知道 input 形状；这里再归一化一次兜底。
+        await saveSettings(ctx.storage, normalizeSettings(input))
+        return loadSettings(ctx.storage, ctx.options)
+      },
+      panelGet: async (input) => {
+        const record = asRecord(input)
+        const requested = record?.["sessionID"]
+        const sessionID = typeof requested === "string" ? requested : ""
+
+        // 统计不落盘：每个会话第一次打开面板时，从 OpenCode 已存消息重建一次。
+        if (sessionID.length > 0 && !tracker.isSeeded(sessionID)) {
+          tracker.seed(sessionID, await buildStats(ctx, sessionID))
+        }
+
+        const current = await goalController.getGoal(sessionID)
+        const stats = tracker.get(sessionID)
+        const tools = Object.entries(stats.tools)
+          .map(([name, count]) => ({ name, count }))
+          .sort((left, right) => right.count - left.count)
+
+        return {
+          goal:
+            current === null
+              ? null
+              : {
+                  objective: current.objective,
+                  status: current.status,
+                  tokensUsed: current.tokensUsed,
+                  timeUsedSeconds: current.timeUsedSeconds,
+                  ...(current.tokenBudget === undefined ? {} : { tokenBudget: current.tokenBudget }),
+                },
+          loops: scheduling.scheduler.listLoops(sessionID).map((loop) => ({
+            id: loop.id,
+            mode: loop.mode,
+            prompt: loop.prompt,
+            ...(loop.nextFireAt === undefined ? {} : { nextFireAt: loop.nextFireAt }),
+          })),
+          jobs: scheduling.jobs.listJobs(sessionID).map((job) => ({
+            id: job.id,
+            cron: job.cron,
+            prompt: job.prompt,
+            ...(job.nextRunAt === undefined ? {} : { nextRunAt: job.nextRunAt }),
+          })),
+          stats: { ...stats, hitRate: hitRatePercent(stats.input, stats.cached), tools },
+        }
+      },
+    })
+
+    // 功能关闭或子代理会话时，请求发给模型前就把对应工具从工具表移除。
+    const hook = await ctx.session.hook("context", async (event) => {
+      const settings = await loadSettings(ctx.storage)
+      if (!settings.enabled) {
+        hideGoalTools(event.tools)
+        hideSchedulingTools(event.tools)
+        return
+      }
+      const subagent = await roles.isSubagent(event.sessionID)
+      if (subagent || !settings.goal.enabled) hideGoalTools(event.tools)
+      if (subagent || !settings.scheduling.enabled) hideSchedulingTools(event.tools)
+    })
+
+    const notifier = createNotifier({ ctx, store: ctx.storage, roles })
+
+    const toolBefore = await ctx.tool.hook("execute.before", async (input) => {
+      await notifier.handleToolBefore({ tool: input.tool, sessionID: input.sessionID })
+    })
+    const toolAfter = await ctx.tool.hook("execute.after", (input) => {
+      tracker.recordTool(input.sessionID, input.tool)
+    })
+
+    const handlers: EventHandler[] = [
+      (event) => {
+        trackEvent(tracker, event)
+        return Promise.resolve()
+      },
+      (event) => notifier.handle(event),
+      (event) => goal.handle(event),
+      (event) => scheduling.handle(event),
+    ]
+
+    const events = new AbortController()
+    void (async () => {
+      try {
+        for await (const event of ctx.event.subscribe({ signal: events.signal })) {
+          await dispatchEvent(handlers, event)
+        }
+      } catch {
+        // aborted 或连接断开：卸载时正常路径
+      }
+    })()
+
+    // 工具注册后刷新一次工具表，让当前会话的下一次请求就能看到新工具。
+    await ctx.tool.reload()
+
+    return async () => {
+      events.abort()
+      notifier.dispose()
+      tracker.clear()
+      await toolAfter.dispose()
+      await toolBefore.dispose()
+      await hook.dispose()
+      await scheduling.dispose()
+      await goal.dispose()
+      await tool.dispose()
+      await rpc.dispose()
+    }
+  },
+})

package/src/notification/format.ts

@@ -0,0 +1,42 @@
+/** 输入：文本；输出：PowerShell 单引号字符串里可安全使用的文本。 */
+export function escapePowerShellSingleQuotedText(input: string): string {
+  return input.replaceAll("'", "''")
+}
+
+/** 输入：文本；输出：AppleScript 双引号字符串里可安全使用的文本。 */
+export function escapeAppleScriptText(input: string): string {
+  return input.replaceAll("\\", "\\\\").replaceAll('"', '\\"')
+}
+
+/** 输入：文本；输出：XML 转义后的文本。 */
+export function escapeXmlText(input: string): string {
+  return input
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+}
+
+/**
+ * 输入：标题 + 正文。
+ * 输出：一行 PowerShell 脚本，弹出 Windows toast。
+ * 预期：先 XML 转义（给 toast 模板），再单引号转义（给 -Command 字符串）。
+ */
+export function buildWindowsToastScript(title: string, message: string): string {
+  const psTitle = escapePowerShellSingleQuotedText(escapeXmlText(title))
+  const psMessage = escapePowerShellSingleQuotedText(escapeXmlText(message))
+
+  return `
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+$Template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$RawXml = [xml] $Template.GetXml()
+($RawXml.toast.visual.binding.text | Where-Object {$_.id -eq '1'}).AppendChild($RawXml.CreateTextNode('${psTitle}')) | Out-Null
+($RawXml.toast.visual.binding.text | Where-Object {$_.id -eq '2'}).AppendChild($RawXml.CreateTextNode('${psMessage}')) | Out-Null
+$SerializedXml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$SerializedXml.LoadXml($RawXml.OuterXml)
+$Toast = [Windows.UI.Notifications.ToastNotification]::new($SerializedXml)
+$Notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('OpenCode')
+$Notifier.Show($Toast)
+`.trim().replaceAll("\n", "; ")
+}

package/src/notification/index.ts

@@ -0,0 +1,165 @@
+import type { Plugin } from "@opencode/plugin"
+
+import type { SessionRoles } from "../goal/session-role.ts"
+import { resolveMessages, type Messages } from "../i18n/index.ts"
+import { readEventSessionID } from "../shared/events.ts"
+import type { JsonStore } from "../shared/json.ts"
+import { loadSettings } from "../shared/settings-store.ts"
+import type { Settings } from "../shared/settings.ts"
+import { createSender, type NotificationSender } from "./send.ts"
+
+/** 通知类型。 */
+type NotificationKind = "completed" | "question" | "permission"
+
+/** 同一会话完成通知的去重窗口（idle 与 execution.succeeded 会同时到达）。 */
+const COMPLETE_DEDUPE_MS = 1000
+
+/** 预览文本上限。 */
+const PREVIEW_MAX = 200
+
+/** 通知控制器。 */
+export type Notifier = {
+  /** 输入：会话事件；输出：无。预期：完成/权限事件按设置发系统通知。 */
+  handle(event: { readonly type: string; readonly data: unknown }): Promise<void>
+  /** 输入：工具名 + 会话；输出：无。预期：`question` 工具触发提问通知。 */
+  handleToolBefore(input: { readonly tool: string; readonly sessionID: string }): Promise<void>
+  /** 输入：无；输出：无。预期：清理去重缓存。 */
+  dispose(): void
+}
+
+/** 输入：文本；输出：空白折叠成单行。 */
+function collapse(text: string): string {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(" ")
+}
+
+/** 输入：文本 + 上限；输出：截断后的文本。 */
+function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max)}...` : text
+}
+
+/**
+ * 输入：插件上下文、存储、会话角色、可选发送函数与平台。
+ * 输出：通知控制器。
+ * 预期：发送失败静默；子代理在 onlyMainSession 下不通知；完成通知带消息预览。
+ */
+export function createNotifier(args: {
+  readonly ctx: Plugin.Context
+  readonly store: JsonStore
+  readonly roles: SessionRoles
+  readonly send?: NotificationSender
+  readonly platform?: NodeJS.Platform
+  readonly now?: () => number
+}): Notifier {
+  const { ctx, store, roles } = args
+  const send = args.send ?? createSender(args.platform ?? process.platform)
+  const clock = args.now ?? Date.now
+  const lastCompleteAt = new Map<string, number>()
+
+  /** 输入：设置里的语言；输出：`resolveMessages` 需要的 locale。 */
+  const localeOf = (settings: Settings): string | undefined =>
+    settings.lang === "auto" ? undefined : settings.lang
+
+  /**
+   * 输入：会话 ID + 文案。
+   * 输出：`User: ...` / `Assistant: ...` 两行（可能为空）。
+   * 预期：取最后一条用户文本与最后一条助手文本的最后一行；读取失败返回空。
+   */
+  const buildPreview = async (sessionID: string, messages: Messages): Promise<string[]> => {
+    const history = await ctx.session.context({ sessionID }).catch(() => undefined)
+    if (history === undefined) return []
+
+    let userText = ""
+    let assistantText = ""
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+      const message = history[index]
+      if (message === undefined) continue
+      if (userText === "" && message.type === "user") userText = collapse(message.text)
+      if (assistantText === "" && message.type === "assistant") {
+        const text = message.content
+          .filter((part) => part.type === "text")
+          .map((part) => part.text)
+          .join("\n")
+        const lines = collapse(text)
+        assistantText = lines
+      }
+      if (userText !== "" && assistantText !== "") break
+    }
+
+    return [
+      userText === "" ? "" : `${messages.notification.user}: ${truncate(userText, PREVIEW_MAX)}`,
+      assistantText === "" ? "" : `${messages.notification.assistant}: ${truncate(assistantText, PREVIEW_MAX)}`,
+    ].filter(Boolean)
+  }
+
+  /** 输入：会话 + 设置 + 通知类型；输出：无。预期：标题带会话名，发送失败静默。 */
+  const notify = async (sessionID: string, settings: Settings, kind: NotificationKind): Promise<void> => {
+    const messages = resolveMessages(localeOf(settings))
+    const session = await ctx.session.get({ sessionID }).catch(() => undefined)
+    const name = session?.title?.trim() ?? ""
+    const title = name.length > 0 ? `${messages.notification.title} · ${name}` : messages.notification.title
+    const detail = kind === "completed" ? await buildPreview(sessionID, messages) : []
+    const body = [messages.notification[kind], ...detail].join("\n")
+
+    try {
+      await send(title, body)
+    } catch {
+      // 通知是尽力而为，失败不影响会话
+    }
+  }
+
+  /** 输入：会话 ID + 设置；输出：是否应通知。预期：onlyMainSession 时跳过子代理。 */
+  const allowed = async (sessionID: string, settings: Settings): Promise<boolean> => {
+    if (!settings.notification.onlyMainSession) return true
+    return !(await roles.isSubagent(sessionID))
+  }
+
+  return {
+    async handle(event) {
+      const sessionID = readEventSessionID(event)
+      if (sessionID === undefined) return
+
+      const settings = await loadSettings(store)
+      if (!settings.enabled || !settings.notification.enabled) return
+
+      if (event.type === "session.deleted") {
+        lastCompleteAt.delete(sessionID)
+        return
+      }
+
+      if (!(await allowed(sessionID, settings))) return
+
+      // idle 与 execution.succeeded 是同一轮结束的两个信号，合并成一次通知。
+      if (event.type === "session.idle" || event.type === "session.execution.succeeded") {
+        if (!settings.notification.onComplete) return
+        const at = clock()
+        const last = lastCompleteAt.get(sessionID)
+        if (last !== undefined && at - last < COMPLETE_DEDUPE_MS) return
+        lastCompleteAt.set(sessionID, at)
+        await notify(sessionID, settings, "completed")
+        return
+      }
+
+      if (event.type === "permission.asked") {
+        if (!settings.notification.onPermission) return
+        await notify(sessionID, settings, "permission")
+      }
+    },
+
+    async handleToolBefore(input) {
+      if (input.tool.toLowerCase() !== "question") return
+
+      const settings = await loadSettings(store)
+      if (!settings.enabled || !settings.notification.enabled || !settings.notification.onQuestion) return
+      if (!(await allowed(input.sessionID, settings))) return
+      await notify(input.sessionID, settings, "question")
+    },
+
+    dispose() {
+      lastCompleteAt.clear()
+    },
+  }
+}

package/src/notification/send.ts

@@ -0,0 +1,104 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+import { buildWindowsToastScript, escapeAppleScriptText } from "./format.ts"
+
+const execFileAsync = promisify(execFile)
+
+const POWERSHELL = "powershell.exe"
+const OSASCRIPT = "osascript"
+const NOTIFY_SEND = "notify-send"
+
+/** Windows toast 对长度敏感，统一截断。 */
+const TITLE_MAX = 100
+const MESSAGE_MAX = 800
+
+/** 发送函数。 */
+export type NotificationSender = (title: string, message: string) => Promise<void>
+
+/** 输入：文本 + 上限；输出：截断后的文本。 */
+function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max)}...` : text
+}
+
+/**
+ * 输入：命令名 + 该命令能快速成功退出的探测参数。
+ * 输出：可用时返回命令名，否则 `null`。
+ * 预期：结果缓存；探测超时 3 秒，不阻塞通知链路。
+ *       探测参数必须按命令区分：把 PowerShell 的 `-Command` 传给 osascript/notify-send 会必然失败，
+ *       导致这两个平台的命令被误判为不存在。
+ */
+function createCommandFinder(commandName: string, probeArgs: readonly string[]): () => Promise<string | null> {
+  let cached: string | null | undefined
+  let pending: Promise<string | null> | undefined
+
+  return async () => {
+    if (cached !== undefined) return cached
+    if (pending !== undefined) return pending
+
+    pending = (async () => {
+      try {
+        await execFileAsync(commandName, [...probeArgs], {
+          timeout: 3_000,
+          windowsHide: true,
+        })
+        cached = commandName
+      } catch {
+        cached = null
+      }
+      return cached
+    })()
+    return pending
+  }
+}
+
+const findPowerShell = createCommandFinder(POWERSHELL, ["-NoProfile", "-Command", "exit 0"])
+const findOsascript = createCommandFinder(OSASCRIPT, ["-e", "return"])
+const findNotifySend = createCommandFinder(NOTIFY_SEND, ["--help"])
+
+/** 输入：命令 + 参数；输出：无。预期：静默执行，失败由调用方忽略。 */
+async function runQuiet(command: string, args: readonly string[]): Promise<void> {
+  await execFileAsync(command, [...args], { timeout: 10_000, windowsHide: true })
+}
+
+/** 输入：标题 + 正文；输出：无。预期：没有 powershell 时静默跳过。 */
+async function sendWindows(title: string, message: string): Promise<void> {
+  const path = await findPowerShell()
+  if (path === null) return
+  const script = buildWindowsToastScript(truncate(title, TITLE_MAX), truncate(message, MESSAGE_MAX))
+  await runQuiet(path, ["-NoProfile", "-NonInteractive", "-Command", script])
+}
+
+/** 输入：标题 + 正文；输出：无。预期：没有 osascript 时静默跳过。 */
+async function sendMacos(title: string, message: string): Promise<void> {
+  const path = await findOsascript()
+  if (path === null) return
+  const safeTitle = escapeAppleScriptText(truncate(title, TITLE_MAX))
+  const safeMessage = escapeAppleScriptText(truncate(message, MESSAGE_MAX))
+  await runQuiet(path, ["-e", `display notification "${safeMessage}" with title "${safeTitle}"`])
+}
+
+/** 输入：标题 + 正文；输出：无。预期：没有 notify-send 时静默跳过。 */
+async function sendLinux(title: string, message: string): Promise<void> {
+  const path = await findNotifySend()
+  if (path === null) return
+  await runQuiet(path, [truncate(title, TITLE_MAX), truncate(message, MESSAGE_MAX)])
+}
+
+/**
+ * 输入：Node 平台字符串。
+ * 输出：该平台的发送函数。
+ * 预期：不支持的平台返回空实现，绝不抛错。
+ */
+export function createSender(platform: NodeJS.Platform): NotificationSender {
+  switch (platform) {
+    case "win32":
+      return sendWindows
+    case "darwin":
+      return sendMacos
+    case "linux":
+      return sendLinux
+    default:
+      return () => Promise.resolve()
+  }
+}