From b3dac2572992847d6c80f60efa40fb26a03c4ec2 Mon Sep 17 00:00:00 2001
From: Nick Shirokov <nick_4312@mail.ru>
Date: Sat, 7 Feb 2026 22:13:47 +0300
Subject: [PATCH] Add epf-add-help skill and help specification

New skill /epf-add-help creates built-in help files (Help.xml + HTML page)
for external data processors. Also adds IncludeHelpInContents to form
metadata if missing.

New spec docs/1c-help-spec.md documents the help file format, HTML
template, and help button integration on forms.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/epf-add-help/SKILL.md          |  96 +++++++++++
 .../skills/epf-add-help/scripts/add-help.ps1  | 115 +++++++++++++
 README.md                                     |   4 +
 docs/1c-help-spec.md                          | 151 ++++++++++++++++++
 docs/1c-xml-format-spec.md                    |   4 +
 5 files changed, 370 insertions(+)
 create mode 100644 .claude/skills/epf-add-help/SKILL.md
 create mode 100644 .claude/skills/epf-add-help/scripts/add-help.ps1
 create mode 100644 docs/1c-help-spec.md

diff --git a/.claude/skills/epf-add-help/SKILL.md b/.claude/skills/epf-add-help/SKILL.md
new file mode 100644
index 00000000..915cf821
--- /dev/null
+++ b/.claude/skills/epf-add-help/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: epf-add-help
+description: Добавить встроенную справку к внешней обработке 1С
+argument-hint: <ProcessorName>
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# /epf-add-help — Добавление справки
+
+Добавляет встроенную справку к обработке: файл метаданных `Help.xml`, HTML-страницу и при необходимости обновляет метаданные форм.
+
+## Usage
+
+```
+/epf-add-help <ProcessorName> [Lang] [SrcDir]
+```
+
+| Параметр      | Обязательный | По умолчанию | Описание                            |
+|---------------|:------------:|--------------|-------------------------------------|
+| ProcessorName | да           | —            | Имя обработки                       |
+| Lang          | нет          | `ru`         | Код языка справки                   |
+| SrcDir        | нет          | `src`        | Каталог исходников                  |
+
+## Команда
+
+```powershell
+powershell.exe -NoProfile -File .claude/skills/epf-add-help/scripts/add-help.ps1 -ProcessorName "<ProcessorName>" [-Lang "<Lang>"] [-SrcDir "<SrcDir>"]
+```
+
+## Что создаётся
+
+```
+<SrcDir>/<ProcessorName>/
+    Ext/
+        Help.xml                    # Метаданные справки (namespace extrnprops)
+        Help/
+            ru.html                 # HTML-страница справки
+```
+
+- `Help.xml` — фиксированная структура с `<Page>ru</Page>` (namespace `http://v8.1c.ru/8.3/xcf/extrnprops`)
+- `ru.html` — HTML 4.0 Transitional с подключением стилей 1С (`v8help://service_book/service_style`)
+- Справка **не регистрируется** в `ChildObjects` корневого XML — достаточно наличия файлов
+
+## Что модифицируется
+
+- Если в метаданных формы (`Forms/<FormName>.xml`) отсутствует `<IncludeHelpInContents>` — скрипт добавит `<IncludeHelpInContents>false</IncludeHelpInContents>` после `<FormType>`. Для форм, созданных через `/epf-add-form`, элемент уже есть.
+
+## Кнопка справки на форме
+
+После создания справки для её вызова нужна кнопка на форме. Добавь кнопку `Form.StandardCommand.Help` в AutoCommandBar формы (`Forms/<FormName>/Ext/Form.xml`).
+
+### Текущая структура AutoCommandBar (созданная epf-add-form)
+
+```xml
+<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
+    <Autofill>true</Autofill>
+</AutoCommandBar>
+```
+
+### Нужно заменить на
+
+```xml
+<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
+    <Autofill>true</Autofill>
+    <ChildItems>
+        <Button name="ФормаСправка" id="{{свободный_id}}">
+            <Type>CommandBarButton</Type>
+            <CommandName>Form.StandardCommand.Help</CommandName>
+            <ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="{{свободный_id + 1}}"/>
+        </Button>
+    </ChildItems>
+</AutoCommandBar>
+```
+
+### Выбор id
+
+Просмотри все `id="..."` в `Form.xml` и выбери следующий свободный числовой id. Обычно id начинаются с 1 и идут подряд. Для кнопки нужны 2 id: один для Button, один для ExtendedTooltip.
+
+### Важно
+
+- `Form.StandardCommand.Help` — стандартная команда платформы, не нужно объявлять в `<Commands>`
+- Обработчика в Module.bsl не требуется — платформа сама найдёт `Help.xml` и откроет HTML
+
+## Редактирование справки
+
+После создания содержимое справки — обычный HTML. Отредактируй `Ext/Help/ru.html` в соответствии с назначением обработки. Поддерживается стандартная HTML-разметка: `<h1>`..`<h4>`, `<p>`, `<ul>`, `<ol>`, `<table>`, `<strong>`, `<em>`, `<a>`, `<pre>`.
+
+## Спецификация
+
+Подробности формата: `docs/1c-help-spec.md`
diff --git a/.claude/skills/epf-add-help/scripts/add-help.ps1 b/.claude/skills/epf-add-help/scripts/add-help.ps1
new file mode 100644
index 00000000..c1081f39
--- /dev/null
+++ b/.claude/skills/epf-add-help/scripts/add-help.ps1
@@ -0,0 +1,115 @@
+param(
+	[Parameter(Mandatory)]
+	[string]$ProcessorName,
+
+	[string]$Lang = "ru",
+
+	[string]$SrcDir = "src"
+)
+
+$ErrorActionPreference = "Stop"
+
+# --- Проверки ---
+
+$processorDir = Join-Path $SrcDir $ProcessorName
+$extDir = Join-Path $processorDir "Ext"
+
+if (-not (Test-Path $extDir)) {
+	Write-Error "Каталог обработки не найден: $extDir. Сначала выполните epf-init."
+	exit 1
+}
+
+$helpXmlPath = Join-Path $extDir "Help.xml"
+if (Test-Path $helpXmlPath) {
+	Write-Error "Справка уже существует: $helpXmlPath"
+	exit 1
+}
+
+# --- Кодировка ---
+
+$encBom = New-Object System.Text.UTF8Encoding($true)
+
+# --- 1. Help.xml ---
+
+$helpXml = @"
+<?xml version="1.0" encoding="UTF-8"?>
+<Help xmlns="http://v8.1c.ru/8.3/xcf/extrnprops" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.17">
+	<Page>$Lang</Page>
+</Help>
+"@
+
+[System.IO.File]::WriteAllText($helpXmlPath, $helpXml, $encBom)
+
+# --- 2. Help/<lang>.html ---
+
+$helpDir = Join-Path $extDir "Help"
+New-Item -ItemType Directory -Path $helpDir -Force | Out-Null
+
+$helpHtmlPath = Join-Path $helpDir "$Lang.html"
+
+$helpHtml = @"
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <link rel="stylesheet" type="text/css" href="v8help://service_book/service_style"/>
+</head>
+<body>
+    <h1>$ProcessorName</h1>
+    <p>Описание обработки.</p>
+</body>
+</html>
+"@
+
+[System.IO.File]::WriteAllText($helpHtmlPath, $helpHtml, $encBom)
+
+# --- 3. Проверка IncludeHelpInContents в метаданных форм ---
+
+$formsDir = Join-Path $processorDir "Forms"
+if (Test-Path $formsDir) {
+	$formMetaFiles = Get-ChildItem -Path $formsDir -Filter "*.xml" -File
+	foreach ($formMeta in $formMetaFiles) {
+		$xmlDoc = New-Object System.Xml.XmlDocument
+		$xmlDoc.PreserveWhitespace = $true
+		$xmlDoc.Load($formMeta.FullName)
+
+		$nsMgr = New-Object System.Xml.XmlNamespaceManager($xmlDoc.NameTable)
+		$nsMgr.AddNamespace("md", "http://v8.1c.ru/8.3/MDClasses")
+
+		$includeHelp = $xmlDoc.SelectSingleNode("//md:IncludeHelpInContents", $nsMgr)
+		if (-not $includeHelp) {
+			# Добавить после <FormType>
+			$formType = $xmlDoc.SelectSingleNode("//md:FormType", $nsMgr)
+			if ($formType) {
+				$newElem = $xmlDoc.CreateElement("IncludeHelpInContents", "http://v8.1c.ru/8.3/MDClasses")
+				$newElem.InnerText = "false"
+				$parent = $formType.ParentNode
+				$nextSibling = $formType.NextSibling
+				# Вставить перенос + табуляцию + элемент
+				$ws = $xmlDoc.CreateWhitespace("`n`t`t`t")
+				if ($nextSibling) {
+					$parent.InsertBefore($ws, $nextSibling) | Out-Null
+					$parent.InsertBefore($newElem, $ws) | Out-Null
+				} else {
+					$parent.AppendChild($ws) | Out-Null
+					$parent.AppendChild($newElem) | Out-Null
+				}
+
+				$settings = New-Object System.Xml.XmlWriterSettings
+				$settings.Encoding = $encBom
+				$settings.Indent = $false
+				$stream = New-Object System.IO.FileStream($formMeta.FullName, [System.IO.FileMode]::Create)
+				$writer = [System.Xml.XmlWriter]::Create($stream, $settings)
+				$xmlDoc.Save($writer)
+				$writer.Close()
+				$stream.Close()
+
+				Write-Host "     IncludeHelpInContents добавлен: $($formMeta.Name)"
+			}
+		}
+	}
+}
+
+Write-Host "[OK] Создана справка: $ProcessorName"
+Write-Host "     Метаданные: $helpXmlPath"
+Write-Host "     Страница:   $helpHtmlPath"
diff --git a/README.md b/README.md
index 3c319912..627de7e3 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@
 | `/epf-init` | `<Name> [Synonym]` | Создать новую обработку (корневой XML + модуль объекта) |
 | `/epf-add-form` | `<ProcessorName> <FormName> [Synonym]` | Добавить управляемую форму |
 | `/epf-add-template` | `<ProcessorName> <TemplateName> <TemplateType>` | Добавить макет (HTML, Text, SpreadsheetDocument, BinaryData) |
+| `/epf-add-help` | `<ProcessorName>` | Добавить встроенную справку (Help.xml + HTML) |
 | `/epf-remove-form` | `<ProcessorName> <FormName>` | Удалить форму |
 | `/epf-remove-template` | `<ProcessorName> <TemplateName>` | Удалить макет |
 | `/epf-build` | `<ProcessorName>` | Собрать EPF из XML (документация команды 1cv8.exe) |
@@ -97,16 +98,19 @@ src/
 ├── epf-remove-template/ # SKILL.md + scripts/remove-template.ps1
 ├── epf-build/           # SKILL.md (только документация)
 ├── epf-dump/            # SKILL.md (только документация)
+├── epf-add-help/        # SKILL.md + scripts/add-help.ps1
 ├── epf-bsp-init/        # SKILL.md (шаблоны кода, без скриптов)
 └── epf-bsp-add-command/ # SKILL.md (шаблоны кода, без скриптов)
 docs/
 ├── 1c-xml-format-spec.md   # Спецификация XML-формата выгрузки
+├── 1c-help-spec.md         # Спецификация встроенной справки
 └── build-spec.md            # Спецификация команд сборки/разборки
 ```
 
 ## Спецификации
 
 - [XML-формат выгрузки обработок](docs/1c-xml-format-spec.md) — полное описание структуры XML-файлов, namespace'ов, элементов форм
+- [Встроенная справка](docs/1c-help-spec.md) — Help.xml, HTML-страницы, кнопка справки на форме
 - [Сборка и разборка EPF](docs/build-spec.md) — команды `1cv8.exe`, параметры, коды возврата
 
 ## Технические детали
diff --git a/docs/1c-help-spec.md b/docs/1c-help-spec.md
new file mode 100644
index 00000000..dcdb7410
--- /dev/null
+++ b/docs/1c-help-spec.md
@@ -0,0 +1,151 @@
+# Встроенная справка внешней обработки 1С
+
+Спецификация добавления встроенной справки (Help) к внешней обработке (EPF) в формате XML-выгрузки версии 2.17.
+
+## 1. Структура файлов
+
+```
+<ИмяОбработки>/
+    Ext/
+        Help.xml                    # Метаданные справки (обязательно)
+        Help/
+            ru.html                 # HTML-страница справки на русском языке
+```
+
+Справка **не регистрируется** в `ChildObjects` корневого XML обработки — достаточно наличия файлов `Help.xml` и `Help/<язык>.html` в каталоге `Ext/`.
+
+## 2. Help.xml — метаданные справки
+
+Пространство имён: `http://v8.1c.ru/8.3/xcf/extrnprops` (то же, что у Template.xml).
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Help xmlns="http://v8.1c.ru/8.3/xcf/extrnprops"
+      xmlns:xs="http://www.w3.org/2001/XMLSchema"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      version="2.17">
+    <Page>ru</Page>
+</Help>
+```
+
+Элемент `<Page>` указывает код языка. Имя файла страницы: `<код_языка>.html`. Может быть несколько элементов `<Page>` для разных языков.
+
+## 3. HTML-страница справки
+
+Формат: HTML 4.0 Transitional, кодировка UTF-8.
+
+### Минимальный шаблон
+
+```html
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <link rel="stylesheet" type="text/css" href="v8help://service_book/service_style"/>
+</head>
+<body>
+    Содержимое справки
+</body>
+</html>
+```
+
+### Обязательные элементы head
+
+| Элемент | Назначение |
+|---------|------------|
+| `<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>` | Кодировка UTF-8 |
+| `<link rel="stylesheet" type="text/css" href="v8help://service_book/service_style"/>` | Стили справки 1С (протокол `v8help://`) |
+
+### Поддерживаемая разметка
+
+Стандартный HTML 4.0: `<h1>`..`<h4>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<table>`, `<strong>`, `<em>`, `<a>`, `<br>`, `<pre>` и др. Стили 1С автоматически форматируют заголовки и абзацы.
+
+## 4. Метаданные формы — IncludeHelpInContents
+
+В файле метаданных формы (`Forms/<ИмяФормы>.xml`) должен быть элемент:
+
+```xml
+<IncludeHelpInContents>false</IncludeHelpInContents>
+```
+
+Полный контекст в файле формы:
+
+```xml
+<Form uuid="...">
+    <Properties>
+        <Name>ОсновнаяФорма</Name>
+        ...
+        <FormType>Managed</FormType>
+        <IncludeHelpInContents>false</IncludeHelpInContents>
+        <UsePurposes>...</UsePurposes>
+        <ExtendedPresentation/>
+    </Properties>
+</Form>
+```
+
+Значение `false` — справка не включается в общее оглавление справочной системы (стандартное поведение для внешних обработок).
+
+## 5. Кнопка вызова справки на форме
+
+Для вызова справки используется стандартная команда платформы `Form.StandardCommand.Help`.
+
+### Вариант А: кнопка в AutoCommandBar формы
+
+Простейший способ — добавить кнопку в автокомандную панель формы (`id="-1"`):
+
+```xml
+<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
+    <Autofill>false</Autofill>
+    <ChildItems>
+        <Button name="ФормаСправка" id="<свободный_id>">
+            <Type>CommandBarButton</Type>
+            <CommandName>Form.StandardCommand.Help</CommandName>
+            <ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="<свободный_id>"/>
+        </Button>
+    </ChildItems>
+</AutoCommandBar>
+```
+
+Кнопка появится на автокомандной панели формы (верхняя строка). Подходит для простых форм.
+
+### Вариант Б: кнопка в пользовательской CommandBar
+
+Если форма не использует AutoCommandBar (задан `Autofill=false`, панель скрыта или пуста), кнопку справки можно разместить в произвольной `<CommandBar>` группе среди других пользовательских кнопок:
+
+```xml
+<CommandBar name="МояКоманднаяПанель" id="...">
+    <Autofill>false</Autofill>
+    <HorizontalStretch>false</HorizontalStretch>
+    <ExtendedTooltip name="МояКоманднаяПанельExtendedTooltip" id="..."/>
+    <ChildItems>
+        <!-- Другие кнопки -->
+        <Button name="КнопкаДействие" id="...">
+            <Type>CommandBarButton</Type>
+            <CommandName>Form.Command.МояКоманда</CommandName>
+            ...
+        </Button>
+        <!-- Кнопка справки -->
+        <Button name="ФормаСправка" id="<свободный_id>">
+            <Type>CommandBarButton</Type>
+            <CommandName>Form.StandardCommand.Help</CommandName>
+            <ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="<свободный_id>"/>
+        </Button>
+    </ChildItems>
+</CommandBar>
+```
+
+Для стандартной команды `Help` не нужно объявлять элемент в секции `<Commands>` — платформа предоставляет её автоматически.
+
+### Важно
+
+- `<Type>CommandBarButton</Type>` — кнопка должна быть типа CommandBarButton (внутри `<CommandBar>`)
+- Никакого обработчика в Module.bsl не требуется — `Form.StandardCommand.Help` обрабатывается платформой
+- Платформа сама найдёт `Help.xml` и откроет соответствующую HTML-страницу
+
+## 6. Чек-лист добавления справки
+
+1. Создать `<ИмяОбработки>/Ext/Help.xml` с указанием языка (`<Page>ru</Page>`)
+2. Создать `<ИмяОбработки>/Ext/Help/ru.html` с содержимым справки
+3. Убедиться что в `Forms/<ИмяФормы>.xml` есть `<IncludeHelpInContents>false</IncludeHelpInContents>`
+4. Добавить кнопку `Form.StandardCommand.Help` в CommandBar или AutoCommandBar формы
+5. Собрать EPF — проверить что справка открывается по кнопке
diff --git a/docs/1c-xml-format-spec.md b/docs/1c-xml-format-spec.md
index e2e566c0..0f1d3778 100644
--- a/docs/1c-xml-format-spec.md
+++ b/docs/1c-xml-format-spec.md
@@ -10,6 +10,9 @@
 <ИмяОбработки>/
     Ext/
         ObjectModule.bsl                     # Модуль объекта (опционально)
+        Help.xml                             # Метаданные справки (опционально)
+        Help/
+            ru.html                          # HTML-страница справки
     Forms/
         <ИмяФормы>.xml                       # Метаданные формы
         <ИмяФормы>/
@@ -28,6 +31,7 @@
 - 0..N форм (каталог `Forms/`)
 - 0..N макетов (каталог `Templates/`)
 - 0..1 модуль объекта (`Ext/ObjectModule.bsl`)
+- 0..1 встроенная справка (`Ext/Help.xml` + `Ext/Help/<язык>.html`), см. [1c-help-spec.md](1c-help-spec.md)
 - 0..N табличных частей (описаны в корневом XML)
 
 ## 2. Пространства имён XML