agent-steward 0.0.1 → 0.0.3
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 +399 -0
- package/CROSS_PLATFORM.md +151 -0
- package/README.md +307 -15
- package/ROADMAP-STRATEGY.md +196 -0
- package/ROADMAP.md +184 -0
- package/dist/core/analytics.d.ts +132 -0
- package/dist/core/analytics.d.ts.map +1 -0
- package/dist/core/analytics.js +290 -0
- package/dist/core/audit.d.ts +96 -0
- package/dist/core/audit.d.ts.map +1 -0
- package/dist/core/audit.js +297 -0
- package/dist/core/cron-to-schtasks.d.ts +12 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -0
- package/dist/core/cron-to-schtasks.js +175 -0
- package/dist/core/dry-run.d.ts +102 -0
- package/dist/core/dry-run.d.ts.map +1 -0
- package/dist/core/dry-run.js +447 -0
- package/dist/core/file-watcher.d.ts +31 -0
- package/dist/core/file-watcher.d.ts.map +1 -0
- package/dist/core/file-watcher.js +186 -0
- package/dist/core/git-trigger.d.ts +82 -0
- package/dist/core/git-trigger.d.ts.map +1 -0
- package/dist/core/git-trigger.js +312 -0
- package/dist/core/glob.d.ts +38 -0
- package/dist/core/glob.d.ts.map +1 -0
- package/dist/core/glob.js +233 -0
- package/dist/core/local-ai.d.ts +52 -0
- package/dist/core/local-ai.d.ts.map +1 -0
- package/dist/core/local-ai.js +119 -0
- package/dist/core/lock.d.ts +57 -0
- package/dist/core/lock.d.ts.map +1 -0
- package/dist/core/lock.js +193 -0
- package/dist/core/matrix.d.ts +167 -0
- package/dist/core/matrix.d.ts.map +1 -0
- package/dist/core/matrix.js +724 -0
- package/dist/core/native-notify.d.ts +36 -0
- package/dist/core/native-notify.d.ts.map +1 -0
- package/dist/core/native-notify.js +113 -0
- package/dist/core/one-shot.d.ts +90 -0
- package/dist/core/one-shot.d.ts.map +1 -0
- package/dist/core/one-shot.js +182 -0
- package/dist/core/otel.d.ts +4 -0
- package/dist/core/otel.d.ts.map +1 -0
- package/dist/core/otel.js +98 -0
- 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/prometheus.d.ts +23 -0
- package/dist/core/prometheus.d.ts.map +1 -0
- package/dist/core/prometheus.js +146 -0
- package/dist/core/ps-wrapper.d.ts +73 -0
- package/dist/core/ps-wrapper.d.ts.map +1 -0
- package/dist/core/ps-wrapper.js +1091 -0
- package/dist/core/record-history.d.ts +25 -0
- package/dist/core/record-history.d.ts.map +1 -0
- package/dist/core/record-history.js +471 -0
- package/dist/core/retention.d.ts +29 -0
- package/dist/core/retention.d.ts.map +1 -0
- package/dist/core/retention.js +98 -0
- 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.d.ts +2 -0
- package/dist/core/schedule-gate.d.ts.map +1 -0
- package/dist/core/schedule-gate.js +211 -0
- package/dist/core/schedule-v2.d.ts +116 -0
- package/dist/core/schedule-v2.d.ts.map +1 -0
- package/dist/core/schedule-v2.js +586 -0
- package/dist/core/scheduler/at-fallback.d.ts +42 -0
- package/dist/core/scheduler/at-fallback.d.ts.map +1 -0
- package/dist/core/scheduler/at-fallback.js +70 -0
- package/dist/core/scheduler/index.d.ts +32 -0
- package/dist/core/scheduler/index.d.ts.map +1 -0
- package/dist/core/scheduler/index.js +63 -0
- package/dist/core/scheduler/linux.d.ts +46 -0
- package/dist/core/scheduler/linux.d.ts.map +1 -0
- package/dist/core/scheduler/linux.js +261 -0
- package/dist/core/scheduler/logs.d.ts +11 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -0
- package/dist/core/scheduler/logs.js +34 -0
- package/dist/core/scheduler/mac.d.ts +46 -0
- package/dist/core/scheduler/mac.d.ts.map +1 -0
- package/dist/core/scheduler/mac.js +256 -0
- package/dist/core/scheduler/posix.d.ts +40 -0
- package/dist/core/scheduler/posix.d.ts.map +1 -0
- package/dist/core/scheduler/posix.js +100 -0
- package/dist/core/scheduler/registry.d.ts +43 -0
- package/dist/core/scheduler/registry.d.ts.map +1 -0
- package/dist/core/scheduler/registry.js +57 -0
- package/dist/core/scheduler/types.d.ts +86 -0
- package/dist/core/scheduler/types.d.ts.map +1 -0
- package/dist/core/scheduler/types.js +1 -0
- package/dist/core/scheduler/windows.d.ts +112 -0
- package/dist/core/scheduler/windows.d.ts.map +1 -0
- package/dist/core/scheduler/windows.js +749 -0
- package/dist/core/secrets.d.ts +66 -0
- package/dist/core/secrets.d.ts.map +1 -0
- package/dist/core/secrets.js +433 -0
- 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 +42 -0
- package/dist/core/session.d.ts.map +1 -0
- package/dist/core/session.js +134 -0
- 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/structured-log.d.ts +84 -0
- package/dist/core/structured-log.d.ts.map +1 -0
- package/dist/core/structured-log.js +146 -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 +55 -0
- package/dist/core/telegram.d.ts.map +1 -0
- package/dist/core/telegram.js +344 -0
- package/dist/core/triage-chain.d.ts +40 -0
- package/dist/core/triage-chain.d.ts.map +1 -0
- package/dist/core/triage-chain.js +80 -0
- 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 +23 -0
- package/dist/core/triage-rules.d.ts.map +1 -0
- package/dist/core/triage-rules.js +196 -0
- package/dist/core/triage-shadow.d.ts +91 -0
- package/dist/core/triage-shadow.d.ts.map +1 -0
- package/dist/core/triage-shadow.js +160 -0
- 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.d.ts +76 -0
- package/dist/core/triage.d.ts.map +1 -0
- package/dist/core/triage.js +271 -0
- 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 +95 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -0
- package/dist/core/wrappers/bash.js +413 -0
- package/dist/db/git-state-repo.d.ts +16 -0
- package/dist/db/git-state-repo.d.ts.map +1 -0
- package/dist/db/git-state-repo.js +38 -0
- package/dist/db/history-repo.d.ts +110 -0
- package/dist/db/history-repo.d.ts.map +1 -0
- package/dist/db/history-repo.js +300 -0
- package/dist/db/index.d.ts +49 -0
- package/dist/db/index.d.ts.map +1 -0
- package/dist/db/index.js +128 -0
- package/dist/db/metrics-repo.d.ts +46 -0
- package/dist/db/metrics-repo.d.ts.map +1 -0
- package/dist/db/metrics-repo.js +103 -0
- package/dist/db/migrate.d.ts +24 -0
- package/dist/db/migrate.d.ts.map +1 -0
- package/dist/db/migrate.js +244 -0
- package/dist/db/recovery.d.ts +11 -0
- package/dist/db/recovery.d.ts.map +1 -0
- package/dist/db/recovery.js +38 -0
- package/dist/db/run-journal.d.ts +60 -0
- package/dist/db/run-journal.d.ts.map +1 -0
- package/dist/db/run-journal.js +143 -0
- package/dist/db/run-resume.d.ts +48 -0
- package/dist/db/run-resume.d.ts.map +1 -0
- package/dist/db/run-resume.js +137 -0
- package/dist/db/runs-repo.d.ts +120 -0
- package/dist/db/runs-repo.d.ts.map +1 -0
- package/dist/db/runs-repo.js +319 -0
- package/dist/db/schema.d.ts +38 -0
- package/dist/db/schema.d.ts.map +1 -0
- package/dist/db/schema.js +325 -0
- package/dist/db/settings-repo.d.ts +8 -0
- package/dist/db/settings-repo.d.ts.map +1 -0
- package/dist/db/settings-repo.js +27 -0
- package/dist/db/tasks-repo.d.ts +26 -0
- package/dist/db/tasks-repo.d.ts.map +1 -0
- package/dist/db/tasks-repo.js +120 -0
- package/dist/db/templates-repo.d.ts +17 -0
- package/dist/db/templates-repo.d.ts.map +1 -0
- package/dist/db/templates-repo.js +57 -0
- package/dist/history.d.ts +60 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +70 -0
- package/dist/i18n.d.ts +75 -0
- package/dist/i18n.d.ts.map +1 -0
- package/dist/i18n.js +357 -0
- package/dist/index.d.ts +858 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5209 -0
- package/dist/integrations.d.ts +72 -0
- package/dist/integrations.d.ts.map +1 -0
- package/dist/integrations.js +233 -0
- package/dist/notifications.d.ts +199 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +967 -0
- package/dist/profiles.d.ts +64 -0
- package/dist/profiles.d.ts.map +1 -0
- package/dist/profiles.js +305 -0
- package/dist/rpc.d.ts +3915 -0
- package/dist/rpc.d.ts.map +1 -0
- package/dist/rpc.js +1596 -0
- package/dist/schtasks.d.ts +32 -0
- package/dist/schtasks.d.ts.map +1 -0
- package/dist/schtasks.js +45 -0
- package/dist/server.d.ts +128 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +2414 -0
- package/dist/settings.d.ts +389 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/settings.js +770 -0
- package/dist/shared/jobs-view.d.ts +59 -0
- package/dist/shared/jobs-view.d.ts.map +1 -0
- package/dist/shared/jobs-view.js +146 -0
- package/dist/skill.d.ts +15 -0
- package/dist/skill.d.ts.map +1 -0
- package/dist/skill.js +93 -0
- package/dist/task-transfer.d.ts +252 -0
- package/dist/task-transfer.d.ts.map +1 -0
- package/dist/task-transfer.js +632 -0
- package/dist/templates.d.ts +57 -0
- package/dist/templates.d.ts.map +1 -0
- package/dist/templates.js +16 -0
- package/dist/types.d.ts +112 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +158 -0
- package/dist/version.d.ts +8 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +27 -0
- package/dist/workspaces.d.ts +113 -0
- package/dist/workspaces.d.ts.map +1 -0
- package/dist/workspaces.js +393 -0
- package/docs/ARCHITECTURE.md +559 -0
- package/docs/COMPATIBILITY.md +237 -0
- package/docs/CONCEPT.md +242 -0
- package/docs/CROSS_PLATFORM.ru.md +152 -0
- package/docs/CROSS_PLATFORM.zh.md +148 -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 +699 -0
- package/docs/FEATURES.zh.md +656 -0
- package/docs/LOCAL-AI.md +300 -0
- package/docs/MIGRATION.md +363 -0
- package/docs/README.ru.md +287 -0
- package/docs/README.zh.md +306 -0
- package/docs/SAVINGS.md +61 -0
- package/docs/SAVINGS.ru.md +60 -0
- package/docs/SAVINGS.zh.md +52 -0
- package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
- package/docs/ZH-LOCALE-PLAN.md +324 -0
- package/docs/dashboard.png +0 -0
- package/docs/spikes/local-model-structured-output.md +81 -0
- package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
- package/docs/spikes/ollama-qwen3-4b.json +163 -0
- package/gui-experimental.cjs +9 -0
- package/index.js +2 -0
- package/locales/en.json +781 -0
- package/locales/ru.json +781 -0
- package/locales/zh.json +781 -0
- package/package.json +154 -13
- package/scripts/bench-local.mjs +321 -0
- package/scripts/check-zh-locale.mjs +218 -0
- package/scripts/demo-dashboard.mjs +209 -0
- package/scripts/run-tests.mjs +236 -0
- package/scripts/spike-local-structured.mjs +182 -0
- package/scripts/test-locale.mjs +45 -0
- package/skills/scheduled-job-best-practices/SKILL.md +158 -0
- package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
- package/src/core/analytics.ts +424 -0
- package/src/core/audit.ts +418 -0
- package/src/core/cron-to-schtasks.ts +209 -0
- package/src/core/dry-run.ts +601 -0
- package/src/core/file-watcher.ts +245 -0
- package/src/core/git-trigger.ts +391 -0
- package/src/core/glob.ts +226 -0
- package/src/core/local-ai.ts +173 -0
- package/src/core/lock.ts +219 -0
- package/src/core/matrix.ts +947 -0
- package/src/core/native-notify.ts +157 -0
- package/src/core/one-shot.ts +239 -0
- package/src/core/otel.ts +128 -0
- package/src/core/permissions.ts +200 -0
- package/src/core/prometheus.ts +215 -0
- package/src/core/ps-wrapper.ts +1160 -0
- package/src/core/record-history.ts +615 -0
- package/src/core/retention.ts +141 -0
- package/src/core/savings.ts +150 -0
- package/src/core/schedule-gate.ts +253 -0
- package/src/core/schedule-v2.ts +668 -0
- package/src/core/scheduler/at-fallback.ts +113 -0
- package/src/core/scheduler/index.ts +82 -0
- package/src/core/scheduler/linux.ts +308 -0
- package/src/core/scheduler/logs.ts +37 -0
- package/src/core/scheduler/mac.ts +322 -0
- package/src/core/scheduler/posix.ts +128 -0
- package/src/core/scheduler/registry.ts +101 -0
- package/src/core/scheduler/types.ts +90 -0
- package/src/core/scheduler/windows.ts +881 -0
- package/src/core/secrets.ts +503 -0
- package/src/core/self-analysis.ts +744 -0
- package/src/core/session.ts +150 -0
- package/src/core/shutdown.ts +69 -0
- package/src/core/structured-log.ts +214 -0
- package/src/core/summary.ts +318 -0
- package/src/core/telegram.ts +436 -0
- package/src/core/triage-chain.ts +125 -0
- package/src/core/triage-compare.ts +277 -0
- package/src/core/triage-rules.ts +238 -0
- package/src/core/triage-shadow.ts +240 -0
- package/src/core/triage-worker.ts +344 -0
- package/src/core/triage.ts +366 -0
- package/src/core/watch-paths.ts +70 -0
- package/src/core/wrappers/bash.ts +532 -0
- package/src/db/git-state-repo.ts +62 -0
- package/src/db/history-repo.ts +492 -0
- package/src/db/index.ts +176 -0
- package/src/db/metrics-repo.ts +170 -0
- package/src/db/migrate.ts +328 -0
- package/src/db/recovery.ts +46 -0
- package/src/db/run-journal.ts +212 -0
- package/src/db/run-resume.ts +220 -0
- package/src/db/runs-repo.ts +481 -0
- package/src/db/schema.ts +349 -0
- package/src/db/settings-repo.ts +31 -0
- package/src/db/tasks-repo.ts +162 -0
- package/src/db/templates-repo.ts +77 -0
- package/src/gui.tsx +5222 -0
- package/src/history.ts +128 -0
- package/src/i18n.ts +413 -0
- package/src/index.ts +6642 -0
- package/src/integrations.ts +297 -0
- package/src/notifications.ts +1346 -0
- package/src/profiles.ts +345 -0
- package/src/rpc.ts +1704 -0
- package/src/schtasks.ts +75 -0
- package/src/server.ts +2663 -0
- package/src/settings.ts +1369 -0
- package/src/shared/jobs-view.ts +188 -0
- package/src/skill.ts +113 -0
- package/src/task-transfer.ts +946 -0
- package/src/templates.ts +67 -0
- package/src/tui-v1.tsx +341 -0
- package/src/tui.tsx +329 -0
- package/src/types.ts +226 -0
- package/src/version.ts +27 -0
- package/src/workspaces.ts +487 -0
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# agent-steward
|
|
2
|
+
|
|
3
|
+
> Плагин для планирования и оркестрации задач AI-агентов в OpenCode V1 (≥ 1.18.29) и V2: cron, одноразовые запуски, DAG-пайплайны, матричные сборки, Quality Gates и наблюдаемость. Бесплатно, с открытым кодом (MIT).
|
|
4
|
+
|
|
5
|
+
[](https://github.com/DeadSno/agent-steward/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/agent-steward)
|
|
7
|
+
[](../LICENSE)
|
|
8
|
+
[](../package.json)
|
|
9
|
+
|
|
10
|
+
Translations: [English](../README.md) · [中文](README.zh.md).
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Быстрый старт
|
|
15
|
+
|
|
16
|
+
1. Установите плагин (см. [Установка](#установка)) и перезапустите OpenCode.
|
|
17
|
+
2. Попросите агента поставить первую задачу — достаточно одного вызова:
|
|
18
|
+
|
|
19
|
+
> Поставь задачу «утренний-отчёт»: каждый день в 09:00 с промптом «Просуммаризируй вчерашние git-коммиты и запиши отчёт в ~/reports/».
|
|
20
|
+
|
|
21
|
+
3. Откройте дашборд: агент печатает ссылку при создании задачи (по умолчанию `http://localhost:4380`), позже её можно получить инструментом `get_dashboard_info`. Посмотреть демо без установки: `node scripts/demo-dashboard.mjs` — дашборд с демо-данными на `http://localhost:4380`.
|
|
22
|
+
|
|
23
|
+

|
|
24
|
+
|
|
25
|
+
## Зачем
|
|
26
|
+
|
|
27
|
+
Большинство планировщиков для AI-агентов — это обёртки над cron: запустить промпт по таймеру и записать лог. Этот плагин относится к задачам агента как к **воркфлоу**:
|
|
28
|
+
|
|
29
|
+
- **DAG-пайплайны** — задача ждёт зависимости и продолжается по success/error.
|
|
30
|
+
- **Матричные сборки** — один шаблон, N репозиториев, параллельно или последовательно, с лимитом конкурентности и переопределениями для workspace.
|
|
31
|
+
- **Quality Gates** — задача считается успешной только если прошла `npm test` (или любая другая команда).
|
|
32
|
+
- **Наблюдаемость** — история в SQLite, метрики, логи и локальный веб-дашборд.
|
|
33
|
+
- **Работает без запущенного OpenCode** — задачи регистрируются в нативном планировщике ОС (Планировщик Windows, launchd, crontab) и переживают перезагрузку.
|
|
34
|
+
|
|
35
|
+
Всё выполняется на вашей машине: без SaaS, телеметрии и аккаунтов.
|
|
36
|
+
|
|
37
|
+
## Возможности
|
|
38
|
+
|
|
39
|
+
| Область | Что есть |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Расписание | cron-выражения, одноразовые запуски через `runAt` / `delaySeconds`, нативный планировщик ОС (Windows / macOS / Linux), локальное время без таймзон, пауза/возобновление, непрерывность сессий (`new` / `reuse` / `last` с очисткой `sessionMaxRuns`) |
|
|
42
|
+
| Надёжность | lock-файл от наложения запусков, таймауты с жёстким kill, повторы с задержкой, crash recovery |
|
|
43
|
+
| Качество | команда Quality Gate, before/after hooks, allow/deny списки инструментов для задачи |
|
|
44
|
+
| Оркестрация | DAG `dependsOn`, цепочки `nextTaskOnSuccess` / `nextTaskOnError`, матричный fan-out (parallel/sequential, `continue`/`stop`, concurrency, переопределения для workspace, агрегатор) |
|
|
45
|
+
| Триггеры | cron, одноразовый запуск (`triggerType: "once"`), git-коммиты (`triggerType: "git"`, фильтры ветки/путей/игнорирования), изменение файла (chokidar, glob-маски `watchGlobs`/`watchIgnore`), MCP-события, входящие webhooks (`POST /api/hooks/:task` с HMAC) |
|
|
46
|
+
| Мультирепо | workspaces с валидацией путей, запуски по workspace, матрица поверх родительской задачи |
|
|
47
|
+
| Наблюдаемость | история SQLite (success / error / timeout / partial / running), метрики (длительность, токены, стоимость), JSONL-логи с `/api/logs`, Prometheus `/metrics`, экспорт OTLP, логи по задачам, веб-дашборд с аналитикой за 14 дней, ретеншн истории и экспорт CSV/JSON |
|
|
48
|
+
| Эксплуатация | dry-run, экспорт/импорт JSON, шаблоны, уведомления по нескольким каналам (webhook, Telegram, нативные toast), тихие часы, дайджест, локальный ассистент для триажа уведомлений (fail-open, shadow-режим), зашифрованные секреты (`${secret:NAME}`), журнал аудита, настройки |
|
|
49
|
+
| Интерфейсы | панель OpenCode GUI, веб-дашборд, 26 инструментов для агента, встроенный скилл |
|
|
50
|
+
|
|
51
|
+
### Язык интерфейса
|
|
52
|
+
|
|
53
|
+
Интерфейс доступен на русском (по умолчанию), английском и китайском (упрощённом). Переключатель языка находится в шапке панели планировщика (🌐 Авто / Русский / English / 中文), а также доступен через инструмент `manage_settings` (`action: "update"`, `locale: "zh"`). Значение `locale: "auto"` («Авто») следует за языком интерфейса OpenCode: панель реагирует на смену языка сразу, а разрешённая локаль отправляется на сервер, чтобы уведомления, дайджест и дашборд использовали тот же язык. Переключение применяется без перезапуска. Локализация дашборда ещё не завершена: часть строк на стороне клиента пока остаётся русской. Описания и схемы инструментов агента остаются английскими, диагностика в консоли — русской.
|
|
54
|
+
|
|
55
|
+
Каталоги лежат в `locales/ru.json`, `locales/en.json` и `locales/zh.json`; набор ключей в них должен совпадать, иначе CI падает.
|
|
56
|
+
|
|
57
|
+
## Установка
|
|
58
|
+
|
|
59
|
+
Нужны OpenCode V1 ≥ 1.18.29 или V2, и Node.js 22.22+. Матрица версий и различия
|
|
60
|
+
поверхностей — в [COMPATIBILITY.md](COMPATIBILITY.md) (GUI и RPC — только V2, TUI — обе линии).
|
|
61
|
+
|
|
62
|
+
Ключ конфигурации зависит от линии:
|
|
63
|
+
|
|
64
|
+
| Линия OpenCode | Ключ в `opencode.jsonc` |
|
|
65
|
+
|---|---|
|
|
66
|
+
| V1 (`1.18.29`–`1.19.x`) | `"plugin": ["agent-steward"]` |
|
|
67
|
+
| V2 (`≥ 2.2.7`) | `"plugins": ["agent-steward"]` |
|
|
68
|
+
|
|
69
|
+
Используйте ключ своей линии; добавлять оба не нужно. В V2 проще через CLI:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
opencode plugin add agent-steward
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
V1 — вручную:
|
|
76
|
+
|
|
77
|
+
```jsonc
|
|
78
|
+
{
|
|
79
|
+
"$schema": "https://opencode.ai/config.json",
|
|
80
|
+
"plugin": ["agent-steward"]
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
V2 — тот же плагин вручную:
|
|
85
|
+
|
|
86
|
+
```jsonc
|
|
87
|
+
{
|
|
88
|
+
"$schema": "https://opencode.ai/config.json",
|
|
89
|
+
"plugins": ["agent-steward"],
|
|
90
|
+
"experimental": {
|
|
91
|
+
"schedules": false
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`experimental.schedules: false` отключает встроенный планировщик OpenCode, чтобы агент не путал встроенные инструменты расписаний с инструментами этого плагина. В OpenCode 2.x конфигурация перезагружается автоматически; если изменения не подхватились, выполните `/reload`. В 1.x перезапустите OpenCode после правки конфигурации. Панель TUI входит в тот же пакет (`exports["./tui"]`), поэтому включается той же записью на обеих линиях.
|
|
97
|
+
|
|
98
|
+
Из исходников:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
git clone https://github.com/DeadSno/agent-steward.git
|
|
102
|
+
cd agent-steward
|
|
103
|
+
npm install
|
|
104
|
+
npm run build && npm run build:gui
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Инструменты для агента
|
|
108
|
+
|
|
109
|
+
Агенту доступен весь функционал — 26 инструментов: расписание, пайплайны, эксплуатация, аналитика и администрирование.
|
|
110
|
+
|
|
111
|
+
| Инструмент | Аргументы | Что делает |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| `schedule_task` | `name`, `prompt`, `schedule` для cron или `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`, `matrix` | Регистрирует задачу в планировщике ОС (cron, одноразовый запуск, файл, git или MCP-событие) |
|
|
114
|
+
| `list_tasks` | — | Задачи: расписание, статус, следующее время запуска, цепочки, workspace, сводка матрицы |
|
|
115
|
+
| `update_task` | `name` + изменяемые поля | Частичное обновление: незаданные поля сохраняются, пустые — очищаются, `matrix: null` убирает матрицу |
|
|
116
|
+
| `delete_task` | `name` | Удаляет задачу (родитель матрицы — вместе с клонами и агрегатором) |
|
|
117
|
+
| `run_task_now` | `name` | Немедленный запуск (для матрицы — запуск fan-out) |
|
|
118
|
+
| `pause_task` | `name` | Пауза (для матрицы — все клоны) |
|
|
119
|
+
| `resume_task` | `name` | Возобновление |
|
|
120
|
+
| `get_history` | `taskName?`, `status?`, `limit?` | История запусков: длительность, токены, стоимость, модель, Quality Gate, хуки |
|
|
121
|
+
| `get_task_logs` | `name`, `lines?` | Хвост лога запуска |
|
|
122
|
+
| `dry_run` | `name?` | Симуляция пайплайна (или всех задач): порядок, DAG, fan-out, оценки |
|
|
123
|
+
| `manage_workspaces` | `action`, `id?`, `name?`, `path?`, `color?` | Multi-repo workspace: список, добавление, изменение, удаление |
|
|
124
|
+
| `matrix_control` | `action`, `name?` | Результаты матрицы, отмена клонов, очистка осиротевших задач, предпросмотр |
|
|
125
|
+
| `get_metrics` | — | Всего запусков, успехов и падений |
|
|
126
|
+
| `get_analytics` | `days?`, `topLimit?` | Отчёт за период: запуски, успешность, длительность, токены, стоимость, топ задач |
|
|
127
|
+
| `self_analysis` | `days?`, `topLimit?`, `includeAnomalies?` | Самодиагностика за период: оценка здоровья, аномалии, тренды и рекомендации по оптимизации |
|
|
128
|
+
| `manage_settings` | `action`, `maxConcurrent?`, `winterMode?`, `notifications?`, `history?` | Чтение и изменение глобальных настроек (параллелизм, уведомления, retention) |
|
|
129
|
+
| `manage_local_ai` | `action` (`get`/`update`/`test`), `mode?`, `baseUrl?`, `model?`, `timeoutMs?`, `fallback?`, `confidenceThreshold?`, `shadow?` | Настройки локального ассистента для триажа уведомлений и проверка модели одним запросом (см. [LOCAL-AI.md](LOCAL-AI.md)) |
|
|
130
|
+
| `manage_templates` | `action`, поля шаблона | Список, сохранение и удаление шаблонов задач |
|
|
131
|
+
| `manage_profiles` | `action`, `name?`, `port?` | Список, создание, переключение и удаление изолированных профилей |
|
|
132
|
+
| `transfer_tasks` | `action`, `data?` | Экспорт всех задач в JSON и импорт обратно |
|
|
133
|
+
| `send_notification` | `action` (`test`/`digest`), `channel?` (`all`/`webhook`/`telegram`/`native`) | Проверка каналов уведомлений или отправка дайджеста |
|
|
134
|
+
| `get_dashboard_info` | — | Порт/URL дашборда, платформа, заголовок, активный профиль |
|
|
135
|
+
| `cleanup_history` | `retentionDays?`, `maxRecords?` | Удаление старой истории по возрасту и/или лимиту записей |
|
|
136
|
+
| `manage_secrets` | `action`, `name?`, `value?` | Создание, список и удаление секретов AES-256-GCM для `env` задач |
|
|
137
|
+
| `get_audit_log` | `action?`, `target?`, `actor?`, `since?`, `until?`, `limit?` | Журнал мутаций: кто, что и когда изменил и через какой интерфейс |
|
|
138
|
+
| `emit_event` | `eventName`, `payload?` | Запуск задач, подписанных на MCP-событие |
|
|
139
|
+
|
|
140
|
+
`schedule_task` принимает и полную конфигурацию матрицы (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
|
|
141
|
+
|
|
142
|
+
## Права и разрешения
|
|
143
|
+
|
|
144
|
+
Задачи агента запускаются через `opencode run --auto`, поэтому их политика инструментов должна быть задана явно. Глобальная настройка `permissions.defaultPolicy` (GUI → Settings или `manage_settings`) задаёт базу:
|
|
145
|
+
|
|
146
|
+
| Политика | Разрешено по умолчанию | Запрещено по умолчанию |
|
|
147
|
+
|---|---|---|
|
|
148
|
+
| `hybrid` (по умолчанию) | read, edit, glob, grep, subagent, skill, webfetch, websearch | shell, question |
|
|
149
|
+
| `secure` | read, glob, grep, skill | edit, shell, question, webfetch, websearch, subagent |
|
|
150
|
+
| `legacy` | все десять действий | — |
|
|
151
|
+
|
|
152
|
+
`deniedTools` всегда важнее. Непустой `allowedTools` превращается в allowlist: всё, что не перечислено, запрещено, а разрешённое политикой действие можно явно вернуть (например, `shell`). `legacyShell: true` возвращает `shell` только при `hybrid` — для задач, перенесённых со старых версий.
|
|
153
|
+
|
|
154
|
+
Заблокированные действия пишутся в аудит как `tool.blocked` с `reason: "default-policy"` и `hint`, а каждый запуск записывает действующую политику.
|
|
155
|
+
|
|
156
|
+
Рекомендуемый приём: держите `git commit`/`push`, сборки и тесты вне агента — в `qualityGate` или `afterScript` (обёртка запускает их через `bash -c`), а агенту оставьте `read`/`edit`. Тогда большинству задач `shell` вообще не нужен.
|
|
157
|
+
|
|
158
|
+
## Скилл для агента
|
|
159
|
+
|
|
160
|
+
Плагин сам регистрирует встроенный скилл `scheduled-job-best-practices`: агент подгружает инструкцию только когда она действительно нужна — проектирование cron, самодостаточные промпты, Quality Gates, лимиты матрицы, правила DAG и разбор падений. Ручная настройка `.opencode/skills` не требуется. Вместе со скиллом поставляется `references/recipes.md` — семь готовых конфигураций.
|
|
161
|
+
|
|
162
|
+
## Матричные сборки
|
|
163
|
+
|
|
164
|
+
```jsonc
|
|
165
|
+
{
|
|
166
|
+
"name": "deploy",
|
|
167
|
+
"schedule": "0 3 * * *",
|
|
168
|
+
"prompt": "Build, test and deploy",
|
|
169
|
+
"matrix": {
|
|
170
|
+
"workspaceIds": ["frontend-id", "backend-id", "mobile-id"],
|
|
171
|
+
"strategy": "parallel",
|
|
172
|
+
"failureMode": "continue",
|
|
173
|
+
"aggregation": "summary",
|
|
174
|
+
"concurrency": 2,
|
|
175
|
+
"createAggregator": true,
|
|
176
|
+
"overrides": {
|
|
177
|
+
"mobile-id": { "qualityGate": "npm run test:mobile" }
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Каждый workspace получает клон `<parent>-matrix-<workspace>`. Родительская задача сама не выполняется: она агрегирует результаты клонов в `success`, `error` или `partial`. Клоны синхронизируются с родителем при его изменении; запущенные клоны не затрагиваются.
|
|
184
|
+
|
|
185
|
+
## GUI и дашборд
|
|
186
|
+
|
|
187
|
+
В боковой панели OpenCode доступны задачи, история, логи, dry-run, шаблоны, импорт/экспорт, лимит конкурентности и группировка матриц. Локальный веб-дашборд добавляет сводку по workspace, вкладки матриц, вид пайплайна и метрики.
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
npm run build:gui # собирает gui-experimental.cjs
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
## Как это устроено
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
src/
|
|
197
|
+
index.ts жизненный цикл плагина, инструменты агента, RPC
|
|
198
|
+
gui.tsx панель OpenCode в сайдбаре
|
|
199
|
+
server.ts локальный веб-дашборд
|
|
200
|
+
core/
|
|
201
|
+
scheduler/ бэкенды Windows / Linux / macOS
|
|
202
|
+
matrix.ts fan-out, агрегация, синхронизация, отмена
|
|
203
|
+
record-history.ts история, повторы, цепочки, продолжение матриц
|
|
204
|
+
dry-run.ts симуляция пайплайна
|
|
205
|
+
lock.ts защита от наложения запусков
|
|
206
|
+
file-watcher.ts триггеры chokidar
|
|
207
|
+
telegram.ts доставка в Telegram Bot API
|
|
208
|
+
native-notify.ts нативные уведомления (Windows/macOS/Linux)
|
|
209
|
+
secrets.ts зашифрованное хранилище секретов (AES-256-GCM)
|
|
210
|
+
audit.ts журнал аудита (audit_log в SQLite)
|
|
211
|
+
db/ SQLite: задачи, история, метрики, настройки
|
|
212
|
+
task-transfer.ts экспорт / импорт / валидация
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Обёртки задач запускают `opencode run` в рабочей директории задачи, поэтому MCP-серверы проекта подхватываются автоматически.
|
|
216
|
+
|
|
217
|
+
### Режим входа (Windows)
|
|
218
|
+
|
|
219
|
+
По умолчанию задачи **интерактивные** (`Interactive only`): Планировщик Windows запускает их только при активном входе пользователя, создавшего задачу, — с обычным профилем, дисками и сохранёнными учётными данными. Передайте `runWhenLoggedOff: true`, чтобы задача работала без входа (`schtasks /ru SYSTEM`). Такая задача идёт в session 0 — без профиля пользователя, подключённых дисков, сетевых ресурсов и сохранённых паролей, поэтому задачи, которым нужно ваше окружение, могут упасть; проверяйте их через `dry_run`. На Linux crontab и так работает без входа, а launchd-агент macOS — только внутри пользовательской сессии.
|
|
220
|
+
|
|
221
|
+
## Разработка
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
npm install
|
|
225
|
+
npm run build # tsc
|
|
226
|
+
npm run build:gui # vite
|
|
227
|
+
npm test # 73 сюит, 600+ проверок
|
|
228
|
+
npm run test:en # те же сюиты с английской локалью
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`npm run test:en` выставляет `OPENCODE_SCHEDULER_LOCALE=en` для каждой сюиты; переменная нужна тестам и сервисам, это не пользовательская настройка.
|
|
232
|
+
|
|
233
|
+
Подробности — в [CONTRIBUTING.md](../CONTRIBUTING.md).
|
|
234
|
+
|
|
235
|
+
## Документация
|
|
236
|
+
|
|
237
|
+
- [ARCHITECTURE.md](ARCHITECTURE.md) — модель процессов, модули, бэкенды, модель данных.
|
|
238
|
+
- [CONCEPT.md](CONCEPT.md) — north star: верифицируемая локально-первая оркестрация.
|
|
239
|
+
- [FEATURES.md](FEATURES.md) — полный каталог возможностей с примерами.
|
|
240
|
+
- [FAQ.md](FAQ.md) — сценарии восстановления и ответы по эксплуатации (English).
|
|
241
|
+
- [MIGRATION.md](MIGRATION.md) — переезд с cron, systemd, launchd или Планировщика Windows.
|
|
242
|
+
- [SAVINGS.md](SAVINGS.md) — как считается оценка «Сэкономлено $» (English).
|
|
243
|
+
- [../CROSS_PLATFORM.md](../CROSS_PLATFORM.md) — различия и бэкенды Windows / macOS / Linux.
|
|
244
|
+
|
|
245
|
+
## FAQ
|
|
246
|
+
|
|
247
|
+
**Работает ли плагин, когда OpenCode закрыт?**
|
|
248
|
+
Да. Задачи регистрируются в нативном планировщике ОС, поэтому выполняются без открытого OpenCode.
|
|
249
|
+
|
|
250
|
+
**Выполняются ли задачи, когда никто не вошёл в систему?**
|
|
251
|
+
На Windows — только если явно включить `runWhenLoggedOff: true`: задача регистрируется как `schtasks /ru SYSTEM` и идёт в session 0 без вашего профиля, подключённых дисков и сохранённых учётных данных. По умолчанию задача интерактивная и работает при активном входе. Linux crontab выполняет задачи и без входа, а launchd-агент macOS — только внутри пользовательской сессии.
|
|
252
|
+
|
|
253
|
+
**Какие платформы поддерживаются?**
|
|
254
|
+
Windows (Планировщик Windows), macOS (launchd) и Linux (crontab). Различия описаны в [CROSS_PLATFORM.md](../CROSS_PLATFORM.md).
|
|
255
|
+
|
|
256
|
+
**Куда отправляются данные?**
|
|
257
|
+
Никуда. История, логи, метрики и настройки хранятся локально в SQLite; телеметрии и аккаунтов нет.
|
|
258
|
+
|
|
259
|
+
**Как включить уведомления в Telegram?**
|
|
260
|
+
Создайте бота у [@BotFather](https://t.me/BotFather), скопируйте токен, напишите боту сообщение и возьмите `chat_id` из `getUpdates` (или используйте 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"`.
|
|
261
|
+
|
|
262
|
+
**Нужен ли отдельный пакет для системных уведомлений?**
|
|
263
|
+
Нет. Windows Toast (PowerShell/WinRT), macOS Notification Center (`osascript`) и Linux `notify-send` вызываются напрямую, `node-notifier` не требуется. Включается через `notifications.native.enabled`.
|
|
264
|
+
|
|
265
|
+
**Можно ли отключить уведомления на ночь?**
|
|
266
|
+
Да. Задайте `notifications.quietHours` (`enabled`, `from`, `to` в `HH:MM`). В этом окне успешные и `partial` запуски не отправляются, а ошибки и таймауты приходят всегда.
|
|
267
|
+
|
|
268
|
+
**Как хранить секреты?**
|
|
269
|
+
Используйте `manage_secrets` (или панель «🔐 Секреты» в сайдбаре). Секреты хранятся в `<PLUGIN_DIR>/secrets.json` с шифрованием AES-256-GCM и ключевым файлом `secrets.key` (права 0600). В `env` задачи секрет ссылается как `${secret:NAME}` — значение подставляется при запуске и маскируется в логах, истории и аудите.
|
|
270
|
+
|
|
271
|
+
**Можно ли посмотреть, кто что изменил?**
|
|
272
|
+
Да. Журнал аудита (`get_audit_log`, панель «📜 Журнал аудита», `GET /api/audit`) записывает каждую мутацию — создание/изменение/удаление/запуск задачи, настройки, шаблоны, профили, workspace, секреты, импорт, очистку истории — с aktёром (mcp/gui/http), источником, временной меткой и замаскированными деталями. Ретеншн по умолчанию 90 дней / 10 000 записей.
|
|
273
|
+
|
|
274
|
+
**Чем это отличается от `experimental.schedules` в OpenCode?**
|
|
275
|
+
Встроенный планировщик выполняет задачи, пока OpenCode запущен. Этот плагин использует нативный планировщик ОС и добавляет DAG-пайплайны, матричные сборки, Quality Gates, webhooks и наблюдаемость.
|
|
276
|
+
|
|
277
|
+
**Можно ли запускать задачи в других репозиториях?**
|
|
278
|
+
Да. Workspaces задают путь к проекту, а матричная сборка запускает один шаблон по нескольким workspace сразу.
|
|
279
|
+
|
|
280
|
+
## Дальнейшее развитие
|
|
281
|
+
|
|
282
|
+
- [ROADMAP.md](../ROADMAP.md) — история спринтов и ближайшие планы.
|
|
283
|
+
- [ROADMAP-STRATEGY.md](../ROADMAP-STRATEGY.md) — позиционирование и горизонт 0–6 месяцев.
|
|
284
|
+
|
|
285
|
+
## Лицензия
|
|
286
|
+
|
|
287
|
+
[MIT](../LICENSE).
|
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
# agent-steward
|
|
2
|
+
|
|
3
|
+
> 用于在 OpenCode V1(≥ 1.18.29)或 V2 中调度与编排 AI agent 任务的插件 —— cron、一次性运行、DAG 流水线、矩阵构建、质量门禁、SQLite 历史记录和本地 Web 仪表盘。支持 Windows、macOS 和 Linux。免费开源(MIT)。
|
|
4
|
+
|
|
5
|
+
[](https://github.com/DeadSno/agent-steward/actions/workflows/ci.yml)
|
|
6
|
+
[](https://www.npmjs.com/package/agent-steward)
|
|
7
|
+
[](https://www.npmjs.com/package/agent-steward)
|
|
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 V1(≥ 1.18.29)或 V2,以及 Node.js 22.22+。版本矩阵与界面差异见
|
|
69
|
+
[COMPATIBILITY.md](COMPATIBILITY.md)(GUI 与 RPC 仅支持 V2,TUI 两条版本线都支持)。
|
|
70
|
+
|
|
71
|
+
配置键因版本线而异:
|
|
72
|
+
|
|
73
|
+
| OpenCode 版本线 | `opencode.jsonc` 中的键 |
|
|
74
|
+
|---|---|
|
|
75
|
+
| V1(`1.18.29`–`1.19.x`) | `"plugin": ["agent-steward"]` |
|
|
76
|
+
| V2(`≥ 2.2.7`) | `"plugins": ["agent-steward"]` |
|
|
77
|
+
|
|
78
|
+
请使用对应版本线的键,无需同时添加两者。V2 可直接用 CLI:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
opencode plugin add agent-steward
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
V1 手动配置:
|
|
85
|
+
|
|
86
|
+
```jsonc
|
|
87
|
+
{
|
|
88
|
+
"$schema": "https://opencode.ai/config.json",
|
|
89
|
+
"plugin": ["agent-steward"]
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
V2 手动配置:
|
|
94
|
+
|
|
95
|
+
```jsonc
|
|
96
|
+
{
|
|
97
|
+
"$schema": "https://opencode.ai/config.json",
|
|
98
|
+
"plugins": ["agent-steward"],
|
|
99
|
+
"experimental": {
|
|
100
|
+
"schedules": false
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`experimental.schedules: false` 会关闭 OpenCode 内置调度器,避免 agent 把内置任务工具与本插件的工具混淆。OpenCode 2.x 会自动重新加载配置;如未生效,请执行 `/reload`。1.x 修改配置后请重启 OpenCode。TUI 面板随同一个包提供(`exports["./tui"]`),两条版本线都用同一条配置启用。
|
|
106
|
+
|
|
107
|
+
从源码安装:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
git clone https://github.com/DeadSno/agent-steward.git
|
|
111
|
+
cd agent-steward
|
|
112
|
+
npm install
|
|
113
|
+
npm run build && npm run build:gui
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Agent 工具
|
|
117
|
+
|
|
118
|
+
agent 可获得完整功能 —— 26 个工具,覆盖调度、流水线、运维、可观测性与管理:
|
|
119
|
+
|
|
120
|
+
| 工具 | 参数 | 作用 |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `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 事件触发器) |
|
|
123
|
+
| `list_tasks` | — | 返回任务及其 schedule、状态、下次运行、链路、workspace 和矩阵摘要 |
|
|
124
|
+
| `update_task` | `name` + 要修改的字段 | 部分更新;省略的字段保留原值,空值表示清空,`matrix: null` 移除矩阵 |
|
|
125
|
+
| `delete_task` | `name` | 删除任务(矩阵父任务会一并删除克隆和聚合器) |
|
|
126
|
+
| `run_task_now` | `name` | 立即运行任务(矩阵父任务会启动扇出) |
|
|
127
|
+
| `pause_task` | `name` | 暂停任务(矩阵父任务会暂停每个克隆) |
|
|
128
|
+
| `resume_task` | `name` | 恢复已暂停的任务 |
|
|
129
|
+
| `get_history` | `taskName?`、`status?`、`limit?` | 最近运行记录,含耗时、token、成本、模型、质量门禁与钩子 |
|
|
130
|
+
| `get_task_logs` | `name`、`lines?` | 运行日志尾部 |
|
|
131
|
+
| `dry_run` | `name?` | 模拟流水线(或全部任务):执行顺序、DAG、矩阵扇出、估算 |
|
|
132
|
+
| `manage_workspaces` | `action`、`id?`、`name?`、`path?`、`color?` | 多仓库 workspace:列出、添加、更新、删除 |
|
|
133
|
+
| `matrix_control` | `action`、`name?` | 矩阵结果、取消待运行克隆、清理孤儿、预览克隆 |
|
|
134
|
+
| `get_metrics` | — | 汇总的运行数、成功数与失败数 |
|
|
135
|
+
| `get_analytics` | `days?`、`topLimit?` | 周期报告:数量、成功率、耗时、token、成本、热门任务 |
|
|
136
|
+
| `self_analysis` | `days?`、`topLimit?`、`includeAnomalies?` | 周期自检报告:健康评分、异常检测、趋势分析与优化建议 |
|
|
137
|
+
| `manage_settings` | `action`、`maxConcurrent?`、`winterMode?`、`notifications?`、`history?` | 读取/更新全局设置(并发、通知、保留策略) |
|
|
138
|
+
| `manage_local_ai` | `action`(`get`/`update`/`test`)、`mode?`、`baseUrl?`、`model?`、`timeoutMs?`、`fallback?`、`confidenceThreshold?`、`shadow?` | 读取、更新或测试本地分诊助手;`test` 会发送一条合成通知并返回延迟与判定结果 |
|
|
139
|
+
| `manage_templates` | `action`、模板字段 | 列出、保存或删除可复用的任务模板 |
|
|
140
|
+
| `manage_profiles` | `action`、`name?`、`port?` | 列出、创建、切换或删除隔离的 profile |
|
|
141
|
+
| `transfer_tasks` | `action`、`data?` | 将所有任务导出为 JSON,或重新导入 |
|
|
142
|
+
| `send_notification` | `action`(`test`/`digest`)、`channel?`(`all`/`webhook`/`telegram`/`native`) | 测试通知渠道或发送摘要 |
|
|
143
|
+
| `get_dashboard_info` | — | 仪表盘端口/URL、平台、标题、当前 profile |
|
|
144
|
+
| `cleanup_history` | `retentionDays?`、`maxRecords?` | 按时间或记录上限删除旧历史 |
|
|
145
|
+
| `manage_secrets` | `action`、`name?`、`value?` | 创建、列出或删除用于任务 `env` 的 AES-256-GCM 加密密钥 |
|
|
146
|
+
| `get_audit_log` | `action?`、`target?`、`actor?`、`since?`、`until?`、`limit?` | 变更审计日志:谁、何时、通过哪个界面改了什么 |
|
|
147
|
+
| `emit_event` | `eventName`、`payload?` | 启动订阅该 MCP 事件的任务 |
|
|
148
|
+
|
|
149
|
+
`schedule_task` 还接受完整的矩阵配置(`workspaceIds`、`strategy`、`failureMode`、`aggregation`、`concurrency`、`overrides`、`createAggregator`)。
|
|
150
|
+
|
|
151
|
+
## 权限
|
|
152
|
+
|
|
153
|
+
Agent 任务以 `opencode run --auto` 运行,因此其工具策略必须显式声明。全局设置 `permissions.defaultPolicy`(GUI → Settings,或 `manage_settings`)决定基线:
|
|
154
|
+
|
|
155
|
+
| 策略 | 默认允许 | 默认禁止 |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| `hybrid`(默认) | read、edit、glob、grep、subagent、skill、webfetch、websearch | shell、question |
|
|
158
|
+
| `secure` | read、glob、grep、skill | edit、shell、question、webfetch、websearch、subagent |
|
|
159
|
+
| `legacy` | 全部十个动作 | — |
|
|
160
|
+
|
|
161
|
+
`deniedTools` 始终优先。非空的 `allowedTools` 会变成 allowlist:未列出的动作一律禁止,也可以显式恢复被策略禁止的动作(例如 `shell`)。`legacyShell: true` 仅在 `hybrid` 下恢复 `shell`,用于从旧版本迁移的任务。
|
|
162
|
+
|
|
163
|
+
被阻止的动作会以 `tool.blocked` 写入审计日志,带 `reason: "default-policy"` 和 `hint`;每次运行还会记录当前生效的策略。
|
|
164
|
+
|
|
165
|
+
推荐做法:把 `git commit`/`push`、构建和测试放在 agent 之外,通过 `qualityGate` 或 `afterScript` 执行(包装器用 `bash -c` 运行它们),让 agent 只保留 `read`/`edit`。这样大多数任务根本不需要 `shell`。
|
|
166
|
+
|
|
167
|
+
## Agent skill
|
|
168
|
+
|
|
169
|
+
插件注册了内置 skill `scheduled-job-best-practices`,agent 只在相关时加载指导:cron 设计、自包含提示词、Quality Gate、矩阵并发、DAG 规则以及事故后诊断。无需手动配置 `.opencode/skills`。该 skill 附带 `references/recipes.md` —— 八个可直接复制的配置。
|
|
170
|
+
|
|
171
|
+
## 矩阵构建
|
|
172
|
+
|
|
173
|
+
```jsonc
|
|
174
|
+
{
|
|
175
|
+
"name": "deploy",
|
|
176
|
+
"schedule": "0 3 * * *",
|
|
177
|
+
"prompt": "Build, test and deploy",
|
|
178
|
+
"matrix": {
|
|
179
|
+
"workspaceIds": ["frontend-id", "backend-id", "mobile-id"],
|
|
180
|
+
"strategy": "parallel",
|
|
181
|
+
"failureMode": "continue",
|
|
182
|
+
"aggregation": "summary",
|
|
183
|
+
"concurrency": 2,
|
|
184
|
+
"createAggregator": true,
|
|
185
|
+
"overrides": {
|
|
186
|
+
"mobile-id": { "qualityGate": "npm run test:mobile" }
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
每个 workspace 会得到一个名为 `<parent>-matrix-<workspace>` 的克隆。父任务自身从不运行:它把克隆结果聚合为 `success`、`error` 或 `partial`。编辑父任务时克隆会保持同步;正在运行的克隆不会被改动。
|
|
193
|
+
|
|
194
|
+
## GUI 与仪表盘
|
|
195
|
+
|
|
196
|
+
OpenCode 侧边栏显示任务、历史、日志、dry-run、模板、导入/导出、并发限制和矩阵分组。本地 Web 仪表盘额外提供按 workspace 的汇总、矩阵标签页、流水线视图和指标。
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
npm run build:gui # produces gui-experimental.cjs
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## 工作原理
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
src/
|
|
206
|
+
index.ts plugin lifecycle, agent tools, RPC
|
|
207
|
+
gui.tsx OpenCode sidebar panel
|
|
208
|
+
server.ts local web dashboard
|
|
209
|
+
core/
|
|
210
|
+
scheduler/ Windows / Linux / macOS backends
|
|
211
|
+
matrix.ts fan-out, aggregation, sync, cancel
|
|
212
|
+
record-history.ts history, retries, chains, matrix continuation
|
|
213
|
+
dry-run.ts pipeline simulation
|
|
214
|
+
lock.ts no-overlap protection
|
|
215
|
+
file-watcher.ts chokidar triggers
|
|
216
|
+
telegram.ts Telegram Bot API delivery
|
|
217
|
+
native-notify.ts Windows Toast / macOS / Linux notifications
|
|
218
|
+
db/ SQLite: tasks, history, metrics, settings
|
|
219
|
+
task-transfer.ts export / import / validation
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
任务包装器在任务工作目录中运行 `opencode run`,因此项目级 MCP server 会被自动加载。
|
|
223
|
+
|
|
224
|
+
### 登录模式(Windows)
|
|
225
|
+
|
|
226
|
+
任务默认**仅交互式**:只有当创建任务的那个用户登录时,任务计划程序才会启动它们,并使用正常的配置文件、磁盘映射和已保存凭据。传入 `runWhenLoggedOff: true` 可在无用户登录时运行任务(`schtasks /ru SYSTEM`)。这类任务在会话 0 中运行 —— 没有用户配置文件、映射磁盘、网络共享或已保存凭据 —— 因此依赖你环境的任务可能失败;请先用 `dry_run` 测试。在 Linux 上 crontab 本来就无需登录即可运行,而 macOS 的 launchd agent 仅在用户会话内运行。
|
|
227
|
+
|
|
228
|
+
## 开发
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
npm install
|
|
232
|
+
npm run build # tsc
|
|
233
|
+
npm run build:gui # vite
|
|
234
|
+
npm test # 73 test suites, 600+ checks
|
|
235
|
+
npm run test:en # same suites with the English locale
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`npm run test:en` 会为每个测试套件设置 `OPENCODE_SCHEDULER_LOCALE=en`;该变量是
|
|
239
|
+
服务内部钩子,不是用户设置。
|
|
240
|
+
|
|
241
|
+
详情见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
|
|
242
|
+
|
|
243
|
+
## 文档
|
|
244
|
+
|
|
245
|
+
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) —— 进程模型、模块、后端、数据模型。
|
|
246
|
+
- [docs/CONCEPT.md](CONCEPT.md) —— north star:可验证的本地优先编排(俄文)。
|
|
247
|
+
- [docs/FEATURES.md](FEATURES.md) —— 带示例的完整功能目录。
|
|
248
|
+
- [docs/FAQ.md](FAQ.md) —— 恢复场景与运维问答。
|
|
249
|
+
- [docs/MIGRATION.md](MIGRATION.md) —— 从 cron、systemd、launchd 或任务计划程序迁移。
|
|
250
|
+
- [docs/SAVINGS.md](SAVINGS.md) —— "Saved $" 估算如何计算。
|
|
251
|
+
- [CROSS_PLATFORM.md](../CROSS_PLATFORM.md) —— Windows / macOS / Linux 的差异与后端。
|
|
252
|
+
|
|
253
|
+
## FAQ
|
|
254
|
+
|
|
255
|
+
**OpenCode 关闭时还能运行吗?**
|
|
256
|
+
cron 和一次性任务可以。它们注册在操作系统原生调度器中,因此无需打开 OpenCode 窗口即可运行。
|
|
257
|
+
|
|
258
|
+
文件(`file`)、git(`git`)和 MCP 事件(`mcp-event`)触发器由插件进程监听(chokidar / git 轮询 / MCP 事件总线),因此这些触发器需要 OpenCode 处于运行状态。
|
|
259
|
+
|
|
260
|
+
| 触发器 | 无需 OpenCode 运行? | 机制 |
|
|
261
|
+
|---|---|---|
|
|
262
|
+
| `cron` | ✅ 是 | 操作系统原生调度器(任务计划程序 / launchd / crontab) |
|
|
263
|
+
| `once` | ✅ 是 | 操作系统原生调度器,一次性注册 |
|
|
264
|
+
| `file` | ❌ 否 | 插件进程内的 chokidar 监听 |
|
|
265
|
+
| `git` | ❌ 否 | 插件进程内的 git 轮询 |
|
|
266
|
+
| `mcp-event` | ❌ 否 | 插件进程内的 MCP 事件总线 |
|
|
267
|
+
| `webhook`(`/api/hooks/:name`) | ❌ 否 | 插件进程内的 HTTP 服务器 |
|
|
268
|
+
|
|
269
|
+
**没人登录时任务会运行吗?**
|
|
270
|
+
在 Windows 上,只有显式设置 `runWhenLoggedOff: true` 才会:任务以 `schtasks /ru SYSTEM` 注册,在会话 0 中运行,没有你的配置文件、映射磁盘或已保存凭据。默认仅交互式 —— 用户登录时任务才运行。Linux crontab 始终无需登录即可运行;macOS launchd agent 仅在用户会话内运行。
|
|
271
|
+
|
|
272
|
+
**支持哪些平台?**
|
|
273
|
+
Windows(任务计划程序)、macOS(launchd)和 Linux(crontab)。后端差异见 [CROSS_PLATFORM.md](../CROSS_PLATFORM.md)。
|
|
274
|
+
|
|
275
|
+
**我的数据会去哪里?**
|
|
276
|
+
哪里都不去。历史、日志、指标和设置都保存在本地 SQLite 中。没有遥测、没有账号、没有云端。
|
|
277
|
+
|
|
278
|
+
**如何配置 Telegram 通知?**
|
|
279
|
+
用 [@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"` 验证。
|
|
280
|
+
|
|
281
|
+
**桌面通知需要额外安装包吗?**
|
|
282
|
+
不需要。Windows Toast(PowerShell/WinRT)、macOS 通知中心(`osascript`)和 Linux 的 `notify-send` 都是直接调用,无需 `node-notifier`。通过 `notifications.native.enabled` 启用。
|
|
283
|
+
|
|
284
|
+
**能在夜间静音通知吗?**
|
|
285
|
+
可以。设置 `notifications.quietHours`(`enabled`、`from`、`to`,格式 `HH:MM`)。窗口期内成功和 `partial` 运行会被抑制,而失败和超时始终送达。
|
|
286
|
+
|
|
287
|
+
**如何保存密钥?**
|
|
288
|
+
用 `manage_secrets`(或侧边栏的 **🔐 Secrets** 面板)创建加密密钥。密钥以 AES-256-GCM 保存在 `<PLUGIN_DIR>/secrets.json`,并配有密钥文件(`secrets.key`;POSIX 上权限 0600,Windows 上使用仅授予当前用户的 ACL)。在任务 `env` 中用 `${secret:NAME}` 引用 —— 值在运行时替换,并在日志、历史和审计中脱敏。
|
|
289
|
+
|
|
290
|
+
**能看到谁改了什么吗?**
|
|
291
|
+
可以。审计日志(`get_audit_log` 工具、**Audit log** 面板、`GET /api/audit`)记录每一次变更 —— 任务创建/更新/删除/运行、设置、模板、profile、workspace、密钥、导入、历史清理 —— 包含操作者(mcp/gui/http)、来源、时间戳和脱敏后的详情。默认保留 90 天 / 10 000 条记录。
|
|
292
|
+
|
|
293
|
+
**它与 `experimental.schedules` 有何不同?**
|
|
294
|
+
内置调度器只在 OpenCode 打开时运行任务。本插件使用操作系统原生调度器,并额外提供 DAG 流水线、矩阵构建、质量门禁、webhook 和可观测性。
|
|
295
|
+
|
|
296
|
+
**任务能在其他仓库中运行吗?**
|
|
297
|
+
可以。workspace 指向项目路径,矩阵构建可同时在多个 workspace 中运行同一个模板。
|
|
298
|
+
|
|
299
|
+
## 路线图
|
|
300
|
+
|
|
301
|
+
- [ROADMAP.md](../ROADMAP.md) —— 冲刺历史与后续计划。
|
|
302
|
+
- [ROADMAP-STRATEGY.md](../ROADMAP-STRATEGY.md) —— 定位与六个月规划。
|
|
303
|
+
|
|
304
|
+
## 许可证
|
|
305
|
+
|
|
306
|
+
[MIT](../LICENSE)。
|