справочник команд: единый источник правды, генератор /help и docs/COMMANDS.md
This commit is contained in:
1 parent
cf2b2fd9ab
commit
8ab2c4251b
3 files changed
+484
No files matched your search
@@ -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 [команда]` — Показывает команды этого бота. Можно указать команду подробнее.
|
||||
@@ -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
|
||||
@@ -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())
|
||||
Reference in new issue
Block a user