Добавлена спецификация и навыки для codex и kimi-code

2026-11-05 14:07:19 +10:00
parent 0e3fd0358f
commit 54f8f14ed7
30 changed files with 3385 additions and 2 deletions
@@ -0,0 +1,55 @@
+# Спецификация Lightweight Cobot
+
+Эти базовые OpenSpec-спецификации описывают поведение, обнаруженное в исходном коде и конфигурации на 5 ноября 2026 года. `specs/` задаёт текущий контракт системы; будущие изменения следует оформлять в `changes/` и после реализации переносить в основные спецификации через архивирование OpenSpec.
+
+## Границы системы
+
+```text
+CLI cobot / ROS actions / HTTP и MCP / Foxglove и RViz
+                ↓
+        iiwa_bringup + конфигурация
+                ↓
+       MoveIt 2 + motion server
+                ↓
+    joint_trajectory_controller
+             ↙           ↘
+    Webots ros2_control   FRI hardware interface → Sunrise Cabinet
+```
+
+Физическое движение опирается на штатные функции безопасности контроллера KUKA и наблюдение оператора. Спецификации описывают поведение программного стека, а не сертификацию безопасности ячейки.
+
+## Карта контрактов
+
+| Раздел | Содержание | Основные источники |
+|---|---|---|
+| [deployment](specs/deployment/spec.md) | запуск, режимы, конфигурация | `cobot/`, `iiwa_bringup/`, `setting_loader.py` |
+| [robot-model](specs/robot-model/spec.md) | модель, суставы, инструмент и лимиты | `iiwa_description/`, `iiwa_config/`, `tool_manager.py` |
+| [fri-control](specs/fri-control/spec.md) | связь с Sunrise и аппаратный интерфейс | `iiwa_controller/`, `iiwa_sunrise/` |
+| [simulation](specs/simulation/spec.md) | Webots, объекты, камеры | `iiwa_bringup/`, `iiwa_utils/` |
+| [motion-planning](specs/motion-planning/spec.md) | суставное, декартово и именованное движение | `iiwa_msgs/`, `move_to_pose_server.py` |
+| [motion-arbitration](specs/motion-arbitration/spec.md) | приоритет, TCP-гизма и остановка | `motion_priority.py`, `tcp_gizmo.cpp` |
+| [direct-trajectories](specs/direct-trajectories/spec.md) | отправка траекторий JSON/CSV | `trajectory.py`, `direct_trajectory.py` |
+| [external-api](specs/external-api/spec.md) | HTTP, MCP и чтение состояния | `iiwa_web/`, `api_endpoints.yaml` |
+| [motion-sequences](specs/motion-sequences/spec.md) | последовательности целей и запись | `motion_sequence_runner.py`, `runner.py` |
+| [observability](specs/observability/spec.md) | RViz, Foxglove, состояние и диагностика | `iiwa_bringup/`, `iiwa_controller/` |
+| [sunrise-program](specs/sunrise-program/spec.md) | контроллерная программа и выбор сети | `iiwa_sunrise/` |
+| [project-tooling](specs/project-tooling/spec.md) | CLI, сборка и документация | `cobot/`, `scripts/`, `docker/` |
+
+## Важные различия и открытые вопросы
+
+- `cobot-setting.yaml` служит локальной конфигурацией. Спецификация ссылается на структуру настроек и значения в `src/iiwa_config/config/setting.yaml`, но не закрепляет IP и другие локальные параметры как универсальные.
+- `MoveToPose.action` и HTTP `POST /robot/move/pose` принимают KUKA ABC в **радианах**. `MoveToPose.srv` объявляет углы в **градусах** и скорость в процентах; в основном launch эта служба не поднимается. Перед использованием её контракт надо пересмотреть отдельно.
+- Веб-сервер и Foxglove по настройкам могут слушать `0.0.0.0`; в просмотренном коде HTTP/MCP не обнаружена прикладная аутентификация. Развёртывание за пределами доверенной сети требует отдельного решения по доступу.
+- README обещает WebSocket API; просмотренные исходники `iiwa_web` явно создают HTTP/FastAPI и MCP. Отдельный WebSocket endpoint в них не найден. Foxglove предоставляет собственный WebSocket bridge.
+- Именованные позы `home`, `work`, `transport` являются конфигурациями суставов в SRDF. Их наличие не доказывает безопасность конкретной физической сцены, нагрузки или инструмента.
+- Пределы ускорения и рывка в `joint_limits.yaml` помечены как проектные, а не подтверждённые характеристики KUKA.
+- Прямой API траекторий проверяет суставную кинематику и динамику, но не проверяет столкновения с окружением.
+- `ServerFriRos2` перед FRI выполняет подъезд к заданной в Java позиции. Значения `ZERO_POSITION` и `MONITOR_WORKING_POSITION` требуют проверки для каждой физической ячейки.
+- При заданном `bag_path` runner удаляет существующий каталог записи перед созданием нового MCAP; путь записи нельзя указывать на данные, которые нужно сохранить.
+
+## Проверка структуры
+
+```bash
+openspec list --specs
+openspec validate --specs --strict
+```