opencode-windows-scheduler 1.5.4 → 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.
- package/CHANGELOG.md +65 -5
- package/CROSS_PLATFORM.md +107 -71
- package/README.md +72 -25
- package/ROADMAP-STRATEGY.md +6 -0
- package/ROADMAP.md +116 -85
- package/dist/core/analytics.d.ts +3 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +4 -0
- package/dist/core/audit.d.ts +2 -1
- package/dist/core/audit.d.ts.map +1 -1
- package/dist/core/audit.js +32 -1
- package/dist/core/cron-to-schtasks.d.ts.map +1 -1
- package/dist/core/cron-to-schtasks.js +21 -4
- package/dist/core/file-watcher.d.ts.map +1 -1
- package/dist/core/file-watcher.js +16 -1
- package/dist/core/git-trigger.d.ts +4 -2
- package/dist/core/git-trigger.d.ts.map +1 -1
- package/dist/core/git-trigger.js +34 -16
- package/dist/core/lock.d.ts +14 -0
- package/dist/core/lock.d.ts.map +1 -1
- package/dist/core/lock.js +81 -4
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +3 -2
- package/dist/core/native-notify.d.ts.map +1 -1
- package/dist/core/native-notify.js +3 -0
- package/dist/core/one-shot.d.ts +7 -1
- package/dist/core/one-shot.d.ts.map +1 -1
- package/dist/core/one-shot.js +15 -2
- package/dist/core/permissions.d.ts +69 -0
- package/dist/core/permissions.d.ts.map +1 -0
- package/dist/core/permissions.js +143 -0
- package/dist/core/ps-wrapper.d.ts +9 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +293 -96
- package/dist/core/record-history.d.ts +11 -0
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +106 -4
- package/dist/core/savings.d.ts +70 -0
- package/dist/core/savings.d.ts.map +1 -0
- package/dist/core/savings.js +87 -0
- package/dist/core/schedule-gate.js +7 -3
- package/dist/core/schedule-v2.js +1 -1
- package/dist/core/scheduler/index.d.ts +13 -1
- package/dist/core/scheduler/index.d.ts.map +1 -1
- package/dist/core/scheduler/index.js +35 -4
- package/dist/core/scheduler/linux.d.ts +4 -1
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +53 -20
- package/dist/core/scheduler/mac.d.ts +2 -1
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +24 -6
- package/dist/core/scheduler/posix.d.ts +1 -1
- package/dist/core/scheduler/posix.d.ts.map +1 -1
- package/dist/core/scheduler/posix.js +2 -2
- package/dist/core/scheduler/registry.d.ts +3 -2
- package/dist/core/scheduler/registry.d.ts.map +1 -1
- package/dist/core/scheduler/registry.js +6 -5
- package/dist/core/scheduler/windows.d.ts +49 -1
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +219 -34
- package/dist/core/secrets.d.ts +5 -3
- package/dist/core/secrets.d.ts.map +1 -1
- package/dist/core/secrets.js +86 -8
- package/dist/core/self-analysis.d.ts +117 -0
- package/dist/core/self-analysis.d.ts.map +1 -0
- package/dist/core/self-analysis.js +539 -0
- package/dist/core/session.d.ts +11 -3
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +34 -5
- package/dist/core/shutdown.d.ts +26 -0
- package/dist/core/shutdown.d.ts.map +1 -0
- package/dist/core/shutdown.js +49 -0
- package/dist/core/summary.d.ts +69 -0
- package/dist/core/summary.d.ts.map +1 -0
- package/dist/core/summary.js +250 -0
- package/dist/core/telegram.d.ts +10 -0
- package/dist/core/telegram.d.ts.map +1 -1
- package/dist/core/telegram.js +228 -47
- package/dist/core/triage-chain.d.ts +9 -3
- package/dist/core/triage-chain.d.ts.map +1 -1
- package/dist/core/triage-chain.js +15 -5
- package/dist/core/triage-compare.d.ts +68 -0
- package/dist/core/triage-compare.d.ts.map +1 -0
- package/dist/core/triage-compare.js +184 -0
- package/dist/core/triage-rules.d.ts.map +1 -1
- package/dist/core/triage-rules.js +22 -0
- package/dist/core/triage-shadow.d.ts +54 -10
- package/dist/core/triage-shadow.d.ts.map +1 -1
- package/dist/core/triage-shadow.js +138 -26
- package/dist/core/triage-worker.d.ts +55 -0
- package/dist/core/triage-worker.d.ts.map +1 -0
- package/dist/core/triage-worker.js +314 -0
- package/dist/core/triage.js +1 -1
- package/dist/core/watch-paths.d.ts +6 -0
- package/dist/core/watch-paths.d.ts.map +1 -0
- package/dist/core/watch-paths.js +62 -0
- package/dist/core/wrappers/bash.d.ts +15 -3
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +153 -120
- package/dist/db/history-repo.d.ts +1 -1
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +29 -14
- package/dist/db/schema.d.ts +1 -1
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +31 -0
- package/dist/history.d.ts +2 -2
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +3 -3
- package/dist/i18n.d.ts +25 -2
- package/dist/i18n.d.ts.map +1 -1
- package/dist/i18n.js +41 -3
- package/dist/index.d.ts +40 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +345 -71
- package/dist/integrations.d.ts +9 -1
- package/dist/integrations.d.ts.map +1 -1
- package/dist/integrations.js +34 -6
- package/dist/notifications.d.ts +30 -2
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +287 -16
- package/dist/profiles.d.ts +1 -1
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +21 -3
- package/dist/rpc.d.ts +145 -8
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +81 -6
- package/dist/server.d.ts +20 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +136 -14
- package/dist/settings.d.ts +89 -5
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +143 -23
- package/dist/task-transfer.d.ts +8 -1
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +2 -2
- package/dist/types.d.ts +8 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +23 -5
- package/dist/workspaces.d.ts +9 -0
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +25 -0
- package/docs/ARCHITECTURE.md +40 -22
- package/docs/CONCEPT.md +230 -0
- package/docs/CROSS_PLATFORM.ru.md +150 -0
- package/docs/CROSS_PLATFORM.zh.md +146 -0
- package/docs/FAQ.md +52 -0
- package/docs/FAQ.ru.md +53 -0
- package/docs/FAQ.zh.md +43 -0
- package/docs/FEATURES.md +125 -48
- package/docs/FEATURES.zh.md +655 -0
- package/docs/LOCAL-AI.md +114 -16
- package/docs/README.ru.md +18 -13
- package/docs/README.zh.md +286 -0
- package/docs/SAVINGS.md +61 -0
- package/docs/SAVINGS.ru.md +60 -0
- package/docs/SAVINGS.zh.md +52 -0
- package/docs/ZH-LOCALE-PLAN.md +324 -0
- package/gui-experimental.cjs +8 -8
- package/locales/en.json +54 -1
- package/locales/ru.json +54 -1
- package/locales/zh.json +780 -0
- package/package.json +24 -7
- package/scripts/check-zh-locale.mjs +218 -0
- package/scripts/run-tests.mjs +236 -0
- package/scripts/test-locale.mjs +4 -3
- package/skills/scheduled-job-best-practices/SKILL.md +6 -3
- package/skills/scheduled-job-best-practices/references/recipes.md +1 -1
- package/src/core/analytics.ts +10 -0
- package/src/core/audit.ts +39 -1
- package/src/core/cron-to-schtasks.ts +23 -4
- package/src/core/file-watcher.ts +20 -1
- package/src/core/git-trigger.ts +34 -16
- package/src/core/lock.ts +88 -3
- package/src/core/matrix.ts +5 -1
- package/src/core/native-notify.ts +3 -0
- package/src/core/one-shot.ts +18 -2
- package/src/core/permissions.ts +200 -0
- package/src/core/ps-wrapper.ts +300 -96
- package/src/core/record-history.ts +111 -4
- package/src/core/savings.ts +150 -0
- package/src/core/schedule-gate.ts +9 -3
- package/src/core/schedule-v2.ts +1 -1
- package/src/core/scheduler/index.ts +41 -3
- package/src/core/scheduler/linux.ts +67 -22
- package/src/core/scheduler/mac.ts +24 -7
- package/src/core/scheduler/posix.ts +2 -2
- package/src/core/scheduler/registry.ts +7 -5
- package/src/core/scheduler/windows.ts +237 -32
- package/src/core/secrets.ts +101 -7
- package/src/core/self-analysis.ts +744 -0
- package/src/core/session.ts +40 -5
- package/src/core/shutdown.ts +69 -0
- package/src/core/summary.ts +318 -0
- package/src/core/telegram.ts +266 -55
- package/src/core/triage-chain.ts +15 -6
- package/src/core/triage-compare.ts +277 -0
- package/src/core/triage-rules.ts +23 -0
- package/src/core/triage-shadow.ts +176 -32
- package/src/core/triage-worker.ts +344 -0
- package/src/core/triage.ts +1 -1
- package/src/core/watch-paths.ts +70 -0
- package/src/core/wrappers/bash.ts +181 -138
- package/src/db/history-repo.ts +31 -18
- package/src/db/schema.ts +31 -0
- package/src/gui.tsx +5070 -4761
- package/src/history.ts +7 -3
- package/src/i18n.ts +55 -4
- package/src/index.ts +432 -74
- package/src/integrations.ts +50 -6
- package/src/notifications.ts +465 -18
- package/src/profiles.ts +21 -3
- package/src/rpc.ts +86 -6
- package/src/server.ts +135 -16
- package/src/settings.ts +305 -46
- package/src/task-transfer.ts +10 -3
- package/src/types.ts +24 -5
- package/src/workspaces.ts +22 -0
- package/dist/gui-experimental.cjs +0 -1
package/docs/LOCAL-AI.md
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
# Local assistant (triage)
|
|
2
2
|
|
|
3
|
-
The local assistant is an optional, fully offline classifier
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
never blocked.
|
|
3
|
+
The local assistant is an optional, fully offline classifier for run outcomes.
|
|
4
|
+
After a run finishes, the scheduler can ask a local model to classify the
|
|
5
|
+
outcome (quality, timeout, permission, network, unknown) and write the verdict
|
|
6
|
+
to the triage audit. It is **opt-in**: when no model is available the scheduler
|
|
7
|
+
keeps working exactly as before and notifications are never blocked.
|
|
9
8
|
|
|
10
9
|
Triage is not a scheduler feature by itself — it only affects notifications. It
|
|
11
10
|
never changes run status, retries, Quality Gates, DAG dependencies or history.
|
|
@@ -16,7 +15,7 @@ never changes run status, retries, Quality Gates, DAG dependencies or history.
|
|
|
16
15
|
run finished ──► triage chain ──► notify / skip / log-only (shadow)
|
|
17
16
|
│
|
|
18
17
|
├─ llm — local model classifies the failure
|
|
19
|
-
└─ rules
|
|
18
|
+
└─ rules - built-in patterns (timeout, permission, network, quality, cost, task)
|
|
20
19
|
```
|
|
21
20
|
|
|
22
21
|
- `off` — no triage; every notification is sent (default).
|
|
@@ -24,10 +23,70 @@ run finished ──► triage chain ──► notify / skip / log-only (shadow)
|
|
|
24
23
|
- `llm` — the configured local model only.
|
|
25
24
|
- `auto` — the model first, then the rules engine (recommended).
|
|
26
25
|
|
|
26
|
+
Rules semantics: if `rules` is omitted (`undefined`), the built-in rule set is
|
|
27
|
+
active. An explicit empty array (`rules: []`) disables the rules engine entirely.
|
|
28
|
+
A non-empty custom array replaces the built-in set; it does not extend it.
|
|
29
|
+
|
|
30
|
+
### Built-in rules
|
|
31
|
+
|
|
32
|
+
The built-in set classifies errors by text, status, cost and task name. All
|
|
33
|
+
built-in rules are notify-only: they never suppress a notification.
|
|
34
|
+
|
|
35
|
+
| Rule | Match | Severity |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| `error-timeout` | timeout / deadline in the error text | high |
|
|
38
|
+
| `error-permission` | permission denied, access denied, forbidden | high |
|
|
39
|
+
| `error-network` | connection refused/reset, DNS, network error | high |
|
|
40
|
+
| `error-quality` | Quality Gate, failed tests, failed build, lint | high |
|
|
41
|
+
| `cost-high` | `costUsd >= 1` | high |
|
|
42
|
+
| `task-important` | task name contains deploy, release, publish, production, backup, restore or migration | high |
|
|
43
|
+
| `status-error` | status is `error` | high |
|
|
44
|
+
| `status-partial` | status is `partial` | medium |
|
|
45
|
+
| `status-success` | status is `success` | low |
|
|
46
|
+
|
|
47
|
+
A custom array replaces the built-in set. For example, this configuration
|
|
48
|
+
suppresses noisy nightly runs and marks runs costing $5 or more as high:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
"notifications": {
|
|
52
|
+
"triage": {
|
|
53
|
+
"mode": "rules",
|
|
54
|
+
"rules": [
|
|
55
|
+
{ "id": "skip-nightly", "field": "task", "operator": "contains", "value": "nightly", "action": "skip", "priority": 50 },
|
|
56
|
+
{ "id": "expensive", "field": "cost", "operator": "gte", "value": 5, "severity": "high", "priority": 90 }
|
|
57
|
+
]
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
27
62
|
The result is validated against a fixed JSON schema. Invalid JSON, an
|
|
28
63
|
unreachable endpoint, a timeout or low confidence all fall back to the rules
|
|
29
|
-
engine (fail-open). With `fallback: "
|
|
30
|
-
and delivers the notification instead.
|
|
64
|
+
engine (fail-open). With `fallback: "notify"` the scheduler skips the rules step
|
|
65
|
+
and delivers the notification instead. The legacy name `"skip"` is still
|
|
66
|
+
accepted and normalized to `"notify"`.
|
|
67
|
+
|
|
68
|
+
The model only **classifies** a run: a valid verdict never suppresses a
|
|
69
|
+
notification on its own. Only a matching rule with `action: "skip"` can
|
|
70
|
+
suppress delivery. This is intentional: an uncertain small model must not be
|
|
71
|
+
able to hide a real failure.
|
|
72
|
+
|
|
73
|
+
## Delivery latency (async triage)
|
|
74
|
+
|
|
75
|
+
In `llm` and `auto` modes triage runs asynchronously. `record-history` delivers
|
|
76
|
+
the notification immediately and starts a detached worker for the model call;
|
|
77
|
+
the worker writes the verdict to `audit_log` with `async: true`. The configured
|
|
78
|
+
`timeoutMs` applies to that background request, not to delivery: a cold model
|
|
79
|
+
that takes 40 seconds cannot delay the webhook, chain triggers or the task lock.
|
|
80
|
+
|
|
81
|
+
Only `rules` mode triages synchronously, because rules are the only thing that
|
|
82
|
+
can suppress a notification. In `llm`/`auto` the model and its rules fallback
|
|
83
|
+
are advisory: the notification is already sent, so `action: "skip"` in the
|
|
84
|
+
audit means “would have been skipped”, not “was suppressed”. Use `rules` mode
|
|
85
|
+
if rules must actually suppress delivery. The GUI shows this warning when a
|
|
86
|
+
model mode is selected.
|
|
87
|
+
|
|
88
|
+
In shadow mode the worker records `shadow: true` and `suppressed: false`, so a
|
|
89
|
+
shadow report remains a safe preview of triage decisions.
|
|
31
90
|
|
|
32
91
|
## Requirements
|
|
33
92
|
|
|
@@ -46,18 +105,48 @@ ollama pull qwen3:4b
|
|
|
46
105
|
Triage settings live under `notifications.triage` and are edited from the GUI
|
|
47
106
|
side panel ("Local assistant") or through the `manage_local_ai` agent tool.
|
|
48
107
|
|
|
108
|
+
The panel shows a persistent connection status next to **Test connection**:
|
|
109
|
+
grey means "not checked", amber "checking", green "connected", red "no
|
|
110
|
+
connection" with the provider error. The test sends one synthetic
|
|
111
|
+
classification request (it is not saved) and reports the model, protocol and
|
|
112
|
+
latency. Status resets when `mode`, `baseUrl` or `model` changes, so a stale
|
|
113
|
+
green cannot hide a new endpoint. A red status never blocks notifications:
|
|
114
|
+
`llm`/`auto` triage is asynchronous and fail-open.
|
|
115
|
+
|
|
49
116
|
| Setting | Values | Default | Meaning |
|
|
50
117
|
| --- | --- | --- | --- |
|
|
51
118
|
| `mode` | `off` / `rules` / `llm` / `auto` | `off` | Triage strategy. |
|
|
52
119
|
| `baseUrl` | URL | `http://127.0.0.1:11434` | Ollama or OpenAI-compatible endpoint. |
|
|
53
120
|
| `model` | string | `""` | Model id, for example `qwen3:4b`. |
|
|
54
|
-
| `timeoutMs` | 1000..120000 | `
|
|
55
|
-
| `fallback` | `rules` / `
|
|
121
|
+
| `timeoutMs` | 1000..120000 | `60000` | Background request timeout in `llm`/`auto`; does not delay delivery. |
|
|
122
|
+
| `fallback` | `rules` / `notify` | `rules` | Behaviour when the model fails or is unsure. |
|
|
56
123
|
| `confidenceThreshold` | 0..1 | `0.6` | Minimum model confidence; below it the fallback applies. |
|
|
57
124
|
| `shadow.enabled` | boolean | `true` | Log decisions without suppressing notifications. |
|
|
58
125
|
| `shadow.days` | 1..365 | `14` | Shadow period length. |
|
|
59
126
|
| `shadow.startedAt` | ISO string / null | `null` | Start of the shadow period; `null` restarts it. |
|
|
60
127
|
|
|
128
|
+
`fallback: "skip"` is accepted as a legacy alias for `notify` and is normalized
|
|
129
|
+
on load, so old settings keep working without edits.
|
|
130
|
+
|
|
131
|
+
## Message summaries
|
|
132
|
+
|
|
133
|
+
`notifications.summary` turns a notification into at most three short lines for
|
|
134
|
+
Telegram and OS toasts. The same Ollama/OpenAI-compatible provider is used, but
|
|
135
|
+
the request is independent of triage and has its own timeout.
|
|
136
|
+
|
|
137
|
+
| Setting | Values | Default | Meaning |
|
|
138
|
+
| --- | --- | --- | --- |
|
|
139
|
+
| `summary.enabled` | boolean | `false` | Use the model summary instead of the template message. |
|
|
140
|
+
| `summary.maxLines` | 1..3 | `3` | Maximum number of lines. |
|
|
141
|
+
| `summary.maxCharsPerLine` | 20..500 | `120` | Hard cut per line. |
|
|
142
|
+
| `summary.timeoutMs` | 1000..120000 | `8000` | Summary request timeout. |
|
|
143
|
+
|
|
144
|
+
The model must answer with strict JSON `{"lines": ["...", "..."]}`. Any
|
|
145
|
+
failure — no provider, HTTP error, timeout, invalid JSON or schema — falls back
|
|
146
|
+
to a deterministic truncation: status and task name, the error text, then
|
|
147
|
+
runtime, tokens and cost. A summary never blocks or drops the notification:
|
|
148
|
+
delivery waits at most `timeoutMs`.
|
|
149
|
+
|
|
61
150
|
## Managing triage from the agent
|
|
62
151
|
|
|
63
152
|
The `manage_local_ai` tool has three actions.
|
|
@@ -76,7 +165,7 @@ Update one or more fields (merged with the current settings):
|
|
|
76
165
|
"mode": "auto",
|
|
77
166
|
"baseUrl": "http://127.0.0.1:11434",
|
|
78
167
|
"model": "qwen3:4b",
|
|
79
|
-
"timeoutMs":
|
|
168
|
+
"timeoutMs": 60000,
|
|
80
169
|
"fallback": "rules",
|
|
81
170
|
"confidenceThreshold": 0.6,
|
|
82
171
|
"shadow": { "enabled": true, "days": 14 }
|
|
@@ -152,10 +241,19 @@ with `available: false`).
|
|
|
152
241
|
|
|
153
242
|
## Shadow mode
|
|
154
243
|
|
|
155
|
-
Shadow mode is the safe way to evaluate triage. Decisions are
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
244
|
+
Shadow mode is the safe way to evaluate triage. Decisions are written to the
|
|
245
|
+
persistent audit journal (`audit_log`, action `triage.decision`), but no
|
|
246
|
+
notification is suppressed. In `llm`/`auto` the verdict arrives asynchronously
|
|
247
|
+
after delivery; in `rules` mode it is computed before delivery. Check the shadow
|
|
248
|
+
report before switching to `mode: "auto"`: it shows how many notifications
|
|
249
|
+
would have been skipped and whether any of those were false positives.
|
|
250
|
+
|
|
251
|
+
The journal survives restarts and runs in the short-lived `record-history`
|
|
252
|
+
process, unlike the old in-memory counters. Read individual decisions with
|
|
253
|
+
`get_audit_log` (`action: "triage.decision"`); the report is also available as
|
|
254
|
+
`rpc.get_shadow_report` (including the last 50 decisions). The report covers
|
|
255
|
+
the configured shadow window `[startedAt, startedAt + days]`; resetting it
|
|
256
|
+
deletes only shadow rows and keeps ordinary decision history.
|
|
159
257
|
|
|
160
258
|
Start with `mode: "auto"`, `shadow.enabled: true` and `shadow.days: 14`. After
|
|
161
259
|
the period, review the shadow report and only then disable shadow mode.
|
package/docs/README.ru.md
CHANGED
|
@@ -7,13 +7,20 @@
|
|
|
7
7
|
[](../LICENSE)
|
|
8
8
|
[](../package.json)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Translations: [English](../README.md) · [中文](README.zh.md).
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Быстрый старт
|
|
15
|
+
|
|
16
|
+
1. Установите плагин (см. [Установка](#установка)) и перезапустите OpenCode.
|
|
17
|
+
2. Попросите агента поставить первую задачу — достаточно одного вызова:
|
|
18
|
+
|
|
19
|
+
> Поставь задачу «утренний-отчёт»: каждый день в 09:00 с промптом «Просуммаризируй вчерашние git-коммиты и запиши отчёт в ~/reports/».
|
|
15
20
|
|
|
16
|
-
|
|
21
|
+
3. Откройте дашборд: агент печатает ссылку при создании задачи (по умолчанию `http://localhost:4380`), позже её можно получить инструментом `get_dashboard_info`. Посмотреть демо без установки: `node scripts/demo-dashboard.mjs` — дашборд с демо-данными на `http://localhost:4380`.
|
|
22
|
+
|
|
23
|
+

|
|
17
24
|
|
|
18
25
|
## Зачем
|
|
19
26
|
|
|
@@ -43,13 +50,13 @@ English version: [README.md](../README.md).
|
|
|
43
50
|
|
|
44
51
|
### Язык интерфейса
|
|
45
52
|
|
|
46
|
-
Интерфейс доступен на русском (по умолчанию) и
|
|
53
|
+
Интерфейс доступен на русском (по умолчанию), английском и китайском (упрощённом). Переключатель языка находится в шапке панели планировщика (🌐 Авто / Русский / English / 中文), а также доступен через инструмент `manage_settings` (`action: "update"`, `locale: "zh"`). Значение `locale: "auto"` («Авто») следует за языком интерфейса OpenCode: панель реагирует на смену языка сразу, а разрешённая локаль отправляется на сервер, чтобы уведомления, дайджест и дашборд использовали тот же язык. Переключение применяется без перезапуска. Локализация дашборда ещё не завершена: часть строк на стороне клиента пока остаётся русской. Описания и схемы инструментов агента остаются английскими, диагностика в консоли — русской.
|
|
47
54
|
|
|
48
|
-
Каталоги лежат в `locales/ru.json` и `locales/
|
|
55
|
+
Каталоги лежат в `locales/ru.json`, `locales/en.json` и `locales/zh.json`; набор ключей в них должен совпадать, иначе CI падает.
|
|
49
56
|
|
|
50
57
|
## Установка
|
|
51
58
|
|
|
52
|
-
Нужны OpenCode v2 и Node.js
|
|
59
|
+
Нужны OpenCode v2 и Node.js 22.22+.
|
|
53
60
|
|
|
54
61
|
```bash
|
|
55
62
|
opencode plugin add opencode-windows-scheduler
|
|
@@ -69,12 +76,6 @@ opencode plugin add opencode-windows-scheduler
|
|
|
69
76
|
|
|
70
77
|
`experimental.schedules: false` отключает встроенный планировщик OpenCode, чтобы агент не путал встроенные инструменты расписаний с инструментами этого плагина. После изменения конфигурации перезапустите OpenCode.
|
|
71
78
|
|
|
72
|
-
Альтернатива — глобальная установка через npm:
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
npm install -g opencode-windows-scheduler
|
|
76
|
-
```
|
|
77
|
-
|
|
78
79
|
Из исходников:
|
|
79
80
|
|
|
80
81
|
```bash
|
|
@@ -185,7 +186,7 @@ src/
|
|
|
185
186
|
npm install
|
|
186
187
|
npm run build # tsc
|
|
187
188
|
npm run build:gui # vite
|
|
188
|
-
npm test #
|
|
189
|
+
npm test # 58 сюит, 600+ проверок
|
|
189
190
|
npm run test:en # те же сюиты с английской локалью
|
|
190
191
|
```
|
|
191
192
|
|
|
@@ -196,8 +197,12 @@ npm run test:en # те же сюиты с английской локаль
|
|
|
196
197
|
## Документация
|
|
197
198
|
|
|
198
199
|
- [ARCHITECTURE.md](ARCHITECTURE.md) — модель процессов, модули, бэкенды, модель данных.
|
|
200
|
+
- [CONCEPT.md](CONCEPT.md) — north star: верифицируемая локально-первая оркестрация.
|
|
199
201
|
- [FEATURES.md](FEATURES.md) — полный каталог возможностей с примерами.
|
|
202
|
+
- [FAQ.md](FAQ.md) — сценарии восстановления и ответы по эксплуатации (English).
|
|
200
203
|
- [MIGRATION.md](MIGRATION.md) — переезд с cron, systemd, launchd или Планировщика Windows.
|
|
204
|
+
- [SAVINGS.md](SAVINGS.md) — как считается оценка «Сэкономлено $» (English).
|
|
205
|
+
- [../CROSS_PLATFORM.md](../CROSS_PLATFORM.md) — различия и бэкенды Windows / macOS / Linux.
|
|
201
206
|
|
|
202
207
|
## FAQ
|
|
203
208
|
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
# opencode-windows-scheduler
|
|
2
|
+
|
|
3
|
+
> 用于调度与编排 AI agent 任务的 OpenCode v2 插件 —— cron、一次性运行、DAG 流水线、矩阵构建、质量门禁、SQLite 历史记录和本地 Web 仪表盘。支持 Windows、macOS 和 Linux。免费开源(MIT)。
|
|
4
|
+
|
|
5
|
+
[](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/opencode-windows-scheduler)
|
|
7
|
+
[](https://www.npmjs.com/package/opencode-windows-scheduler)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](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
|
+

|
|
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)。
|
package/docs/SAVINGS.md
ADDED
|
@@ -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.
|