KnowledgeHub Mobile Capture

«云飞随手记» — это мобильный сервис записи и пакет плагина для OpenAI. Он записывает текст, расшифровки голоса и вложения из ChatGPT на телефоне в личный приватный репозиторий User KnowledgeHub на GitHub в режиме только добавления, без перезаписи.

Текущий статус: код и локальная тестовая база уже готовы; только после завершения публичного развёртывания, настройки OAuth и приёмки на реальном мобильном устройстве личный KnowledgeHub сможет пометить «мобильную быструю заметку» как включённую.

Границы системы

flowchart LR
    A["手机 ChatGPT\n云飞随手记"] -->|"OAuth + MCP"| B["Mobile Capture 服务"]
    B -->|"仅创建新文件"| C["GitHub 私有 KnowledgeHub"]
    C -->|"git pull"| D["本地 KnowledgeHub"]
    D --> E["Obsidian"]
    D --> F["Codex"]

Сервис регистрирует только один инструмент записи: create_quick_capture. Путь генерируется на стороне сервера, клиент не может его задать:

00-Inbox/Human/Quick-Captures/YYYY/MM/<时间戳>-<随机标识>.md
10-Sources/Attachments/Quick-Captures/YYYY/MM/<capture-key>/<文件名>

Содержимое записи не выполняется как команда, не сортируется, не архивируется и не превращается в задачи автоматически. При успехе должны возвращаться stored: true, путь в базе знаний и SHA Git-коммита.

Related MCP server: brain-mcp

Состав репозитория

• src/: MCP HTTP-сервис, проверка OAuth/API Key, запись только в режиме create-only на GitHub.

• plugins/knowledgehub-mobile-capture/: устанавливаемый манифест плагина и Skill для мобильного захвата.

• test/: тесты границ путей, лимитов вложений, create-only и семантики ошибок.

• docs/DEPLOYMENT.md: шаги развёртывания и подключения для реального мобильного режима.

• docs/ACCEPTANCE.md: приёмка, которую необходимо завершить до включения.

Локальная разработка и проверка

Режим локального API Key предназначен только для разработки и отладки в Codex, не может применяться как официальный способ аутентификации в мобильном ChatGPT.

Copy-Item .env.example .env
# 编辑 .env 后，把变量导入当前终端
npm install
npm test
npm start

Проверка здоровья: GET http://localhost:8787/health. Точка входа MCP: POST http://localhost:8787/mcp, заголовок запроса: Authorization: Bearer <CAPTURE_API_KEY>.

Официальный мобильный режим

В официальном режиме необходимо установить AUTH_MODE=oauth-jwt, использовать тождественный провайдера, поддерживающего MCP OAuth 2.1, и развернуть на публичном HTTPS. Для ChatGPT не поддерживается замена этой процедуры аутентификации собственным API-ключом пользователя. Полная инструкция — в инструкции по развёртыванию.

Официальные материалы OpenAI:

• Аутентификация MCP-плагинов

• Подключение и тестирование плагина

• Архитектура плагинов

Принципы безопасности

• GitHub Token хранится только в Secret платформы развёртывания и не попадает в репозиторий, плагин или чат.

• Токен авторизует только чтение и запись содержимого целевого приватного репозитория KnowledgeHub.

• Сервис не предоставляет инструментов для изменения, перемещения, перезаписи или удаления.

• В режиме OAuth обязательно проверяются издатель, аудитория, целые области доступа и безусловный список пользователя sub.

• Вложения по умолчанию: не более 5 файлов, по 10 MiB каждое, суммарно 20 MiB; текст по умолчанию не более 1 MiB.

• Если вложение уже создано, а окончательная заметка не удалась, автоудаление не выполняется; волучение вернёт пути, которые требуют ручной проверки.

Отношение с KnowledgeHub

• KnowledgeHub-Framework определяет контракт.

• KnowledgeHub-Setup отвечает за опциональную установку и онбординг.

• Этот репозиторий реализует мобильную удалённую точку входа, не сохраняет пользовательские данные или учётные данные.

• Личный репозиторий KnowledgeHub пользователя — единственный источник истины.

Лицензия

MIT