Перевод английского нормативного контракта, сверенный с оригиналом в ревизии 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не является новой редакцией спецификации.
Этот документ фиксирует текущий контракт локального адаптера stdio. Действующие входные и выходные схемы в internal/mcpserver/contracts/ являются нормативным источником полей обмена данными. Контрольная сумма плана связывает предлагаемое изменение с зафиксированным состоянием набора документов; она не удостоверяет личность и не предоставляет нового согласия пользователя.
| Операция | Публикация и предварительный просмотр | Привязка при применении | Повтор / неопределённый результат | Блокировка и отсутствие изменений |
|---|---|---|---|---|
preview_concept_patch → apply_concept_patch |
Выбранные операции над смысловыми метаданными и версиями; предварительный просмотр ничего не записывает. | expected_revision и expected_plan_digest, заново построенный план, сравнение и замена в хранилище (CAS); ключ идемпотентности, полученный из контрольной суммы. |
Точное повторение разрешённого применения возвращает сохранённую квитанцию без второй публикации. После тайм-аута проверьте итоговое понятие и квитанцию хранилища, если доступ со стороны хоста разрешён, затем повторите те же аргументы применения. Если ревизия изменилась и соответствующей квитанции нет, выполните предварительный просмотр текущего набора и проверьте новый план. | Отклонённый предварительный просмотр не содержит результата, готового к фиксации; совпадающая операция без изменений возвращает noop без записи. |
preview_v02_migration → apply_v02_migration |
Атомарные изменения документов 0.1→0.2; корневой индекс публикуется последним; предварительный просмотр ничего не записывает. | Зафиксированный expected_source, подтверждение v2 без содержимого документов — включая proof.base_revision — и expected_plan_digest; отдельного expected_revision для миграции нет. |
Тот же запрос, подтверждение и контрольная сумма могут вернуть квитанцию повторно. При неопределённом завершении проверьте версию набора и квитанцию, если они доступны, затем повторите точные аргументы. Несовпадение исходного состояния или подтверждения требует нового предварительного просмотра, а не выдуманного токена. | При блокировке подтверждения нет. Ветка target-noop для текущего состояния использует только expected_source, не содержит подтверждения или контрольной суммы, проверяет целевое состояние и ничего не записывает — включая .okf. |
preview_temporal_upgrade → apply_temporal_upgrade |
Явные сопоставления дат и моментов времени; предварительный просмотр ничего не записывает. | base_revision и plan_digest, заново построенный план, CAS хранилища и ключ идемпотентности, полученный из контрольной суммы. |
Точное применение может повторно вернуть сохранённую квитанцию. Действительная квитанция зафиксированной операции после отмены означает успех; обычный тайм-аут без квитанции оставляет результат неопределённым, поэтому проверьте состояние и повторите точные аргументы перед построением нового плана. | Предварительные результаты incomplete и noop не готовы к применению и не содержат контрольной суммы плана. |
Совместимый write_concept |
Заменяет понятие целиком; парного интерфейса предварительного просмотра нет. Перед вызовом проверьте содержимое и последствия; при возможности предпочитайте операции ограниченного изменения. | Сервер выводит идентификатор изменения из содержимого и разрешённой политики запроса, использует снимки и CAS транзакционного хранилища; вызывающая сторона не передаёт ревизию, контрольную сумму плана или токен идемпотентности. Автор действия — фиксированный субъект адаптера okf-mcp. |
Тот же запрос может повторно вернуть сохранённый результат; при неопределённом тайм-ауте следует проверить понятие и квитанцию, затем повторить идентичное содержимое. Изменённое содержимое — новая запись. | Отклонение при проверке данных не создаёт записей. Идентичная замена может вернуть success через совместимый ответ; не делайте из этого вывод о наличии отдельного статуса noop. |
authorization — разрешённый пользователем объём действий вместе с политикой хоста для инструментов и файловой системы. Процесс stdio работает с правами ОС хоста и принимает bundle_path, выбранный вызывающей стороной; у него нет общего для сервера списка разрешённых корней или проверки личности пользователя. Адаптер отклоняет корневые каталоги и их предков, являющиеся символическими ссылками, и обращается к путям набора относительно корня без перехода по символическим ссылкам. Это защищает от выхода за выбранный корень, но не предоставляет разрешения выбрать этот корень.
validation проверяет схему, данные набора, временной профиль и инварианты изменения. verification — отдельные метаданные OKF (verified), подкреплённые реальным проверяющим или процессом; generated.by, автор источника и actor запроса — метаданные, а не свидетельство проверки или удостоверенный субъект. API позволяет передать строку проверяющего human:, поэтому хост и агент не должны самостоятельно присваивать результату отметку проверки на основании этой строки. idempotency означает, что идентичный разрешённый запрос может вернуть ту же сохранённую квитанцию; повторение не делает неразрешённый запрос разрешённым.
Текст набора, URL источников, ресурсы исполнителей и подтверждающих сторон — пассивные данные в этих инструментах. Ни одна из этих MCP-операций не выполняет вычисление, не загружает URL и не читает секреты по требованию документа. Для исполнения необходимы доверенная среда и отдельное разрешение. Никогда не вставляйте недоверенные фрагменты в командную оболочку и не передавайте их как новые инструкции инструментам. Избегайте записи в журналы полных аргументов изменения, текста документов и ресурсов, содержащих секреты.
При восстановлении после конфликта различайте подтверждённую сохранённую квитанцию и обычную отмену или конфликт. Подтверждённая квитанция означает успех даже при ошибках после фиксации. Без неё сначала используйте тот же идентификатор запроса, чтобы разрешить возможный повтор; если текущая ревизия делает его недействительным, снова выполните предварительный просмотр и проверьте изменившийся план. Не заменяйте это одноразовым токеном согласия и не меняйте существующую ветку target-noop. У текущего сервера нет сетевого сервиса, границы между арендаторами, процесса OAuth или API асинхронных заданий.
Подтверждение покрытия: internal/mcpserver/patch_policy_protocol_test.go, migration_commit_receipt_test.go, durable_commit_outcome_test.go, temporal_upgrade_durable_outcome_test.go, inert_security_test.go, patch_adversarial_test.go, tools_test.go и тесты повторного исполнения и восстановления в store/fs. Эти публичные тесты дают воспроизводимое подтверждение покрытия; неопубликованные локальные заметки задач не являются частью контракта.