architect/_archive/2025-11-26-cleanup/cifra/archive/2025-11-10-restructure-v2/HOW_TO_WORK_WITH_DOCS.md

Как работать с документами платформы

Версия: 1.0.0
Дата: 2025-11-10
Цель: Объяснить КАК технически работать с документами

🎯 ГЛАВНЫЙ ОТВЕТ

ВАМ НЕ НУЖНА СПЕЦИАЛЬНАЯ ПРОГРАММА!

Все документы — это обычные текстовые файлы (Markdown, YAML, Python).

Работать можно:
- ✅ Через SSH (nano, vim)
- ✅ Через VS Code (удобнее всего)
- ✅ Через GitHub (веб-интерфейс)
- 🟡 Через веб-панель (можно сделать, но необязательно)

📋 ВАРИАНТЫ РАБОТЫ (от простого к сложному)

✅ ВАРИАНТ 1: Через SSH (уже работает!)

Что нужно: Только SSH доступ (у вас уже есть)

Как это работает:

# 1. Подключаемся к серверу
ssh root@91.218.142.168

# 2. Переходим в workspace
cd /opt/claude-workspace

# 3. Открываем документ в редакторе
nano projects/marketplace/PROJECT.md

# Или vim (если привычнее)
vim projects/marketplace/PROJECT.md

Редакторы в терминале:

nano (самый простой)

nano projects/marketplace/PROJECT.md

# Управление:
Ctrl+O  # Сохранить
Ctrl+X  # Выйти
Ctrl+K  # Вырезать строку
Ctrl+U  # Вставить

Плюсы:
- ✅ Уже установлен
- ✅ Простой (подсказки внизу)
- ✅ Не нужно учиться

Минусы:
- ⚠️ Нет подсветки синтаксиса
- ⚠️ Неудобно для больших файлов

vim (продвинутый)

vim projects/marketplace/PROJECT.md

# Режимы:
i           # Вставить текст (INSERT mode)
Esc         # Командный режим
:w          # Сохранить
:q          # Выйти
:wq         # Сохранить и выйти
/поиск      # Поиск

Плюсы:
- ✅ Мощный (много возможностей)
- ✅ Подсветка синтаксиса

Минусы:
- ⚠️ Нужно учиться
- ⚠️ Непривычный

Как работать через SSH:

1. Посмотреть файл:

cat projects/marketplace/PROJECT.md
# Или с нумерацией строк:
cat -n projects/marketplace/PROJECT.md
# Или постранично:
less projects/marketplace/PROJECT.md

2. Редактировать:

nano projects/marketplace/PROJECT.md
# Редактируем, Ctrl+O, Ctrl+X

3. Git commit:

git add projects/marketplace/PROJECT.md
git commit -m "docs: обновлён PROJECT.md"

Итого через SSH:
- ✅ Работает прямо сейчас
- ✅ Не нужно ничего устанавливать
- ⚠️ Не очень удобно для больших правок

✅ ВАРИАНТ 2: Через VS Code (РЕКОМЕНДУЮ!)

Что нужно: VS Code на вашем компьютере + SSH доступ

Что такое VS Code:

Как настроить (один раз):

Шаг 1: Установить VS Code

Скачать с: https://code.visualstudio.com/

Windows: .exe установщик
Mac: .dmg
Linux: .deb / .rpm

Шаг 2: Установить расширение Remote-SSH

1. Открыть VS Code
2. Нажать Ctrl+Shift+X (Extensions)
3. Найти "Remote - SSH"
4. Нажать Install

Шаг 3: Подключиться к серверу

1. Нажать F1 (или Ctrl+Shift+P)
2. Выбрать "Remote-SSH: Connect to Host..."
3. Ввести: root@91.218.142.168
4. Ввести пароль (или использовать SSH ключ)

Шаг 4: Открыть workspace

1. File → Open Folder
2. Выбрать: /opt/claude-workspace
3. VS Code теперь работает НАПРЯМУЮ с сервером!

Как работать в VS Code:

Открыть файл:

Ctrl+P → набрать "PROJECT.md" → Enter

Редактировать:

Просто редактируете как обычный текстовый файл
- Подсветка синтаксиса ✅
- Автодополнение ✅
- Поиск/замена ✅
- Предпросмотр Markdown ✅

Предпросмотр Markdown:

Открыть PROJECT.md
Нажать Ctrl+Shift+V → Preview
Видите красиво отформатированный документ!

Git операции:

1. Source Control (Ctrl+Shift+G)
2. Видите все изменения
3. Пишете commit message
4. Нажимаете Commit (галочка вверху)

Терминал внутри VS Code:

Ctrl+` (обратная кавычка)
→ Терминал прямо в VS Code!
→ Можно запускать команды на сервере

Плюсы VS Code:

Минусы:
- ⚠️ Нужно установить программу
- ⚠️ Нужен стабильный интернет (работа через SSH)

Это ЛУЧШИЙ вариант для работы с документами!

✅ ВАРИАНТ 3: Через GitHub (веб-интерфейс)

Что нужно: Push репозиторий на GitHub (один раз)

Настройка (один раз):

1. Создать репозиторий на GitHub:

https://github.com/ → New Repository
Название: cifra-platform
Private: ✅ (приватный!)

2. Подключить на сервере:

cd /opt/claude-workspace

# Добавить remote
git remote add origin git@github.com:username/cifra-platform.git

# Push
git push -u origin master

Как работать через GitHub:

1. Открыть файл:

GitHub → репозиторий → projects/marketplace/PROJECT.md
→ Видите файл в браузере

2. Редактировать:

Нажать кнопку "Edit" (карандаш)
→ Редактируете прямо в браузере
→ Commit changes

3. Pull на сервер:

# На сервере
cd /opt/claude-workspace
git pull origin master

Плюсы GitHub:

Минусы:
- ⚠️ Нужно делать pull/push вручную
- ⚠️ Медленнее чем локальная работа
- ⚠️ Не подходит для частых мелких правок

Хорошо для:
- Редких крупных изменений
- Просмотра документов
- Backup

🟡 ВАРИАНТ 4: Веб-панель (можно сделать)

Что это: Специальный веб-интерфейс для управления документами

Как может выглядеть:

http://91.218.142.168:3000/

┌─────────────────────────────────────────┐
│ Платформа ЦИФРА — Панель управления     │
├─────────────────────────────────────────┤
│                                         │
│ 📁 Проекты:                             │
│   ├─ marketplace     [Открыть] [Изм.]   │
│   └─ analytics       [Открыть] [Изм.]   │
│                                         │
│ 📋 Последние изменения:                 │
│   - 2025-11-10: Обновлён PROJECT.md     │
│   - 2025-11-09: Создан DocumentAgent    │
│                                         │
│ 🤖 Агенты:                              │
│   ├─ DocumentAgent   [Запустить]        │
│   └─ CodeAgent       [Запустить]        │
│                                         │
│ 📊 Метрики:                             │
│   - Токенов использовано: 150K          │
│   - Экономия: 80%                       │
└─────────────────────────────────────────┘

Что можно сделать:

Простая панель (Streamlit):

# panel/app.py

import streamlit as st
import os
import yaml

st.title("Платформа ЦИФРА — Панель")

# Список проектов
st.header("Проекты")
projects = os.listdir("/opt/claude-workspace/projects")
for project in projects:
    col1, col2 = st.columns([3, 1])
    with col1:
        st.write(f"📁 {project}")
    with col2:
        if st.button("Открыть", key=project):
            # Открыть PROJECT.md
            pass

# Редактор
st.header("Редактор")
project = st.selectbox("Проект", projects)
file = st.selectbox("Файл", ["PROJECT.md", "ROADMAP.md"])

content = st.text_area("Содержимое", height=400)
if st.button("Сохранить"):
    # Сохранить в файл
    st.success("Сохранено!")

Запуск:

cd /opt/claude-workspace/panel
streamlit run app.py --server.port 3000

Доступ:

http://91.218.142.168:3000

Продвинутая панель (Django/FastAPI):

Функции:
- ✅ WYSIWYG редактор Markdown
- ✅ Предпросмотр в реальном времени
- ✅ Git интеграция (commit/push из панели)
- ✅ Запуск агентов
- ✅ Просмотр метрик
- ✅ Управление проектами

Технологии:
- Backend: FastAPI
- Frontend: React / Vue
- Markdown: Editor.js / TipTap
- Git: GitPython

Время разработки:
- Простая панель (Streamlit): 2-4 часа
- Продвинутая (FastAPI + React): 1-2 недели

Плюсы веб-панели:

Минусы:
- ⚠️ Нужно разрабатывать
- ⚠️ Дополнительный сервер (порт)
- ⚠️ Безопасность (нужна аутентификация)

Нужно ли сейчас:
- ❌ НЕТ для Фазы 0-1 (рано)
- 🟡 МОЖНО в Фазе 2-3 (если нужно)
- ✅ ДА в Фазе 4+ (для масштабирования)

📊 СРАВНЕНИЕ ВАРИАНТОВ

Критерий SSH (nano) VS Code GitHub Веб-панель
Установка ✅ Уже есть Нужно установить Нужно настроить Нужно разработать
Удобство ⚠️ Средне ✅ Отлично 🟡 Хорошо ✅ Отлично
Скорость ✅ Быстро ✅ Быстро ⚠️ Медленно 🟡 Средне
Markdown preview ❌ Нет ✅ Есть ✅ Есть ✅ Есть
Git интеграция Команды ✅ Визуально ✅ Автоматически ✅ Визуально
Работа оффлайн ❌ Нет ❌ Нет ❌ Нет ❌ Нет
Подходит для Мелкие правки Основная работа Просмотр, редкие правки Управление платформой

🎯 МОИ РЕКОМЕНДАЦИИ

ДЛЯ ФАЗЫ 0-1 (СЕЙЧАС):

Вариант A: VS Code (если удобно с компьютера)

1. Установить VS Code
2. Установить Remote-SSH расширение
3. Подключиться к серверу
4. Открыть /opt/claude-workspace
5. Работать как с обычными файлами!

✅ ЛУЧШИЙ вариант для комфортной работы

Вариант B: SSH + nano (если нет возможности установить VS Code)

1. ssh root@91.218.142.168
2. cd /opt/claude-workspace
3. nano projects/marketplace/PROJECT.md
4. Редактируем, Ctrl+O, Ctrl+X
5. git commit ...

✅ Работает прямо сейчас

ДЛЯ ФАЗЫ 2+ (ПОТОМ):

GitHub для backup:

git push origin master

→ Автоматический backup
→ Можно смотреть документы в браузере

Веб-панель (опционально):

Если будет нужно:
- Много людей работают
- Не все знают Git
- Нужен удобный интерфейс

Сделаем простую панель на Streamlit за 2-4 часа

🚀 БЫСТРЫЙ СТАРТ (ПРЯМО СЕЙЧАС)

Если хотите VS Code:

1. Скачайте:

https://code.visualstudio.com/download

2. Установите расширение:

Откройте VS Code
Extensions (Ctrl+Shift+X)
Найдите "Remote - SSH"
Install

3. Подключитесь:

F1 → "Remote-SSH: Connect to Host"
Введите: root@91.218.142.168
Пароль: [ваш SSH пароль]

4. Откройте workspace:

File → Open Folder
Выберите: /opt/claude-workspace

5. Готово!

Теперь можете редактировать файлы как обычно
Ctrl+P → PROJECT.md → Enter

Если хотите через SSH (проще):

1. Подключитесь:

ssh root@91.218.142.168

2. Откройте файл:

cd /opt/claude-workspace
nano projects/marketplace/PROJECT.md

3. Редактируйте:

Меняете текст
Ctrl+O (сохранить)
Ctrl+X (выйти)

4. Git commit:

git add projects/marketplace/PROJECT.md
git commit -m "docs: обновлён PROJECT.md"

Готово!

📝 ПРИМЕРЫ РАБОТЫ

Пример 1: Обновить ROADMAP.md

Через VS Code:

1. Ctrl+P → "ROADMAP" → Enter
2. Добавляем:
   ## v2.0 - Backend
   - FastAPI
   - PostgreSQL
3. Ctrl+S (сохранить)
4. Source Control → Commit

Через SSH:

nano projects/marketplace/design/ROADMAP.md
# Редактируем
# Ctrl+O, Ctrl+X

git add projects/marketplace/design/ROADMAP.md
git commit -m "docs: добавлена v2.0 в roadmap"

Пример 2: Создать новый ADR

Через VS Code:

1. File → New File
2. Сохранить как: platform/.claude/decisions/ADR-002.md
3. Вставить шаблон ADR
4. Заполнить
5. Ctrl+S → Commit

Через SSH:

cd /opt/claude-workspace/platform/.claude/decisions
nano ADR-002-metrics-storage.md
# Пишем содержимое
# Ctrl+O, Ctrl+X

git add .
git commit -m "docs: ADR-002 хранение метрик"

Пример 3: Посмотреть историю изменений

Через VS Code:

1. Открыть файл PROJECT.md
2. Правой кнопкой → "Open Timeline"
3. Видите все версии файла
4. Можете сравнить версии

Через SSH:

# История файла
git log --oneline -- projects/marketplace/PROJECT.md

# Посмотреть конкретный коммит
git show a1b2c3d

# Diff между версиями
git diff HEAD~1 HEAD -- projects/marketplace/PROJECT.md

❓ FAQ

Q: Можно ли работать с телефона/планшета?

A: Да, несколько вариантов:

1. GitHub (в браузере)
   - Можно редактировать файлы
   - Не очень удобно для больших текстов

2. SSH клиент (Termux на Android, iSH на iOS)
   - ssh root@...
   - nano file.md
   - Работает, но неудобно

3. VS Code for Web (github.dev)
   - Открыть репозиторий на github.com
   - Нажать "." (точка)
   - Откроется VS Code в браузере!

Рекомендую: GitHub для мелких правок с телефона

Q: Безопасно ли хранить документы в Git?

A: ДА, если:
✅ Приватный репозиторий (GitHub Private)
✅ Секреты (.env) в .gitignore
✅ Нет персональных данных пользователей

Git — стандарт в индустрии для документации

Q: Можно ли работать оффлайн?

A: Да, если клонировать репозиторий локально:

git clone ssh://root@91.218.142.168/opt/claude-workspace local-copy
cd local-copy
# Работаете локально
git commit ...
# Когда есть интернет:
git push

Q: Нужна ли веб-панель?

A: Зависит:

НЕ нужна если:
- Вы один/два человека работаете
- Удобно с VS Code

Нужна если:
- Много людей (не все знают Git)
- Нужен удобный интерфейс для нетехнических людей
- Хотите запускать агентов из браузера

Можем сделать позже (Фаза 2-3)

✅ ИТОГО

Что делать СЕЙЧАС:

Вариант 1 (рекомендую):

1. Установить VS Code
2. Подключиться к серверу через Remote-SSH
3. Работать комфортно!

Вариант 2 (если проще):

1. ssh root@91.218.142.168
2. nano файл.md
3. git commit

Не нужно сейчас:
- ❌ Веб-панель (рано)
- ❌ Сложные инструменты
- ❌ Дополнительные серверы

Потом (Фаза 2+):
- 🟡 GitHub для backup
- 🟡 Веб-панель (если понадобится)

Версия: 1.0.0
Дата: 2025-11-10
Статус: Готово

🎯 ВАШ ВЫБОР?

Q1: Какой вариант вам удобнее?
- A) VS Code (установлю программу)
- B) SSH + nano (работаю через терминал)
- C) Хочу веб-панель (сделаем простую)

Q2: Помочь настроить VS Code?
- Или сами справитесь?

Q3: Начинаем работать с документами?
- Или ещё вопросы есть?