справочник команд: единый источник правды, генератор /help и docs/COMMANDS.md

This commit is contained in:
root committed 2026-10-15 15:58:40 +03:00
1 parent cf2b2fd9ab
commit 8ab2c4251b
3 files changed
+484

No files matched your search

+44
View File
@@ -0,0 +1,44 @@
# Справочник команд
Файл создан автоматически из `ops/bots/commands.yaml`.
**Правьте справочник, а не этот файл.**
## ADM — Управление службами и состояние инфраструктуры
Отвечает на команды о состоянии и выполняет перезапуски.
| Команда | Что делает | Доступ | Состояние |
|---|---|---|---|
| `/status` | Показывает состояние хостов и служб с ответами проверок. | все | готово |
| `/issues` | Список открытых задач Gitea с метками важности. | все | готово |
| `/runbook <сервис>` | Показывает инструкцию по обслуживанию указанного сервиса. | все | готово |
| `/restart <сервис>` | Перезапускает службу через службу восстановления. | админ | готово |
## WORK — Обновления и рабочие задачи
Показывает очередь обновлений и принимает решения по ним.
| Команда | Что делает | Доступ | Состояние |
|---|---|---|---|
| `/queue` | Показывает очередь обновлений с номерами заявок. | все | готовится |
| `/approve <номер>` | Ставит заявку в работу — обновление будет выполнено. | админ | готовится |
| `/reject <номер>` | Отклоняет заявку — обновление выполнено не будет. | админ | готовится |
| `/update <служба>` | Немедленно ставит обновление службы в очередь. | админ | готовится |
## AUTH — Доступ и регистрация
Обслуживает заявки на доступ к сервисам.
| Команда | Что делает | Доступ | Состояние |
|---|---|---|---|
| `/requests` | Показывает необработанные заявки на регистрацию. | админ | готовится |
| `/approve-user <почта>` | Даёт доступ указанному пользователю и создаёт учётную запись. | админ | готовится |
| `/deny-user <почта>` | Отклоняет заявку на доступ. | админ | готовится |
## MEDIA — Медиа-службы
Состояние и управление медиасервисами.
| Команда | Что делает | Доступ | Состояние |
|---|---|---|---|
| `/media` | Показывает состояние медиасервисов и их очереди загрузок. | все | готовится |
## Общие команды
- `/help [команда]` — Показывает команды этого бота. Можно указать команду подробнее.
+189
View File
@@ -0,0 +1,189 @@
# ============================================================
# Справочник команд buryan-hub — ЕДИНСТВЕННЫЙ ИСТОЧНИК ПРАВДЫ
# ============================================================
# Из этого файла генерируется:
# * ответ /help в каждом боте (только его команды);
# * docs/COMMANDS.md в репозитории;
# * закреплённое сообщение в комнате Matrix.
#
# ДОБАВИТЬ КОМАНДУ = ДОБАВИТЬ ЗАПИСЬ СЮДА. Помощь обновится сама.
#
# Поля:
# command — как вызывается, без слэша
# bot — какому боту принадлежит: adm | work | alert | auth | media
# title — короткое название
# description — что делает, одним предложением
# usage — как вызывать
# examples — примеры (показываются в /help)
# access — admin | user (кто может вызывать)
# aliases — другие написания
# status — ready | planned (planned показывается серым, но видно)
bots:
adm:
name: ADM
purpose: Управление службами и состояние инфраструктуры
about: Отвечает на команды о состоянии и выполняет перезапуски.
work:
name: WORK
purpose: Обновления и рабочие задачи
about: Показывает очередь обновлений и принимает решения по ним.
alert:
name: ALERT
purpose: Тревоги инфраструктуры
about: Только сообщает о проблемах и восстановлении. Команд не принимает.
auth:
name: AUTH
purpose: Доступ и регистрация
about: Обслуживает заявки на доступ к сервисам.
media:
name: MEDIA
purpose: Медиа-службы
about: Состояние и управление медиасервисами.
commands:
# ─── ADM: состояние и управление ───────────────────────────
- command: status
bot: adm
title: Состояние служб
description: Показывает состояние хостов и служб с ответами проверок.
usage: /status
examples:
- /status
access: user
aliases: ["!status"]
status: ready
- command: issues
bot: adm
title: Открытые задачи
description: Список открытых задач Gitea с метками важности.
usage: /issues
examples:
- /issues
access: user
aliases: ["!issues"]
status: ready
- command: runbook
bot: adm
title: Ранбук сервиса
description: Показывает инструкцию по обслуживанию указанного сервиса.
usage: /runbook <сервис>
examples:
- /runbook radarr
- /runbook n8n
access: user
aliases: ["!runbook"]
status: ready
- command: restart
bot: adm
title: Перезапуск службы
description: Перезапускает службу через службу восстановления.
usage: /restart <сервис>
examples:
- /restart radarr
access: admin
aliases: ["!restart"]
status: ready
# ─── WORK: обновления ──────────────────────────────────────
- command: queue
bot: work
title: Очередь обновлений
description: Показывает очередь обновлений с номерами заявок.
usage: /queue
examples:
- /queue
access: user
status: planned
- command: approve
bot: work
title: Одобрить обновление
description: Ставит заявку в работу — обновление будет выполнено.
usage: /approve <номер>
examples:
- /approve 17
access: admin
status: planned
- command: reject
bot: work
title: Отклонить обновление
description: Отклоняет заявку — обновление выполнено не будет.
usage: /reject <номер>
examples:
- /reject 17
access: admin
status: planned
- command: update
bot: work
title: Обновить службу сейчас
description: Немедленно ставит обновление службы в очередь.
usage: /update <служба>
examples:
- /update prowlarr
access: admin
status: planned
# ─── AUTH: доступ ──────────────────────────────────────────
- command: requests
bot: auth
title: Заявки на доступ
description: Показывает необработанные заявки на регистрацию.
usage: /requests
examples:
- /requests
access: admin
status: planned
- command: approve-user
bot: auth
title: Одобрить заявку
description: Даёт доступ указанному пользователю и создаёт учётную запись.
usage: /approve-user <почта>
examples:
- /approve-user user@example.com
access: admin
status: planned
- command: deny-user
bot: auth
title: Отклонить заявку
description: Отклоняет заявку на доступ.
usage: /deny-user <почта>
examples:
- /deny-user user@example.com
access: admin
status: planned
# ─── MEDIA: медиасервисы ───────────────────────────────────
- command: media
bot: media
title: Состояние медиасервисов
description: Показывает состояние медиасервисов и их очереди загрузок.
usage: /media
examples:
- /media
access: user
status: planned
# ─── Общие для всех ботов ──────────────────────────────────
- command: help
bot: all
title: Справка
description: Показывает команды этого бота. Можно указать команду подробнее.
usage: /help [команда]
examples:
- /help
- /help restart
access: user
status: ready
+251
View File
@@ -0,0 +1,251 @@
#!/usr/bin/env python3
"""Генератор справки по командам.
Из единственного источника правды (commands.yaml) делает:
* ответ /help для каждого бота — только его команды;
* docs/COMMANDS.md — общий справочник в репозитории;
* подсказку при опечатке.
Зачем: команды не должны жить в голове и не должны быть зашиты
в код. Добавить команду = добавить запись в commands.yaml,
а справка обновится сама.
Использование:
python3 gen_help.py — показать справку всем ботам
python3 gen_help.py --bot adm — справка одного бота
python3 gen_help.py --command restart — подробно про команду
python3 gen_help.py --markdown FILE — записать общий справочник
python3 gen_help.py --suggest statsu — подсказать похожую команду
"""
from __future__ import annotations
import argparse
import difflib
import os
import sys
try:
import yaml
except ImportError: # запасной разбор, если PyYAML не установлен
yaml = None
CATALOG = os.getenv("COMMANDS_FILE",
os.path.join(os.path.dirname(os.path.abspath(__file__)),
"commands.yaml"))
def load(path: str = CATALOG) -> dict:
"""Читает справочник. Если PyYAML нет — разбирает встроенным способом."""
with open(path, encoding="utf-8") as fh:
text = fh.read()
if yaml is not None:
return yaml.safe_load(text)
return _simple_parse(text)
def _simple_parse(text: str) -> dict:
"""Минимальный разбор YAML для нашего формата — без внешних зависимостей.
Понимает списки словарей с простыми значениями и списками строк.
Нужен, чтобы справка работала даже там, где PyYAML не установлен.
"""
data: dict = {"bots": {}, "commands": []}
section = None
item: dict | None = None
list_key = None
bot_key = None
bot_item: dict | None = None
for raw in text.split("\n"):
line = raw.rstrip()
if not line or line.lstrip().startswith("#"):
continue
stripped = line.strip()
if line.startswith("bots:") and not line.startswith(" "):
section, item, bot_item = "bots", None, None
continue
if line.startswith("commands:") and not line.startswith(" "):
section, item, bot_item = "commands", None, None
continue
if section == "bots":
if line.startswith(" ") and not line.startswith(" ") and stripped.endswith(":"):
bot_key = stripped[:-1]
bot_item = {}
data["bots"][bot_key] = bot_item
continue
if bot_item is not None and ":" in stripped:
k, v = stripped.split(":", 1)
bot_item[k.strip()] = v.strip()
continue
continue
if section == "commands":
if stripped.startswith("- "):
item = {}
data["commands"].append(item)
list_key = None
rest = stripped[2:]
if ":" in rest:
k, v = rest.split(":", 1)
item[k.strip()] = v.strip()
continue
if item is None:
continue
if stripped.endswith(":") and not stripped.startswith("-"):
list_key = stripped[:-1]
item[list_key] = []
continue
if stripped.startswith("- ") and list_key:
item[list_key].append(stripped[2:].strip().strip('"\''))
continue
if ":" in stripped:
k, v = stripped.split(":", 1)
item[k.strip()] = v.strip().strip('"\'')
list_key = None
return data
def commands_for(data: dict, bot: str) -> list[dict]:
"""Команды бота: его собственные плюс общие (bot: all)."""
out = []
for cmd in data.get("commands", []):
if cmd.get("bot") in (bot, "all"):
out.append(cmd)
return out
def help_text(data: dict, bot: str) -> str:
"""Справка для бота. Коротко: название, вызов, описание."""
info = data.get("bots", {}).get(bot, {})
lines = []
if info.get("name"):
lines.append(f"<b>{info['name']}</b> — {info.get('purpose', '')}")
lines.append("")
ready = [c for c in commands_for(data, bot) if c.get("status") != "planned"]
planned = [c for c in commands_for(data, bot) if c.get("status") == "planned"]
lines.append("Доступные команды:")
for cmd in ready:
access = " (только админ)" if cmd.get("access") == "admin" else ""
lines.append(f"/{cmd['command']} — {cmd.get('description', '')}{access}")
if planned:
lines.append("")
lines.append("Готовятся:")
for cmd in planned:
lines.append(f"/{cmd['command']} — {cmd.get('description', '')}")
lines.append("")
lines.append("Подробнее о команде: /help <команда>")
return "\n".join(lines)
def command_help(data: dict, name: str) -> str | None:
"""Подробная справка по одной команде."""
name = name.lstrip("/!").strip()
for cmd in data.get("commands", []):
if cmd.get("command") == name or name in (cmd.get("aliases") or []):
lines = [f"<b>/{cmd['command']}</b> — {cmd.get('title', '')}"]
lines.append(cmd.get("description", ""))
lines.append("")
lines.append(f"Вызов: <code>{cmd.get('usage', '/' + cmd['command'])}</code>")
if cmd.get("examples"):
lines.append("Примеры:")
for ex in cmd["examples"]:
lines.append(f" <code>{ex}</code>")
if cmd.get("aliases"):
lines.append(f"Варианты: {', '.join(cmd['aliases'])}")
if cmd.get("access") == "admin":
lines.append("Доступ: только администратор")
if cmd.get("status") == "planned":
lines.append("Состояние: готовится, пока не работает")
if cmd.get("bot") and cmd["bot"] != "all":
lines.append(f"Бот: {data.get('bots', {}).get(cmd['bot'], {}).get('name', cmd['bot'])}")
return "\n".join(lines)
return None
def suggest(data: dict, wrong: str | None) -> str | None:
"""Подсказка при опечатке: «возможно, вы имели в виду»."""
if not wrong:
return None
names = [c["command"] for c in data.get("commands", [])]
close = difflib.get_close_matches(wrong.lstrip("/!").strip(), names, n=1, cutoff=0.6)
if close:
return f"Команда не распознана. Возможно, вы имели в виду /{close[0]}? Список: /help"
return "Команда не распознана. Список команд: /help"
def markdown(data: dict) -> str:
"""Общий справочник для репозитория."""
lines = ["# Справочник команд", "",
"Файл создан автоматически из `ops/bots/commands.yaml`.",
"**Правьте справочник, а не этот файл.**", ""]
for bot_key, info in data.get("bots", {}).items():
cmds = [c for c in commands_for(data, bot_key) if c.get("bot") == bot_key]
if not cmds:
continue
lines.append(f"## {info.get('name', bot_key)} — {info.get('purpose', '')}")
if info.get("about"):
lines.append(info["about"])
lines.append("")
lines.append("| Команда | Что делает | Доступ | Состояние |")
lines.append("|---|---|---|---|")
for cmd in cmds:
access = "админ" if cmd.get("access") == "admin" else "все"
state = "готово" if cmd.get("status") != "planned" else "готовится"
lines.append(f"| `{cmd.get('usage', '/' + cmd['command'])}` | "
f"{cmd.get('description', '')} | {access} | {state} |")
lines.append("")
lines.append("## Общие команды")
lines.append("")
for cmd in data.get("commands", []):
if cmd.get("bot") == "all":
lines.append(f"- `{cmd.get('usage')}` — {cmd.get('description', '')}")
lines.append("")
return "\n".join(lines)
def main() -> int:
ap = argparse.ArgumentParser(description="Генератор справки по командам")
ap.add_argument("--bot", help="показать справку одного бота")
ap.add_argument("--command", help="подробно про команду")
ap.add_argument("--suggest", help="подсказать похожую команду")
ap.add_argument("--markdown", metavar="FILE", help="записать общий справочник")
ap.add_argument("--catalog", default=CATALOG, help="путь к справочнику")
args = ap.parse_args()
if not os.path.exists(args.catalog):
print(f"справочник не найден: {args.catalog}", file=sys.stderr)
return 1
data = load(args.catalog)
if args.command:
print(command_help(data, args.command) or "Команда не найдена")
return 0
if args.suggest:
print(suggest(data, args.suggest) or "")
return 0
if args.markdown:
with open(args.markdown, "w", encoding="utf-8") as fh:
fh.write(markdown(data))
print(f"записан справочник: {args.markdown}")
return 0
if args.bot:
print(help_text(data, args.bot))
return 0
for bot in data.get("bots", {}):
print("=" * 60)
print(help_text(data, bot))
print()
return 0
if __name__ == "__main__":
raise SystemExit(main())