feat: export core Hermes skills

2026-07-15 02:45:56 +00:00
parent a028b63eda
commit 54711fee2a
308 changed files with 41310 additions and 1 deletions
@@ -0,0 +1,65 @@
+# UWF Workflow Pitfalls for nantong-lease-audit
+
+**Last updated**: 2026-06-30
+
+## Pitfall 1: File Name Collision — Multiple Contracts per Campus
+
+The `nantong-lease-audit` workflow writes output to:
+```
+/tmp/nantong-lease-audit/{{ campus }}-row-data.json
+```
+
+When a campus has **multiple contracts** (e.g., 租赁 + 物业), running both contracts through the workflow causes the second to **overwrite** the first's JSON file.
+
+**Discovered**: 通州金鹰 — 租赁合同 wrote `通州金鹰-row-data.json`, then 物业合同 overwrote it.
+
+**Fix**: When running multiple contracts for the same campus:
+1. Run them sequentially (not in parallel) — OR —
+2. After each workflow completes, rename/copy the output before starting the next:
+   ```bash
+   # After lease contract workflow completes:
+   cp /tmp/nantong-lease-audit/通州金鹰-row-data.json \
+      /tmp/nantong-lease-audit/通州金鹰-租赁-row-data.json
+   # Then run property contract workflow (will overwrite 通州金鹰-row-data.json)
+   ```
+3. When building the xlsx, read both JSON files separately
+
+**Current workaround used**: Read the lease contract data from CAS step output (`uwf step show <hash>`) if the JSON was overwritten, then manually reconstruct the property contract data.
+
+## Pitfall 2: Workflow Prompt Variable Not Passed
+
+The classifier role's moderator instruction shows empty values:
+```
+分类合同。OCR文本路径：，校区：，原始文件名：
+```
+
+This happens when the `ocr_path`, `campus`, and `filename` variables are not properly interpolated from the thread start prompt. The classifier still works because the OCR path is in the task context, but the moderator prompt looks incomplete.
+
+**Root cause**: The thread start prompt uses Chinese colons `：` which may not match the YAML template variable syntax. Current workaround: the classifier reads the OCR path from the task context anyway.
+
+## Pitfall 3: Workflow v1 → v2 Hash Change
+
+When the workflow YAML is updated and re-registered:
+- Old hash: `7KZ5BWT12R5RJ` (v1, no format templates)
+- New hash: `C77579MQ9QPKE` (v2, with H/K/L format templates + reference loading)
+
+Threads started before the update continue using the old hash. Always verify which hash is active:
+```bash
+uwf workflow show nantong-lease-audit  # Shows current hash
+```
+
+## Pitfall 4: Background Exec Returns "Step 1 running"
+
+When using `uwf thread exec <id> --count 20 --background`, the foreground output may show only:
+```
+Step 1  classifier → running
+```
+
+This does NOT mean only step 1 ran. The background worker continues processing all steps. Check actual progress with:
+```bash
+uwf step list <thread-id>
+uwf thread show <thread-id>
+```
+
+Expected progression: classifier → template-diff → rule-analyzer → data-extractor → end.
+Total time: ~15-20 minutes for all 4 steps.