opencode-windows-scheduler 1.5.2 → 1.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (231) hide show
  1. package/CHANGELOG.md +107 -2
  2. package/CROSS_PLATFORM.md +107 -71
  3. package/LICENSE +21 -21
  4. package/README.md +74 -26
  5. package/ROADMAP-STRATEGY.md +11 -4
  6. package/ROADMAP.md +322 -112
  7. package/dist/core/analytics.d.ts +3 -0
  8. package/dist/core/analytics.d.ts.map +1 -1
  9. package/dist/core/analytics.js +4 -0
  10. package/dist/core/audit.d.ts +2 -1
  11. package/dist/core/audit.d.ts.map +1 -1
  12. package/dist/core/audit.js +32 -1
  13. package/dist/core/cron-to-schtasks.d.ts.map +1 -1
  14. package/dist/core/cron-to-schtasks.js +21 -4
  15. package/dist/core/file-watcher.d.ts.map +1 -1
  16. package/dist/core/file-watcher.js +16 -1
  17. package/dist/core/git-trigger.d.ts +4 -2
  18. package/dist/core/git-trigger.d.ts.map +1 -1
  19. package/dist/core/git-trigger.js +34 -16
  20. package/dist/core/local-ai.d.ts +52 -0
  21. package/dist/core/local-ai.d.ts.map +1 -0
  22. package/dist/core/local-ai.js +119 -0
  23. package/dist/core/lock.d.ts +14 -0
  24. package/dist/core/lock.d.ts.map +1 -1
  25. package/dist/core/lock.js +81 -4
  26. package/dist/core/matrix.d.ts.map +1 -1
  27. package/dist/core/matrix.js +3 -2
  28. package/dist/core/native-notify.d.ts.map +1 -1
  29. package/dist/core/native-notify.js +3 -0
  30. package/dist/core/one-shot.d.ts +7 -1
  31. package/dist/core/one-shot.d.ts.map +1 -1
  32. package/dist/core/one-shot.js +15 -2
  33. package/dist/core/permissions.d.ts +69 -0
  34. package/dist/core/permissions.d.ts.map +1 -0
  35. package/dist/core/permissions.js +143 -0
  36. package/dist/core/ps-wrapper.d.ts +9 -30
  37. package/dist/core/ps-wrapper.d.ts.map +1 -1
  38. package/dist/core/ps-wrapper.js +477 -108
  39. package/dist/core/record-history.d.ts +11 -0
  40. package/dist/core/record-history.d.ts.map +1 -1
  41. package/dist/core/record-history.js +106 -4
  42. package/dist/core/savings.d.ts +70 -0
  43. package/dist/core/savings.d.ts.map +1 -0
  44. package/dist/core/savings.js +87 -0
  45. package/dist/core/schedule-gate.js +7 -3
  46. package/dist/core/schedule-v2.js +1 -1
  47. package/dist/core/scheduler/index.d.ts +13 -1
  48. package/dist/core/scheduler/index.d.ts.map +1 -1
  49. package/dist/core/scheduler/index.js +35 -4
  50. package/dist/core/scheduler/linux.d.ts +4 -1
  51. package/dist/core/scheduler/linux.d.ts.map +1 -1
  52. package/dist/core/scheduler/linux.js +53 -20
  53. package/dist/core/scheduler/mac.d.ts +2 -1
  54. package/dist/core/scheduler/mac.d.ts.map +1 -1
  55. package/dist/core/scheduler/mac.js +24 -6
  56. package/dist/core/scheduler/posix.d.ts +1 -1
  57. package/dist/core/scheduler/posix.d.ts.map +1 -1
  58. package/dist/core/scheduler/posix.js +2 -2
  59. package/dist/core/scheduler/registry.d.ts +3 -2
  60. package/dist/core/scheduler/registry.d.ts.map +1 -1
  61. package/dist/core/scheduler/registry.js +6 -5
  62. package/dist/core/scheduler/windows.d.ts +49 -1
  63. package/dist/core/scheduler/windows.d.ts.map +1 -1
  64. package/dist/core/scheduler/windows.js +219 -34
  65. package/dist/core/secrets.d.ts +5 -3
  66. package/dist/core/secrets.d.ts.map +1 -1
  67. package/dist/core/secrets.js +86 -8
  68. package/dist/core/self-analysis.d.ts +117 -0
  69. package/dist/core/self-analysis.d.ts.map +1 -0
  70. package/dist/core/self-analysis.js +539 -0
  71. package/dist/core/session.d.ts +11 -3
  72. package/dist/core/session.d.ts.map +1 -1
  73. package/dist/core/session.js +34 -5
  74. package/dist/core/shutdown.d.ts +26 -0
  75. package/dist/core/shutdown.d.ts.map +1 -0
  76. package/dist/core/shutdown.js +49 -0
  77. package/dist/core/summary.d.ts +69 -0
  78. package/dist/core/summary.d.ts.map +1 -0
  79. package/dist/core/summary.js +250 -0
  80. package/dist/core/telegram.d.ts +10 -0
  81. package/dist/core/telegram.d.ts.map +1 -1
  82. package/dist/core/telegram.js +228 -47
  83. package/dist/core/triage-chain.d.ts +40 -0
  84. package/dist/core/triage-chain.d.ts.map +1 -0
  85. package/dist/core/triage-chain.js +80 -0
  86. package/dist/core/triage-compare.d.ts +68 -0
  87. package/dist/core/triage-compare.d.ts.map +1 -0
  88. package/dist/core/triage-compare.js +184 -0
  89. package/dist/core/triage-rules.d.ts +23 -0
  90. package/dist/core/triage-rules.d.ts.map +1 -0
  91. package/dist/core/triage-rules.js +196 -0
  92. package/dist/core/triage-shadow.d.ts +91 -0
  93. package/dist/core/triage-shadow.d.ts.map +1 -0
  94. package/dist/core/triage-shadow.js +160 -0
  95. package/dist/core/triage-worker.d.ts +55 -0
  96. package/dist/core/triage-worker.d.ts.map +1 -0
  97. package/dist/core/triage-worker.js +314 -0
  98. package/dist/core/triage.d.ts +76 -0
  99. package/dist/core/triage.d.ts.map +1 -0
  100. package/dist/core/triage.js +271 -0
  101. package/dist/core/watch-paths.d.ts +6 -0
  102. package/dist/core/watch-paths.d.ts.map +1 -0
  103. package/dist/core/watch-paths.js +62 -0
  104. package/dist/core/wrappers/bash.d.ts +15 -3
  105. package/dist/core/wrappers/bash.d.ts.map +1 -1
  106. package/dist/core/wrappers/bash.js +153 -120
  107. package/dist/db/history-repo.d.ts +1 -1
  108. package/dist/db/history-repo.d.ts.map +1 -1
  109. package/dist/db/history-repo.js +29 -14
  110. package/dist/db/schema.d.ts +1 -1
  111. package/dist/db/schema.d.ts.map +1 -1
  112. package/dist/db/schema.js +31 -0
  113. package/dist/history.d.ts +2 -2
  114. package/dist/history.d.ts.map +1 -1
  115. package/dist/history.js +3 -3
  116. package/dist/i18n.d.ts +25 -2
  117. package/dist/i18n.d.ts.map +1 -1
  118. package/dist/i18n.js +75 -10
  119. package/dist/index.d.ts +66 -3
  120. package/dist/index.d.ts.map +1 -1
  121. package/dist/index.js +527 -68
  122. package/dist/integrations.d.ts +9 -1
  123. package/dist/integrations.d.ts.map +1 -1
  124. package/dist/integrations.js +34 -6
  125. package/dist/notifications.d.ts +30 -2
  126. package/dist/notifications.d.ts.map +1 -1
  127. package/dist/notifications.js +289 -10
  128. package/dist/profiles.d.ts +1 -1
  129. package/dist/profiles.d.ts.map +1 -1
  130. package/dist/profiles.js +21 -3
  131. package/dist/rpc.d.ts +401 -5
  132. package/dist/rpc.d.ts.map +1 -1
  133. package/dist/rpc.js +138 -5
  134. package/dist/server.d.ts +20 -0
  135. package/dist/server.d.ts.map +1 -1
  136. package/dist/server.js +136 -14
  137. package/dist/settings.d.ts +167 -3
  138. package/dist/settings.d.ts.map +1 -1
  139. package/dist/settings.js +322 -3
  140. package/dist/task-transfer.d.ts +8 -1
  141. package/dist/task-transfer.d.ts.map +1 -1
  142. package/dist/task-transfer.js +2 -2
  143. package/dist/types.d.ts +8 -1
  144. package/dist/types.d.ts.map +1 -1
  145. package/dist/types.js +23 -5
  146. package/dist/workspaces.d.ts +9 -0
  147. package/dist/workspaces.d.ts.map +1 -1
  148. package/dist/workspaces.js +25 -0
  149. package/docs/ARCHITECTURE.md +48 -28
  150. package/docs/CONCEPT.md +230 -0
  151. package/docs/CROSS_PLATFORM.ru.md +150 -0
  152. package/docs/CROSS_PLATFORM.zh.md +146 -0
  153. package/docs/FAQ.md +52 -0
  154. package/docs/FAQ.ru.md +53 -0
  155. package/docs/FAQ.zh.md +43 -0
  156. package/docs/FEATURES.md +141 -44
  157. package/docs/FEATURES.zh.md +655 -0
  158. package/docs/LOCAL-AI.md +300 -0
  159. package/docs/MIGRATION.md +17 -0
  160. package/docs/README.ru.md +22 -16
  161. package/docs/README.zh.md +286 -0
  162. package/docs/SAVINGS.md +61 -0
  163. package/docs/SAVINGS.ru.md +60 -0
  164. package/docs/SAVINGS.zh.md +52 -0
  165. package/docs/ZH-LOCALE-PLAN.md +324 -0
  166. package/docs/spikes/local-model-structured-output.md +81 -0
  167. package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
  168. package/docs/spikes/ollama-qwen3-4b.json +163 -0
  169. package/gui-experimental.cjs +8 -8
  170. package/locales/en.json +85 -0
  171. package/locales/ru.json +85 -0
  172. package/locales/zh.json +780 -0
  173. package/package.json +31 -7
  174. package/scripts/bench-local.mjs +321 -0
  175. package/scripts/check-zh-locale.mjs +218 -0
  176. package/scripts/run-tests.mjs +236 -0
  177. package/scripts/spike-local-structured.mjs +182 -0
  178. package/scripts/test-locale.mjs +4 -3
  179. package/skills/scheduled-job-best-practices/SKILL.md +6 -3
  180. package/skills/scheduled-job-best-practices/references/recipes.md +40 -0
  181. package/src/core/analytics.ts +10 -0
  182. package/src/core/audit.ts +39 -1
  183. package/src/core/cron-to-schtasks.ts +23 -4
  184. package/src/core/file-watcher.ts +20 -1
  185. package/src/core/git-trigger.ts +34 -16
  186. package/src/core/local-ai.ts +173 -0
  187. package/src/core/lock.ts +88 -3
  188. package/src/core/matrix.ts +5 -1
  189. package/src/core/native-notify.ts +3 -0
  190. package/src/core/one-shot.ts +18 -2
  191. package/src/core/permissions.ts +200 -0
  192. package/src/core/ps-wrapper.ts +492 -108
  193. package/src/core/record-history.ts +111 -4
  194. package/src/core/savings.ts +150 -0
  195. package/src/core/schedule-gate.ts +9 -3
  196. package/src/core/schedule-v2.ts +1 -1
  197. package/src/core/scheduler/index.ts +41 -3
  198. package/src/core/scheduler/linux.ts +67 -22
  199. package/src/core/scheduler/mac.ts +24 -7
  200. package/src/core/scheduler/posix.ts +2 -2
  201. package/src/core/scheduler/registry.ts +7 -5
  202. package/src/core/scheduler/windows.ts +237 -32
  203. package/src/core/secrets.ts +101 -7
  204. package/src/core/self-analysis.ts +744 -0
  205. package/src/core/session.ts +40 -5
  206. package/src/core/shutdown.ts +69 -0
  207. package/src/core/summary.ts +318 -0
  208. package/src/core/telegram.ts +266 -55
  209. package/src/core/triage-chain.ts +125 -0
  210. package/src/core/triage-compare.ts +277 -0
  211. package/src/core/triage-rules.ts +238 -0
  212. package/src/core/triage-shadow.ts +240 -0
  213. package/src/core/triage-worker.ts +344 -0
  214. package/src/core/triage.ts +366 -0
  215. package/src/core/watch-paths.ts +70 -0
  216. package/src/core/wrappers/bash.ts +181 -138
  217. package/src/db/history-repo.ts +31 -18
  218. package/src/db/schema.ts +31 -0
  219. package/src/gui.tsx +551 -14
  220. package/src/history.ts +7 -3
  221. package/src/i18n.ts +87 -13
  222. package/src/index.ts +649 -71
  223. package/src/integrations.ts +50 -6
  224. package/src/notifications.ts +468 -5
  225. package/src/profiles.ts +21 -3
  226. package/src/rpc.ts +143 -5
  227. package/src/server.ts +135 -16
  228. package/src/settings.ts +582 -5
  229. package/src/task-transfer.ts +10 -3
  230. package/src/types.ts +24 -5
  231. package/src/workspaces.ts +22 -0
@@ -0,0 +1,286 @@
1
+ # opencode-windows-scheduler
2
+
3
+ > 用于调度与编排 AI agent 任务的 OpenCode v2 插件 —— cron、一次性运行、DAG 流水线、矩阵构建、质量门禁、SQLite 历史记录和本地 Web 仪表盘。支持 Windows、macOS 和 Linux。免费开源(MIT)。
4
+
5
+ [![CI](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml)
6
+ [![npm](https://img.shields.io/npm/v/opencode-windows-scheduler.svg)](https://www.npmjs.com/package/opencode-windows-scheduler)
7
+ [![npm downloads](https://img.shields.io/npm/dm/opencode-windows-scheduler.svg)](https://www.npmjs.com/package/opencode-windows-scheduler)
8
+ [![license](https://img.shields.io/npm/l/opencode-windows-scheduler.svg)](LICENSE)
9
+ [![node](https://img.shields.io/node/v/opencode-windows-scheduler.svg)](package.json)
10
+
11
+ Translations: [English](../README.md) · [Русский](README.ru.md).
12
+
13
+ ---
14
+
15
+ ## 快速开始
16
+
17
+ 1. 安装插件(见[安装](#安装))并重启 OpenCode。
18
+ 2. 让 agent 调度你的第一个任务 —— 一次调用即可:
19
+
20
+ > 创建一个名为 "morning-report" 的任务,每天 09:00 运行,提示词为:"Summarize yesterday's git commits and write the report to ~/reports/"。
21
+
22
+ 3. 打开仪表盘观察运行情况:创建任务时 agent 会打印 URL(默认 `http://localhost:4380`),之后也可以随时用 `get_dashboard_info` 工具获取。想不安装任何东西先看看效果?`node scripts/demo-dashboard.mjs` 会在 `http://localhost:4380` 启动一个演示仪表盘。
23
+
24
+ ## 为什么需要它
25
+
26
+ 大多数面向 AI agent 的调度器只是 cron 包装器:按定时器运行一段提示词,再写一个日志文件。本插件把 agent 任务视为**工作流**:
27
+
28
+ - **DAG 流水线** —— 任务等待依赖完成,并按成功/失败继续链路。
29
+ - **矩阵构建** —— 一个模板、N 个仓库,可并行或串行,带并发限制和按 workspace 覆盖的参数。
30
+ - **质量门禁** —— 只有 `npm test`(或任意命令)通过时,任务才被标记为成功。
31
+ - **可观测性** —— SQLite 历史、指标、日志和本地 Web 仪表盘。
32
+ - **无需打开 OpenCode 也能运行** —— cron 与一次性任务注册到操作系统原生调度器(Windows 任务计划程序、launchd、crontab),重启后依然有效。文件、git 和 MCP 事件触发器在插件进程内监听,因此需要 OpenCode 处于运行状态。
33
+
34
+ 一切都运行在你的机器上。没有 SaaS、没有遥测、没有账号。
35
+
36
+ ![本地 Web 仪表盘:矩阵构建、DAG 图、指标与运行历史](dashboard.png)
37
+
38
+ 不想安装 OpenCode 也想看看效果?`node scripts/demo-dashboard.mjs` 会用演示数据在 http://localhost:4380 启动仪表盘。
39
+
40
+ ## 功能
41
+
42
+ | 领域 | 你能得到什么 |
43
+ |---|---|
44
+ | 调度 | cron 表达式、通过 `runAt` / `delaySeconds` 的一次性运行、操作系统原生调度器(Windows / macOS / Linux)、IANA 时区(原生支持优先,否则按分钟轮询 + 门禁)、暂停/恢复、会话连续性(`new` / `reuse` / `last`,配合 `sessionMaxRuns` 清理) |
45
+ | 可靠性 | 锁文件防重叠、带强制终止的超时、带延迟的重试、崩溃恢复 |
46
+ | 质量 | Quality Gate 命令、before/after 钩子、按任务配置的允许/禁止工具列表 |
47
+ | 编排 | `dependsOn` DAG、`nextTaskOnSuccess` / `nextTaskOnError` 链路、矩阵扇出(并行/串行、`continue`/`stop`、并发、按 workspace 覆盖、聚合任务) |
48
+ | 触发器 | cron、一次性(`triggerType: "once"`)、git 提交(`triggerType: "git"`,分支/路径/忽略过滤)、文件变更(chokidar,支持 glob 掩码 `watchGlobs`/`watchIgnore`)、MCP 事件、入站 webhook(`POST /api/hooks/:task`,HMAC 签名) |
49
+ | 多仓库 | 带路径校验的 workspace、按 workspace 运行、围绕父任务的矩阵 |
50
+ | 可观测性 | SQLite 历史(success / error / timeout / partial / running)、指标(耗时、token、成本)、可通过 `/api/logs` 读取的 JSONL 运行日志、Prometheus `/metrics`、OTLP 导出、按任务日志、带 14 天分析的本地 Web 仪表盘、历史保留策略与 CSV/JSON 导出 |
51
+ | 运维 | dry-run 预览、JSON 导出/导入、模板、多渠道通知(webhook、Telegram、系统原生 toast)、免打扰时段、摘要、加密密钥(`${secret:NAME}`)、审计日志、设置 |
52
+ | 接口 | OpenCode GUI 面板、Web 仪表盘、25 个 agent 工具、内置 agent skill |
53
+
54
+ ### 语言
55
+
56
+ 界面提供俄语(默认)、英语和中文。语言选择器位于调度器面板顶部(🌐 自动 / Русский / English / 中文),
57
+ 也可通过 `manage_settings` 工具切换(`action: "update"`,`locale: "zh"` 等)。
58
+ `locale: "auto"`(「自动」)跟随 OpenCode 界面语言:面板会立即响应语言切换,
59
+ 并将解析后的语言发送到服务器,使通知、摘要和仪表盘保持一致。切换无需重启。
60
+ 仪表盘的本地化仍在推进:部分客户端字符串目前仍为俄语。按设计,agent 工具描述
61
+ 与 schema 保持英语,输出到控制台的诊断信息保持俄语。
62
+
63
+ 字符串目录位于 `locales/ru.json`、`locales/en.json` 和 `locales/zh.json`;
64
+ 每个键必须同时存在于三者中,否则 CI 会失败。
65
+
66
+ ## 安装
67
+
68
+ 需要 OpenCode v2 和 Node.js 22.22+(`node:sqlite` 与 chokidar 6 要求 Node.js 22.22+)。
69
+
70
+ ```bash
71
+ opencode plugin add opencode-windows-scheduler
72
+ ```
73
+
74
+ 或者手动把插件加入 `opencode.jsonc`:
75
+
76
+ ```jsonc
77
+ {
78
+ "$schema": "https://opencode.ai/config.json",
79
+ "plugins": ["opencode-windows-scheduler"],
80
+ "experimental": {
81
+ "schedules": false
82
+ }
83
+ }
84
+ ```
85
+
86
+ `experimental.schedules: false` 会关闭 OpenCode 内置调度器,避免 agent 把内置任务工具与本插件的工具混淆。修改配置后请重启 OpenCode。
87
+
88
+ 从源码安装:
89
+
90
+ ```bash
91
+ git clone https://github.com/DeadSno/opencode-windows-scheduler.git
92
+ cd opencode-windows-scheduler
93
+ npm install
94
+ npm run build && npm run build:gui
95
+ ```
96
+
97
+ ## Agent 工具
98
+
99
+ agent 可获得完整功能 —— 25 个工具,覆盖调度、流水线、运维、可观测性与管理:
100
+
101
+ | 工具 | 参数 | 作用 |
102
+ |---|---|---|
103
+ | `schedule_task` | `name`;cron 用 `schedule`,一次性用 `runAt` / `delaySeconds`;可选 `session` / `sessionMaxRuns`、`timeoutSeconds`、`model`、`priority`、`beforeScript`、`afterScript`、`qualityGate`、`dependsOn`、`retryCount`、`retryDelay`、`nextTaskOnSuccess`、`nextTaskOnError`、`triggerType`(`cron`/`file`/`git`/`mcp-event`/`once`)、`mcpEvent`、`watchPath`、`watchGlobs`、`watchIgnore`、`gitBranch`、`gitPaths`、`gitIgnore`、`gitPollSeconds`、`activeDays`、`windowPolicy`(`skip`/`postpone`/`run`)、`workingDirectory`、`workspaceId`、`allowedTools`、`deniedTools`、`legacyShell`、`matrix` | 在操作系统调度器中注册任务(cron、一次性、文件、git 或 MCP 事件触发器) |
104
+ | `list_tasks` | — | 返回任务及其 schedule、状态、下次运行、链路、workspace 和矩阵摘要 |
105
+ | `update_task` | `name` + 要修改的字段 | 部分更新;省略的字段保留原值,空值表示清空,`matrix: null` 移除矩阵 |
106
+ | `delete_task` | `name` | 删除任务(矩阵父任务会一并删除克隆和聚合器) |
107
+ | `run_task_now` | `name` | 立即运行任务(矩阵父任务会启动扇出) |
108
+ | `pause_task` | `name` | 暂停任务(矩阵父任务会暂停每个克隆) |
109
+ | `resume_task` | `name` | 恢复已暂停的任务 |
110
+ | `get_history` | `taskName?`、`status?`、`limit?` | 最近运行记录,含耗时、token、成本、模型、质量门禁与钩子 |
111
+ | `get_task_logs` | `name`、`lines?` | 运行日志尾部 |
112
+ | `dry_run` | `name?` | 模拟流水线(或全部任务):执行顺序、DAG、矩阵扇出、估算 |
113
+ | `manage_workspaces` | `action`、`id?`、`name?`、`path?`、`color?` | 多仓库 workspace:列出、添加、更新、删除 |
114
+ | `matrix_control` | `action`、`name?` | 矩阵结果、取消待运行克隆、清理孤儿、预览克隆 |
115
+ | `get_metrics` | — | 汇总的运行数、成功数与失败数 |
116
+ | `get_analytics` | `days?`、`topLimit?` | 周期报告:数量、成功率、耗时、token、成本、热门任务 |
117
+ | `manage_settings` | `action`、`maxConcurrent?`、`winterMode?`、`notifications?`、`history?` | 读取/更新全局设置(并发、通知、保留策略) |
118
+ | `manage_local_ai` | `action`(`get`/`update`/`test`)、`mode?`、`baseUrl?`、`model?`、`timeoutMs?`、`fallback?`、`confidenceThreshold?`、`shadow?` | 读取、更新或测试本地分诊助手;`test` 会发送一条合成通知并返回延迟与判定结果 |
119
+ | `manage_templates` | `action`、模板字段 | 列出、保存或删除可复用的任务模板 |
120
+ | `manage_profiles` | `action`、`name?`、`port?` | 列出、创建、切换或删除隔离的 profile |
121
+ | `transfer_tasks` | `action`、`data?` | 将所有任务导出为 JSON,或重新导入 |
122
+ | `send_notification` | `action`(`test`/`digest`)、`channel?`(`all`/`webhook`/`telegram`/`native`) | 测试通知渠道或发送摘要 |
123
+ | `get_dashboard_info` | — | 仪表盘端口/URL、平台、标题、当前 profile |
124
+ | `cleanup_history` | `retentionDays?`、`maxRecords?` | 按时间或记录上限删除旧历史 |
125
+ | `manage_secrets` | `action`、`name?`、`value?` | 创建、列出或删除用于任务 `env` 的 AES-256-GCM 加密密钥 |
126
+ | `get_audit_log` | `action?`、`target?`、`actor?`、`since?`、`until?`、`limit?` | 变更审计日志:谁、何时、通过哪个界面改了什么 |
127
+ | `emit_event` | `eventName`、`payload?` | 启动订阅该 MCP 事件的任务 |
128
+
129
+ `schedule_task` 还接受完整的矩阵配置(`workspaceIds`、`strategy`、`failureMode`、`aggregation`、`concurrency`、`overrides`、`createAggregator`)。
130
+
131
+ ## 权限
132
+
133
+ Agent 任务以 `opencode run --auto` 运行,因此其工具策略必须显式声明。全局设置 `permissions.defaultPolicy`(GUI → Settings,或 `manage_settings`)决定基线:
134
+
135
+ | 策略 | 默认允许 | 默认禁止 |
136
+ |---|---|---|
137
+ | `hybrid`(默认) | read、edit、glob、grep、subagent、skill、webfetch、websearch | shell、question |
138
+ | `secure` | read、glob、grep、skill | edit、shell、question、webfetch、websearch、subagent |
139
+ | `legacy` | 全部十个动作 | — |
140
+
141
+ `deniedTools` 始终优先。非空的 `allowedTools` 会变成 allowlist:未列出的动作一律禁止,也可以显式恢复被策略禁止的动作(例如 `shell`)。`legacyShell: true` 仅在 `hybrid` 下恢复 `shell`,用于从旧版本迁移的任务。
142
+
143
+ 被阻止的动作会以 `tool.blocked` 写入审计日志,带 `reason: "default-policy"` 和 `hint`;每次运行还会记录当前生效的策略。
144
+
145
+ 推荐做法:把 `git commit`/`push`、构建和测试放在 agent 之外,通过 `qualityGate` 或 `afterScript` 执行(包装器用 `bash -c` 运行它们),让 agent 只保留 `read`/`edit`。这样大多数任务根本不需要 `shell`。
146
+
147
+ ## Agent skill
148
+
149
+ 插件注册了内置 skill `scheduled-job-best-practices`,agent 只在相关时加载指导:cron 设计、自包含提示词、Quality Gate、矩阵并发、DAG 规则以及事故后诊断。无需手动配置 `.opencode/skills`。该 skill 附带 `references/recipes.md` —— 八个可直接复制的配置。
150
+
151
+ ## 矩阵构建
152
+
153
+ ```jsonc
154
+ {
155
+ "name": "deploy",
156
+ "schedule": "0 3 * * *",
157
+ "prompt": "Build, test and deploy",
158
+ "matrix": {
159
+ "workspaceIds": ["frontend-id", "backend-id", "mobile-id"],
160
+ "strategy": "parallel",
161
+ "failureMode": "continue",
162
+ "aggregation": "summary",
163
+ "concurrency": 2,
164
+ "createAggregator": true,
165
+ "overrides": {
166
+ "mobile-id": { "qualityGate": "npm run test:mobile" }
167
+ }
168
+ }
169
+ }
170
+ ```
171
+
172
+ 每个 workspace 会得到一个名为 `<parent>-matrix-<workspace>` 的克隆。父任务自身从不运行:它把克隆结果聚合为 `success`、`error` 或 `partial`。编辑父任务时克隆会保持同步;正在运行的克隆不会被改动。
173
+
174
+ ## GUI 与仪表盘
175
+
176
+ OpenCode 侧边栏显示任务、历史、日志、dry-run、模板、导入/导出、并发限制和矩阵分组。本地 Web 仪表盘额外提供按 workspace 的汇总、矩阵标签页、流水线视图和指标。
177
+
178
+ ```bash
179
+ npm run build:gui # produces gui-experimental.cjs
180
+ ```
181
+
182
+ ## 工作原理
183
+
184
+ ```
185
+ src/
186
+ index.ts plugin lifecycle, agent tools, RPC
187
+ gui.tsx OpenCode sidebar panel
188
+ server.ts local web dashboard
189
+ core/
190
+ scheduler/ Windows / Linux / macOS backends
191
+ matrix.ts fan-out, aggregation, sync, cancel
192
+ record-history.ts history, retries, chains, matrix continuation
193
+ dry-run.ts pipeline simulation
194
+ lock.ts no-overlap protection
195
+ file-watcher.ts chokidar triggers
196
+ telegram.ts Telegram Bot API delivery
197
+ native-notify.ts Windows Toast / macOS / Linux notifications
198
+ db/ SQLite: tasks, history, metrics, settings
199
+ task-transfer.ts export / import / validation
200
+ ```
201
+
202
+ 任务包装器在任务工作目录中运行 `opencode run`,因此项目级 MCP server 会被自动加载。
203
+
204
+ ### 登录模式(Windows)
205
+
206
+ 任务默认**仅交互式**:只有当创建任务的那个用户登录时,任务计划程序才会启动它们,并使用正常的配置文件、磁盘映射和已保存凭据。传入 `runWhenLoggedOff: true` 可在无用户登录时运行任务(`schtasks /ru SYSTEM`)。这类任务在会话 0 中运行 —— 没有用户配置文件、映射磁盘、网络共享或已保存凭据 —— 因此依赖你环境的任务可能失败;请先用 `dry_run` 测试。在 Linux 上 crontab 本来就无需登录即可运行,而 macOS 的 launchd agent 仅在用户会话内运行。
207
+
208
+ ## 开发
209
+
210
+ ```bash
211
+ npm install
212
+ npm run build # tsc
213
+ npm run build:gui # vite
214
+ npm test # 58 test suites, 600+ checks
215
+ npm run test:en # same suites with the English locale
216
+ ```
217
+
218
+ `npm run test:en` 会为每个测试套件设置 `OPENCODE_SCHEDULER_LOCALE=en`;该变量是
219
+ 服务内部钩子,不是用户设置。
220
+
221
+ 详情见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
222
+
223
+ ## 文档
224
+
225
+ - [docs/ARCHITECTURE.md](ARCHITECTURE.md) —— 进程模型、模块、后端、数据模型。
226
+ - [docs/CONCEPT.md](CONCEPT.md) —— north star:可验证的本地优先编排(俄文)。
227
+ - [docs/FEATURES.md](FEATURES.md) —— 带示例的完整功能目录。
228
+ - [docs/FAQ.md](FAQ.md) —— 恢复场景与运维问答。
229
+ - [docs/MIGRATION.md](MIGRATION.md) —— 从 cron、systemd、launchd 或任务计划程序迁移。
230
+ - [docs/SAVINGS.md](SAVINGS.md) —— "Saved $" 估算如何计算。
231
+ - [CROSS_PLATFORM.md](../CROSS_PLATFORM.md) —— Windows / macOS / Linux 的差异与后端。
232
+
233
+ ## FAQ
234
+
235
+ **OpenCode 关闭时还能运行吗?**
236
+ cron 和一次性任务可以。它们注册在操作系统原生调度器中,因此无需打开 OpenCode 窗口即可运行。
237
+
238
+ 文件(`file`)、git(`git`)和 MCP 事件(`mcp-event`)触发器由插件进程监听(chokidar / git 轮询 / MCP 事件总线),因此这些触发器需要 OpenCode 处于运行状态。
239
+
240
+ | 触发器 | 无需 OpenCode 运行? | 机制 |
241
+ |---|---|---|
242
+ | `cron` | ✅ 是 | 操作系统原生调度器(任务计划程序 / launchd / crontab) |
243
+ | `once` | ✅ 是 | 操作系统原生调度器,一次性注册 |
244
+ | `file` | ❌ 否 | 插件进程内的 chokidar 监听 |
245
+ | `git` | ❌ 否 | 插件进程内的 git 轮询 |
246
+ | `mcp-event` | ❌ 否 | 插件进程内的 MCP 事件总线 |
247
+ | `webhook`(`/api/hooks/:name`) | ❌ 否 | 插件进程内的 HTTP 服务器 |
248
+
249
+ **没人登录时任务会运行吗?**
250
+ 在 Windows 上,只有显式设置 `runWhenLoggedOff: true` 才会:任务以 `schtasks /ru SYSTEM` 注册,在会话 0 中运行,没有你的配置文件、映射磁盘或已保存凭据。默认仅交互式 —— 用户登录时任务才运行。Linux crontab 始终无需登录即可运行;macOS launchd agent 仅在用户会话内运行。
251
+
252
+ **支持哪些平台?**
253
+ Windows(任务计划程序)、macOS(launchd)和 Linux(crontab)。后端差异见 [CROSS_PLATFORM.md](../CROSS_PLATFORM.md)。
254
+
255
+ **我的数据会去哪里?**
256
+ 哪里都不去。历史、日志、指标和设置都保存在本地 SQLite 中。没有遥测、没有账号、没有云端。
257
+
258
+ **如何配置 Telegram 通知?**
259
+ 用 [@BotFather](https://t.me/BotFather) 创建机器人,复制 token,给机器人发一条消息并从 `getUpdates` 读取 `chat_id`(也可以使用群组/频道 ID)。把两者填入侧边栏面板,或用 `manage_settings` 设置 `notifications.telegram`(`enabled`、`botToken`、`chatId`,可选 `parseMode`)。若不想把密钥写进 `settings.json`,可改用 `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` 和 `OPENCODE_SCHEDULER_TELEGRAM_CHAT_ID` —— 对应字段为空时会使用环境变量。用 `send_notification` 加 `channel: "telegram"` 验证。
260
+
261
+ **桌面通知需要额外安装包吗?**
262
+ 不需要。Windows Toast(PowerShell/WinRT)、macOS 通知中心(`osascript`)和 Linux 的 `notify-send` 都是直接调用,无需 `node-notifier`。通过 `notifications.native.enabled` 启用。
263
+
264
+ **能在夜间静音通知吗?**
265
+ 可以。设置 `notifications.quietHours`(`enabled`、`from`、`to`,格式 `HH:MM`)。窗口期内成功和 `partial` 运行会被抑制,而失败和超时始终送达。
266
+
267
+ **如何保存密钥?**
268
+ 用 `manage_secrets`(或侧边栏的 **🔐 Secrets** 面板)创建加密密钥。密钥以 AES-256-GCM 保存在 `<PLUGIN_DIR>/secrets.json`,并配有密钥文件(`secrets.key`;POSIX 上权限 0600,Windows 上使用仅授予当前用户的 ACL)。在任务 `env` 中用 `${secret:NAME}` 引用 —— 值在运行时替换,并在日志、历史和审计中脱敏。
269
+
270
+ **能看到谁改了什么吗?**
271
+ 可以。审计日志(`get_audit_log` 工具、**Audit log** 面板、`GET /api/audit`)记录每一次变更 —— 任务创建/更新/删除/运行、设置、模板、profile、workspace、密钥、导入、历史清理 —— 包含操作者(mcp/gui/http)、来源、时间戳和脱敏后的详情。默认保留 90 天 / 10 000 条记录。
272
+
273
+ **它与 `experimental.schedules` 有何不同?**
274
+ 内置调度器只在 OpenCode 打开时运行任务。本插件使用操作系统原生调度器,并额外提供 DAG 流水线、矩阵构建、质量门禁、webhook 和可观测性。
275
+
276
+ **任务能在其他仓库中运行吗?**
277
+ 可以。workspace 指向项目路径,矩阵构建可同时在多个 workspace 中运行同一个模板。
278
+
279
+ ## 路线图
280
+
281
+ - [ROADMAP.md](../ROADMAP.md) —— 冲刺历史与后续计划。
282
+ - [ROADMAP-STRATEGY.md](../ROADMAP-STRATEGY.md) —— 定位与六个月规划。
283
+
284
+ ## 许可证
285
+
286
+ [MIT](../LICENSE)。
@@ -0,0 +1,61 @@
1
+ # The "Saved $" counter
2
+
3
+ The dashboard and `get_analytics` show a **"Saved"** KPI. It is an **estimate**,
4
+ not an accounting fact: the amount is labelled as an estimate and links to this
5
+ page.
6
+
7
+ Translations: [Русский](SAVINGS.ru.md) · [中文](SAVINGS.zh.md)
8
+
9
+ ## Methodology
10
+
11
+ The counterfactual is built from run history (`history` in SQLite).
12
+
13
+ 1. Records from the analysis window are taken, except unfinished ones
14
+ (`status = "running"`).
15
+ 2. A run enters the estimate when it **has tokens** (`tokens > 0`) and **has no
16
+ recorded cost** (`costUsd` empty or `0`). Usually this is a local model (Ollama)
17
+ or an already paid subscription: tokens were spent but no money was charged.
18
+ 3. For each such run a hypothetical cloud cost is computed:
19
+
20
+ ```
21
+ saved = tokens / 1000 × referenceCostPer1kTokensUsd
22
+ ```
23
+
24
+ 4. The total is summed across every run in the window and broken down by task
25
+ (top 10 by savings).
26
+
27
+ The default reference price is **$0.01 per 1k tokens** (a mix of input and output
28
+ from a mid-tier cloud provider), the constant
29
+ `CLOUD_REFERENCE_COST_PER_1K_TOKENS_USD` in `src/core/savings.ts`. Runs with a
30
+ recorded cost do not enter the savings: money was already charged for them, so
31
+ there is nothing to compare.
32
+
33
+ ## What the estimate does not account for
34
+
35
+ - prompt caching, discounts and batch pricing;
36
+ - the difference between input and output token prices;
37
+ - runs without tokens (for example a pure shell run): there may be no savings at
38
+ all;
39
+ - runs where the cost was not recorded by mistake rather than because it was zero —
40
+ such records inflate the estimate.
41
+
42
+ So the counter answers "how much would this cost in the cloud at the reference
43
+ price", not "how much money came back to the account".
44
+
45
+ ## API
46
+
47
+ `get_analytics` returns `report.savings`:
48
+
49
+ | Field | Value |
50
+ | --- | --- |
51
+ | `kind` | always `estimate` |
52
+ | `savedUsd` | estimated savings, USD |
53
+ | `runs` | runs in the counterfactual |
54
+ | `tokens` | tokens in those runs |
55
+ | `actualCostUsd` | recorded cost of the same runs (usually 0) |
56
+ | `totalCostUsd` | recorded cost of all runs in the window |
57
+ | `referenceCostPer1kTokensUsd` | reference price |
58
+ | `methodologyUrl` | link to this page |
59
+ | `byTask` | breakdown `{ taskName, runs, tokens, savedUsd }` |
60
+
61
+ The methodology is verified against fixed data: `test-savings.mjs`, 14 checks.
@@ -0,0 +1,60 @@
1
+ # Счётчик «сэкономлено $»
2
+
3
+ Дашборд и `get_analytics` показывают KPI **«Сэкономлено»**. Это **оценка**, а не
4
+ бухгалтерский факт: рядом с суммой стоит пометка «оценка» и ссылка на эту
5
+ страницу.
6
+
7
+ Translations: [English](SAVINGS.md) · [中文](SAVINGS.zh.md)
8
+
9
+ ## Methodology
10
+
11
+ Контрфактика строится по истории запусков (`history` в SQLite).
12
+
13
+ 1. Берутся записи окна анализа, кроме незавершённых (`status = "running"`).
14
+ 2. В оценку попадает запуск, у которого **есть токены** (`tokens > 0`) и
15
+ **не записана стоимость** (`costUsd` пустой или `0`). Обычно это локальная
16
+ модель (Ollama) или уже оплаченная подписка: токены потрачены, но деньги за
17
+ них не списаны.
18
+ 3. Для каждого такого запуска считается гипотетическая облачная стоимость:
19
+
20
+ ```
21
+ saved = tokens / 1000 × referenceCostPer1kTokensUsd
22
+ ```
23
+
24
+ 4. Сумма складывается по всем запускам окна и разбивается по задачам
25
+ (топ-10 по экономии).
26
+
27
+ Эталонная цена по умолчанию — **$0.01 за 1k токенов** (смесь входа и выхода
28
+ облачного провайдера среднего класса), константа
29
+ `CLOUD_REFERENCE_COST_PER_1K_TOKENS_USD` в `src/core/savings.ts`. Запуски с
30
+ записанной стоимостью в экономию не попадают: за них деньги уже списаны, и
31
+ сравнивать нечего.
32
+
33
+ ## Что оценка не учитывает
34
+
35
+ - кеш промптов, скидки и пакетные тарифы;
36
+ - разницу цен входных и выходных токенов;
37
+ - запуски без токенов (например, чистый shell): экономии там может и не быть;
38
+ - запуски, где стоимость не записана по ошибке, а не потому что она нулевая —
39
+ такие записи завышают оценку.
40
+
41
+ Поэтому счётчик отвечает на вопрос «сколько бы это стоило в облаке по
42
+ эталонной цене», а не «сколько денег вернулось на счёт».
43
+
44
+ ## API
45
+
46
+ `get_analytics` возвращает `report.savings`:
47
+
48
+ | Поле | Значение |
49
+ | --- | --- |
50
+ | `kind` | всегда `estimate` |
51
+ | `savedUsd` | оценка экономии, USD |
52
+ | `runs` | запусков в контрфактике |
53
+ | `tokens` | токенов в этих запусках |
54
+ | `actualCostUsd` | записанная стоимость этих же запусков (обычно 0) |
55
+ | `totalCostUsd` | записанная стоимость всех запусков окна |
56
+ | `referenceCostPer1kTokensUsd` | эталонная цена |
57
+ | `methodologyUrl` | ссылка на эту страницу |
58
+ | `byTask` | разбивка `{ taskName, runs, tokens, savedUsd }` |
59
+
60
+ Методика проверяется на фиксированных данных: `test-savings.mjs`, 14 проверок.
@@ -0,0 +1,52 @@
1
+ # 「节省 $」计数器
2
+
3
+ 仪表盘和 `get_analytics` 会显示 **「节省」** KPI。它是**估算**,不是账务事实:
4
+ 金额会标注为估算并链接到本页。
5
+
6
+ Translations: [English](SAVINGS.md) · [Русский](SAVINGS.ru.md)
7
+
8
+ ## 方法
9
+
10
+ 反事实估算基于运行历史(SQLite 中的 `history`)。
11
+
12
+ 1. 取分析窗口内的记录,排除未完成的运行(`status = "running"`)。
13
+ 2. 当一次运行**有 token**(`tokens > 0`)且**没有记录成本**(`costUsd` 为空或 `0`)时,
14
+ 它进入估算。通常是本地模型(Ollama)或已付费订阅:消耗了 token 但未扣费。
15
+ 3. 对每次这样的运行计算假设的云端成本:
16
+
17
+ ```
18
+ saved = tokens / 1000 × referenceCostPer1kTokensUsd
19
+ ```
20
+
21
+ 4. 在窗口内对所有运行求和,并按任务拆分(按节省额取前 10)。
22
+
23
+ 默认参考价格为 **每 1k token $0.01**(中端云厂商输入/输出混合价),即
24
+ `src/core/savings.ts` 中的常量 `CLOUD_REFERENCE_COST_PER_1K_TOKENS_USD`。
25
+ 有记录成本的运行不计入节省:已经扣过费,没什么可对比的。
26
+
27
+ ## 估算未考虑的因素
28
+
29
+ - 提示词缓存、折扣和批量定价;
30
+ - 输入与输出 token 的价格差异;
31
+ - 没有 token 的运行(例如纯 shell 运行):可能根本没有节省;
32
+ - 成本因错误而未记录(而非因为为零)的运行——这类记录会虚增估算。
33
+
34
+ 因此该计数器回答的是「按参考价格在云端要花多少钱」,而不是「实际退回了多少钱」。
35
+
36
+ ## API
37
+
38
+ `get_analytics` 返回 `report.savings`:
39
+
40
+ | 字段 | 值 |
41
+ | --- | --- |
42
+ | `kind` | 始终为 `estimate` |
43
+ | `savedUsd` | 估算节省额,USD |
44
+ | `runs` | 反事实中的运行数 |
45
+ | `tokens` | 这些运行的 token 数 |
46
+ | `actualCostUsd` | 这些运行记录的成本(通常为 0) |
47
+ | `totalCostUsd` | 窗口内所有运行记录的成本 |
48
+ | `referenceCostPer1kTokensUsd` | 参考价格 |
49
+ | `methodologyUrl` | 指向本页的链接 |
50
+ | `byTask` | 拆分 `{ taskName, runs, tokens, savedUsd }` |
51
+
52
+ 该方法在固定数据上验证:`test-savings.mjs`,14 项检查。