mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
---
|
||
layout: default
|
||
title: "Техническая спецификация CLI для конфигурации"
|
||
parent: "Russian (Beta)"
|
||
---
|
||
|
||
# Техническая спецификация CLI для конфигурации
|
||
|
||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||
|
||
## Обзор
|
||
|
||
Эта спецификация описывает расширенные возможности конфигурации через командную строку для TrustGraph, позволяя пользователям управлять отдельными элементами конфигурации с помощью команд CLI с гранулярным уровнем доступа. Интеграция поддерживает четыре основных сценария использования:
|
||
|
||
1. **Перечисление элементов конфигурации**: Отображение ключей конфигурации определенного типа
|
||
2. **Получение элемента конфигурации**: Получение конкретных значений конфигурации
|
||
3. **Установка элемента конфигурации**: Установка или обновление отдельных элементов конфигурации
|
||
4. **Удаление элемента конфигурации**: Удаление конкретных элементов конфигурации
|
||
|
||
## Цели
|
||
|
||
- **Детализированный контроль**: Обеспечение управления отдельными элементами конфигурации, а не пакетными операциями
|
||
- **Список по типу**: Предоставление пользователям возможности исследовать элементы конфигурации по типу
|
||
- **Операции для отдельных элементов**: Предоставление команд для получения/установки/удаления отдельных элементов конфигурации
|
||
- **Интеграция с API**: Использование существующего API для конфигурации для всех операций
|
||
- **Единый шаблон CLI**: Соблюдение установленных норм и шаблонов CLI для TrustGraph
|
||
- **Обработка ошибок**: Предоставление понятных сообщений об ошибках для некорректных операций
|
||
- **Вывод в формате JSON**: Поддержка структурированного вывода для программного использования
|
||
- **Документация**: Включение подробной справки и примеров использования
|
||
|
||
## Предыстория
|
||
|
||
TrustGraph в настоящее время предоставляет управление конфигурацией через API для конфигурации и один командный интерфейс `tg-show-config`, который отображает всю конфигурацию. Хотя это работает для просмотра конфигурации, оно не обеспечивает возможности детального управления.
|
||
|
||
Текущие ограничения включают:
|
||
- Отсутствие возможности перечисления элементов конфигурации по типу через командную строку
|
||
- Отсутствие командной строки для получения конкретных значений конфигурации
|
||
- Отсутствие командной строки для установки отдельных элементов конфигурации
|
||
- Отсутствие командной строки для удаления отдельных элементов конфигурации
|
||
|
||
Эта спецификация решает эти проблемы, добавляя четыре новые команды CLI, которые обеспечивают детальное управление конфигурацией. Предоставляя отдельные операции API через команды CLI, TrustGraph может:
|
||
- Обеспечить управление конфигурацией через скрипты
|
||
- Предоставить пользователям возможность исследовать структуру конфигурации по типу
|
||
- Обеспечить целевые обновления конфигурации
|
||
- Обеспечить детальный контроль над конфигурацией
|
||
|
||
## Техническое проектирование
|
||
|
||
### Архитектура
|
||
|
||
Для расширенного CLI необходимо следующее техническое:
|
||
|
||
1. **tg-list-config-items**
|
||
- Перечисление ключей конфигурации для указанного типа
|
||
- Вызов API-метода Config.list(type)
|
||
- Вывод списка ключей конфигурации
|
||
|
||
Модуль: `trustgraph.cli.list_config_items`
|
||
|
||
2. **tg-get-config-item**
|
||
- Получение конкретного элемента конфигурации(й)
|
||
- Вызов API-метода Config.get(keys)
|
||
- Вывод значений конфигурации в формате JSON
|
||
|
||
Модуль: `trustgraph.cli.get_config_item`
|
||
|
||
3. **tg-put-config-item**
|
||
- Установка или обновление элемента конфигурации
|
||
- Вызов API-метода Config.put(values)
|
||
- Прием параметров type, key и value
|
||
|
||
Модуль: `trustgraph.cli.put_config_item`
|
||
|
||
4. **tg-delete-config-item**
|
||
- Удаление элемента конфигурации
|
||
- Вызов API-метода Config.delete(keys)
|
||
- Прием параметров type и key
|
||
|
||
Модуль: `trustgraph.cli.delete_config_item`
|
||
|
||
### Модели данных
|
||
|
||
#### ConfigKey и ConfigValue
|
||
|
||
Команды используют существующие структуры данных из `trustgraph.api.types`:
|
||
|
||
```python
|
||
@dataclasses.dataclass
|
||
class ConfigKey:
|
||
type : str
|
||
key : str
|
||
|
||
@dataclasses.dataclass
|
||
class ConfigValue:
|
||
type : str
|
||
key : str
|
||
value : str
|
||
```
|
||
|
||
Это обеспечивает:
|
||
- Последовательную обработку данных в CLI и API
|
||
- Типобезопасное управление конфигурацией
|
||
- Структурированные форматы ввода/вывода
|
||
- Интеграцию с существующим API для конфигурации
|
||
|
||
### Спецификации команд CLI
|
||
|
||
#### tg-list-config-items
|
||
```bash
|
||
tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
|
||
```
|
||
- **Назначение**: Отобразить все ключи конфигурации для данного типа
|
||
- **API-вызов**: `Config.list(type)`
|
||
- **Вывод**:
|
||
- `text` (по умолчанию): Ключи конфигурации, разделенные новыми строками
|
||
- `json`: Массив строк JSON с ключами конфигурации
|
||
|
||
#### tg-get-config-item
|
||
```bash
|
||
tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
|
||
```
|
||
- **Назначение**: Получить конкретный элемент конфигурации
|
||
- **API-вызов**: `Config.get([ConfigKey(type, key)])`
|
||
- **Вывод**:
|
||
- `text` (по умолчанию): Сырая текстовая строка
|
||
- `json`: JSON-кодированная строка значения
|
||
|
||
#### tg-put-config-item
|
||
```bash
|
||
tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
|
||
tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
|
||
```
|
||
- **Назначение**: Установить или обновить элемент конфигурации
|
||
- **API-вызов**: `Config.put([ConfigValue(type, key, value)])`
|
||
- **Варианты ввода**:
|
||
- `--value <строка>`: Строковое значение, указанное непосредственно в командной строке
|
||
- `--stdin`: Чтение всего ввода как значения конфигурации
|
||
- **Вывод**: Подтверждение успеха
|
||
|
||
#### tg-delete-config-item
|
||
```bash
|
||
tg-delete-config-item --type <type> --key <key> [--api-url <url>]
|
||
```
|
||
- **Назначение**: Удалить элемент конфигурации
|
||
- **API-вызов**: `Config.delete([ConfigKey(type, key)])`
|
||
- **Вывод**: Подтверждение успеха
|
||
|
||
### Детали реализации
|
||
|
||
Все команды следуют установленной схеме CLI для TrustGraph:
|
||
- Использование `argparse` для разбора командной строки
|
||
- Импорт и использование `trustgraph.api.Api` для взаимодействия с backend
|
||
- Соблюдение тех же схем обработки ошибок, что и у существующих CLI
|
||
- Поддержка стандартного параметра `--api-url` для настройки URL API
|
||
- Предоставление описательного справки и примеров использования
|
||
|
||
#### Обработка форматов вывода
|
||
|
||
**Текст:**
|
||
```bash
|
||
tg-list-config-items --type prompt
|
||
template-1
|
||
template-2
|
||
system-prompt
|
||
```
|
||
|
||
**JSON:**
|
||
```bash
|
||
tg-list-config-items --type prompt --format json
|
||
["template-1", "template-2", "system-prompt"]
|
||
```
|
||
|
||
**Текст:**
|
||
```bash
|
||
tg-get-config-item --type prompt --key template-1
|
||
You are a helpful assistant. Please respond to: {query}
|
||
```
|
||
|
||
**JSON:**
|
||
```bash
|
||
tg-get-config-item --type prompt --key template-1 --format json
|
||
"You are a helpful assistant. Please respond to: {query}"
|
||
```
|
||
|
||
**Текст:**
|
||
```bash
|
||
tg-put-config-item --type prompt --key new-template --value "Custom prompt: {input}"
|
||
```
|
||
|
||
**JSON:**
|
||
```bash
|
||
tg-put-config-item --type prompt --key complex-template --stdin < ./prompt-template.txt
|
||
```
|
||
|
||
**Текст:**
|
||
```bash
|
||
tg-delete-config-item --type prompt --key old-template
|
||
```
|
||
|
||
## Открытые вопросы
|
||
|
||
- Следует ли командам поддерживать пакетные операции (несколько ключей) помимо отдельных элементов?
|
||
- Какой формат вывода следует использовать для подтверждений успеха?
|
||
- Как следует документировать и узнавать пользователями типы конфигурации?
|
||
|
||
## Ссылки
|
||
|
||
- Существующий API для конфигурации: `trustgraph/api/config.py`
|
||
- Шаблоны CLI: `trustgraph-cli/trustgraph/cli/show_config.py`
|
||
- Типы данных: `trustgraph/api/types.py`
|