[OPS] Индекс документации: 630 файлов в ops/INDEX.md — навигация по 95 каталогам с заголовками и датами, автообновление ежедневно (docs-index 06:50), попадает в RAG. Раньше индекс описывал 6 документов из 630

This commit is contained in:
root committed 2026-11-10 15:06:56 +03:00
1 parent 0d7122a796
commit 8da1da3e9d
3 files changed
+1173

No files matched your search

+1031
View File
File diff suppressed because it is too large. Load diff
+57
View File
@@ -0,0 +1,57 @@
# Индекс документации (10.11.2026)
## Проблема
**630 markdown-файлов в `ops/` и 946 по репозиторию.** Индекс `docs/README.md`
описывал 6 документов. Найти нужное можно было только `grep`'ом.
Документация — сильная сторона проекта (фиксирует ловушки), но без навигации
она превращается в архив.
## Что сделано
### `ops/scripts/build_docs_index.py`
Собирает все `.md` из `ops/`, берёт заголовок, размер и дату изменения,
группирует по каталогам. Пишет `ops/INDEX.md`.
```
файлов: 630
каталогов: 95
размер индекса: 76 КБ
```
Свежие файлы — сверху, у каждого каталога счётчик «за неделю»:
```
## ops — 45 файлов (29 за неделю)
| Документ | О чём | Изменён |
|---|---|---|
| AUDIT-LOCAL-RENDER-2026-11-09.md | Локальные рендеры комнат | 09.11 |
| SERVICE-STANDARD.md | Единый стандарт сервиса | 07.11 |
| NOTIFICATIONS.md | Политика уведомлений (анти-спам) | 06.11 |
```
### Автообновление
Задание Hermes **`docs-index`** ежедневно в 06:50. Индекс не устареет.
### Индекс попадает в RAG
`ops/INDEX.md` лежит в индексируемом каталоге — значит секретарь сможет
найти документ по описанию, а не только по содержимому.
## Итог
| Было | Стало |
|---|---|
| 630 файлов без навигации | индекс по каталогам с описаниями |
| ручной `grep` | таблица «документ — о чём — когда» |
| `docs/README.md` (6 ссылок) | `ops/INDEX.md` (630 файлов) |
## Осталось
1. `docs/README.md` — обновить, чтобы вело на `ops/INDEX.md`.
2. Часть документов старше месяца — кандидаты на архивацию (44 файла).
3. Разделить «живые» документы и «историю спринтов» по папкам.
+85
View File
@@ -0,0 +1,85 @@
#!/usr/bin/env python3
"""Индекс документации: 946 файлов → одна навигация.
Для каждого .md собирает: первую строку-заголовок, размер, дату изменения.
Группирует по каталогу. Пишет ops/INDEX.md.
Запуск: python3 ops/scripts/build_docs_index.py
"""
import datetime
import os
import re
ROOT = "/root/buryan-infra"
OUT = os.path.join(ROOT, "ops/INDEX.md")
SKIP_DIRS = {".git", "node_modules", "__pycache__", "rag", ".venv"}
def title_of(path):
try:
with open(path, encoding="utf-8", errors="ignore") as f:
for line in f:
s = line.strip()
if s.startswith("#"):
return re.sub(r"^#+\s*", "", s)[:90]
if s and not s.startswith(("---", "```")):
return s[:90]
except Exception:
pass
return ""
def main():
groups = {}
total = 0
for dirpath, dirnames, filenames in os.walk(os.path.join(ROOT, "ops")):
dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
for fn in filenames:
if not fn.endswith(".md"):
continue
p = os.path.join(dirpath, fn)
rel = os.path.relpath(p, ROOT)
if rel == "ops/INDEX.md":
continue
try:
st = os.stat(p)
except OSError:
continue
groups.setdefault(os.path.relpath(dirpath, ROOT), []).append({
"rel": rel,
"title": title_of(p),
"size": st.st_size,
"mtime": st.st_mtime,
})
total += 1
lines = ["# Индекс документации",
"",
"Сгенерировано: %s · файлов: **%d** · генератор: `ops/scripts/build_docs_index.py`"
% (datetime.datetime.now().strftime("%Y-%m-%d %H:%M"), total),
"",
"Навигация по каталогам. Свежие файлы — сверху."]
for d in sorted(groups):
items = sorted(groups[d], key=lambda x: -x["mtime"])
fresh = sum(1 for i in items if i["mtime"] > datetime.datetime.now().timestamp() - 7 * 86400)
lines.append("")
lines.append("## %s — %d файлов (%d за неделю)" % (d, len(items), fresh))
lines.append("")
lines.append("| Документ | О чём | Изменён |")
lines.append("|---|---|---|")
for i in items[:40]:
date = datetime.datetime.fromtimestamp(i["mtime"]).strftime("%d.%m")
name = i["rel"].split("/")[-1]
lines.append("| [%s](%s) | %s | %s |"
% (name, i["rel"], (i["title"] or "—").replace("|", "/")[:70], date))
if len(items) > 40:
lines.append("| … ещё %d | | |" % (len(items) - 40))
open(OUT, "w", encoding="utf-8").write("\n".join(lines) + "\n")
print("записано:", OUT)
print("файлов:", total, "| каталогов:", len(groups))
print("размер индекса:", os.path.getsize(OUT) // 1024, "КБ")
if __name__ == "__main__":
main()