Различия

Показаны различия между двумя версиями страницы.

--- sharixopen:knowledge:publishing:page_layout [2026/10/17 07:44] – [sharixknowledge] approved package sx_knowledge_api_open
+++ sharixopen:knowledge:publishing:page_layout [2026/10/17 12:36] (текущий) – [sharixknowledge] approved package sx_knowledge_api_open
@@ Строка 1: / Строка 1: @@
-====== Стандарт оформления страницы: навигация, граф, каталог и связи ======
-[[sharixopen:knowledge:start|База знаний ShariX]] · [[sharixopen:knowledge:publishing:start|Подготовка архивов]] · [[sharixopen:knowledge:publishing:page_layout|Обязательные блоки страниц]] · [[sharixopen:knowledge:publishing:bundle_v1|Формат ZIP]] · [[sharixopen:knowledge:publishing:routing_and_review|Open / Platform / Joint]] · [[sharixopen:knowledge:publishing:ai_rules|Правила для ИИ]]
-**Назначение:** обязательный шаблон для всех новых и обновляемых управляемых страниц ShariX Knowledge. Он одинаково применяется к документации ''open'', ''platform'' и ''joint'', но сведения каждой области публикуются только в соответствующей wiki. **Статус:** проект правил ''review''.
-===== 1. Почему необходим шаблон =====
-Машинные связи в ''manifest.json'' нужны графу, но не создают понятного меню для человека. Обычные DokuWiki-ссылки необходимы даже при наличии графа. Раздел, состоящий из отдельных страниц без точки входа, не считается корректно оформленным. Если в пакете несколько документов, их надо объединить в одну объяснимую структуру.
-===== 2. Какие блоки обязательны =====
-^ Элемент ^ Главная страница wiki / стартовая страница раздела ^ Обычная содержательная страница ^ Назначение ^
-| Заголовок ''====== ... ======'' | Да | Да | Понятное название документа |
-| Путь навигации и ссылка на родительский раздел | Да (на главный каталог, если есть родитель) | Да | Переходы читателя без графа |
-| Краткое описание, назначение и статус документа | Да | Да | Что описано, для кого и насколько утверждено |
-| Оглавление и явные wiki-ссылки на дочерние/тематические страницы | Да | По смыслу, минимум ссылка на родителя и связанные материалы | Не допускать страниц-сирот |
-| ''%%~~NOCACHE~~%%'' | Да | Да, если присутствует динамический блок | Снять риск кеширования ACL-зависимых блоков |
-| ''%%~~SHARIX_KNOWLEDGE_GRAPH~~%%'' | **Да** | Нет, кроме осмысленных специальных страниц-обзоров | Визуальная карта знаний с фильтрами |
-| ''%%~~SHARIX_KNOWLEDGE_CATALOG~~%%'' | **Да** | Нет, кроме страниц-каталогов | Текстовые ссылки на опубликованные доступные материалы |
-| ''%%~~SHARIX_KNOWLEDGE_RELATED~~%%'' | Рекомендуется, если страница управляется ShariX Knowledge | **Да** | Соседи по связям для открытой страницы |
-| Раздел «Связанные материалы» и ссылки назад/вперёд | Да | Да | Завершить маршрут чтения |
-**Важно:** каталог и граф плагина показывают опубликованные **доступные текущему посетителю** материалы соответствующей wiki, а не только текущий раздел. Нужное меню конкретного раздела пишется вручную обычными DokuWiki-ссылками. Один ''RELATED'' не заменяет ''GRAPH'', ''CATALOG'' или меню.
-Эти блоки требуют установленного и работоспособного плагина ShariX Knowledge с поддержкой графа (сборка 0.1.5+, включая исправленную 0.1.7). Для неуправляемых старых страниц автоматические связи могут отсутствовать. Не делать вид, что связность проверена только потому, что синтаксис распознан.
-===== 3. Каноническая стартовая страница раздела =====
-Вместо фиктивных адресов подставить реальный namespace и действительные названия страниц. Код ниже — **образец содержимого DokuWiki**, а не буквальный текст для слепой вставки.
-<code text>
-====== Название раздела ======
-[[sharixopen:knowledge:start|База знаний]] · [[sharixopen:example:start|Название раздела]]
-**Назначение:** что находится в разделе и кто его читатель.
-**Статус:** draft / review / approved / deprecated; не путать с lifecycle.
-===== С чего начать =====
-  * [[sharixopen:example:concepts|Понятия и термины]] — введение.
-  * [[sharixopen:example:usage|Сценарии использования]] — практическая часть.
-  * [[sharixopen:example:setup|Настройка]] — руководство.
-===== Граф знаний =====
-~~NOCACHE~~
-~~SHARIX_KNOWLEDGE_GRAPH~~
-===== Каталог опубликованных документов =====
-~~SHARIX_KNOWLEDGE_CATALOG~~
-===== Связанные материалы =====
-~~SHARIX_KNOWLEDGE_RELATED~~
-[[sharixopen:knowledge:start|Вернуться к главной базе знаний]]
-</code>
-''example'' выше только условный namespace; перед публикацией заменить его на реальные существующие или создаваемые страницы. В ''platform'' и ''joint'' заменять **все** адреса на соответствующие внутренние пространства, не оставляя открытые ссылки на выдуманные внутренние страницы.
-===== 4. Каноническая дочерняя страница =====
-<code text>
-====== Название документа ======
-[[sharixopen:knowledge:start|База знаний]] · [[sharixopen:example:start|Раздел]] · Текущая страница
-**Назначение:** зачем нужен документ.
-**Статус документа:** review. **Состояние разработки:** planned / in_progress / implemented / retired / unspecified.
-===== Содержание =====
-Конкретные проверяемые сведения. Для процесса — участники, условия, шаги и результат;
-для сценария — акторы, предусловия и основной/альтернативный поток;
-для настройки — предпосылки, действия, контроль и откат;
-для термина — определение, контекст применения и ссылки на употребления.
-===== Что читать дальше =====
-  * [[sharixopen:example:another_page|Связанный документ]] — почему он относится к теме.
-  * [[sharixopen:example:start|Вернуться в раздел]].
-===== Связанные материалы =====
-~~NOCACHE~~
-~~SHARIX_KNOWLEDGE_RELATED~~
-</code>
-На реальной дочерней странице **не вставлять** ''GRAPH'' и ''CATALOG'' механически: эти блоки ставятся на главной/стартовой странице. Все три блока допустимы на странице-обзоре, как в стартовом шаблоне выше.
-===== 5. Метаданные графа и текст должны совпадать =====
-^ В тексте ^ В ''manifest.json'' ^ Проверка ^
-| Дочерняя страница раздела | ''extensions.taxonomy.parents'' = реальный ID родительского документа | На странице есть ссылка на родителя; в графе — связь ''contains'' |
-| Зависимость документа | ''relations.depends_on'' = ID требуемого документа | В тексте указано, **в чём** состоит зависимость, со ссылкой на страницу |
-| Применимость, проверка, конфликт, замещение | ''applies_to'', ''verified_by'', ''conflicts_with'', ''supersedes'' | Реальная, обоснованная связь и человекочитаемое объяснение |
-| Тематический переход | ''relations.related_to'' = ID другой страницы | В содержании есть понятная читателю wiki-ссылка |
-| Использование термина | ''extensions.taxonomy.terms'' = существующий ID термина | Термин объяснён или ведёт на словарь |
-Разрешённые ключи ''relations'': ''applies_to'', ''depends_on'', ''supersedes'', ''verified_by'', ''conflicts_with'', ''related_to''. Рёбра ''contains'' строятся из ''taxonomy.parents''; ''uses_term'' — из ''taxonomy.terms'', а ''defines_term'' — из ''extensions.glossary''. В версии плагина 0.1.7 обычные DokuWiki-ссылки в тексте **не образуют автоматически** рёбер ''links_to'': они служат для читательской навигации, а для машинной связи укажите подтверждённое отношение по ID. Все рёбра строятся только для реально опубликованных метаданных страниц, доступных текущему читателю.
-Если точная цель связи неизвестна — не выдумывать ID, URL или документ. Сохранить пояснение в тексте как ''требует уточнения'', не создавать фальшивое ребро. Если у автора нет доступа к intrawiki, публичная страница не должна раскрывать внутреннюю структуру даже через метаданные.
-===== 6. Для Open, Platform и Joint =====
-^ Область ^ ''area'' ^ Формат адресов ^ Где читатель увидит блоки ^
-| ShariX Open | ''open'' | ''sharixopen:...'' | Публичная wiki, только открытые данные |
-| ShariX Platform | ''platform'' | ''sharixplatform:platform:...'' | Только intrawiki, с учётом ACL |
-| Совместная зона | ''joint'' | ''sharixplatform:joint:...'' | Также только intrawiki, с учётом ACL |
-**Публичный автор** может создать структуру предложения для ''platform'' или ''joint'', описав только известные ему открытые факты. Не создавать в Open страницу с реальными названиями или сведениями закрытых процессов. Достаточно безопасного описания предложения, ''status=review'' и передачи через разрешённую модерацию. Администратор intrawiki подтвердит детали, права и ссылки перед публикацией.
-Читайте также [[sharixopen:knowledge:publishing:routing_and_review|правила областей и модерации]].
-===== 7. Обязательная проверка результата ИИ =====
-Перед передачей ZIP автор или ИИ обязан проверить **сами тексты**, а не только ''manifest.json'':
-  - Есть одна логическая точка входа; для каждого поддерева — своя ''start''-страница, если материалов несколько.
-  - На **каждой** странице есть заголовок, вводная часть, статус и ссылки на родителя/близкие материалы; обратный путь работает.
-  - На **каждой стартовой** странице буквально присутствуют три отдельные строки ''GRAPH'', ''CATALOG'', ''NOCACHE'' (полный синтаксис выше), а также реальные текстовые ссылки на дочерние страницы.
-  - На **каждой дочерней** странице буквально присутствует ''RELATED'' и ''NOCACHE'' (полный синтаксис выше) и обычные wiki-ссылки.
-  - Каждый документ имеет правильные ''id'', ''page'', ''area'', ''sha256'' и (только для обновления) настоящий ''base_sha256'' текущего опубликованного текста.
-  - В ''extensions.taxonomy.parents'' и ''relations'' используются действительные ID соответствующих опубликованных или включённых в тот же ZIP документов; никакой вымышленной внутренней структуры.
-  - Указанные в тексте адреса соответствуют ''page'' и действительно существуют либо создаются тем же пакетом. Проверить, что не появляются красные ссылки после публикации.
-  - Все специальные блоки в примерах помещены внутрь блоков исходного кода и поэтому не должны запускаться как виджеты внутри технической документации. На реальных страницах директивы располагаются **вне кодовых блоков** на отдельных строках.
-  - Граф, каталог и блок связанных материалов после публикации действительно отображаются для обычного читателя с учётом ACL. Проверка ZIP **не заменяет** эту проверку браузером.
-Если хоть один пункт нельзя проверить без доступа к wiki — **явно отметить непроверенное**, не писать «всё прошло». Разрешается передать пакет на модерацию как проект, но не объявлять результат опубликованным и корректным.
-===== Связанные материалы =====
-[[sharixopen:knowledge:publishing:start|Главная страница правил]] · [[sharixopen:knowledge:publishing:bundle_v1|Точный формат архива]] · [[sharixopen:knowledge:publishing:ai_rules|Инструкция для ИИ]] · [[sharixopen:standards:knowledge_model_v03|Общая модель знаний]]
-~~NOCACHE~~
-~~SHARIX_KNOWLEDGE_RELATED~~