devcontour-harness-ui 0.1.0-alpha.1 → 0.1.0-alpha.2
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/README.md +23 -6
- package/docs/design.md +292 -78
- package/docs/harness-proposals.md +49 -2
- package/docs/release-notes/0.1.0-alpha.2.md +218 -0
- package/package.json +3 -2
- package/skills/harness-ui/SKILL.md +50 -18
package/README.md
CHANGED
|
@@ -15,13 +15,19 @@
|
|
|
15
15
|
данные harness, а не пересказ агента: что ждёт вашего ответа, что идёт
|
|
16
16
|
сейчас, как именно проверена работа и где лежит принятый результат.
|
|
17
17
|
|
|
18
|
-
> Статус: `0.1.0-alpha.
|
|
18
|
+
> Статус: `0.1.0-alpha.2`. Все экраны только для чтения: обзор, детали
|
|
19
19
|
> работы, ревью, решения, кто что делал, настройки, история и здоровье, на
|
|
20
20
|
> русском и английском. Данные — файл представления или живой
|
|
21
21
|
> `harness view` (`--state`, harness `0.1.0-alpha.55` и новее). Схемой
|
|
22
22
|
> представления владеет harness; см. [предложения для harness](docs/harness-proposals.md).
|
|
23
|
+
> С harness `0.1.0-alpha.56` (ревизия представления 1) панель показывает,
|
|
24
|
+
> кто и почему ответил на вопрос, итоги окна истории и замечает изменения по
|
|
25
|
+
> токену harness. С `0.1.0-alpha.57` (ревизия 2) — ещё ленту «кто что
|
|
26
|
+
> делал» и есть ли принятая работа в удалённой ветке (по копии ветки на этой
|
|
27
|
+
> машине, без сети). С alpha.55 и alpha.56 всё прочее работает, как раньше.
|
|
23
28
|
> [Дизайн](docs/design.md) описывает схему, экраны, безопасность и этапы;
|
|
24
|
-
> изменения — в
|
|
29
|
+
> изменения — в заметках к выпускам [0.1.0-alpha.2](docs/release-notes/0.1.0-alpha.2.md)
|
|
30
|
+
> и [0.1.0-alpha.1](docs/release-notes/0.1.0-alpha.1.md).
|
|
25
31
|
|
|
26
32
|
## Язык
|
|
27
33
|
|
|
@@ -38,21 +44,26 @@
|
|
|
38
44
|
версия, как и у harness):
|
|
39
45
|
|
|
40
46
|
```sh
|
|
41
|
-
npm install --save-dev --save-exact devcontour-harness@0.1.0-alpha.
|
|
47
|
+
npm install --save-dev --save-exact devcontour-harness@0.1.0-alpha.57 devcontour-harness-ui@0.1.0-alpha.2
|
|
42
48
|
npx devcontour-harness-ui --demo --lang ru # демонстрационные данные
|
|
43
49
|
# → {"ok":true,"url":"http://127.0.0.1:4790/","port":4790,"readOnly":true,...}
|
|
44
50
|
```
|
|
45
51
|
|
|
46
52
|
Откройте напечатанный URL. Чтобы показать настоящий проект, панель сама
|
|
47
|
-
вызывает установленный harness
|
|
48
|
-
|
|
53
|
+
вызывает установленный harness и передаёт язык интерфейса. Открытая
|
|
54
|
+
страница обновляется сама: пока она открыта, панель замечает изменения
|
|
55
|
+
каталога состояния и перепроверяет `harness view` (2–15 с, не реже 5 с,
|
|
56
|
+
пока идут попытки) и присылает изменения по SSE; без открытой страницы и
|
|
57
|
+
при скрытой вкладке harness не запускается. Над экраном — строка «Данные на
|
|
58
|
+
HH:MM» и предупреждение, если обновить данные не удалось:
|
|
49
59
|
|
|
50
60
|
```sh
|
|
51
61
|
npx devcontour-harness-ui --state <state> --policy .harness/policy.json \
|
|
52
62
|
--harness node_modules/.bin/harness
|
|
53
63
|
```
|
|
54
64
|
|
|
55
|
-
Или запишите снимок и раздайте файл (деталей работ у снимка нет)
|
|
65
|
+
Или запишите снимок и раздайте файл (деталей работ у снимка нет); при
|
|
66
|
+
перезаписи файла открытая страница обновится:
|
|
56
67
|
|
|
57
68
|
```sh
|
|
58
69
|
npx harness view --state <state> --policy .harness/policy.json > view.json # конверт тоже принимается
|
|
@@ -73,6 +84,11 @@ npx devcontour-harness-ui --view view.json
|
|
|
73
84
|
- `--host`, только loopback: `127.0.0.1`, `::1` или `localhost`. Всё
|
|
74
85
|
остальное отклоняется.
|
|
75
86
|
- `--lang ru|en` — язык, когда страница не запросила свой (`?lang=`).
|
|
87
|
+
- `--window 24h|7d` — окно истории для `--state` (по умолчанию окно harness,
|
|
88
|
+
24 ч).
|
|
89
|
+
- `--check [--harness <bin>] [--state <dir> [--policy <file>]]` — печатает
|
|
90
|
+
`{harness, ui, viewVersion, compatible, fix?}`; выход 0 — совместимо, 3 —
|
|
91
|
+
нет.
|
|
76
92
|
|
|
77
93
|
В stdout печатается одна строка JSON, подсказки идут в stderr. Коды
|
|
78
94
|
выхода: 0, 2 (ввод), 3 (отказ) и 4 (инфраструктура).
|
|
@@ -83,6 +99,7 @@ npx devcontour-harness-ui --view view.json
|
|
|
83
99
|
npm install
|
|
84
100
|
npm test && npm run typecheck && npm run build
|
|
85
101
|
npm run test:e2e # Playwright при 1280 и 390 px, axe; нужен локальный Chromium Playwright
|
|
102
|
+
npm run check # всё вместе: typecheck, prettier, unit, сборка, e2e
|
|
86
103
|
node dist/lib/cli.js --demo
|
|
87
104
|
```
|
|
88
105
|
|
package/docs/design.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# devcontour-harness-ui: дизайн
|
|
2
2
|
|
|
3
|
-
Статус: `0.1.0-alpha.
|
|
3
|
+
Статус: `0.1.0-alpha.2` — срезы S2 (экраны только для чтения, два языка) и S3 без `--from` и без `serve-view` (живые обновления, `--window`, `--check`, §6, §10); читает ревизии представления 0, 1 и 2. Относится к представлению версии 1.
|
|
4
4
|
Версия 1 зафиксирована в harness `0.1.0-alpha.55` (P1): поля меняются только
|
|
5
5
|
добавлением (`viewRevision`) или новой мажорной версией (§4).
|
|
6
6
|
|
|
@@ -189,26 +189,26 @@ harness, а не из файла политики: например `approvalMod
|
|
|
189
189
|
Предел: 500. Счётчики обзора берутся из `progress`, а не из этого списка
|
|
190
190
|
(§3.6).
|
|
191
191
|
|
|
192
|
-
| Поле | Источник в harness
|
|
193
|
-
| ----------------------------------------------------- |
|
|
194
|
-
| `id, graphId, status, resultSha?` | `status.works[]`
|
|
195
|
-
| `title?` | заголовок узла графа, замаскирован и обрезан до 120 символов (§9); убирается с `--no-titles`
|
|
196
|
-
| `stage {name, step?, since?, next[], needs?}` | `status.works[].stage` (alpha.54: `queued, blocked, prepare, writer, gates, review, integration, input, stopped, done, cancelled`)
|
|
197
|
-
| `stage.typical? {p50Ms, p90Ms, samples}` | P2: наблюдаемая длительность этого этапа в этом состоянии; нет, пока образцов меньше минимума (предложено 5, §11)
|
|
198
|
-
| `attempts.used / max / left` | `attemptSummaryView()`: учтённые `work.attempt` против `maxAttempts`
|
|
199
|
-
| `attempts.failed` | `attemptSummaryOf()`: учтённые сбои; прерывания при остановке не считаются
|
|
200
|
-
| `attempts.interrupted` | попытки с `interruptedByShutdown`; попытку они не расходуют
|
|
201
|
-
| `attempts.rechecks` | записи доказательств с `recheck: true` по всем попыткам работы
|
|
202
|
-
| `attempts.neutral {used, max}` | `work.neutralFailures` против `MAX_NEUTRAL_FAILURES`
|
|
203
|
-
| `attempts.line` | `attemptSummaryLine`
|
|
204
|
-
| `attempts.lastFailure? {attempt, bucket, plain, at?}` | alpha.55: почему остановилась прошлая попытка; `bucket` из `failureBucketOf`, `plain` — шаблон и маскированная деталь, до 160 символов
|
|
205
|
-
| `liveness?` | `status.works[].liveness` (`quiet`, `stalled`; `active`, когда работа движется)
|
|
206
|
-
| `runtime?, model?` | активная попытка
|
|
207
|
-
| `blockers[] {code, plain?, actor}` | alpha.55: коды `engine.blockers` с понятным текстом и тем, кто должен действовать (`null` — никто, работа ждёт очереди)
|
|
208
|
-
| `dependsOn?` | P2: зависимости узла в графе, для полосы плана (§5.1)
|
|
209
|
-
| `target? {repositoryId, ref, acceptedSha?, remote}` | P2: принято локально; `remote.state` (`pushed`, `not-pushed`, `unknown`) по локальной remote-tracking ref, без fetch
|
|
210
|
-
| `question?` | `status.works[].input` (`requestId, state, severity`)
|
|
211
|
-
| `spend {calls, usd: Bounded, durationMs}` | `stage.spend`: собственные записи вызовов работы, по правилам стоимости отчёта (§3.7)
|
|
192
|
+
| Поле | Источник в harness |
|
|
193
|
+
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
194
|
+
| `id, graphId, status, resultSha?` | `status.works[]` |
|
|
195
|
+
| `title?` | заголовок узла графа, замаскирован и обрезан до 120 символов (§9); убирается с `--no-titles` |
|
|
196
|
+
| `stage {name, step?, since?, next[], needs?}` | `status.works[].stage` (alpha.54: `queued, blocked, prepare, writer, gates, review, integration, input, stopped, done, cancelled`) |
|
|
197
|
+
| `stage.typical? {p50Ms, p90Ms, samples}` | P2: наблюдаемая длительность этого этапа в этом состоянии; нет, пока образцов меньше минимума (предложено 5, §11) |
|
|
198
|
+
| `attempts.used / max / left` | `attemptSummaryView()`: учтённые `work.attempt` против `maxAttempts` |
|
|
199
|
+
| `attempts.failed` | `attemptSummaryOf()`: учтённые сбои; прерывания при остановке не считаются |
|
|
200
|
+
| `attempts.interrupted` | попытки с `interruptedByShutdown`; попытку они не расходуют |
|
|
201
|
+
| `attempts.rechecks` | записи доказательств с `recheck: true` по всем попыткам работы |
|
|
202
|
+
| `attempts.neutral {used, max}` | `work.neutralFailures` против `MAX_NEUTRAL_FAILURES` |
|
|
203
|
+
| `attempts.line` | `attemptSummaryLine` |
|
|
204
|
+
| `attempts.lastFailure? {attempt, bucket, plain, at?}` | alpha.55: почему остановилась прошлая попытка; `bucket` из `failureBucketOf`, `plain` — шаблон и маскированная деталь, до 160 символов |
|
|
205
|
+
| `liveness?` | `status.works[].liveness` (`quiet`, `stalled`; `active`, когда работа движется) |
|
|
206
|
+
| `runtime?, model?` | активная попытка |
|
|
207
|
+
| `blockers[] {code, plain?, actor}` | alpha.55: коды `engine.blockers` с понятным текстом и тем, кто должен действовать (`null` — никто, работа ждёт очереди) |
|
|
208
|
+
| `dependsOn?` | P2: зависимости узла в графе, для полосы плана (§5.1) |
|
|
209
|
+
| `target? {repositoryId, ref, acceptedSha?, remote}` | P2: принято локально; `remote.state` (`pushed`, `not-pushed`, `unknown`) по локальной remote-tracking ref, без fetch; с ревизии 2 ещё `remote.checkedAt?` и `remote.line?` (§3.9) |
|
|
210
|
+
| `question?` | `status.works[].input` (`requestId, state, severity`) |
|
|
211
|
+
| `spend {calls, usd: Bounded, durationMs}` | `stage.spend`: собственные записи вызовов работы, по правилам стоимости отчёта (§3.7) |
|
|
212
212
|
|
|
213
213
|
`blockers[]` в черновике был массивом строк; объекты заменяют его до
|
|
214
214
|
фиксации версии 1. Это единственное обязательное поле среди новых:
|
|
@@ -287,6 +287,18 @@ createdAt`, а также:
|
|
|
287
287
|
- `plain?` (alpha.55): одна строка обычными словами — что изменится для
|
|
288
288
|
пользователя. Замаскирована, обрезана до 200 символов.
|
|
289
289
|
- `answeredBy?`: alpha.54 `input.answeredBy`.
|
|
290
|
+
- `answerBasis? {by, rule?, reason?, impact, at, line}` (ревизия 1,
|
|
291
|
+
alpha.56): основание последнего ответа — кто ответил (`operator`, `lead`,
|
|
292
|
+
`host`), правило ведущего (`technical` | `severity`, у оператора и хоста
|
|
293
|
+
правила нет), причина ведущего (маскирована, до 200 символов, нет с
|
|
294
|
+
`--no-titles`), влияние вопроса, время и готовая строка `line` на языке
|
|
295
|
+
представления («ответил ведущий (технический вопрос): <причина>»). Панель
|
|
296
|
+
показывает «HH:MM — <line>» под состоянием вопроса и раскрытие «кто и
|
|
297
|
+
почему ответил»; сама строку не составляет. Без `answerBasis` (alpha.55)
|
|
298
|
+
остаётся «ответил: <кто>» по `answeredBy`, а без обоих полей о том, кто
|
|
299
|
+
ответил, ничего не сказано. Детали работы alpha.56 показывают и вопросы
|
|
300
|
+
закрытой работы; у отменённой или заменённой работы состояние вопроса —
|
|
301
|
+
`cancelled` или `superseded` («Вопрос снят», «Вопрос заменён»).
|
|
290
302
|
- `title?`: текст вопроса, замаскированный и затем обрезанный до 200
|
|
291
303
|
символов. Варианты и вложения не включаются. Полный текст доступен через
|
|
292
304
|
`harness input-show` до S5, когда его отдаёт аутентифицированный маршрут
|
|
@@ -362,10 +374,17 @@ createdAt`, а также:
|
|
|
362
374
|
Попытки в час на экране истории суммируются из этих интервалов в UI.
|
|
363
375
|
Перегруппировка интервалов — работа отображения, а не вывод новых данных.
|
|
364
376
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
377
|
+
`history.totals` (ревизия 1, alpha.56; предложение P7) — итоги окна,
|
|
378
|
+
посчитанные harness теми же правилами, что ряды: `attemptsStarted`,
|
|
379
|
+
`attemptsFailed`, `failuresByBucket` (сумма равна `attemptsFailed`),
|
|
380
|
+
`gatesPassed`, `gatesFailed`, `gatesReused`, `reviewRounds {plan, contract,
|
|
381
|
+
code, attempt}`, `spendUsd` (`Bounded`), `wallMs` (время окна, когда шла
|
|
382
|
+
хотя бы одна попытка), `attemptMs` (сумма времени попыток) и `loadPeak`.
|
|
383
|
+
Экран истории показывает их панелью «Итоги окна», и текстовые сводки
|
|
384
|
+
графиков берут числа оттуда. Без итогов (alpha.55) панель говорит, что в
|
|
385
|
+
этой версии harness их нет, — нулей вместо отсутствующих чисел нет; сводки
|
|
386
|
+
тогда, как и раньше, складывают ряды на экране (отображение, а не новые
|
|
387
|
+
данные).
|
|
369
388
|
|
|
370
389
|
### 3.8 health
|
|
371
390
|
|
|
@@ -391,14 +410,41 @@ createdAt`, а также:
|
|
|
391
410
|
|
|
392
411
|
### 3.9 activity[] и decisions[] (P2)
|
|
393
412
|
|
|
394
|
-
`activity[] {at, actor, action, workId?, subject?, plain}` — кто что
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
413
|
+
`activity[] {at, actor, action, workId?, subject?, plain}` — кто что делал
|
|
414
|
+
(ревизия 2, harness `0.1.0-alpha.57`). Источник — записи, которые
|
|
415
|
+
представление уже читает: попытки с их проверками и ревью, раунды ревью
|
|
416
|
+
плана, контракта и кода, вопросы исполнителя и ответы. Новые сверху, не
|
|
417
|
+
больше 50, окно — то же, что у истории (по умолчанию 24 ч, `--window 7d` —
|
|
418
|
+
7 дней); опущенные в окне — `truncated.activity`.
|
|
419
|
+
|
|
420
|
+
- `actor` — кто действовал: `controller` (запустил попытку или проверку,
|
|
421
|
+
принял работу, эскалировал), `writer` (задал вопрос), `reviewer` (вердикт
|
|
422
|
+
раунда), `lead`, `operator` или `host` (ответил на вопрос). Схема держит
|
|
423
|
+
строку открытой: неизвестный исполнитель показывается как есть.
|
|
424
|
+
- `action` — код события: `attempt.started|failed|cancelled|expired|interrupted`,
|
|
425
|
+
`work.accepted`, `gate.passed|failed|recheck|reused|not-launched`,
|
|
426
|
+
`review.approved|changes-requested|escalated`, `question.asked|answered`.
|
|
427
|
+
Неизвестный код показывается как есть.
|
|
428
|
+
- `plain` — фраза harness на языке `--lang`, замаскирована и обрезана
|
|
429
|
+
(200). Панель её не пересказывает и не составляет.
|
|
430
|
+
|
|
431
|
+
**Нет поля — производитель не ведёт ленту** (harness alpha.55 и alpha.56):
|
|
432
|
+
экран пишет «harness этой версии не ведёт ленту». **Пустой список — в окне
|
|
433
|
+
ничего не происходило**: «за окно (24 ч) ничего не происходило». Пустое
|
|
434
|
+
представление без состояния выдаёт `[]`. Вынести ли ленту в отдельный
|
|
435
|
+
документ — открытое решение (§11).
|
|
436
|
+
|
|
437
|
+
`works[].target.remote` с ревизии 2 (alpha.57) несёт настоящее состояние:
|
|
438
|
+
`pushed` — принятый коммит в истории удалённой ветки, `not-pushed` — ещё
|
|
439
|
+
нет, `unknown` — удалённой ветки нет или git её не прочитал (с `reason`).
|
|
440
|
+
`checkedAt?` — когда git на этой машине последний раз обновил копию
|
|
441
|
+
удалённой ветки (reflog; без reflog поля нет). `line?` — готовая строка на
|
|
442
|
+
языке представления: «уже в удалённой ветке origin/main», «принято
|
|
443
|
+
локально; в удалённой ветке origin/main ещё нет», «неизвестно (нет
|
|
444
|
+
удалённой ветки)». Harness читает только локальные ref, config и reflog —
|
|
445
|
+
без `git fetch` и без сети, поэтому состояние может отставать до
|
|
446
|
+
следующего `fetch` или `push` на этой машине. До alpha.57 состояние всегда
|
|
447
|
+
`unknown` с причиной.
|
|
402
448
|
|
|
403
449
|
`decisions[] {id, kind, by, at, workId?, subject?, findingId?, requestId?,
|
|
404
450
|
temporary, revisit?, title?, reason?}` — решения, принятые по ходу работы:
|
|
@@ -448,7 +494,8 @@ temporary, revisit?, title?, reason?}` — решения, принятые по
|
|
|
448
494
|
| `activity[].plain` | 200 |
|
|
449
495
|
| `decisions[].title`, `decisions[].revisit` | 200 |
|
|
450
496
|
| `decisions[].reason` | 400 |
|
|
451
|
-
| `target.remote.reason`, `
|
|
497
|
+
| `target.remote.reason`, `target.remote.line` | 200 |
|
|
498
|
+
| `drift[].unavailable` | 200 |
|
|
452
499
|
| `progress.queue.detail`, `warnings[].message`, `line` | 200 |
|
|
453
500
|
|
|
454
501
|
Строки настроек — имена моделей, id и перечисления. Id следуют схемам
|
|
@@ -551,11 +598,16 @@ at?}`.
|
|
|
551
598
|
- неизвестное состояние бюджета считается `undetermined`;
|
|
552
599
|
- неизвестный `how` проверки показывается как «способ неизвестен», не как
|
|
553
600
|
«проверено»;
|
|
554
|
-
- неизвестное `remote.state` — как «неизвестно», не как
|
|
601
|
+
- неизвестное `remote.state` — как «неизвестно», не как «отправлено»,
|
|
602
|
+
даже если его `line` говорит иное; состояние решает только `state`, у
|
|
603
|
+
`unknown` панель пишет причину (`reason`).
|
|
555
604
|
- Поиск идёт только по собственным свойствам, поэтому `__proto__` и похожие
|
|
556
605
|
ключи показываются как текст.
|
|
557
|
-
-
|
|
558
|
-
|
|
606
|
+
- Сборка знает ревизию 2 (`KNOWN_VIEW_REVISION`, harness
|
|
607
|
+
`0.1.0-alpha.57`) и полностью рисует ревизии 1 (`0.1.0-alpha.56`) и 0
|
|
608
|
+
(`0.1.0-alpha.55`): поля ревизий 1 и 2 необязательны, и их отсутствие
|
|
609
|
+
никогда не показывается нулём. Когда `viewRevision` новее, чем знает сборка, приложение пишет
|
|
610
|
+
«данные новее панели — обновите панель, чтобы видеть всё».
|
|
559
611
|
- Любая другая мажорная версия отклоняется с `VIEW_VERSION_UNSUPPORTED` и
|
|
560
612
|
подсказкой, как исправить. UI не угадывает.
|
|
561
613
|
- HTTP 409 сохраняет код и сообщение при прохождении через
|
|
@@ -703,7 +755,7 @@ Desktop (≥ 1024 px)
|
|
|
703
755
|
│ код, ревью прочитал diff, ничего не запускал (codex) │
|
|
704
756
|
│ e2e не проверялось │
|
|
705
757
|
├───────────────────────────────────────────────────────────────┤
|
|
706
|
-
│ Принято:
|
|
758
|
+
│ Принято: ещё нет (после приёмки: локально; в удалённой ветке) │
|
|
707
759
|
│ Дрейф после приёмки: — │
|
|
708
760
|
└───────────────────────────────────────────────────────────────┘
|
|
709
761
|
```
|
|
@@ -716,10 +768,22 @@ Desktop (≥ 1024 px)
|
|
|
716
768
|
проверено, как (`how`) и кем (`by`). Слова «проверено» без способа нет.
|
|
717
769
|
Ревью, которое читало diff, так и подписано: «прочитал diff, ничего не
|
|
718
770
|
запускал». Без `verification` — «нет сведений о проверках».
|
|
719
|
-
- **«Принято локально / в
|
|
720
|
-
|
|
721
|
-
remote-tracking ref без fetch
|
|
722
|
-
|
|
771
|
+
- **«Принято локально / в удалённой ветке»** — из `resultSha` и `target`.
|
|
772
|
+
Состояние удалённой ветки harness берёт из её копии на этой машине
|
|
773
|
+
(remote-tracking ref) без fetch и без сети. У `pushed` и `not-pushed`
|
|
774
|
+
панель называет состояние словами строки harness, но из самого
|
|
775
|
+
`remote.state` и ветки из `trackingRef`: «Принято локально; в удалённой
|
|
776
|
+
ветке origin/main ещё нет.», «Принято локально; уже в удалённой ветке
|
|
777
|
+
origin/main.» Строку `remote.line` панель не цитирует: harness обрезает
|
|
778
|
+
её до 200 символов, и при длинном имени ветки обрезка срезает «ещё нет» —
|
|
779
|
+
отрицательное состояние читалось бы как утвердительное (предложение P9).
|
|
780
|
+
Ниже — «Сверено с копией удалённой ветки на этой машине, без сети; git
|
|
781
|
+
обновил копию: вчера 20:30» из `remote.checkedAt` (сегодня — только
|
|
782
|
+
время, вчера — «вчера», раньше — дата); без `checkedAt` — «когда git
|
|
783
|
+
обновлял копию — неизвестно». Рядом раскрытие «в удалённой ветке: что
|
|
784
|
+
это значит» (§12); в обзоре — одно на список. `unknown` и незнакомое
|
|
785
|
+
состояние — «неизвестно» с причиной, никогда не «нет» и не «отправлено».
|
|
786
|
+
У alpha.55 и alpha.56 состояние всегда `unknown` с причиной.
|
|
723
787
|
- При 390 px колонки складываются так: сейчас, этапы, почему повтор,
|
|
724
788
|
что проверено, расходы и что мешает, ревью, принято, дрейф. Этапы
|
|
725
789
|
становятся вертикальным списком.
|
|
@@ -768,15 +832,31 @@ Desktop (≥ 1024 px)
|
|
|
768
832
|
|
|
769
833
|
```
|
|
770
834
|
┌────────────────────────────────────────────────────────────────────┐
|
|
771
|
-
│
|
|
772
|
-
│
|
|
773
|
-
│
|
|
835
|
+
│ События harness за последние 24 ч, новые сверху. │
|
|
836
|
+
│ Работа: все · locale-format · export-csv · add-greeting │
|
|
837
|
+
│ Кто: все · контроллер · исполнитель · ведущий · reviewer │
|
|
838
|
+
│ 11:51 [контроллер] контроллер запустил проверку lint: прошла │
|
|
839
|
+
│ (работа locale-format, попытка 2, кандидат) locale-format │
|
|
840
|
+
│ 11:40 [исполнитель] исполнитель задал вопрос q-17 по работе │
|
|
841
|
+
│ export-csv (важность 8) export-csv │
|
|
842
|
+
│ вчера 18:05 [reviewer] reviewer codex одобрил план g1, раунд 2 │
|
|
843
|
+
│ Кто есть кто: контроллер · исполнитель · ведущий — что это значит │
|
|
774
844
|
└────────────────────────────────────────────────────────────────────┘
|
|
775
845
|
```
|
|
776
846
|
|
|
777
|
-
Источник — `activity[]
|
|
778
|
-
|
|
779
|
-
|
|
847
|
+
Источник — `activity[]` (§3.9), новые сверху, как прислал harness, с
|
|
848
|
+
фильтром по работе и по исполнителю (`#/activity?work=&actor=`). Это
|
|
849
|
+
события harness, а не пересказ агента: фраза `plain` показывается как
|
|
850
|
+
написана, рядом — значок исполнителя словами, ссылка на детали работы и
|
|
851
|
+
код события мелким шрифтом. Время — в часовом поясе зрителя: сегодня —
|
|
852
|
+
`ЧЧ:ММ`, вчера — «вчера ЧЧ:ММ», раньше — `ДД.ММ.ГГГГ ЧЧ:ММ`. Ниже ленты —
|
|
853
|
+
раскрытия глоссария для исполнителей, которые в ней есть.
|
|
854
|
+
|
|
855
|
+
- `[]` — «За окно (24 ч) ничего не происходило».
|
|
856
|
+
- Нет поля — «harness этой версии не ведёт ленту», а не «ничего не было».
|
|
857
|
+
- Фильтр без совпадений — «По выбранному фильтру событий нет».
|
|
858
|
+
- `truncated.activity` — «Ещё N событий окна не показано: лента держит 50
|
|
859
|
+
последних».
|
|
780
860
|
|
|
781
861
|
### 5.6 Настройки (`#/settings`, только чтение)
|
|
782
862
|
|
|
@@ -813,6 +893,16 @@ reviewer кода и откуда он взят. При 390 px это одна
|
|
|
813
893
|
4. Накопленные расходы против линии бюджета. Кривая пунктирная и подписана
|
|
814
894
|
«нижняя граница», когда `spendBound` равно `lower`.
|
|
815
895
|
|
|
896
|
+
Над графиками — панель «Итоги окна» из `history.totals`: начато и
|
|
897
|
+
неудачных попыток (неудачные — по причинам), проверки, раунды ревью по
|
|
898
|
+
видам, расход за окно с границей, время, когда шли попытки, сумма времени
|
|
899
|
+
попыток и пик нагрузки. У каждой строки своё «что это значит», у расхода —
|
|
900
|
+
ещё и его граница («≥» или «неизвестно»). Граница кривой расходов — более
|
|
901
|
+
осторожная из `spendBound` и `totals.spendUsd.bound`: окно без известной
|
|
902
|
+
цены ни одного вызова — «неизвестно», а не «≥ $0.00»; тогда кривая не
|
|
903
|
+
рисуется, а таблица данных пишет «неизвестно». Без итогов (harness
|
|
904
|
+
alpha.55) панель так и пишет.
|
|
905
|
+
|
|
816
906
|
Окно по умолчанию — 24 ч; переключатель на 7 дней работает, только когда
|
|
817
907
|
производитель отдаёт это окно. При 390 px графики идут друг под другом во
|
|
818
908
|
всю ширину высотой 120 px с тремя подписями оси.
|
|
@@ -885,7 +975,8 @@ npx devcontour-harness-ui --demo --lang ru # срез S2, язык ин
|
|
|
885
975
|
файл.
|
|
886
976
|
|
|
887
977
|
**Окно истории (S3).** `--window 24h|7d` передаётся в живые маршруты
|
|
888
|
-
(`--state`, `--from`) как
|
|
978
|
+
(`--state`, позже `--from`) как есть; только если `capabilities` объявляет
|
|
979
|
+
`window` у операции `view`, иначе CLI отказывает с `HARNESS_VIEW_UNAVAILABLE`. По умолчанию окно 24 ч, 7 дней — по запросу.
|
|
889
980
|
Для `--view` окно задаёт тот, кто записал файл.
|
|
890
981
|
|
|
891
982
|
**Контракт обмена.** Один контракт покрывает и CLI панели, и предложенный
|
|
@@ -899,9 +990,22 @@ npx devcontour-harness-ui --demo --lang ru # срез S2, язык ин
|
|
|
899
990
|
id проверяется по алфавиту id графа (`[A-Za-z0-9_-]{1,80}`), иначе 404.
|
|
900
991
|
У файла `--view` деталей нет (503 `VIEW_UNAVAILABLE`); `--demo` отдаёт
|
|
901
992
|
встроенные детали двух работ и русские тексты harness для `?lang=ru`.
|
|
902
|
-
- `GET /api/events` — поток SSE.
|
|
903
|
-
`
|
|
904
|
-
|
|
993
|
+
- `GET /api/events[?lang=][&work=<id>]` — поток SSE (S3). Данные каждого
|
|
994
|
+
события — один объект JSON; `token` — дайджест содержимого (§6
|
|
995
|
+
«Обновления»), а не `source.token`:
|
|
996
|
+
- `event: view` `{token, checkedAt}` — дайджест отличается от последнего
|
|
997
|
+
отправленного (первое событие потока — тоже `view`);
|
|
998
|
+
- `event: fresh` `{token, checkedAt}` — живой маршрут проверил снова, то же
|
|
999
|
+
содержимое; у файла — только первая удачная проверка после сбоя;
|
|
1000
|
+
- `event: stale` `{code, message, since, checkedAt}` — проверка не удалась
|
|
1001
|
+
(отказ harness, сбой, таймаут, файл не читается); `since` — первый сбой
|
|
1002
|
+
подряд;
|
|
1003
|
+
- `event: ping` `{}` каждые 15 с, чтобы страница отличала мёртвый поток.
|
|
1004
|
+
|
|
1005
|
+
Не больше 32 потоков на сервер, лишний получает 503. Неизвестный `work`
|
|
1006
|
+
— 404, работа без документа деталей у файла — 503.
|
|
1007
|
+
|
|
1008
|
+
- `GET /api/health` возвращает `{ok, version, readOnly, live, lang?}`; `live` — `state` (живой `harness view`) или `file`.
|
|
905
1009
|
|
|
906
1010
|
Лента активности пока входит в документ обзора (`activity[]`, 50 последних
|
|
907
1011
|
записей). Отдельный маршрут `GET /api/view?activity=1` с более длинным
|
|
@@ -959,7 +1063,8 @@ capabilities`. Если в каталоге нет операции `view` (harn
|
|
|
959
1063
|
умолчанию `harness` из PATH).
|
|
960
1064
|
- Позже (P3) маршрут перейдёт на `harness serve-view` дочерним процессом
|
|
961
1065
|
с прокси `/api/*` и SSE; договор `/api/view` не меняется.
|
|
962
|
-
- `--from <url>` (S3
|
|
1066
|
+
- `--from <url>` (S3, ещё не сделано: в harness `0.1.0-alpha.55` нет
|
|
1067
|
+
`serve-view`) проксирует к уже запущенному `serve-view`. Адрес
|
|
963
1068
|
проверяется до первого запроса:
|
|
964
1069
|
- схема должна быть `http:`;
|
|
965
1070
|
- хост должен быть литералом `127.0.0.1` или `[::1]`, либо `localhost`,
|
|
@@ -972,9 +1077,89 @@ capabilities`. Если в каталоге нет операции `view` (harn
|
|
|
972
1077
|
**Без телеметрии.** Нет аналитики, запросов шрифтов или CDN и проверки
|
|
973
1078
|
обновлений. Сборка самодостаточна.
|
|
974
1079
|
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
1080
|
+
**Обновления (S3).** У harness `0.1.0-alpha.55` нет канала изменений
|
|
1081
|
+
(`serve-view` — предложение P3), поэтому изменения замечает сам CLI панели и
|
|
1082
|
+
отправляет их странице по `/api/events`:
|
|
1083
|
+
|
|
1084
|
+
- **Только пока страница открыта.** Наблюдение за документом существует,
|
|
1085
|
+
пока его держит хотя бы один поток. Без потоков нет ни таймеров, ни `stat`,
|
|
1086
|
+
ни запусков harness: панель без открытой страницы не тратит процессор.
|
|
1087
|
+
- **Подсказка и проверка.** Каждую 1 с сервер сравнивает дешёвую подпись
|
|
1088
|
+
файлов (mtime, размер, inode): у `--state` — каталога состояния,
|
|
1089
|
+
`state.sqlite`, `state.sqlite-wal` и файла политики, у `--view` — самого
|
|
1090
|
+
файла. Изменение подписи сразу запускает проверку: у `--state` — `harness
|
|
1091
|
+
view`, у `--view` — чтение файла.
|
|
1092
|
+
- **Дайджест.** Изменение определяет идентичность содержимого. С ревизии
|
|
1093
|
+
представления 1 (harness `0.1.0-alpha.56`, предложение P8) это сам
|
|
1094
|
+
`source.token` (`harness:` и SHA-256 строки токена — так любая строка
|
|
1095
|
+
безопасна для заголовка и одинакова в SSE и `x-hui-digest`): harness хеширует содержимое без часов
|
|
1096
|
+
проекции и сам меняет токен, когда от часов зависит содержимое (аренда,
|
|
1097
|
+
живость, запись вышла из окна или переехала в соседний интервал). Язык и
|
|
1098
|
+
работа, от которых токен ещё зависит, разделены ключом наблюдения. Подписи
|
|
1099
|
+
окна истории при этом не двигаются, пока не изменилось содержимое: строка
|
|
1100
|
+
свежести говорит «без изменений с HH:MM». У ревизии 0 (`0.1.0-alpha.55`)
|
|
1101
|
+
токен хеширует и границы окна и разный при каждом запуске, поэтому панель
|
|
1102
|
+
считает свой дайджест: SHA-256 документа без `generatedAt` и
|
|
1103
|
+
`source.token`, с границами окна, обрезанными до минуты (неизменное
|
|
1104
|
+
состояние — тот же дайджест в пределах минуты). Пустой токен ревизии 1
|
|
1105
|
+
тоже получает этот дайджест (документ без строки `source.token` проверка
|
|
1106
|
+
панели отклоняет). Дайджест файла — SHA-256 всех байтов
|
|
1107
|
+
(время снимка — его содержимое). `GET /api/view` и `/api/work/<id>`
|
|
1108
|
+
отдают дайджест в заголовке `x-hui-digest`; `ETag` — хеш байтов ответа.
|
|
1109
|
+
- **Интервал с отступлением (`--state`).** Без изменения подписи сервер
|
|
1110
|
+
перепроверяет через 2 с, затем через 4, 8 и 15 с, пока ничего не меняется;
|
|
1111
|
+
изменение возвращает 2 с. Пока в представлении есть работающие попытки
|
|
1112
|
+
(`progress.running > 0`), интервал не больше 5 с: аренды и живость меняются
|
|
1113
|
+
без записи в хранилище (§3.10). Неудачная проверка тоже отступает. Файл
|
|
1114
|
+
`--view` проверяется только по изменению подписи.
|
|
1115
|
+
- **Повторное использование.** `GET /api/view` в течение 1,5 с после
|
|
1116
|
+
удачной проверки берёт её результат, а не запускает harness ещё раз (не
|
|
1117
|
+
больше 64 таких результатов, отказы не хранятся). Проверка, которая ждёт
|
|
1118
|
+
свободного места среди `MAX_RUNS` запусков, не запускается, если её
|
|
1119
|
+
наблюдение уже закончилось.
|
|
1120
|
+
- **Медленный читатель.** Поток, у которого не отправлено больше 64 КБ,
|
|
1121
|
+
закрывается, а не копит события.
|
|
1122
|
+
- **Восстановление.** Первая удачная проверка после сбоя всегда даёт событие
|
|
1123
|
+
(`view` или `fresh`), даже у файла с прежним содержимым.
|
|
1124
|
+
- **Страница.** Пока поток не прислал первое событие, страница опрашивает
|
|
1125
|
+
`GET /api/view` каждые 5 с. Получив `view` с токеном, отличным от токена
|
|
1126
|
+
документа на экране (его `x-hui-digest`), она загружает документ; `fresh`
|
|
1127
|
+
с тем же дайджестом только обновляет время проверки. Неудачная загрузка
|
|
1128
|
+
повторяется опросом раз в 5 с, пока не удастся, даже когда поток жив; так
|
|
1129
|
+
же повторяется и первый отказ `VIEW_UNAVAILABLE`. Загрузки идут по одной
|
|
1130
|
+
(запрос во время загрузки — ещё одна загрузка после неё); подтверждение
|
|
1131
|
+
показанного содержимого и скрытие вкладки отменяют ответ загрузки, которая
|
|
1132
|
+
ещё идёт. Загрузка без ответа 40 с считается неудачной и повторяется опросом. Скрытая вкладка не опрашивает никогда.
|
|
1133
|
+
Экран работы держит только поток деталей: поток обзора на нём закрыт. Ошибка потока или 45 с тишины (нет даже `ping`) — страница
|
|
1134
|
+
закрывает поток, переходит на опрос раз в 5 с и пробует поток снова через
|
|
1135
|
+
30 с. Скрытая вкладка закрывает поток и останавливает опрос; при показе
|
|
1136
|
+
страница сразу загружает документ и открывает поток.
|
|
1137
|
+
- **Свежесть.** Над экраном строка «Данные на HH:MM · обновляются сами»
|
|
1138
|
+
(`--state`), «… · снимок; при изменении файла страница обновится»
|
|
1139
|
+
(`--view`) или «… · проверка раз в 5 секунд» (опрос). Время — `generatedAt`
|
|
1140
|
+
документа или, у `--state`, более позднее время проверки того же
|
|
1141
|
+
содержимого («без изменений с HH:MM»). Когда проверка не удалась (`stale`
|
|
1142
|
+
или 503 после удачного документа), над ней предупреждение «Не удалось
|
|
1143
|
+
обновить данные с HH:MM: <причина>. На экране данные на HH:MM — они могут
|
|
1144
|
+
быть устаревшими»; неизвестное не показывается свежим.
|
|
1145
|
+
- **Встраивание.** `ViewSource.subscribe(onChange, {workId?})` передаёт
|
|
1146
|
+
`LiveEvent` (`view`, `fresh`, `stale`, `down`); вызов `onChange()` без
|
|
1147
|
+
события значит «загрузите снова». `httpViewSource` даёт `subscribe`, только
|
|
1148
|
+
когда есть `EventSource`.
|
|
1149
|
+
|
|
1150
|
+
Измерения (macOS, harness `0.1.0-alpha.55`, пустое состояние, `harness view`
|
|
1151
|
+
≈ 0,25 с процессора) — в описании ветки; без страницы панель за 120 с не
|
|
1152
|
+
запустила harness ни разу.
|
|
1153
|
+
|
|
1154
|
+
**Совместимость (`--check`, S3).** `devcontour-harness-ui --check [--harness
|
|
1155
|
+
<bin>] [--state <dir> [--policy <file>]]` запускает `harness --version`,
|
|
1156
|
+
`harness capabilities` и, с `--state`, один `harness view`, затем печатает
|
|
1157
|
+
одну строку `{ok, harness, ui, viewVersion, uiViewVersion, compatible, fix?,
|
|
1158
|
+
view?}`. `viewVersion` берётся из выходной схемы операции `view` в каталоге
|
|
1159
|
+
(или из прочитанного представления); не объявленная версия — `null` и
|
|
1160
|
+
`compatible: false`, пока не прочитано представление. Выход 0 — совместимо,
|
|
1161
|
+
3 — нет (с `fix`). Отказ harness на этом состоянии при совпадающих версиях
|
|
1162
|
+
— `compatible: true` с `fix` и `view.ok: false`.
|
|
978
1163
|
|
|
979
1164
|
## 7. API встраивания (DevContour)
|
|
980
1165
|
|
|
@@ -1129,7 +1314,7 @@ loopback. Пока P1 не выпущен, свободные тексты в п
|
|
|
1129
1314
|
- `questions[].plain`;
|
|
1130
1315
|
- `activity[].plain`;
|
|
1131
1316
|
- `decisions[].title`, `decisions[].reason` и `decisions[].revisit`;
|
|
1132
|
-
- `target.remote.reason`.
|
|
1317
|
+
- `target.remote.reason` и `target.remote.line`.
|
|
1133
1318
|
|
|
1134
1319
|
Секрет может разрезаться пополам на границе обрезки и проскочить, поэтому
|
|
1135
1320
|
маскирование выполняется **до** обрезки. Шаг маскирования:
|
|
@@ -1373,6 +1558,24 @@ build`. Тесты не используют сеть дальше loopback, и
|
|
|
1373
1558
|
30 с на голову цели; `git fetch` не запускается ни разу (тест по
|
|
1374
1559
|
журналу команд git).
|
|
1375
1560
|
- Тесты: интеграция CLI на fixture runtime harness, без живых моделей.
|
|
1561
|
+
- Сделано без `serve-view` (harness `0.1.0-alpha.55` его не выдаёт):
|
|
1562
|
+
- вместо дочернего `serve-view` — наблюдение в самом CLI панели (§6
|
|
1563
|
+
«Обновления»): подсказка по mtime, перепроверка `harness view` с
|
|
1564
|
+
отступлением, SSE `/api/events`, запасной опрос, пауза скрытой вкладки,
|
|
1565
|
+
строка свежести и предупреждение об устаревших данных;
|
|
1566
|
+
- `--window 24h|7d`, `--check`, навык на живом маршруте;
|
|
1567
|
+
- тесты: `tests/live.test.ts` (нет страницы — нет запусков; изменение
|
|
1568
|
+
доходит за 2 с при интервалах по умолчанию; отступление и сброс;
|
|
1569
|
+
отказ и таймаут harness — `stale` с первым временем сбоя; повторное
|
|
1570
|
+
использование для `GET`; файл), `tests/subscribe.test.ts`,
|
|
1571
|
+
`tests/cli.test.ts` (`--check`, `--window`), `e2e/live.spec.ts`
|
|
1572
|
+
(изменение файла на открытой странице за 2 с, «устаревшие» при
|
|
1573
|
+
пропавшем файле, скрытая вкладка без запусков harness, опрос при
|
|
1574
|
+
заблокированном потоке).
|
|
1575
|
+
- Осталось до P3 в harness: `--from <url>`, дочерний `serve-view`, кэш
|
|
1576
|
+
дрейфа по голове цели (30 с) и проверка «ни одного `git fetch`» — это
|
|
1577
|
+
поведение `serve-view`; пустое представление при отсутствующем каталоге
|
|
1578
|
+
с политикой и `POLICY_REQUIRED` без неё уже делает `harness view`.
|
|
1376
1579
|
|
|
1377
1580
|
**S4: встраивание в DevContour.**
|
|
1378
1581
|
|
|
@@ -1452,24 +1655,35 @@ build`. Тесты не используют сеть дальше loopback, и
|
|
|
1452
1655
|
|
|
1453
1656
|
Тексты «что это значит» на экране берутся отсюда.
|
|
1454
1657
|
|
|
1455
|
-
| Термин | Что это значит
|
|
1456
|
-
| ------------------------ |
|
|
1457
|
-
| Этап | Шаг, на котором сейчас работа: очередь, подготовка, написание, проверки, ревью, интеграция, ожидание ответа.
|
|
1458
|
-
| Ведущий (lead) | Агент, который ведёт проект от вашего имени: запускает harness, читает результаты, отвечает на вопросы, которые ему разрешены.
|
|
1459
|
-
| Исполнитель, writer | Агент, который пишет код одной работы в отдельной копии репозитория.
|
|
1460
|
-
| Reviewer, ревью | Другой агент читает план или изменения и пишет замечания. Ревью кода читает diff и ничего не запускает, если это не сказано отдельно.
|
|
1461
|
-
| Проверки, gates | Команды проекта (тесты, lint, сборка), которые harness запускает над изменением. Результат пишется вместе со способом: запущено, взято прежнее, не проверялось.
|
|
1462
|
-
| Перепроверка | Повторный запуск проверки на той же попытке, чтобы отличить настоящую ошибку от случайной.
|
|
1463
|
-
| Попытка | Один заход исполнителя над работой. У работы ограниченное число попыток; прерывание при остановке попытку не расходует.
|
|
1464
|
-
| Нейтральный сбой | Сбой не по вине кода (например, окружение), который не расходует попытку, но имеет свой предел.
|
|
1465
|
-
| Интеграция | Перенос принятого изменения в целевую ветку с проверками на результате.
|
|
1466
|
-
| Принято | Работа прошла проверки и ревью, и harness записал результат в целевую ветку локально. «В удалённом репозитории» — отдельный факт: туда результат отправляет человек или ведущий по вашей просьбе.
|
|
1467
|
-
| Дрейф | Целевая ветка изменилась после приёмки, и принятый результат стоит не на её вершине.
|
|
1468
|
-
| Эскалация | Блокирующее замечание не решилось за несколько раундов ревью, и решение переходит к вам.
|
|
1469
|
-
| Временное решение | Решение «пока так», с условием, когда к нему вернуться.
|
|
1470
|
-
| Технический вопрос | Вопрос, ответ на который не меняет результат для пользователя. Его может решать ведущий, если это включено в настройках.
|
|
1471
|
-
| Нижняя граница (`≥`) | Часть цен неизвестна, поэтому показанная сумма — минимум, настоящая может быть больше.
|
|
1472
|
-
| Неизвестно, не проверено | У harness нет сведений. Это не ноль и не «в порядке».
|
|
1473
|
-
| Контроллер | Процесс harness, который сейчас ведёт очередь. Без него работа не продвигается.
|
|
1474
|
-
| Зависшая / тихая попытка | Попытка давно не подавала признаков жизни (тихая) или дольше порога (зависшая).
|
|
1475
|
-
| Ждёт очереди | Работа ждёт свободного места или окончания работ, от которых зависит. Ничего делать не нужно.
|
|
1658
|
+
| Термин | Что это значит |
|
|
1659
|
+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1660
|
+
| Этап | Шаг, на котором сейчас работа: очередь, подготовка, написание, проверки, ревью, интеграция, ожидание ответа. |
|
|
1661
|
+
| Ведущий (lead) | Агент, который ведёт проект от вашего имени: запускает harness, читает результаты, отвечает на вопросы, которые ему разрешены. |
|
|
1662
|
+
| Исполнитель, writer | Агент, который пишет код одной работы в отдельной копии репозитория. |
|
|
1663
|
+
| Reviewer, ревью | Другой агент читает план или изменения и пишет замечания. Ревью кода читает diff и ничего не запускает, если это не сказано отдельно. |
|
|
1664
|
+
| Проверки, gates | Команды проекта (тесты, lint, сборка), которые harness запускает над изменением. Результат пишется вместе со способом: запущено, взято прежнее, не проверялось. |
|
|
1665
|
+
| Перепроверка | Повторный запуск проверки на той же попытке, чтобы отличить настоящую ошибку от случайной. |
|
|
1666
|
+
| Попытка | Один заход исполнителя над работой. У работы ограниченное число попыток; прерывание при остановке попытку не расходует. |
|
|
1667
|
+
| Нейтральный сбой | Сбой не по вине кода (например, окружение), который не расходует попытку, но имеет свой предел. |
|
|
1668
|
+
| Интеграция | Перенос принятого изменения в целевую ветку с проверками на результате. |
|
|
1669
|
+
| Принято | Работа прошла проверки и ревью, и harness записал результат в целевую ветку локально. «В удалённом репозитории» — отдельный факт: туда результат отправляет человек или ведущий по вашей просьбе. |
|
|
1670
|
+
| Дрейф | Целевая ветка изменилась после приёмки, и принятый результат стоит не на её вершине. |
|
|
1671
|
+
| Эскалация | Блокирующее замечание не решилось за несколько раундов ревью, и решение переходит к вам. |
|
|
1672
|
+
| Временное решение | Решение «пока так», с условием, когда к нему вернуться. |
|
|
1673
|
+
| Технический вопрос | Вопрос, ответ на который не меняет результат для пользователя. Его может решать ведущий, если это включено в настройках. |
|
|
1674
|
+
| Нижняя граница (`≥`) | Часть цен неизвестна, поэтому показанная сумма — минимум, настоящая может быть больше. |
|
|
1675
|
+
| Неизвестно, не проверено | У harness нет сведений. Это не ноль и не «в порядке». |
|
|
1676
|
+
| Контроллер | Процесс harness, который сейчас ведёт очередь. Без него работа не продвигается. |
|
|
1677
|
+
| Зависшая / тихая попытка | Попытка давно не подавала признаков жизни (тихая) или дольше порога (зависшая). |
|
|
1678
|
+
| Ждёт очереди | Работа ждёт свободного места или окончания работ, от которых зависит. Ничего делать не нужно. |
|
|
1679
|
+
| Кто и почему ответил | Кто дал последний ответ на вопрос исполнителя: вы, ведущий или хост. Ведущий отвечает только по правилу из настроек и записывает причину; её показывает harness. |
|
|
1680
|
+
| Причина неудачи | Группа, к которой harness отнёс неудачную попытку: ошибка в коде, окружение, время вышло и другие. Числа по группам складываются в число неудачных попыток. |
|
|
1681
|
+
| Раунд ревью | Одно прочтение плана, контракта или изменений reviewer и его ответ с замечаниями. Повтор вызова после сбоя отдельным раундом не считается. |
|
|
1682
|
+
| Время, когда шли попытки | Сколько времени окна хотя бы одна попытка работала. Две попытки одновременно считаются один раз. |
|
|
1683
|
+
| Сумма времени попыток | Время всех попыток окна, сложенное: две попытки по часу одновременно дают 2 ч. |
|
|
1684
|
+
| Расход за окно | Стоимость вызовов агентов, которые harness относит к окну, по правилам своего отчёта. «≥» — у части вызовов цена или учёт неизвестны или неполны; «неизвестно» — ни у одного вызова окна нет известной цены. |
|
|
1685
|
+
| Пик нагрузки | Наибольшее число попыток, которые шли одновременно в окне; сравнивается с числом мест. |
|
|
1686
|
+
| Обычное время этапа | Сколько этап занимал раньше в этом состоянии (не меньше пяти замеров): половина укладывалась в первое число, девять из десяти — во второе. Наблюдение, а не обещание. |
|
|
1687
|
+
| Вы, оператор | Человек, для которого идёт работа. Отвечает на вопросы, которые меняют результат для пользователя, и решает эскалации. |
|
|
1688
|
+
| Хост | Программа, внутри которой запущен harness (например, DevContour). Может ответить на вопрос исполнителя от своего имени по своим правилам. |
|
|
1689
|
+
| В удалённой ветке | harness сверяет принятый коммит с копией удалённой ветки на этой машине (remote-tracking ref, например origin/main) — без сети и без git fetch, поэтому сведения могут отставать до следующего git fetch или git push здесь. Время рядом — когда git на этой машине последний раз обновил копию. «Неизвестно» — не «нет» и не «отправлено»; сам harness ничего не отправляет. |
|
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
Это предложения для репозитория harness; в этом репозитории они не
|
|
4
4
|
реализуются. Вместе они дают панели оператора ([design.md](design.md)) один
|
|
5
5
|
источник данных: только для чтения и с версией. P1 и P2 реализованы в
|
|
6
|
-
harness `0.1.0-alpha.55
|
|
7
|
-
(design.md
|
|
6
|
+
harness `0.1.0-alpha.55`, P7 и P8 — в `0.1.0-alpha.56` (ревизия
|
|
7
|
+
представления 1); схемой представления теперь владеет harness (design.md
|
|
8
|
+
§3).
|
|
8
9
|
|
|
9
10
|
Цель панели — чтобы её понимал оператор без технической подготовки. Панель
|
|
10
11
|
показывает данные harness, а не пересказ агента. Поэтому всё, что панель
|
|
@@ -432,6 +433,12 @@ how: executed|reused|read|not-checked, by?, attempt?, at?}`. Предел — 50
|
|
|
432
433
|
|
|
433
434
|
### P6.6. Лента действий (P2, S–M)
|
|
434
435
|
|
|
436
|
+
**Статус: реализовано в 0.1.0-alpha.57** (ревизия представления 2): лента
|
|
437
|
+
— из записей, которые представление уже читает (попытки, проверки, раунды
|
|
438
|
+
ревью, вопросы и ответы); `actor` — `controller`, `writer`, `reviewer`,
|
|
439
|
+
`lead`, `operator`, `host`; `truncated.activity` — опущенные в окне. Лента
|
|
440
|
+
осталась в обзорном документе.
|
|
441
|
+
|
|
435
442
|
- **Что.** Кто что делал: ведущий ↔ harness, writer, reviewer,
|
|
436
443
|
контроллер, оператор.
|
|
437
444
|
- **Источник.** Журнал событий, новые сверху, окно — окно истории (24 ч по
|
|
@@ -451,6 +458,11 @@ how: executed|reused|read|not-checked, by?, attempt?, at?}`. Предел — 50
|
|
|
451
458
|
|
|
452
459
|
### P6.8. Принято локально / в удалённом репозитории (P2, S)
|
|
453
460
|
|
|
461
|
+
**Статус: реализовано в 0.1.0-alpha.57** (ревизия 2): `remote.state`
|
|
462
|
+
настоящий, плюс `checkedAt` (время reflog копии ветки) и готовая строка
|
|
463
|
+
`line` на языке представления. Только локальные ref, config и reflog, без
|
|
464
|
+
сети.
|
|
465
|
+
|
|
454
466
|
- **Что.** Есть ли принятый результат только локально или уже в удалённом
|
|
455
467
|
репозитории.
|
|
456
468
|
- **Источник.** Только локальная remote-tracking ref, без `fetch`. Кеш по
|
|
@@ -493,6 +505,10 @@ temporary, revisit?, title?, reason?}`, предел 50. Тексты маски
|
|
|
493
505
|
|
|
494
506
|
## P7. Итоги окна истории (S)
|
|
495
507
|
|
|
508
|
+
> Реализовано в harness `0.1.0-alpha.56`: `history.totals` с теми же
|
|
509
|
+
> числами, а также `failuresByBucket`, `reviewRounds`, `spendUsd`, `wallMs`
|
|
510
|
+
> и `attemptMs`. Панель показывает их на экране истории (design.md §3.7).
|
|
511
|
+
|
|
496
512
|
Текстовые сводки графиков истории (S2) сейчас суммируют ряды `history` в
|
|
497
513
|
панели: начатые и неудачные попытки, пройденные, проваленные и повторно
|
|
498
514
|
использованные gates, пик нагрузки. Предложение: `history.totals
|
|
@@ -500,6 +516,37 @@ temporary, revisit?, title?, reason?}`, предел 50. Тексты маски
|
|
|
500
516
|
loadPeak}` в проекции, чтобы и эти числа приходили из harness. Добавление
|
|
501
517
|
— новая ревизия представления.
|
|
502
518
|
|
|
519
|
+
## P8. Токен изменений без часов проекции (S)
|
|
520
|
+
|
|
521
|
+
> Реализовано в harness `0.1.0-alpha.56`: токен — SHA-256 содержимого без
|
|
522
|
+
> часов проекции. С ревизии 1 панель берёт `source.token` как идентичность
|
|
523
|
+
> содержимого и считает свой дайджест только для alpha.55 (design.md §6).
|
|
524
|
+
|
|
525
|
+
`source.token` в `0.1.0-alpha.55` хеширует и `history.from`/`history.to`, а
|
|
526
|
+
окно истории заканчивается в `now` с точностью до миллисекунды. Поэтому
|
|
527
|
+
токен разный при каждом запуске `harness view` над неизменным состоянием, и
|
|
528
|
+
по нему нельзя заметить «ничего не изменилось» (§3.10 design.md обещает
|
|
529
|
+
равенство токенов для равного представления). Панель S3 пока считает
|
|
530
|
+
собственный дайджест: без `generatedAt` и `source.token`, с границами окна,
|
|
531
|
+
обрезанными до минуты (`digestOf` в `src/server/serve.ts`).
|
|
532
|
+
|
|
533
|
+
Предложение: исключить границы окна из канонических байтов токена или
|
|
534
|
+
выравнивать конец окна по границе интервала (`bucketMs`), чтобы токен
|
|
535
|
+
менялся только вместе с содержимым. Тест: два запуска над одним состоянием
|
|
536
|
+
с разными часами внутри одного интервала дают один токен.
|
|
537
|
+
|
|
538
|
+
## P9. Строка удалённой ветки не теряет состояние при обрезке (S)
|
|
539
|
+
|
|
540
|
+
`target.remote.line` (alpha.57) обрезается до 200 символов целиком. Имя
|
|
541
|
+
удалённой ветки стоит в середине строки «принято локально; в удалённой
|
|
542
|
+
ветке <имя> ещё нет», поэтому при имени длиннее ~160 символов обрезка
|
|
543
|
+
срезает «ещё нет», и строка читается как утвердительная. Панель поэтому
|
|
544
|
+
строку не цитирует, а пишет состояние из `remote.state` и `trackingRef`.
|
|
545
|
+
|
|
546
|
+
Предложение: обрезать имя ветки внутри строки (с «…»), а слова состояния
|
|
547
|
+
сохранять всегда; или ставить состояние в начало строки. Тест: ветка из
|
|
548
|
+
300 символов — строка ≤ 200 и кончается словами состояния.
|
|
549
|
+
|
|
503
550
|
## Порядок и зависимости
|
|
504
551
|
|
|
505
552
|
1. Работа alpha.54 слита: этап h12, цикл ревью h14, h10 review-code и
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# devcontour-harness-ui 0.1.0-alpha.2
|
|
2
|
+
|
|
3
|
+
Срез S3 дизайна — живые обновления — и чтение ревизий 1 и 2 представления
|
|
4
|
+
(devcontour-harness `0.1.0-alpha.56` и `0.1.0-alpha.57`). Peer прежний:
|
|
5
|
+
devcontour-harness `>=0.1.0-alpha.55 <0.2.0`.
|
|
6
|
+
|
|
7
|
+
Панель по-прежнему полностью работает с ревизиями 0 (`0.1.0-alpha.55`) и 1
|
|
8
|
+
(`0.1.0-alpha.56`): новые поля необязательны, и их отсутствие не
|
|
9
|
+
показывается нулём.
|
|
10
|
+
|
|
11
|
+
## Порядок выпуска
|
|
12
|
+
|
|
13
|
+
1. devcontour-harness `0.1.0-alpha.57` публикуется в npm первым (он
|
|
14
|
+
включает всё из `0.1.0-alpha.56`): без него нет ленты «кто что делал» и
|
|
15
|
+
сведений об удалённой ветке, а без alpha.56 — ещё и оснований ответов,
|
|
16
|
+
итогов окна и токена содержимого.
|
|
17
|
+
2. Затем devcontour-harness-ui `0.1.0-alpha.2`. Панель работает с harness
|
|
18
|
+
`0.1.0-alpha.55` и новее: с более старым harness экраны пишут, что этих
|
|
19
|
+
сведений в этой версии harness нет («harness этой версии не ведёт
|
|
20
|
+
ленту», «в удалённом репозитории — неизвестно» с причиной harness), а с
|
|
21
|
+
alpha.55 изменения определяет собственный дайджест панели.
|
|
22
|
+
|
|
23
|
+
## Живые обновления (S3)
|
|
24
|
+
|
|
25
|
+
- В harness нет канала изменений (`serve-view` — предложение P3), поэтому
|
|
26
|
+
изменения замечает сам CLI панели и отправляет их странице по
|
|
27
|
+
`GET /api/events[?lang=][&work=<id>]` (SSE): `view` — содержимое
|
|
28
|
+
изменилось, `fresh` — проверено снова, то же содержимое, `stale` —
|
|
29
|
+
проверка не удалась (с `since`, временем первого сбоя подряд), `ping`
|
|
30
|
+
каждые 15 с. Не больше 32 потоков на сервер, лишний получает 503.
|
|
31
|
+
- Каждую 1 с сервер сравнивает дешёвую подпись файлов (mtime, размер,
|
|
32
|
+
inode): у `--state` — каталога состояния, `state.sqlite`,
|
|
33
|
+
`state.sqlite-wal` и политики, у `--view` — самого файла. Изменение сразу
|
|
34
|
+
запускает проверку. Без изменений `harness view` перепроверяется через 2,
|
|
35
|
+
4, 8 и 15 с; пока идут попытки — не реже раза в 5 с.
|
|
36
|
+
- **Без открытой страницы harness не запускается.** Наблюдение живёт, пока
|
|
37
|
+
страница держит поток; скрытая вкладка закрывает поток и не опрашивает
|
|
38
|
+
никогда. Без страницы панель за 120 с не запустила harness ни разу.
|
|
39
|
+
- `GET /api/view` и `/api/work/<id>` отдают дайджест содержимого в
|
|
40
|
+
заголовке `x-hui-digest`; в течение 1,5 с после удачной проверки `GET`
|
|
41
|
+
берёт её результат, а не запускает harness ещё раз.
|
|
42
|
+
- Страница: пока поток не прислал первое событие или когда он упал (или 45 с
|
|
43
|
+
тишины), она опрашивает `GET /api/view` раз в 5 с и пробует поток снова
|
|
44
|
+
через 30 с. Загрузки идут по одной; загрузка без ответа **40 с** считается
|
|
45
|
+
неудачной и повторяется опросом, так что один зависший запрос не держит
|
|
46
|
+
остальные. Временный `VIEW_UNAVAILABLE` повторяется, и на первой загрузке
|
|
47
|
+
тоже.
|
|
48
|
+
- **Свежесть.** Над экраном строка «Данные на HH:MM · обновляются сами»
|
|
49
|
+
(`--state`), «… · снимок; при изменении файла страница обновится»
|
|
50
|
+
(`--view`) или «… · проверка раз в 5 секунд» (опрос). Когда проверка не
|
|
51
|
+
удалась — предупреждение «Не удалось обновить данные с HH:MM: <причина>.
|
|
52
|
+
На экране данные на HH:MM — они могут быть устаревшими»; неизвестное не
|
|
53
|
+
показывается свежим. Восстановление объявляется всегда.
|
|
54
|
+
- Встраивание: `ViewSource.subscribe(onChange, {workId?})` передаёт
|
|
55
|
+
`LiveEvent` (`view`, `fresh`, `stale`, `down`); `httpViewSource` даёт
|
|
56
|
+
`subscribe`, только когда есть `EventSource`.
|
|
57
|
+
- `/api/health` возвращает ещё `live`: `state` или `file`.
|
|
58
|
+
|
|
59
|
+
## CLI
|
|
60
|
+
|
|
61
|
+
- `--window 24h|7d` — окно истории для `--state` (по умолчанию окно
|
|
62
|
+
harness, 24 ч). Если harness не объявляет `window` у операции `view` —
|
|
63
|
+
отказ `HARNESS_VIEW_UNAVAILABLE`.
|
|
64
|
+
- `--check [--harness <bin>] [--state <dir> [--policy <file>]]` запускает
|
|
65
|
+
`harness --version`, `harness capabilities` и, с `--state`, один
|
|
66
|
+
`harness view`, затем печатает одну строку `{ok, harness, ui, viewVersion,
|
|
67
|
+
uiViewVersion, compatible, fix?, view?}`. Выход 0 — совместимо, 3 — нет
|
|
68
|
+
(с `fix`).
|
|
69
|
+
- Ещё не сделано: `--from <url>` и дочерний `serve-view` ждут P3 в harness.
|
|
70
|
+
|
|
71
|
+
## Ревизия 1 представления (harness 0.1.0-alpha.56)
|
|
72
|
+
|
|
73
|
+
### Кто и почему ответил
|
|
74
|
+
|
|
75
|
+
- Под состоянием отвеченного вопроса — «HH:MM — <строка harness>»:
|
|
76
|
+
«ответил ведущий (технический вопрос): <причина>», «ответил оператор»
|
|
77
|
+
(`questions[].answerBasis.line`, на языке представления). Панель строку
|
|
78
|
+
не составляет; рядом раскрытие «кто и почему ответил».
|
|
79
|
+
- С alpha.55 (без `answerBasis`) остаётся «ответил: <кто>»; без сведений о
|
|
80
|
+
том, кто ответил, ничего не пишется.
|
|
81
|
+
- Детали работы показывают и вопросы закрытой работы. Состояния
|
|
82
|
+
`cancelled` и `superseded` названы словами: «Вопрос снят», «Вопрос
|
|
83
|
+
заменён».
|
|
84
|
+
|
|
85
|
+
### Итоги окна истории
|
|
86
|
+
|
|
87
|
+
- Экран истории начинается с панели «Итоги окна» из `history.totals`:
|
|
88
|
+
начато и неудачных попыток (неудачные — по причинам), проверки, раунды
|
|
89
|
+
ревью (план, контракт, код, в попытках), расход за окно с честной
|
|
90
|
+
границей («≥» или «неизвестно», не `$0.00`), время, когда шли попытки,
|
|
91
|
+
сумма времени попыток и пик нагрузки. У каждой строки — «что это
|
|
92
|
+
значит», у расхода — ещё и пояснение его границы.
|
|
93
|
+
- Сводки под графиками берут числа из итогов. Граница накопленных расходов
|
|
94
|
+
— более осторожная из `spendBound` и `totals.spendUsd.bound`: окно, где
|
|
95
|
+
цена ни одного вызова не известна, — «неизвестно», а не «≥ $0.00»;
|
|
96
|
+
кривая тогда не рисуется, а таблица данных пишет «неизвестно». Без итогов (alpha.55) панель
|
|
97
|
+
пишет, что в этой версии harness их нет, а сводки, как раньше, складывают
|
|
98
|
+
ряды на экране.
|
|
99
|
+
|
|
100
|
+
### Обычное время этапа
|
|
101
|
+
|
|
102
|
+
- Диапазон короче и честнее: «обычно 5–12 мин» вместо «обычно 5 мин–12
|
|
103
|
+
мин»; нижняя граница округляется вниз, верхняя вверх, «до 2 мин», когда
|
|
104
|
+
нижняя меньше минуты. Несогласованный диапазон (p90 меньше p50) и
|
|
105
|
+
отсутствующее наблюдение не показываются. Рядом — раскрытие «обычное
|
|
106
|
+
время этапа».
|
|
107
|
+
|
|
108
|
+
### Токен содержимого
|
|
109
|
+
|
|
110
|
+
- С ревизии 1 идентичность содержимого — `source.token` harness
|
|
111
|
+
(`harness:` и SHA-256 строки токена в событиях SSE и `x-hui-digest`):
|
|
112
|
+
harness alpha.56 считает его без часов проекции. Собственный дайджест
|
|
113
|
+
панели (без `generatedAt` и токена, окно до минуты) остаётся для alpha.55
|
|
114
|
+
и для пустого токена.
|
|
115
|
+
- Пока содержимое не изменилось, страница не перезагружается: подписи окна
|
|
116
|
+
истории остаются от последнего изменения, строка свежести говорит «без
|
|
117
|
+
изменений с HH:MM».
|
|
118
|
+
|
|
119
|
+
## Ревизия 2 представления (harness 0.1.0-alpha.57)
|
|
120
|
+
|
|
121
|
+
### Кто что делал
|
|
122
|
+
|
|
123
|
+
- Экран `#/activity` читает `activity[]`: события окна истории, новые
|
|
124
|
+
сверху, как их прислал harness. У каждой строки — время, значок того, кто
|
|
125
|
+
действовал (контроллер, исполнитель, reviewer, ведущий, вы, хост; словами,
|
|
126
|
+
не только цветом), фраза harness как написана, ссылка на детали работы и
|
|
127
|
+
код события мелким шрифтом. Неизвестный исполнитель и код показываются
|
|
128
|
+
как есть.
|
|
129
|
+
- Время в часовом поясе зрителя: сегодня — `ЧЧ:ММ`, вчера — «вчера ЧЧ:ММ»,
|
|
130
|
+
раньше — дата и время.
|
|
131
|
+
- Фильтры по работе и по исполнителю (`#/activity?work=&actor=`), «показано
|
|
132
|
+
N из M»; фильтр без совпадений — «По выбранному фильтру событий нет».
|
|
133
|
+
- Пустая лента — «За окно (24 ч) ничего не происходило»; поля нет (harness
|
|
134
|
+
alpha.55, alpha.56) — «harness этой версии не ведёт ленту», а не «ничего не
|
|
135
|
+
было». Опущенные в окне (`truncated.activity`) — «Ещё N событий окна не
|
|
136
|
+
показано: лента держит 50 последних».
|
|
137
|
+
- У приёмки работы (`work.accepted`) рядом с фразой harness — «где:
|
|
138
|
+
принято локально; удалённая ветка — в деталях работы» и ссылка «что
|
|
139
|
+
проверено»: фраза harness обрезается до 200 символов и при длинной ветке
|
|
140
|
+
теряет «локально».
|
|
141
|
+
- Под лентой — «Кто есть кто»: раскрытия глоссария для исполнителей из
|
|
142
|
+
ленты; в глоссарии новые термины «вы, оператор» и «хост».
|
|
143
|
+
|
|
144
|
+
### Принято локально / в удалённой ветке
|
|
145
|
+
|
|
146
|
+
- В деталях работы и в обзоре у `pushed` и `not-pushed` — состояние
|
|
147
|
+
словами строки harness, но из самого `target.remote.state` и ветки
|
|
148
|
+
`trackingRef`: «Принято локально; в удалённой ветке origin/main ещё
|
|
149
|
+
нет.», «Принято локально; уже в удалённой ветке origin/main.» Строка
|
|
150
|
+
`target.remote.line` не цитируется: harness обрезает её до 200 символов,
|
|
151
|
+
и при длинном имени ветки обрезка срезает «ещё нет» (предложение P9 для
|
|
152
|
+
harness).
|
|
153
|
+
- Ниже — когда git на этой машине последний раз обновил копию удалённой
|
|
154
|
+
ветки (`target.remote.checkedAt`): «Сверено с копией удалённой ветки на
|
|
155
|
+
этой машине, без сети; git обновил копию: вчера 20:30»; без `checkedAt` —
|
|
156
|
+
«когда git обновлял копию — неизвестно».
|
|
157
|
+
- Раскрытие «в удалённой ветке: что это значит»: сверка только с локальной
|
|
158
|
+
remote-tracking ref, без сети и `git fetch`, поэтому сведения могут
|
|
159
|
+
отставать; «неизвестно» — не «нет» и не «отправлено»; harness ничего не
|
|
160
|
+
отправляет сам. В обзоре — одно раскрытие на список.
|
|
161
|
+
- `unknown` и незнакомое состояние — «неизвестно» с причиной harness, даже
|
|
162
|
+
если строка говорит иное: панель никогда не пишет «отправлено» без
|
|
163
|
+
`pushed`. У alpha.55 и alpha.56 состояние всегда `unknown` с причиной.
|
|
164
|
+
|
|
165
|
+
### Договор
|
|
166
|
+
|
|
167
|
+
- Копии схем harness — alpha.57 и настоящий пустой документ alpha.57
|
|
168
|
+
(`activity: []`); копии alpha.56 и alpha.55 с их настоящими пустыми
|
|
169
|
+
документами — в `tests/contract/harness-0.1.0-alpha.56/` и
|
|
170
|
+
`tests/contract/harness-0.1.0-alpha.55/`. Тесты проверяют, что документы
|
|
171
|
+
в форме alpha.55 и alpha.56 проходят свою и все более новые схемы и
|
|
172
|
+
проверку панели, а образцы в форме alpha.57 и alpha.56 действительно
|
|
173
|
+
несут новые поля (старая схема их отклоняет). Типы `AnswerBasis`,
|
|
174
|
+
`HistoryTotals`, `ActivityEntry` и `target.remote` сверяются со схемой
|
|
175
|
+
поле за полем; `KNOWN_VIEW_REVISION` — `2`. Проверка панели отклоняет
|
|
176
|
+
неверный `checkedAt` и нестроковую `line`.
|
|
177
|
+
- Демонстрационные данные (`--demo`) — ревизия 2: основания ответов, итоги
|
|
178
|
+
окна, лента, согласованная с проверками, ревью и вопросами деталей работ (одно событие — вчерашнее) и принятая работа, ещё не
|
|
179
|
+
отправленная в удалённую ветку.
|
|
180
|
+
|
|
181
|
+
## Проверки
|
|
182
|
+
|
|
183
|
+
`npm run check` — typecheck, prettier, unit, сборка и e2e (Playwright при
|
|
184
|
+
1280 и 390 px, axe; нужен локально установленный Chromium Playwright).
|
|
185
|
+
|
|
186
|
+
- Unit (S3): `tests/live.test.ts` (нет страницы — нет запусков; изменение
|
|
187
|
+
доходит за 2 с; отступление и сброс; отказ и таймаут harness — `stale` с
|
|
188
|
+
первым временем сбоя; повторное использование для `GET`; файл),
|
|
189
|
+
`tests/subscribe.test.ts`, `tests/cli.test.ts` (`--check`, `--window`).
|
|
190
|
+
- e2e (S3): изменение файла на открытой странице за 2 с, «устаревшие» при
|
|
191
|
+
пропавшем файле, скрытая вкладка без запусков harness, опрос при
|
|
192
|
+
заблокированном потоке.
|
|
193
|
+
- Unit (ревизия 1): основание ответа (RU и EN, alpha.55, пустая строка, закрытая
|
|
194
|
+
работа), итоги окна (строки, раскрытия, сводки из итогов, неизвестный
|
|
195
|
+
расход, alpha.55 без нулей), диапазон этапа, дайджест обеих ревизий и
|
|
196
|
+
живой маршрут на alpha.56 (тот же токен — `fresh`, новый — изменение,
|
|
197
|
+
токены с пробелами, кириллицей и переводом строки одинаковы в SSE и
|
|
198
|
+
заголовке) и переходы 55 → 56 → 55.
|
|
199
|
+
- e2e (ревизия 1): живой маршрут в браузере следует токену harness.
|
|
200
|
+
- Unit (ревизия 2): лента (строки harness как написаны, значки, «вчера» и
|
|
201
|
+
дата, ссылки на работы, фильтры, `[]`, нет поля, фильтр без совпадений,
|
|
202
|
+
`truncated`, окно 7 дней, неизвестный исполнитель и код, RU и EN),
|
|
203
|
+
строка удалённой ветки (все состояния, время сверки сегодня, вчера и
|
|
204
|
+
раньше, без `checkedAt` и без `trackingRef`, обрезанная строка harness
|
|
205
|
+
без «ещё нет» — всё равно «ещё нет», `unknown` и незнакомое состояние со
|
|
206
|
+
строкой «уже в удалённой ветке» — всё равно «неизвестно»), время событий
|
|
207
|
+
(полночь, переход на летнее и зимнее время, границы года, ранние годы,
|
|
208
|
+
несуществующая дата), проверка панели для новых полей, лента согласована
|
|
209
|
+
с проверками, ревью и ответами других документов, документы в форме 55,
|
|
210
|
+
56 и 57.
|
|
211
|
+
- e2e (ревизия 2): лента и строка удалённой ветки на демонстрации, фильтр
|
|
212
|
+
по работе и переход к работе из события, «вчера» и дата по часам
|
|
213
|
+
страницы.
|
|
214
|
+
|
|
215
|
+
## Пакет
|
|
216
|
+
|
|
217
|
+
В пакете только `dist` (библиотека, CLI, приложение и данные
|
|
218
|
+
демонстрации), `docs`, `skills`, `README.md` и `LICENSE`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "devcontour-harness-ui",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.2",
|
|
4
4
|
"description": "Read-only operator panel for devcontour-harness: React components and a local standalone app over the harness operator view.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -41,7 +41,8 @@
|
|
|
41
41
|
"start": "node dist/lib/cli.js --demo",
|
|
42
42
|
"format": "prettier --write .",
|
|
43
43
|
"format:check": "prettier --check .",
|
|
44
|
-
"test:e2e": "npm run build && playwright test"
|
|
44
|
+
"test:e2e": "npm run build && playwright test",
|
|
45
|
+
"check": "npm run typecheck && npm run format:check && npm test && npm run test:e2e"
|
|
45
46
|
},
|
|
46
47
|
"peerDependencies": {
|
|
47
48
|
"devcontour-harness": ">=0.1.0-alpha.55 <0.2.0",
|
|
@@ -83,9 +83,35 @@ $H capabilities > "$VIEW_DIR/caps.json" # только чтение
|
|
|
83
83
|
|
|
84
84
|
## 3. Запустить панель в фоне
|
|
85
85
|
|
|
86
|
-
Если `
|
|
87
|
-
|
|
88
|
-
|
|
86
|
+
Если `$UI --help` перечисляет `--check`, сначала проверь совместимость (только
|
|
87
|
+
чтение):
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
$UI --check --harness <путь к $H> --state <state> --policy .harness/policy.json > "$VIEW_DIR/check.json"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`"compatible": true` — можно запускать. `false` — прочитай `fix` и скажи
|
|
94
|
+
пользователю, какую версию панели или harness поставить; не запускай панель
|
|
95
|
+
вслепую.
|
|
96
|
+
|
|
97
|
+
Предпочитай живой маршрут: панель сама вызывает harness, а открытая страница
|
|
98
|
+
обновляется сама (строка «Данные на HH:MM · обновляются сами»). Пока
|
|
99
|
+
страница закрыта или вкладка скрыта, панель harness не запускает.
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
$UI --state <state> --policy .harness/policy.json --harness <путь к $H> \
|
|
103
|
+
> "$VIEW_DIR/panel.out" 2> "$VIEW_DIR/panel.err" &
|
|
104
|
+
echo $! > "$VIEW_DIR/panel.pid"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`--harness` нужен, когда `$H` — не одна команда из PATH (например, `npx …`):
|
|
108
|
+
передай `<repo>/node_modules/.bin/harness` или путь из skill `harness`.
|
|
109
|
+
Окно истории — `--window 24h` (по умолчанию) или `--window 7d`, если
|
|
110
|
+
пользователь спрашивает о неделе.
|
|
111
|
+
|
|
112
|
+
Если `$UI --help` не перечисляет `--state` (старая панель), запиши снимок
|
|
113
|
+
вне репозитория и раздай его. Панель принимает конверт harness как есть;
|
|
114
|
+
повторная запись файла обновляет открытую страницу.
|
|
89
115
|
|
|
90
116
|
```sh
|
|
91
117
|
$H view --state <state> --policy .harness/policy.json > "$VIEW_DIR/view.json"
|
|
@@ -97,12 +123,6 @@ echo $! > "$VIEW_DIR/panel.pid"
|
|
|
97
123
|
(`error.code`) и сообщи пользователю. `POLICY_REQUIRED` значит, что путь к
|
|
98
124
|
политике неверен. Не раздавай устаревший файл.
|
|
99
125
|
|
|
100
|
-
Если `$UI --help` перечисляет `--state`, предпочитай живой маршрут:
|
|
101
|
-
`$UI --state <state> --policy .harness/policy.json`, и панель сама остаётся
|
|
102
|
-
актуальной. Когда `$H` — не одна команда из PATH (например, `npx …`),
|
|
103
|
-
передай путь к исполняемому файлу harness: `--harness
|
|
104
|
-
<repo>/node_modules/.bin/harness`.
|
|
105
|
-
|
|
106
126
|
Язык: у CLI есть `--lang ru|en` (по умолчанию — из системной локали), а у
|
|
107
127
|
страницы — `?lang=ru|en` и переключатель в навигации. Если пользователь
|
|
108
128
|
говорит по-русски, передай `--lang ru`. Разделы панели — hash-адреса:
|
|
@@ -156,20 +176,30 @@ echo $! > "$VIEW_DIR/panel.pid"
|
|
|
156
176
|
Никогда не говори «проверено» или «готово», не назвав, как и кем.
|
|
157
177
|
- «Почему повтор» — простыми словами, чем закончилась прошлая попытка
|
|
158
178
|
(например, «окружение — порт занят»).
|
|
159
|
-
- «Принято локально / в
|
|
160
|
-
|
|
161
|
-
`fetch
|
|
162
|
-
`0.1.0-alpha.
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
179
|
+
- «Принято локально / в удалённой ветке». Состояние удалённой ветки
|
|
180
|
+
harness читает из её копии на этой машине (remote-tracking ref) без
|
|
181
|
+
`fetch` и без сети, то есть «по последним сведениям git здесь»; рядом
|
|
182
|
+
— когда git последний раз обновил эту копию. С harness `0.1.0-alpha.57`
|
|
183
|
+
панель пишет состояние словами harness («принято локально; в удалённой
|
|
184
|
+
ветке origin/main ещё нет»). Harness `0.1.0-alpha.55` и `.56` ветку не читают и
|
|
185
|
+
всегда пишут «неизвестно» с причиной: не говори «отправлено» или «не
|
|
186
|
+
отправлено» по такому состоянию. Если результат принят только локально,
|
|
187
|
+
предложи push, но не делай его без просьбы пользователя.
|
|
166
188
|
- **Решения**: какие решения приняты (ведущим или пользователем), включая
|
|
167
189
|
временные — с условием, когда их пересмотреть.
|
|
168
|
-
- **Кто что делал**: кто —
|
|
169
|
-
что и когда
|
|
190
|
+
- **Кто что делал**: кто — контроллер harness, исполнитель, reviewer,
|
|
191
|
+
ведущий, вы или хост — что и когда сделал, фразами harness, новые сверху,
|
|
192
|
+
за окно истории. «За окно ничего не происходило» — пустая лента; «harness
|
|
193
|
+
этой версии не ведёт ленту» — производитель ленту не прислал (например,
|
|
194
|
+
harness старше `0.1.0-alpha.57`); это не «ничего не было».
|
|
170
195
|
- **Здоровье**: потрачено против бюджета (`≥` значит «не меньше», потому что
|
|
171
196
|
часть цен неизвестна; `unknown` никогда не ноль), жив ли контроллер,
|
|
172
197
|
зависшие попытки и принятые результаты, которые потом изменились.
|
|
198
|
+
- **Строка свежести** над экраном: «Данные на HH:MM · обновляются сами»
|
|
199
|
+
(живой маршрут), «· снимок…» (файл) или «· проверка раз в 5 секунд»
|
|
200
|
+
(запасной опрос). Если над ней «Не удалось обновить данные с HH:MM: …»,
|
|
201
|
+
на экране устаревшие данные: так и скажи, назови причину и не выдавай
|
|
202
|
+
их за текущие.
|
|
173
203
|
- **Подвал** «Данные harness на HH:MM; панель ничего не меняет»: время
|
|
174
204
|
снимка и напоминание, что нажатия ничего не меняют в работе.
|
|
175
205
|
- У каждого термина есть «что это значит» — предложи раскрыть его, а не
|
|
@@ -212,3 +242,5 @@ Ctrl-C тоже останавливает панель, если она раб
|
|
|
212
242
|
| `NOT_A_VIEW` "malformed: …" | файл не представление или конверт ошибки | создай его заново через `$H view`; если есть ошибка harness, сообщи её |
|
|
213
243
|
| пустая панель, "No state yet" | в этом каталоге состояния ничего не запускалось | нормально до первого `harness run` |
|
|
214
244
|
| "The app bundle is not built" | запуск из исходного checkout | `npm run build` в checkout панели |
|
|
245
|
+
| «Не удалось обновить данные с HH:MM» | harness отказал, упал или не ответил за 30 с | прочитай причину в строке; проверь `$H status`; на экране последние удачные данные |
|
|
246
|
+
| `"compatible": false` от `--check` | версии панели и harness не подходят друг другу | сделай то, что написано в `fix`; сообщи обе версии |
|