docs: IDEA.MD — суть проекта и состав плагина
This commit is contained in:
hermes committed
1 parent
efde679f7a
commit
39ba95ff18
1 file changed
+134
@@ -0,0 +1,134 @@
|
|||||||
|
# dsh-vk-group — Плагин управления группой ВКонтакте для DeepSeek Harness
|
||||||
|
|
||||||
|
## Что это
|
||||||
|
|
||||||
|
DSH-плагин (bundle), который даёт агенту внутри DeepSeek Harness полный набор инструментов для управления сообществом ВКонтакте: постинг, модерация, участники, сообщения, обсуждения, статистика, медиа.
|
||||||
|
|
||||||
|
## Почему
|
||||||
|
|
||||||
|
DeepSeek Harness — открытый харнес от DeepSeek (репозиторий `deepseek-ai/deepseek-harness`, ~256k звёзд) с архитектурой «всё есть плагин». Плагины — это TypeScript-модули, экспортирующие `apply(ctx)`, регистрирующие инструменты через `ctx.tools.register(defineTool(...))`. ВКонтакте имеет развитое REST API (`dev.vk.com/method`) для управления сообществами. Соединить оба — значит дать одному агенту автономно вести сообщество целиком.
|
||||||
|
|
||||||
|
## Технологии
|
||||||
|
|
||||||
|
- TypeScript / ESM
|
||||||
|
- `@deepseek-ai/cordis` — фреймворк плагинов
|
||||||
|
- `@deepseek-ai/dsh-tools` — `defineTool`, типизированная схема инструментов
|
||||||
|
- `@deepseek-ai/schemastery` — конфигурация
|
||||||
|
- VK API v5.199+ — REST, LongPoll API, Callback API
|
||||||
|
- Node fetch — HTTP-клиент VK API
|
||||||
|
|
||||||
|
## Архитектура плагина
|
||||||
|
|
||||||
|
```
|
||||||
|
dsh-vk-group/
|
||||||
|
├── package.json # dsh.bundle, engines.dsh
|
||||||
|
├── cordis.patch.yml # слой плагина
|
||||||
|
├── src/
|
||||||
|
│ ├── index.ts # apply(ctx) — точка входа
|
||||||
|
│ ├── config.ts # Config (Schemastery schema)
|
||||||
|
│ ├── vk/
|
||||||
|
│ │ ├── client.ts # VK API клиент: retry, rate-limit, captcha-hook
|
||||||
|
│ │ ├── methods.ts # типизированные обёртки методов
|
||||||
|
│ │ ├── errors.ts # коды ошибок VK → типизированные ошибки
|
||||||
|
│ │ └── longpoll.ts # LongPoll-цикл (ctx.jobs + ctx.effect)
|
||||||
|
│ ├── tools/ # ~22 инструмента vk_*
|
||||||
|
│ │ ├── community.ts # info / update settings
|
||||||
|
│ │ ├── members.ts # list / manage / status
|
||||||
|
│ │ ├── moderation.ts # ban / requests / managers
|
||||||
|
│ │ ├── wall.ts # post / edit / delete / pin / list
|
||||||
|
│ │ ├── comments.ts # list / manage
|
||||||
|
│ │ ├── media.ts # photos / docs / video / stories upload
|
||||||
|
│ │ ├── board.ts # topics + comments
|
||||||
|
│ │ ├── market.ts # products
|
||||||
|
│ │ ├── messages.ts # community messages
|
||||||
|
│ │ ├── analytics.ts # stats / shortlink
|
||||||
|
│ │ ├── callback.ts # Callback API servers
|
||||||
|
│ │ ├── longpoll-control.ts
|
||||||
|
│ │ └── moderation-rules.ts
|
||||||
|
│ ├── events/
|
||||||
|
│ │ └── inbound.ts # LongPoll → agent.followup()
|
||||||
|
│ ├── policy/
|
||||||
|
│ │ └── moderation.ts # rule engine + tools/pre-execute gate
|
||||||
|
│ ├── skill/
|
||||||
|
│ │ └── vk-group-ops/SKILL.md
|
||||||
|
│ └── ui/
|
||||||
|
│ └── settings.tsx # карточки инструментов + панель настроек
|
||||||
|
└── tests/
|
||||||
|
├── client.test.ts
|
||||||
|
├── tools.test.ts
|
||||||
|
└── integration.test.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Инструменты (22)
|
||||||
|
|
||||||
|
| Инструмент | Назначение |
|
||||||
|
|---|---|
|
||||||
|
| `vk_community_info` | Информация о сообществе + счётчики + права токена |
|
||||||
|
| `vk_community_update` | Изменение настроек (dry-run diff, whitelist полей) |
|
||||||
|
| `vk_members_list` | Список участников (пагинация, фильтр, сортировка) |
|
||||||
|
| `vk_members_manage` | Исключить / одобрить / отклонить / пригласить |
|
||||||
|
| `vk_member_status` | isMember + ban_info + member_status |
|
||||||
|
| `vk_ban_list` | Список заблокированных |
|
||||||
|
| `vk_ban_manage` | Бан / разбан (причина, срок) |
|
||||||
|
| `vk_requests_list` | Заявки на вступление |
|
||||||
|
| `vk_requests_handle` | Одобрить / отклонить заявки (пакетно) |
|
||||||
|
| `vk_managers_list` | Список руководителей |
|
||||||
|
| `vk_manager_set` | Назначить / разжаловать / изменить полномочия |
|
||||||
|
| `vk_wall_post` | Создать запись (текст, вложения, from_group, signed) |
|
||||||
|
| `vk_wall_edit` | Редактировать запись |
|
||||||
|
| `vk_wall_delete` | Удалить / восстановить запись |
|
||||||
|
| `vk_wall_pin` | Закрепить / открепить запись |
|
||||||
|
| `vk_wall_list` | Лента записей (фильтры: owner, others, suggested, postponed) |
|
||||||
|
| `vk_comments_list` | Комментарии к записи |
|
||||||
|
| `vk_comment_manage` | Удалить / восстановить / пожаловаться |
|
||||||
|
| `vk_media_upload` | Загрузка фото / docs / video (возвращает attachment-строку) |
|
||||||
|
| `vk_board_topic` | Создать / закрыть / закрепить / удалить обсуждение |
|
||||||
|
| `vk_board_comment` | Комментарий в обсуждении (создать / удалить) |
|
||||||
|
| `vk_market_manage` | Добавить / редактировать / удалить товар |
|
||||||
|
| `vk_messages_send` | Сообщение от имени сообщества |
|
||||||
|
| `vk_messages_list` | Список диалогов сообщества |
|
||||||
|
| `vk_stats_get` | Статистика сообщества (период, интервал) |
|
||||||
|
| `vk_shortlink` | Короткая ссылка (utils.getShortLink) |
|
||||||
|
| `vk_callback_manage` | Серверы Callback API (add / edit / delete / settings) |
|
||||||
|
| `vk_longpoll_control` | Старт / стоп / статус LongPoll-цикла |
|
||||||
|
| `vk_moderation_rules` | Чтение / запись правил модерации |
|
||||||
|
|
||||||
|
## События (LongPoll → агент)
|
||||||
|
|
||||||
|
LongPoll-цикл работает как фоновая задача (`ctx.jobs`). События VK доставляются агенту через `agent.followup()`:
|
||||||
|
|
||||||
|
- `MESSAGE_NEW` — новое сообщение в сообщество
|
||||||
|
- `WALL_REPLY_NEW` — новый комментарий на стене
|
||||||
|
- `WALL_POST_NEW` — новая запись (от участника, если стена открытая)
|
||||||
|
- `GROUP_JOIN` / `GROUP_LEAVE`
|
||||||
|
- `MESSAGE_TYPING_STATE`
|
||||||
|
- `BOARD_REPLY_NEW` — ответ в обсуждении
|
||||||
|
- `MARKET_COMMENT_NEW`
|
||||||
|
|
||||||
|
## Конфигурация (Schemastery)
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface Config {
|
||||||
|
accessToken: string // community or user token
|
||||||
|
groupId: number // negative or positive
|
||||||
|
apiVersion: string // default '5.199'
|
||||||
|
language: string // 'ru' | 'en' | 'uk'
|
||||||
|
rateLimit: { rps: number; burst: number }
|
||||||
|
retry: { maxAttempts: number; baseDelayMs: number }
|
||||||
|
captcha: { autoSolve: boolean; solverTool?: string }
|
||||||
|
longpoll: { enabled: boolean; mode: number; timeoutSec: number }
|
||||||
|
callback: { enabled: boolean; serverUrl?: string; confirmToken?: string }
|
||||||
|
moderation: { autoBanKeywords: string[]; autoApprove: boolean; warnThreshold: number }
|
||||||
|
defaultFromGroup: boolean
|
||||||
|
defaultSigned: boolean
|
||||||
|
ui: { settingsTab: boolean }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Вики (14 страниц)
|
||||||
|
|
||||||
|
См. вики репозитория Gitea.
|
||||||
|
|
||||||
|
## Статус
|
||||||
|
|
||||||
|
План и архитектура готовы. Код не написан — ожидаю решения.
|
||||||
Reference in new issue
Block a user