Просмотр и восстановление изменения проекта

Отделите сохраненные ресурсы от истории зафиксированных изменений.

При сохранении проекта, чертежа или траектории рабочая копия SQLite обновляется. При создании фиксации проекта рабочие ресурсы преобразуются в Git-совместимые объекты и перемещается ссылка на текущую ветку. Это отдельные операции: сохраненный рисунок может быть незафиксирован, а зафиксированная программа может оставаться локальной без какого-либо удаленного зеркала.

Служба истории боковой панели создает один канонический файл JSON для каждого ресурса. Дерево включает в себя файл project.json, чертежи, компоненты, траектории движения инструмента, указанные материалы/инструменты/конфигурации станков и производственные затраты. YAML рабочего процесса и другой несущий текст, не являющийся объектом, находятся в дереве репозитория, а не в обычных записях чертежей. Изменение одного объекта не требует рассмотрения всей базы данных как непрозрачного двоичного различия.

Прежде чем следовать изменяющимся примерам, выберите одноразовый или запланированный проект. Набор PROJECT_ID к его реальному идентификатору и использовать текущий URL-адрес соединения/носитель приложения. История проекта и конечные точки рабочего процесса документированы в файле справочник по API истории; метаданные проекта пишутся с использованием aPI проектов.

Объекты используют формат свободных объектов git с точностью до байта, поэтому идентификаторы фиксации и дерева соответствуют тому, что git рассчитывается для одного и того же контента. Ссылки на ветки находятся под refs/heads/, а ветка по умолчанию — main.

Проверьте идентичность и рабочее состояние

Доступ для чтения, фиксации, создания веток, открытия запросов на включение, проверок и диспетчеризации рабочих процессов требует доступа к проекту. Извлечение, восстановление, удаленная настройка, push-pull и объединение требуют доступа сопровождающего: владельца проекта или АДМИНИСТРА/МЕНЕДЖЕРА организации. Дополнительный заголовок сеанса учетной записи выбирает действующего пользователя; без действительного сеанса учетной записи приложение использует свой локальный профиль.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/status"

В ответе указывается ветвь, HEAD с нулевым значением и грязные пути. Грязный означает, что текущие файлы ресурсов отличаются от HEAD. Непустой список — это полезная информация для проверки, а не сбой хранилища. Прежде чем перемещать рабочую копию, решите, относятся ли эти изменения к коммиту или их следует намеренно восстановить/отбросить.

Если HEAD имеет значение null, запишите первую фиксацию проекта перед созданием ветки из HEAD. API ветки разрешает реальную фиксацию исходного кода; в новом проекте нет заполнителя для перехода.

Создайте базовый план или запишите предполагаемые изменения

Для фиксации требуется непустое сообщение и фиксируются текущие ресурсы базы данных. Сначала просмотрите «грязные» пути: API не подготавливает отдельные файлы сущностей. Необязательное поле «Файлы» добавляет определения безопасного рабочего процесса, описанные ниже; он не выбирает, какие изменения чертежа включить.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Record baseline blank"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/commit"

Ответом является запись фиксации 201 с идентификатором объекта, родительскими идентификаторами, сообщением и информацией об авторе. Запишите его OID для последующего сравнения или восстановления. Неизмененное дерево отклоняется с помощью NothingToCommit, вместо того чтобы создавать еще одну редакцию из того же содержимого.

authorKind по умолчанию пользователь. Коммиты, созданные помощником, используют ai и не могут совершать коммиты в main. Политика субъекта применяется службой проекта; другое сообщение на дисплее не обходит его. Создание фиксации может активировать рабочие процессы после записи фиксации. Последующий неудачный рабочий процесс не отменяет эту фиксацию.

Создать и проверить предложение

Создавая ветку пишет реф; он не переключает рабочую базу данных. Checkout является явным и отказывается от незафиксированных рабочих изменений. Следующие вызовы создают ветвь из текущего HEAD и загружают ее как извлеченную ветвь.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"name":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/branches"

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"branch":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/checkout"

Чтобы начать в другом месте, добавьте от ревизии к созданию ветки. Имена должны быть безопасными ссылками: обход, повторяющиеся косые черты, конечная косая черта/суффикс .lock и фрагменты ref-выражений отклоняются. Повторное использование существующего имени также запрещено.

После оформления заказа сохраните предполагаемые изменения проекта через API ресурсов. Для небольшой демонстрации обновите метаданные проекта, указав PUT /api/projects/:id и новое имя, а затем зафиксируйте его. Полученный результат меняет файл project.json; это не подразумевает изменения геометрии. В реальной версии детали сохраните чертеж и все восстановленные траектории перед фиксацией.

Прочтите точные изменения, находящиеся на рассмотрении

GET /vcs/log поддерживает оборот, ограничение и дополнительный отслеживаемый путь. GET /vcs/diff требует и принимает необязательный параметр from. Используйте явные OID для воспроизводимого сравнения. Кодируйте имена ветвей и пути JSON как значения запроса, а не добавляйте неэкранированные знаки препинания в URL-адреса.

curl --fail-with-body --get \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --data-urlencode "from=main" \
  --data-urlencode "to=proposal/blank-label" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/diff"

Изменения сущности включают путь, тип ресурса, добавленный/измененный/удаленный статус, необязательный идентификатор/имя и изменения свойств, описываемые указателями JSON. Canonical JSON рекурсивно сортирует ключи объектов, сохраняя порядок массива. Непересекающиеся изменения свойств объекта могут структурно сливаться; несовместимые одновременные изменения массива представляют собой атомарные конфликты, а не поэлементное согласование.

Просматривайте данные производства как часть записи траектории инструмента: соответствие G-кода и идентичности артефакта важнее, чем знакомое имя файла. При фиксации проекта фиксируются сохраненные данные; он не запускает отсутствующий собственный запрос на производство только потому, что дерево содержит текст ЧПУ.

Зафиксировать исполняемые проверки вместе с проектом

Дополнительные файлы конечной точки общедоступной фиксации ограничены .cadcamfun/workflows/<safe-name>.yml или ямл. Он принимает текстовые значения, а не произвольные исправления файловой системы. Вы не можете использовать это поле для замены рисунка JSON, написания сценариев оболочки или удаления файла, отправив значение null.

Определение фиксируется как текст YAML, затем бегун загружает его из этой зафиксированной ссылки. В приведенном ниже примере проверяются структурные файлы, требуется ЧПУ для существующих траекторий, проверяется последовательность операций и делается попытка воспроизведения для траекторий, несущих сохраненный запрос генератора.

name: Review checks
on:
  manual: true
  pullRequest:
    branches: [main]
jobs:
  inspect:
    steps:
      - id: structure
        uses: project/validate
      - uses: project/require-gcode
      - uses: cam/sequence
      - id: replay
        uses: cam/verify

Чтобы зафиксировать его из сценария, создайте тело JSON с помощью сериализатора, а не экранируйте YAML вручную:

const body = {
  message: "Add committed review checks",
  files: { ".cadcamfun/workflows/review.yml": await Bun.file("review.yml").text() }
}
const encoded = JSON.stringify(body)

Коммит по-прежнему сохраняет снимки всех текущих рабочих ресурсов. Проверьте YAML перед его записью: фиксация истории может быть успешной, в то время как полученный недействительный рабочий процесс позже будет записан как неудачный запуск. Производственный механизм проверяет схему, зависимости, циклы, повторяющиеся идентификаторы шагов и зарегистрированные идентификаторы использования.

Отправляйте проверки и интерпретируйте их показания

POST /api/projects/:id/actions/dispatch принимает необязательную ссылку и запускает каждый рабочий процесс вручную, соответствующий зафиксированной ссылке. Это не селектор с одним именем рабочего процесса. Прочтите определения в действиях/рабочих процессах и сохраняющиеся результаты в действиях/выполнениях. По умолчанию служба возвращает последние запуски 50.

При выполнении регистрируются рабочий процесс, триггер, ссылка, SHA, временные метки, состояние и события. Задания соответствуют уровням зависимости; независимые задания могут выполняться одновременно, а шаги внутри задания являются последовательными. Неизвестные идентификаторы использования терпят неудачу перед выполнением. Значение if — это успех, неудача или всегда, а не произвольное выражение. Неудачная зависимость полностью пропускает свою последующую работу.

Внимательно интерпретируйте результаты CAM. cam/verify и cam/gcode проверять совершенные Toolpath.data.request. Отсутствующие запросы, неподдерживаемые траектории инструмента или отсутствие ЧПУ могут быть указаны в пропущенных выходных данных. Успешный запуск с проверенным=0 не является доказательством проверки. project/require-gcode проверяет существующие траектории инструмента; проект без траекторий может бессмысленно удовлетворить эту потребность.

Автоматическая интеграция push-триггеров HTTP в настоящее время не предоставляет измененных путей, поэтому фильтр push-путей не соответствует этим событиям. Для этой интеграции используйте фильтры только для ветвей или явную ручную отправку. События начала/завершения HTTP в реальном времени публикуются после возврата синхронного выполнения; используйте сохраненные прогоны для получения устойчивых результатов.

Открытие, проверка и объединение предложения

Откройте локальный запрос на включение с заголовком, заголовком, необязательным телом и базой (основной по умолчанию). Голова и основание должны различаться, а базе, уже содержащей голову, нечего объединять. Ответ включает локальный номер проекта, используемый конечными точками проверки и слияния.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"title":"Review blank label","head":"proposal/blank-label","base":"main","body":"Metadata change and committed checks."}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/pulls"

GET /pulls/:number возвращает запрос, отзывы и изменения. Отзывы принимают комментарии, утверждают или запрашивают изменения с необязательным путем/указателем. Последний вердикт об отсутствии комментариев для каждого рецензента управляет блоком запросов на изменения. Более поздний комментарий не проясняет это; этот рецензент должен представить обновленный вердикт об одобрении. Реализация не требует положительного количества утверждений, если не остается вердикта о блокировке.

POST /pulls/:number/merge требует доступа сопровождающего. Актеры ИИ не могут сливаться с главными. Если база извлечена, служба требует чистую рабочую копию и применяет объединенный снимок к базе данных. Если извлечена другая ветка, она обновляет базовую ссылку без замены текущей рабочей базы данных. Слияния могут выполнять ускоренную перемотку вперед или создавать коммит слияния; проверять происхождение, а не предполагать наличие двух родителей.

Объединенные различия в пул-реквестах используют записанный коммит слияния, сохраняя представление обзора после перемещения ссылок. Локальные запросы на включение — это записи проверки приложения, а не автоматические запросы на включение GitHub.

Восстановление контента без переписывания истории

POST /vcs/restore принимает версию и дополнительные пути. Для этого требуется доступ сопровождающего и чистая рабочая копия, а также создается новый коммит, содержащий более ранний контент. Он не сбрасывает ветку назад и не стирает промежуточные коммиты. Затем служба применяет новый HEAD к рабочей базе данных.

{
  "rev": "earlier-commit-oid",
  "paths": ["drawings/actual-drawing-id.json"]
}

Замените путь реальным отслеживаемым ресурсом и сначала проверьте его разницу. Пропуск путей восстанавливает полное предыдущее дерево; который может заменить или удалить несколько связанных ресурсов. Снимки всего проекта также содержат элементы ссылочной библиотеки и стоимость, поэтому восстановленные траектории инструмента могут сохранять зависимости. Восстановление версии ресурса и восстановление истории проекта имеют разные области действия.

После восстановления источника производства проверьте, соответствует ли сохраненный исходный результат предполагаемой версии чертежа. Операция истории сохраняет более ранний артефакт; он не превращает этот артефакт в свидетельство недавно измененного рисунка.

Зеркальное отображение истории совершений и восстановление конфликтов

Зеркало GitHub не является обязательным. Установите для удаленного доступа строку владельца/репозитория с помощью PUT /vcs/remote или значение null для отсоединения. Push и pull используют для этого вызова токен GitHub пользователя в x-github-token; он не сохраняется в проекте JSON. Для этих операций HTTP требуется доступ сопровождающего.

Push загружает доступные объекты и отказывается перезаписывать невыполненные удаленные коммиты. Pull требует чистой рабочей копии, извлекает удаленную ветку и объединяет. Структурный конфликт JSON идентифицирует пути и указатели без написания частичного коммита слияния репозитория. Осмотрите обе стороны, примите обдуманное решение и повторите попытку, вместо того, чтобы навязывать одну сторону другой.

HTTP 409 обычно означает «грязное состояние» или конфликт слияния; 403 может означать ограничение сопровождающего или AI-main; 404 может означать недоступный проект или неизвестную версию; 400 охватывает недопустимые имена, пустые сообщения или отсутствие изменений. Сбой базы данных соответствует ошибке хранилища сервера. Сохраняйте OID и сообщение об ошибке при диагностике несоответствия.

Источник происхождения: packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts, и http/vcs.ts; схема рабочего процесса/бегун в packages/workflow/src и сайдкар workflow-runner.ts/workflow-steps.ts.

Как отзывы определяют слияние

1. Откройте запрос на включение из функциональной ветки (исполнитель ИИ должен использовать ai/* ветка) в main.
2. Рецензенты отправляют comment, approve, или request-changes, опционально привязанный к файлу path и JSON pointer.
3. Во время слияния служба принимает последний вердикт каждого рецензента без комментариев. Если какой-либо из них request-changes, слияние завершается неудачно с blocked: «Рецензент запросил изменения».
4. Если базовая ветка извлечена, ее рабочая копия должна быть чистой.
5. Слияние осуществляется в трех направлениях для каждого свойства JSON. Конфликты возвращаются со своими путями и указателями, и ничего не фиксируется.
6. Рабочие процессы с on.pullRequest соответствие базовой ветке, выполняемой при открытии запроса на включение, поэтому их результаты доступны во время проверки.

Восстановить рецепты

// Bring back one drawing as it was three commits ago
const old = repo.log()[3].oid
repo.restorePaths(old, ["drawings/d1.json"], me, "Restore plate outline")

// Make the whole tree equal to an older commit (a new commit on top)
repo.revertTo(old, me)               // message defaults to "Restore <rev>"

// Who changed a toolpath, most recent first
repo.fileLog("toolpaths/op1.json").map((e) => e.message)

Обе операции восстановления добавляют новую фиксацию, поэтому старое состояние само по себе может быть отменено, а история остается доступной для совместного использования. Восстановление файла траектории без материала или инструмента, на который он ссылается, может привести к тому, что ссылки останутся висящими; восстановить эти файлы библиотеки за один вызов.

Полная обзорная сессия, записанная

Каждый ответ ниже был получен из работающей сайдкара в новом проекте (идентификаторы сокращены). Пути относятся к /api/projects/{id}/.

# fresh project with one drawing
GET  vcs/status
{"branch":"main","head":null,"dirty":["drawings/2f315a02-….json","project.json"]}

POST vcs/commit       {"message":"Baseline"}
{"oid":"8bdded63…","parents":[],"message":"Baseline\n","author":{"name":"Local user",…}}

POST vcs/branches     {"name":"thicker"}
{"current":"main","branches":{"main":"8bdded63…","thicker":"8bdded63…"}}

POST vcs/checkout     {"branch":"thicker"}
{"branch":"thicker","head":"8bdded63…","dirty":[]}

PUT  /api/drawings/{id}  {"name":"Plate 12mm"}
GET  vcs/status
{"branch":"thicker","head":"8bdded63…","dirty":["drawings/2f315a02-….json"]}

POST vcs/commit       {"message":"Rename plate"}
{"oid":"a6869011…","parents":["8bdded63…"],…}

GET  vcs/diff?from=main&to=thicker
[{"path":"drawings/2f315a02-….json","kind":"drawings","id":"2f315a02-…","name":"Plate 12mm",
  "status":"modified","changes":[
    {"pointer":"/name","before":"Plate","after":"Plate 12mm"},
    {"pointer":"/updatedAt","before":"…09:20.069Z","after":"…09:20.168Z"}]}]

POST pulls            {"title":"Thicker plate","head":"thicker","base":"main"}
{"number":1,"state":"open","authorKind":"user","mergeCommit":null,…}

POST pulls/1/reviews  {"verdict":"approve","body":"Looks good"}
{"verdict":"approve","body":"Looks good","path":null,"pointer":null,…}

POST pulls/1/merge
{"number":1,"state":"merged","mergeCommit":"a6869011…",…}

POST pulls/1/merge    (again)
{"_tag":"BadRequest","message":"Pull request is not open"}

Поля просмотра и запроса

Через 3Д