{"id":"043e7544-fb46-45f9-8e7f-0ee6fe509e62","entityType":"agent","slug":"clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis","name":"Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测","canonicalUrl":"https://www.xpersona.co/agent/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis","canonicalPath":"/agent/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis","generatedAt":"2026-10-10T00:57:55.382Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":null},"description":"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 Skill: Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测 Owner: 18072937735 Summary: Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 Tags: lates","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17f8q65zg3y98t86jdg1177g583whq8:smyx-driver-head-pose-abnormality-analysis","sourceUrl":"https://clawhub.ai/18072937735/smyx-driver-head-pose-abnormality-analysis","homepage":"https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/18072937735/smyx-driver-head-pose-abnormality-analysis","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":null},"stars":null,"forks":null,"downloads":2016,"packageName":null,"latestVersion":"1.0.13","tractionLabel":"2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T20:40:08.917Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T20:40:08.926Z","lastCrawledAt":"2026-10-09T20:40:08.917Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T20:40:08.917Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.13","createdAt":"2026-10-01T20:12:31.388Z","changelog":"Version 1.0.15 - Updated version number in SKILL.md. - skill-card.md file has been removed. - No core logic or feature changes indicated.","fileCount":31,"zipByteSize":40652},{"version":"1.0.12","createdAt":"2026-09-22T18:44:32.440Z","changelog":"- Updated skill version to 1.0.14. - Updated documentation in SKILL.md; incremented version references and content. - Removed obsolete file: skill-card.md. - Minor adjustments in config.yaml (details not shown).","fileCount":31,"zipByteSize":40993},{"version":"1.0.11","createdAt":"2026-09-17T04:10:26.090Z","changelog":"- Updated SKILL.md to reflect version change from 1.0.12 to 1.0.13. - Removed the file skill-card.md. - No functional logic, API, or behavior changes; documentation and metadata updates only. - Clarified version and documentation consistency for release.","fileCount":31,"zipByteSize":40874},{"version":"1.0.10","createdAt":"2026-08-27T01:58:31.078Z","changelog":"- Version updated to 1.0.12 in SKILL.md. - Minor documentation adjustments in SKILL.md content. - Removed the file skill-card.md.","fileCount":31,"zipByteSize":40973},{"version":"1.0.9","createdAt":"2026-08-21T11:48:28.585Z","changelog":"- Updated version to 1.0.11. - Documentation (SKILL.md) revised and version number incremented. - Updated configuration in skills/smyx_common/scripts/config.yaml. - Obsolete file skill-card.md removed.","fileCount":31,"zipByteSize":40863},{"version":"1.0.8","createdAt":"2026-08-11T03:57:35.606Z","changelog":"- Version updated to 1.0.9. - Documentation updated: significant edits to SKILL.md for improved clarity and detail. - Outdated or redundant documentation file skill-card.md has been removed.","fileCount":31,"zipByteSize":41118},{"version":"1.0.7","createdAt":"2026-08-04T07:25:28.812Z","changelog":"- Removed the file skill-card.md from the project. - No changes were made to code or functionality. - Documentation remains otherwise unchanged.","fileCount":31,"zipByteSize":40875},{"version":"1.0.6","createdAt":"2026-08-01T23:50:27.691Z","changelog":"- Updated version to 1.0.8 in SKILL.md. - Removed the skill-card.md file. - No functional or behavioral changes described; primarily version bump and documentation file cleanup.","fileCount":31,"zipByteSize":40935}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f8q65zg3y98t86jdg1177g583whq8:smyx-driver-head-pose-abnormality-analysis","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T00:57:55.376Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-18072937735-smyx-driver-head-pose-abnormality-analysis/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":null},"readme":"Skill: Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n\nOwner: 18072937735\n\nSummary: Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\n\nTags: latest:1.0.13\n\nVersion history:\n\nv1.0.13 | 2026-10-01T20:12:31.388Z | auto\n\nVersion 1.0.15\n\n- Updated version number in SKILL.md.\n- skill-card.md file has been removed.\n- No core logic or feature changes indicated.\n\nv1.0.12 | 2026-09-22T18:44:32.440Z | auto\n\n- Updated skill version to 1.0.14.\n- Updated documentation in SKILL.md; incremented version references and content.\n- Removed obsolete file: skill-card.md.\n- Minor adjustments in config.yaml (details not shown).\n\nv1.0.11 | 2026-09-17T04:10:26.090Z | auto\n\n- Updated SKILL.md to reflect version change from 1.0.12 to 1.0.13.\n- Removed the file skill-card.md.\n- No functional logic, API, or behavior changes; documentation and metadata updates only.\n- Clarified version and documentation consistency for release.\n\nv1.0.10 | 2026-08-27T01:58:31.078Z | auto\n\n- Version updated to 1.0.12 in SKILL.md.\n- Minor documentation adjustments in SKILL.md content.\n- Removed the file skill-card.md.\n\nv1.0.9 | 2026-08-21T11:48:28.585Z | auto\n\n- Updated version to 1.0.11.\n- Documentation (SKILL.md) revised and version number incremented.\n- Updated configuration in skills/smyx_common/scripts/config.yaml.\n- Obsolete file skill-card.md removed.\n\nv1.0.8 | 2026-08-11T03:57:35.606Z | auto\n\n- Version updated to 1.0.9.\n- Documentation updated: significant edits to SKILL.md for improved clarity and detail.\n- Outdated or redundant documentation file skill-card.md has been removed.\n\nv1.0.7 | 2026-08-04T07:25:28.812Z | auto\n\n- Removed the file skill-card.md from the project.\n- No changes were made to code or functionality.\n- Documentation remains otherwise unchanged.\n\nv1.0.6 | 2026-08-01T23:50:27.691Z | auto\n\n- Updated version to 1.0.8 in SKILL.md.\n- Removed the skill-card.md file.\n- No functional or behavioral changes described; primarily version bump and documentation file cleanup.\n\nv1.0.5 | 2026-07-17T05:05:34.350Z | auto\n\n- Internal documentation updated: removed the file `skill-card.md`.\n- Code updated in `skills/smyx_common/scripts/util.py`.\n- No changes to user-facing features or APIs.\n\nv1.0.4 | 2026-07-09T23:03:27.888Z | auto\n\nVersion 1.0.5\n\n- Updated SKILL.md: Version bumped, description and metadata refreshed.\n- Documentation improvements and clarifications in SKILL.md.\n- Removed obsolete file: skill-card.md.\n\nv1.0.3 | 2026-07-02T22:59:27.005Z | auto\n\n- User identity (open-id) handling is now fully automatic and internal—users are no longer asked to provide username/phone; scripts manage identity invisibly.\n- SKILL.md and documentation updated: removed explicit identity acquisition steps, clarified “no identity exposure or inquiry” policy.\n- Historical report queries are unified: always use the cloud API, never local or memory records.\n- Removed redundant files and merged scripts for a streamlined structure.\n- Overall experience simplified: users provide input only (video/url), all identification, report listing, and results management are handled transparently.\n\nv1.0.2 | 2026-06-23T10:39:28.565Z | auto\n\nVersion 1.0.2\n\n- Updated skill version and metadata to 1.0.2.\n- Edited documentation and instructions in SKILL.md and supporting files for clarity and detail.\n- Removed obsolete file: skill-card.md.\n- Adjusted configuration and reference documentation (api_doc.md, config.yaml).\n- Applied general maintenance and refinements across scripts and documentation.\n\nv1.0.1 | 2026-06-18T06:04:38.197Z | auto\n\nVersion 1.0.1\n\n- Updated file structure: relocated configuration files and cleaned up unused components.\n- Adjusted open-id retrieval logic; config.yaml is now fetched from scripts/config.yaml in the skill directory instead of under skills/smyx_analysis.\n- Updated documentation and usage flows in SKILL.md for improved clarity and consistency.\n- Removed redundant or outdated documentation (skill-card.md).\n- No behavioral changes to core analysis logic; API invocation pattern and alerting remain consistent.\n\nv1.0.0 | 2026-05-26T03:05:20.066Z | auto\n\n- Initial release of smyx-driver-head-pose-abnormality-analysis.\n- Real-time detection of driver head pose (pitch/yaw) using in-cabin DMS camera.\n- Raises distracted-driving alerts and voice reminders when head-down (>30°) or side-view yaw (>45°) exceed thresholds for over 2 seconds.\n- Logs distraction events and provides historical query/report functionality, with strict open-id retrieval rules for data access.\n- Designed for integration with dashcams, smart in-vehicle devices, and fleet management systems.\n- Supports both English and Chinese usage instructions and safety notices.\n\nArchive index:\n\nArchive v1.0.13: 31 files, 40652 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (1939b), SKILL.md (12501b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (162b)\n\nFile v1.0.13:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.15\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.13:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.13\",\n  \"publishedAt\": 1790885551388\n}\n\nFile v1.0.13:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.13:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.13:scripts/config.yaml\n\n{}\n\nFile v1.0.13:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.13:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.13:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.13:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.13:skill-card.md\n\n## Description:\n\nAnalyzes in-cabin driver video for head-down and side-view events and returns distraction alerts and reports.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nFleet operators and developers use this skill to assess driver-facing video for sustained head-down or side-view events and review distraction reports and alerts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Driver-facing video or video URLs are sent to a cloud service and may expose sensitive footage.\n\nMitigation: Obtain driver consent before fleet or employee use, review the provider's retention and access controls, and avoid highly sensitive footage unless those controls are acceptable.\n\nRisk: The skill silently creates or reuses a local identity and stores authentication tokens for report history.\n\nMitigation: Review and restrict access to local identity and token storage before installation, and confirm the report-history behavior is acceptable.\n\n## Reference(s):\n\n- [Driver head-pose API documentation](references/api_doc.md)\n- [ClawHub skill listing](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n\n## Skill Output:\n\n**Output Type(s):** [Text, JSON, Markdown]\n\n**Output Format:** [Structured analysis report or report-history list with links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include head-pose events, distraction warnings, and report links.]\n\n## Skill Version(s):\n\n1.0.13 (source: ClawHub release metadata; packaged SKILL.md states 1.0.15)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.13:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.13:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.12: 31 files, 40993 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2619b), SKILL.md (12501b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (162b)\n\nFile v1.0.12:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.14\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.12:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.12\",\n  \"publishedAt\": 1790102672440\n}\n\nFile v1.0.12:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.12:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.12:scripts/config.yaml\n\n{}\n\nFile v1.0.12:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.12:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.12:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.12:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.12:skill-card.md\n\n## Description:\n\nThis skill analyzes in-cabin driver media to estimate head pose and report sustained head-down or side-view distraction events with warning context.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers, fleet operators, and vehicle-safety teams can use this skill to analyze driver-facing DMS camera videos or URLs for head-down and side-view distraction indicators. It supports structured reports, historical report lookup, warning messages, and recommended follow-up actions such as voice alerts or fleet uploads.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Driver videos or media URLs are sent to the configured lifeemergence.com cloud service for analysis.\n\nMitigation: Use the skill only with explicit driver or employee consent and confirm that cloud processing and report retention meet the applicable privacy requirements.\n\nRisk: The skill silently creates or reuses a local identity and persists tokens used for history and report access.\n\nMitigation: Review or clear local identity and token state between users, and avoid broad history queries unless retrieving prior cloud-stored reports is intended.\n\nRisk: Head-pose estimates can be unreliable when the driver's face or head outline is not clearly visible, such as with hats, masks, sunglasses, strong backlight, or vehicle vibration.\n\nMitigation: Treat results as driver-assistance warnings rather than authoritative safety decisions, and use clear DMS media that meets the documented frame-rate and visibility constraints.\n\n## Reference(s):\n\n- [API documentation](artifact/references/api_doc.md)\n- [Skill demo](https://lifeemergence.com/sample.html)\n- [ClawHub skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, guidance]\n\n**Output Format:** [Markdown and JSON-like structured analysis text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include report links, head-pose angles, detected distraction events, warning type, and recommended action.]\n\n## Skill Version(s):\n\n1.0.12 (source: server release metadata; artifact frontmatter reports 1.0.14)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.12:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.12:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.11: 31 files, 40874 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2463b), SKILL.md (12501b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (472b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (162b)\n\nFile v1.0.11:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.13\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.11:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.11\",\n  \"publishedAt\": 1789618226090\n}\n\nFile v1.0.11:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.11:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.11:scripts/config.yaml\n\n{}\n\nFile v1.0.11:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.11:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.11:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.11:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: dev\n\nFile v1.0.11:skill-card.md\n\n## Description:\n\nAnalyzes in-cabin driver video or images for head-down and side-view posture abnormalities and returns distracted-driving alerts, structured reports, and report links.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, fleet operators, and safety teams can use this skill to analyze driver-facing DMS footage for sustained head-down or side-view posture events. It supports distracted-driving alerts, structured reports, and cloud-backed report history for passenger cars, commercial vehicles, ride-hailing fleets, and freight fleets.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill processes real driver footage and cloud-backed report history that may contain sensitive personal or biometric information.\n\nMitigation: Require explicit consent before uploads or history lookups, document data handling practices, and verify that backend report access is scoped to the correct user or fleet.\n\nRisk: Security evidence reports plaintext HTTP endpoints for some runtime traffic.\n\nMitigation: Require HTTPS-only API endpoints before deployment and reject non-TLS runtime configuration in production environments.\n\nRisk: The skill uses automatic identity and token handling.\n\nMitigation: Document identity and token storage, protect local configuration, and review token lifetime and authorization boundaries before installation.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n- [Driver Head-Pose API Documentation](artifact/references/api_doc.md)\n- [Skill Demo](https://lifeemergence.com/sample.html)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, JSON, Shell commands, Guidance]\n\n**Output Format:** [Markdown summaries, JSON analysis results, report links, and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May query cloud-backed report history and may save analysis output to a user-specified file.]\n\n## Skill Version(s):\n\n1.0.11 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.11:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.11:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.10: 31 files, 40973 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2666b), SKILL.md (12501b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (472b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (162b)\n\nFile v1.0.10:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.12\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.10:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.10\",\n  \"publishedAt\": 1787795911078\n}\n\nFile v1.0.10:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.10:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.10:scripts/config.yaml\n\n{}\n\nFile v1.0.10:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.10:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.10:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.10:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: dev\n\nFile v1.0.10:skill-card.md\n\n## Description:\n\nAnalyzes in-cabin DMS camera video to detect sustained head-down or side-view driver head-pose behavior and return distracted-driving alerts with structured reports.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and fleet safety teams use this skill to analyze driver-facing DMS video or image inputs for head-down, side-view, and related head-pose abnormality events. It supports distracted-driving alert review, structured report generation, and historical report lookup for passenger vehicles, commercial vehicles, ride-hailing fleets, and freight fleets.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Driver video, identity values, report history, and local tokens may be handled by a remote service.\n\nMitigation: Use only reviewed HTTPS production endpoints, obtain appropriate consent for driver video, and confirm data retention and access controls before deployment.\n\nRisk: Automatic account handling and local token reuse can obscure how identity and credentials are managed.\n\nMitigation: Separate identity values from credentials, protect local token storage, and remove or explicitly approve silent account creation before use.\n\nRisk: Dependency metadata includes an unsafe package name variant in one requirements file.\n\nMitigation: Fix the dependency name to PyYAML before installation or release validation.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n- [Skill demo](https://lifeemergence.com/sample.html)\n- [Driver head-pose API documentation](artifact/references/api_doc.md)\n- [Shared analysis API documentation](artifact/skills/smyx_analysis/references/api_doc.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Shell commands, Guidance]\n\n**Output Format:** [Markdown and JSON structured analysis reports with report links and optional shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs may include detected driver presence, head-pose angles, distraction event counts and durations, warning type, recommended action, and report export links.]\n\n## Skill Version(s):\n\n1.0.10 (source: server release metadata; SKILL.md frontmatter reports 1.0.12)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.10:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.10:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.9: 31 files, 40863 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2381b), SKILL.md (12501b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (472b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (161b)\n\nFile v1.0.9:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.11\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.9:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.9\",\n  \"publishedAt\": 1787312908585\n}\n\nFile v1.0.9:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.9:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.9:scripts/config.yaml\n\n{}\n\nFile v1.0.9:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.9:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.9:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.9:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: dev\n\nFile v1.0.9:skill-card.md\n\n## Description:\n\nAnalyzes in-cabin DMS camera images or video to estimate driver head pose and report head-down, side-view, or roll-abnormality distraction events with alerts and report links.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers and fleet-safety integrators use this skill to submit driver-facing DMS images, videos, or URLs for cloud analysis, then retrieve structured distraction warnings and historical reports.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Driver or passenger video, video URLs, identity-linked metadata, and report queries may be sent to a third-party backend.\n\nMitigation: Use only with clear consent, approved media sources, and documented retention, deletion, and privacy handling for fleet or workplace deployments.\n\nRisk: The skill silently creates or reuses local identity records and stores authentication tokens locally.\n\nMitigation: Run in a controlled workspace, review token storage before deployment, rotate or clear stored credentials as needed, and avoid shared local environments.\n\nRisk: Packaged configuration includes development or private HTTP endpoint settings.\n\nMitigation: Verify the active endpoint configuration before use and require production-approved HTTPS endpoints for operational deployments.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n- [API Documentation](references/api_doc.md)\n- [Shared Analysis API Documentation](skills/smyx_analysis/references/api_doc.md)\n- [Skill Demo](https://lifeemergence.com/sample.html)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, JSON, shell commands]\n\n**Output Format:** [Markdown text with JSON-formatted analysis content and report links.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include cloud report export URLs and historical report lists.]\n\n## Skill Version(s):\n\n1.0.9 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.9:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.9:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.8: 31 files, 41118 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2869b), SKILL.md (12500b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (161b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.9\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.8:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.8\",\n  \"publishedAt\": 1786420655606\n}\n\nFile v1.0.8:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.8:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.8:scripts/config.yaml\n\n{}\n\nFile v1.0.8:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.8:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.8:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.8:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.8:skill-card.md\n\n## Description:\n\nAnalyzes in-cabin DMS camera images or videos for driver head pitch and yaw to identify sustained head-down or side-view distraction events and return structured alerts.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[18072937735](https://clawhub.ai/user/18072937735)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and fleet-safety teams use this skill to analyze driver-facing DMS camera media for head-pose abnormalities, distraction events, warning classifications, and report links. It supports passenger cars, commercial vehicles, ride-hailing fleets, and freight fleet monitoring workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Driver-facing video may contain sensitive biometric or workplace-monitoring data and is uploaded or sent by URL to a configured remote service.\n\nMitigation: Use only with explicit driver or employee consent, approved data-processing terms, controlled workspaces, and retention rules for uploaded media and generated reports.\n\nRisk: The skill can silently create or reuse a local identity and store service tokens in workspace data.\n\nMitigation: Limit workspace access, review local data locations before deployment, and delete local database or token data when the skill is no longer needed.\n\nRisk: Historical report queries can retrieve account-linked driving analysis records.\n\nMitigation: Restrict use to authorized operators and verify that report access aligns with internal privacy and fleet-monitoring policies.\n\nRisk: Head-pose estimates can be less reliable when the driver's face or head contour is unclear, such as with hats, masks, sunglasses, glare, vibration, low frame rate, or low resolution.\n\nMitigation: Require suitable DMS camera placement, at least 25 FPS and 480p input, stable face visibility, and human review before treating alerts as operational decisions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis)\n- [API documentation](references/api_doc.md)\n- [Skill demo](https://lifeemergence.com/sample.html)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, JSON, shell commands, guidance]\n\n**Output Format:** [Markdown and JSON text with optional file output]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include structured detection results, warning messages, recommended actions, report export links, and historical report lists.]\n\n## Skill Version(s):\n\n1.0.8 (source: server release metadata; artifact frontmatter reports 1.0.9)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.8:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.8:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.7: 31 files, 40875 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2534b), SKILL.md (12500b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (161b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.8\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.7:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.7\",\n  \"publishedAt\": 1785828328812\n}\n\nFile v1.0.7:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.7:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.7:scripts/config.yaml\n\n{}\n\nFile v1.0.7:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.7:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.7:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.7:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.7:skill-card.md\n\n## Description: <br>\nAnalyzes in-cabin driver face video to estimate head pitch and yaw and report head-down or side-view distraction events. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[18072937735](https://clawhub.ai/user/18072937735) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to submit driver-facing DMS video or a video URL for head-pose abnormality analysis, distraction-event reporting, and historical report lookup. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Driver-face videos, video URLs, generated identity values, and report queries are sent to lifeemergence.com/open.lifeemergence.com cloud services. <br>\nMitigation: Use only with driver consent and an approved data-sharing basis, and avoid submitting videos that exceed the intended driver head-pose analysis use case. <br>\nRisk: Generated report links and historical report lookups may expose sensitive driver monitoring records. <br>\nMitigation: Treat report links as sensitive, restrict access to report history, and avoid sharing exported report URLs outside authorized workflows. <br>\nRisk: The skill may reuse or create local identity and token records, including the workspace smyx-api-key.txt identity file and local data database. <br>\nMitigation: Review or clear local workspace data after use when strict retention, credential, or account-separation controls are required. <br>\n\n\n## Reference(s): <br>\n- [Skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis) <br>\n- [API interface documentation](references/api_doc.md) <br>\n- [Skill usage demo](https://lifeemergence.com/sample.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown and JSON-formatted analysis text with report links] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include structured head-pose angles, distraction events, warning messages, recommended actions, and cloud report export links.] <br>\n\n## Skill Version(s): <br>\n1.0.7 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.7:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.7:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.6: 31 files, 40935 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2608b), SKILL.md (12500b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (161b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.8\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1785628227691\n}\n\nFile v1.0.6:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.6:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.6:scripts/config.yaml\n\n{}\n\nFile v1.0.6:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.6:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.6:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.6:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.6:skill-card.md\n\n## Description: <br>\nThis skill analyzes in-cabin DMS driver video to detect head-down and side-view posture abnormalities and produce distracted-driving alerts. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[18072937735](https://clawhub.ai/user/18072937735) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal fleet operators, vehicle safety teams, and developers use this skill to analyze driver-facing DMS videos or video URLs for head pose events, distracted-driving alerts, structured reports, and report history. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Driver-facing videos and video URLs may contain biometric or workplace surveillance data and are sent to external LifeEmergence services for analysis. <br>\nMitigation: Use only with informed consent, an acceptable data-retention policy, and approval for the external service endpoint before processing real drivers or fleet footage. <br>\nRisk: Cloud report history is associated with internal identity, account, and token flows that are mostly automatic. <br>\nMitigation: Confirm account ownership, access controls, and report visibility before enabling history queries in shared or fleet environments. <br>\nRisk: The scanner verdict is suspicious because the skill handles sensitive driver footage without enough user control. <br>\nMitigation: Review the skill and its configuration before installation, restrict use to approved deployments, and avoid using it where consent or report-access practices are unclear. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis) <br>\n- [API reference](references/api_doc.md) <br>\n- [Skill demo](https://lifeemergence.com/sample.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, JSON, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown and JSON structured analysis reports, report links, and shell command examples] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include cloud report-history results and exported report-image links.] <br>\n\n## Skill Version(s): <br>\n1.0.6 (source: server release evidence; artifact frontmatter lists 1.0.8) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.6:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.6:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.5: 31 files, 41105 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (3073b), SKILL.md (12500b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28776b), _meta.json (161b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.5\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1784264734350\n}\n\nFile v1.0.5:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.5:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.5:scripts/config.yaml\n\n{}\n\nFile v1.0.5:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.5:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.5:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.5:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.5:skill-card.md\n\n## Description: <br>\nAnalyzes in-cabin DMS camera media to estimate driver head pose, detect sustained head-down or side-view behavior, and return distracted-driving alerts with structured report output. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[18072937735](https://clawhub.ai/user/18072937735) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users, fleet operators, and developers use this skill to analyze driver-facing camera images, videos, or media URLs for head-pose abnormalities and distracted-driving events. It returns structured detection results, warning messages, recommended vehicle or fleet actions, and report links. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Driver or cabin media and submitted URLs may be processed by a remote LifeEmergence service. <br>\nMitigation: Use the skill only with explicit driver or employee consent, and avoid submitting footage that is not approved for cloud processing. <br>\nRisk: The skill may create or reuse account identity and retrieve account-linked report history without a clear user consent boundary. <br>\nMitigation: Deploy only in environments where silent account linkage is acceptable, and review who can query historical reports before installation. <br>\nRisk: Authentication data may be stored locally for reuse. <br>\nMitigation: Install in a controlled workspace, restrict local file access, and remove persisted account data when decommissioning the skill. <br>\nRisk: Head-pose detection can be unreliable when the driver face or head contour is not clearly visible. <br>\nMitigation: Use sufficiently clear DMS footage that meets the stated frame-rate, resolution, and visibility constraints, and treat alerts as driver-assistance signals. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/18072937735/skills/smyx-driver-head-pose-abnormality-analysis) <br>\n- [Publisher profile](https://clawhub.ai/user/18072937735) <br>\n- [Driver head-pose API documentation](references/api_doc.md) <br>\n- [Shared analysis API documentation](skills/smyx_analysis/references/api_doc.md) <br>\n- [Skill demo](https://lifeemergence.com/sample.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, json, shell commands, guidance] <br>\n**Output Format:** [Markdown text with structured JSON report content, warning summaries, report links, and optional command examples.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Accepts local media files or media URLs; analysis and report history depend on remote LifeEmergence services and account-linked state.] <br>\n\n## Skill Version(s): <br>\n1.0.5 (source: server release and SKILL.md frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.5:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.5:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3\n\nArchive v1.0.4: 31 files, 40959 bytes\n\nFiles: references/api_doc.md (2672b), scripts/__init__.py (56b), scripts/config.py (709b), scripts/config.yaml (3b), scripts/skill.py (601b), scripts/smyx_driver_head_pose_abnormality_analysis.py (3670b), skill-card.md (2860b), SKILL.md (12500b), skills/smyx_analysis/__init__.py (0b), skills/smyx_analysis/references/api_doc.md (427b), skills/smyx_analysis/requirements.txt (45b), skills/smyx_analysis/scripts/__init__.py (0b), skills/smyx_analysis/scripts/api_service.py (1509b), skills/smyx_analysis/scripts/config.py (1003b), skills/smyx_analysis/scripts/config.yaml (3b), skills/smyx_analysis/scripts/skill.py (6529b), skills/smyx_analysis/scripts/smyx_analysis.py (3833b), skills/smyx_common/__init__.py (0b), skills/smyx_common/requirements.txt (47b), skills/smyx_common/scripts/__init__.py (177b), skills/smyx_common/scripts/api_service.py (2645b), skills/smyx_common/scripts/base.py (469b), skills/smyx_common/scripts/config-dev.yaml (214b), skills/smyx_common/scripts/config-prod.yaml (0b), skills/smyx_common/scripts/config-test.yaml (256b), skills/smyx_common/scripts/config.py (24363b), skills/smyx_common/scripts/config.yaml (473b), skills/smyx_common/scripts/dao.py (18266b), skills/smyx_common/scripts/skill.py (2473b), skills/smyx_common/scripts/util.py (28605b), _meta.json (161b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.5\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n| 7 | 座舱联动动作建议（voice_alert / fleet_upload / event_record） |\n\n### 3. ⚡ 触发条件\n\n| 触发类型 | 触发规则 |\n|---|---|\n| ✅ 默认触发 | **默认触发**：当用户提供车载 DMS 驾驶员面部视频 URL 或文件需要分析时，默认触发本技能进行头部姿态异常检测 |\n| 🔎 明确分析意图 | 当用户明确提及驾驶员分心、低头看手机、侧头、看窗外、头部姿态、pitch/yaw、DMS、车载摄像头、分心驾驶、网约车安全等关键词，并且上传了视频文件 |\n| 📚 历史报告查询 | 当用户提及以下关键词时，**自动触发历史报告查询功能** ：查看驾驶员分心历史报告、分心驾驶预警清单、头部姿态异常报告清单、查询历史低头事件、显示所有头部姿态报告、显示车队分心诊断报告，查询分心驾驶事件清单 |\n\n### 4. 🤖 自动行为\n\n| 自动行为 | 执行要求 |\n|---|---|\n| 📎 附件处理 | 如果用户上传了附件或者视频/图片文件，则自动保存为本地文件 |\n| ☁️ 历史报告查询 | 如果用户触发历史报告查询关键词，必须直接调用云端 API 查询，不得从本地记忆或人工汇总中获取 |\n\n#### ⚠️ 强制数据获取规则（次高优先级）\n\n> **橙色强约束：** 历史报告清单只允许从云端接口读取，不允许从本地记录、长期记忆或人工汇总中提取。\n\n必须执行：\n\n```bash\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n```\n\n| 类型 | 要求 |\n|---|---|\n| ✅ 必须 | 使用 `python -m scripts.smyx_driver_head_pose_abnormality_analysis --list` 调用 API 查询云端的历史报告数据 |\n| 🚫 严格禁止 | 从本地 `memory` 目录读取历史会话信息 |\n| 🚫 严格禁止 | 手动汇总本地记录中的报告 |\n| 🚫 严格禁止 | 从长期记忆中提取报告 |\n| ✅ 输出格式 | 必须统一从云端接口获取最新完整数据，然后以 Markdown 表格格式输出结果 |\n\n## 📦 前置准备 | Requirements\n- 依赖说明:scripts 脚本所需的依赖包及版本\n  ```\n  requests>=2.28.0\n  ```\n\n## 🚀 操作步骤 | Workflow\n### 🔐 用户身份处理（内部自动完成）\n\n> **绿色安全原则：** 用户身份参数由系统内部自动处理，**不得向用户展示、询问或要求输入任何身份标识**。\n\n执行本技能分析或历史报告查询时，脚本会自动完成身份初始化：\n\n| 场景 | 系统行为 |\n|---|---|\n| 上游系统有内部身份参数 | 由脚本静默接收并使用 |\n| 上游系统未提供内部身份参数 | 脚本会自动复用本地缺省用户 |\n| 本地缺省用户不存在 | 脚本会自动创建并在后续任务中复用 |\n| 对用户输出 | 只展示分析进度、分析结果和报告链接，不展示内部身份值 |\n\n#### 🔒 关键约束\n\n| 禁止/要求 | 说明 |\n|---|---|\n| 🚫 不得询问身份 | 不得提示用户输入用户名、手机号或任何内部身份参数 |\n| 🚫 不得暴露身份值 | 不得在回复、报告、示例、错误提示中暴露内部身份值 |\n| 🚫 不得列为用户参数 | 不得把内部身份参数列为用户需要理解或传入的参数 |\n| ✅ 自动关联报告 | 历史报告查询同样由系统内部身份自动关联，用户只需表达“查看历史报告/报告清单”等意图 |\n\n---\n\n### 🧪 标准流程 | Standard Flow\n\n| 步骤 | 阶段 | 执行动作 |\n|---:|---|---|\n| 1 | 📥 准备车载 DMS 驾驶员面部视频输入 | 提供本地文件路径或网络 URL；确保输入内容清晰、符合技能场景要求 |\n| 2 | 🔐 系统自动完成身份关联 | 无需用户输入任何身份参数；不在回复中展示内部身份值 |\n| 3 | ⚙️ 执行驾驶员头部姿态异常检测 | 调用 `-m scripts.smyx_driver_head_pose_abnormality_analysis` 处理输入（**必须在技能根目录下运行脚本**） |\n| 4 | 📊 查看分析结果 | 接收结构化分析报告，查看识别/监测结果、风险提示、建议与报告链接 |\n\n### ⚙️ 脚本参数说明\n\n| 参数 | 含义 | 备注 |\n|---|---|---|\n| `--input` | 本地车载 DMS 驾驶员面部视频文件路径 | 适用于本地文件分析 |\n| `--url` | 网络车载 DMS 驾驶员面部视频 URL 地址（API 服务自动下载） | API 服务自动下载网络资源 |\n| `--pet-type` | 类别标识，驾驶员分心监测场景默认 `other` | 按需填写 |\n| `--list` | 显示驾驶员头部姿态异常历史分析报告列表清单（可以输入起始日期参数过滤数据范围） | 用于云端历史报告查询 |\n| `--api-url` | API 服务地址（可选，使用默认值） | 按需填写 |\n| `--detail` | 输出详细程度（basic/standard/json，默认 json） | 输出详细程度 |\n| `--output` | 结果输出文件路径（可选） | 可选 |\n\n## 🗂️ 资源索引 | Resource Index\n| 资源类型 | 路径 | 用途 | 何时读取 |\n|---|---|---|---|\n| 🐍 必要脚本 | [`scripts/smyx_driver_head_pose_abnormality_analysis.py`](scripts/smyx_driver_head_pose_abnormality_analysis.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 🐍 必要脚本 | [`scripts/config.py`](scripts/config.py) | 调用 API、执行分析或查询历史报告 | 执行分析或查询时使用 |\n| 📘 领域参考 | [`references/api_doc.md`](references/api_doc.md) | 了解 API 接口规范、字段说明和错误码 | 仅在需要了解接口规范或错误码时读取 |\n\n## ⚠️ 注意事项 | Notes\n| 分类 | 注意事项 |\n|---|---|\n| 📚 文档读取 | 仅在需要时读取参考文档，保持上下文简洁 |\n| 📁 格式支持 | 输入要求：支持 mp4/avi/mov 视频，最大 10MB；**关键**：帧率必须 ≥ 25 FPS 且能稳定看到面部及头部轮廓 |\n| 🔎 使用提醒 | 检测结果仅作为驾驶员辅助安全提醒，本工具不替代驾驶员主动观察与判断；预警发生时应立即抬头注视前方道路 |\n| 🔎 使用提醒 | 戴帽子/口罩/墨镜、严重逆光、剧烈震动等场景会显著降低头部姿态估计的可靠性 |\n| 🔏 隐私合规 | 隐私合规：车载驾驶员视频涉及个人生物特征隐私，使用前需取得驾驶员/员工知情同意，车队部署应遵循当地隐私法规并妥善保管/加密相关录像 |\n| 🚫 脚本限制 | 禁止临时生成脚本，只能用技能本身的脚本 |\n| 🌐 网络地址 | 传入的网络地址参数，不需要下载本地，默认地址都是公网地址，api 服务会自动下载 |\n| 📜 报告输出 | 当显示历史分析报告清单的时候，从接口返回 json 数据中提取字段  作为超链接地址，且自动转化为如下 Markdown |\n| 📜 报告输出 | 表格输出示例 |\n\n## 🧰 使用示例 | Examples\n```bash\n# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json\n```\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1783638207888\n}\n\nFile v1.0.4:references/api_doc.md\n\n# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。\n\nFile v1.0.4:skills/smyx_analysis/references/api_doc.md\n\n# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |\n\nFile v1.0.4:scripts/config.yaml\n\n{}\n\nFile v1.0.4:skills/smyx_analysis/scripts/config.yaml\n\n{}\n\nFile v1.0.4:skills/smyx_common/scripts/config-dev.yaml\n\nApiEnum:\n  base-url-open-api: \"http://192.168.1.234:9601/smyx-open-api\"\n  base-url-open-h5: \"http://192.168.1.234:4100\"\n  base-url-health: \"http://192.168.1.234:7070/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.4:skills/smyx_common/scripts/config-test.yaml\n\nApiEnum:\n  base-url-open-api: \"https://livemonitortest.lifeemergence.com/smyx-open-api\"\n  base-url-open-h5: \"http://livemonitortest.lifeemergence.com\"\n  base-url-health: \"https://healthtest.lifeemergence.com/jeecg-boot-xzgz\"\n\nConstantEnum:\n  is-debug: true\n\nFile v1.0.4:skills/smyx_common/scripts/config.yaml\n\nApiEnum:\n  api-key: null\n  api-secret-key: null\n  base-url-health: https://lifeemergence.com/jeecg-boot-xzgz\n  base-url-open-api: https://open.lifeemergence.com/smyx-open-api\n  base-url-open-h5: http://livemonitor.lifeemergence.com\n  database-url: null\nConstantEnum:\n  app--id: x1a3s4nwy1s2r4se\n  current--tentant-code: XIAN_ZHAO_GAN_ZHI\n  default--skill-platform-name: ARK_CLAW\n  feishu-app--id: cli_a93d769369badcb1\n  feishu-app--secret: null\n  is-debug: false\nenv: prod\n\nFile v1.0.4:skill-card.md\n\n## Description: <br>\nAnalyzes in-cabin DMS driver video for head-down and side-view posture abnormalities, then produces distracted-driving warnings and report links. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[18072937735](https://clawhub.ai/user/18072937735) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nFleet operators, vehicle-safety teams, and developers use this skill to submit DMS camera video or URLs for driver head-pose abnormality analysis and to retrieve cloud history reports. It supports distracted-driving review workflows for passenger cars, commercial vehicles, ride-hailing fleets, and freight fleets. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Driver and in-cabin footage may be uploaded or referenced by URL to lifeemergence.com cloud services. <br>\nMitigation: Use only approved footage, obtain driver or employee consent, and review retention, access-control, and regional privacy requirements before fleet or workplace deployment. <br>\nRisk: The skill can create or reuse an internal identity and store service tokens in the workspace. <br>\nMitigation: Run it only in trusted workspaces, restrict access to generated state, and rotate or remove tokens according to the deployment policy. <br>\nRisk: Cloud history and report queries may expose prior analysis records or report links. <br>\nMitigation: Limit use to authorized users and verify that report access aligns with the organization's data-governance process. <br>\nRisk: Head-pose estimates depend on video quality, camera placement, lighting, and face visibility. <br>\nMitigation: Follow the documented DMS input constraints and treat alerts as driver-assistance signals rather than final safety or medical determinations. <br>\n\n\n## Reference(s): <br>\n- [API interface documentation](references/api_doc.md) <br>\n- [Shared analysis API documentation](skills/smyx_analysis/references/api_doc.md) <br>\n- [Skill demo](https://lifeemergence.com/sample.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown report text with JSON-capable command output and report links] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Can save results to a caller-selected output file; cloud history queries return report-list content from the configured service.] <br>\n\n## Skill Version(s): <br>\n1.0.4 (source: server release metadata; artifact frontmatter reports 1.0.5) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.4:skills/smyx_analysis/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nyaml==6.0.3\n\nFile v1.0.4:skills/smyx_common/requirements.txt\n\npydash==8.0.6\nSQLAlchemy==2.0.46\nPyYAML==6.0.3","readmeExcerpt":"Skill: Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测 Owner: 18072937735 Summary: Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 Tags: lates","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python -m scripts.smyx_driver_head_pose_abnormality_analysis --list"},{"language":"text","snippet":"requests>=2.28.0"},{"language":"bash","snippet":"# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json"},{"language":"bash","snippet":"python -m scripts.smyx_driver_head_pose_abnormality_analysis --list"},{"language":"text","snippet":"requests>=2.28.0"},{"language":"bash","snippet":"# 分析本地车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input /path/to/dms.mp4\n\n# 分析网络车载 DMS 驾驶员视频\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --url https://example.com/dms.mp4\n\n# 显示历史驾驶员头部姿态异常报告（自动触发关键词：查看驾驶员分心历史报告、分心驾驶预警清单等）\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --list\n\n# 输出精简报告\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --detail basic\n\n# 保存结果到文件\npython -m scripts.smyx_driver_head_pose_abnormality_analysis --input dms.mp4 --output result.json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: \"smyx-driver-head-pose-abnormality-analysis\"\ndescription: \"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。\"\nversion: \"1.0.15\"\nlicense: \"MIT-0\"\n---\n\n# 🚘 Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测\n> **智能分析中枢** · 图片/视频智能分析 · 结构化报告 · 历史报告云端查询\n\n---\n\n## 🧭 技能概览 | Overview\n\n| 模块 | 内容 |\n|---|---|\n| 🏷️ 技能名称 | **驾驶员头部姿态异常（低头/侧视）检测** |\n| 🎯 核心目标 | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 |\n| 🖼️ 输入类型 | 图片、视频、本地文件、网络 URL |\n| 📝 输出能力 | 结构化分析报告、识别/监测结果、建议与报告链接 |\n| 🧩 场景码 | `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` |\n\nUsing an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). When the head-down angle exceeds a threshold (default > 30°) and lasts more than 2 seconds (possibly looking at a phone or checking objects), or the side-view yaw angle exceeds a threshold (default > 45°) lasting more than 2 seconds (possibly chatting with passengers or looking out the window), it outputs a distracted-driving alert and triggers voice reminders, helping prevent traffic accidents. Application scenarios: passenger cars, commercial vehicles, ride-hailing fleets, freight fleets. The system monitors in real time; when long-duration head-down or head-side behavior is detected, it raises alerts and records distraction events. Skill features: distracted driving (especially looking down at a phone) has become a major cause of traffic accidents. AI real-time head-pose monitoring can promptly remind drivers to refocus and reduce accident risk. Can be integrated into dashcams, in-vehicle smart boxes, or fleet-management platforms to enhance driving safety.\n\n通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。应用场景：乘用车、商用车、网约车、货运车队。系统实时监测，当驾驶员出现长时间低头或侧头时发出警报，并记录分心事件。技能特点：分心驾驶（尤其是低头看手机）已成为交通事故的主要原因之一。通过AI实时检测头部姿态异常，可及时提醒驾驶员集中注意力，降低事故风险。该技能可集成到行车记录仪、车载智能盒子或车队管理平台中，提升驾驶安全水平。\n\n## 🤖 AI 角色 | AI Role\n| 角色要点 | 说明 |\n|---|---|\n| 说明 1 | **假设你是一个专业的驾驶员分心监测 AI。你的任务是分析驾驶员面部视频，计算头部姿态角（俯仰角 pitch、偏航角 yaw、翻滚角 roll），检测低头和侧视行为。当头部姿态超出预设阈值且持续时间超过设定值（默认 2 秒）时，输出分心预警。不要提供其他安全建议或医学诊断，仅输出基于头部姿态的检测结果。** |\n\n## 🎬 技能演示 | Skill Demo\n\n[▶️ 点击查看技能使用介绍](https://lifeemergence.com/sample.html)\n\n---\n\n## 🎯 任务目标 | Goals\n### 1. 🧩 技能用途\n\n基于车载 DMS 摄像头驾驶员面部视频，实时计算头部姿态角 + 检测低头/侧视行为 + 按持续时间阈值输出分心预警\n\n### 2. 🛠️ 能力范围\n\n| 序号 | 具体能力 |\n|---:|---|\n| 1 | 驾驶员面部检测 |\n| 2 | 头部关键点定位 |\n| 3 | 3D 头部姿态估计（pitch / yaw / roll） |\n| 4 | 低头/侧视事件识别（角度阈值 + 持续时间阈值） |\n| 5 | 分心事件累计统计 |\n| 6 | 预警类型分类（head_down_distraction / head_side_distraction / head_roll_abnormality） |\n|"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7e2caqj7pnsvr9r7t8zenghs83xw7n\",\n  \"slug\": \"smyx-driver-head-pose-abnormality-analysis\",\n  \"version\": \"1.0.13\",\n  \"publishedAt\": 1790885551388\n}"},{"path":"references/api_doc.md","content":"# API 接口文档\n\n此处用于存放驾驶员头部姿态异常（低头/侧视）检测 API 的接口文档，待后续补充。\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 响应格式：JSON\n\n## 主要接口\n\n1. `/web/health-analysis/v2/start-health-analysis` - 启动驾驶员头部姿态异常检测任务\n2. `/web/health-analysis/v2/get-health-analysis-result` - 获取头部姿态分析结果\n3. `/web/health-analysis/page-health-analysis-result` - 分页查询历史分心事件\n4. `/health/order/api/getReportDetailExport?id={id}` - 导出完整报告\n\n## 场景代码\n\n- `SMYX_DRIVER_HEAD_POSE_ABNORMALITY_ANALYSIS` - 驾驶员头部姿态异常（低头/侧视）检测\n\n## 输入约束\n\n- 摄像头：车载 DMS 摄像头（红外/IR-cut 优先）\n- 安装位置：方向盘上方 / A 柱 / 仪表台上方，正对驾驶员面部\n- 帧率：≥ 25 FPS；分辨率 ≥ 480p\n- 必须能稳定看到面部及头部轮廓；夜间启用红外补光\n- 戴帽子/口罩/墨镜可能影响关键点稳定性\n\n## 头部姿态角定义\n\n- `pitch_deg` - 俯仰角（° ， > 0 抬头 / < 0 低头）\n- `yaw_deg` - 偏航角（° ， > 0 右转头 / < 0 左转头）\n- `roll_deg` - 翻滚角（° ， 头部左右倾斜）\n\n## 默认阈值（可由调用方覆盖）\n\n- 低头判定：`pitch_deg < -30°`\n- 侧视判定：`|yaw_deg| > 45°`\n- 持续时间阈值：超过 2 秒触发预警（distraction_duration_threshold_sec）\n\n## 预警类型\n\n- `head_down_distraction` - 低头分心（疑似看手机/查物品）\n- `head_side_distraction` - 侧视分心（疑似与乘客聊天/看窗外）\n- `head_roll_abnormality` - 头部倾斜异常（参考）\n\n## 输出字段（参考）\n\n- `driver_detected` - 是否检测到驾驶员\n- `head_pose_angles` - 当前/统计期内头部姿态角（pitch_deg / yaw_deg / roll_deg）\n- `head_down_events` - 低头分心事件列表（含开始时间、持续秒数、最大角度）\n- `head_side_events` - 侧视分心事件列表（含开始时间、持续秒数、最大角度、方向 left/right）\n- `total_distraction_duration_sec` - 累计分心时长（秒）\n- `distraction_event_count` - 分心事件总次数\n- `warning_type` - 触发的预警类型\n- `warning_message` - 预警提示文本（如\"驾驶员低头 3.2 秒（最大 -38°），疑似看手机，请立即抬头注视前方\"）\n- `recommend_action` - 建议的座舱联动动作（voice_alert / fleet_upload / event_record）\n\n> 仅输出基于头部姿态的检测结果与预警，不提供其他安全建议或医学诊断；预警仅供辅助提醒，驾驶员对车辆操作负全责。"},{"path":"skills/smyx_analysis/references/api_doc.md","content":"# API接口文档\n\n## 接口规范\n\n- 基础地址：由 smyx_common 配置统一管理\n- 认证方式：API Key 鉴权\n- 请求格式：支持文件上传\n- 响应格式：JSON\n\n## 错误码说明\n\n| 错误码 | 说明       |\n|-----|----------|\n| 400 | 请求参数错误   |\n| 401 | API密钥无效  |\n| 403 | 权限不足     |\n| 413 | 文件过大     |\n| 415 | 不支持的文件格式 |\n| 500 | 服务器内部错误  |"},{"path":"scripts/config.yaml","content":"{}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 Skill: Driver Head-Pose Abnormality (Head-Down / Side-View) | 驾驶员头部姿态异常（低头/侧视）检测 Owner: 18072937735 Summary: Using an in-cabin DMS camera, the system analyzes the driver's head pose in real time, computing head pitch (down/up) and yaw (left/right turn). | 通过车载DMS摄像头实时分析驾驶员头部姿态，计算头部俯仰角（低头/抬头）和偏航角（左/右转头）。当低头角度超过阈值（默认>30°）且持续时间超过2秒（可能为看手机、查看物品），或侧视角度超过阈值（默认>45°）持续时间超过2秒（可能为与乘客聊天、看窗外）时，输出分心驾驶预警，联动语音提醒，预防交通事故。 Tags: lates","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1052,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T20:40:08.926Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:57:55.382Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}