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,655 @@
1
+ # 功能
2
+
3
+ Translations: [English](FEATURES.md).
4
+
5
+ 调度器全部能力的完整目录,附带示例以及实践中真正要紧的注意事项。
6
+
7
+ - [调度](#调度)
8
+ - [执行策略](#执行策略)
9
+ - [编排](#编排)
10
+ - [多仓库工作区](#多仓库工作区)
11
+ - [配置档案(多项目)](#配置档案多项目sprint-21)
12
+ - [工作区环境变量](#工作区环境变量sprint-21)
13
+ - [可观测性](#可观测性)
14
+ - [管理](#管理)
15
+ - [Agent 接口](#agent-接口)
16
+ - [平台支持](#平台支持)
17
+ - [限制与非目标](#限制与非目标)
18
+
19
+ ## 调度
20
+
21
+ ### Cron 计划
22
+
23
+ 五字段 cron:`minute hour day-of-month month day-of-week`。每个字段都支持列表、范围与步进(`0 8-10,18 * * 1-5/2`)、月份和星期名称(`0 9 * * MON-FRI`)、`@every` 语法糖(`@every 15m`、`@every 2h`、`@every 1d`)、表示当月最后一天的 `L`,以及 `d#n` 第 n 个星期几的形式(`0 9 * * FRI#3`)。
24
+
25
+ | 模式 | 示例 | 含义 |
26
+ | --- | --- | --- |
27
+ | 每 N 分钟 | `*/15 * * * *` | 每 15 分钟 |
28
+ | 固定时间 | `0 9 * * *` | 每天 09:00 |
29
+ | 工作日 | `30 8 * * 1-5` | 周一至周五 08:30 |
30
+ | 每月 | `0 3 1 * *` | 1 日 03:00 |
31
+ | 最后一天 | `0 3 L * *` | 当月最后一日 03:00 |
32
+ | 第 N 个星期几 | `0 9 * * FRI#3` | 第三个周五 09:00 |
33
+ | 语法糖 | `@every 15m` | 每 15 分钟 |
34
+
35
+ Windows 后端会把简单的 cron 表达式转换为原生任务计划程序触发器。`schtasks` 无法表达的表达式(`L`、`#`、复杂列表),以及时区不同于系统时区的任务,都以轮询模式注册:操作系统任务每分钟唤醒一次包装器,由 `schedule-gate` 决定 agent 是否运行。
36
+
37
+ ### 一次性运行
38
+
39
+ `triggerType: "once"` 让任务在某一特定时刻恰好运行一次。可以使用 `runAt`(ISO-8601,或本地日期字符串如 `2026-11-13 22:40`)或 `delaySeconds`(从现在起的延迟):
40
+
41
+ ```json
42
+ {
43
+ "name": "deploy-once",
44
+ "triggerType": "once",
45
+ "runAt": "2026-11-13T22:40:00+03:00",
46
+ "prompt": "Deploy the current main branch."
47
+ }
48
+ ```
49
+
50
+ ```json
51
+ { "name": "remind-later", "triggerType": "once", "delaySeconds": 3600, "prompt": "..." }
52
+ ```
53
+
54
+ 两者同时存在时以 `runAt` 为准。`schedule` 被忽略。一次性任务以原生方式注册(`schtasks /sc ONCE`、Linux `at`、macOS launchd 清理代理),插件重启后不会重复运行,而且无法与
55
+
56
+ > **Windows 区域设置说明。** `schtasks /sd` 只接受当前 Windows 区域设置格式的日期。
57
+ > 插件生成 `DD.MM.YYYY`,与俄语(以及大多数欧洲)区域设置匹配。在英语/美式区域
58
+ > 设置(`MM/DD/YYYY`)的系统上 `schtasks` 会拒绝该日期,因此那里无法使用一次性
59
+ > 任务。
60
+ 矩阵(matrix)组合。
61
+
62
+ ### 会话连续性
63
+
64
+ 每次计划运行既可以选择开启全新的 OpenCode 会话(`new`,默认),也可以复用存储在任务上的持久会话,或继续最近一次会话(`last`,对应 `opencode --continue`)。在任务上设置 `session`;对于 `reuse`,会自动生成 `sessionId` 并随任务定义一起存储——它永远不会从用户输入接收,也不会以明文导出。
65
+
66
+ ```json
67
+ {
68
+ "name": "nightly-analyst",
69
+ "schedule": "0 3 * * *",
70
+ "session": "reuse",
71
+ "sessionMaxRuns": 10,
72
+ "prompt": "Refresh the analysis."
73
+ }
74
+ ```
75
+
76
+ - `session`:`new`(默认)、`reuse`(传入 `--session <id>`)、`last`(传入 `--continue`)。
77
+ - `sessionMaxRuns`(仅用于 `reuse`):复用的会话在被删除(`opencode session delete`)并
78
+ 启动新会话之前可以存活多少次运行。未设置/0 表示不限制。
79
+ - `sessionId` 按机器/配置档案独立存在。内部运行计数器
80
+ (`sessionRunCount`)永不导出。
81
+ - 不带会话字段的旧导出/导入文件会以 `new` 导入。
82
+
83
+ ### 时区与启动窗口
84
+
85
+ - `timezone` — 每个任务的 IANA 时区(例如 `Europe/Moscow`)。`nextRun`/`prevRun`、
86
+ 试运行的下次运行预估以及闸门都在该时区内计算 cron;夏令时切换会被处理
87
+ (春季跳变中不存在的时间会被跳过)。
88
+ - `notBefore` / `notAfter` — 以 `HH:MM` 表示的每日启动窗口(可以跨午夜,
89
+ 例如 `22:00`–`06:00`)。在窗口之外触发的运行会被**推迟**
90
+ 到窗口开启之时(通过延迟文件,推迟一次),而不是被跳过。
91
+ - `activeDays` — 允许的星期 `0`=周日 … `6`=周六(Sprint 27)。留空或
92
+ 七天全选表示每天。适用于 cron 和事件触发器。
93
+ - `windowPolicy` — 窗口之外或在不允许的日子的行为(Sprint 27):
94
+ `postpone`(默认)等待下一个开启时机(最多 12 小时),`skip` 丢弃
95
+ 该次运行,`run` 照常执行。
96
+ - `pausedUntil` — 将任务暂停到某一 ISO 时刻。`pause_task` 接受
97
+ `until`;插件在启动时和一个 5 分钟定时器上自动重新启用任务,
98
+ 而 `resume_task` 可以提前恢复。
99
+
100
+ ### 文件触发器
101
+
102
+ ```json
103
+ {
104
+ "name": "regen-api-client",
105
+ "triggerType": "file",
106
+ "watchPath": "C:\\projects\\api\\openapi.yaml",
107
+ "prompt": "Regenerate the API client from openapi.yaml and run contract tests."
108
+ }
109
+ ```
110
+
111
+ 文件由插件宿主中的 chokidar 监视,变更会被去抖处理。文件触发器忽略 `schedule`。
112
+
113
+ #### 文件触发器的 Glob 掩码(Sprint 27)
114
+
115
+ `watchGlobs` 和 `watchIgnore` 限制哪些变更算作触发器:
116
+
117
+ 掩码支持 `*`(不跨 `/`)、`**`(任意段,包括零段)、
118
+ `?`(单个字符)、`[abc]` / `[a-z]`(字符类)、`{a,b}`(备选)以及 `!`
119
+ (取反)。空的 `watchGlobs` 表示“任何变更”。路径被规范化为 POSIX
120
+ 形式(`\` → `/`),在 Windows 上比较不区分大小写。
121
+
122
+ ### Git 触发器(Sprint 27)
123
+
124
+ ```json
125
+ {
126
+ "name": "deploy-on-push",
127
+ "triggerType": "git",
128
+ "workingDirectory": "C:\\projects\\api",
129
+ "gitBranch": "main, release/*",
130
+ "gitPaths": ["src/**", "package.json"],
131
+ "gitIgnore": ["**/*.md", "CHANGELOG.md"],
132
+ "gitPollSeconds": 60,
133
+ "prompt": "Deploy the changed services to staging."
134
+ }
135
+ ```
136
+
137
+ 带有 `triggerType: "git"` 的任务会在其工作目录中出现新提交时启动。第一次轮询只记住当前的 `HEAD`(基线),不会启动任何东西。之后的轮询比较 `git diff --name-only <last>..HEAD`,当掩码 `gitPaths`(为空——任意文件)匹配且未被 `gitIgnore` 排除时启动任务。过滤器 `gitBranch` 限制分支(逗号分隔,支持 `*` 和 `?`)。
138
+
139
+ 轮询周期 `gitPollSeconds` — 最小 5 秒,默认 60。状态(最近一次处理的提交)存储在 SQLite 表 `git_state` 中,因此插件重启不会导致重复运行。
140
+
141
+ ### MCP 事件触发器
142
+
143
+ ```json
144
+ {
145
+ "name": "on-pr-opened",
146
+ "triggerType": "mcp-event",
147
+ "mcpEvent": { "server": "github", "event": "pull_request.opened", "filter": "repo=acme/api" },
148
+ "prompt": "Review the newly opened pull request."
149
+ }
150
+ ```
151
+
152
+ 事件通过 `emit_event` RPC 方法发出。
153
+
154
+ ### 手动运行与暂停
155
+
156
+ - `run_task_now` 立即启动任务,走同一个包装器(超时、锁、
157
+ 钩子、Quality Gate)。
158
+ - `pause_task` / `resume_task` 禁用并重新启用操作系统条目。对于矩阵父任务,
159
+ 每个克隆都会被暂停。
160
+
161
+ ### 登录模式(Windows)
162
+
163
+ 默认情况下任务**仅以交互方式运行**:任务计划程序只在创建它的用户已登录时运行它。这是安全的默认值——作业可以看到用户配置文件、映射驱动器、项目的 `opencode.json` 和已保存的凭据。
164
+
165
+ 有些作业必须在工作时间之外、或在已锁定/已注销的机器上运行。传入 `runWhenLoggedOff: true`(agent 工具 `schedule_task` / `update_task`,或侧边栏)即可改为以 `schtasks /ru SYSTEM` 注册任务。这样运行发生在会话 0 中,没有用户的配置文件、映射驱动器、网络共享或已保存的凭据。依赖用户环境的任务可能以 `Access is denied` 或文件缺失而失败,因此请先用 `dry_run` 检查,并优先使用绝对路径。
166
+
167
+ `runWhenLoggedOff` 仅限 Windows:Linux crontab 本来就在没有已登录用户的情况下运行,而 macOS launchd 代理只在用户会话内运行。`list_tasks` 会同时报告操作系统值(`logonMode`)和插件设置(`runWhenLoggedOff`);`dry_run` 在任务注册之前显示同样的两项。
168
+
169
+ ## 执行策略
170
+
171
+ ### 超时与不重叠
172
+
173
+ 每次运行都有 `timeoutSeconds`(默认 3600)。超时后进程树会被停止,该次运行记录为 `timeout`。锁文件防止同一任务的两次运行重叠;第二次启动会立即退出并记录为 `skipped`。
174
+
175
+ ### 前置检查、Quality Gate、后置检查
176
+
177
+ ```json
178
+ {
179
+ "name": "nightly-deps",
180
+ "schedule": "0 2 * * *",
181
+ "beforeScript": "git pull --ff-only",
182
+ "prompt": "Update dependencies, fix breaking changes, keep the diff minimal.",
183
+ "qualityGate": "npm test",
184
+ "afterScript": "git push",
185
+ "timeoutSeconds": 2400
186
+ }
187
+ ```
188
+
189
+ | 钩子 | 时机 | 非零退出的后果 |
190
+ | --- | --- | --- |
191
+ | `beforeScript` | agent 启动之前 | 运行被取消,前置检查标记为失败 |
192
+ | `qualityGate` | 成功响应之后 | 运行被标记为 Quality Gate 失败(error) |
193
+ | `afterScript` | 运行之后,即使失败也执行 | 记入历史,不会把成功改写掉 |
194
+
195
+ ### 重试
196
+
197
+ `retryCount` 和 `retryDelay`(秒)用于重试失败的运行。重试状态被持久化,因此崩溃不会造成无限重试循环。重试先于链式后续任务和依赖者发生。
198
+
199
+ ### 模型与优先级
200
+
201
+ `model` 选择一个 OpenCode 模型(例如 `anthropic/claude-3-5-sonnet`);
202
+ 省略它则使用 OpenCode 的默认值。`priority` 取值 `0..10`,并透传给
203
+ 调度器条目。
204
+
205
+ ### 工具限制
206
+
207
+ 基线来自 `permissions.defaultPolicy`:`hybrid`(默认)允许
208
+ read/edit/glob/grep/subagent/skill/webfetch/websearch 并拒绝 `shell` 和 `question`,
209
+ `secure` 只允许 read/glob/grep/skill,而 `legacy` 恢复 1.5.x 允许一切的行为。任务级
210
+ `legacyShell: true` 会在 `hybrid` 下为从旧版本迁移来的作业重新启用 `shell`;
211
+ `legacy` 是粗放的替代方案。
212
+
213
+ `allowedTools` 和 `deniedTools` 对任务包装器启动的 `opencode run` 进程
214
+ 强制生效。包装器通过 `OPENCODE_CONFIG_CONTENT` 把生成的 `permissions` 规则
215
+ 传给该进程;不会向任务工作目录写入任何文件,因此项目级
216
+ `opencode.jsonc` 永远不会被覆盖。每个 `deniedTools` 条目都会变成对应
217
+ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置)
218
+ 会拒绝所有未列出的动作。包装器以 `--auto` 运行 `opencode`,所以
219
+ 只有未被拒绝的权限会被自动批准。限制作用于 agent 进程,
220
+ 而不作用于钩子、Quality Gate 或脚本——它们仍以你的用户权限运行。精确的动作映射和已知限制(项目/系统配置、
221
+ 嵌套子代理)见
222
+ [ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)。
223
+
224
+ ## 编排
225
+
226
+ ### 链式调度
227
+
228
+ ```json
229
+ { "name": "build", "nextTaskOnSuccess": "deploy", "nextTaskOnError": "notify-failure" }
230
+ ```
231
+
232
+ 一次运行结束后恰好启动一个后续任务。
233
+
234
+ ### DAG 依赖
235
+
236
+ ```json
237
+ { "name": "smoke-tests", "dependsOn": ["deploy"], "schedule": "0 * * * *" }
238
+ ```
239
+
240
+ 只有当每个依赖的最近一次运行成功时,依赖者才会启动。如果某个依赖是矩阵,则**所有克隆**都必须成功——处于 `partial` 的矩阵会阻塞依赖者。
241
+
242
+ ### 矩阵构建(扇出)
243
+
244
+ 一份定义,每个工作区一个克隆:
245
+
246
+ ```json
247
+ {
248
+ "name": "deploy",
249
+ "schedule": "0 3 * * *",
250
+ "prompt": "Build, test and deploy this repository. Report what changed.",
251
+ "matrix": {
252
+ "workspaceIds": ["ws-frontend", "ws-backend", "ws-mobile"],
253
+ "strategy": "parallel",
254
+ "failureMode": "continue",
255
+ "concurrency": 2,
256
+ "overrides": {
257
+ "ws-mobile": { "qualityGate": "flutter test", "prompt": "Use the Flutter toolchain." }
258
+ }
259
+ }
260
+ }
261
+ ```
262
+
263
+ | 字段 | 默认值 | 含义 |
264
+ | --- | --- | --- |
265
+ | `strategy` | `parallel` | `sequential` 只有在前一个克隆结束后才启动下一个 |
266
+ | `failureMode` | `continue` | `stop` 在第一次失败后中止其余克隆 |
267
+ | `concurrency` | 无限制 | 同时运行的最大克隆数(`sequential` 时被忽略) |
268
+ | `aggregation` | `summary` | `summary` 为父任务写入一条聚合记录 |
269
+ | `createAggregator` | `false` | 同时创建依赖每个克隆的 `<parent>-matrix-complete` |
270
+ | `overrides` | 无 | 按工作区的 prompt/模型/Quality Gate/钩子 |
271
+
272
+ 值得了解的行为:
273
+
274
+ - 克隆命名为 `<parent>-matrix-<workspace>`,继承父定义并拥有
275
+ 自己的工作目录。
276
+ - 父任务从不自己运行;它的状态是聚合值:`success`、`error`、
277
+ `partial`(在 `continue` 下部分克隆失败)或 `running`。
278
+ - 编辑父任务(工作区、prompt、覆盖、并发)会**同步**克隆
279
+ 集合:缺失的克隆被创建,发生变化的被更新,被移除的被删除。正在
280
+ 运行作业的克隆永远不会被改动。
281
+ - 取消矩阵(`matrix_control`,`action: "cancel"`)会把待运行的克隆
282
+ 标记为已取消并停止正在运行的克隆。删除父任务会删除它的整个家族。
283
+ - `matrix_control` 的 `action: "cleanup"` 会移除父任务已不存在的孤立
284
+ 克隆;同样的清理也会在插件启动时运行。
285
+
286
+ ## 多仓库工作区
287
+
288
+ 工作区是一个命名目录:id、name、path、可选的 git 远程仓库和颜色。
289
+
290
+ ```json
291
+ { "id": "ws-api", "name": "API", "path": "C:\\projects\\api", "color": "#3b82f6" }
292
+ ```
293
+
294
+ 在工作区中运行任务时使用 `workspaceId` 代替 `workingDirectory`。路径在
295
+ 添加/更新/导入时会被校验,仪表板按工作区分组任务和运行记录。
296
+ 工作区是矩阵构建扇出的单位。
297
+
298
+ ## 配置档案(多项目,Sprint 21)
299
+
300
+ 配置档案让你在一个插件内运行多套相互独立的调度器安装,每套都有
301
+ 自己的 SQLite 数据库、设置、日志、包装器和仪表板端口。这对于
302
+ 分隔项目、客户或环境(例如 `default` 和 `work`)很有用,
303
+ 使它们彼此看不到对方的数据。
304
+
305
+ - 配置档案 `default` 使用插件的基础目录(无需迁移,行为与
306
+ Sprint 21 之前完全一致)。命名配置档案位于 `<base>/profiles/<name>`。
307
+ - 配置档案选择顺序:`OPENCODE_SCHEDULER_PROFILE` 环境变量 → 基础目录中的
308
+ `active-profile` 文件 → `default`。切换配置档案会写入标记文件,并且需要
309
+ 重启 OpenCode,因为插件目录在模块加载时解析。
310
+ - 每个配置档案的仪表板端口:`OPENCODE_SCHEDULER_PORT` 环境变量 → 来自
311
+ `profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。
312
+ - RPC:`get_profiles` 列出配置档案及其目录、端口和活动标志;
313
+ `set_profile` 切换活动配置档案(会提示重启);`create_profile` /
314
+ `delete_profile` 管理命名配置档案(`default` 不能被删除)。
315
+
316
+ ### 工作区环境变量(Sprint 21)
317
+
318
+ 每个工作区都可以携带环境变量,它们会被注入到该工作区中的每次任务运行:
319
+
320
+ - `env` — 显式的 `KEY=VALUE` 对,以 JSON 形式存储在 SQLite 中;
321
+ - `envFile` — 可选的 `.env` 文件路径,其变量先被加载,随后
322
+ 显式对覆盖它们;
323
+ - 文件格式:`KEY=value` 行、`#` 注释、空行、行首 `export `、
324
+ 成对引号包裹的值会去掉引号;
325
+ - 键名校验:`^[A-Za-z_][A-Za-z0-9_]*$`,每个工作区最多 100 对;
326
+ - 传递:在任务创建/更新时,插件把真实值写入
327
+ `<PLUGIN_DIR>/env/<sanitized>.env`(POSIX 上权限 `0600`)并传给
328
+ 包装器(Windows:`-EnvFile "<path>"`;POSIX:在调用
329
+ `opencode run` 之前执行 `set -a; . "$ENV_FILE"; set +a`);
330
+ - 密钥遮蔽:匹配 `/(TOKEN|SECRET|PASS|PASSWORD|KEY|CREDENTIAL|AUTH)/i`
331
+ 的键在日志和被遮蔽的 API 响应中显示为 `***`——值永远不会泄漏进日志。
332
+
333
+ ## 可观测性
334
+
335
+ ### 历史记录
336
+
337
+ 每次运行都会变成一行记录:状态、开始/结束、时长、错误、token、成本、模型、
338
+ 前置/后置检查结果、下一个链式任务、工作区和工具限制。状态:
339
+
340
+ | 状态 | 含义 |
341
+ | --- | --- |
342
+ | `running` | 已开始,未结束 |
343
+ | `success` | 已结束,无 Quality Gate 失败 |
344
+ | `error` | agent 错误、钩子失败或 Quality Gate 失败 |
345
+ | `timeout` | 被超时终止 |
346
+ | `partial` | 既有成功也有失败的矩阵聚合 |
347
+
348
+ ### 指标
349
+
350
+ 按任务的计数器和总计:运行次数、成功、错误、token、成本。可通过
351
+ `get_history`、RPC 层和仪表板头部获取。14 天分析切片——
352
+ 按天分桶(UTC)、成功率、基于 token 的成本估算、按成本排名的热门任务、
353
+ 矩阵和模型细分——可通过 `get_analytics` /
354
+ `GET /api/analytics` 以及仪表板的 **Analytics for the period** 区块获取。
355
+ 历史记录会自动清理(按时间和大小限制,见设置),并可导出为
356
+ CSV/JSON(`GET /api/history/export`),或导出为用于 OpenTelemetry 的
357
+ OTLP/JSON(`GET /api/history/export?format=otlp`)。
358
+
359
+ 同一数据切片还带有一个 **"Saved"** 计数器:花费了 token 但
360
+ 没有记录成本的运行(本地模型、预付套餐)按每 1k token $0.01 的
361
+ 参考云价格计价。该 KPI 标注为估算值,并链接到
362
+ [docs/SAVINGS.md](SAVINGS.md) 的完整方法说明;`report.savings` 暴露
363
+ `savedUsd`、`runs`、`tokens` 以及按任务的细分。
364
+
365
+ ### Prometheus
366
+
367
+ `GET /metrics` 暴露 Prometheus 文本格式(0.0.4):`opencode_scheduler_info`、
368
+ `up`、`queue_depth`、`history_records`、`runs_total{task,status}`、
369
+ `errors_total{task}`、`tokens_total{task}`、`cost_usd_total{task}` 以及
370
+ `run_duration_seconds` 直方图(1 s … 3600 s + `+Inf`)。`runs_total` 有
371
+ 独立的 `success`、`error` 和 `partial` 状态;`errors_total` 只统计
372
+ 错误和超时,因此 `partial` 永远不会把它抬高。数值在抓取时从
373
+ SQLite 读取,因此不需要额外的 agent 或导出器进程。
374
+
375
+ ### 结构化日志
376
+
377
+ 每次运行的开始/结束以及每次 webhook 决策都会追加到
378
+ `<PLUGIN_DIR>/logs/runs.jsonl`(每行一个 JSON 对象,达到 10 MiB 轮转为
379
+ `runs.jsonl.1`)。`GET /api/logs` 返回最新在前的记录,支持 `task`、
380
+ `status`、`event`、`since`、`until`、`limit` 和 `format=jsonl`。数据库
381
+ `history` 表仍是聚合的事实来源;JSONL 用于日志
382
+ 外送和调试,写入失败时从不阻塞运行。
383
+
384
+ ### 传入 webhook
385
+
386
+ `POST /api/hooks/:task?token=…` 可以从 GitHub Actions、GitLab CI 或任何
387
+ 外部系统启动任务。请求必须在 `X-Scheduler-Signature: sha256=<hex>` 中携带
388
+ 原始正文的 HMAC-SHA256(GitHub 的 `X-Hub-Signature-256` 和裸
389
+ 十六进制摘要也被接受)。令牌也可以来自 `X-Scheduler-Token`
390
+ 或 `X-Gitlab-Token`。可选的 `X-Scheduler-Timestamp` 会对照
391
+ `timestampToleranceSeconds` 校验。钩子默认禁用;用空凭据启用它们时会自动生成令牌和密钥。错误:401(坏的
392
+ 令牌/签名/时间戳)、403(通道已禁用或缺少凭据)、404
393
+ (未知任务)、413(正文超过 `maxBodyBytes`)。仪表板仍然只绑定
394
+ localhost,因此外部 CI 需要隧道或自托管运行器。
395
+
396
+ #### 面向发送方的重放保护指引
397
+
398
+ 剩下的两种认证模式在传输层都是可重放的,因此
399
+ 选择发送方式时应当考虑到这一点:
400
+
401
+ - **`timestampToleranceSeconds = 0` 的签名(legacy)。** HMAC 只覆盖
402
+ 正文,因此任何被截获的请求都可以原样重放,永远有效。
403
+ 设置非零容差并发送 `X-Scheduler-Timestamp`(unix 秒或
404
+ 毫秒):这样签名就覆盖 `<timestamp>.<body>`,被捕获的
405
+ 请求在窗口之外便会失效。
406
+ - **仅令牌模式。** 查询参数或请求头中的 Bearer 令牌同样
407
+ 可以被重放——调度器无法区分正常的重复与重放。如果你
408
+ 无法切换到带时间戳签名的 HMAC,请改为采取缓解措施:把令牌保存在
409
+ CI 密钥中(不要写进代码),定期轮换它,为每个任务限定一个令牌,并
410
+ 让目标任务保持幂等,使意外的重放不造成危害。
411
+ - **GitHub Actions。** GitHub 自身不会发送 `X-Scheduler-Timestamp`,因此
412
+ 仅凭 `X-Hub-Signature-256` 运行在 legacy(可重放)模式。建议
413
+ 使用用共享密钥对 `<timestamp>.<body>` 签名的工作流步骤,或依赖
414
+ 短生命周期的工作流运行和幂等任务。
415
+ - 调度器本身不执行重放缓存:唯一请求去重
416
+ (例如事件 ID)是发送方的责任。
417
+
418
+ ### OpenTelemetry
419
+
420
+ 历史可以导出为 OTLP/JSON:每次运行一个 span,确定性的 32 位十六进制
421
+ `traceId` 和 16 位十六进制 `spanId`、纳秒时间戳、task/status/duration/tokens/
422
+ cost/model/error 属性以及 OK/ERROR 状态。输出可以提交到
423
+ OpenTelemetry Collector,也可以直接查看。
424
+
425
+ ### 日志
426
+
427
+ 每次运行都追加到 `logs/<task>.log`——前置/后置钩子、Quality Gate 输出以及
428
+ agent 的 stdout/stderr。`get_task_logs` 返回末尾(1–1000 行)。
429
+
430
+ ### 试运行
431
+
432
+ `dry_run` 模拟一个任务或所有任务:执行顺序、DAG 前置条件、矩阵
433
+ 扇出和预估时间。不执行任何东西,也不创建任何东西。
434
+
435
+ ### 仪表板
436
+
437
+ 本地 Web 仪表板展示任务、矩阵标签页、按工作区的汇总、DAG 标记、
438
+ 指标、14 天分析区块(KPI、每日柱状图、按成本排名的热门任务、矩阵)、
439
+ 最近运行以及 CSV/JSON 历史导出。它绑定 localhost 且没有认证
440
+ ——不要对外暴露它。`GET /api/health` 报告插件版本、调度器后端、队列
441
+ 深度和数据库状态,供外部监控使用。
442
+
443
+ ## 管理
444
+
445
+ ### 模板
446
+
447
+ 把定义保存为可复用的模板,然后一键或一次工具调用即可从中创建任务。
448
+
449
+ ### 导出与导入
450
+
451
+ `export_tasks` 生成带版本的 JSON 文档,包含定义,以及矩阵
452
+ 配置和 `matrixParentId`。`import_tasks` 校验每条记录并逐条
453
+ 报告错误,而不是让整批失败。未知工作区和无效的
454
+ 矩阵组合会被明确拒绝。
455
+
456
+ ### 通知
457
+
458
+ 运行完成时通过三个相互独立的通道发送通知——webhook、Telegram
459
+ 以及原生 OS 通知——可在设置中配置,并可用
460
+ `test_notification` 测试。
461
+
462
+ - **Webhook 投递:** 每个任务完成(成功/错误/超时)通过与
463
+ Discord/Slack 兼容的 webhook(`{ content, text }`)。`webhook.timeoutMs`
464
+ (默认 10 000)、`webhook.retryCount`(默认 2)和 `webhook.retryDelayMs`
465
+ (默认 1000)控制请求;网络错误、超时、HTTP 5xx 和 429 会
466
+ 以指数退避重试(上限 30 s),其他 4xx 不重试。
467
+ - **Telegram:** Bot API `sendMessage`,带 `chat_id`、`parse_mode`(`HTML`、
468
+ `MarkdownV2`、`Markdown` 或纯文本)、可选静默模式、论坛主题
469
+ (`messageThreadId`)和仪表板链接(`includeDashboardLink`)。在
470
+ GUI 中或用 `manage_settings` → `notifications.telegram` 配置。`botToken` 和 `chatId`
471
+ 也可以来自 `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` 和
472
+ `OPENCODE_SCHEDULER_TELEGRAM_CHAT_ID`,这样 `settings.json` 中就不存储任何密钥;
473
+ 令牌在每条错误消息和日志行中都被遮蔽。
474
+ - **原生 OS 通知:** Windows Toast(PowerShell/WinRT)、macOS 通知
475
+ 中心(`osascript`)和 Linux `notify-send`。没有额外依赖:不需要
476
+ `node-notifier`。`notifications.native.sound` 在支持的地方开关声音。
477
+ - **模板:** `templates.success` 和 `templates.error` 接受占位符
478
+ `{task}`、`{status}`、`{duration}`、`{error}`、`{emoji}`、`{cost}` 和 `{tokens}`。
479
+ 当存在 token/成本数据时,消息会加上 ` · 1500 tok · $0.0060` 后缀。
480
+ - **过滤:** `filters.include` / `filters.exclude` 是带 `*`
481
+ 通配符的任务名模式;空的 include 列表表示所有任务,exclude 优先。
482
+ - **免打扰时段:** `quietHours.enabled`,`from`/`to` 为 `HH:MM`(支持跨夜
483
+ 区间,例如 22:00 → 08:00)。在该窗口内 `success` 和
484
+ `partial` 被抑制,而 `error` 和 `timeout` 仍会投递。
485
+ - **去重(31.2):** `notifications.dedup.enabled` 把 `windowMinutes`
486
+ (默认 60)内相同任务 + 状态的通知分组。启用
487
+ `suppressDuplicates` 时,非重要的重复会被抑制;`importantStatuses`
488
+ (默认 `error`、`timeout`)中列出的状态始终投递,并带有本地化的重复
489
+ 后缀,例如 `(repeat 3)`。计数器存放在 SQLite 的 `notification_dedup`
490
+ 表中,因此能挺过短生命周期的 `record-history` 进程,并且
491
+ `maxCount` 对计数器封顶。
492
+ - **矩阵通知:** 在整个家族完成时——成功、`partial`(`onPartial`)
493
+ 以及所有克隆都失败(`onAllFailed`)。卡住检测器会报告运行
494
+ 超过 `matrix.stuckAfterMinutes`(默认 60,`0` 表示禁用)的克隆,每次运行报告一次。
495
+ - **摘要:** `digest.enabled` 发送每日(`frequency: "daily"`,在 `digest.time`)
496
+ 或每周(周一,之后补发)汇总:运行次数、成功率、成本、token
497
+ 和主要错误,通过每个已启用的通道发送。也可通过
498
+ `send_digest` RPC 和 GUI 的 **Send digest now** 按钮使用(手动
499
+ 发送不会移动计划)。
500
+ - **测试按钮:** 向 `all`、`webhook`、`telegram` 或 `native`
501
+ 发送测试消息,并报告每个通道的成功/失败。一个通道的
502
+ 失败从不阻塞其他通道,也从不抛入任务运行。
503
+
504
+ ### Secrets(Sprint 26)
505
+
506
+ 加密的密钥存储位于 `<PLUGIN_DIR>/secrets.json`,使用 AES-256-GCM 和
507
+ 32 字节密钥文件 `secrets.key`(POSIX 上权限 0600;Windows 上是一个仅授予
508
+ 当前用户的 ACL,通过 `icacls` 应用)。`manage_secrets` 工具(以及 **Secrets**
509
+ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
510
+ `[A-Za-z0-9_.-]`,最长 64 个字符;列表只显示名称、遮蔽预览
511
+ (`••••` + 后 4 位)和更新时间——从不显示值。
512
+
513
+ 在任务工作区的 `env` 中,用 `${secret:NAME}` 引用密钥。值在
514
+ 运行时被替换(缺失的密钥解析为空字符串,并给出仅含
515
+ 名称的警告)。密钥引用不会被遮蔽——它们在 GUI 环境变量
516
+ 编辑器中按原样显示——而字面的类密钥值(`TOKEN=`、`PASSWORD=`、…)
517
+ 在日志、结构化日志、历史和审计中被遮蔽为 `***`。
518
+
519
+ #### 恢复被隔离的密钥存储
520
+
521
+ 如果 `secrets.json` 解析失败,它会被隔离,而不是被删除:文件被
522
+ 重命名为原文件旁边的 `secrets.json.corrupt-<timestamp>`。这是
523
+ 读取操作的副作用——恢复是**设计上手动进行**的,以确保没有任何
524
+ 自动重写能够破坏数据:
525
+
526
+ 1. 在插件目录中找到被隔离的文件:`secrets.json.corrupt-*`
527
+ (Windows:`%APPDATA%\opencode\windows-scheduler\`,macOS/Linux:
528
+ `~/.config/opencode/windows-scheduler/` 或 `$XDG_CONFIG_HOME`)。
529
+ 2. 检查它:损坏通常是被截断的 JSON(写入中断)或
530
+ 手工编辑。在文本编辑器中修正 JSON 语法。
531
+ 3. 把修好的文件复制回 `secrets.json`(保留 `.corrupt-*` 副本作为
532
+ 备份),并用 `manage_secrets`(`action: "list"`)验证。
533
+ 4. 如果文件无法修复,用 `manage_secrets`
534
+ (`action: "set"`)重新设置密钥;用已丢失的 `secrets.key` 加密的值无法
535
+ 恢复——请重新输入它们。
536
+ 5. 在更罕见的连重命名都失败的情况下,写入保持阻塞
537
+ (`corruptedStore` 被置位),直到手动清除 `.corrupt-*` 路径——
538
+ 自己把损坏的文件移走,然后重新设置密钥。
539
+
540
+ ### 审计日志(Sprint 26)
541
+
542
+ 每一次变更——任务创建/更新/删除/运行、设置、模板、配置档案、
543
+ 工作区、密钥、导入、历史清理——都会记录在 SQLite 的 `audit_log`
544
+ 表中,包含动作、目标类型/目标、操作者(`mcp`/`gui`/`http`)、
545
+ 来源、脱敏详情和远程地址。`ts` 和 `action` 上建有索引;
546
+ 保留期默认为 90 天 / 10 000 条记录,并自动清理。
547
+
548
+ `get_audit_log` 工具(以及 **Audit log** GUI 面板)按
549
+ `action`、`target`、`actor`、`since`/`until` 和 `limit` 过滤读取日志。也可
550
+ 通过 RPC `get_audit` 和 HTTP `GET /api/audit` 获取。详情中的
551
+ 密钥值会被脱敏;`${secret:NAME}` 引用按原样保留。
552
+
553
+ ### 崩溃恢复
554
+
555
+ 崩溃后仍停留在 `running` 的运行会在下次插件启动时标记为
556
+ `error`,因此时间线从不说谎。孤立的矩阵克隆也会在启动时清理。
557
+
558
+ ### 设置
559
+
560
+ 全局默认值(超时、并发、通知、历史保留)存放在
561
+ `settings.json` 中,可从 GUI/RPC 层编辑。历史保留使
562
+ 原始运行日志保持有界:`history.retentionDays`(默认 30)和 `history.maxRecords`
563
+ (默认 5000);`0` 表示禁用相应限制。清理在插件启动时每天最多运行一次,记录
564
+ `lastCleanupAt` / `lastCleanupDeleted`,也可通过 `cleanup_history` RPC 和 GUI 的 **Clear now** 按钮使用。`metrics.json` 中的
565
+ 聚合不受保留期影响。
566
+
567
+ ## Agent 接口
568
+
569
+ 二十五个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
570
+ `run_task_now`、`pause_task`、`resume_task`、`get_history`、`get_task_logs`、`dry_run`、
571
+ `manage_workspaces`、`matrix_control`(results/cancel/cleanup/preview)、`get_metrics`、
572
+ `get_analytics`、`manage_settings`、`manage_local_ai`、`manage_templates`、`manage_profiles`、
573
+ `transfer_tasks`、`send_notification`、`get_dashboard_info`、`cleanup_history`、
574
+ `manage_secrets`、`get_audit_log`、
575
+ `emit_event`。
576
+
577
+ 捆绑的 skill `scheduled-job-best-practices` 教会 agent 安全的默认做法:
578
+ 最小权限、Quality Gate、超时、矩阵并发、DAG 规则以及
579
+ 创建 → 试运行 → 立即运行 → 检查 的循环。它由插件
580
+ 自动注册,无需安装步骤。
581
+
582
+ `manage_local_ai` 工具读取、更新并测试本地分诊设置
583
+ (`action: "get" | "update" | "test"`);见 [LOCAL-AI.md](LOCAL-AI.md)。
584
+
585
+ ## 本地助手(分诊)
586
+
587
+ 一个可选的离线模型对失败和 partial 的运行进行分类(类别、严重程度、
588
+ 置信度、原因)。模型从不自行抑制通知:只有
589
+ 带 `action: "skip"` 的匹配规则引擎规则才能做到。它是选择加入且
590
+ 失败开放的:没有模型时由规则引擎或直接投递接管,
591
+ 通知永远不会因模型不可用而被阻塞。
592
+ 它从不改变运行状态、重试、Quality Gate、DAG 依赖或历史。
593
+
594
+ - `mode`:`off`(默认)、`rules`、`llm` 或 `auto`(先模型,后规则)。
595
+ - `fallback`:模型失败或不确定时用 `rules`(默认)或 `notify`。
596
+ 旧值 `skip` 作为 `notify` 的别名被接受。
597
+ - `confidenceThreshold`:模型的最低置信度(0..1)。
598
+ - 省略 `rules` 表示使用内置规则;`rules: []` 禁用它们;自定义
599
+ 数组会替换内置规则集。
600
+ - 内置规则覆盖错误、状态、成本和任务名
601
+ (deploy/release/backup/migration);全部仅用于通知。示例见
602
+ [LOCAL-AI.md](LOCAL-AI.md)。
603
+ - GUI 显示彩色的连接状态(未检查 / 检查中 /
604
+ 已连接 / 无连接),并在模式、URL 或模型变化时重置它。
605
+ - 在 `llm`/`auto` 下,分诊是异步的:通知立即
606
+ 投递,一个分离的工作者把结论写入审计。只有
607
+ `rules` 模式在投递前分诊,因为只有规则能够抑制。
608
+ - `notifications.embedding` 在精确去重之上增加语义去重:
609
+ 消息被转换为归一化的词袋向量存入 SQLite,
610
+ 在窗口内按余弦相似度比较,超过
611
+ `threshold`(默认 0.85)时被抑制。重要状态
612
+ 永远不会被抑制。不需要新依赖,也不需要外部
613
+ 嵌入模型。
614
+ - `notifications.summary` 为 Telegram 和
615
+ toast 最多渲染三行短文本。模型返回严格的 JSON
616
+ `{"lines": [...]}`;任何失败都会回退到确定性截断(状态、
617
+ 错误、运行时长/token/成本),投递最多等待
618
+ `summary.timeoutMs`(默认 8 s)。
619
+ - 影子模式把决策记录到持久审计日志
620
+ (`get_audit_log`,动作 `triage.decision`)而不抑制通知,
621
+ 因此可以在强制执行之前安全地评估分诊效果,且报告
622
+ 能在重启后保留。
623
+
624
+ 设置、按内存划分的模型层级、`npm run bench:local` 基准测试、
625
+ 影子工作流和故障排查(包括 `OLLAMA_CONTEXT_LENGTH`)都记录在
626
+ [LOCAL-AI.md](LOCAL-AI.md)。
627
+
628
+ ## 平台支持
629
+
630
+ | 能力 | Windows | Linux | macOS |
631
+ | --- | --- | --- | --- |
632
+ | Cron 调度 | Task Scheduler | crontab | launchd |
633
+ | 回退 | — | — | crontab |
634
+ | 超时与锁 | PowerShell 包装器 | bash 包装器 | bash 包装器 |
635
+ | 文件触发器 | chokidar | chokidar | chokidar |
636
+ | 历史、指标、仪表板 | 是 | 是 | 是 |
637
+ | Agent 工具与 skill | 是 | 是 | 是 |
638
+ | 无已登录用户运行 | 选择加入(`runWhenLoggedOff`) | 总是(crontab) | 否(按用户代理) |
639
+
640
+ ## 限制与非目标
641
+
642
+ - **没有 `triggerType: "once"` 就没有一次性调度。** 一次性运行通过
643
+ `runAt`/`delaySeconds` 实现;要立即运行请使用 `run_task_now`。
644
+ - **没有超出内置 `session` 模式的会话连续性。** `new`、`reuse`
645
+ 和 `last` 覆盖常见场景;不支持按消息分叉/分支会话。
646
+ - **没有沙箱。** 钩子、Quality Gate 和 prompt 都以你的用户权限运行。
647
+ - **仪表板没有认证。** 设计上仅限 localhost。
648
+ - **密钥不加密。** 请使用环境变量或外部密钥
649
+ 管理器。
650
+ - **`allowedTools` / `deniedTools` 限制的是 agent 进程,而不是整个作业。**
651
+ 钩子、Quality Gate 和包装器脚本仍以你的用户权限运行,而且项目级
652
+ 或系统级 `opencode.jsonc` 可以削弱任务范围的拒绝规则。见
653
+ ARCHITECTURE.md 中的权限强制限制。
654
+ - **矩阵克隆是独立的任务。** 它们出现在任务列表中(归组在父任务
655
+ 下),并像任何其他运行一样消耗全局并发槽位。