wehub-resource-sync
a06f331eb8
CI / benchmark (push) Has been skipped
install-script / posix-syntax (push) Successful in 6m1s
CI / build-onnx (push) Failing after 6m43s
init-smoke / dry-run (push) Failing after 15m57s
security / govulncheck (push) Has been cancelled
security / trivy-fs (push) Has been cancelled
CI / test (1.26, ubuntu-latest) (push) Has been cancelled
Scorecard supply-chain security / Scorecard analysis (push) Has been cancelled
CI / test (1.26, macos-latest) (push) Has been cancelled
CI / build-windows (push) Has been cancelled
CI / lint (push) Has been cancelled
install-script / powershell-syntax (push) Has been cancelled
install-script / install (macos-14) (push) Has been cancelled
install-script / install (ubuntu-latest) (push) Has been cancelled
99 lines
6.6 KiB
Markdown
99 lines
6.6 KiB
Markdown
# AGENTS.md — Temporal dispatch allow-list (для корпоративного агента)
|
||
|
||
Этот файл — инструкция агенту, работающему в **корпоративном форке** gortex, по
|
||
сопровождению распознавания Temporal-диспатча под ваш кодовой базы. Цель: повышать точность
|
||
графа Temporal **без утечки корпоративных имён** в исходники / upstream.
|
||
|
||
> Не путать с `docs/agents.md` (это про agent-адаптеры самого gortex). Здесь — только про
|
||
> Temporal allow-list и LLM-клининг.
|
||
|
||
---
|
||
|
||
## 1. Как устроено распознавание (три слоя)
|
||
|
||
Имя активности/воркфлоу в `workflow.ExecuteActivity(ctx, <name>, …)` часто приходит не литералом.
|
||
Форк распознаёт его тремя слоями, по возрастанию доверия:
|
||
|
||
1. **Generic-эвристика (recall, скрыто).** Любой хелпер с `env` в имени —
|
||
`cfg.ActivityFromEnv("KEY", "Default")` — распознаётся структурно: 2-й строковый аргумент
|
||
берётся как дефолтное имя. Ребро садится на **speculative 0.4** (`temporal_env_source=heuristic`),
|
||
скрыто из обычных запросов. Вести ничего не нужно — работает само.
|
||
2. **Allow-list (precision, видимо).** Если имя хелпера в built-in списке (`GetEnvOrDefault`,
|
||
`GetEnvOrDefaultValue`, `EnvOr`, `GetenvDefault`, `GetEnvDefault`) **или** в вашем
|
||
репо-локальном allow-list — ребро повышается до **inferred 0.6**, видимо по умолчанию
|
||
(`temporal_env_source=allowlist`). `os.Getenv(...)` / `cmp.Or(...)` тоже → 0.6.
|
||
3. **LLM-клининг (опционально).** Проход `gortex analyze --kind temporal_verify` отдаёт каждое
|
||
рёбро уровня ≤0.65 вашей LLM, заземляя в реальном коде: confirmed → повышает и делает видимым,
|
||
rejected → гасит (скрывает), uncertain → оставляет как есть. Register-confirmed (0.9) не трогает.
|
||
|
||
**Главное:** слой 1 жадный и безвредный (скрыт), слой 2 точечно повышает, слой 3 чистит. Поэтому
|
||
**не обязательно** перечислять все хелперы — список нужен лишь чтобы **сделать конкретный хелпер
|
||
видимым по умолчанию**.
|
||
|
||
---
|
||
|
||
## 2. Как вести allow-list
|
||
|
||
Файл **git-ignored** (см. `.gitignore`: `.gortex/`), читается **только** под env-гейтом.
|
||
|
||
1. Включить гейт: `export GORTEX_ALLOW_LOCAL_TEMPORAL=1`.
|
||
2. Создать `.gortex/temporal-allowlist.yaml` в корне репозитория:
|
||
|
||
```yaml
|
||
# Имена ваших env-хелперов, по которым диспатч резолвится на дефолт.
|
||
# Сопоставление по имени функции (без пакета), регистронезависимо.
|
||
env_helpers:
|
||
- GetActivityNameFromEnv
|
||
- FetchActivityName
|
||
- resolveActivity # локальные/lowercase тоже годятся
|
||
```
|
||
|
||
3. Проверить эффект: `gortex analyze --kind temporal_orphans --path . --format json` (до/после) —
|
||
часть `broken_dispatch` должна закрыться, env-сайты получить `temporal_env_source=allowlist`.
|
||
|
||
Что добавлять / чего нет:
|
||
|
||
- **Добавлять:** имена функций-обёрток «прочитать env и вернуть дефолт». Это generic-инфраструктура,
|
||
не бизнес-данные.
|
||
- **НЕ добавлять:** имена активностей/воркфлоу/бизнес-логику. Они тут не нужны (распознаются
|
||
структурно), и им не место даже в git-ignored файле.
|
||
|
||
---
|
||
|
||
## 3. Протокол анонимизации (не спалить корпоративное)
|
||
|
||
- Файл `.gortex/temporal-allowlist.yaml` **git-ignored** — не коммить его и не добавлять в PR.
|
||
- Имена env-хелперов сами по себе — generic infra (безопасны), но всё равно держим их **только** в
|
||
локальном файле, а не в исходниках форка.
|
||
- Если делаешь фикстуры для передачи OSS-стороне — следуй
|
||
`docs/temporal-compare/temporal-gap-synthetic-fixtures.md` (протокол: «сохраняем форму, стираем
|
||
содержание»): repo-пути → `example.com/app`, имена активностей → `ChargeActivity`, env-ключи →
|
||
`FOO_ACTIVITY_ENV`, тела → выкинуть.
|
||
|
||
---
|
||
|
||
## 4. LLM-клининг (precision-проход вашей моделью)
|
||
|
||
Требует настроенного `llm.provider` (например ваш `custom-provider`) в `.gortex.yaml` /
|
||
`~/.config/gortex/config.yaml`.
|
||
|
||
```bash
|
||
gortex analyze --kind temporal_verify --path . --format json
|
||
```
|
||
|
||
- Проверяет **только** низкодоверенные рёбра (speculative 0.4 + inferred 0.6) — набор маленький,
|
||
стоимость ограничена. Register-confirmed 0.9 не трогает.
|
||
- Вердикты кэшируются в git-ignored `.gortex/temporal-verify-cache.json` по хэшу
|
||
(модель + имя + исходник вызова + исходник кандидата) → повторный прогон детерминирован и
|
||
бесплатен (годится для CI). Меняется код или модель — кэш промахивается и перепроверяет.
|
||
- Вывод: `checked / confirmed / rejected / uncertain / errors` (+ `details` в JSON с причинами).
|
||
- На каждом ребре остаются `temporal_llm_verdict` и `temporal_llm_reason` для аудита.
|
||
|
||
---
|
||
|
||
## 5. Что делать с тем, что всё ещё не резолвится
|
||
|
||
Для dispatch-шейпов, остающихся `broken_dispatch` и не закрытых ничем выше, —
|
||
`docs/temporal-compare/temporal-gap-synthetic-fixtures.md`: какие минимальные анонимизированные
|
||
фикстуры отдать OSS-стороне, чтобы дорезолвить либу.
|