analysis: flow_stats.py и эталон метрик dx-flow — журнал самодостаточен для демона-аналитика
This commit is contained in:
Витковских Евгений
parent
0683962cd2
commit
075f063ce4
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Конвейер разработки на агентах: этап → исполнение → проверки (dx-flow)
|
||||||
|
|
||||||
|
> ЖИВАЯ карточка процесса: совершенствуется ретроспективами (dx-retro-1),
|
||||||
|
> оценки приёмов пересматриваются по новой фактуре, дописывается
|
||||||
|
> доказательной базой следующих проектов. Первая доказательная база — Kit.RAG
|
||||||
|
> (2026-10-30…11-01: 3 дня, 90 коммитов, 39 workflow-прогонов ~0,7 млрд
|
||||||
|
> токенов, ~26 ревизий; гейт 104→607 монотонно, находки ревизий 53→1–2
|
||||||
|
> low, ускорение модуль к модулю ×3–5). См. [readme.md](../../readme.md).
|
||||||
|
|
||||||
|
## Цикл этапа (проверен на 3 модулях)
|
||||||
|
|
||||||
|
```
|
||||||
|
ТЗ этапа (/stage: «Среда и гейты» B1–B8 + RAG-темы с якорями)
|
||||||
|
→ ИСПОЛНЕНИЕ: субагенты-workflow параллельно по зонам (или агент напрямую)
|
||||||
|
→ ИНТЕГРАТОР: полный гейт (build+test решения), точечные — у исполнителей
|
||||||
|
→ РЕВИЗИЯ СВЕЖИМ КОНТЕКСТОМ: независимый агент без контекста исполнителя;
|
||||||
|
сверяет код↔канон, якоря перепроверяет живым запросом (dx-dev-8),
|
||||||
|
числа пересчитывает сам (руками/своим парсером)
|
||||||
|
→ ПРАВКИ по находкам (применить/отклонить с обоснованием)
|
||||||
|
→ КОНТРОЛЬНЫЙ ГЕЙТ (правки ничего не сломали)
|
||||||
|
→ КАСКАД статусов (одно место: readme модуля; plan — строка; handoff —
|
||||||
|
хвосты/грабли) → GIT-КОММИТ (рецепт — в коммите этапа, B5/D3)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Роли проверок
|
||||||
|
|
||||||
|
| Роль | Что проверяет | Ключевое свойство |
|
||||||
|
|---|---|---|
|
||||||
|
| Исполнитель | свою зону (точечные тесты) | не видит чужих зон |
|
||||||
|
| Интегратор | сборка целиком, швы (DI/slnx/фикстуры — dx-dev-3) | единственный полный гейт |
|
||||||
|
| Ревизор («проверка разработчиком со стороны» + «архитектором») | код↔канон, псевдо-цитаты, якоря, числа | СВЕЖИЙ контекст — главный источник качества; ловил high, невидимые исполнителю |
|
||||||
|
| Главная сессия | эскалации/развилки, инциденты вне зон | решает владелец |
|
||||||
|
|
||||||
|
Архитектурная проверка решений = протокол dx-dev-1 (до утверждения) +
|
||||||
|
ревизия шага 0 (module_reqs/спеки как документы, B7).
|
||||||
|
|
||||||
|
## Приёмы (оценки по ретроспективе Kit.RAG; пересматриваются)
|
||||||
|
|
||||||
|
| Приём | Оценка | Комментарий |
|
||||||
|
|---|---|---|
|
||||||
|
| Ревизия свежим контекстом + контрольный гейт | ядро, не трогать | находки 53→1–2 low; ловила вне-зонные правки, псевдо-цитаты |
|
||||||
|
| Авточемод с эскалациями на развилках | высокоэффективно | темп ×3–5 без потери контуров контроля; вводить ПОСЛЕ обкатки конвейера |
|
||||||
|
| Workflow-исполнители этапов | высокоэффективно | цена: капы/redo-прогоны (6/39), кэш-переигрывания — лечится маркером «ТЗ vN» |
|
||||||
|
| Honest-skip вместо молчаливого пропуска | высоко | все skip'ы позже сняты живыми прогонами |
|
||||||
|
| TCP-стабы внешних сервисов + детерминированные векторы | высоко | приёмочные стабильны и доказательны, не зависят от живой LLM |
|
||||||
|
| docChanges-реестр → легализация одним Изм. на замыкании | высоко (клапан) | симптом дрейфа канона — следить за возрастом |
|
||||||
|
| Метрики замыкания с независимым пересчётом | высоко | «не замерено честно» — списком, не замалчивать |
|
||||||
|
| Повторные полные гейты ×3–4 на этап | условно | после введения файл-лока основания нет — точечные + контрольный |
|
||||||
|
| Дублирование статусов в 3+ документах | НЕ окупилось | ~68% документационных коммитов; одно место + ссылки |
|
||||||
|
|
||||||
|
## Анти-паттерны (пережито, не повторять)
|
||||||
|
|
||||||
|
- Канон утверждается до схождения решений → смена курса после начала
|
||||||
|
кода (Изм. 5: переделка этапа, 53 находки). Лечение: dx-dev-1 до
|
||||||
|
утверждения.
|
||||||
|
- Вне-процессные правки «по ходу» с самовольной атрибуцией → откат,
|
||||||
|
инцидент. Лечение: изменения — через записи канона/эскалации.
|
||||||
|
- Закрытый этап «доезжает» потом дважды. Лечение: замыкание = контрольный
|
||||||
|
гейт + хвосты в handoff, не «потом».
|
||||||
|
|
||||||
|
## Открытые хвосты (совершенствуется)
|
||||||
|
|
||||||
|
- Страж-навык d-proc-guard (авто-проверка чек-листа при генерации ТЗ) —
|
||||||
|
решение на замыкании И4 по метрикам.
|
||||||
|
- Фильтр `--tag env:*` для search — среда из текста запроса в фильтр.
|
||||||
|
- Каноническая нарезка (чанк = законченная единица) — в очереди
|
||||||
|
легализации; снимет и недетерминизм LLM-нарезки.
|
||||||
|
- Формы исполнения вне workflow (короткие этапы) — накопить фактуру.
|
||||||
|
|
||||||
|
## Scorecard: оценки, по которым совершенствуется процесс
|
||||||
|
|
||||||
|
**Механика влияния на знания.** Замер (замыкание итерации, dx-retro-2)
|
||||||
|
→ светофор 🟢/🟡/🔴 → порог-триггер → изменение КОНКРЕТНОГО артефакта
|
||||||
|
знаний (карточка `_env` / правило dx / приём в dx-flow / строка dx-map /
|
||||||
|
наполнение дерева) → коммит std1-ext с указанием источника-замера →
|
||||||
|
переиндексация корпуса. Если правило соблюдается, а метрика хуже цели —
|
||||||
|
пересматривается ОЦЕНКА правила/приёма (понижается, хвост в «Открытых
|
||||||
|
хвостах»). Правки знаний — только через ретроспективу (владелец в
|
||||||
|
контуре утверждения), никогда «по ходу».
|
||||||
|
|
||||||
|
**Фиксация.** Замер — факт в отчёте замыкания итерации проекта (формат:
|
||||||
|
`итерация | метрика | значение | светофор | триггер | действие`), не
|
||||||
|
редактируется. Светофор и цели — здесь, с датой и источником. Действие —
|
||||||
|
git-коммит std1-ext («ретроспектива ИN, метрика M»). **Версионность** —
|
||||||
|
git: вся история правил и оценок = история коммитов; откат = `git
|
||||||
|
revert` правки знаний с обоснованием; замеры-факты не откатываются;
|
||||||
|
корпус пересобирается из git (индекс — производное, не версионируется).
|
||||||
|
|
||||||
|
### Метрики (база / цель / триггер / текущий светофор 2026-11-02)
|
||||||
|
|
||||||
|
| # | Метрика | База (И1/И2) | Цель | Триггер (порог действия) | Сейчас |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| А1 | Находки ревизии/этап, медиана | ~7 (пик 53) / ~2 | ≤2, high=0 | high на этапе → усилить B-блок ТЗ и фокус ревизии | 🟡 (И3-э1: 2 high) |
|
||||||
|
| А2 | Псевдо-якоря/псевдо-цитаты | 0 / 0 (И3-э1: 2) | 0 | >0 → приём в dx-flow + формулировка dx-dev-8 | 🟡 |
|
||||||
|
| А3 | Дефекты после замыкания этапа | И1: этап доезжал ×2 | 0 | >0 → ужесточить замыкание (контрольный + хвосты в handoff) | 🟡 |
|
||||||
|
| А4 | Повторы известных граблей | И2: 3 (кодировка/лок/байты) | 0 | 1-й повтор → инструмент (dx-retro-3); 2-й → эскалация владельцу | 🟡 (проверка И3: инструменты введены) |
|
||||||
|
| Б1 | Доля документационных коммитов | ~70% / ~56% | ≤40% | >50% две итерации подряд → упрощать каскад (одно место статусов) | 🟡 |
|
||||||
|
| Б2 | Redo-прогоны workflow/этап | 4 / 2 | ≤1 | >2 → стабильность скриптов (маркер «ТЗ vN», прогон сниппетов) | 🟡 |
|
||||||
|
| Б3 | Wall-clock и токены этапа | база И1/И2 зафиксирована | тренд ↓ на однотипных этапах | рост ×2 → разбор причин | 🟢 (ускорение ×3–5) |
|
||||||
|
| В1 | Возврат правил: батарея top-3 | 16/16 | 100% | <100% → чинить корпус/нарезку, не батарею | 🟢 |
|
||||||
|
| В2 | Темы с первого захода | 2/4 до env-фикса | ≥75% | <75% → тюнинг запросов / ускорить `--tag env:*` | 🟡 (контрольный прогон /decision) |
|
||||||
|
| В3 | Дыры корпуса (темы без находок) | механизм заведён | закрытие в ту же итерацию | каждая → кандидат наполнения дерева | 🟢 |
|
||||||
|
| В4 | Возраст docChanges на легализации | до 4 этапов | ≤1 итерации | >1 итерации → выносить легализацию чаще | 🟡 |
|
||||||
|
| Г1 | Honest-skip'ы сняты к замыканию | И1: все сняты живыми | 100% | остаток → в хвосты handoff | 🟢 |
|
||||||
|
| Г2 | Эскалации закрыты владельцем | не замерялось | ≤1 дня | дольше → выносить в повестку явно | 🟢 (эмпирически быстро) |
|
||||||
|
| Г3 | Инциденты среды: новые → карточка | правило заведено | в тот же день | дольше → помнить о dx-retro-3 | 🟢 |
|
||||||
|
|
||||||
|
**Пересмотр целей** — не чаще каждой второй ретроспективы, коммитом с
|
||||||
|
обоснованием. Добавление метрики — через ретроспективу (какие решения
|
||||||
|
она изменит? не изменяет — не заводить).
|
||||||
|
|
||||||
|
### История светофоров (полная — git log карточки)
|
||||||
|
|
||||||
|
- 2026-11-02 — базовая фиксация: А1–А4/Б1/Б2/В2/В4 🟡, Б3/В1/В3/Г* 🟢;
|
||||||
|
источники — ретроспектива Kit.RAG (И1/И2) и живой прогон /decision.
|
||||||
|
|
||||||
|
## Правило обновления карточки
|
||||||
|
|
||||||
|
Ретроспектива проекта (dx-retro-1) дописывает: новые приёмы с оценкой и
|
||||||
|
прецедентом-числом, пересматривает существующие оценки, закрывает хвосты,
|
||||||
|
обновляет светофоры со ссылкой на замер. Числа обязательны
|
||||||
|
(«быстрее/лучше» без чисел не принимается, dx-retro-2). Коммит в
|
||||||
|
std1-ext с указанием источника-ретроспективы + переиндексация корпуса.
|
||||||
|
Откат оценки/правила — git revert с обоснованием; замеры-факты
|
||||||
|
последующих итераций не откатываются.
|
||||||
|
|
@ -0,0 +1,202 @@
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
"""Агрегатор журнала опыта kit-dev-flow (общий git-репозиторий статистики).
|
||||||
|
|
||||||
|
Читает карточки прогонов runs/**/*.md (YAML-шапка между первыми двумя
|
||||||
|
строками '---'), считает агрегаты по всем проектам команды и печатает
|
||||||
|
markdown-отчёт. Точка опыта: --dir > env KIT_FLOW_EXP_DIR >
|
||||||
|
~/.zcode/kit-knowledge.json (flow_exp_dir) > I:\\Kit\\DB.FlowExp_WorkStatistics.
|
||||||
|
|
||||||
|
Примеры:
|
||||||
|
python flow_stats.py # всё
|
||||||
|
python flow_stats.py --kind этап-модуля # класс текущего шага
|
||||||
|
python flow_stats.py --days 30 --last 40
|
||||||
|
python flow_stats.py --write-summary # обновить _summary.md
|
||||||
|
"""
|
||||||
|
import argparse
|
||||||
|
import datetime as dt
|
||||||
|
import glob
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
|
||||||
|
DEFAULT_DIR = r"I:\Kit\DB.FlowExp_WorkStatistics"
|
||||||
|
NUM_FIELDS = ("agents", "revisions", "escalations", "duration_min")
|
||||||
|
STR_FIELDS = ("date", "project", "step", "kind", "form", "preset",
|
||||||
|
"model", "result", "run_id")
|
||||||
|
|
||||||
|
|
||||||
|
def resolve_dir(cli_dir):
|
||||||
|
if cli_dir:
|
||||||
|
return cli_dir
|
||||||
|
env = os.environ.get("KIT_FLOW_EXP_DIR")
|
||||||
|
if env:
|
||||||
|
return env
|
||||||
|
cfg_path = os.path.join(os.path.expanduser("~"),
|
||||||
|
".zcode", "kit-knowledge.json")
|
||||||
|
try:
|
||||||
|
with open(cfg_path, encoding="utf-8") as fh:
|
||||||
|
cfg = json.load(fh)
|
||||||
|
if cfg.get("flow_exp_dir"):
|
||||||
|
return cfg["flow_exp_dir"]
|
||||||
|
except (OSError, ValueError):
|
||||||
|
pass
|
||||||
|
return DEFAULT_DIR
|
||||||
|
|
||||||
|
|
||||||
|
def parse_card(path):
|
||||||
|
"""YAML-шапка карточки: ключ: значение (одна строка на ключ)."""
|
||||||
|
with open(path, encoding="utf-8") as fh:
|
||||||
|
lines = fh.read().splitlines()
|
||||||
|
if not lines or lines[0].strip() != "---":
|
||||||
|
return None
|
||||||
|
meta, end = {}, None
|
||||||
|
for i, line in enumerate(lines[1:], start=1):
|
||||||
|
s = line.strip()
|
||||||
|
if s == "---":
|
||||||
|
end = i
|
||||||
|
break
|
||||||
|
if ":" in s and not s.startswith("#"):
|
||||||
|
key, _, val = s.partition(":")
|
||||||
|
val = val.split(" #")[0].strip().strip('"').strip("'")
|
||||||
|
if key.strip() in STR_FIELDS or key.strip() in NUM_FIELDS:
|
||||||
|
meta[key.strip()] = val
|
||||||
|
if end is None or not meta.get("date"):
|
||||||
|
return None
|
||||||
|
lessons, in_lessons = [], False
|
||||||
|
for line in lines[end + 1:]:
|
||||||
|
bs = line.strip()
|
||||||
|
if bs.startswith("## Уроки"):
|
||||||
|
in_lessons = True
|
||||||
|
continue
|
||||||
|
if in_lessons and bs.startswith("## "):
|
||||||
|
in_lessons = False
|
||||||
|
elif in_lessons and bs.startswith("- "):
|
||||||
|
lessons.append(bs[2:].strip())
|
||||||
|
meta["_lessons"] = lessons
|
||||||
|
return meta
|
||||||
|
|
||||||
|
|
||||||
|
def num(meta, field):
|
||||||
|
try:
|
||||||
|
return float(meta.get(field, ""))
|
||||||
|
except (TypeError, ValueError):
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def load_cards(root, kind, project, days):
|
||||||
|
cards = []
|
||||||
|
for path in glob.glob(os.path.join(root, "runs", "**", "*.md"),
|
||||||
|
recursive=True):
|
||||||
|
meta = parse_card(path)
|
||||||
|
if not meta:
|
||||||
|
continue
|
||||||
|
if kind and meta.get("kind") != kind:
|
||||||
|
continue
|
||||||
|
if project and meta.get("project") != project:
|
||||||
|
continue
|
||||||
|
try:
|
||||||
|
d = dt.date.fromisoformat(meta["date"][:10])
|
||||||
|
except ValueError:
|
||||||
|
d = None
|
||||||
|
if days and d and (dt.date.today() - d).days > days:
|
||||||
|
continue
|
||||||
|
cards.append(meta)
|
||||||
|
cards.sort(key=lambda m: m.get("date", ""))
|
||||||
|
return cards
|
||||||
|
|
||||||
|
|
||||||
|
def avg(values):
|
||||||
|
vals = [v for v in values if v is not None]
|
||||||
|
return (sum(vals) / len(vals)) if vals else None
|
||||||
|
|
||||||
|
|
||||||
|
def fmt(v, suffix=""):
|
||||||
|
return "%.1f%s" % (v, suffix) if v is not None else "—"
|
||||||
|
|
||||||
|
|
||||||
|
def group_stats(cards, field):
|
||||||
|
"""{значение поля: [всего, success]} по карточкам с непустым полем."""
|
||||||
|
stats = {}
|
||||||
|
for m in cards:
|
||||||
|
key = m.get(field) or "—"
|
||||||
|
s = stats.setdefault(key, [0, 0])
|
||||||
|
s[0] += 1
|
||||||
|
if m.get("result") == "success":
|
||||||
|
s[1] += 1
|
||||||
|
return stats
|
||||||
|
|
||||||
|
|
||||||
|
def render(cards, title):
|
||||||
|
out = ["# Статистика kit-dev-flow — " + title, ""]
|
||||||
|
out.append("Карточек: %d (проектов: %d)" % (
|
||||||
|
len(cards), len({m.get("project") for m in cards if m.get("project")})))
|
||||||
|
out.append("")
|
||||||
|
for field, label in [("form", "форма"), ("preset", "пресет"),
|
||||||
|
("kind", "класс шага")]:
|
||||||
|
groups = group_stats(cards, field)
|
||||||
|
if len(groups) < 2 and field != "form":
|
||||||
|
continue
|
||||||
|
out.append("| %s | прогонов | success |" % label)
|
||||||
|
out.append("|---|---|---|")
|
||||||
|
for key, (total, ok) in sorted(groups.items(),
|
||||||
|
key=lambda kv: -kv[1][0]):
|
||||||
|
out.append("| %s | %d | %d%% |" % (key, total, ok * 100 // total))
|
||||||
|
out.append("")
|
||||||
|
out.append("Средние: агентов %s, ревизий %s, эскалаций %s, "
|
||||||
|
"длительность %s мин." % (
|
||||||
|
fmt(avg([num(m, "agents") for m in cards])),
|
||||||
|
fmt(avg([num(m, "revisions") for m in cards])),
|
||||||
|
fmt(avg([num(m, "escalations") for m in cards])),
|
||||||
|
fmt(avg([num(m, "duration_min") for m in cards]))))
|
||||||
|
out.append("")
|
||||||
|
fails = [m for m in cards if m.get("result") in ("fail", "partial")]
|
||||||
|
out.append("Провальных/частичных: %d. Уроки из последних:" % len(fails))
|
||||||
|
shown = 0
|
||||||
|
for m in reversed(fails):
|
||||||
|
if shown >= 8:
|
||||||
|
break
|
||||||
|
for lesson in m.get("_lessons", []):
|
||||||
|
out.append("- (%s, %s, %s) %s" % (
|
||||||
|
m.get("project", "?"), m.get("step", "?"),
|
||||||
|
m.get("form", "?"), lesson))
|
||||||
|
shown += 1
|
||||||
|
if shown >= 8:
|
||||||
|
break
|
||||||
|
if not shown:
|
||||||
|
out.append("- (нет провальных карточек в выборке)")
|
||||||
|
return "\n".join(out) + "\n"
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
ap = argparse.ArgumentParser(description=__doc__)
|
||||||
|
ap.add_argument("--dir", help="локальный клон репозитория опыта")
|
||||||
|
ap.add_argument("--kind", help="фильтр: класс шага (kind карточки)")
|
||||||
|
ap.add_argument("--project", help="фильтр: проект (по умолчанию все)")
|
||||||
|
ap.add_argument("--days", type=int, help="только последние N дней")
|
||||||
|
ap.add_argument("--last", type=int, help="только последние N карточек")
|
||||||
|
ap.add_argument("--write-summary", action="store_true",
|
||||||
|
help="записать отчёт в _summary.md репозитория")
|
||||||
|
args = ap.parse_args()
|
||||||
|
|
||||||
|
root = resolve_dir(args.dir)
|
||||||
|
if not os.path.isdir(root):
|
||||||
|
print("ОШИБКА: каталог журнала не найден: %s" % root, file=sys.stderr)
|
||||||
|
print("Настрой flow_exp_dir в ~/.zcode/kit-knowledge.json "
|
||||||
|
"или склонируй репозиторий опыта.", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
cards = load_cards(root, args.kind, args.project, args.days)
|
||||||
|
if args.last:
|
||||||
|
cards = cards[-args.last:]
|
||||||
|
title = args.kind or ("проект " + args.project if args.project else "все проекты")
|
||||||
|
report = render(cards, title)
|
||||||
|
if args.write_summary:
|
||||||
|
path = os.path.join(root, "_summary.md")
|
||||||
|
with open(path, "w", encoding="utf-8", newline="\n") as fh:
|
||||||
|
fh.write(report)
|
||||||
|
print("Записан отчёт: %s" % path)
|
||||||
|
print(report)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
Loading…
Reference in New Issue