CLI и структурированный выход
Используйте open-science для проверки статуса приложения, выполнения задач, управления Коннекторами и учетными данными и управления локальной службой. Начните с установленной пусковой установки и подтвердите, к какому локальному экземпляру она подключается.
Обновитель приложений удален: v1.0.0 больше не принимает open-science update, включая его форму --json. Используйте элементы управления обновлениями рабочего стола или оригинальный установщик / менеджер пакетов. Бывший код выхода 5 и 6 не являются частью текущей таблицы CLI. Смотрите Обновление руководства.
Настройка из терминала
Установите десктопную пусковую установку, используйте автономный архив v1.0.5 или следуйте npm инсталляция. Отдельный пакет архивов Node, бэкэнд и веб-интерфейс; этапы извлечения ниже применяются к этим архивам.
- Выберите macOS или Linux arm64/x64, или Windows x64, соответствующий хосту.
- Извлеките полный архив в письменное место. Держите пусковую установку,
backendиnode-runtimeвместе. Копирование только пусковой установки сломает стартап. - Из этого каталога запустите
./open-science --helpна macOS/Linux или./open-science.cmd --helpв PowerShell. После добавления этого каталога в PATH откройте новый терминал и используйтеopen-science, как указано ниже. - Начните местный бэкэнд и проверьте готовность. Запуск его сам по себе не настраивает модель.
open-science init
open-science start --no-open
open-science runtime list --json
open-science doctor --json
init создает каталог конфигурации без запуска приложения. --profile является псевдонимом --config-root для портативного профиля CLI. Используйте один и тот же каталог абсолютной конфигурации для ввода, запуска и последующих команд; Отдельный профиль имеет собственную настройку. runtime list показывает обнаруженную готовность фреймворка, версию и управляемый/внешний источник без раскрытия исполняемых путей.
Для неконфигурированной настройки Codex:
open-science runtime install codex --json
open-science codex login
open-science doctor --json
Следуйте за потоком входа. Это подготавливает или восстанавливает управляемое время выполнения Codex и регистрирует подписку через приложение. Он не импортирует внешние файлы входа Codex. Первый загрузочный страп в настоящее время нацелен на Codex, хотя список выполнения включает в себя другие фреймворки. О существующей конфликтной конфигурации сообщается, а не молча заменяется.
Если вместо этого используется ключ OpenAI API, используйте provider add --type official --vendor openai --model MODEL_ID --api-key-env OPENAI_API_KEY --json с поддерживаемым идентификатором модели и ключом, уже поставляемым через среду управления секретом. Для OpenAlex используйте connector configure literature --openalex-key-env OPENALEX_API_KEY --json. Префиксируйте обе команды с помощью open-science. Никогда не ставьте сам ключ в командные аргументы. Успешная проверка учетных данных не устанавливает, что исследовательский запрос завершен или что квота остается.
Прочитайте готовый, индивидуальный проверка и предложите действия следующий от doctor. Отчет может успешно выйти, в то время как ready является ложным. Если бэкэнд отсутствует, Доктор сообщает об этом и выходит из 3. Завершите заявленную предпосылку, проверьте еще раз, затем выполнить задание в предполагаемом проекте.
Для установки Homebrew или Linux .deb / .rpm следуйте за Упаковка инструкций. Распределительные пакеты Linux предоставляют open-science-cli; Замените эту команду в примерах на этой странице, чтобы избежать выбора другой настольной пусковой установки.
Точки входа
| Вступление | Требование | Команда |
|---|---|---|
| Установка прикладной пусковой установки | Settings → General → Command line tool → Install command | open-science --help |
| Проверка источника | Встроенные зависимости приложений и репозиторий | node packages/open-science/cli.mjs --help |
| Автономный архив CLI | Соответствие ОС/архитектуры; Сохранить полный извлеченный каталог | ./open-science --help или ./open-science.cmd --help |
| npm клиент / SDK | Node.js 22.13+ и работающий совместимый бэкэнд; Проверить требования к пакету перед установкой | Идентификатор пакета @aipoch/open-science |
Установленная пусковая установка использует упакованное время выполнения приложения. Если его каталог отсутствует в PATH, следуйте инструкциям общей панели и откройте новый терминал. Не переименовывайте исполняемый файл в соответствии с брендингом дисплея.
После Install command откройте новое окно PowerShell и запустите:
Get-Command open-science | Select-Object Name, Source
open-science --help
open-science status --json
Убедитесь, что Source указывает на пусковую установку, обычно open-science.cmd под вашим профилем пользователя. Успешный вывод помощи подтверждает запуск пусковой установки. Если статус возвращает {"running":false}, CLI не сообщает о запущенном бэкэнде; Это не означает, что окно рабочего стола закрыто. Проверьте предполагаемый экземпляр с помощью Режим работы сервера перед отправкой задач или загрузкой файлов.
Выполните небольшую командную задачу
Пример Сохранить записку из командной строки
- Установите команду, используя вход выше. Поддерживайте бэкэнд с рабочей моделью, либо через рабочий стол, либо через
start --no-open. - Запустите
open-science status --json, затемopen-science project list --json. Проверьте предполагаемый экземпляр и скопируйте возвращенный идентификатор проекта. - Сохранить
task.mdс помощью Сохранить project-note.md, содержащий краткую заметку о проверке соединения. Не читайте другие файлы и не используйте сеть. - Запускайте команды под Запуск входных и контрольных флагов. Заменить каждый заполнитель только после получения его идентификатора из предыдущего результата.
- Если запуск приостанавливается для разрешения, ответьте в соответствующем настольном компьютере или аутентифицированном разговоре браузера.
--waitможет отсчитывать время, пока работа продолжается. Проверьтеrun status RUN_ID --json, прежде чем снова подать заявку. - Выберите возвращенный идентификатор артефакта Markdown, загрузите его в новое локальное имя файла и откройте его. Завершенный прогон без запрашиваемого артефакта требует последующих действий в ходе этой сессии. Если артефакт существует, но загрузка не удается, следуйте Артефакт скачать восстановление.
Для выполнения задач первого плана используйте --return-on-attention, проверьте возвращенный план и ответьте через приложение или команды плана ниже. Для интеграции JSON следует отличать запущенный, завершенный, неудавшийся и отмененный, а не рассматривать каждый успешный ответ HTTP как завершенную задачу.
Командные семьи
| Команда | Аргументы/флаги | Эффект |
|---|---|---|
project list | --json | Читайте доступные проекты |
project create | Имя, факультативно --description, один из --agent-context / --agent-context-file | Создать проект |
project update | ID или точное имя, предоставленные метаданные/контекстовые поля | Модифицировать только поставляемые поля; --clear-agent-context Явно проясняет контекст |
project session-defaults show | Идентификатор проекта или точное имя | Читайте дефолты для новых сессий |
project session-defaults update | Проект плюс сеансовые опции | Обновление по умолчанию с защитой от одновременных редактирования |
run | --projectБыстрый ввод, факультативный --session, --wait | Начать или продолжить работу |
run status / run cancel | Проверить. | Проверить или явно отменить пробежку |
session status | Сеансовый идентификатор | Читать сессию Состояние |
session config show | Сеансовый идентификатор | Чтение: сохраняющаяся/эффективная конфигурация и пересмотр |
session config update | Идентификатор сеанса, --revisionПредоставляемые варианты | Изменение поворотов в будущем, когда сессия может принять обновление |
settings agent-routing show/update | Параметры маршрутизации Framework and Reviewer/Subagent | Читать или атомарно обновлять глобальную маршрутизацию |
plan show/approve/reject/revise | идентификатор сеанса; Решение требует точной версии артефакта и его пересмотра. | Читайте или отвечайте на активный план |
artifacts list | Сеансовый идентификатор | Читать сохраненные артефакты |
artifacts download | Идентификатор артефакта, --output | Сохранить внешнюю копию |
Используйте идентификаторы проектов в сценариях. CLI может определить уникальное точное название проекта. Дублирующие имена неоднозначны. Маршрутизация SDK/HTTP требует наличия идентификаторов. Контекст проекта принимает до символов 16,000, а список/создание/обновление результатов обнажает hasAgentContext, а не частный контекстный корпус.
Если artifacts download не работает с HTTP 500, обновите старое приложение и повторите тот же идентификатор возвращенного артефакта. Скачать Recovery Steps отличает завершенную задачу от неудавшейся передачи файлов. Не повторяйте исследовательскую задачу только для того, чтобы получить существующий результат.
Управлять коннекторами и учетными данными
Эти команды используют бегущий бэкэнд и сохраненные настройки. Подтвердите предполагаемый экземпляр перед редактированием. Пользовательские записи Connector и учетные данные требуют локального аутентифицированного соединения; Для сервера запустите CLI на этом сервере, в том числе через SSH.
| Команда | Вход/результат |
|---|---|
| Список разъемов открытой науки — Джонсон | Безопасные настройки просмотров доступных коннекторов |
| Открытый научный разъем CONNECTOR_ID -json | Конфигурация/статус для возвращаемого идентификатора |
| Открытый научный разъем CONNECTOR_ID | Установите включенное предпочтение |
| Открытый научный разъем отключает CONNECTOR_ID | Очистите свои включенные предпочтения |
| open-science connector add (недоступная ссылка) | Прочитайте новое пользовательское определение MCP от JSON stdin |
| Обновление разъема открытой науки CONNECTOR_ID -json | Обновление конфигурации от JSON stdin |
| Открытый научный разъем удалить CONNECTOR_ID | Удалите пользовательское определение MCP |
| Открыто-научный разъемный тест CONNECTOR_ID -json | Откройте инструменты через отдельное соединение, а затем закройте его. |
| Открыто-научный список — Джонсон | Читайте метаданные учетных данных без сырых секретов |
| Открытая наука Добавить -json | Прочитайте новый сертификат от JSON Stdin |
| Обновление CREDENTIAL_ID -json | Обновление имени дисплея и/или секрета от JSON stdin |
Пример Отправьте локальную конфигурацию Connector
Отправьте подготовленный локальный файл конфигурации с:
open-science connector add --json < connector.json
| Поле конфигурации | Требование |
|---|---|
| Имя / DisplayName | Требуется для нового пользовательского Connector; Имя/ID остается стабильным во время обновления |
| транспорт | stdio, streamable_http или Sse; Также требуется для обновления |
| команда / args | Локальные исполняемые и необязательные аргументы для stdio |
| урл | Конечная точка для HTTP/SSE |
| envCredentialIds / headerCredentialIds | Обязательные имена окружения / заголовков для сохраненных учетных данных |
| oauthCredentialId | Объединить существующий общий учетный документ OAuth |
| Опущенные обязательные документы | Сохранение сохраненных значений при обновлении; Пустая среда / объект связывания заголовка очищает карту |
Можно добавлять, редактировать или удалять только пользовательские определения MCP. Enabled — это предпочтение выбора, а не доказательство подключения или глобального аннулирования доступа к Specialist.
испытание не позволяет использовать Connector или выполнять его бизнес-инструменты. Он возвращает успех, дополнительный инструментCount и сообщение. Открытие ограничено десятью секундами, а отказ выходит ненулевым. Связанная живая диагностика Connector не поддерживается. Тестирование может обновить существующие токены OAuth, но не выполняет вход в браузер впервые.
Credential записывает секреты через JSON stdin. Держите их вне командных аргументов и истории снарядов. Ввод токена использует имя отображения, вид: токен и секрет; Также поддерживается api_key. Свяжите возвращенный createdCredential.id с Connector. Старые бэкэнды без этих конечных точек возвращают ошибку, а не возвращаются к прямым настройкам-файлам.
Запуск входных и контрольных флагов
open-science project list --json
open-science run --project PROJECT_ID --prompt-file ./task.md --wait --json
open-science artifacts list SESSION_ID --json
open-science artifacts download ARTIFACT_ID --output ./result.csv --json
Замените капитализированных держателей с возвращенными идентификаторами. В примере не указаны изобретённый Skill или провайдер, который должен существовать на вашей установке.
| Флаг | контракт |
|---|---|
--prompt / --prompt-file | Встроенный текст или файл UTF-8; Stdin может обеспечить подсказку при опущении |
--session | Продолжить указанную сессию |
--cwd | Внешний рабочий каталог; CLI решает относительный путь, сервер канонизирует и проверяет его. |
--approval-profile | ask, auto, full; по умолчанию ask |
--provider + --model / --provider-default-model | Выберите настроенного поставщика и явную или принадлежащую поставщику модель по умолчанию. |
--reasoning-effort | Списки помощи CLI default, low, medium, high, xhigh, max; Выбор модели UI может отличаться |
--skill | Повторяемый установленный идентификатор Skill; Не устанавливайте недостающий Skill |
--plan-first | Требуется ответ на план перед выполнением |
--auto-review / --no-auto-review | Установить сеанс автоматического обзора |
--memory / --no-memory | Установить память сеанса; взаимоисключающий |
--specialist | Привязать новый сеанс с помощью UUID или стабильного имени профиля; Имя презентации не является идентификатором маршрутизации |
--delegation allow/deny | контроль приема новых делегированных работ; Отказ не отменяет существующих детей |
--compute-host | Повторяемые конфигурируемые идентификаторы хоста; выбирает цели выполнения, не настраивает SSH |
--enable-compute-host / --clear-compute-hosts | Управление доступом/дефолтом на новой сессии; Изменения в существующем сессионном доступе используют обновление конфигурации |
Внешний cwd остается в собственности абонента. Повторное использование --session с --cwd требует того же канонического каталога. Запрос на выполнение не перемещает сеанс. Отказ от хост-варианта сохраняет существующий выбор; Используйте явную операцию очистки, когда это предназначено.
Ожидание, внимание и отмена
| Вариант/штат | Результат |
|---|---|
Без --wait | Возвращение после приема; сохранять id и sessionId Опросить позже |
--wait | Дождитесь состояния терминального запуска |
--wait --return-on-attention | Возвращается, когда требуется утверждение структурированного плана; Поводы разрешения - это не одно и то же состояние внимания. |
--timeout-ms | Прекратить ожидание клиента после истечения срока; Серверный запуск продолжается |
--cancel-on-timeout | Явно отменить после тайм-аута; Командир все еще сообщает о тайм-ауте |
run cancel RUN_ID | ожидание отмены/финализации; сохранение уже завершенных артефактов |
Для утверждения плана сначала прочитайте plan show, затем поставьте как --artifact-version, так и --revision. Решение о несвоевременном плане не должно применяться к новому плану. Обновления конфигурации сеанса также требуют пересмотра, возвращенного session config show. Обновления возвращают session_revision_conflict. Активный корневой агент, субагент или Notebook может блокировать обновление с помощью session_busy.
Структурированные коды выхода и выхода
--json выдает один результат. --jsonl доступен с run --wait, транслирует события и заканчивается результатом выполнения. Не объединяйте эти два. Ошибки структурированы на stderr по запросу; Проанализируйте error.code, а не только исходный код процесса.
На местном уровне были воспроизведены следующие ответы по недействительным вариантам:
{"error":{"code":"invalid_cli_usage","message":"Use only one of --json or --jsonl."},"exitCode":2}
| Код завершения | Значение |
|---|---|
| 0 | Командование увенчалось успехом; проверить состояние возвратного пробега/внимания, где это применимо; |
| 1 | Общий / запущенный сбой, тайм-аут, конфликт или отчет о состоянии без запущенной службы |
| 2 | Недействительное использование CLI |
| 3 | Местный демон недоступен |
| 4 | Запрошенный проект/запуск/сессия/артефакт/Specialist не найден |
JSONL может включать run.progress и stream.resync-required. Если повторное воспроизведение недоступно после повторного подключения, перечитайте авторитетное состояние запуска; Не думайте, что поток событий — это постоянная история. Команды жизненного цикла имеют отдельные ограничения флага, описанные в Безголовый сервис.
Реализация CLI, командный гид.
Технический справочник: Контракт CLI.
Без присмотра бегут
Добавьте --permission-prompts none в run, чтобы отказаться от неразрешенных человеческих взаимодействий, а не ждать бесконечно. Отобранный профиль одобрения и запомнившиеся гранты по-прежнему применяются; Оставшиеся запросы на разрешение отклоняются, пользовательские вопросы отклоняются, а Планы, требующие проверки человеком, отклоняются. Это не одобряет каждое действие.
open-science run --project "Sequence and PDF Research" \
--prompt "Summarize the existing public-data result. Do not request user input." \
--approval-profile ask --permission-prompts none --wait --jsonl
Опция применяется только к этому вызову и не сохраняется в качестве предпочтения сеанса. Его нельзя комбинировать с --plan-first. Осмотрите окончательный статус и ошибку: избегание человеческого ожидания не гарантирует выполнение задачи. Клиент проверяет хост-функцию permission-prompts-none; Обновите соответствующий клиент и приложение, если старый хост возвращает unsupported_capability.
Пути запуска Windows
v0.37.1 исправляет пути запуска настольных компьютеров, содержащие символы, не являющиеся ASCII. После обновления откройте новый терминал и проверьте Get-Command open-science и open-science --help. Если команда по-прежнему решается на более старую установку, используйте путь, показанный в Settings → General. Держите весь отдельный архивный каталог нетронутым. Успешная команда помощи не устанавливает модель готовности. Проверьте doctor --json.
Проверьте установленный CLI без запуска сервиса
open-science version --json
open-science help run
open-science paths --json
open-science paths --profile /ABSOLUTE/PATH/TO/PROFILE --json
Эти команды работают без бегущего бэкэнда. version сообщает об инсталляции, а не о версии подключенного сервиса. paths отчеты cliPath, nodePath, startupConfigRoot и discoveryConfigRootsОн не идентифицирует активную службу или каталог исследовательских данных. Явный профиль выбирает место запуска / обнаружения, не создавая его. Пути могут раскрывать локальные имена пользователей, поэтому просмотрите выход, прежде чем делиться им.
Подключение внешнего клиента MCP
Отдельный CLI в v1.0.4 раскрывает инструменты исследования stdio. Сначала запустите сервис предполагаемого профиля; адаптер не запускает его автоматически. Замените оба абсолютных пути в этой конфигурации клиента:
open-science start --no-open --config-root /absolute/path/to/profile
open-science mcp --help
{
"mcpServers": {
"open-science": {
"command": "/absolute/path/to/open-science",
"args": ["mcp", "--config-root", "/absolute/path/to/profile"]
}
}
}
Пусть клиент запустит адаптер. Найдите проекты через list_projects, передайте полученный идентификатор проекта в start_run, отслеживайте get_run и просматривайте list_artifacts. Одно только обнаружение инструмента не доказывает, что услуга доступна. Звонки требуют запуска аутентифицированной локальной службы; это не удаленная конечная точка HTTP MCP.
Клиент действует в соответствии с существующими разрешениями профиля. Он может создавать постоянные проекты, изменять конфигурацию и начинать работу, которая записывает файлы или несет расходы на модели. Одобрения могут по-прежнему требовать действий в Open-Science. Проверьте текущее состояние после тайм-аута перед повторением записи. Закрытие клиента или отмена его запроса не отменяет принятые исследования: явно вызовите cancel_run. См. Официальный инструмент MCP и ссылка на разрешение.
Для команд пакетов следуйте Импорт и экспорт CLI.
Поддерживайте работу службы для автоматизации
Использовать open-science start --no-open --json для нужного профиля перед выходом из настольного приложения, если работа CLI, браузера или SDK должна продолжаться. С v1.0.5 это включает один постоянный режим; повторные запуски не суммируются. Обычная команда stop отключает постоянный режим, но при подключённом App сервис продолжает работать. Прочитайте Результаты жизненного цикла Прежде чем рассматривать успешную команду остановки как остановленную службу.