plan: add resource system guidance

- Add bound Sirna workflow names for experiment 1 and experiment 2 submissions.
- Route named workflow submission through a shared create-order core with minimal param payloads.
- Add direct scheduler controls and cancel/take-out manual confirmation handling.

.conda/base/recipe.yaml

@@ -3,7 +3,7 @@
 
 package:
   name: unilabos
-  version: 0.11.2
+  version: 0.11.1
 
 source:
   path: ../../unilabos
@@ -54,7 +54,7 @@ requirements:
   - pymodbus
   - matplotlib
   - pylibftdi
-  - uni-lab::unilabos-env ==0.11.2
+  - uni-lab::unilabos-env ==0.11.1
 
 about:
   repository: https://github.com/deepmodeling/Uni-Lab-OS

.conda/environment/recipe.yaml

@@ -2,7 +2,7 @@
 
 package:
   name: unilabos-env
-  version: 0.11.2
+  version: 0.11.1
 
 build:
   noarch: generic

.conda/full/recipe.yaml

@@ -3,7 +3,7 @@
 
 package:
   name: unilabos-full
-  version: 0.11.2
+  version: 0.11.1
 
 build:
   noarch: generic
@@ -11,7 +11,7 @@ build:
 requirements:
   run:
   # Base unilabos package (includes unilabos-env)
-  - uni-lab::unilabos ==0.11.2
+  - uni-lab::unilabos ==0.11.1
   # Documentation tools
   - sphinx
   - sphinx_rtd_theme

plan/2026-05-20_11_resource_material_sync_guidance_draft.md

@@ -0,0 +1,914 @@
+# Draft: Resource And Material Sync Guidance For Sirna And Similar Bioyond Systems
+
+Status: draft for discussion, not an implementation mandate.
+
+This note triangulates across five source categories with different authority:
+
+1. `docs/developer_guide/examples/workstation_architecture.md`: desired shape
+   and vocabulary. It is a design target, not proof that the current code has
+   every behavior.
+2. `BioyondWorkstation`, `BioyondResourceSynchronizer`, and shared graphio code:
+   the current compatibility anchor. New guidance should mostly preserve this
+   lifecycle and extend it deliberately.
+3. Existing non-Sirna Bioyond stations: practical examples of how the shared
+   base is used, including shortcuts that should not become policy.
+4. Sirna implementation, plans, findings, and guide notes: stress-test evidence.
+   They expose real missing cases, but the current Sirna code is not the
+   architecture authority because parts were added without fully aligning to the
+   shared base.
+5. UniLabOS resource framework behavior around PLR resources,
+   `ResourceTreeSet`, serialize/deserialize, and `update_resource(resources=...)`.
+
+The short recommendation is:
+
+Keep the shared Bioyond workstation lifecycle as the center of gravity. Evolve
+the shared synchronizer with small project hooks for classification, ID-based
+resolution, and non-slot material handling, rather than letting Sirna become a
+parallel synchronization model. For Sirna, those hooks should resolve placement
+by Bioyond IDs, distinguish physical slot labware from reagent liquid contents,
+preserve Bioyond IDs in `unilabos_extra`, mutate the local PLR deck, and publish
+the full deck through `update_resource(resources=[deck])`.
+
+Do not treat every Bioyond stock row as a deck resource.
+
+## Evidence Weighting
+
+This task is not a Sirna implementation retrospective. It is a best-practice
+alignment pass across the architecture target, the shared base class, observed
+station behavior, and Sirna's newly exposed edge cases.
+
+Use the sources this way:
+
+- Architecture doc: ask "what shape should this system eventually have?"
+- Shared Bioyond base: ask "what behavior must remain compatible today?"
+- Other Bioyond stations: ask "what patterns are already working in practice?"
+- Sirna current code and notes: ask "what did the base model fail to handle, and
+  which Sirna fixes conflict with the shared lifecycle?"
+- Live API/schema evidence: ask "what is true for this deployment's material,
+  warehouse, and coordinate data?"
+
+The Sirna AGENT_GUIDE is useful for finding caveats and prior investigations,
+but it should not be cited as an independent source of truth when source code,
+framework behavior, live API evidence, or architecture docs can answer the same
+question.
+
+## Mental Model
+
+There are three resource worlds. Confusing them is the main source of bugs.
+
+| World | Owner | Purpose | Recommended truth |
+| --- | --- | --- | --- |
+| Bioyond/LIMS | Bioyond APIs through `BioyondV1RPC` | External stock, material IDs, warehouse IDs, location IDs, inbound/outbound side effects | External material truth |
+| PLR deck | Workstation driver | Runtime workstation material layout, warehouse occupancy, liquid contents | Local mutation surface |
+| UniLabOS resource tree | `ResourceTreeSet` / ROS node / host resource APIs | Canonical UniLabOS/cloud representation | Framework/cloud truth |
+
+The architecture guide describes `Deck` as the local material system and
+`ResourceSynchronizer` as the optional external-system bridge
+(`docs/developer_guide/examples/workstation_architecture.md:221`). The broader
+framework serializes PLR objects into `ResourceTreeSet`, whose resource dicts
+carry `id`, `uuid`, `parent_uuid`, `type`, `class`, `pose`, `config`, `data`,
+and `extra` (`unilabos/resources/resource_tracker.py:107`).
+
+Therefore the correct path is:
+
+```text
+Bioyond rows
+  -> normalized material records
+  -> preserve Bioyond materialTypeMode: Sample / Consumables / Reagent
+  -> resolve material/location/warehouse IDs
+  -> choose UniLabOS handling for that mode
+  -> mutate PLR deck
+  -> ResourceTreeSet.from_plr_resources([deck])
+  -> ROS update_resource(resources=[deck])
+  -> host/cloud resource-tree update
+```
+
+Avoid direct cloud JSON patches and avoid treating Bioyond records as already
+being UniLabOS resource nodes.
+
+## Target Architecture
+
+The ideal architecture in `workstation_architecture.md` is still the right
+direction:
+
+1. `WorkstationBase` owns the local `deck`, workflow state, and hardware
+   interface.
+2. `ResourceSynchronizer` owns external material synchronization.
+3. `BioyondResourceSynchronizer` owns the Bioyond-specific use of
+   `BioyondV1RPC`.
+4. `ROS2WorkstationNode.update_resource(resources)` owns the UniLabOS/cloud
+   resource-tree update.
+5. Optional HTTP report handlers may trigger local deck mutation, external sync,
+   and cloud publication.
+
+The documented startup sequence is:
+
+1. Create workstation.
+2. Initialize PLR deck and warehouses.
+3. Create Bioyond RPC hardware interface.
+4. Create resource synchronizer.
+5. `sync_from_external()`.
+6. Initialize ROS node and children.
+7. `post_init(ros_node)`.
+8. Upload `resources=[deck]`.
+
+See `docs/developer_guide/examples/workstation_architecture.md:308`,
+`docs/developer_guide/examples/workstation_architecture.md:497`, and
+`docs/developer_guide/examples/workstation_architecture.md:737`.
+
+Important caveat: that document is the hope. It is still valuable because it
+names the desired responsibilities, but current Bioyond stations implement a
+more limited, best-effort side-effect sync. When the doc and current code
+diverge, use the doc to choose direction and the shared base code to choose the
+next compatible step.
+
+## Current Practical Behavior
+
+The shared `BioyondWorkstation` implementation is the current behavioral
+baseline. It does this today:
+
+1. Requires a deck.
+2. Reconstructs `deck.warehouses` from deck children/config when needed.
+3. Creates `BioyondV1RPC`.
+4. Installs `BioyondResourceSynchronizer`.
+5. Immediately calls `sync_from_external()`.
+6. Later, in `post_init`, publishes the whole deck with
+   `ROS2DeviceNode.run_async_func(self._ros_node.update_resource, True,
+   resources=[self.deck])`.
+
+Relevant code:
+
+- `BioyondResourceSynchronizer` is defined in
+  `unilabos/devices/workstation/bioyond_studio/station.py:117`.
+- `sync_from_external()` fetches stock `typeMode` 0, 1, and 2, then passes all
+  rows to `resource_bioyond_to_plr(...)`
+  (`unilabos/devices/workstation/bioyond_studio/station.py:147`).
+- `BioyondWorkstation.__init__` installs the synchronizer and syncs immediately
+  (`unilabos/devices/workstation/bioyond_studio/station.py:856`).
+- `post_init()` uploads the deck (`unilabos/devices/workstation/bioyond_studio/station.py:893`).
+- `resource_tree_add()` performs Bioyond create/inbound side effects
+  (`unilabos/devices/workstation/bioyond_studio/station.py:958`).
+
+This practical behavior works for simple physical-resource stock import, but it
+does not provide full continuous two-way sync, conflict resolution, or reliable
+stale-state cleanup. In particular:
+
+- Re-fetching stock does not clearly clear stale local deck state first.
+- Local-to-external update no-ops unless `unilabos_extra["update_resource_site"]`
+  is present.
+- `process_material_change_report()` is mostly TODO-level in the base station.
+- Some station-specific code bypasses the shared synchronizer with direct LIMS
+  calls.
+- Some existing stations contain shortcuts that should not be copied, such as
+  duplicate initialization, stale globals, or hardcoded warehouse/axis cases.
+
+Treat current Bioyond behavior as operationally useful and compatibility
+important, not as proof that the ideal architecture is already achieved. The
+goal is to tighten this base path, not replace it with a Sirna-only path.
+
+## Recommended Shared Pipeline
+
+For Sirna and similar Bioyond systems, the base synchronizer should evolve from
+the current shared path into one shared pipeline with small project hooks:
+
+```text
+sync_from_external()
+  fetch stock rows from Bioyond
+  update RPC material cache
+  normalize rows into a common internal shape
+  preserve materialTypeMode: Sample / Consumables / Reagent
+  resolve warehouse/location by Bioyond IDs when available
+  choose handling for the row's mode
+  apply Sample / Consumables rows as mapped slot labware by default
+  apply Reagent rows as physical reagent labware or liquid content by evidence
+  report unknown modes or unmapped handling loudly
+  publish deck if deck changed and ROS node is available
+```
+
+Suggested extension points:
+
+```python
+class BioyondResourceSynchronizer(ResourceSynchronizer):
+    def external_material_mode(self, row: dict) -> str:
+        return row["materialTypeMode"]  # Sample | Consumables | Reagent
+
+    def resolve_external_row(self, row: dict) -> dict:
+        ...
+
+    def apply_external_row(self, row: dict, mode: str, resolved: dict) -> None:
+        ...
+```
+
+The base class should continue to own:
+
+- stock fetches for `typeMode` 0/1/2;
+- material-cache refresh;
+- common normalization;
+- mode validation for `Sample` / `Consumables` / `Reagent`;
+- publication orchestration;
+- error aggregation;
+- stale-state policy once agreed.
+
+Project code should own only the parts that are truly deployment-specific:
+
+- material type/mode to PLR class mapping;
+- project-local handling inside `Sample` / `Consumables` / `Reagent`;
+- project-local warehouse ID/name mapping;
+- project-local coordinate conventions;
+- special row handling such as Sirna reagent-as-liquid.
+
+This keeps existing Bioyond stations close to the same lifecycle while still
+absorbing the Sirna lessons that the earlier base did not model. The default
+hook behavior can remain "Sample/Consumables/Reagent rows become mapped slot
+labware" for simpler stations; Sirna should override Reagent handling where
+evidence requires liquid-content behavior.
+
+## Sirna Findings To Feed Back Into Shared Design
+
+Treat Sirna as a stress test for the shared base, not as a replacement design.
+It raises real questions that earlier stations did not need to answer:
+
+- within the `Reagent` mode, some external rows may be liquid contents rather
+  than slot-occupying reagent labware;
+- placement should be ID-first where Bioyond supplies material/location IDs;
+- warehouse and axis metadata must survive serialize/deserialize;
+  project-specific mode handling is available.
+
+For Sirna-like deployments, the old implicit rule "stock row equals PLR
+resource" is too coarse. For simpler deployments, it can remain the default
+mode-handling behavior.
+
+### IDs Win
+
+Placement identity should prefer:
+
+```text
+materialId
+locationId
+materialTypeId
+warehouseId / whid
+```
+
+Display/debug fields are not identity:
+
+```text
+materialName
+materialCode
+locationCode
+locationShowName
+warehouseName / whName
+```
+
+`locationCode` such as `1-1` is not globally unique. It can exist in multiple
+warehouses. Code-only resolution may be kept as a diagnostic fallback, but it
+must raise on ambiguity.
+
+The current Sirna ID-first resolver is useful source evidence for this direction
+(`unilabos/devices/workstation/bioyond_studio/sirna_station/sirna_station.py:3659`).
+The Sirna mega plan captures the same concern, but the implementation and live
+Bioyond IDs are the stronger evidence.
+
+### Bioyond Modes And UniLabOS Handling Are Different
+
+Bioyond has three primary material modes in this context:
+
+```text
+Sample
+Consumables
+Reagent
+```
+
+Those modes should be preserved as the external taxonomy. UniLabOS still needs a
+handling decision inside the mode: should the row create/place a physical PLR
+resource, or update contents on an already-placed parent resource?
+
+Physical slot resources include things like:
+
+- tip racks;
+- plates;
+- cell culture plates;
+- empty trough/bottle labware;
+- other objects that occupy a warehouse slot.
+
+Reagents are contents of a parent labware when the row describes a liquid rather
+than a physical holder. For Sirna, Bioyond `stock_material(typeMode=2)` returns
+`materialTypeMode="Reagent"` rows; those rows still need evidence-based handling
+as either physical reagent labware or reagent liquid content. The finding in
+`temp_benyao/sirna/_findings/2026-05-07_reagents_vs_resources.md:6` records the
+bug: the generic path can fall back to `RegularContainer`, fail registry lookup,
+and drop reagent rows such as `试剂槽裂解液/Betame`.
+
+Recommended behavior:
+
+1. Validate `materialTypeMode` as `Sample`, `Consumables`, or `Reagent`.
+2. For `Sample` and `Consumables`, default to mapped slot labware: instantiate
+   the mapped PLR class and place it into the resolved warehouse slot.
+3. For `Reagent`, decide whether the row represents physical reagent labware or
+   reagent liquid content from material type evidence, row shape, and live data.
+4. For physical reagent labware, place the mapped PLR resource in the resolved
+   slot.
+5. For reagent liquid content, find the parent trough/bottle and attach liquid
+   metadata to its tracker.
+6. Preserve Bioyond IDs in `parent.unilabos_extra["reagent_bioyond_ids"]`.
+7. Make liquid attachment idempotent by Bioyond material ID.
+8. If the parent labware is missing or the mode/handling cannot be resolved,
+   defer or log with IDs; do not guess.
+
+The existing Sirna helper `_attach_liquid_to_parent()` already follows the
+idempotent metadata direction
+(`unilabos/devices/workstation/bioyond_studio/sirna_station/sirna_station.py:4074`).
+
+### The `0003` Question Must Stay Evidence-Based
+
+Do not blindly map `materialTypeCode 0003` to `BioyondSirna_ReagentTrough`.
+
+If live/schema evidence says a `0003` row is physical trough labware, map it to
+a PLR resource class. If evidence says it is liquid content, attach it to the
+parent trough. If evidence is contradictory, mark it unsupported and log the
+Bioyond IDs.
+
+Treat this as an open design decision until source/schema/live evidence settles
+the row shape. The Sirna plan records the question, but it should not decide the
+mapping by itself.
+
+### Sirna Warehouse And Axis Rules Are Project-Local
+
+Sirna warehouse layout and axis conventions must be verified from Sirna source,
+Sirna schema, current deck behavior, and live/read-only Sirna APIs when
+available. Do not import Peptide, reaction, dispensing, or cell station layout
+truth.
+
+For Sirna specifically, the current integrated deck display should be treated as
+the good baseline. The prior col-row slot-key fix is already present in the
+deck/graphio path, and any remaining x/y or y-reverse correction should be
+handled through shared warehouse metadata and shared graphio/display mapping
+rather than by reshaping the Sirna station display ad hoc.
+
+### Display Geometry: Evidence Before Axis Values
+
+Peptide resource sync should not be treated as a validated model, but its
+UniLabOS display work is useful and should influence this guidance.
+
+Confirmed Peptide behavior:
+
+- Peptide live warehouse evidence found `自动化堆栈` with 170 locations where
+  `code="10-17"` appears at `x=17, y=10`
+  (`../Uni-Lab-OS-Peptide/temp_benyao/peptide/_findings/2026-05-13_1404_peptide_col_row_deck.md:6`).
+- Peptide's current display convention is Peptide-specific evidence:
+  `bioyond_axis="xy_col_row"` and `bioyond_key_axis="col_row"` in the current
+  Peptide station implementation. Do not copy that pair into Sirna or any other
+  project without live warehouse evidence for that target system. With this
+  Peptide combination, graphio does not apply the legacy x/y swap
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/graphio.py:868`).
+- Peptide models the main automation stack as 17 visual rows by 10 visual
+  columns while preserving labels such as `10-17`
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/bioyond/decks.py:308`).
+- Peptide warehouses and deck child positions use `frontend_y_flip=True` /
+  `_frontend_y_flipped_coordinate(...)` so stored PLR coordinates compensate for
+  the frontend y-axis inversion
+  (`../Uni-Lab-OS-Peptide/unilabos/resources/bioyond/decks.py:299`;
+  `temp_benyao/peptide/_findings/2026-05-13_1514_frontend_y_flip_layout.md:6`).
+- The older Peptide graph-layout note is stale for the Sirna discussion. The
+  current Sirna integrated station/deck display is a good baseline; the reusable
+  Peptide lesson is axis metadata and frontend y-reverse compatibility.
+- Peptide tests encode the intended behavior: `10-17` lands at row 17 /
+  column 10, and after frontend y-flip the displayed site positions match the
+  expected top-to-bottom layout
+  (`../Uni-Lab-OS-Peptide/temp_benyao/peptide/tests/test_peptide_deck_layout.py:60`).
+
+Guidance for Sirna and similar systems:
+
+1. Treat `bioyond_axis` and `bioyond_key_axis` as two separate concepts:
+   - `bioyond_axis` describes how Bioyond numeric `x/y` map to visual axes.
+   - `bioyond_key_axis` describes how slot labels such as `10-17` are generated
+     or preserved.
+2. Do not infer display orientation from label strings alone. Both `row_col`
+   and `col_row` can preserve the same final label text while producing
+   different visual layouts and graphio swap behavior.
+3. Use live/read-only `code/x/y` evidence for each project and each warehouse
+   family before choosing axis metadata.
+4. Keep visual orientation fixes separate from material identity. IDs and slot
+   labels determine registration; display dimensions and frontend y-flip only
+   determine how the deck appears.
+5. Author intended display coordinates first, then convert stored y coordinates
+   for the active frontend convention:
+   - deck child stored y = `deck_height - display_y - child_height`;
+   - warehouse site stored y = `warehouse_height - display_y - site_height`;
+   - graph-level y values should be transformed only when the active frontend
+     convention requires it.
+6. Preserve the current Sirna display as the baseline unless concrete frontend
+   evidence shows a y-reverse problem. Do not change station/deck graph
+   semantics just to match stale Peptide layout notes.
+7. Add layout tests that assert:
+   - warehouse `num_items_x`, `num_items_y`, capacity, first key, and last key;
+   - representative `code/x/y` examples land on the intended site key;
+   - frontend y-flip produces expected displayed positions;
+   - generated deck children do not overlap in displayed coordinates.
+8. When borrowing from Peptide, borrow the evidence pattern: live discovery,
+   axis/key-axis metadata, y-flip tests, and display fixtures. Do not borrow a
+   literal axis pair or Peptide resource-sync behavior as a validated path.
+
+Concrete live discovery workflow:
+
+1. Prefer the reusable read-only probe pattern before reading old findings:
+
+```bash
+python3 temp_benyao/sirna/tests/probe_readonly_storage_inventory.py \
+  --base-url <api_host> \
+  --api-key <api_key> \
+  --output temp_benyao/<project>/_logs/<timestamp>_readonly_storage_inventory_probe.json
+```
+
+This probe checks swagger candidates, project storage/location endpoints,
+material type endpoints, `warehouse-info-by-mat-type-id`, and `stock-material`,
+then writes a redacted evidence file and a merged warehouse summary.
+
+2. For Sirna quick checks, `temp_benyao/sirna/tests/discover_sirna_warehouses.py`
+   is the narrower historical helper. Treat it as a template unless it has been
+   parameterized for the target config.
+3. Query `/api/storage/location/locations-by-type?type=0&typeMode=0&materialType=0`
+   first for stack names, warehouse IDs, full slot lists, `code`, `x`, `y`, `z`,
+   and display mode. This endpoint is the topology source when available.
+4. Cross-reference with `/api/lims/storage/material-types` and
+   `/api/lims/storage/warehouse-info-by-mat-type-id` to learn material-type
+   placement constraints. Use `stock-material` only for occupied-slot evidence;
+   it cannot reveal empty topology.
+5. Infer `bioyond_key_axis` from how slot labels must be generated or preserved,
+   and infer `bioyond_axis` from how raw Bioyond `x/y` must map to PLR holder
+   indices. A label such as `10-17` alone is ambiguous; compare it to the same
+   record's `x/y`, and use boundary examples from non-square stacks.
+6. Encode the discovered convention on the warehouse resource, not in a one-off
+   station branch. The metadata must serialize/deserialize with the warehouse
+   because graph load and cloud sync rebuild resources.
+7. Add or update layout tests before changing Sirna display behavior. For Sirna,
+   test against the current good display first, then only change shared x/y or
+   y-reverse mapping if the fixture demonstrates a real mismatch.
+
+### Deserialize Must Be Idempotent
+
+This is confirmed framework behavior, not a possible risk. Resource publication
+builds `ResourceTreeSet` from live PLR resources by calling
+`resource.serialize()` and `resource.serialize_all_state()`
+(`unilabos/resources/resource_tracker.py:547`). Readback/reconstruction goes
+through `ResourceTreeSet.to_plr_resources()`, finds the PLR subclass, calls
+`sub_cls.deserialize(...)`, then restores PLR state, UUIDs, and `unilabos_extra`
+(`unilabos/resources/resource_tracker.py:637`). `ResourceTreeSet.dump()` also
+serializes resource nodes while excluding `children` from each individual node
+record (`unilabos/resources/resource_tracker.py:914`), so parent/child
+relationships and object state must survive the framework tree shape rather than
+only an in-memory PLR object graph.
+
+Sirna resource/deck classes therefore must survive:
+
+1. registry-time construction;
+2. `Resource.deserialize()` round trips;
+3. cloud-synced deck state with serialized children.
+
+If a synced deck already has serialized `children`, default setup must not
+create duplicate/stale child resources. Sirna noticed this problem, but the
+reason is framework-level: cloud/resource-tree sync reconstructs PLR objects
+from serialized state, so constructors and setup logic must be idempotent.
+
+Existing Sirna deck code already acknowledges the issue: `BIOYOND_Sirna_Deck`
+turns `setup=False` during deserialize when serialized `children` are present
+(`unilabos/resources/bioyond/decks.py:153`). Sirna material classes also use
+registry-visible `@resource(...)` decorators and tolerant constructors with
+`*args, **kwargs`, defaults, and `ordering` fallbacks
+(`unilabos/resources/bioyond/sirna_materials.py:14`). Treat those as required
+patterns for any new synced resource class.
+
+Guidance:
+
+- Do not add a deck/resource class until it round-trips through
+  `Resource.serialize()` / `Resource.deserialize()` and
+  `ResourceTreeSet.from_plr_resources(...).to_plr_resources()`.
+- Preserve `unilabos_uuid`, parentage, `unilabos_extra`, and liquid state across
+  the round trip.
+- Make default setup conditional: if serialized children exist, do not recreate
+  default warehouses or default child resources on top of them.
+- Itemized PLR subclasses must provide `ordered_items` or `ordering`; otherwise
+  deserialization can fail or rebuild a different structure.
+
+## Startup And Resync Recommendation
+
+The current Sirna code installs `SirnaResourceSynchronizer` after
+`super().post_init(ros_node)` (`sirna_station.py:363`). That is useful as a
+phase patch and as evidence that classification hooks are needed, but it should
+not become the long-term lifecycle. Base initialization may already have run
+generic stock sync and base post-init may already have published the deck before
+the Sirna synchronizer is installed.
+
+Recommended pathway:
+
+1. Keep the `BioyondWorkstation` lifecycle as the base path.
+2. Add a synchronizer factory or hook registration point before eager sync, for
+   example `create_resource_synchronizer()`.
+3. Let Sirna provide classification/resolution hooks through that shared
+   synchronizer shape.
+4. Make startup sync use the installed hook-aware synchronizer before the first
+   deck publication.
+5. Make manual resync, reset resync, report-triggered resync, and future
+   periodic sync all call `self.resource_synchronizer.sync_from_external()`.
+6. Do not instantiate fresh base synchronizers inside Sirna actions, because
+   that bypasses the installed project logic.
+
+This directly addresses the overlap finding in
+`temp_benyao/sirna/_findings/2026-05-12_sirna_synchronizer_overlap.md:6`.
+
+## Material Registration From Create-Order Results
+
+Create-order allocation registration should remain separate from stock sync, but
+it should use the same classification and apply logic.
+
+Recommended create-order pipeline:
+
+1. Normalize allocation records into:
+
+```python
+{
+    "materialId": "...",
+    "materialCode": "...",
+    "materialName": "...",
+    "materialTypeId": "...",
+    "materialTypeCode": "...",
+    "materialTypeMode": "Sample|Consumables|Reagent",
+    "materialTypeName": "...",
+    "locationId": "...",
+    "locationCode": "...",
+    "locationShowName": "...",
+}
+```
+
+2. Resolve warehouse and slot by:
+
+```text
+material-info(materialId)
+  -> warehouse-info-by-mat-type-id(materialTypeId) matched by locationId
+  -> code-only diagnostic fallback only if unambiguous
+```
+
+3. Classify as `slot_labware`, `liquid_content`, or `unsupported`.
+4. Apply mutation to the PLR deck.
+5. Publish the full deck once after the batch.
+
+The current Sirna `_register_materials_to_tree()` already documents this flow
+(`sirna_station.py:3659`) and should be the local reference implementation until
+the shared hook is designed.
+
+## Cloud / UniLabOS Publication Rules
+
+Always mutate real tracked PLR resources first. Then publish through the
+framework.
+
+Correct call shape:
+
+```python
+ROS2DeviceNode.run_async_func(
+    self._ros_node.update_resource,
+    True,
+    **{"resources": [self.deck]},
+)
+```
+
+The real method is:
+
+```python
+async def update_resource(self, resources: List["ResourcePLR"])
+```
+
+See `unilabos/ros/nodes/base_device_node.py:727`.
+
+Do not call:
+
+```python
+update_resource(resource_name=..., resource_data=...)
+```
+
+Do not manually serialize the deck for this path. `update_resource()` creates a
+`ResourceTreeSet`, sends it to `/c2s_update_resource_tree`, and applies returned
+UUID mappings. Missing root parent UUIDs are auto-mounted to the current device,
+so parentage should be preserved on PLR objects before publication.
+
+## Metadata Contract
+
+Every Bioyond-originated slot resource should carry enough metadata for unload,
+audit, and later sync:
+
+```python
+plr_resource.unilabos_extra = {
+    "material_bioyond_id": mat["materialId"],
+    "material_bioyond_code": mat["materialCode"],
+    "material_bioyond_name": mat["materialName"],
+    "material_bioyond_type_id": mat["materialTypeId"],
+    "material_bioyond_type_code": mat["materialTypeCode"],
+    "material_bioyond_type_mode": mat["materialTypeMode"],
+    "location_bioyond_id": mat["locationId"],
+    "location_code": resolved["location_code"],
+    "warehouse_bioyond_id": resolved["warehouse_id"],
+    "warehouse_bioyond_name": resolved["warehouse_name"],
+    "location_resolution_source": resolved["source"],
+}
+```
+
+Every Bioyond-originated liquid content should preserve equivalent metadata on
+the parent labware:
+
+```python
+parent.unilabos_extra.setdefault("reagent_bioyond_ids", []).append({
+    "material_bioyond_id": mat["materialId"],
+    "material_bioyond_code": mat["materialCode"],
+    "material_bioyond_name": mat["materialName"],
+    "material_bioyond_type_id": mat["materialTypeId"],
+    "material_bioyond_type_code": mat["materialTypeCode"],
+    "location_bioyond_id": mat["locationId"],
+    "quantity": mat.get("quantity"),
+    "location_resolution_source": resolved["source"],
+})
+```
+
+This metadata is not decorative. It is required for correct unload, audit,
+duplicate prevention, and future round-trip sync.
+
+## Stale State And Conflict Policy
+
+This is confirmed current behavior, not just a theoretical risk.
+
+Current stock import places resources into empty warehouse slots and skips
+occupied slots. That prevents overwrites, but it can leave stale local resources
+after external moves/deletes.
+
+Evidence:
+
+- `BioyondResourceSynchronizer.sync_from_external()` fetches Bioyond stock and
+  delegates to `resource_bioyond_to_plr(...)`, but it does not compute a
+  before/after diff or remove local resources absent from the snapshot
+  (`unilabos/devices/workstation/bioyond_studio/station.py:147`).
+- `resource_bioyond_to_plr(...)` only assigns when the target warehouse position
+  is empty or a placeholder; when a real resource already occupies the slot, it
+  logs "跳过放置" and leaves the existing object in place
+  (`unilabos/resources/graphio.py:936`).
+- Bioyond outbound/removal logic exists in separate local-to-external hooks such
+  as `resource_tree_remove(...)`, but that is not invoked by stock refresh for
+  Bioyond rows that disappeared externally
+  (`unilabos/devices/workstation/bioyond_studio/station.py:987`).
+
+Recommended direction:
+
+1. Define Bioyond as the source of truth for external stock snapshots unless a
+   local operation is in progress.
+2. Before applying a stock snapshot, compute a diff by Bioyond material ID.
+3. Remove or mark local resources whose Bioyond IDs disappeared from the
+   snapshot, subject to workflow safety checks.
+4. Move local resources whose Bioyond location ID changed.
+5. Attach/detach liquid contents idempotently by Bioyond material ID.
+6. Publish once after applying the batch.
+7. In ambiguous or active-operation cases, log and require manual confirmation.
+
+Until this policy exists, call the current implementation "refresh/import" rather
+than "authoritative synchronization."
+
+## External-To-Local And Local-To-External Boundaries
+
+External-to-local:
+
+- Bioyond stock and create-order allocation rows mutate the local PLR deck.
+- Then UniLabOS publication derives resource trees from the PLR deck.
+
+Local-to-external:
+
+- `resource_tree_add` / update / remove may call Bioyond add, inbound, outbound,
+  or move APIs.
+- These paths should require Bioyond IDs or explicit creation parameters.
+- Movement should use `unilabos_extra["update_resource_site"]` only as an
+  explicit request, not as hidden ambient state.
+- After successful Bioyond side effects, refresh or update the PLR deck and
+  publish the deck.
+
+Avoid station-level direct LIMS calls that bypass the synchronizer unless the
+action explicitly reconciles the deck afterward.
+
+## Error Handling Rules
+
+Fail loudly on:
+
+- unknown material type code/name;
+- unresolved warehouse ID/name;
+- location ID not found in `warehouse-info-by-mat-type-id`;
+- code-only location ambiguity;
+- missing parent labware for liquid content;
+- invalid PLR resource class or `Resource.deserialize()` failure;
+- Bioyond RPC returning empty/fallback values where an ID is required.
+
+Do not silently create `RegularContainer` to hide mapping failures. The Sirna
+finding at `temp_benyao/sirna/_findings/2026-05-07_reagents_vs_resources.md:52`
+calls this out as a reusable trap.
+
+## Tests And Validation
+
+Minimum offline tests:
+
+1. `update_resource` is called only with `resources=[deck]`.
+2. `ResourceTreeSet.from_plr_resources([deck])` preserves UUIDs, parentage,
+   `data`, and `unilabos_extra`.
+3. Sirna allocation records resolve by `material-info` first.
+4. `warehouse-info-by-mat-type-id` resolves by `locationId`.
+5. Code-only fallback raises on ambiguous slots.
+6. `Sample` and `Consumables` rows become slot labware.
+7. Reagent content rows become parent liquid metadata.
+8. Re-running registration does not duplicate liquid entries.
+9. Missing parent labware is deferred/logged, not guessed.
+10. Unknown material type emits Bioyond IDs.
+11. Deck deserialize does not recreate duplicate default children.
+12. Warehouse coordinate mapping is tested per warehouse, not globally.
+13. A synced Sirna deck round-trips through PLR deserialize and
+    `ResourceTreeSet` conversion without duplicate default children.
+14. Stock refresh with a missing Bioyond material ID proves current add/skip
+    behavior first, then verifies the chosen diff/delete policy once implemented.
+15. Display geometry tests cover project-local live discovery fixtures,
+    `bioyond_axis`, `bioyond_key_axis`, representative `code/x/y` mappings,
+    frontend y-flip, and no-overlap deck layout.
+
+Focused Sirna command:
+
+```bash
+pytest temp_benyao/sirna/tests/test_sirna_resource_system.py -q
+```
+
+Shared conversion command, when changing graphio or Bioyond converters:
+
+```bash
+pytest tests/resources/test_converter_bioyond.py -q
+```
+
+Live/read-only validation should capture fixtures for:
+
+- `stock_material(typeMode=0/1/2, includeDetail=true)`;
+- `material-info(materialId)`;
+- `warehouse-info-by-mat-type-id(materialTypeId)`;
+- create-order allocation records;
+- frontend/cloud resource-tree readback after publication.
+
+## Discrepancies To Discuss
+
+### 1. Architecture Is Direction; Base Code Is The Compatibility Anchor
+
+The architecture guide presents `ResourceSynchronizer` as bidirectional. Current
+Bioyond code is mostly eager external import plus selected add/remove/update
+side effects. It has no complete continuous conflict-resolution loop.
+
+Sirna current code should be read in this context: it exposes missing
+capabilities, but parts of it conflict with the existing base lifecycle because
+it was layered on after the base sync behavior already existed.
+
+Recommendation: keep the bidirectional architecture as the target, preserve
+`BioyondWorkstation` as the implementation anchor, and introduce shared hooks
+for the missing Sirna-class problems. Describe the current implementation as
+best-effort refresh plus Bioyond side effects until a diff/conflict policy
+exists.
+
+### 2. The Doc Centers `Deck`; The Framework Centers `ResourceTreeSet`
+
+The architecture guide uses PLR `Deck` as the material system. UniLabOS resource
+tracking uses `ResourceTreeSet` as the canonical serialized representation.
+
+Recommendation: phrase the model as "Deck is the local PLR mutation surface;
+ResourceTreeSet is the UniLabOS/cloud representation derived from it."
+
+### 3. Base Bioyond Sync Treats Every Stock Row As PLR Resource
+
+`BioyondResourceSynchronizer.sync_from_external()` currently feeds typeMode
+0/1/2 rows into `resource_bioyond_to_plr(...)`.
+
+Sirna evidence shows this is wrong for reagent/content-like rows.
+
+Recommendation: add classification hooks before conversion. Rows classified as
+liquid content must not go through standalone PLR resource conversion.
+
+### 4. Sirna Fix Exists As A Fork, Not A Shared Hook
+
+Current `SirnaResourceSynchronizer` captures the important reagent-as-liquid
+question, but it duplicates or bypasses shared sync mechanics. Startup can run
+base sync before the Sirna synchronizer is installed, and manual/reset paths
+have used fresh base synchronizers.
+
+Recommendation: keep the discovered behavior where evidence supports it, but
+refactor the shape. A factory/hook in the shared synchronizer is preferable to a
+long-lived parallel sync class.
+
+### 5. Sirna Create-Order Registration Is Stronger Than Stock Sync
+
+Create-order registration now has ID-first resolution and a clearer classifier.
+That is valuable evidence, not automatically the canonical sync design. The
+stock sync path still resolves external liquid rows by warehouse name/code and
+stores weaker metadata.
+
+Recommendation: extract the stronger resolver/classifier ideas into shared
+hooks, then converge stock sync and create-order registration on the same
+functions.
+
+### 6. Graphio Has Shared Fragility
+
+`resource_bioyond_to_plr()` contains hardcoded warehouse/coordinate cases and a
+fallback to `RegularContainer`. Hardening it affects multiple Bioyond projects.
+
+Recommendation: after Sirna is green, discuss shared graphio hardening in a
+separate change: no silent `RegularContainer`, explicit unknown-type diagnostics,
+and project-specific axis metadata instead of hardcoded names.
+
+### 7. Serialize/Deserialize Is A Gating Contract
+
+This is not optional documentation neatness. Any new resource/deck class or sync
+metadata must pass the framework serialize/deserialize path before it can be
+trusted in cloud-synced operation.
+
+Recommendation: make round-trip tests part of acceptance for resource-system
+changes, especially for Sirna deck setup, warehouse metadata, `reagent_bioyond_ids`,
+liquid tracker state, and itemized labware ordering.
+
+### 8. Existing Stock Sync Is Add/Skip-Biased, Not Delete-Aware
+
+Current `sync_from_external()` imports and places observed Bioyond resources,
+but it does not delete local resources missing from the latest stock snapshot.
+When a target slot is occupied by a real resource, graphio skips placement rather
+than replacing it.
+
+Recommendation: describe the current behavior as "stock refresh/import" until a
+Bioyond-ID diff policy is implemented. Deletion/removal must be a deliberate
+phase, with workflow-safety checks and tests, not implied by the current stock
+sync name.
+
+### 9. Peptide Display Is Useful; Peptide Sync Is Not Yet Authority
+
+Peptide's latest display work is useful evidence for Peptide's own warehouse
+axis/key-axis metadata and for the shared need to account for frontend y-axis
+inversion. It does not define Sirna's axis values. Its resource sync remains
+untested/problematic and should not be treated as the model for Sirna sync
+behavior.
+
+Recommendation: fold the Peptide display lesson into shared guidance as a
+discovery-and-test pattern, not as a literal axis pair. Keep Sirna display
+behavior grounded in Sirna live evidence and the current good deck baseline; keep
+resource synchronization recommendations grounded in the Sirna ID-first
+registration path and the shared Bioyond synchronizer refactor.
+
+### 10. Some Existing Stations Should Be Examples Only, Not Templates
+
+Non-Sirna stations show useful patterns, but also shortcuts:
+
+- direct LIMS calls bypassing the synchronizer;
+- duplicate `super().__init__()` in reaction station;
+- stale/undefined `WAREHOUSE_MAPPING` references;
+- RPC methods collapsing failures into empty values;
+- no robust stale deck cleanup on stock refresh.
+
+Recommendation: borrow the shared deck publication and Bioyond ID metadata
+patterns, not the incidental shortcuts.
+
+## Recommended Discussion Path
+
+For the next implementation discussion, decide these in order:
+
+1. What is the smallest shared-base extension that lets project hooks exist
+   before eager sync without breaking existing Bioyond stations?
+2. Should `BioyondWorkstation` gain a synchronizer factory, a hook registry, or
+   a delayed eager-sync point?
+3. Is `materialTypeCode 0003` in current Sirna live data physical labware,
+   liquid content, or both depending on row shape?
+4. Where should Sirna warehouse Bioyond IDs live: station config, deck metadata,
+   or both?
+5. Should stock refresh clear/diff deck state now, or remain append/skip until
+   after create-order registration is stable?
+6. Should `update_resource` remain async/non-blocking for material registration,
+   or should selected user-facing actions fail if publication fails?
+7. Which parts of the Sirna reagent-as-liquid rule are project-local, and which
+   should become shared Bioyond behavior after Peptide/cell validation?
+8. Should graphio fallback hardening land before or after Sirna stock sync is
+   fully validated?
+9. Should any remaining Sirna x/y or y-reverse issue be fixed in shared
+   graphio/display mapping after a live fixture proves it, or should the current
+   Sirna deck remain untouched?
+
+## Recommended Pathway
+
+The pragmatic path is:
+
+1. Preserve and test the current `BioyondWorkstation` lifecycle as the shared
+   compatibility baseline.
+2. Treat Sirna create-order registration as a local proof of the missing
+   classification/ID-resolution behavior, not as the architecture shape to copy.
+3. Validate live/read-only Sirna fixtures for `0003`, warehouse IDs, and stock
+   reagent rows.
+4. Refactor the shared Bioyond synchronizer to expose classification,
+   resolution, and non-slot row hooks with default behavior matching existing
+   stations.
+5. Make Sirna install hooks before the first external sync and first deck
+   publication through the shared lifecycle.
+6. Route startup, manual resync, reset resync, and report-triggered resync
+   through the installed synchronizer.
+7. Converge stock sync and create-order registration on one
+   resolver/classifier/apply implementation.
+8. Add stale-state diffing only after the basic ID-first path is stable.
+9. Harden graphio fallback as a shared follow-up.
+
+This gives Sirna the necessary behavior without locking in a second Bioyond sync
+system that future projects will have to debug around.

recipes/msgs/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: ros-humble-unilabos-msgs
-  version: 0.11.2
+  version: 0.11.1
 source:
   path: ../../unilabos_msgs
   target_directory: src

recipes/unilabos/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: unilabos
-  version: "0.11.2"
+  version: "0.11.1"
 
 source:
   path: ../..

scripts/workflow.py

@@ -2,7 +2,6 @@ import json
 import logging
 import traceback
 import uuid
-import xml.etree.ElementTree as ET
 from typing import Any, Dict, List
 
 import networkx as nx
@@ -25,7 +24,15 @@ class SimpleGraph:
 
     def add_edge(self, source, target, **attrs):
         """添加边"""
-        edge = {"source": source, "target": target, **attrs}
+        # edge = {"source": source, "target": target, **attrs}
+        edge = {
+            "source": source, "target": target,
+            "source_node_uuid": source,
+            "target_node_uuid": target,
+            "source_handle_io": "source",
+            "target_handle_io": "target",
+            **attrs
+        }
         self.edges.append(edge)
 
     def to_dict(self):
@@ -42,6 +49,7 @@ class SimpleGraph:
             "multigraph": False,
             "graph": {},
             "nodes": nodes_list,
+            "edges": self.edges,
             "links": self.edges,
         }
 
@@ -58,495 +66,8 @@ def extract_json_from_markdown(text: str) -> str:
     return text
 
 
-def convert_to_type(val: str) -> Any:
-    """将字符串值转换为适当的数据类型"""
-    if val == "True":
-        return True
-    if val == "False":
-        return False
-    if val == "?":
-        return None
-    if val.endswith(" g"):
-        return float(val.split(" ")[0])
-    if val.endswith("mg"):
-        return float(val.split("mg")[0])
-    elif val.endswith("mmol"):
-        return float(val.split("mmol")[0]) / 1000
-    elif val.endswith("mol"):
-        return float(val.split("mol")[0])
-    elif val.endswith("ml"):
-        return float(val.split("ml")[0])
-    elif val.endswith("RPM"):
-        return float(val.split("RPM")[0])
-    elif val.endswith(" °C"):
-        return float(val.split(" ")[0])
-    elif val.endswith(" %"):
-        return float(val.split(" ")[0])
-    return val
 
 
-def refactor_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """统一的数据重构函数，根据操作类型自动选择模板"""
-    refactored_data = []
-
-    # 定义操作映射，包含生物实验和有机化学的所有操作
-    OPERATION_MAPPING = {
-        # 生物实验操作
-        "transfer_liquid": "SynBioFactory-liquid_handler.prcxi-transfer_liquid",
-        "transfer": "SynBioFactory-liquid_handler.biomek-transfer",
-        "incubation": "SynBioFactory-liquid_handler.biomek-incubation",
-        "move_labware": "SynBioFactory-liquid_handler.biomek-move_labware",
-        "oscillation": "SynBioFactory-liquid_handler.biomek-oscillation",
-        # 有机化学操作
-        "HeatChillToTemp": "SynBioFactory-workstation-HeatChillProtocol",
-        "StopHeatChill": "SynBioFactory-workstation-HeatChillStopProtocol",
-        "StartHeatChill": "SynBioFactory-workstation-HeatChillStartProtocol",
-        "HeatChill": "SynBioFactory-workstation-HeatChillProtocol",
-        "Dissolve": "SynBioFactory-workstation-DissolveProtocol",
-        "Transfer": "SynBioFactory-workstation-TransferProtocol",
-        "Evaporate": "SynBioFactory-workstation-EvaporateProtocol",
-        "Recrystallize": "SynBioFactory-workstation-RecrystallizeProtocol",
-        "Filter": "SynBioFactory-workstation-FilterProtocol",
-        "Dry": "SynBioFactory-workstation-DryProtocol",
-        "Add": "SynBioFactory-workstation-AddProtocol",
-    }
-
-    UNSUPPORTED_OPERATIONS = ["Purge", "Wait", "Stir", "ResetHandling"]
-
-    for step in data:
-        operation = step.get("action")
-        if not operation or operation in UNSUPPORTED_OPERATIONS:
-            continue
-
-        # 处理重复操作
-        if operation == "Repeat":
-            times = step.get("times", step.get("parameters", {}).get("times", 1))
-            sub_steps = step.get("steps", step.get("parameters", {}).get("steps", []))
-            for i in range(int(times)):
-                sub_data = refactor_data(sub_steps)
-                refactored_data.extend(sub_data)
-            continue
-
-        # 获取模板名称
-        template = OPERATION_MAPPING.get(operation)
-        if not template:
-            # 自动推断模板类型
-            if operation.lower() in ["transfer", "incubation", "move_labware", "oscillation"]:
-                template = f"SynBioFactory-liquid_handler.biomek-{operation}"
-            else:
-                template = f"SynBioFactory-workstation-{operation}Protocol"
-
-        # 创建步骤数据
-        step_data = {
-            "template": template,
-            "description": step.get("description", step.get("purpose", f"{operation} operation")),
-            "lab_node_type": "Device",
-            "parameters": step.get("parameters", step.get("action_args", {})),
-        }
-        refactored_data.append(step_data)
-
-    return refactored_data
-
-
-def build_protocol_graph(
-    labware_info: List[Dict[str, Any]], protocol_steps: List[Dict[str, Any]], workstation_name: str
-) -> SimpleGraph:
-    """统一的协议图构建函数，根据设备类型自动选择构建逻辑"""
-    G = SimpleGraph()
-    resource_last_writer = {}
-    LAB_NAME = "SynBioFactory"
-
-    protocol_steps = refactor_data(protocol_steps)
-
-    # 检查协议步骤中的模板来判断协议类型
-    has_biomek_template = any(
-        ("biomek" in step.get("template", "")) or ("prcxi" in step.get("template", ""))
-        for step in protocol_steps
-    )
-
-    if has_biomek_template:
-        # 生物实验协议图构建
-        for labware_id, labware in labware_info.items():
-            node_id = str(uuid.uuid4())
-
-            labware_attrs = labware.copy()
-            labware_id = labware_attrs.pop("id", labware_attrs.get("name", f"labware_{uuid.uuid4()}"))
-            labware_attrs["description"] = labware_id
-            labware_attrs["lab_node_type"] = (
-                "Reagent" if "Plate" in str(labware_id) else "Labware" if "Rack" in str(labware_id) else "Sample"
-            )
-            labware_attrs["device_id"] = workstation_name
-
-            G.add_node(node_id, template=f"{LAB_NAME}-host_node-create_resource", **labware_attrs)
-            resource_last_writer[labware_id] = f"{node_id}:labware"
-
-        # 处理协议步骤
-        prev_node = None
-        for i, step in enumerate(protocol_steps):
-            node_id = str(uuid.uuid4())
-            G.add_node(node_id, **step)
-
-            # 添加控制流边
-            if prev_node is not None:
-                G.add_edge(prev_node, node_id, source_port="ready", target_port="ready")
-            prev_node = node_id
-
-            # 处理物料流
-            params = step.get("parameters", {})
-            if "sources" in params and params["sources"] in resource_last_writer:
-                source_node, source_port = resource_last_writer[params["sources"]].split(":")
-                G.add_edge(source_node, node_id, source_port=source_port, target_port="labware")
-
-            if "targets" in params:
-                resource_last_writer[params["targets"]] = f"{node_id}:labware"
-
-        # 添加协议结束节点
-        end_id = str(uuid.uuid4())
-        G.add_node(end_id, template=f"{LAB_NAME}-liquid_handler.biomek-run_protocol")
-        if prev_node is not None:
-            G.add_edge(prev_node, end_id, source_port="ready", target_port="ready")
-
-    else:
-        # 有机化学协议图构建
-        WORKSTATION_ID = workstation_name
-
-        # 为所有labware创建资源节点
-        for item_id, item in labware_info.items():
-            # item_id = item.get("id") or item.get("name", f"item_{uuid.uuid4()}")
-            node_id = str(uuid.uuid4())
-
-            # 判断节点类型
-            if item.get("type") == "hardware" or "reactor" in str(item_id).lower():
-                if "reactor" not in str(item_id).lower():
-                    continue
-                lab_node_type = "Sample"
-                description = f"Prepare Reactor: {item_id}"
-                liquid_type = []
-                liquid_volume = []
-            else:
-                lab_node_type = "Reagent"
-                description = f"Add Reagent to Flask: {item_id}"
-                liquid_type = [item_id]
-                liquid_volume = [1e5]
-
-            G.add_node(
-                node_id,
-                template=f"{LAB_NAME}-host_node-create_resource",
-                description=description,
-                lab_node_type=lab_node_type,
-                res_id=item_id,
-                device_id=WORKSTATION_ID,
-                class_name="container",
-                parent=WORKSTATION_ID,
-                bind_locations={"x": 0.0, "y": 0.0, "z": 0.0},
-                liquid_input_slot=[-1],
-                liquid_type=liquid_type,
-                liquid_volume=liquid_volume,
-                slot_on_deck="",
-                role=item.get("role", ""),
-            )
-            resource_last_writer[item_id] = f"{node_id}:labware"
-
-        last_control_node_id = None
-
-        # 处理协议步骤
-        for step in protocol_steps:
-            node_id = str(uuid.uuid4())
-            G.add_node(node_id, **step)
-
-            # 控制流
-            if last_control_node_id is not None:
-                G.add_edge(last_control_node_id, node_id, source_port="ready", target_port="ready")
-            last_control_node_id = node_id
-
-            # 物料流
-            params = step.get("parameters", {})
-            input_resources = {
-                "Vessel": params.get("vessel"),
-                "ToVessel": params.get("to_vessel"),
-                "FromVessel": params.get("from_vessel"),
-                "reagent": params.get("reagent"),
-                "solvent": params.get("solvent"),
-                "compound": params.get("compound"),
-                "sources": params.get("sources"),
-                "targets": params.get("targets"),
-            }
-
-            for target_port, resource_name in input_resources.items():
-                if resource_name and resource_name in resource_last_writer:
-                    source_node, source_port = resource_last_writer[resource_name].split(":")
-                    G.add_edge(source_node, node_id, source_port=source_port, target_port=target_port)
-
-            output_resources = {
-                "VesselOut": params.get("vessel"),
-                "FromVesselOut": params.get("from_vessel"),
-                "ToVesselOut": params.get("to_vessel"),
-                "FiltrateOut": params.get("filtrate_vessel"),
-                "reagent": params.get("reagent"),
-                "solvent": params.get("solvent"),
-                "compound": params.get("compound"),
-                "sources_out": params.get("sources"),
-                "targets_out": params.get("targets"),
-            }
-
-            for source_port, resource_name in output_resources.items():
-                if resource_name:
-                    resource_last_writer[resource_name] = f"{node_id}:{source_port}"
-
-    return G
-
-
-def draw_protocol_graph(protocol_graph: SimpleGraph, output_path: str):
-    """
-    (辅助功能) 使用 networkx 和 matplotlib 绘制协议工作流图，用于可视化。
-    """
-    if not protocol_graph:
-        print("Cannot draw graph: Graph object is empty.")
-        return
-
-    G = nx.DiGraph()
-
-    for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
-        G.add_node(node_id, label=label, **attrs)
-
-    for edge in protocol_graph.edges:
-        G.add_edge(edge["source"], edge["target"])
-
-    plt.figure(figsize=(20, 15))
-    try:
-        pos = nx.nx_agraph.graphviz_layout(G, prog="dot")
-    except Exception:
-        pos = nx.shell_layout(G)  # Fallback layout
-
-    node_labels = {node: data["label"] for node, data in G.nodes(data=True)}
-    nx.draw(
-        G,
-        pos,
-        with_labels=False,
-        node_size=2500,
-        node_color="skyblue",
-        node_shape="o",
-        edge_color="gray",
-        width=1.5,
-        arrowsize=15,
-    )
-    nx.draw_networkx_labels(G, pos, labels=node_labels, font_size=8, font_weight="bold")
-
-    plt.title("Chemical Protocol Workflow Graph", size=15)
-    plt.savefig(output_path, dpi=300, bbox_inches="tight")
-    plt.close()
-    print(f"  - Visualization saved to '{output_path}'")
-
-
-from networkx.drawing.nx_agraph import to_agraph
-import re
-
-COMPASS = {"n","e","s","w","ne","nw","se","sw","c"}
-
-def _is_compass(port: str) -> bool:
-    return isinstance(port, str) and port.lower() in COMPASS
-
-def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: str = "LR"):
-    """
-    使用 Graphviz 端口语法绘制协议工作流图。
-    - 若边上的 source_port/target_port 是 compass（n/e/s/w/...），直接用 compass。
-    - 否则自动为节点创建 record 形状并定义命名端口 <portname>。
-    最终由 PyGraphviz 渲染并输出到 output_path（后缀决定格式，如 .png/.svg/.pdf）。
-    """
-    if not protocol_graph:
-        print("Cannot draw graph: Graph object is empty.")
-        return
-
-    # 1) 先用 networkx 搭建有向图，保留端口属性
-    G = nx.DiGraph()
-    for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
-        # 保留一个干净的“中心标签”，用于放在 record 的中间槽
-        G.add_node(node_id, _core_label=str(label), **{k:v for k,v in attrs.items() if k not in ("label",)})
-
-    edges_data = []
-    in_ports_by_node  = {}  # 收集命名输入端口
-    out_ports_by_node = {}  # 收集命名输出端口
-
-    for edge in protocol_graph.edges:
-        u = edge["source"]
-        v = edge["target"]
-        sp = edge.get("source_port")
-        tp = edge.get("target_port")
-
-        # 记录到图里（保留原始端口信息）
-        G.add_edge(u, v, source_port=sp, target_port=tp)
-        edges_data.append((u, v, sp, tp))
-
-        # 如果不是 compass，就按“命名端口”先归类，等会儿给节点造 record
-        if sp and not _is_compass(sp):
-            out_ports_by_node.setdefault(u, set()).add(str(sp))
-        if tp and not _is_compass(tp):
-            in_ports_by_node.setdefault(v, set()).add(str(tp))
-
-    # 2) 转为 AGraph，使用 Graphviz 渲染
-    A = to_agraph(G)
-    A.graph_attr.update(rankdir=rankdir, splines="true", concentrate="false", fontsize="10")
-    A.node_attr.update(shape="box", style="rounded,filled", fillcolor="lightyellow", color="#999999", fontname="Helvetica")
-    A.edge_attr.update(arrowsize="0.8", color="#666666")
-
-    # 3) 为需要命名端口的节点设置 record 形状与 label
-    #    左列 = 输入端口；中间 = 核心标签；右列 = 输出端口
-    for n in A.nodes():
-        node = A.get_node(n)
-        core = G.nodes[n].get("_core_label", n)
-
-        in_ports  = sorted(in_ports_by_node.get(n, []))
-        out_ports = sorted(out_ports_by_node.get(n, []))
-
-        # 如果该节点涉及命名端口，则用 record；否则保留原 box
-        if in_ports or out_ports:
-            def port_fields(ports):
-                if not ports:
-                    return " "  # 必须留一个空槽占位
-                # 每个端口一个小格子，<p> name
-                return "|".join(f"<{re.sub(r'[^A-Za-z0-9_:.|-]', '_', p)}> {p}" for p in ports)
-
-            left  = port_fields(in_ports)
-            right = port_fields(out_ports)
-
-            # 三栏：左(入) | 中(节点名) | 右(出)
-            record_label = f"{{ {left} | {core} | {right} }}"
-            node.attr.update(shape="record", label=record_label)
-        else:
-            # 没有命名端口：普通盒子，显示核心标签
-            node.attr.update(label=str(core))
-
-    # 4) 给边设置 headport / tailport
-    #    - 若端口为 compass：直接用 compass（e.g., headport="e"）
-    #    - 若端口为命名端口：使用在 record 中定义的 <port> 名（同名即可）
-    for (u, v, sp, tp) in edges_data:
-        e = A.get_edge(u, v)
-
-        # Graphviz 属性：tail 是源，head 是目标
-        if sp:
-            if _is_compass(sp):
-                e.attr["tailport"] = sp.lower()
-            else:
-                # 与 record label 中 <port> 名一致；特殊字符已在 label 中做了清洗
-                e.attr["tailport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(sp))
-
-        if tp:
-            if _is_compass(tp):
-                e.attr["headport"] = tp.lower()
-            else:
-                e.attr["headport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(tp))
-
-        # 可选：若想让边更贴边缘，可设置 constraint/spline 等
-        # e.attr["arrowhead"] = "vee"
-
-    # 5) 输出
-    A.draw(output_path, prog="dot")
-    print(f"  - Port-aware workflow rendered to '{output_path}'")
-
-
-def flatten_xdl_procedure(procedure_elem: ET.Element) -> List[ET.Element]:
-    """展平嵌套的XDL程序结构"""
-    flattened_operations = []
-    TEMP_UNSUPPORTED_PROTOCOL = ["Purge", "Wait", "Stir", "ResetHandling"]
-
-    def extract_operations(element: ET.Element):
-        if element.tag not in ["Prep", "Reaction", "Workup", "Purification", "Procedure"]:
-            if element.tag not in TEMP_UNSUPPORTED_PROTOCOL:
-                flattened_operations.append(element)
-
-        for child in element:
-            extract_operations(child)
-
-    for child in procedure_elem:
-        extract_operations(child)
-
-    return flattened_operations
-
-
-def parse_xdl_content(xdl_content: str) -> tuple:
-    """解析XDL内容"""
-    try:
-        xdl_content_cleaned = "".join(c for c in xdl_content if c.isprintable())
-        root = ET.fromstring(xdl_content_cleaned)
-
-        synthesis_elem = root.find("Synthesis")
-        if synthesis_elem is None:
-            return None, None, None
-
-        # 解析硬件组件
-        hardware_elem = synthesis_elem.find("Hardware")
-        hardware = []
-        if hardware_elem is not None:
-            hardware = [{"id": c.get("id"), "type": c.get("type")} for c in hardware_elem.findall("Component")]
-
-        # 解析试剂
-        reagents_elem = synthesis_elem.find("Reagents")
-        reagents = []
-        if reagents_elem is not None:
-            reagents = [{"name": r.get("name"), "role": r.get("role", "")} for r in reagents_elem.findall("Reagent")]
-
-        # 解析程序
-        procedure_elem = synthesis_elem.find("Procedure")
-        if procedure_elem is None:
-            return None, None, None
-
-        flattened_operations = flatten_xdl_procedure(procedure_elem)
-        return hardware, reagents, flattened_operations
-
-    except ET.ParseError as e:
-        raise ValueError(f"Invalid XDL format: {e}")
-
-
-def convert_xdl_to_dict(xdl_content: str) -> Dict[str, Any]:
-    """
-    将XDL XML格式转换为标准的字典格式
-
-    Args:
-        xdl_content: XDL XML内容
-
-    Returns:
-        转换结果，包含步骤和器材信息
-    """
-    try:
-        hardware, reagents, flattened_operations = parse_xdl_content(xdl_content)
-        if hardware is None:
-            return {"error": "Failed to parse XDL content", "success": False}
-
-        # 将XDL元素转换为字典格式
-        steps_data = []
-        for elem in flattened_operations:
-            # 转换参数类型
-            parameters = {}
-            for key, val in elem.attrib.items():
-                converted_val = convert_to_type(val)
-                if converted_val is not None:
-                    parameters[key] = converted_val
-
-            step_dict = {
-                "operation": elem.tag,
-                "parameters": parameters,
-                "description": elem.get("purpose", f"Operation: {elem.tag}"),
-            }
-            steps_data.append(step_dict)
-
-        # 合并硬件和试剂为统一的labware_info格式
-        labware_data = []
-        labware_data.extend({"id": hw["id"], "type": "hardware", **hw} for hw in hardware)
-        labware_data.extend({"name": reagent["name"], "type": "reagent", **reagent} for reagent in reagents)
-
-        return {
-            "success": True,
-            "steps": steps_data,
-            "labware": labware_data,
-            "message": f"Successfully converted XDL to dict format. Found {len(steps_data)} steps and {len(labware_data)} labware items.",
-        }
-
-    except Exception as e:
-        error_msg = f"XDL conversion failed: {str(e)}"
-        logger.error(error_msg)
-        return {"error": error_msg, "success": False}
 
 
 def create_workflow(

setup.py

@@ -4,7 +4,7 @@ package_name = 'unilabos'
 
 setup(
     name=package_name,
-    version='0.11.2',
+    version='0.11.1',
     packages=find_packages(),
     include_package_data=True,
     install_requires=['setuptools'],

unilabos/__init__.py

@@ -1 +1 @@
-__version__ = "0.11.2"
+__version__ = "0.11.1"

unilabos/app/utils.py

@@ -10,170 +10,29 @@ import shutil
 import sys
 
 
-_PATCH_MARKER = "# UniLabOS DLL Patch"
-_PATCH_END_MARKER = "# End UniLabOS DLL Patch"
-
-# 75 = EX_TEMPFAIL: 临时失败、重试即可，避免与业务退出码冲突
-_RESTART_EXIT_CODE = 75
-
-
-def _build_dll_patch(lib_bin: str, preload_pyd: str = "") -> str:
-    """生成一段加在目标文件顶部的 DLL 加载补丁源码。
-
-    - 始终把 ``lib_bin`` 加入 DLL 搜索路径，并把 handle 挂在模块属性上，
-      防止 GC 清掉搜索路径（``os.add_dll_directory`` 的句柄被回收时
-      目录会被移除）。
-    - 可选地用 ``ctypes.CDLL`` 预加载一个 .pyd，把它的依赖 DLL 提前装入
-      进程内存，作为 ``rclpy._rclpy_pybind11`` 这类首次加载点的兜底。
-    """
-    # 用 repr() 序列化路径：Python 解析 repr 的结果会还原成原始字符串，
-    # 不需要也不能再叠加 raw-string 前缀（叠了反而会让 \\ 变成两个反斜杠）。
-    lines = [
-        _PATCH_MARKER,
-        "import os as _ulab_os",
-        f"_ulab_p = {lib_bin!r}",
-        'if hasattr(_ulab_os, "add_dll_directory") and _ulab_os.path.isdir(_ulab_p):',
-        "    try: _UNILAB_DLL_HANDLE = _ulab_os.add_dll_directory(_ulab_p)",
-        "    except Exception: _UNILAB_DLL_HANDLE = None",
-    ]
-    if preload_pyd:
-        lines.extend(
-            [
-                "import ctypes as _ulab_ctypes",
-                f"try: _ulab_ctypes.CDLL({preload_pyd!r})",
-                "except Exception: pass",
-            ]
-        )
-    lines.append(_PATCH_END_MARKER)
-    return "\n".join(lines) + "\n"
-
-
-def _apply_dll_patch(file_path: str, lib_bin: str, preload_pyd: str = "") -> bool:
-    """把 DLL 补丁前置到 ``file_path``。文件不存在或已打过补丁则返回 False。"""
-    if not os.path.isfile(file_path):
-        return False
-    with open(file_path, "r", encoding="utf-8") as f:
-        content = f.read()
-    if _PATCH_MARKER in content:
-        return False
-    shutil.copy2(file_path, file_path + ".bak")
-    with open(file_path, "w", encoding="utf-8") as f:
-        f.write(_build_dll_patch(lib_bin, preload_pyd) + content)
-    return True
-
-
-def _print_restart_banner(patched_files):
-    """打印重启提示并以 EX_TEMPFAIL 退出。
-
-    - 不使用 ANSI 颜色码：Windows 旧版 cmd / PowerShell 5 默认不开 VT 处理，
-      会把 ``\\033[1;33m`` 当做字面字符显示，反而让用户看不到正文。
-    - 同时写入 stderr 与 stdout：某些上层 launcher / supervisor 只重定向
-      其中一路，写两遍能保证用户至少看到一份。
-    - 写入前防御性把流切到 UTF-8 with replace：``main.py`` 里已经做过一次，
-      但本模块也可能被绕过 ``main.py`` 的代码路径直接 import；reconfigure
-      失败也只是退回 errors=replace，不影响整体流程。
-    """
-    if sys.platform == "win32":
-        for _stream in (sys.stdout, sys.stderr):
-            try:
-                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
-            except (AttributeError, OSError):
-                pass
-
-    bar = "#" * 78
-    files_lines = [f"[UniLabOS]   - {p}" for p in patched_files]
-    body = "\n".join(
-        [
-            "",
-            bar,
-            bar,
-            "##",
-            "##  [UniLabOS] Windows + conda 下检测到 DLL 加载失败，已自动打补丁。",
-            "##  [UniLabOS] DLL load failure detected on Windows + conda;",
-            "##  [UniLabOS] the following files have been auto-patched:",
-            "##",
-            *[f"##  {line}" for line in files_lines],
-            "##",
-            "##  [UniLabOS] 当前进程的 rclpy 状态已损坏，补丁需要在新进程才生效。",
-            "##  [UniLabOS] The current process is unusable; the patch only takes",
-            "##  [UniLabOS] effect on a fresh process.",
-            "##",
-            "##  >>> 请重新运行刚才的命令 / Please re-run the same command. <<<",
-            "##",
-            bar,
-            bar,
-            "",
-        ]
-    )
-
-    for stream in (sys.stderr, sys.stdout):
-        try:
-            stream.write(body)
-            stream.flush()
-        except Exception:
-            try:
-                print(body, file=stream)
-            except Exception:
-                pass
-
-    sys.exit(_RESTART_EXIT_CODE)
-
-
 def patch_rclpy_dll_windows():
-    """在 Windows + conda 环境下修复 rclpy / rosidl typesupport 的 DLL 加载。
-
-    背景：conda 安装的 ros 系列包，其原生扩展依赖 ``$CONDA_PREFIX/Library/bin``
-    下的 DLL；只有 conda 环境被正确激活、且 PATH 中含 ``Library/bin`` 时，
-    ``os.add_dll_directory`` 才能找到它们。当从快捷方式 / IDE / 子进程 /
-    没激活的 shell 启动 ``unilab`` 时，会出现 ``DLL load failed``。
-
-    本函数会:
-        1) 修补 ``rclpy/impl/implementation_singleton.py`` —— rclpy 自身的 C 扩展入口；
-        2) 修补 ``rpyutils/add_dll_directories.py`` —— 所有 ``*_s__rosidl_typesupport_c.pyd``
-           （``geometry_msgs`` / ``std_msgs`` / ``sensor_msgs`` 等）的统一加载入口。
-
-    打完补丁后**必须重启进程**才能生效（当前进程的 rclpy 已经发生过
-    ``ImportError``，子模块仍处于损坏状态）。因此函数会主动退出，并在
-    stdout/stderr 同时打印明显的重启提示，避免用户被后续报错淹没。
-    """
+    """在 Windows + conda 环境下为 rclpy 打 DLL 加载补丁"""
     if sys.platform != "win32" or not os.environ.get("CONDA_PREFIX"):
         return
-
     try:
-        import rclpy  # noqa: F401
+        import rclpy
 
         return
     except ImportError as e:
         if not str(e).startswith("DLL load failed"):
             return
-
     cp = os.environ["CONDA_PREFIX"]
-    lib_bin = os.path.join(cp, "Library", "bin")
-    site_packages = os.path.join(cp, "Lib", "site-packages")
-    if not os.path.isdir(lib_bin):
+    impl = os.path.join(cp, "Lib", "site-packages", "rclpy", "impl", "implementation_singleton.py")
+    pyd = glob.glob(os.path.join(cp, "Lib", "site-packages", "rclpy", "_rclpy_pybind11*.pyd"))
+    if not os.path.exists(impl) or not pyd:
         return
-
-    patched = []
-
-    # 1) rclpy 自身的入口
-    rclpy_impl = os.path.join(site_packages, "rclpy", "impl", "implementation_singleton.py")
-    rclpy_pyd_matches = glob.glob(os.path.join(site_packages, "rclpy", "_rclpy_pybind11*.pyd"))
-    rclpy_pyd = rclpy_pyd_matches[0] if rclpy_pyd_matches else ""
-    if rclpy_pyd and _apply_dll_patch(rclpy_impl, lib_bin, preload_pyd=rclpy_pyd):
-        patched.append(rclpy_impl)
-
-    # 2) rpyutils —— 所有 rosidl typesupport pyd 的加载点；放在 rclpy 之后
-    #    例：geometry_msgs/geometry_msgs_s__rosidl_typesupport_c.pyd
-    rpyutils_dll = os.path.join(site_packages, "rpyutils", "add_dll_directories.py")
-    if _apply_dll_patch(rpyutils_dll, lib_bin):
-        patched.append(rpyutils_dll)
-
-    if not patched:
-        # 已经打过补丁但 rclpy 仍然加载失败：原因不是缺 DLL 搜索路径，
-        # 不要再次打补丁污染文件，让上层看到真实的 ImportError。
-        return
-
-    _print_restart_banner(patched)
+    with open(impl, "r", encoding="utf-8") as f:
+        content = f.read()
+    lib_bin = os.path.join(cp, "Library", "bin").replace("\\", "/")
+    patch = f'# UniLabOS DLL Patch\nimport os,ctypes\nos.add_dll_directory("{lib_bin}") if hasattr(os,"add_dll_directory") else None\ntry: ctypes.CDLL("{pyd[0].replace(chr(92),"/")}")\nexcept: pass\n# End Patch\n'
+    shutil.copy2(impl, impl + ".bak")
+    with open(impl, "w", encoding="utf-8") as f:
+        f.write(patch + content)
 
 
 patch_rclpy_dll_windows()

unilabos/devices/workstation/bioyond_studio/debug_call_log.py

@@ -0,0 +1,459 @@
+"""Per-action raw call/response log for Bioyond stations.
+
+When a debug session is active, ``wrap_rpc_http`` replaces a ``BioyondV1RPC``
+instance's ``post`` / ``get`` methods with closures that perform the HTTP
+transport themselves, capture the request/response details, and append a record
+to the active session before returning exactly what ``BaseRequest`` would have
+returned. Outside of an active session the wrapped method delegates to the
+original (unwrapped) implementation, leaving non-debug behavior intact.
+
+The session writes a Markdown file under ``out_dir`` mirroring the format of
+``temp_benyao/peptide/_logs/2026-04-30_160316_day3_samplefile_only_raw_calls.md``
+minus the "Raw Payload Argument" section.
+
+This module has no dependency on ``BioyondV1RPC`` itself; the only contract is
+that the wrapped instance descends from ``BaseRequest`` (i.e. has a logger
+returned by ``self.get_logger()``).
+"""
+
+from __future__ import annotations
+
+import contextvars
+import copy
+import inspect
+import json
+import re
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Iterator, List, Optional
+
+import requests
+
+__all__ = [
+    "CallRecord",
+    "CallLogContext",
+    "session",
+    "wrap_rpc_http",
+    "active_session",
+]
+
+
+_DEFAULT_TIMEOUT_GET = 30
+_DEFAULT_TIMEOUT_POST = 120
+
+
+@dataclass
+class CallRecord:
+    """One captured HTTP call inside a debug session."""
+
+    index: int
+    method: str
+    url: str
+    path: str
+    source: str
+    transport: str
+    http_status: Optional[int]
+    request_body: Any
+    response_body: Any
+    error: Optional[str] = None
+
+
+@dataclass
+class CallLogContext:
+    """State for a single ``session()`` block.
+
+    A session lazily creates its file on the first appended record. Actions
+    that abort before any RPC produce no file.
+    """
+
+    action: str
+    out_dir: Path
+    started_at: datetime
+    calls: List[CallRecord] = field(default_factory=list)
+    file_path: Optional[Path] = None
+
+    def append(self, record: CallRecord) -> None:
+        record.index = len(self.calls) + 1
+        self.calls.append(record)
+        self._write_file()
+
+    # -- file I/O -------------------------------------------------------------
+
+    def _resolve_file_path(self) -> Path:
+        if self.file_path is not None:
+            return self.file_path
+        timestamp = self.started_at.strftime("%Y-%m-%d_%H%M%S")
+        slug = _slugify_action(self.action)
+        candidate = self.out_dir / f"{timestamp}_{slug}_raw_calls.md"
+        suffix = 2
+        while candidate.exists():
+            candidate = (
+                self.out_dir
+                / f"{timestamp}_{slug}_raw_calls_{suffix:02d}.md"
+            )
+            suffix += 1
+        self.file_path = candidate
+        return self.file_path
+
+    def _write_file(self) -> None:
+        path = self._resolve_file_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_render_markdown(self), encoding="utf-8")
+
+
+_active_session: contextvars.ContextVar[Optional[CallLogContext]] = (
+    contextvars.ContextVar("_active_session", default=None)
+)
+
+
+def active_session() -> Optional[CallLogContext]:
+    """Return the currently active :class:`CallLogContext`, if any."""
+    return _active_session.get()
+
+
+@contextmanager
+def session(action: str, out_dir: Path) -> Iterator[CallLogContext]:
+    """Open a per-action debug session.
+
+    On entry, sets the module-level ``_active_session`` ContextVar so any
+    ``wrap_rpc_http``'d clients on the same thread/task record their calls.
+    On exit, the previous active session (if any) is restored.
+    """
+    ctx = CallLogContext(
+        action=str(action),
+        out_dir=Path(out_dir),
+        started_at=datetime.now(),
+    )
+    token = _active_session.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _active_session.reset(token)
+
+
+def wrap_rpc_http(rpc: Any) -> None:
+    """Idempotently wrap ``rpc.post`` / ``rpc.get``.
+
+    When a session is active (``_active_session.get() is not None``), the
+    wrapped methods perform the HTTP call themselves with ``requests`` and
+    record the call before returning the same value ``BaseRequest`` would have
+    returned. When no session is active, the wrapped methods delegate to the
+    original implementation, preserving stock ``BaseRequest`` behavior.
+
+    Calling this twice on the same instance is a no-op. The wrapper does not
+    alter ``rpc.form_post`` (no Sirna action calls it as of plan 3).
+    """
+    if rpc is None:
+        return
+    if getattr(rpc, "_debug_call_log_wrapped", False):
+        return
+
+    rpc._orig_post = rpc.post
+    rpc._orig_get = rpc.get
+
+    def _wrapped_post(
+        url: str,
+        params: Any = None,
+        files: Any = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        ctx = _active_session.get()
+        if ctx is None:
+            kwargs = {}
+            if params is not None:
+                kwargs["params"] = params
+            if files is not None:
+                kwargs["files"] = files
+            if headers is not None:
+                kwargs["headers"] = headers
+            return rpc._orig_post(url, **kwargs)
+        effective_params = params if params is not None else {}
+        effective_headers = (
+            headers
+            if headers is not None
+            else {"Content-Type": "application/json"}
+        )
+        source = _detect_source(rpc)
+        request_body = _redact(effective_params)
+        record = CallRecord(
+            index=0,
+            method="POST",
+            url=str(url),
+            path=_url_path(url),
+            source=source,
+            transport=_pick_transport(effective_params),
+            http_status=None,
+            request_body=request_body,
+            response_body=None,
+            error=None,
+        )
+        return_value: Any = None
+        try:
+            response = requests.post(
+                url,
+                data=json.dumps(effective_params) if effective_params else None,
+                headers=effective_headers,
+                timeout=_DEFAULT_TIMEOUT_POST,
+                files=files,
+            )
+        except Exception as exc:  # pragma: no cover - delegated to logger
+            record.error = f"transport error: {exc}"
+            try:
+                rpc.get_logger().error(f"Request ERROR: {exc}")
+            except Exception:
+                pass
+            ctx.append(record)
+            return None
+
+        record.http_status = response.status_code
+        record.response_body, parse_error = _decode_response_body(response)
+        try:
+            rpc.get_logger().debug(
+                f"Request >>> : {response.request.body} "
+                f"{response.status_code} {response.text}"
+            )
+        except Exception:
+            pass
+
+        if response.status_code == 200:
+            if parse_error is not None:
+                record.error = f"json parse error: {parse_error}"
+                return_value = None
+            else:
+                return_value = record.response_body
+        else:
+            record.error = f"HTTP {response.status_code}: {response.text}"
+            try:
+                rpc.get_logger().error(
+                    f"Request ERROR: ('Request ERROR:', {response.text!r})"
+                )
+            except Exception:
+                pass
+            return_value = None
+
+        ctx.append(record)
+        return return_value
+
+    def _wrapped_get(
+        url: str,
+        params: Any = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        ctx = _active_session.get()
+        if ctx is None:
+            kwargs = {}
+            if params is not None:
+                kwargs["params"] = params
+            if headers is not None:
+                kwargs["headers"] = headers
+            return rpc._orig_get(url, **kwargs)
+        effective_params = params if params is not None else {}
+        effective_headers = (
+            headers
+            if headers is not None
+            else {"Content-Type": "application/json"}
+        )
+        source = _detect_source(rpc)
+        request_body = _redact(effective_params)
+        record = CallRecord(
+            index=0,
+            method="GET",
+            url=str(url),
+            path=_url_path(url),
+            source=source,
+            transport="params",
+            http_status=None,
+            request_body=request_body,
+            response_body=None,
+            error=None,
+        )
+        return_value: Any = None
+        try:
+            response = requests.get(
+                url,
+                params=effective_params,
+                headers=effective_headers,
+                timeout=_DEFAULT_TIMEOUT_GET,
+            )
+        except Exception as exc:  # pragma: no cover - delegated to logger
+            record.error = f"transport error: {exc}"
+            try:
+                rpc.get_logger().error(f"Request ERROR: {exc}")
+            except Exception:
+                pass
+            ctx.append(record)
+            return None
+
+        record.http_status = response.status_code
+        record.response_body, parse_error = _decode_response_body(response)
+        try:
+            rpc.get_logger().debug(
+                f"Request >>> : {effective_params} "
+                f"{response.status_code} {response.text}"
+            )
+        except Exception:
+            pass
+
+        if response.status_code == 200:
+            if parse_error is not None:
+                record.error = f"json parse error: {parse_error}"
+                return_value = None
+            else:
+                return_value = record.response_body
+
+        ctx.append(record)
+        return return_value
+
+    rpc.post = _wrapped_post
+    rpc.get = _wrapped_get
+    rpc._debug_call_log_wrapped = True
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+_URL_PATH_RE = re.compile(r"https?://[^/]+(/.*)?$")
+_SLUG_RE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def _slugify_action(action: str) -> str:
+    slug = _SLUG_RE.sub("_", str(action)).strip("_")
+    return slug or "action"
+
+
+def _url_path(url: Any) -> str:
+    text = str(url or "")
+    match = _URL_PATH_RE.match(text)
+    if match and match.group(1):
+        return match.group(1)
+    if text.startswith("/"):
+        return text
+    return text
+
+
+def _pick_transport(params: Any) -> str:
+    if isinstance(params, dict) and "data" in params:
+        return "data"
+    return "params"
+
+
+def _detect_source(rpc: Any) -> str:
+    """Walk the call stack to find the outermost frame whose ``self`` is rpc."""
+    try:
+        stack = inspect.stack()
+    except Exception:
+        return ""
+    candidate = ""
+    try:
+        for frame_info in stack:
+            frame = frame_info.frame
+            if frame.f_locals.get("self", None) is rpc:
+                candidate = frame_info.function
+        return candidate
+    finally:
+        del stack
+
+
+def _redact(params: Any) -> Any:
+    """Return a copy of ``params`` with ``apiKey`` redacted."""
+    try:
+        cloned = copy.deepcopy(params)
+    except Exception:
+        return params
+    _redact_in_place(cloned)
+    return cloned
+
+
+def _redact_in_place(value: Any) -> None:
+    if isinstance(value, dict):
+        for key in list(value.keys()):
+            if isinstance(key, str) and key.lower() == "apikey":
+                value[key] = "<redacted>"
+            else:
+                _redact_in_place(value[key])
+    elif isinstance(value, list):
+        for item in value:
+            _redact_in_place(item)
+
+
+def _decode_response_body(response: Any) -> tuple[Any, Optional[str]]:
+    """Best-effort response decoding used for both record + return value."""
+    text = getattr(response, "text", "")
+    try:
+        return response.json(), None
+    except Exception as exc:
+        if text:
+            return {"raw_text": text}, str(exc)
+        return None, str(exc)
+
+
+# ---------------------------------------------------------------------------
+# Markdown rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_markdown(ctx: CallLogContext) -> str:
+    title = f"# {ctx.action} Raw Call/Response Log"
+    parts: List[str] = [title, ""]
+    parts.append("## LIMS Calls")
+    parts.append("")
+    parts.append("| # | Method | Path | Source | HTTP |")
+    parts.append("|---|---|---|---|---|")
+    for record in ctx.calls:
+        anchor = _row_anchor(record)
+        http = (
+            f"`{record.http_status}`"
+            if record.http_status is not None
+            else "`-`"
+        )
+        parts.append(
+            f"| [{record.index}](#{anchor}) | `{record.method}` | "
+            f"`{record.path}` | `{record.source}` | {http} |"
+        )
+    parts.append("")
+
+    for record in ctx.calls:
+        parts.append(f"## {record.index} {record.method} {record.path}")
+        parts.append("")
+        parts.append(f"- Source: `{record.source}`")
+        parts.append(f"- Transport: `{record.transport}`")
+        if record.http_status is not None:
+            parts.append(f"- HTTP status: `{record.http_status}`")
+        else:
+            parts.append("- HTTP status: `-`")
+        if record.error:
+            parts.append(f"- Error: {record.error}")
+        parts.append("")
+        parts.append("### Request Body")
+        parts.append("")
+        parts.append("```json")
+        parts.append(_to_json_block(record.request_body))
+        parts.append("```")
+        parts.append("")
+        parts.append("### Response Body")
+        parts.append("")
+        parts.append("```json")
+        parts.append(_to_json_block(record.response_body))
+        parts.append("```")
+        parts.append("")
+
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def _row_anchor(record: CallRecord) -> str:
+    """Build a GitHub-style anchor matching ``## N METHOD /path``."""
+    raw = f"{record.index}-{record.method}-{record.path}"
+    raw = raw.lower()
+    raw = re.sub(r"[^a-z0-9]+", "-", raw)
+    return raw.strip("-")
+
+
+def _to_json_block(value: Any) -> str:
+    try:
+        return json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
+    except TypeError:
+        return json.dumps(str(value), ensure_ascii=False, indent=2)

unilabos/devices/workstation/bioyond_studio/sirna_station/__init__.py

@@ -0,0 +1,3 @@
+from .sirna_station import BioyondSirnaStation, fetch_workflow_list, load_sirna_config
+
+__all__ = ["BioyondSirnaStation", "fetch_workflow_list", "load_sirna_config"]

unilabos/devices/workstation/bioyond_studio/station.py

@@ -7,6 +7,7 @@ Bioyond Workstation Implementation
 import time
 import traceback
 import threading
+from contextlib import contextmanager
 from datetime import datetime
 from typing import Dict, Any, List, Optional, Union
 import json
@@ -14,6 +15,7 @@ from pathlib import Path
 
 from unilabos.devices.workstation.workstation_base import WorkstationBase, ResourceSynchronizer
 from unilabos.devices.workstation.bioyond_studio.bioyond_rpc import BioyondV1RPC
+from unilabos.devices.workstation.bioyond_studio import debug_call_log
 from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
 from unilabos.resources.warehouse import WareHouse
 from unilabos.utils.log import logger
@@ -174,6 +176,8 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
                 logger.warning("从Bioyond获取的物料数据为空")
                 return False
 
+            self._update_material_cache_from_stock(all_bioyond_data)
+
             # 转换为UniLab格式
             unilab_resources = resource_bioyond_to_plr(
                 all_bioyond_data,
@@ -187,6 +191,29 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
             logger.error(f"从Bioyond同步物料数据失败: {e}")
             return False
 
+    def _update_material_cache_from_stock(self, materials: List[Dict[str, Any]]) -> None:
+        """用本次库存查询结果同步 RPC 的 name -> material id 缓存。"""
+        material_cache = getattr(self.bioyond_api_client, "material_cache", None)
+        if not isinstance(material_cache, dict):
+            return
+
+        before_count = len(material_cache)
+        for material in materials:
+            material_name = material.get("name")
+            material_id = material.get("id")
+            if material_name and material_id:
+                material_cache[material_name] = material_id
+
+            for detail_material in material.get("detail", []) or []:
+                detail_name = detail_material.get("name")
+                detail_id = detail_material.get("detailMaterialId") or detail_material.get("id")
+                if detail_name and detail_id:
+                    material_cache[detail_name] = detail_id
+
+        logger.debug(
+            f"已用Bioyond库存同步物料缓存: {before_count} -> {len(material_cache)}"
+        )
+
     def sync_to_external(self, resource: Any) -> bool:
         """将本地物料数据变更同步到Bioyond系统"""
         try:
@@ -678,6 +705,70 @@ class BioyondWorkstation(WorkstationBase):
     集成Bioyond物料管理的工作站实现
     """
 
+    # 子类（如 sirna / peptide）覆写以指定默认 raw-call 日志目录。
+    # 路径相对仓库根；为 None 时若 debug_log=True 仍会写入临时位置。
+    _DEBUG_LOG_DEFAULT_DIR: Optional[str] = None
+
+    def _create_bioyond_rpc(self, config: Dict[str, Any]) -> BioyondV1RPC:
+        """创建 Bioyond RPC 客户端并应用调试包装。
+
+        所有创建 ``BioyondV1RPC`` 的路径（饿汉初始化、Sirna 延迟初始化、
+        以及未来的前端重新配置路径）都应通过该 helper，
+        以确保 debug_log 包装与命名/日志策略保持一致。
+        """
+        rpc = BioyondV1RPC(config)
+        debug_call_log.wrap_rpc_http(rpc)
+        return rpc
+
+    def _set_hardware_interface(self, rpc: BioyondV1RPC) -> BioyondV1RPC:
+        """将已构造的 RPC 客户端设置到 ``self.hardware_interface``，并应用调试包装。"""
+        debug_call_log.wrap_rpc_http(rpc)
+        self.hardware_interface = rpc
+        return rpc
+
+    def _debug_log_resolved_dir(self) -> Path:
+        """解析 ``debug_log_dir`` 为绝对路径。"""
+        configured = (getattr(self, "bioyond_config", {}) or {}).get("debug_log_dir")
+        default_dir = getattr(self, "_DEBUG_LOG_DEFAULT_DIR", None)
+        candidate = configured or default_dir or "temp_benyao/_logs/bioyond_debug"
+        path = Path(candidate)
+        if not path.is_absolute():
+            repo_root = Path(__file__).resolve().parents[4]
+            path = repo_root / path
+        return path
+
+    def _ensure_debug_log_state(self) -> None:
+        """从 ``self.bioyond_config`` 派生 ``_debug_log_enabled`` / ``_debug_log_dir``。
+
+        每次进入 ``_debug_call_session`` 时都重新解析，以兼容前端在运行时
+        修改 ``bioyond_config['debug_log']`` 或目录的场景；同时也容忍
+        子类（如 Sirna 延迟初始化）在 ``__init__`` 早期未触发本方法。
+        """
+        cfg = getattr(self, "bioyond_config", {}) or {}
+        self._debug_log_enabled = bool(cfg.get("debug_log"))
+        self._debug_log_dir = self._debug_log_resolved_dir()
+
+    @contextmanager
+    def _debug_call_session(self, action_name: str):
+        """在 action 体外加一层 debug 会话上下文。
+
+        - ``debug_log`` 关闭时是空上下文，开销为 0。
+        - ``debug_log`` 开启时进入 :func:`debug_call_log.session`，所有
+          已被 ``wrap_rpc_http`` 包装过的 RPC 客户端都会捕获本次 action
+          产生的 HTTP 调用并写入 Markdown 文件。
+
+        子类（如 ``end_experiment``、``manual_unload`` 等）可以直接在
+        action 体里以 ``with self._debug_call_session("action_name"):`` 包裹。
+        """
+        cfg = getattr(self, "bioyond_config", {}) or {}
+        enabled = bool(cfg.get("debug_log"))
+        if not enabled:
+            yield None
+            return
+        out_dir = BioyondWorkstation._debug_log_resolved_dir(self)
+        with debug_call_log.session(action_name, out_dir) as ctx:
+            yield ctx
+
     def _publish_task_status(
         self,
         task_id: str,
@@ -862,7 +953,7 @@ class BioyondWorkstation(WorkstationBase):
             self.bioyond_config = {}
             print("警告: 未提供 bioyond_config，请确保在 JSON 配置文件中提供完整配置")
 
-        self.hardware_interface = BioyondV1RPC(self.bioyond_config)
+        self.hardware_interface = self._create_bioyond_rpc(self.bioyond_config)
 
     def resource_tree_add(self, resources: List[ResourcePLR]) -> None:
         """添加资源到资源树并更新ROS节点
@@ -1338,11 +1429,7 @@ class BioyondWorkstation(WorkstationBase):
             if self.hardware_interface:
                 self.hardware_interface.scheduler_reset()
 
-            # 刷新物料缓存
-            if self.hardware_interface:
-                self.hardware_interface.refresh_material_cache()
-
-            # 重新同步资源
+            # 重新同步资源，并用同一次库存查询结果更新物料缓存
             if self.resource_synchronizer:
                 self.resource_synchronizer.sync_from_external()
 

unilabos/resources/bioyond/__init__.py

@@ -0,0 +1 @@
+from . import sirna_materials  # noqa: F401  ensure @resource classes are importable for PLR deserialize

unilabos/resources/bioyond/decks.py

@@ -1,6 +1,8 @@
 from os import name
+
 from pylabrobot.resources import Deck, Coordinate, Rotation
 
+from unilabos.registry.decorators import resource
 from unilabos.resources.bioyond.YB_warehouses import (
     bioyond_warehouse_1x4x4,
     bioyond_warehouse_1x4x4_right,  # 新增：右侧仓库 (A05～D08)
@@ -23,6 +25,11 @@ from unilabos.resources.bioyond.YB_warehouses import (
 from unilabos.resources.bioyond.warehouses import (
     bioyond_warehouse_tipbox_storage_left,   # 新增：Tip盒堆栈(左)
     bioyond_warehouse_tipbox_storage_right,  # 新增：Tip盒堆栈(右)
+    bioyond_warehouse_sirna_automation_stack,
+    bioyond_warehouse_sirna_centrifuge_balance_plate_stack,
+    bioyond_warehouse_sirna_g3_liquid_handler,
+    bioyond_warehouse_numeric_stack,  # 新增：数字编码堆栈 (用于多肽站)
+    bioyond_warehouse_live_grid,
 )
 
 
@@ -101,6 +108,83 @@ class BIOYOND_PolymerPreparationStation_Deck(Deck):
         for warehouse_name, warehouse in self.warehouses.items():
             self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
 
+@resource(
+    id="BIOYOND_SirnaStation_Deck",
+    category=["deck"],
+    description="BIOYOND 小核酸工作站 Deck",
+    icon="配液站.webp",
+)
+class BIOYOND_SirnaStation_Deck(Deck):
+    WAREHOUSE_BIOYOND_AXIS = {
+        "G3移液站": "xy_col_row",
+        "自动化堆栈": "xy_col_row",
+        "离心机配平板堆栈": "xy_col_row",
+    }
+    WAREHOUSE_BIOYOND_KEY_AXIS = {
+        "G3移液站": "col_row",
+        "自动化堆栈": "col_row",
+        "离心机配平板堆栈": "col_row",
+    }
+    # Bioyond warehouse UUID -> 本地仓库名称 映射。
+    # 留空时由配置（station config 的 ``warehouse_bioyond_ids``）注入。
+    # graph 节点也可在 deck.config.warehouse_bioyond_ids 覆盖。
+    WAREHOUSE_BIOYOND_IDS: dict = {}
+
+    def __init__(
+        self,
+        name: str = "SirnaStation_Deck",
+        size_x: float = 2700.0,
+        size_y: float = 1080.0,
+        size_z: float = 1500.0,
+        category: str = "deck",
+        setup: bool = False,
+        warehouse_bioyond_ids: dict | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(name=name, size_x=size_x, size_y=size_y, size_z=size_z)
+        # 按需写入实例级覆盖；保留默认空 mapping，避免改动模型常量。
+        self.warehouse_bioyond_ids: dict = dict(self.WAREHOUSE_BIOYOND_IDS)
+        if warehouse_bioyond_ids:
+            self.warehouse_bioyond_ids.update(warehouse_bioyond_ids)
+        if setup:
+            self.setup()
+
+    @classmethod
+    def deserialize(cls, data: dict, allow_marshal: bool = False):
+        if data.get("children") and data.get("setup") is True:
+            data = data.copy()
+            data["setup"] = False
+        result = super().deserialize(data, allow_marshal=allow_marshal)
+        result._ensure_sirna_warehouse_metadata()
+        return result
+
+    def _ensure_sirna_warehouse_metadata(self) -> None:
+        for child in getattr(self, "children", []):
+            name = getattr(child, "name", "")
+            axis = self.WAREHOUSE_BIOYOND_AXIS.get(name)
+            if axis and not hasattr(child, "bioyond_axis"):
+                child.bioyond_axis = axis
+            key_axis = self.WAREHOUSE_BIOYOND_KEY_AXIS.get(name)
+            if key_axis and not hasattr(child, "bioyond_key_axis"):
+                child.bioyond_key_axis = key_axis
+
+    def setup(self) -> None:
+        # Sirna 读接口 /api/storage/location/locations-by-type 返回完整固定堆栈清单。
+        # LIMS 在库物料接口仍使用相同的 自动化堆栈 名称和数字库位编码。
+        self.warehouses = {
+            "G3移液站": bioyond_warehouse_sirna_g3_liquid_handler(),
+            "自动化堆栈": bioyond_warehouse_sirna_automation_stack(),
+            "离心机配平板堆栈": bioyond_warehouse_sirna_centrifuge_balance_plate_stack(),
+        }
+        self.warehouse_locations = {
+            "G3移液站": Coordinate(0.0, 0.0, 0.0),
+            "自动化堆栈": Coordinate(220.0, 0.0, 0.0),
+            "离心机配平板堆栈": Coordinate(1740.0, 0.0, 0.0),
+        }
+
+        for warehouse_name, warehouse in self.warehouses.items():
+            self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
+
 class BIOYOND_YB_Deck(Deck):
     def __init__(
         self,
@@ -150,12 +234,146 @@ class BIOYOND_YB_Deck(Deck):
         for warehouse_name, warehouse in self.warehouses.items():
             self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
 
+@resource(
+    id="BIOYOND_PeptideStation_Deck",
+    category=["deck"],
+    description="BIOYOND 多肽工作站 Deck",
+    icon="preparation_station.webp",
+)
+class BIOYOND_PeptideStation_Deck(Deck):
+    WAREHOUSE_BIOYOND_AXIS = dict.fromkeys(
+        [
+            "自动化堆栈",
+            "低温冰箱仓库",
+            "Tecan移液站库",
+            "G3移液站库",
+            "IDOT移液站库",
+            "G3缓冲库",
+            "盖板缓冲库",
+            "配平板缓冲库",
+            "IDOT缓冲库",
+            "固相合成板底座缓冲位",
+            "离心机库位",
+            "热封膜机位",
+        ],
+        "xy_col_row",
+    )
+    WAREHOUSE_BIOYOND_KEY_AXIS = dict.fromkeys(WAREHOUSE_BIOYOND_AXIS, "row_col")
+
+    def __init__(
+        self,
+        name: str = "PeptideStation_Deck",
+        size_x: float = 3500.0,
+        size_y: float = 1800.0,
+        size_z: float = 1500.0,
+        category: str = "deck",
+        setup: bool = False
+    ) -> None:
+        super().__init__(name=name, size_x=size_x, size_y=size_y, size_z=size_z)
+        if setup:
+            self.setup()
+
+    @classmethod
+    def deserialize(cls, data: dict, allow_marshal: bool = False):
+        if data.get("children") and data.get("setup") is True:
+            # 已有序列化子资源，跳过 setup 避免重复创建
+            result = super(BIOYOND_PeptideStation_Deck, cls).deserialize(data, allow_marshal=allow_marshal)
+        else:
+            result = super(BIOYOND_PeptideStation_Deck, cls).deserialize(data, allow_marshal=allow_marshal)
+        result._ensure_peptide_warehouse_metadata()
+        return result
+
+    def _ensure_peptide_warehouse_metadata(self) -> None:
+        for child in getattr(self, "children", []):
+            name = getattr(child, "name", "")
+            axis = self.WAREHOUSE_BIOYOND_AXIS.get(name)
+            if axis and not hasattr(child, "bioyond_axis"):
+                child.bioyond_axis = axis
+            key_axis = self.WAREHOUSE_BIOYOND_KEY_AXIS.get(name)
+            if key_axis and not hasattr(child, "bioyond_key_axis"):
+                child.bioyond_key_axis = key_axis
+
+    def setup(self) -> None:
+        # 多肽工作站仓库配置
+        # 基于 2026-05-09 live API probe 发现的实际仓库拓扑 (12个仓库)
+        # 数据来源: temp_benyao/peptide/_logs/warehouse_discovery_raw_live_2026-05-09.json
+        self.warehouses = {
+            # 主自动化堆栈 - live API: code 10-17 -> x=17, y=10，显示为 10 行×17 列
+            "自动化堆栈": bioyond_warehouse_numeric_stack(
+                "自动化堆栈", rows=10, columns=17, bioyond_axis="xy_col_row", bioyond_key_axis="row_col"
+            ),
+
+            # 低温存储
+            "低温冰箱仓库": bioyond_warehouse_live_grid(
+                "低温冰箱仓库", rows=2, columns=3, slot_keys=["1", "2", "3", "4", "5", "6"]
+            ),
+
+            # 移液站库位
+            "Tecan移液站库": bioyond_warehouse_live_grid(
+                "Tecan移液站库", rows=1, columns=18, slot_keys=[str(index) for index in range(1, 19)]
+            ),
+            "G3移液站库": bioyond_warehouse_live_grid(
+                "G3移液站库",
+                rows=1,
+                columns=18,
+                slot_keys=["1", "2", "3", "4", "垃圾桶", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18"],
+            ),
+            "IDOT移液站库": bioyond_warehouse_live_grid(
+                "IDOT移液站库",
+                rows=1,
+                columns=12,
+                slot_keys=[f"0009-{index:04d}" for index in range(1, 13)],
+            ),
+
+            # 缓冲库位
+            "G3缓冲库": bioyond_warehouse_live_grid(
+                "G3缓冲库", rows=1, columns=5, slot_keys=[str(index) for index in range(1, 6)]
+            ),
+            "盖板缓冲库": bioyond_warehouse_live_grid(
+                "盖板缓冲库", rows=1, columns=7, slot_keys=[str(index) for index in range(1, 8)]
+            ),
+            "配平板缓冲库": bioyond_warehouse_live_grid(
+                "配平板缓冲库", rows=1, columns=3, slot_keys=[str(index) for index in range(1, 4)]
+            ),
+            "IDOT缓冲库": bioyond_warehouse_live_grid(
+                "IDOT缓冲库", rows=1, columns=2, slot_keys=["1", "1"]
+            ),
+            "固相合成板底座缓冲位": bioyond_warehouse_live_grid(
+                "固相合成板底座缓冲位",
+                rows=1,
+                columns=4,
+                slot_keys=[f"0015-{index:04d}" for index in range(1, 5)],
+            ),
+
+            # 设备库位
+            "离心机库位": bioyond_warehouse_live_grid(
+                "离心机库位", rows=1, columns=4, slot_keys=[f"0017-{index:04d}" for index in range(1, 5)]
+            ),
+            "热封膜机位": bioyond_warehouse_live_grid(
+                "热封膜机位", rows=1, columns=2, slot_keys=[f"0016-{index:04d}" for index in range(1, 3)]
+            ),
+        }
+
+        # 仓库位置布局 (需根据实际硬件布局调整)
+        self.warehouse_locations = {
+            "自动化堆栈": Coordinate(0.0, 0.0, 0.0),
+            "Tecan移液站库": Coordinate(0.0, 1150.0, 0.0),
+            "G3移液站库": Coordinate(0.0, 1300.0, 0.0),
+            "IDOT移液站库": Coordinate(0.0, 1450.0, 0.0),
+            "G3缓冲库": Coordinate(0.0, 1600.0, 0.0),
+            "盖板缓冲库": Coordinate(850.0, 1600.0, 0.0),
+            "低温冰箱仓库": Coordinate(2700.0, 0.0, 0.0),
+            "配平板缓冲库": Coordinate(2700.0, 300.0, 0.0),
+            "IDOT缓冲库": Coordinate(2700.0, 450.0, 0.0),
+            "固相合成板底座缓冲位": Coordinate(2700.0, 600.0, 0.0),
+            "离心机库位": Coordinate(2700.0, 750.0, 0.0),
+            "热封膜机位": Coordinate(2700.0, 900.0, 0.0),
+        }
+
+        for warehouse_name, warehouse in self.warehouses.items():
+            self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
+
 def YB_Deck(name: str) -> Deck:
     by=BIOYOND_YB_Deck(name=name)
     by.setup()
     return by
-
-
-
-
-

unilabos/resources/bioyond/sirna_materials.py

@@ -0,0 +1,126 @@
+"""Sirna Station Material Resource Definitions
+
+Defines PyLabRobot resource classes for Bioyond Sirna station materials.
+Each class is decorated with @resource for AST-based registry discovery.
+"""
+
+from collections import OrderedDict
+
+from pylabrobot.resources import Plate, TipRack, Container
+
+from unilabos.registry.decorators import resource
+
+
+@resource(
+    id="bioyond_sirna_g3_200ul_tip_rack",
+    category=["labware", "tip_rack"],
+    description="G3-200ul枪头盒 for Sirna station",
+)
+class BioyondSirna_G3_200ul_TipRack(TipRack):
+    """G3-200ul tip rack for Sirna liquid handling."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("size_x", 127.76)
+        kwargs.setdefault("size_y", 85.48)
+        kwargs.setdefault("size_z", 64.0)
+        kwargs.setdefault("model", "bioyond_sirna_g3_200ul_tip_rack")
+        kwargs.setdefault("with_tips", True)
+        if kwargs.get("ordering") is None and kwargs.get("ordered_items") is None:
+            kwargs["ordering"] = OrderedDict()
+        super().__init__(*args, **kwargs)
+
+
+@resource(
+    id="bioyond_sirna_g3_50ul_tip_rack",
+    category=["labware", "tip_rack"],
+    description="G3-50ul枪头盒 for Sirna station",
+)
+class BioyondSirna_G3_50ul_TipRack(TipRack):
+    """G3-50ul tip rack for Sirna liquid handling."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("size_x", 127.76)
+        kwargs.setdefault("size_y", 85.48)
+        kwargs.setdefault("size_z", 64.0)
+        kwargs.setdefault("model", "bioyond_sirna_g3_50ul_tip_rack")
+        kwargs.setdefault("with_tips", True)
+        if kwargs.get("ordering") is None and kwargs.get("ordered_items") is None:
+            kwargs["ordering"] = OrderedDict()
+        super().__init__(*args, **kwargs)
+
+
+@resource(
+    id="bioyond_sirna_384_well_plate",
+    category=["labware", "plate"],
+    description="384孔板 for Sirna assays",
+)
+class BioyondSirna_384WellPlate(Plate):
+    """384-well plate for Sirna reporter gene detection."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("size_x", 127.76)
+        kwargs.setdefault("size_y", 85.48)
+        kwargs.setdefault("size_z", 14.35)
+        kwargs.setdefault("model", "bioyond_sirna_384_well_plate")
+        kwargs.setdefault("plate_type", "skirted")
+        if kwargs.get("ordering") is None and kwargs.get("ordered_items") is None:
+            kwargs["ordering"] = OrderedDict()
+        super().__init__(*args, **kwargs)
+
+
+@resource(
+    id="bioyond_sirna_cell_culture_plate",
+    category=["labware", "plate"],
+    description="细胞培养板 for Sirna cell culture",
+)
+class BioyondSirna_CellCulturePlate(Plate):
+    """Cell culture plate for Sirna experiments."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("size_x", 127.76)
+        kwargs.setdefault("size_y", 85.48)
+        kwargs.setdefault("size_z", 14.35)
+        kwargs.setdefault("model", "bioyond_sirna_cell_culture_plate")
+        kwargs.setdefault("plate_type", "skirted")
+        if kwargs.get("ordering") is None and kwargs.get("ordered_items") is None:
+            kwargs["ordering"] = OrderedDict()
+        super().__init__(*args, **kwargs)
+
+
+@resource(
+    id="bioyond_sirna_reagent_trough",
+    category=["labware", "trough"],
+    description="试剂槽 for Sirna reagents",
+)
+class BioyondSirna_ReagentTrough(Container):
+    """Reagent trough for Sirna station reagents (RiboGreen, etc.)."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("size_x", 127.76)
+        kwargs.setdefault("size_y", 85.48)
+        kwargs.setdefault("size_z", 44.0)
+        kwargs.setdefault("max_volume", 300000.0)
+        kwargs.setdefault("model", "bioyond_sirna_reagent_trough")
+        super().__init__(*args, **kwargs)
+
+
+# Material type code mapping for dynamic instantiation
+MATERIAL_TYPE_CODE_TO_CLASS = {
+    "0016": BioyondSirna_G3_200ul_TipRack,
+    "0017": BioyondSirna_G3_50ul_TipRack,
+    "0015": BioyondSirna_384WellPlate,
+    "0001": BioyondSirna_CellCulturePlate,
+    "0006": BioyondSirna_ReagentTrough,
+}
+
+
+def get_material_class_by_type_code(type_code: str):
+    """Get resource class by Bioyond material type code.
+
+    Args:
+        type_code: Bioyond materialTypeCode (e.g., "0016", "0017")
+
+    Returns:
+        Resource class or None if not found
+    """
+    return MATERIAL_TYPE_CODE_TO_CLASS.get(type_code)

unilabos/resources/bioyond/warehouses.py

@@ -1,5 +1,180 @@
+from pylabrobot.resources import Coordinate
+from pylabrobot.resources.carrier import ResourceHolder, create_homogeneous_resources
+
 from unilabos.resources.warehouse import WareHouse, warehouse_factory
 
+
+class BioyondWareHouse(WareHouse):
+    """Bioyond 仓库，额外保存服务端 x/y 坐标和库位标签语义。"""
+
+    def __init__(self, *args, bioyond_axis: str = "xy_row_col", bioyond_key_axis: str = "row_col", **kwargs):
+        super().__init__(*args, **kwargs)
+        self.bioyond_axis = bioyond_axis
+        self.bioyond_key_axis = bioyond_key_axis
+
+    def serialize(self) -> dict:
+        data = super().serialize()
+        data["bioyond_axis"] = self.bioyond_axis
+        data["bioyond_key_axis"] = self.bioyond_key_axis
+        return data
+
+
+def bioyond_warehouse_numeric_stack(
+    name: str,
+    rows: int = 10,
+    columns: int = 17,
+    bioyond_axis: str = "xy_row_col",
+    bioyond_key_axis: str = "row_col",
+) -> WareHouse:
+    """创建 Bioyond 数字库位堆栈，库位名使用服务端返回的 行-列 格式。
+
+    bioyond_axis: 仓库级别的 Bioyond 坐标轴约定，供 graphio 的坐标映射使用。
+        - "xy_row_col" (default): Bioyond x→row, y→col (reaction/peptide 历史约定).
+        - "xy_col_row": Bioyond x→col, y→row (Sirna live API 实测约定).
+    bioyond_key_axis: 库位标签生成约定。
+        - "row_col" (default): 视觉行列和标签行列一致，例如 10 行 x 17 列 → 1-1..10-17。
+        - "col_row": 视觉行列转置，但标签仍保持 Bioyond row-col，例如
+          17 行 x 10 列 → 1-1..10-17。
+    未设置时 graphio 回退到默认 "xy_row_col"，其他调用方保持原行为。
+    """
+    num_items_x = columns
+    num_items_y = rows
+    num_items_z = 1
+    dx = 10.0
+    dy = 10.0
+    dz = 10.0
+    item_dx = 147.0
+    item_dy = 106.0
+    item_dz = 130.0
+    locations = [
+        Coordinate(dx + col * item_dx, dy + row * item_dy, dz)
+        for row in range(num_items_y)
+        for col in range(num_items_x)
+    ]
+    holders = create_homogeneous_resources(
+        klass=ResourceHolder,
+        locations=locations,
+        resource_size_x=127.0,
+        resource_size_y=86.0,
+        resource_size_z=25.0,
+        name_prefix=name,
+    )
+    if bioyond_key_axis == "row_col":
+        keys = [
+            f"{row + 1}-{col + 1}"
+            for row in range(num_items_y)
+            for col in range(num_items_x)
+        ]
+    elif bioyond_key_axis == "col_row":
+        keys = [
+            f"{col + 1}-{row + 1}"
+            for row in range(num_items_y)
+            for col in range(num_items_x)
+        ]
+    else:
+        raise ValueError(f"未知 Bioyond 库位标签约定: {bioyond_key_axis!r}")
+    warehouse = BioyondWareHouse(
+        name=name,
+        size_x=dx + item_dx * num_items_x,
+        size_y=dy + item_dy * num_items_y,
+        size_z=dz + item_dz * num_items_z,
+        num_items_x=num_items_x,
+        num_items_y=num_items_y,
+        num_items_z=num_items_z,
+        ordering_layout="row-major",
+        sites={key: holder for key, holder in zip(keys, holders.values())},
+        category="warehouse",
+        bioyond_axis=bioyond_axis,
+        bioyond_key_axis=bioyond_key_axis,
+    )
+    return warehouse
+
+
+def bioyond_warehouse_live_grid(
+    name: str,
+    rows: int,
+    columns: int,
+    slot_keys: list[str] | None = None,
+    bioyond_axis: str = "xy_col_row",
+    bioyond_key_axis: str = "row_col",
+) -> WareHouse:
+    """创建 Bioyond 实测库位网格，按服务端 code 保存位点标签。
+
+    默认用于 Peptide live API 返回的坐标：x 是视觉列，y 是视觉行。
+    当服务端 code 重复时，为保持 PLR ordering 唯一性，会给后续重复项追加 ``#N``。
+    """
+    num_items_x = columns
+    num_items_y = rows
+    num_items_z = 1
+    dx = 10.0
+    dy = 10.0
+    dz = 10.0
+    item_dx = 147.0
+    item_dy = 106.0
+    item_dz = 130.0
+    locations = [
+        Coordinate(dx + col * item_dx, dy + row * item_dy, dz)
+        for row in range(num_items_y)
+        for col in range(num_items_x)
+    ]
+    holders = create_homogeneous_resources(
+        klass=ResourceHolder,
+        locations=locations,
+        resource_size_x=127.0,
+        resource_size_y=86.0,
+        resource_size_z=25.0,
+        name_prefix=name,
+    )
+    keys = slot_keys or [str(index + 1) for index in range(num_items_x * num_items_y)]
+    if len(keys) != len(holders):
+        raise ValueError(f"{name} 库位数量不匹配: keys={len(keys)}, holders={len(holders)}")
+
+    seen: dict[str, int] = {}
+    unique_keys: list[str] = []
+    for key in keys:
+        count = seen.get(key, 0) + 1
+        seen[key] = count
+        unique_keys.append(key if count == 1 else f"{key}#{count}")
+
+    return BioyondWareHouse(
+        name=name,
+        size_x=dx + item_dx * num_items_x,
+        size_y=dy + item_dy * num_items_y,
+        size_z=dz + item_dz * num_items_z,
+        num_items_x=num_items_x,
+        num_items_y=num_items_y,
+        num_items_z=num_items_z,
+        ordering_layout="row-major",
+        sites={key: holder for key, holder in zip(unique_keys, holders.values())},
+        category="warehouse",
+        bioyond_axis=bioyond_axis,
+        bioyond_key_axis=bioyond_key_axis,
+    )
+
+
+# ================ 小核酸工作站相关堆栈 ================
+
+def bioyond_warehouse_sirna_g3_liquid_handler(name: str = "G3移液站") -> WareHouse:
+    """创建小核酸 G3 移液站库位堆栈：显示为 14 行 x 1 列，标签保持 1-1..1-14。"""
+    return bioyond_warehouse_numeric_stack(
+        name, rows=14, columns=1, bioyond_axis="xy_col_row", bioyond_key_axis="col_row"
+    )
+
+
+def bioyond_warehouse_sirna_automation_stack(name: str = "自动化堆栈") -> WareHouse:
+    """创建小核酸自动化堆栈：显示为 17 行 x 10 列，标签保持 1-1..10-17。"""
+    return bioyond_warehouse_numeric_stack(
+        name, rows=17, columns=10, bioyond_axis="xy_col_row", bioyond_key_axis="col_row"
+    )
+
+
+def bioyond_warehouse_sirna_centrifuge_balance_plate_stack(name: str = "离心机配平板堆栈") -> WareHouse:
+    """创建小核酸离心机配平板堆栈：显示为 1 行 x 2 列，标签保持 1-1、2-1。"""
+    return bioyond_warehouse_numeric_stack(
+        name, rows=1, columns=2, bioyond_axis="xy_col_row", bioyond_key_axis="col_row"
+    )
+
+
 # ================ 反应站相关堆栈 ================
 
 def bioyond_warehouse_1x4x4(name: str) -> WareHouse:

unilabos/resources/graphio.py

@@ -42,7 +42,7 @@ def canonicalize_nodes_data(
     Returns:
         ResourceTreeSet: 标准化后的资源树集合
     """
-    print_status(f"{len(nodes)} Resources loaded:", "info")
+    print_status(f"{len(nodes)} Resources loaded", "info")
 
     # 第一步：基本预处理（处理graphml的label字段）
     outer_host_node_id = None
@@ -736,7 +736,7 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
             logger.warning(f"物料 {unique_name} 不是有效的 ResourcePLR 实例，类型: {type(plr_material)}")
             continue
 
-        plr_material.code = material.get("code", "") and material.get("barCode", "") or ""
+        plr_material.code = material.get("barCode") or material.get("code") or ""
         plr_material.unilabos_uuid = str(uuid.uuid4())
 
         # ⭐ 保存 Bioyond 原始信息到 unilabos_extra（用于出库时查询）
@@ -864,11 +864,22 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
                     warehouse = deck.warehouses[wh_name]
                     logger.debug(f"[Warehouse匹配] 找到warehouse: {wh_name} (容量: {warehouse.capacity}, 行×列: {warehouse.num_items_x}×{warehouse.num_items_y})")
 
-                    # Bioyond坐标映射 (重要！): x→行(1=A,2=B...), y→列(1=01,2=02...), z→层(通常=1)
-                    x = loc.get("x", 1)  # 行号 (1-based: 1=A, 2=B, 3=C, 4=D)
-                    y = loc.get("y", 1)  # 列号 (1-based: 1=01, 2=02, 3=03...)
+                    # Bioyond坐标映射:
+                    # - 历史 row_col 仓库中 x/y 直接按行/列参与索引。
+                    # - Sirna 的库位标签为 col-row，stock-material 返回 x=标签第二段、y=标签第一段。
+                    #   因此 x=13,y=4 应落到 key=4-13，而不是交换后落到 3-5。
+                    x = loc.get("x", 1)
+                    y = loc.get("y", 1)
                     z = loc.get("z", 1)  # 层号 (1-based, 通常为1)
 
+                    # 仓库级别的轴约定覆盖。
+                    # 对旧的 row-col 视觉标签，bioyond_axis="xy_col_row" 需要交换 x/y。
+                    # 对 Sirna 的 col-row 库位标签，原始 x/y 已能直接索引到 code 对应位置，不再交换。
+                    bioyond_axis = getattr(warehouse, "bioyond_axis", "xy_row_col")
+                    bioyond_key_axis = getattr(warehouse, "bioyond_key_axis", "row_col")
+                    if bioyond_axis == "xy_col_row" and bioyond_key_axis != "col_row":
+                        x, y = y, x
+
                     # 如果是右侧堆栈，需要调整列号 (5→1, 6→2, 7→3, 8→4)
                     if wh_name == "堆栈1右":
                         y = y - 4  # 将5-8映射到1-4
@@ -912,10 +923,43 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
                             logger.debug(f"列优先warehouse {wh_name}: x={x}(行),y={y}(列) → row={row_idx},col={col_idx} → idx={idx}")
 
                     if 0 <= idx < warehouse.capacity:
-                        if warehouse[idx] is None or isinstance(warehouse[idx], ResourceHolder):
+                        slot_key = None
+                        ordering = getattr(warehouse, "_ordering", {})
+                        sites = getattr(warehouse, "sites", [])
+                        if isinstance(ordering, dict) and idx < len(sites):
+                            site_at_idx = sites[idx]
+                            slot_key = next(
+                                (key for key, site in ordering.items() if site is site_at_idx),
+                                None,
+                            )
+
+                        current_resource = warehouse[idx]
+                        if current_resource is None or isinstance(current_resource, (ResourceHolder, str)):
+                            if isinstance(current_resource, str):
+                                logger.warning(
+                                    f"⚠️ 物料 {unique_name} 覆盖 {wh_name}[{idx}]"
+                                    f"{f'({slot_key})' if slot_key else ''} 的旧占位 occupied_by={current_resource!r}"
+                                )
                             # 物料尺寸已在放入warehouse前根据需要进行了交换
                             warehouse[idx] = plr_material
-                            logger.debug(f"✅ 物料 {unique_name} 放置到 {wh_name}[{idx}] (Bioyond坐标: x={loc.get('x')}, y={loc.get('y')})")
+                            logger.debug(
+                                f"✅ 物料 {unique_name} 放置到 {wh_name}[{idx}]"
+                                f"{f'({slot_key})' if slot_key else ''} "
+                                f"(Bioyond坐标: x={loc.get('x')}, y={loc.get('y')})"
+                            )
+                        else:
+                            parent = getattr(current_resource, "parent", None)
+                            current_repr = repr(current_resource)
+                            current_len = len(current_resource) if isinstance(current_resource, str) else None
+                            logger.warning(
+                                f"⚠️ 物料 {unique_name} 跳过放置到 {wh_name}[{idx}]"
+                                f"{f'({slot_key})' if slot_key else ''}：目标库位已有 "
+                                f"{type(current_resource).__name__}"
+                                f"(value={current_repr}, len={current_len})"
+                                f"(name={getattr(current_resource, 'name', None)}, "
+                                f"parent={getattr(parent, 'name', None)}, "
+                                f"uuid={getattr(current_resource, 'unilabos_uuid', None)})"
+                            )
                     else:
                         logger.warning(f"❌ 物料 {unique_name} 的索引 {idx} 超出仓库 {wh_name} 容量 {warehouse.capacity}")
                 else:

unilabos/utils/environment_check.py

@@ -47,10 +47,7 @@ def _has_uv() -> bool:
 
 def _install_command(installer: str, package: str, upgrade: bool, is_chinese: bool) -> List[str]:
     if installer == "uv":
-        # uv >= 0.5 默认要求虚拟环境，对 conda env 会报 "No virtual environment found"。
-        # 显式 --python sys.executable 让 uv 把当前解释器（conda/venv/system 都行）
-        # 视为目标环境，绕开 venv 检测。
-        cmd = ["uv", "pip", "install", "--python", sys.executable]
+        cmd = ["uv", "pip", "install"]
         if upgrade:
             cmd.append("--upgrade")
         cmd.append(package)
@@ -92,11 +89,7 @@ def _print_manual_git_install_hint(requirement: str) -> None:
         return
 
     repo_dir = _repo_dir_name(git_url)
-    install_cmd = (
-        f'uv pip install --python "{sys.executable}" -e .'
-        if _has_uv()
-        else f"{sys.executable} -m pip install -e ."
-    )
+    install_cmd = "uv pip install -e ." if _has_uv() else f"{sys.executable} -m pip install -e ."
     if _is_chinese_locale() and not _has_uv():
         install_cmd += " -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
 

unilabos/workflow/from_python_script.py

@@ -0,0 +1,241 @@
+import ast
+import json
+from typing import Dict, List, Any, Tuple, Optional
+
+from .common import WorkflowGraph, RegistryAdapter
+
+Json = Dict[str, Any]
+
+# ---------------- Converter ----------------
+
+class DeviceMethodConverter:
+    """
+    - 字段统一：resource_name（原 device_class）、template_name（原 action_key）
+    - params 单层；inputs 使用 'params.' 前缀
+    - SimpleGraph.add_workflow_node 负责变量连线与边
+    """
+    def __init__(self, device_registry: Optional[Dict[str, Any]] = None):
+        self.graph = WorkflowGraph()
+        self.variable_sources: Dict[str, Dict[str, Any]] = {}        # var -> {node_id, output_name}
+        self.instance_to_resource: Dict[str, Optional[str]] = {}     # 实例名 -> resource_name
+        self.node_id_counter: int = 0
+        self.registry = RegistryAdapter(device_registry or {})
+
+    # ---- helpers ----
+    def _new_node_id(self) -> int:
+        nid = self.node_id_counter
+        self.node_id_counter += 1
+        return nid
+
+    def _assign_targets(self, targets) -> List[str]:
+        names: List[str] = []
+        import ast
+        if isinstance(targets, ast.Tuple):
+            for elt in targets.elts:
+                if isinstance(elt, ast.Name):
+                    names.append(elt.id)
+        elif isinstance(targets, ast.Name):
+            names.append(targets.id)
+        return names
+
+    def _extract_device_instantiation(self, node) -> Optional[Tuple[str, str]]:
+        import ast
+        if not isinstance(node.value, ast.Call):
+            return None
+        callee = node.value.func
+        if isinstance(callee, ast.Name):
+            class_name = callee.id
+        elif isinstance(callee, ast.Attribute) and isinstance(callee.value, ast.Name):
+            class_name = callee.attr
+        else:
+            return None
+        if isinstance(node.targets[0], ast.Name):
+            instance = node.targets[0].id
+            return instance, class_name
+        return None
+
+    def _extract_call(self, call) -> Tuple[str, str, Dict[str, Any], str]:
+        import ast
+        owner_name, method_name, call_kind = "", "", "func"
+        if isinstance(call.func, ast.Attribute):
+            method_name = call.func.attr
+            if isinstance(call.func.value, ast.Name):
+                owner_name = call.func.value.id
+                call_kind = "instance" if owner_name in self.instance_to_resource else "class_or_module"
+            elif isinstance(call.func.value, ast.Attribute) and isinstance(call.func.value.value, ast.Name):
+                owner_name = call.func.value.attr
+                call_kind = "class_or_module"
+        elif isinstance(call.func, ast.Name):
+            method_name = call.func.id
+            call_kind = "func"
+
+        def pack(node):
+            if isinstance(node, ast.Name):
+                return {"type": "variable", "value": node.id}
+            if isinstance(node, ast.Constant):
+                return {"type": "constant", "value": node.value}
+            if isinstance(node, ast.Dict):
+                return {"type": "dict", "value": self._parse_dict(node)}
+            if isinstance(node, ast.List):
+                return {"type": "list", "value": self._parse_list(node)}
+            return {"type": "raw", "value": ast.unparse(node) if hasattr(ast, "unparse") else str(node)}
+
+        args: Dict[str, Any] = {}
+        pos: List[Any] = []
+        for a in call.args:
+            pos.append(pack(a))
+        for kw in call.keywords:
+            args[kw.arg] = pack(kw.value)
+        if pos:
+            args["_positional"] = pos
+        return owner_name, method_name, args, call_kind
+
+    def _parse_dict(self, node) -> Dict[str, Any]:
+        import ast
+        out: Dict[str, Any] = {}
+        for k, v in zip(node.keys, node.values):
+            if isinstance(k, ast.Constant):
+                key = str(k.value)
+                if isinstance(v, ast.Name):
+                    out[key] = f"var:{v.id}"
+                elif isinstance(v, ast.Constant):
+                    out[key] = v.value
+                elif isinstance(v, ast.Dict):
+                    out[key] = self._parse_dict(v)
+                elif isinstance(v, ast.List):
+                    out[key] = self._parse_list(v)
+        return out
+
+    def _parse_list(self, node) -> List[Any]:
+        import ast
+        out: List[Any] = []
+        for elt in node.elts:
+            if isinstance(elt, ast.Name):
+                out.append(f"var:{elt.id}")
+            elif isinstance(elt, ast.Constant):
+                out.append(elt.value)
+            elif isinstance(elt, ast.Dict):
+                out.append(self._parse_dict(elt))
+            elif isinstance(elt, ast.List):
+                out.append(self._parse_list(elt))
+        return out
+
+    def _normalize_var_tokens(self, x: Any) -> Any:
+        if isinstance(x, str) and x.startswith("var:"):
+            return {"__var__": x[4:]}
+        if isinstance(x, list):
+            return [self._normalize_var_tokens(i) for i in x]
+        if isinstance(x, dict):
+            return {k: self._normalize_var_tokens(v) for k, v in x.items()}
+        return x
+
+    def _make_params_payload(self, resource_name: Optional[str], template_name: str, call_args: Dict[str, Any]) -> Dict[str, Any]:
+        input_keys = self.registry.get_action_input_keys(resource_name, template_name) if resource_name else []
+        defaults = self.registry.get_action_goal_default(resource_name, template_name) if resource_name else {}
+        params: Dict[str, Any] = dict(defaults)
+
+        def unpack(p):
+            t, v = p.get("type"), p.get("value")
+            if t == "variable":
+                return {"__var__": v}
+            if t == "dict":
+                return self._normalize_var_tokens(v)
+            if t == "list":
+                return self._normalize_var_tokens(v)
+            return v
+
+        for k, p in call_args.items():
+            if k == "_positional":
+                continue
+            params[k] = unpack(p)
+
+        pos = call_args.get("_positional", [])
+        if pos:
+            if input_keys:
+                for i, p in enumerate(pos):
+                    if i >= len(input_keys):
+                        break
+                    name = input_keys[i]
+                    if name in params:
+                        continue
+                    params[name] = unpack(p)
+            else:
+                for i, p in enumerate(pos):
+                    params[f"arg_{i}"] = unpack(p)
+        return params
+
+    # ---- handlers ----
+    def _on_assign(self, stmt):
+        import ast
+        inst = self._extract_device_instantiation(stmt)
+        if inst:
+            instance, code_class = inst
+            resource_name = self.registry.resolve_resource_by_classname(code_class)
+            self.instance_to_resource[instance] = resource_name
+            return
+
+        if isinstance(stmt.value, ast.Call):
+            owner, method, call_args, kind = self._extract_call(stmt.value)
+            if kind == "instance":
+                device_key = owner
+                resource_name = self.instance_to_resource.get(owner)
+            else:
+                device_key = owner
+                resource_name = self.registry.resolve_resource_by_classname(owner)
+
+            module = self.registry.get_device_module(resource_name)
+            params = self._make_params_payload(resource_name, method, call_args)
+
+            nid = self._new_node_id()
+            self.graph.add_workflow_node(
+                nid,
+                device_key=device_key,
+                resource_name=resource_name,      # ✅
+                module=module,
+                template_name=method,             # ✅
+                params=params,
+                variable_sources=self.variable_sources,
+                add_ready_if_no_vars=True,
+                prev_node_id=(nid - 1) if nid > 0 else None,
+            )
+
+            out_vars = self._assign_targets(stmt.targets[0])
+            for var in out_vars:
+                self.variable_sources[var] = {"node_id": nid, "output_name": "result"}
+
+    def _on_expr(self, stmt):
+        import ast
+        if not isinstance(stmt.value, ast.Call):
+            return
+        owner, method, call_args, kind = self._extract_call(stmt.value)
+        if kind == "instance":
+            device_key = owner
+            resource_name = self.instance_to_resource.get(owner)
+        else:
+            device_key = owner
+            resource_name = self.registry.resolve_resource_by_classname(owner)
+
+        module = self.registry.get_device_module(resource_name)
+        params = self._make_params_payload(resource_name, method, call_args)
+
+        nid = self._new_node_id()
+        self.graph.add_workflow_node(
+            nid,
+            device_key=device_key,
+            resource_name=resource_name,      # ✅
+            module=module,
+            template_name=method,             # ✅
+            params=params,
+            variable_sources=self.variable_sources,
+            add_ready_if_no_vars=True,
+            prev_node_id=(nid - 1) if nid > 0 else None,
+        )
+
+    def convert(self, python_code: str):
+        tree = ast.parse(python_code)
+        for stmt in tree.body:
+            if isinstance(stmt, ast.Assign):
+                self._on_assign(stmt)
+            elif isinstance(stmt, ast.Expr):
+                self._on_expr(stmt)
+        return self

unilabos/workflow/from_xdl.py

@@ -0,0 +1,131 @@
+from typing import List, Any, Dict
+import xml.etree.ElementTree as ET
+
+
+def convert_to_type(val: str) -> Any:
+    """将字符串值转换为适当的数据类型"""
+    if val == "True":
+        return True
+    if val == "False":
+        return False
+    if val == "?":
+        return None
+    if val.endswith(" g"):
+        return float(val.split(" ")[0])
+    if val.endswith("mg"):
+        return float(val.split("mg")[0])
+    elif val.endswith("mmol"):
+        return float(val.split("mmol")[0]) / 1000
+    elif val.endswith("mol"):
+        return float(val.split("mol")[0])
+    elif val.endswith("ml"):
+        return float(val.split("ml")[0])
+    elif val.endswith("RPM"):
+        return float(val.split("RPM")[0])
+    elif val.endswith(" °C"):
+        return float(val.split(" ")[0])
+    elif val.endswith(" %"):
+        return float(val.split(" ")[0])
+    return val
+
+
+def flatten_xdl_procedure(procedure_elem: ET.Element) -> List[ET.Element]:
+    """展平嵌套的XDL程序结构"""
+    flattened_operations = []
+    TEMP_UNSUPPORTED_PROTOCOL = ["Purge", "Wait", "Stir", "ResetHandling"]
+
+    def extract_operations(element: ET.Element):
+        if element.tag not in ["Prep", "Reaction", "Workup", "Purification", "Procedure"]:
+            if element.tag not in TEMP_UNSUPPORTED_PROTOCOL:
+                flattened_operations.append(element)
+
+        for child in element:
+            extract_operations(child)
+
+    for child in procedure_elem:
+        extract_operations(child)
+
+    return flattened_operations
+
+
+def parse_xdl_content(xdl_content: str) -> tuple:
+    """解析XDL内容"""
+    try:
+        xdl_content_cleaned = "".join(c for c in xdl_content if c.isprintable())
+        root = ET.fromstring(xdl_content_cleaned)
+
+        synthesis_elem = root.find("Synthesis")
+        if synthesis_elem is None:
+            return None, None, None
+
+        # 解析硬件组件
+        hardware_elem = synthesis_elem.find("Hardware")
+        hardware = []
+        if hardware_elem is not None:
+            hardware = [{"id": c.get("id"), "type": c.get("type")} for c in hardware_elem.findall("Component")]
+
+        # 解析试剂
+        reagents_elem = synthesis_elem.find("Reagents")
+        reagents = []
+        if reagents_elem is not None:
+            reagents = [{"name": r.get("name"), "role": r.get("role", "")} for r in reagents_elem.findall("Reagent")]
+
+        # 解析程序
+        procedure_elem = synthesis_elem.find("Procedure")
+        if procedure_elem is None:
+            return None, None, None
+
+        flattened_operations = flatten_xdl_procedure(procedure_elem)
+        return hardware, reagents, flattened_operations
+
+    except ET.ParseError as e:
+        raise ValueError(f"Invalid XDL format: {e}")
+
+
+def convert_xdl_to_dict(xdl_content: str) -> Dict[str, Any]:
+    """
+    将XDL XML格式转换为标准的字典格式
+
+    Args:
+        xdl_content: XDL XML内容
+
+    Returns:
+        转换结果，包含步骤和器材信息
+    """
+    try:
+        hardware, reagents, flattened_operations = parse_xdl_content(xdl_content)
+        if hardware is None:
+            return {"error": "Failed to parse XDL content", "success": False}
+
+        # 将XDL元素转换为字典格式
+        steps_data = []
+        for elem in flattened_operations:
+            # 转换参数类型
+            parameters = {}
+            for key, val in elem.attrib.items():
+                converted_val = convert_to_type(val)
+                if converted_val is not None:
+                    parameters[key] = converted_val
+
+            step_dict = {
+                "operation": elem.tag,
+                "parameters": parameters,
+                "description": elem.get("purpose", f"Operation: {elem.tag}"),
+            }
+            steps_data.append(step_dict)
+
+        # 合并硬件和试剂为统一的labware_info格式
+        labware_data = []
+        labware_data.extend({"id": hw["id"], "type": "hardware", **hw} for hw in hardware)
+        labware_data.extend({"name": reagent["name"], "type": "reagent", **reagent} for reagent in reagents)
+
+        return {
+            "success": True,
+            "steps": steps_data,
+            "labware": labware_data,
+            "message": f"Successfully converted XDL to dict format. Found {len(steps_data)} steps and {len(labware_data)} labware items.",
+        }
+
+    except Exception as e:
+        error_msg = f"XDL conversion failed: {str(e)}"
+        return {"error": error_msg, "success": False}

unilabos_msgs/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>unilabos_msgs</name>
-  <version>0.11.2</version>
+  <version>0.11.1</version>
   <description>ROS2 Messages package for unilabos devices</description>
   <maintainer email="changjh@pku.edu.cn">Junhan Chang</maintainer>
   <maintainer email="18435084+Xuwznln@users.noreply.github.com">Xuwznln</maintainer>