Поиск по справке и образцам Plank

Поиск по справке и образцам Plank

plank_docs_search ищет по собственной документации Plank и готовым образцам. Индекс один для всех пространств и не содержит ничего из пространств: ни файлов, ни чатов, ни данных клиентов. Для прошлой работы этого пространства есть plank_history_search.

Где он ищет

• help — все статьи этой справки, на русском и английском
• template — шаблоны дашбордов («Шаблоны»)
• use_case — опубликованные сценарии из Настройки → Сценарии
• kit — наборы скриптов Plank (1С, банковские выписки, ЭСФ, зарплата, финансы, соцсети, Kaspi…): манифест набора, его README и заголовок (как запускать) каждого скрипта, но не весь код
• asset — сборщики презентаций и отчётов, которые раздаёт справка (plank_deck.py и соседние)

Индекс пересобирает Plank при выпуске релиза, а не на каждый вопрос, поэтому вызов — это один быстрый поиск.

Когда искать

• Перед тем как делать с нуля дашборд, скрипт, презентацию, интеграцию, автоматизацию: в Plank может уже быть шаблон, набор или сборщик.
• Перед тем как гадать, как работает функция Plank, или говорить человеку, что Plank этого не умеет.
• Не для файлов и прошлых чатов пространства (plank_history_search) и не для интернета.

Лучше всего работают один-два конкретных запроса словами человека: «дашборд продаж с воронкой», «загрузить выписку в 1С».

Как вызывать

plank_docs_search({ query: "сверка с контрагентом в 1С" })
plank_docs_search({ query: "еженедельный отчёт по продажам", kinds: ["template", "use_case"], limit: 5 })

kinds сужает поиск до help, template, use_case, kit, asset; limit — от 1 до 10 (по умолчанию 5).

Каждый результат — карточка: вид, заголовок и раздел, ref (help:<slug>, template:<slug>, use_case:<slug>, kit:<id>/<путь>, asset:<файл>), адрес, строка «как использовать» и фрагмент. Фрагмент — не ответ: откройте источник и берите шаги, названия и ограничения из него:

• статья справки — curl -s https://plank.md/ru/help/<slug>.md (английская — /help/<slug>.md)
• шаблон — plank_dashboard_template_get({ slug }), затем постройте на данных человека и опубликуйте с template_slug (см. /help/dashboards)
• сборщик — скачайте той командой curl, что дана в карточке
• файл набора — прочитайте в пространстве, если набор установлен, иначе см. ниже

Если ни одна карточка не о том, что спросили, так и скажите и не придумывайте функцию Plank.

Набора нет в этом пространстве

Пространство получает набор только при создании из шаблона, который его несёт, поэтому карточка может назвать набор, которого здесь нет. В scripts/.plank-kits.json перечислены наборы (и версии), которые пространство получило; если файла нет, ничего не записано.

Чтобы добавить набор, возьмите его манифест — https://plank.md/help/kits/<id>/manifest.json: в нём каждый файл с адресом и sha256 и installOrder, который подтягивает наборы-зависимости. Устанавливайте из корня пространства, добавляя только отсутствующие файлы:

BASE=https://plank.md/help/kits
KIT=<id>
for K in $(curl -fsS "$BASE/$KIT/manifest.json" | jq -r '.installOrder[]'); do
  curl -fsS "$BASE/$K/manifest.json" | jq -r '.files[].path' | while read -r p; do
    [ -e "$p" ] && continue
    mkdir -p "$(dirname "$p")"
    curl -fsS "$BASE/$K/files/$p" -o "$p"
  done
done

Никогда не перезаписывайте существующий файл: набор в пространстве часто доработан под компанию. Для обновления установленного набора есть своя процедура (см. /help/1c-starter-kit, «Обновление уже установленного набора»). Скажите человеку, что вы установили.