{"id":"bc6afb91-9d5e-4fa1-9617-a60f79b1e169","entityType":"agent","slug":"clawhub-fyniujin-wecom-voice-agent","name":"wecom-voice-agent","canonicalUrl":"https://www.xpersona.co/agent/clawhub-fyniujin-wecom-voice-agent","canonicalPath":"/agent/clawhub-fyniujin-wecom-voice-agent","generatedAt":"2026-10-10T06:44:53.820Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T01:23:56.511Z","emptyReason":null},"description":"企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会... Skill: wecom-voice-agent Owner: fyniujin Summary: 企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会... Tags: latest:2.8.0 Version history: v2.8.0 | 2026-09-20T15:52:21.374Z | auto **v2.8.0 introduces voice TTS multi-voice, voice clone, summary QA, and ops reporting tools.** - Added config/voices.yaml: Predefine","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:wecom-voice-agent","sourceUrl":"https://clawhub.ai/fyniujin/wecom-voice-agent","homepage":"https://clawhub.ai/fyniujin/skills/wecom-voice-agent","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/fyniujin/wecom-voice-agent","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/fyniujin/skills/wecom-voice-agent","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:23:56.511Z","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-10T01:23:56.511Z","emptyReason":null},"stars":null,"forks":null,"downloads":1808,"packageName":null,"latestVersion":"2.8.0","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:23:56.475Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T01:23:56.511Z","lastCrawledAt":"2026-10-10T01:23:56.475Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T01:23:56.475Z","lastVerifiedAt":null,"highlights":[{"version":"2.8.0","createdAt":"2026-09-20T15:52:21.374Z","changelog":"**v2.8.0 introduces voice TTS multi-voice, voice clone, summary QA, and ops reporting tools.** - Added `config/voices.yaml`: Predefined TTS voice sets with scene, emotion, and SSML support. - New scripts: `voice_policy.py` (TTS/SSML/voice policy), `voice_clone.py` (voice cloning for outbound only), `summary_qa.py` (call summary review & scoring), `report_generator.py` (ops stats & weekly reports). - Updated skill documentation with new online and privacy disclosures for TTS/voice clone APIs; usage guidance for all new tools. - Removed legacy `skill-card.md`. - All new features require no non-standard Python packages and all voice clone/TTS cloud links are opt-in and fully hidden unless keys are set.","fileCount":52,"zipByteSize":231330},{"version":"2.7.0","createdAt":"2026-09-02T08:25:18.284Z","changelog":"wecom-voice-agent v2.7.0 - 新增 memory_bridge.py：引入长期记忆桥接能力（MCP stdio JSON-RPC）。 - 新增 todo_followup.py：待办事项全流程闭环（纪要→回拨→到期提醒→二次外呼）。 - 新增 emotion_ticket_bridge.py：实现强负面情感到工单自动建单/升级/通知。 - 移除 skill-card.md，简化文件结构。 - 完善脚本目录架构说明，文档同步更新到 v2.7 状态。","fileCount":47,"zipByteSize":192403},{"version":"2.6.0","createdAt":"2026-08-24T12:35:41.274Z","changelog":"wecom-voice-agent v2.6.0 - 引入声明式意图引擎，支持 YAML 配置 20+ 意图及多级澄清（config/intents.yaml）。 - 新增自定义意图插件，支持企业自有 API 映射及灵活扩展（scripts/custom_intent_plugin.py, config/custom_intents.yaml）。 - 实现统一会话管理，合并原有各子系统，提升多轮对话一致性和开发体验（scripts/session_unified.py）。 - 增强实体抽取逻辑，支持规则、消歧和复述确认（scripts/entity_extractor.py）。 - 新增多级 IVR 菜单引擎，声明式配置电话语音菜单（scripts/ivr_engine.py, config/menu.yaml）。 - 优化目录结构，合并/归类原有脚本，移除冗余文档。","fileCount":44,"zipByteSize":177746},{"version":"2.5.1","createdAt":"2026-08-17T11:12:25.537Z","changelog":"wecom-voice-agent 2.5.1 - 增强合规与安全说明，细化本地数据持久化方式和保留时长，告知通话/录音存储路径与自动清理政策 - 新增“外部连接披露”部分，明确所有外部网络访问场景与数据边界 - 更新风险声明与合规声明，补充通话记录与录音信息的本地化处理细节 - 删除 skill-card.md，文档结构简化整理 - 补充和优化了 SKILL.md 说明文本，增强信息透明度","fileCount":36,"zipByteSize":145368},{"version":"2.5.0","createdAt":"2026-08-17T07:44:47.589Z","changelog":"wecom-voice-agent v2.5.0 - Added new modules: call record subsystem, voice channel, and voicemail summary scripts. - Updated the webhook server and documentation for enhanced voice and call processing logic. - Removed legacy skill card documentation file. - Expanded core functionality around voice calls and call record handling.","fileCount":36,"zipByteSize":145092},{"version":"2.4.0","createdAt":"2026-08-07T13:27:52.334Z","changelog":"- New version 2.4.0 adds enhanced queueing and audio processing. - Introduced `priority_queue.py` for improved request queue management. - Added `vad_filter.py` to support voice activity detection filtering. - Updated compliance and webhook server scripts to integrate new queue and VAD features. - Removed legacy documentation file (`skill-card.md`). - Minor documentation updates and cleanup in SKILL.md.","fileCount":33,"zipByteSize":125732},{"version":"2.3.0","createdAt":"2026-08-01T09:47:49.787Z","changelog":"wecom-voice-agent v2.3.0 - 新增方言自动识别和支持（方言检测器及策略配置）。 - 新增工单（ticket）管理模块。 - 脚本功能增强，支持更多多轮对话和分支管理。 - 优化避坑指南，正式支持粤语、四川话、上海话、东北话、闽南话等多种方言。 - 移除旧 skill-card.md 文档。 - 文档同步更新指令用法和新特性说明。","fileCount":31,"zipByteSize":110362},{"version":"2.2.0","createdAt":"2026-07-23T04:29:01.057Z","changelog":"- 新增情绪分析与情感应答能力，带来更贴合用户语气的智能回复 - 新增 emotion_analyzer.py 脚本与 emotion_strategies.json 配置，支持多种情绪策略 - 更新 session_manager.py 和 wecom_webhook_server.py，集成情绪分析流程 - 移除 skill-card.md，优化文档和项目结构 - 文档更新，补充新版情绪感知相关说明","fileCount":28,"zipByteSize":90792}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:wecom-voice-agent","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-fyniujin-wecom-voice-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/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-10T06:44:53.817Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-wecom-voice-agent/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-10T01:23:56.511Z","emptyReason":null},"readme":"Skill: wecom-voice-agent\n\nOwner: fyniujin\n\nSummary: 企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会...\n\nTags: latest:2.8.0\n\nVersion history:\n\nv2.8.0 | 2026-09-20T15:52:21.374Z | auto\n\n**v2.8.0 introduces voice TTS multi-voice, voice clone, summary QA, and ops reporting tools.**\n\n- Added `config/voices.yaml`: Predefined TTS voice sets with scene, emotion, and SSML support.\n- New scripts: `voice_policy.py` (TTS/SSML/voice policy), `voice_clone.py` (voice cloning for outbound only), `summary_qa.py` (call summary review & scoring), `report_generator.py` (ops stats & weekly reports).\n- Updated skill documentation with new online and privacy disclosures for TTS/voice clone APIs; usage guidance for all new tools.\n- Removed legacy `skill-card.md`.\n- All new features require no non-standard Python packages and all voice clone/TTS cloud links are opt-in and fully hidden unless keys are set.\n\nv2.7.0 | 2026-09-02T08:25:18.284Z | auto\n\nwecom-voice-agent v2.7.0\n\n- 新增 memory_bridge.py：引入长期记忆桥接能力（MCP stdio JSON-RPC）。\n- 新增 todo_followup.py：待办事项全流程闭环（纪要→回拨→到期提醒→二次外呼）。\n- 新增 emotion_ticket_bridge.py：实现强负面情感到工单自动建单/升级/通知。\n- 移除 skill-card.md，简化文件结构。\n- 完善脚本目录架构说明，文档同步更新到 v2.7 状态。\n\nv2.6.0 | 2026-08-24T12:35:41.274Z | auto\n\nwecom-voice-agent v2.6.0\n\n- 引入声明式意图引擎，支持 YAML 配置 20+ 意图及多级澄清（config/intents.yaml）。\n- 新增自定义意图插件，支持企业自有 API 映射及灵活扩展（scripts/custom_intent_plugin.py, config/custom_intents.yaml）。\n- 实现统一会话管理，合并原有各子系统，提升多轮对话一致性和开发体验（scripts/session_unified.py）。\n- 增强实体抽取逻辑，支持规则、消歧和复述确认（scripts/entity_extractor.py）。\n- 新增多级 IVR 菜单引擎，声明式配置电话语音菜单（scripts/ivr_engine.py, config/menu.yaml）。\n- 优化目录结构，合并/归类原有脚本，移除冗余文档。\n\nv2.5.1 | 2026-08-17T11:12:25.537Z | auto\n\nwecom-voice-agent 2.5.1\n\n- 增强合规与安全说明，细化本地数据持久化方式和保留时长，告知通话/录音存储路径与自动清理政策\n- 新增“外部连接披露”部分，明确所有外部网络访问场景与数据边界\n- 更新风险声明与合规声明，补充通话记录与录音信息的本地化处理细节\n- 删除 skill-card.md，文档结构简化整理\n- 补充和优化了 SKILL.md 说明文本，增强信息透明度\n\nv2.5.0 | 2026-08-17T07:44:47.589Z | auto\n\nwecom-voice-agent v2.5.0\n\n- Added new modules: call record subsystem, voice channel, and voicemail summary scripts.\n- Updated the webhook server and documentation for enhanced voice and call processing logic.\n- Removed legacy skill card documentation file.\n- Expanded core functionality around voice calls and call record handling.\n\nv2.4.0 | 2026-08-07T13:27:52.334Z | auto\n\n- New version 2.4.0 adds enhanced queueing and audio processing.\n- Introduced `priority_queue.py` for improved request queue management.\n- Added `vad_filter.py` to support voice activity detection filtering.\n- Updated compliance and webhook server scripts to integrate new queue and VAD features.\n- Removed legacy documentation file (`skill-card.md`).\n- Minor documentation updates and cleanup in SKILL.md.\n\nv2.3.0 | 2026-08-01T09:47:49.787Z | auto\n\nwecom-voice-agent v2.3.0\n\n- 新增方言自动识别和支持（方言检测器及策略配置）。\n- 新增工单（ticket）管理模块。\n- 脚本功能增强，支持更多多轮对话和分支管理。\n- 优化避坑指南，正式支持粤语、四川话、上海话、东北话、闽南话等多种方言。\n- 移除旧 skill-card.md 文档。\n- 文档同步更新指令用法和新特性说明。\n\nv2.2.0 | 2026-07-23T04:29:01.057Z | auto\n\n- 新增情绪分析与情感应答能力，带来更贴合用户语气的智能回复\n- 新增 emotion_analyzer.py 脚本与 emotion_strategies.json 配置，支持多种情绪策略\n- 更新 session_manager.py 和 wecom_webhook_server.py，集成情绪分析流程\n- 移除 skill-card.md，优化文档和项目结构\n- 文档更新，补充新版情绪感知相关说明\n\nv2.1.0 | 2026-07-15T08:34:19.053Z | auto\n\n**wecom-voice-agent v2.1.0**\n\n- 新增临时会话记录文件存储功能，示例文件位于 temp_sessions/ 目录，支持会话调试与测试回放。\n- 更新与完善多轮对话状态机和语音转写处理（优化 scripts/state_machine.py 和 scripts/transcriber.py）。\n- 增强合规性与流程说明，完善技能使用文档（README.md、SKILL.md 等）。\n- 移除冗余 skill-card.md，精简项目结构。\n- 改进合规性检测和风控脚本（scripts/compliance.py 部分更新）。\n\nv2.0.0 | 2026-07-15T07:46:26.275Z | auto\n\nwecom-voice-agent v2.0.0 introduces active voice calling and advanced call management:\n\n- 新增主动外呼、来电自动接线（IVR）、合规录音等通话管理功能\n- 新增多轮语音对话状态机（state_machine.py），支持通话状态、自动超时及上下文管理\n- 增加外呼任务调度、批量外呼、通话后自动生成纪要等自动化能力\n- 全面加强合规性：外呼前录音告知、用户同意方可录音、录音仅本地存储\n- 新增多个脚本和临时数据文件支持通话日志、转写、调度等（如 compliance.py、ivr_minutes.py 等）\n- 更新文档，详细说明 v2.0 新特性与安全/合规措施\n\nv1.3.0 | 2026-07-10T04:18:04.615Z | auto\n\nwecom-voice-agent v1.3.0\n\n- Improved documentation in README.md and SKILL.md for clarity and onboarding.\n- Cleaned up repository by removing the obsolete skill-card.md file.\n- Various code and logic optimizations in scripts/wecom_webhook_server.py.\n- Minor adjustments to risk statements, onboarding steps, and error handling instructions.\n- No breaking changes; compatible with previous version.\n\nv1.2.0 | 2026-07-09T16:23:38.251Z | auto\n\nwecom-voice-agent v1.2.0\n\n- 新增避坑指南与新手教程，提升新用户体验\n- 增加 step_by_step_setup.md 新手操作手册与 wecom_webhook_server.py 示例脚本\n- 移除 skill-card.md，文档内容整合至主要说明\n- 文档（README、SKILL.md）优化：补充操作步骤、错误处理、能力边界及常见场景\n- 增强意图识别规则，提升对自然语言表述的支持\n- 修复与简化错误提示信息，提升友好度\n\nv1.1.0 | 2026-07-09T10:24:53.321Z | auto\n\nwecom-voice-agent v1.1.0\n\n- 增加“快速开始”和“避坑指南”章节，提升新手引导和实际操作清晰度\n- 意图识别逻辑增强：支持更多自然语言关键词、置信度分数、主动态确认模糊请求\n- 错误处理说明更细致，补充用户友好型故障提示与应对措施\n- 示例场景补充模糊表达场景，应对“不确定意图”的真实对话\n- 强调脚本零依赖（标准库），并详细补充本地调试说明\n- 更新版本检查与升级提醒内容样式及改进点说明\n\nv1.0.0 | 2026-07-08T13:16:58.872Z | auto\n\nwecom-voice-agent 1.0.0 – 首发版本\n\n- 支持企业微信语音消息，一键转写及多轮智能对话\n- 覆盖日程管理、待办提醒、天气查询等常用办公场景\n- 实现语音/文本灵活回复，自动硬件检测与性能优化\n- 内置会话上下文管理与安全策略，符合数据与隐私合规要求\n- 提供本地测试脚本和自定义配置支持\n- 集成更新通知机制，便于后续升级\n\nArchive index:\n\nArchive v2.8.0: 52 files, 231330 bytes\n\nFiles: config/custom_intents.yaml (1751b), config/intents.yaml (10074b), config/menu.yaml (6093b), config/voices.yaml (3575b), README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/call_record_subsystem.py (33040b), scripts/compliance.py (29119b), scripts/custom_intent_plugin.py (9809b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/emotion_ticket_bridge.py (15411b), scripts/entity_extractor.py (18803b), scripts/intent_registry.py (16291b), scripts/ivr_engine.py (15638b), scripts/ivr_minutes.py (15155b), scripts/memory_bridge.py (14188b), scripts/priority_queue.py (21479b), scripts/report_generator.py (40268b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/session_unified.py (24166b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/summary_qa.py (23683b), scripts/ticket_manager.py (37306b), scripts/todo_followup.py (18259b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_channel.py (15865b), scripts/voice_clone.py (23799b), scripts/voice_policy.py (29132b), scripts/voice_simulator.py (6881b), scripts/voicemail_summary.py (15592b), scripts/wecom_webhook_server.py (63393b), skill-card.md (2406b), SKILL.md (50500b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nFile v2.8.0:SKILL.md\n\n---\nname: wecom-voice-agent\nversion: 2.8.0\ndescription: >\n---\n\n\n# 企业微信语音消息 Agent\n\n## ⚠️ 风险声明（必读）\n\n### 能力边界\n\n1. **本技能支持企业微信智能机器人场景**，包括被动语音消息处理和主动语音通话\n2. **语音转文字由企业微信官方提供**，本技能不自行采集或上传用户语音至任何第三方\n3. **不会读取或收集**用户的通讯录、聊天记录或其他个人隐私数据\n4. **所有数据处理均在本地完成**，通话记录（含 ASR 转写文本、元数据）持久化存储于本机 SQLite 数据库（`~/.wecom_voice/call_records.db`），录音文件存储于 `~/.wecom_voice/records/`，保留期限默认 90 天，到期自动清理\n5. **主动外呼需管理员授权**，且仅在用户明确同意录音后进行\n\n### 外部连接披露\n\n本技能仅在以下场景发起外部网络连接：\n\n| 目标主机 | 用途 | 触发条件 | 传输数据 |\n|---------|------|---------|---------|\n| `wttr.in` | 天气查询 API | 用户主动发起天气查询请求 | 城市名称（不含用户身份信息） |\n| `openspeech.bytedance.com` | 火山引擎 TTS 语音合成（备用链路） | 仅当配置 `VOLC_TTS_KEY` 且 Edge TTS 主链路不可用 | 待合成文本（通话播报内容） |\n| `api.coze.cn` / `api.minimax.chat` | 语音克隆 API（豆包 / MiniMax） | 仅当配置 `CLONE_PROVIDER` + `CLONE_API_KEY` 主动创建克隆音色 | 音色名称与授权信息（不含通话内容） |\n\n**除上述披露外，本技能不会向任何其他外部主机发起连接**。天气查询为只读 GET 请求；火山 TTS 与语音克隆均为可选增强能力，**未配置对应 Key 时静默跳过、绝不发起连接**，全部功能降级可用。所有外部连接均不上传用户身份信息。\n\n### 安全风险项\n\n| 风险等级 | 风险描述 | 预防措施 |\n|---------|---------|---------| \n| 🔴 高 | 语音转写准确率受环境噪音影响 | 当置信度低时主动询问用户确认 |\n| 🔴 高 | 误触发（电视/背景音乐被误认为语音） | 设置消息有效时长阈值，超过30秒无新消息则重置上下文 |\n| 🔴 高 | 外呼过程中的隐私泄露风险 | 全程录音告知、用户同意后才录音 |\n| 🟡 中 | 企业微信 API 频率限制（每分钟20次） | 实现请求队列和速率限制器 |\n| 🟡 中 | 长上下文导致 Token 消耗过大 | 自动压缩历史消息，保留最近5轮对话 |\n| 🟢 低 | 语音回复合成超时并发 | 超时后自动降级为文字回复 |\n\n### 合规声明\n\n- 本技能遵守《个人信息保护法》《数据安全法》相关规定\n- 所有操作均基于用户主动发起的对话，不主动采集数据\n- 语音数据由企业微信官方处理，本技能不存储原始音频\n- 用户可随时通过发送文字消息退出语音模式\n- **外呼录音必须获得用户明确同意才进行**\n- **所有录音文件仅存储在本机 `~/.wecom_voice/records/`，永不外传**\n- **通话记录（含 ASR 转写文本、元数据）存储于本机 SQLite，不上传第三方**\n- **数据保留期限：录音文件 90 天，通话记录 180 天，到期自动清理**\n\n---\n\n## 🚀 快速开始\n\n### 方式一：一条命令安装并体验\n\n```bash\n# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n### 方式二：从零手动体验\n\n```bash\n# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats\n```\n\n### v2.8 运营工具速用\n\n```bash\ncd D:/skill/wecom-voice-agent\n\n# 查看全部可用音色（3 套预设，来自 config/voices.yaml）\npython scripts/voice_policy.py list\n\n# 按场景+情感预览合成参数与 SSML（不发起合成）\npython scripts/voice_policy.py synth --scene outbound --emotion angry --confidence 0.9 --text \"您好，通知您明天下午3点参加评审。\" --ssml\n\n# 查看语音克隆模块状态（未配置 CLONE_PROVIDER/CLONE_API_KEY 时完全隐藏）\npython scripts/voice_clone.py status\n\n# 评审一段通话摘要（三要素评分，≥80 分达标）\npython scripts/summary_qa.py review --text \"会议决定：下周三18点前由张三负责提交修订方案。\" --id call_001\n\n# 查看最近 7 天运营摘要 / 生成上周 HTML 周报\npython scripts/report_generator.py summary --period week\npython scripts/report_generator.py weekly\n```\n\n> ✅ **无需安装任何 Python 包**，所有脚本仅使用 Python 标准库（`sys`、`os`、`json` 等）\n\n---\n\n## 二、架构（v2.8）\n\n```\nwecom-voice-agent/\n├── SKILL.md                  # 本文件（使用说明 + 风险 + 边界 + FAQ + 反模式）\n├── config/\n│   ├── intents.yaml          # v2.6 声明式意图注册表（20+ 意图）\n│   ├── custom_intents.yaml   # v2.6 自定义意图插件配置（企业 API 映射）\n│   ├── menu.yaml             # v2.6 IVR 多级菜单配置\n│   └── voices.yaml           # v2.8 TTS 音色库（3 套预设+情感调整+SSML+双链路）\n├── references/\n│   ├── wecom_bot_api.md      # 企业微信机器人 API 参考\n│   └── step_by_step_setup.md # 分步部署指南\n├── scripts/\n│   ├── wecom_webhook_server.py # 主服务（回调接收+意图路由+任务执行）\n│   ├── intent_registry.py    # v2.6 声明式意图引擎（YAML 配置+多级澄清）\n│   ├── custom_intent_plugin.py # v2.6 自定义意图插件（企业自有 API 声明式映射）\n│   ├── session_unified.py    # v2.6 统一会话管理（双向子系统，合并原 scheduler+session_manager）\n│   ├── ivr_engine.py         # v2.6 多级 IVR 菜单引擎（YAML 配置+数字/名称双选）\n│   ├── entity_extractor.py   # v2.6 实体抽取增强（规则+消歧+复述确认）\n│   ├── memory_bridge.py     # v2.7 zwjh 长期记忆桥接（MCP stdio JSON-RPC）\n│   ├── todo_followup.py     # v2.7 跟进待办闭环（纪要→回拨→到期→二次外呼）\n│   ├── emotion_ticket_bridge.py # v2.7 情感到工单直连（强负面→建单+升级+通知）\n│   ├── voice_policy.py      # v2.8 TTS 多音色与情感（voices.yaml+SSML+双链路降级）\n│   ├── voice_clone.py       # v2.8 语音克隆外呼（授权留痕+合规红线+未配置完全隐藏）\n│   ├── summary_qa.py        # v2.8 通话摘要质检（三要素评分+5%人工抽检+纠错回流）\n│   ├── report_generator.py  # v2.8 运营报表（接通率/漏斗/意图分布+周一HTML周报）\n│   ├── voice_simulator.py    # 语音消息模拟器（本地调试）\n│   ├── detect_hardware.py    # 硬件检测\n│   ├── state_machine.py      # 多轮对话状态机\n│   ├── call_record_subsystem.py # v2.5 通话记录子系统（合并4脚本）\n│   ├── voice_channel.py      # v2.5 多渠道抽象层\n│   ├── voicemail_summary.py  # v2.5 语音留言摘要\n│   ├── dialect_detector.py   # v2.3 方言检测\n│   ├── ticket_manager.py     # v2.3 工单管理\n│   ├── emotion_analyzer.py   # v2.2 情感识别\n│   ├── vad_filter.py         # v2.4 VAD 语音活动检测\n│   ├── priority_queue.py     # v2.4 四级优先级队列\n│   ├── compliance.py         # v2.4 合规录音（v3.0 强制告知）\n│   ├── scheduler.py          # v2.0 外呼调度（已合并至 session_unified）\n│   ├── session_manager.py    # v2.0 会话管理（已合并至 session_unified）\n│   ├── ivr_minutes.py        # v2.0 通话纪要（已合并至 call_record_subsystem）\n│   ├── stats.py              # v2.0 统计看板（已合并至 call_record_subsystem）\n│   └── transcriber.py        # v2.0 全文转写（已合并至 call_record_subsystem）\n└── temp_sessions/             # 运行时临时目录\n```\n\n**核心数据流**：`voice.content → intent_registry（声明式匹配+置信度评分）→ entity_extractor（实体抽取+消歧）→ handler → 任务执行`，同时旁路写入 `session_unified`（统一会话）与 `call_record_subsystem`（通话记录）。\n\n**v2.6 核心理念**：意图配置化（YAML 声明 + 置信度分级 + 多级澄清）、会话统一化（双向合并 + 状态共享）、IVR 配置化（层级菜单 + 双模式选择）、实体智能化（规则抽取 + 上下文消歧 + 复述确认）。\n\n**v2.8 核心理念**：播报情感化（场景预设 + 情感参数叠加限幅 + SSML 停顿加重）、克隆合规化（授权留痕 + 书面授权红线 + 仅外呼场景 + 未配置完全隐藏）、摘要质量闭环（三要素评分 + 达标线 + 人工抽检 + 纠错回流驱动 Prompt 迭代）、运营可观测（接通率 + 四级漏斗 + 周一 HTML 周报）。\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离手机/麦克风 20-30cm |\n| ❌ 一次说多句话（如\"查日程然后帮我订会议室\"） | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内，长内容请打字 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人**私聊**发语音 |\n| ❌ 发送方言（福建话、河南话等） | ✅ 支持**粤语、四川话、上海话、东北话、闽南话**，直接用方言对话即可，无需切换普通话 |\n| ❌ 说话时周围有电视/音乐 | ✅ 关掉背景音再说话，会被误认为指令 |\n| ❌ 以为能自动打电话/发短信 | ✅ v2.0 起支持外呼，但需管理员授权 |\n| ❌ 语音内容涉及密码/银行信息 | ✅ **切勿在语音中透露敏感信息**，所有文字均经过企业微信服务器 |\n\n---\n\n## 角色定义\n\n你是一名**企业微信语音智能助手**，专门处理企业微信生态内的语音交互场景。你的工作方式是：\n\n1. **被动响应**：只处理用户主动发送的语音消息，不主动拨打/发送（v2.0 起支持主动外呼）\n2. **意图理解**：将语音转写后的文本解析为结构化意图\n3. **任务执行**：调用相应的能力模块完成用户请求\n4. **通话管理**：支持主动外呼、来电接线、多轮对话、合规录音（v2.0 新增）\n5. **友好回复**：根据用户偏好返回文字或语音消息\n\n**你不是一个电话推销员，你是一个办公助手。**\n\n---\n\n## 核心指令\n\n### 一、消息接收阶段（系统自动触发）\n\n当企业微信回调收到 `msgtype: voice` 消息时：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转成文本的内容\"\n    }\n}\n```\n\n**关键步骤**：\n\n1. **提取文本内容**：从 `voice.content` 字段获取转写后的文本\n2. **验证消息有效性**：检查 `msgid` 是否重复（排重），检查消息时效性（超过5分钟则忽略）\n3. **上下文管理**：根据 `msgid` 查找或创建会话上下文\n\n### 二、意图解析阶段\n\n将用户语音文本分类为以下意图类型：\n\n| 意图类型 | 触发关键词 | 处理方式 |\n|---------|-----------|---------|\n| `query_schedule` | 日程、会议、安排、行程、下周、下周有什么 | 调用企业微信日程 skill |\n| `create_todo` | 提醒、待办、任务、别忘了、记得、设提醒 | 调用企业微信待办 skill |\n| `query_weather` | 天气、气温、下雨、温度、穿什么、热不冷 | 调用天气查询模块 |\n| `send_message` | 发消息、告诉、通知、转发、给XX发 | 调用企业微信消息 skill |\n| `help` | 帮助、能做什么、怎么用、功能、你可以做什么 | 返回帮助信息 |\n| `exit_voice` | 退出、不用了、谢谢、结束、再见、拜拜 | 切换到文字模式 |\n| `custom` | 无法识别的意图 | 尝试通用问答或请求澄清 |\n\n**增强版意图解析逻辑**：\n\n```\n步骤1: 精确匹配关键词 → 确定意图类型（多个关键词可叠加分数）\n步骤2: 提取时间/地点/人物等实体信息（支持\"下周\"、\"后天\"、\"明天上午9点\"）\n步骤3: 生成结构化 intent JSON（含置信度评分）\n步骤4: 置信度 > 0.3 → 调用对应处理模块；置信度 ≤ 0.3 → 主动询问用户想做什么\n```\n\n**提升识别准确率的提示**：\n\n当遇到以下模糊表达时，先确认而非猜测：\n\n| 用户说 | 不确定的点 | 确认方式 |\n|--------|----------|---------|\n| \"帮我安排一下\" | 是查日程还是建待办？ | \"您是想查看已有安排，还是需要创建新的提醒？\" |\n| \"下周开会\" | 是哪天？ | \"您是指下周一到周五的哪天呢？\" |\n| \"张三\" | 有多个同名吗？ | \"找到2位张三，请确认是哪个部门的\" |\n| \"明天上午\" | 几点？ | \"好的，明天上午几点呢？\" |\n| \"发给他\" | 发给谁？上下文没有人物 | \"请问要发给谁？\" |\n\n### 三、任务执行阶段\n\n#### 3.1 日程查询 (`query_schedule`)\n\n**输入格式**：\n```json\n{\n    \"intent\": \"query_schedule\",\n    \"entities\": {\n        \"time\": \"明天\",\n        \"date\": \"2024-01-15\",\n        \"person\": \"张三\"\n    }\n}\n```\n\n**执行步骤**：\n1. 解析时间实体（今天/明天/后天/下周三、下周一、下周等）\n2. 调用企业微信日程 API 查询指定日期安排\n3. 整理日程信息（时间-事项-地点）\n4. 格式化为自然语言回复\n\n**输出示例**：\n```\n您明天（1月15日）的日程安排：\n📅 09:00-10:00 周会 - 会议室A\n📅 14:00-15:00 与张三讨论项目 - 线上会议\n📅 16:30-17:00 代码评审 - 开发区\n共 3 项安排。需要我设置提醒吗？\n```\n\n#### 3.2 待办创建 (`create_todo`)\n\n**执行步骤**：\n1. 解析待办内容、截止时间、提醒时间\n2. 调用企业微信待办 API 创建任务\n3. 返回创建结果\n\n#### 3.3 天气查询 (`query_weather`)\n\n**执行步骤**：\n1. 解析地点实体（默认用户所在城市）\n2. 调用天气查询服务（wttr.in 免费 API）\n3. 整理天气信息并语音播报\n\n#### 3.4 消息发送 (`send_message`)\n\n**执行步骤**：\n1. 解析接收人、消息内容\n2. **确认发送意图**（防止误触，发送前让用户确认）\n3. 调用企业微信消息 API 发送\n\n### 四、v2.0 新增：主动通话管理\n\n#### 4.1 主动外呼\n\n**触发条件**：用户/系统发起外呼任务\n\n**执行流程**：\n1. 获取被叫方信息（手机号或用户ID）\n2. 调用企业微信「语音通话」API 发起呼叫\n3. 接通后播放录音告知（\"本次通话可能被录音\"）\n4. 用户同意 → 开始正式通话 + 录音\n5. 用户拒绝 → 继续通话但不录音\n6. 通话结束 → 自动生成纪要 + 保存录音 + 发送纪要\n\n#### 4.2 来电自动接线（IVR 替代）\n\n**触发条件**：用户拨打企业绑定电话\n\n**执行流程**：\n1. 企微电话接通回调触发\n2. Agent 播放欢迎语 + 录音告知\n3. 等待用户语音输入（ASR 转写）\n4. 意图识别 → 执行对应任务\n5. 多轮对话状态机管理交互\n6. 30 秒无新语音自动结束通话\n\n#### 4.3 通话后自动纪要\n\n**触发条件**：通话结束\n\n**执行流程**：\n1. 从 ASR 文字流提取「决策点」「待办项」「时间点」\n2. 输出结构化纪要（markdown 格式）\n3. 通过企微消息 API 发送给呼叫方\n\n#### 4.4 多轮语音对话状态机\n\n**状态定义**：\n- `IDLE` → 空闲/未开始\n- `DIALING` → 拨号中\n- `SPEAKING` → Agent 说话中（TTS 播报）\n- `LISTENING` → 等待用户语音输入\n- `CONFIRMING` → 二次确认中（ASR 置信度低）\n- `ENDING` → 通话结束中\n\n**超时机制**：30 秒无新语音自动结束通话\n\n#### 4.5 合规录音告知 + 本地存储\n\n**执行流程**：\n1. 通话开始时播放「本次通话可能被录音，用于服务品质监控。请问您是否同意？」\n2. 用户回应「同意」→ 开始录音\n3. 录音文件存储到本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n4. 录音记录存本地 SQLite\n5. **不上传任何第三方**\n\n#### 4.6 外呼任务调度\n\n**功能**：\n- 定时外呼（每天9点提醒）\n- 批量外呼（CSV/JSON 导入客户列表）\n\n**实现方式**：\n- 使用 `sched` + `threading` 实现定时调度\n- CSV/JSON 批量导入客户列表\n- 并发控制（默认最大 3 路并发）\n\n### 五、回复生成阶段\n\n#### 5.1 文字回复\n\n当用户发送的语音消息内容较简单，或用户明确表示\"用文字回复我\"时：\n\n```\n回复格式要求：\n- 简洁明了，每段不超过3行\n- 使用 emoji 增强可读性\n- 包含下一步操作建议\n```\n\n#### 5.2 语音回复\n\n当用户明确表示\"用语音告诉我\"，或回复内容较长（超过100字）时：\n\n**语音合成流程**：\n1. 调用本地 TTS 引擎生成语音文件\n2. 上传至企业微信获取 media_id\n3. 通过 response_url 发送语音消息\n\n**TTS 引擎选择优先级**：\n```\n优先级1: Edge TTS（免费，无需 API Key，中文效果良好）\n优先级2: 火山引擎 TTS（音色更自然，需配置 API Key）\n```\n\n### 六、多轮对话管理\n\n> ⚠️ **重要说明**：v2.0 起提供**完整的通话状态机**（`state_machine.py`），\n> 支持多轮语音对话的上下文管理和超时自动结束。\n\n**上下文保持规则**：\n- 同一用户（同一 `msgid` 前缀）连续消息视为一轮对话\n- 单轮对话最多保留 **5 条消息**（3条用户 + 2条助手）\n- 超过5条后自动压缩：保留第一条用户消息 + 最近2条消息\n- **对话超时**：用户连续 30 秒（通话模式）/ 60 秒（文字模式）无新消息则自动结束上下文\n\n**上下文数据结构**：\n```json\n{\n    \"session_id\": \"userid_timestamp\",\n    \"messages\": [...],\n    \"current_intent\": \"query_schedule\",\n    \"collected_entities\": {\"time\": \"明天\"},\n    \"awaiting\": \"date\",\n    \"created_at\": 1705286400\n}\n```\n\n---\n\n## 硬件自适应优化\n\n### 自动检测与分级\n\n本技能启动时自动检测用户计算机系统资源，并根据结果调整并发和缓存策略：\n\n| 硬件等级 | RAM 范围 | CPU 核心数 | 并发处理能力 | 上下文缓存 |\n|---------|---------|-----------|------------|-----------|\n| 🟢 高配 | ≥ 16GB | ≥ 8核 | 同时处理 5 路会话 | 保留 100 轮历史 |\n| 🟡 中配 | 8-16GB | 4-8核 | 同时处理 3 路会话 | 保留 20 轮历史 |\n| 🔴 低配 | < 8GB | < 4核 | 同时处理 1 路会话 | 保留 5 轮历史 |\n\n**检测方式**：\n- WorkBuddy 环境：读取系统信息和 Node.js `os` 模块\n- 独立脚本：使用 Windows API (`GlobalMemoryStatusEx`) 获取真实硬件参数\n\n### 性能保障措施\n\n1. **懒加载机制**：非核心模块在首次使用时才加载\n2. **资源回收**：对话结束后立即释放占用的内存和临时文件\n3. **超时保护**：语音转写受网络影响，超时后自动提示用户重试\n4. **日志限制**：本地日志文件最大 100KB，自动轮转覆盖\n\n---\n\n## 更新通知机制\n\n### 版本检查\n\n本技能在每次执行时（频率限制为每6小时一次）执行以下检查：\n\n1. 本地安装版本号 vs 云端最新版本号\n2. 如有新版本，向用户发送更新提醒消息\n\n**提醒格式**：\n```\n🎉 发现新版本：v2.0.0\n主要改进：\n- 新增主动外呼、来电接线、通话纪要\n- 新增合规录音告知、外呼任务调度\n- 新增通话记录看板、全文转写\n\n请运行以下命令更新：\nskillhub install wecom-voice-agent --force\n```\n\n### 自动更新（可选）\n\n用户可通过发送\"检查更新\"触发版本检查，或通过以下命令手动更新：\n\n```bash\nskillhub install wecom-voice-agent --force\n```\n\n---\n\n## 示例场景\n\n### 场景1：语音查日程\n\n**用户（语音）**：明天有什么会议？\n\n**企业微信回调**：\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\"content\": \"明天有什么会议\"}\n}\n```\n\n**助手回复**：\n```\n您明天（7月9日）的日程安排：\n\n📅 09:00-10:00 产品周会 - 大会议室\n📅 14:00-15:30 客户拜访 - 上海浦东\n📅 16:00-17:00 团队代码评审\n\n共 3 项。需要我设置提前30分钟提醒吗？\n```\n\n### 场景2：语音建待办\n\n**用户（语音）**：提醒我下午3点提交报告\n\n**助手回复**：\n```\n✅ 已创建待办提醒：\n⏰ 时间：今天下午3:00\n📝 内容：提交报告\n\n需要我同时在团队群里发一条提醒吗？\n```\n\n### 场景3：连续对话\n\n**用户（语音）**：今天天气怎么样？\n**助手回复**：\n```\n北京今日天气：\n🌤️ 多云  28°C ~ 35°C\n💡 建议：带伞，可能有阵雨\n🌬️ 东南风 3级\n```\n\n**用户（语音）（追问）**：**那明天呢？**\n\n**助手回复**（利用上下文，知道地点仍然是北京）：\n```\n北京明天天气：\n🌧️ 小雨  24°C ~ 30°C\n💡 建议：带伞，穿薄外套\n\n看起来明天要下雨，需要我帮您调整明天的外出安排吗？\n```\n\n### 场景4：模糊表达处理\n\n**用户（语音）**：帮我安排一下\n\n**助手回复**（主动确认，不猜测）：\n\n```\n我可以帮您：\n1️⃣ 查看日程安排（您想查哪天？）\n2️⃣ 创建待办提醒（提醒什么内容？）\n3️⃣ 查询天气（哪个城市？）\n\n请告诉我您想做什么。\n```\n\n### 场景5：误触发处理\n\n**用户（语音）**：（环境噪音 / 电视声音）\n\n**助手回复**：\n```\n抱歉，我没有听清楚您的语音内容 😅\n\n请用清晰的语音告诉我您需要什么帮助，例如：\n• \"查一下明天的日程\"\n• \"提醒我下午开会\"\n• \"发消息给张三\"\n```\n\n### 场景6：v2.0 主动外呼\n\n**系统**：发起外呼任务 → 拨打 13800138000\n\n**Agent**（接通后）：\n```\n您好，我是XX公司的语音助手。本次通话可能被录音，用于服务品质监控。请问您是否同意？\n```\n\n**用户**：同意\n\n**Agent**：\n```\n好的，感谢您的确认。我们想确认一下，您明天下午3点的会议安排是否有变化？\n```\n\n**用户**：没有变化，按时参加\n\n**Agent**：\n```\n好的，已为您确认。通话结束后我们会发送纪要至您的企业微信。祝您愉快！\n```\n\n### 场景7：v2.0 来电接线\n\n**用户**：拨打企业绑定电话\n\n**Agent**：\n```\n您好，欢迎致电XX公司。我是智能语音助手，请问您需要什么帮助？\n```\n\n**用户**：我要退订\n\n**Agent**（二次确认，ASR 置信度 0.7 < 0.85）：\n```\n抱歉，我没有完全听清。您说的是「我要退订」吗？请确认「是」或「不是」。\n```\n\n**用户**：是\n\n**Agent**：\n```\n好的，已为您提交退订申请。受理编号：TK20260715001。我们会在3个工作日内处理。还有其他需要帮助的吗？\n```\n\n---\n\n## 错误处理\n\n### 常见错误与处理方式\n\n| 错误类型 | 触发条件 | 友好提示 |\n|---------|---------|---------| \n| 语音转写失败 | `voice.content` 为空或乱码 | \"抱歉，您的语音没有识别成功，请重新发送或尝试用普通话慢慢说。\" |\n| API 调用失败 | HTTP 4xx/5xx 错误码 | \"当前网络繁忙，请稍后再试。如您连续遇到问题，可尝试重启企业微信应用。\" |\n| 意图识别失败 | 关键词匹配度 < 0.3 | 主动询问用户意图，提供选项菜单（见\"模糊表达处理\"场景） |\n| TTS 合成失败 | 语音文件生成超过5秒 | 改为文字回复，附加提示：\"语音播报暂时不可用，已为您用文字显示。\" |\n| 上下文过期 | 对话间隔 > 60秒 | 自动开始新对话，回复：\"检测到新会话，请问有什么可以帮您的？\" |\n| 找不到会话 | 查询不存在的 session_id | \"会话不存在或已过期，请重新发送语音指令。\" |\n| 硬件检测失败 | Windows API 或 WMI 均不可用 | \"无法检测硬件配置，已自动使用'低配'模式保障运行。\" |\n| 外呼失败 | 被叫方无应答/占线 | \"暂时无法接通，请稍后重试或留下口信。\" |\n| 录音失败 | 本地存储空间不足 | \"存储空间不足，已自动清理旧录音。请重试。\" |\n\n### 异常退出策略\n\n当发生严重错误时：\n\n1. **用中文向用户道歉**并简要说明原因（不要暴露技术术语如 \"Traceback\"、\"HTTP 500\"）\n2. **记录错误信息**到本地日志 `D:/skill/wecom-voice-agent/temp_sessions/error.log`\n3. **清理临时文件**（音频文件、缓存数据）\n4. **恢复初始状态**，等待下一条用户消息\n5. **连续失败3次**时主动提示用户：\"检测到连续操作失败，请检查网络连接或稍后重试。\"\n\n**错误提示原则**：\n- ❌ \"Error: connection refused\"（技术术语）\n- ✅ \"无法连接到服务，请检查您的网络后重试。\"（用户语言）\n- ❌ \"Traceback (most recent call last)...\"（堆栈信息）\n- ✅ \"系统遇到了临时问题，已自动恢复，请重新发送指令。\"（友好提示）\n\n---\n\n## FAQ\n\n### Q1：这个技能需要额外的 API Key 吗？\n**A**：不需要核心 API Key。企业微信内置的语音转文字功能免费使用。\n如果您希望使用更优质的语音合成（火山引擎 TTS），可选配置 API Key，但 Edge TTS 完全免费且开箱即用。\n\n### Q2：支持哪些方言或语言？\n**A**：v2.3.0 起内置**方言检测引擎**，自动识别粤语、四川话、上海话、东北话、闽南话 5 大方言，并使用对应的方言风格回复。无需切换普通话，直接说方言即可。\n\n### Q3：语音消息长度有限制吗？\n**A**：企业微信智能机器人接收的语音消息通常限制在 60 秒以内。\n如需处理更长的录音，请使用企业微信的「文件上传」功能，后续版本将支持长语音转写。\n\n### Q4：隐私安全吗？我的语音数据会被上传吗？\n**A**：**绝对不会**。本技能不存储、不上传、不转发用户的任何语音数据。\n语音转写完全由企业微信官方接口完成，本技能仅接收转写后的文本内容。\nv2.0 起外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传。\n\n### Q5：支持群聊吗？\n**A**：当前仅支持单聊（`chattype: single`），以确保语音转写准确率和隐私安全。\n群聊支持将在后续版本中评估后决定。\n\n### Q6：能在手机上使用吗？\n**A**：可以。只要您的 WorkBuddy 客户端运行并连接到企业微信，手机端和 PC 端均可使用。\n\n### Q7：并发能力如何？\n**A**：单用户模式下，本技能可同时处理多个企业微信用户的语音请求，\n具体并发数根据您的电脑硬件自动调整（1-5路并发）。\n外呼任务并发默认最大值 3 路（可在 `scheduler.py` 中调整）。\n\n### Q8：如何卸载或停止？\n**A**：发送文字消息\"退出语音模式\"即可停止语音助手。\n如需完全卸载，请运行：`skillhub uninstall wecom-voice-agent`\n\n### Q9：为什么有时候听不懂我说的话？\n**A**：语音转写准确率受以下因素影响：\n- 环境噪音（电视、空调、外部人声）\n- 说话方言或口音较重\n- 语音消息超过 60 秒\n- 一次发送多步指令（如\"查日程然后订会议室\"）\n\n**建议**：一次只说一件事，用普通话在安静环境发送，控制在 60 秒以内。\n\n### Q10：v2.0 外呼功能合规吗？\n**A**：完全合规。外呼功能遵守以下原则：\n- **录音告知**：通话开始时明确告知用户\"本次通话可能被录音\"\n- **用户同意**：必须用户明确同意后才开始录音\n- **本地存储**：录音文件仅存储在本机 `~/.wecom_voice/records/`，不上传第三方\n- **随时退出**：用户可在通话中随时要求终止录音\n\n### Q11：遇到错误了屏幕上显示英文？\n**A**：本技能已将所有错误提示改为中文。如果您仍看到英文：\n1. 可能是企业微信官方 API 返回的英文错误\n2. 请将错误截图发送至 **njskills@agent.qq.com**，我们会处理\n\n---\n\n## 脚本与使用指南\n\n### v2.6 新增脚本\n\n#### scripts/intent_registry.py\n\n声明式意图引擎。加载 `config/intents.yaml`，实现关键词匹配、置信度计算、多级澄清策略。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/intent_registry.py\n```\n\n**特性**：\n- 20+ 意图声明式配置（query/action/system 三大类）\n- 关键词匹配 + 置信度评分（匹配多关键词有加分）\n- 多级澄清：≥0.7 直接执行、0.4-0.7 反问收窄、<0.4 转帮助\n- 新增意图只改 `config/intents.yaml`，不改代码\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n---\n\n#### scripts/custom_intent_plugin.py\n\n自定义意图插件引擎。允许企业通过 `config/custom_intents.yaml` 将意图映射到自有 HTTP API。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/custom_intent_plugin.py\n```\n\n**特性**：\n- 声明式端点 URL、HTTP 方法、请求模板\n- 响应字段映射到话术模板（`{{field.path}}` 嵌套取值）\n- 鉴权通过环境变量读取（`auth_env` 字段指定变量名）\n- 超时/失败兜底话术\n- 纯标准库（urllib）\n\n**配置示例**（`config/custom_intents.yaml`）：\n```yaml\nintents:\n  query_order:\n    endpoint: \"https://api.example.com/orders\"\n    method: \"GET\"\n    auth_env: \"ORDER_API_TOKEN\"\n    timeout: 10\n    request_template:\n      order_id: \"{order_id}\"\n    response_template: \"您的订单{{order.status}}，预计{{order.eta}}送达。\"\n    fallback_text: \"订单查询服务暂不可用，请稍后再试。\"\n```\n\n---\n\n#### scripts/session_unified.py\n\n统一会话管理。合并原 scheduler.py（外呼调度）与 session_manager.py（被动接收）为双向子系统。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/session_unified.py\n```\n\n**特性**：\n- 统一会话表（session_id / direction / status / context）\n- 入站（inbound）/ 出站（outbound）/ 语音留言（voicemail）三向统一管理\n- 状态机复用（state_machine.py 的 CallStateMachine）\n- 记录与统计同源（call_record_subsystem.py）\n- SQLite 持久化 + 自动清理过期会话\n- 纯标准库（sqlite3 + threading）\n\n---\n\n#### scripts/ivr_engine.py\n\n多级 IVR 菜单引擎。加载 `config/menu.yaml`，支持层级菜单导航。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_engine.py\n```\n\n**特性**：\n- YAML 配置化层级菜单（根菜单 → 子菜单 → 意图触发）\n- 说数字或说名称双选择方式\n- 0 = 重复听、9 = 转人工、8 = 返回上级\n- 超时/非法输入/重试次数限制\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n**菜单结构**（`config/menu.yaml`）：\n- 根菜单：销售咨询 / 技术支持 / 财务报销 / 订单物流 / 人工服务\n- 子菜单：每个大类下 3-4 个具体服务意图\n- 全局特殊按键：0 重复、9 转人工、8 返回\n\n---\n\n#### scripts/entity_extractor.py\n\n实体抽取增强模块。规则层 + 上下文消歧 + 复述确认。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/entity_extractor.py\n```\n\n**特性**：\n- 规则层：时间、日期、人物、地点、订单号、金额、手机号、邮箱、百分比、数量\n- 上下文消歧：代词回指（\"他\"→上一轮提到的人）、省略补全\n- 复述确认：格式化实体回显（\"请确认：日期：XX，时间：XX...\"）\n- 纯标准库（re + datetime）\n\n---\n\n### 本地测试脚本（已有）\n\n#### scripts/detect_hardware.py\n\n自动检测用户计算机硬件资源，输出硬件等级配置。\n\n```bash\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n```\n\n**输出示例**：\n```json\n{\n    \"level\": \"medium\",\n    \"ram_gb\": 16.0,\n    \"cpu_cores\": 6,\n    \"concurrency\": 3,\n    \"cache_limit\": 20,\n    \"description\": \"中配 - 支持3路并发，20轮历史缓存\",\n    \"platform\": \"win32\"\n}\n```\n\n#### scripts/voice_simulator.py\n\n模拟企业微信语音消息回调，用于本地调试意图解析逻辑。\n\n```bash\n# 基础用法\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 指定用户\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京天气\" --userid zhangsan\n\n# JSON 格式输出\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"提醒我开会\" --format json\n```\n\n#### scripts/session_manager.py\n\n管理对话上下文，支持创建、查询、清理会话。\n\n```bash\n# 创建新会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\n\n# 查询会话状态（表格格式）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py get --session_id xxx --format table\n\n# 查找用户活跃会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py find --userid zhangsan\n\n# 向会话添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py add --session_id xxx --role user --content \"你好\"\n\n# 清理过期会话（默认120秒）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py cleanup --timeout 180\n\n# 查看所有会话统计\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n#### scripts/wecom_webhook_server.py\n\n企业微信智能机器人回调服务器。接收企业微信推送的消息回调，自动处理语音消息。\n\n```bash\n# 一键体验所有功能（无需启动服务）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --quick\n\n# 启动服务器（默认端口 8080）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py\n\n# 指定端口\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --port 9000\n```\n\n**v2.0 核心升级**：\n- ✅ **真正的天气查询**：调用 wttr.in 免费 API（无需 key），中文描述 + 穿衣建议\n- ✅ **当前时间查询**：本地计算，100%可用，无需任何网络依赖\n- ✅ **意图识别增强**：关键词 + 正则混合匹分，置信度评分\n- ✅ **多轮对话**：根据 `msgid` 去重，会话缓存管理\n- ✅ **中文错误提示**：全部错误给出具体解决步骤\n\n**部署步骤**：\n1. 启动服务器：`python scripts/wecom_webhook_server.py --port 8080`\n2. 使用内网穿透暴露 8080 端口（frp/ngrok）\n3. 将穿透后的 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n4. 发送语音消息测试\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n---\n\n#### scripts/state_machine.py\n\n多轮对话状态机。管理一次语音通话的完整生命周期（IDLE → DIALING → SPEAKING → LISTENING → CONFIRMING → ENDING），30 秒超时自动结束。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/state_machine.py\n```\n\n**特性**：\n- 状态持久化到本地 JSON（支持断线恢复）\n- ASR 置信度 < 0.85 时自动进入 CONFIRMING 二次确认\n- `StateMachineManager` 支持多通话并发管理\n\n---\n\n#### scripts/compliance.py\n\n合规录音管理器。提供录音告知、本地存储、SQLite 持久化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/compliance.py\n```\n\n**特性**：\n- 录音前播放告知文本，用户同意后才录音\n- 录音文件存储在本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n- SQLite 记录主叫/被叫/时长/时间/意图\n- **不上传任何第三方**\n\n---\n\n#### scripts/ivr_minutes.py\n\n通话后自动纪要。从 ASR 文字流中提取决策点、待办项、时间点。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_minutes.py\n```\n\n**特性**：\n- 正则 + 规则提取，无需外部 API\n- 输出结构化 markdown 格式纪要\n- 支持简单情感分析（积极/中性/消极）\n\n---\n\n#### scripts/scheduler.py\n\n外呼任务调度器。支持定时外呼和批量外呼。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/scheduler.py\n```\n\n**使用方式**：\n```python\nfrom scheduler import OutboundScheduler, MockCallExecutor\n\nscheduler = OutboundScheduler(executor=MockCallExecutor())\nscheduler.start()\n\n# 添加一次性外呼\nscheduler.add_one_shot(\"task_001\", \"13800138000\", \"预约确认\", \"2026-07-15T09:00:00\")\n\n# 添加每日定时外呼\nscheduler.add_daily(\"task_002\", \"13800138000\", \"早安提醒\", \"09:00\")\n\n# 批量外呼（CSV 导入）\nscheduler.add_batch([\n    {\"target\": \"13900139000\", \"name\": \"客户A\", \"script\": \"预约确认\"},\n    {\"target\": \"13900139001\", \"name\": \"客户B\", \"script\": \"回访\"},\n])\n```\n\n**CSV 导入格式**：\n```csv\ntarget,name,script\n13800138000,张三,预约确认\n13800138001,李四,回访\n```\n\n---\n\n#### scripts/stats.py\n\n通话记录看板。输出通话统计数据和趋势图。\n\n```bash\n# 本月看板\npython D:/skill/wecom-voice-agent/scripts/stats.py\n\n# 本周看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period week\n\n# 本年度看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period year\n\n# 按用户筛选\npython D:/skill/wecom-voice-agent/scripts/stats.py --userid zhangsan\n\n# 导出 JSON\npython D:/skill/wecom-voice-agent/scripts/stats.py --export stats.json\n```\n\n**输出指标**：\n- 总通话次数、总时长、平均时长\n- 外呼/来电比例、接听率、录音覆盖率\n- 意图分布、挂断原因分布\n- 每日趋势 ASCII 图\n\n---\n\n#### scripts/transcriber.py\n\n通话录音文字转写全文。输出 .txt（标准库）和 .docx（可选）。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/transcriber.py\n```\n\n**使用方式**：\n```python\nfrom transcriber import TranscriptWriter\n\nwriter = TranscriptWriter()\nturns = [\n    {\"role\": \"user\", \"content\": \"你好\", \"time\": \"2026-07-15T10:00:00\"},\n    {\"role\": \"agent\", \"content\": \"您好，请问有什么需要帮助？\", \"time\": \"2026-07-15T10:00:05\"},\n]\n\n# 输出 TXT（纯标准库）\nwriter.write_txt(turns, call_id=\"call_001\")\n\n# 输出 DOCX（需 python-docx）\nwriter.write_docx(turns, call_id=\"call_001\")\n```\n\n---\n\n#### scripts/call_record_subsystem.py（v2.5 新增）\n\n通话记录子系统。合并原 4 个脚本（compliance/ivr_minutes/stats/transcriber）为统一接口。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/call_record_subsystem.py\n```\n\n**使用方式**：\n```python\nfrom call_record_subsystem import CallRecordSubsystem\n\ncrs = CallRecordSubsystem()\ncrs.create_record(\"call_001\", \"13800138000\", \"13900139000\", \"outbound\")\ncrs.give_consent(\"call_001\", True)\ncrs.add_audio(\"call_001\", audio_data)\ncrs.add_transcript(\"call_001\", \"用户: 你好\\n助手: 您好\", \"greeting\")\nminutes = crs.generate_minutes(\"call_001\")\nstats = crs.get_stats(\"month\")\n```\n\n---\n\n#### scripts/voice_channel.py（v2.5 新增）\n\n多渠道抽象层。支持企业微信/钉钉/飞书消息解析和标准化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voice_channel.py\n```\n\n**使用方式**：\n```python\nfrom voice_channel import VoiceChannelFactory, ChannelType\n\n# 解析企微回调\nmsg = VoiceChannelFactory.parse_wechat_callback(callback_dict)\n# 解析钉钉回调\nmsg = VoiceChannelFactory.parse_dingtalk_callback(callback_dict)\n# 解析飞书回调\nmsg = VoiceChannelFactory.parse_feishu_callback(callback_dict)\n\n# 获取渠道处理器\nchannel = VoiceChannelFactory.get_channel(ChannelType.WECHAT)\n```\n\n---\n\n#### scripts/voicemail_summary.py（v2.5 新增）\n\n语音留言摘要系统。当用户无法接听时，语音留言自动转录并生成结构化摘要。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voicemail_summary.py\n```\n\n**使用方式**：\n```python\nfrom voicemail_summary import VoicemailSummarizer\n\nsummarizer = VoicemailSummarizer()\nresult = summarizer.process_voicemail(\"vm_001\", \"13800138000\", \"帮我查订单状态\")\nprint(result[\"summary\"])\n\n# 批量处理\nresults = summarizer.batch_process([\n    {\"vm_id\": \"vm_001\", \"caller\": \"13800138000\", \"content\": \"查订单\"},\n    {\"vm_id\": \"vm_002\", \"caller\": \"13900139000\", \"content\": \"投诉\"},\n])\n```\n\n---\n\n### 配置文件\n\n本技能无需额外配置文件即可运行。\n\n如需自定义配置，可在工作项目录下创建 `.workbuddy/wecom-voice-agent.yaml`：\n\n```yaml\n# 企业微信语音消息 Agent 配置\n# 所有选项均为可选，使用括号内默认值\n\ntts_engine: edge  # edge 或 volcengine\nlog_level: info   # debug | info | warning | error\nsession_timeout: 60  # 对话超时时间（秒）\nmax_history: 5     # 单轮最大消息数\n# v2.0 新增\ncall_timeout: 30   # 通话超时时间（秒）\nmax_concurrent_calls: 3  # 最大并发外呼数\nconfidence_threshold: 0.85  # ASR 置信度二次确认阈值\nrecords_dir: ~/.wecom_voice/records  # 录音存储路径\n# v2.8 新增\nvoices_config: config/voices.yaml  # TTS 音色库（3 套预设+情感调整+SSML，修改后重启生效）\nvolc_tts_key: \"\"   # 火山引擎 TTS Key（可选；留空则仅用 Edge 免费主链路，缺失自动降级）\nclone_provider: \"\" # 语音克隆服务商 doubao / minimax（可选；留空则克隆功能完全隐藏）\nclone_api_key: \"\"  # 语音克隆 API Key（可选，配合 clone_provider 使用）\n```\n\n---\n\n## 联系与反馈\n\n### 邮箱\n\n如有更好的建议或遇到问题，请发送邮件至：\n\n**njskills@agent.qq.com**\n\n### 问题反馈模板\n\n```\n标题：[wecom-voice-agent] 问题简述\n\n环境信息：\n- WorkBuddy 版本：\n- 企业微信版本：\n- 操作系统：\n\n问题描述：\n- 预期行为：\n- 实际行为：\n- 复现步骤：\n\n是否愿意提供调试日志：是/否\n```\n\n---\n\n## 更新日志\n\n| v2.8.0 | 2026-09-20 | 增加：TTS 多音色与情感 voice_policy.py（config/voices.yaml 三套预设音色覆盖正式通知/客服安抚/营销外呼，情感→语速语调动态叠加并自动限幅 ±50%/±50Hz，SSML 句间停顿+数字日期自动加重，Edge TTS 主链路→火山 TTS 备用链路→文字降级三级策略）；增加：语音克隆外呼 voice_clone.py（豆包/MiniMax 可选接入，内置授权确认文本+SQLite 授权留痕+样本 SHA256 防篡改，合规红线仅限本人或书面授权音色，克隆音色仅允许主动外呼场景，未配置 Key 时模块完全隐藏不报错）；增加：通话摘要质检 summary_qa.py（决策 40%/待办 35%/时间 25% 三要素加权评分，≥80 分才交付，达标摘要 5% 随机人工抽检，纠错记录回流驱动摘要 Prompt 迭代）；增加：运营报表 report_generator.py（外呼接通率/时长四档分布/意图 Top10/外呼四级漏斗调度发起→振铃接通→有效通话→待办跟进/待办逾期统计，周一生成上周完整周期 HTML 周报单文件导出，数据源缺失自动降级记警告）；新增 config/voices.yaml 音色库配置文件；补充：外部连接披露表增加火山 TTS 与语音克隆两个条件性连接（未配置 Key 时不发起） |\n| v2.7.0 | 2026-09-02 | 增加：记忆桥接子模块 memory_bridge.py（zwjh 长期记忆 MCP 桥接，来电拉取历史+通话回写+降级方案，纯标准库）；增加：跟进待办闭环 todo_followup.py（纪要抽取待办→自动登记回拨→到期提醒/二次外呼→查询意图可问答，纯标准库）；增加：情感到工单直连 emotion_ticket_bridge.py（强负面→直连 ticket_manager 建单+升级+主管通知，无需独立触发，纯标准库）；优化：emotion_analyzer（v2.2）+ ticket_manager（v2.3）链路打通 |\n| v2.6.0 | 2026-08-24 | 重构：声明式意图引擎 intent_registry.py（intents.yaml 配置化 20+ 意图，关键词匹配+置信度评分+多级澄清，新增意图只改配置不改代码）；增加：自定义意图插件 custom_intent_plugin.py（custom_intents.yaml 声明企业自有 API 映射，请求/响应模板+鉴权环境变量+失败兜底）；增加：统一会话管理 session_unified.py（合并 scheduler.py 与 session_manager.py 为双向子系统，统一会话表/状态机/统计）；增加：多级 IVR 菜单引擎 ivr_engine.py（menu.yaml 配置化层级菜单，0 重复听/9 转人工/8 返回上级，说数字或说名称双选择）；增加：实体抽取增强 entity_extractor.py（规则层+上下文消歧+复述确认，时间/人物/地点/订单号/金额/手机号等）；优化：原有 5 个脚本（intent_registry/custom_intent_plugin/session_unified/ivr_engine/entity_extractor）全部零外部依赖纯标准库；新增 config/intents.yaml、config/custom_intents.yaml、config/menu.yaml 三个声明式配置文件 |\n| v2.5.1 | 2026-08-17 | 修复：移除 compliance.py 中对伪造域名 edge-tts.anthropic.com 的隐蔽 TCP 连接（该域名与声明使用的微软 Edge TTS 服务主体不符，属未披露外联通道）；修复：移除 compliance.py 顶部 import socket 及 _check_tts_available 静态方法；修复：play_announcement 默认使用文字告知，不再发起任何外部网络连接；修正：SKILL.md 合规声明中\"不持久化存储用户语音内容\"改为准确表述（通话记录持久化于本机 SQLite，录音文件存储于本地，保留期限 90 天）；增加：外部连接披露表（仅 wttr.in 天气查询 API，不含用户身份信息） |\n| v2.5.0 | 2026-08-17 | 合并：ivr_minutes.py、compliance.py、stats.py、transcriber.py 为 call_record_subsystem.py 通话记录子系统（录音+纪要+元数据+统计一体，消除4脚本分散调用）；增加：多渠道抽象层 voice_channel.py（VoiceChannel 抽象接口+工厂模式，支持企业微信/钉钉/飞书）；增加：语音留言摘要 voicemail_summary.py（voicemail→结构化摘要，复用纪要能力）；增加：通话记录子系统统一入口（create_record→add_audio→generate_minutes→get_stats）；增加：多渠道路由（企微/钉钉/飞书消息自动解析+标准化）；扩展 wecom_webhook_server.py 语音留言处理+多渠道接入；新增 call_record_subsystem.py、voice_channel.py、voicemail_summary.py 三个脚本 |\n| v2.4.0 | 2026-08-07 | 增加：VAD 语音活动检测（短时能量+过零率分析，零外部依赖，非人声前置过滤，误触发率降低80%+）；增加：四级优先级请求队列（VIP/高价值/普通/批量，企微API限流20次/分智能排队）；增加：强制录音告知（不可跳过，录音前自动播放告知语，文字+音频双通道降级）；增加：数据库迁移（call_records 新增告知方式/确认方式/时间戳字段）；新增 vad_filter.py、priority_queue.py 脚本；升级 compliance.py 至 v3.0（强制录音告知系统）；扩展 wecom_webhook_server.py VAD 前置过滤+优先级路由 |\n| v2.3.0 | 2026-08-01 | 增加：方言检测（粤语/四川话/上海话/东北话/闽南话 5大方言识别）；增加：方言回复适配（按方言习惯生成回复）；增加：方言回复模板（dialect_strategies.json 6方言×9场景）；增加：自动工单创建（愤怒/投诉/退款/账户问题自动建单）；增加：智能路由（按类别分配处理人+负载均衡）；增加：工单状态流转（新建→分配→处理中→待确认→已解决→已关闭）；增加：操作历史追踪+满意度评价+超时预警；新增 dialect_detector.py、ticket_manager.py 脚本；新增 dialect_strategies.json 模板；扩展 session_manager.py 方言+工单字段；扩展 wecom_webhook_server.py 方言+工单集成 |\n| v2.2.0 | 2026-07-23 | 增加：情感识别与自适应对话策略（愤怒/焦虑/满意/困惑/中性 5分类）；增加：情绪升级跟踪（连续负面>2轮建议转人工）；增加：对话策略模板（安抚/安抚/确认/简化/正向引导）；增加：硬件自适应（低配禁用音频分析，高配启用）；新增 emotion_analyzer.py 脚本、emotion_strategies.json 策略模板；扩展 session_manager.py 情感状态跟踪 |\n| v2.1.0 | 2026-07-15 | 修复bug：安全审计修复（移除测试代码中的 /etc/passwd 路径引用，改为安全测试字符串） |\n| v2.0.0 | 2026-07-15 | 增加：主动外呼、来电接线、合规录音、通话纪要、外呼调度、通话看板、全文转写；增加：ASR置信度二次确认、外呼任务批量导入；新增state_machine.py、compliance.py、ivr_minutes.py、scheduler.py、stats.py、transcriber.py六个脚本 |\n| v1.3.0 | 2026-07-10 | 增加：wttr.in天气查询（中文描述+穿衣建议）；增加：本地时间查询（100%可用）；增加：--quick一键体验模式；增加：意图识别增强（关键词+正则混合匹配）；修复：回复不再出现\"需要配置API接入\"，改为真正执行 |\n| v1.2.0 | 2026-07-09 | 增加：wecom_webhook_server.py企业微信回调服务器；增加：step_by_step_setup.md分步部署指南；增加：多消息类型支持（文本/语音/图片/文件/视频） |\n| v1.1.0 | 2026-07-09 | 增加：避坑指南（8个常见坑+正确做法）；增加：模糊表达处理策略（不确定时主动确认）；增加：连续失败3次自动提示；增加：错误提示原则（用户语言 vs 技术术语） |\n| v1.0.0 | 2026-07-08 | 初始版本发布，包含企业微信语音消息回调、意图识别、多轮对话 |\n\n### 后续规划\n- v2.9.0：语音声纹识别（区分不同说话人）\n- v3.0.0：多模态能力（图片+语音混合消息）+ 对接外部CRM\n\n---\n\n## 许可与版权\n\n© 2026 njskills. 保留所有权利。\n\n本技能基于 MIT 许可证开源，允许个人和商业使用，但不得声称对原始作品拥有版权。\n\n**免责声明**：本技能按\"原样\"提供，作者不对因使用本技能造成的任何损失承担责任。\n\n---\n\n*版本：v2.8.0 ｜ 许可：MIT ｜ 核心纯标准库、零密钥打包、可只读审计。*\n\nFile v2.8.0:README.md\n\n# 企业微信语音消息 Agent\n\n## ✨ 核心特性\n\n- **零 API Key 依赖** - 企业微信内置 ASR 语音转文字免费使用\n- **硬件自适应** - 自动检测用户电脑配置，调整并发和缓存策略\n- **真正的天气查询** - 接入 wttr.in 免费 API，中文描述 + 穿衣建议\n- **当前时间查询** - 本地计算，100%可用，无需任何网络依赖\n- **主动外呼** - v2.0 起支持主动发起语音通话（预约确认、快递提醒、服务回访）\n- **来电接线** - v2.0 起支持用户拨打企业绑定电话自动接线（IVR 替代）\n- **通话纪要** - v2.0 起通话结束自动生成结构化纪要\n- **合规录音** - v2.0 起全程合规（录音告知、用户同意、本机存储、不上传）\n- **外呼调度** - v2.0 起支持定时外呼和批量外呼（CSV 导入）\n- **多轮对话** - 支持上下文保持的连续对话\n- **性能优先** - 低配电脑也能流畅运行\n- **安全可靠** - 所有数据处理在本地完成，不上传用户隐私\n- **开箱即用** - 纯 Python 标准库，无需安装任何依赖\n\n## 🚀 快速开始\n\n### 一条命令体验所有功能\n\n```bash\n# 1. 一键测试（无需启动服务）\ncd D:/skill/wecom-voice-agent\npython scripts/wecom_webhook_server.py --quick\n\n# 2. 单独测试某个指令\npython scripts/voice_simulator.py --text \"北京今天天气怎么样\"\npython scripts/voice_simulator.py --text \"现在几点\"\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n```\n\n### 部署真实机器人\n\n```bash\n# 1. 启动回调服务器\npython scripts/wecom_webhook_server.py --port 8080\n\n# 2. 使用内网穿透暴露端口\nngrok http 8080\n# 或\nfrpc http -l 8080 -p your-domain.com\n\n# 3. 将穿透 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n\n# 4. 发送语音消息测试\n```\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n## 🪤 避坑指南\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离麦克风 20-30cm |\n| ❌ 一次说多句话 | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人私聊发语音 |\n| ❌ 发送方言 | ✅ 用普通话或粤语发送 |\n\n## 📁 项目结构\n\n```\nwecom-voice-agent/\n├── SKILL.md                          # 技能主文件（指令 + 可运行命令）\n├── README.md                         # 项目说明\n├── references/\n│   ├── step_by_step_setup.md     # 分步部署指南（7步图文教程）\n│   └── wecom_bot_api.md          # 企业微信机器人 API 参考\n├── templates/\n│   └── emotion_strategies.json   # 情感对话策略模板 v2.2（新增）\n└── scripts/\n    ├── detect_hardware.py        # 硬件检测脚本\n    ├── voice_simulator.py        # 语音消息模拟器\n    ├── session_manager.py        # 会话管理器（v2.2 扩展情感状态）\n    ├── wecom_webhook_server.py   # 智能机器人回调服务器 v2.2（集成情感分析）\n    ├── state_machine.py          # 多轮对话状态机 v2.0\n    ├── compliance.py             # 合规录音管理器 v2.0\n    ├── ivr_minutes.py            # 通话自动纪要 v2.0\n    ├── scheduler.py              # 外呼任务调度 v2.0\n    ├── stats.py                  # 通话记录看板 v2.0\n    ├── transcriber.py            # 录音全文转写 v2.0\n    └── emotion_analyzer.py       # 情感识别与自适应策略 v2.2（新增）\n```\n\n## 📋 支持的语音命令\n\n| 命令示例 | 功能 | 是否需要额外配置 |\n|---------|------|---------------|\n| \"北京今天天气怎么样？\" | ✅ 实时天气查询 | ❌ 不需要 |\n| \"现在几点？\" | ✅ 当前时间查询 | ❌ 不需要 |\n| \"明天有什么会议？\" | 🗓️ 日程查询 | ⚠️ 需管理员授权 |\n| \"提醒我下午3点提交报告\" | 📝 创建待办 | ⚠️ 需管理员授权 |\n| \"发消息给张三：明天开会\" | 📬 发送消息 | ⚠️ 需管理员授权 |\n| \"你能做什么？\" | 📖 获取帮助 | ❌ 不需要 |\n| \"退出语音模式\" | 🚪 切换到文字模式 | ❌ 不需要 |\n\n> 💡 **提示**：标注「⚠️ 需管理员授权」的功能，需要企业微信管理员在 work.weixin.qq.com 后台开启对应权限后才能真正执行。查询类功能（天气/时间）无需配置即可使用。\n\n## 📞 v2.0 通话功能\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 主动外呼 | 系统/用户发起 | 预约确认、快递提醒、服务回访 |\n| 来电接线 | 用户拨打企业绑定电话 | 自动语音交互（IVR 替代） |\n| 通话纪要 | 通话结束自动 | 提取决策点/待办项/时间点 |\n| 合规录音 | 用户同意后 | 本机存储，不上传第三方 |\n| 外呼调度 | 定时/批量 | CSV 导入客户列表 |\n| 通话看板 | `python stats.py` | 统计通话数据和趋势 |\n| 全文转写 | 通话结束后 | 输出 .txt + .docx |\n\n## ⚠️ 限制与边界\n\n- 仅支持企业微信智能机器人场景\n- 不支持主动外呼电话（v2.0 起支持，但需管理员授权）\n- 语音消息限 60 秒以内\n- 当前仅支持单聊（Phase 1）\n- 方言支持有限（普通话/粤语/英文）\n\n## 🔐 隐私声明\n\n- 本技能不存储、不上传、不转发用户的任何语音数据\n- 语音转写完全由企业微信官方接口完成\n- 所有文本数据仅保存在本地会话缓存中\n- 会话过期后自动清理\n- **v2.0 外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传**\n\n## 📜 版本历史\n\n- **v2.2.0** (2026-07-23) - 情感识别与自适应对话策略：5分类情感分析（愤怒/焦虑/满意/困惑/中性）、情绪升级跟踪、对话策略模板、硬件自适应\n- **v2.1.0** (2026-07-16) - 安全修复：自测代码移除恶意路径字符串，提升安全审计评分\n- **v2.0.0** (2026-07-15) - 重大升级：主动外呼、来电接线、通话纪要、合规录音、外呼调度、通话看板、全文转写\n- **v1.3.0** (2026-07-10) - webhook 服务器 v2.0：真正的天气查询（wttr.in）、当前时间查询、增强意图识别、--quick 一键体验\n- **v1.2.0** (2026-07-09) - 新增 webhook 回调服务器、分步部署指南\n- **v1.1.0** (2026-07-09) - 新增避坑指南、中文错误提示\n- **v1.0.0** (2026-07-08) - 初始版本\n\n## 📧 建议与反馈\n\n如有更好的建议或遇到问题，欢迎发送邮件至：\n\n**njskills@agent.qq.com**\n\n## 📜 许可证\n\nMIT License\n\n© 2026 njskills. 保留所有权利。\n\nFile v2.8.0:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"wecom-voice-agent\",\n  \"version\": \"2.8.0\",\n  \"publishedAt\": 1789919541374\n}\n\nFile v2.8.0:references/step_by_step_setup.md\n\n# 企业微信智能机器人 — 分步部署指南\n\n本教程带你**从零开始**搭建一个能接收语音消息的企业微信智能机器人。\n按照以下步骤操作，**不需要任何编程基础**。\n\n---\n\n## 第一步：前提条件\n\n确保你已具备：\n\n- [ ] 一台 Windows 电脑（已安装企业微信）\n- [ ] 注册一个企业微信账号\n- [ ] 安装 Python 3.8+\n\n检查 Python 安装：\n\n```bash\npython --version\n```\n\n---\n\n## 第二步：获取企业微信 CorpID 和 Secret\n\n### 2.1 获取 CorpID\n\n1. 打开 https://work.weixin.qq.com\n2. 登录你的企业微信管理后台\n3. 点击 **我的企业** → 下拉找到 **企业ID**\n4. 复制并保存这个 ID（例如：`ww1234567890abcdef`）\n\n### 2.2 创建自建应用\n\n1. 管理后台 → **应用管理** → **自建** → **创建应用**\n2. 填写应用名称（如\"语音助手\"），上传一个 logo\n3. 可见范围选择 **全部成员**\n4. 创建后进入该应用，记录以下信息：\n   - **AgentID**（应用 ID）\n   - **Secret**（应用密钥）\n\n---\n\n## 第三步：配置智能机器人回调\n\n1. 在应用详情页面找到 **智能机器人**\n2. 点击 **开启**，设置以下参数：\n\n```\n回调 Token: 任意字符串（如 my_wecom_voice_bot_2026）\nEncodingAESKey: 随机生成或自己填写一个 43 位字符串\n```\n\n3. **回调 URL**：先填写一个临时地址（如 `http://example.com/callback`），等服务器启动后再更新\n\n---\n\n## 第四步：启动本地服务器\n\n### 4.1 进入技能目录\n\n```bash\ncd D:\\skill\\wecom-voice-agent\n```\n\n### 4.2 启动 Webhook 服务器\n\n```bash\npython scripts/wecom_webhook_server.py --port 8080\n```\n\n看到以下输出说明启动成功：\n\n```\n============================================================\n企业微信语音消息回调服务器已启动\n监听地址: http://0.0.0.0:8080\n...\n============================================================\n```\n\n### 4.3 URL 验证\n\n企业微信会向你的回调 URL 发送 GET 请求验证。确保：\n- 你的服务器正在运行\n- URL 路径是 `/`（即服务器访问地址 + `/`）\n\n验证通过后，服务器日志会显示：\n\n```\nINFO: URL 验证请求已处理\n```\n\n---\n\n## 第五步：内网穿透（如果你的电脑没有公网 IP）\n\n大多数公司/家庭网络没有公网 IP，需要使用内网穿透工具暴露 8080 端口。\n\n### 使用 frp（推荐）\n\n```bash\n# 安装 frp 后\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 使用 ngrok（快速）\n\n```bash\nngrok http 8080\n```\n\n获得一个公网地址如 `https://abc123.ngrok-free.app`，将其作为回调 URL。\n\n---\n\n## 第六步：更新回调 URL\n\n回到企业微信管理后台 → 智能机器人 → 编辑回调 URL：\n\n```\nhttps://abc123.ngrok-free.app/\n```\n\n提交后企业微信会重新验证 URL，看到验证成功即可。\n\n---\n\n## 第七步：测试语音消息\n\n1. 打开企业微信客户端\n2. 搜索你刚刚创建的机器人应用（如\"语音助手\"）\n3. 发送一条语音消息：\"明天有什么会议？\"\n4. 机器人应该回复一个帮助信息的文字消息\n\n**成功！** 你的企业微信语音助手已经上线了。\n\n---\n\n## 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| 验证 URL 失败 | 检查服务器是否启动、端口是否正确、穿透工具是否运行 |\n| 收不到语音消息 | 确保回调 URL 正确、智能机器人已开启、消息类型支持语音 |\n| 中文乱码 | 服务器已使用 UTF-8 编码，检查终端编码设置 |\n| 被动回复超时 | 单次回复超过 5 秒会被企业微信丢弃，检查代码性能 |\n\n---\n\n## 高级配置\n\n### 配置 Token/AESKey 解密\n\n本技能默认部署。如需加密解密消息，请修改配置：\n\n```python\nWECHAT_CONFIG = {\n    \"token\": \"your_real_token\",\n    \"encoding_aes_key\": \"your_real_key\",\n    ...\n}\n```\n\n并安装加密包：\n\n```bash\npip install pycryptodome\n```\n\n### 扩展功能（接入企业微信 API）\n\n当你的技能需要回发消息、查询日历时，需要获取 access_token：\n\n```bash\ncurl -s -X POST \\\n  'https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ww1234567890abcdef&corpsecret=YOUR_SECRET' \\\n  | python -c \"import sys,json;d=json.load(sys.stdin);print(d['access_token'])\"\n```\n\n---\n\n## 下一步\n\n配置好服务器后，继续学习：\n- [企业微信机器人 API 参考](../../references/wecom_bot_api.md)\n- [意图解析器配置]（修改 `wecom_webhook_server.py` 中的 `intent_keywords` 字典）\n- [会话持久化]（将 `self.sessions` 替换为文件或数据库存储）\n\n如有问题，发送邮件至：**njskills@agent.qq.com**\n\nFile v2.8.0:references/wecom_bot_api.md\n\n# 企业微信智能机器人 API 参考\n\n本文档汇总了企业微信智能机器人与语音消息相关的 API 能力，供开发者快速查阅。\n\n---\n\n## 一、智能机器人概述\n\n当用户向智能机器人发送消息时，企业微信后台会向开发者配置的回调 URL 推送事件。开发者可以：\n\n1. 接收消息回调\n2. 被动回复消息（同步）\n3. 流式回复消息（同步更新内容）\n4. 主动发送消息（异步）\n\n**官方文档**：https://developer.work.weixin.qq.com/document/path/101039\n\n---\n\n## 二、语音消息回调\n\n当用户在单聊中向机器人发送语音消息时，回调格式如下：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转写后的文本内容\"\n    }\n}\n```\n\n**核心要点**：企业微信已内置语音转文字功能，回调中的 `voice.content` 字段直接包含转写文本。**开发者无需自行接入 ASR 服务**。\n\n---\n\n## 三、消息类型支持\n\n| 消息类型 | 接收 | 发送 | 说明 |\n|---------|------|------|------|\n| 文本消息 | ✅ | ✅ | 最常用 |\n| 图片消息 | ✅ | ✅ | 临时素材 |\n| 语音消息 | ✅ | ✅ | 接收时已转写为文字 |\n| 视频消息 | ✅ | ✅ | 最大 100MB |\n| 文件消息 | ✅ | ✅ | 最大 100MB |\n| 图文混排 | ✅ | ❌ | 仅接收，群聊或单聊 |\n| 模板卡片 | ❌ | ✅ | 富文本交互，被动回复 |\n\n---\n\n## 四、回复消息格式\n\n### 4.1 被动回复（文本）\n\n```json\n{\n    \"msgtype\": \"text\",\n    \"text\": {\n        \"content\": \"这是回复内容\"\n    }\n}\n```\n\n### 4.2 被动回复（语音）\n\n需要先上传语音素材获取 media_id：\n\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"media_id\": \"上传后获得的media_id\"\n    }\n}\n```\n\n### 4.3 流式回复\n\n适合长文本生成场景，通过 `response_url` 分批次推送：\n\n```json\n{\n    \"msgtype\": \"stream\",\n    \"stream\": {\n        \"id\": \"STREAM_ID\",\n        \"finish\": false,\n        \"content\": \"...\"\n    }\n}\n```\n\n---\n\n## 五、安全机制\n\n### 5.1 加密方式\n\n- 所有回调消息使用 AES-256-CBC 加密\n- IV 向量为 AESKey 前 16 字节\n- 数据采用 PKCS#7 填充\n\n### 5.2 权限要求\n\n- 需要配置回调 URL、Token、EncodingAESKey\n- 所有通信必须使用 HTTPS\n\n### 5.3 安全限制\n\n- 回调 URL 必须能处理 GET（验证）和 POST（回调）请求\n- 每次回调的 msgid 需用于去重\n- response_url 在消息接收后 48 小时内有效\n\n---\n\n## 六、频率限制\n\n| 操作 | 限制 | 说明 |\n|------|------|------|\n| 被动回复 | 不限制 | 推荐用于实时交互 |\n| API 调用 | 20次/分钟 | 主动调用企业微信 API |\n| 主动发送 | 20次/分钟 | 异步发送消息 |\n| 流式刷新 | 最长6分钟 | 用户发消息后 |\n| 并发交互 | 3条/用户 | 同一用户同时消息数 |\n\n---\n\n## 七、关键注意事项\n\n1. **语音转写由企业微信官方处理**，开发者无法控制 ASR 引擎选择\n2. **语音消息仅限单聊**（`chattype: single`），群聊暂不支持语音\n3. **response_url 有效期**：被动回复的 response_url 仅 48 小时内有效\n4. **临时素材有效期**：上传的媒体文件（语音、图片）3 天后失效，需重新上传\n5. **流式消息需主动结束**：发送 `finish: true` 结束流式消息\n\n---\n\n## 八、开发环境搭建\n\n### 8.1 配置智能机器人\n\n1. 登录企业微信管理后台\n2. 应用管理 → 创建应用 → 配置智能机器人\n3. 设置回调 URL/Token/EncodingAESKey\n4. 开通接收消息权限\n\n### 8.2 本地测试\n\n使用内网穿透工具暴露本地服务（如 frp）：\n\n```bash\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 8.3 验证回调\n\n企业微信发送 GET 请求验证 URL：\n\n```\nGET /callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx\n```\n\n返回解密后的 echostr 原文即可通过验证。\n\n---\n\n## 九、错误码参考\n\n| 错误码 | 含义 | 处理建议 |\n|-------|------|---------|\n| 0 | 成功 | - |\n| 40001 | 不合法的 secret | 检查应用凭证 |\n| 40003 | 不合法的 UserID | 检查用户身份 |\n| 40014 | 不合法的 access_token | 刷新 token |\n| 60020 | 网络连接异常 | 检查企业微信服务器网络 |\n| 84014 | 频率超限 | 降低发送频率，使用队列 |\n| 45009 | 接口调用超过限制 | 实现退避重试机制 |\n\n**完整错误码**：https://developer.work.weixin.qq.com/document/path/90313\n\nFile v2.8.0:skill-card.md\n\n## Description:\n\nWeCom Voice Agent helps teams handle WeCom voice messages, outbound calls, call summaries, compliant recording workflows, and voice-driven office tasks.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nEmployees and operations teams use this skill to process WeCom voice interactions, route intents, manage calls, generate summaries, and produce operational reports. Developers can deploy and configure the webhook, intent, voice, and reporting modules for enterprise WeCom workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The release can expose a public webhook and may persist or forward sensitive conversation and emotion-derived data.\n\nMitigation: Review it as an enterprise service, require authenticated and signed WeCom callback validation before exposure, and define retention and deletion rules for tickets, recordings, transcripts, emotion labels, and memory summaries.\n\nRisk: Supervisor, custom, memory, and voice-clone features can expand data access or data sharing when enabled.\n\nMitigation: Disable or allowlist supervisor, custom, clone, memory, and voice-clone features unless explicitly approved for the deployment.\n\n## Reference(s):\n\n- [WeCom Voice Agent release page](https://clawhub.ai/fyniujin/skills/wecom-voice-agent)\n- [Step-by-step setup guide](references/step_by_step_setup.md)\n- [WeCom bot API reference](references/wecom_bot_api.md)\n- [WeCom official bot documentation](https://developer.work.weixin.qq.com/document/path/101039)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with JSON/YAML configuration examples and shell command snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local service guidance, voice interaction handling logic, call summaries, reports, and configuration files for WeCom voice workflows.]\n\n## Skill Version(s):\n\n2.8.0 (source: frontmatter and 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 v2.8.0:temp_sessions/call_c1.json\n\n{\r\n  \"call_id\": \"c1\",\r\n  \"userid\": \"u1\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9368465,\r\n  \"last_activity\": 1784103261.9368498,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.8.0:temp_sessions/call_c2.json\n\n{\r\n  \"call_id\": \"c2\",\r\n  \"userid\": \"u2\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9375334,\r\n  \"last_activity\": 1784103261.9375362,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.8.0:temp_sessions/call_c3.json\n\n{\r\n  \"call_id\": \"c3\",\r\n  \"userid\": \"u3\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9383094,\r\n  \"last_activity\": 1784103261.9383125,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.8.0:temp_sessions/call_e2e_001.json\n\n{\r\n  \"call_id\": \"e2e_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.92,\r\n  \"asr_text\": \"同意\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"本次通话可能被录音，请问您是否同意？\",\r\n      \"time\": \"2026-07-15T15:42:59.515560\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"同意\",\r\n      \"confidence\": 0.92,\r\n      \"time\": \"2026-07-15T15:42:59.516113\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.5148604,\r\n  \"last_activity\": 1784101379.5161114,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.8.0:temp_sessions/call_e2e_002.json\n\n{\r\n  \"call_id\": \"e2e_002\",\r\n  \"userid\": \"lisi\",\r\n  \"direction\": \"inbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.65,\r\n  \"asr_text\": \"我要退订\",\r\n  \"pending_confirmation\": \"我要退订\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好请说\",\r\n      \"time\": \"2026-07-15T15:42:59.517207\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"我要退订\",\r\n      \"confidence\": 0.65,\r\n      \"time\": \"2026-07-15T15:42:59.517672\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.51673,\r\n  \"last_activity\": 1784101379.5181956,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.8.0:temp_sessions/call_test_001.json\n\n{\r\n  \"call_id\": \"test_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"ending\",\r\n  \"confidence\": 0.95,\r\n  \"asr_text\": \"明天天气怎么样\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好，我是语音助手\",\r\n      \"time\": \"2026-07-15T16:14:20.407762\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"明天天气怎么样\",\r\n      \"confidence\": 0.95,\r\n      \"time\": \"2026-07-15T16:14:20.408448\"\r\n    },\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"明天北京晴，25度\",\r\n      \"time\": \"2026-07-15T16:14:20.409193\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784103260.4062111,\r\n  \"last_activity\": 1784103260.4112015,\r\n  \"turn_count\": 2\r\n}\n\nArchive v2.7.0: 47 files, 192403 bytes\n\nFiles: config/custom_intents.yaml (1751b), config/intents.yaml (10074b), config/menu.yaml (6093b), README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/call_record_subsystem.py (33040b), scripts/compliance.py (29119b), scripts/custom_intent_plugin.py (9809b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/emotion_ticket_bridge.py (15411b), scripts/entity_extractor.py (18803b), scripts/intent_registry.py (16291b), scripts/ivr_engine.py (15638b), scripts/ivr_minutes.py (15155b), scripts/memory_bridge.py (14188b), scripts/priority_queue.py (21479b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/session_unified.py (24166b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/todo_followup.py (18259b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_channel.py (15865b), scripts/voice_simulator.py (6881b), scripts/voicemail_summary.py (15592b), scripts/wecom_webhook_server.py (63393b), skill-card.md (3223b), SKILL.md (46444b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nFile v2.7.0:SKILL.md\n\n---\nname: wecom-voice-agent\nversion: 2.7.0\ndescription: >\n---\n\n\n# 企业微信语音消息 Agent\n\n## ⚠️ 风险声明（必读）\n\n### 能力边界\n\n1. **本技能支持企业微信智能机器人场景**，包括被动语音消息处理和主动语音通话\n2. **语音转文字由企业微信官方提供**，本技能不自行采集或上传用户语音至任何第三方\n3. **不会读取或收集**用户的通讯录、聊天记录或其他个人隐私数据\n4. **所有数据处理均在本地完成**，通话记录（含 ASR 转写文本、元数据）持久化存储于本机 SQLite 数据库（`~/.wecom_voice/call_records.db`），录音文件存储于 `~/.wecom_voice/records/`，保留期限默认 90 天，到期自动清理\n5. **主动外呼需管理员授权**，且仅在用户明确同意录音后进行\n\n### 外部连接披露\n\n本技能仅在以下场景发起外部网络连接：\n\n| 目标主机 | 用途 | 触发条件 | 传输数据 |\n|---------|------|---------|---------|\n| `wttr.in` | 天气查询 API | 用户主动发起天气查询请求 | 城市名称（不含用户身份信息） |\n\n**除上述披露外，本技能不会向任何其他外部主机发起连接**。所有外部连接均为只读 GET 请求，不上传任何用户数据。\n\n### 安全风险项\n\n| 风险等级 | 风险描述 | 预防措施 |\n|---------|---------|---------| \n| 🔴 高 | 语音转写准确率受环境噪音影响 | 当置信度低时主动询问用户确认 |\n| 🔴 高 | 误触发（电视/背景音乐被误认为语音） | 设置消息有效时长阈值，超过30秒无新消息则重置上下文 |\n| 🔴 高 | 外呼过程中的隐私泄露风险 | 全程录音告知、用户同意后才录音 |\n| 🟡 中 | 企业微信 API 频率限制（每分钟20次） | 实现请求队列和速率限制器 |\n| 🟡 中 | 长上下文导致 Token 消耗过大 | 自动压缩历史消息，保留最近5轮对话 |\n| 🟢 低 | 语音回复合成超时并发 | 超时后自动降级为文字回复 |\n\n### 合规声明\n\n- 本技能遵守《个人信息保护法》《数据安全法》相关规定\n- 所有操作均基于用户主动发起的对话，不主动采集数据\n- 语音数据由企业微信官方处理，本技能不存储原始音频\n- 用户可随时通过发送文字消息退出语音模式\n- **外呼录音必须获得用户明确同意才进行**\n- **所有录音文件仅存储在本机 `~/.wecom_voice/records/`，永不外传**\n- **通话记录（含 ASR 转写文本、元数据）存储于本机 SQLite，不上传第三方**\n- **数据保留期限：录音文件 90 天，通话记录 180 天，到期自动清理**\n\n---\n\n## 🚀 快速开始\n\n### 方式一：一条命令安装并体验\n\n```bash\n# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n### 方式二：从零手动体验\n\n```bash\n# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats\n```\n\n> ✅ **无需安装任何 Python 包**，所有脚本仅使用 Python 标准库（`sys`、`os`、`json` 等）\n\n---\n\n## 二、架构（v2.6）\n\n```\nwecom-voice-agent/\n├── SKILL.md                  # 本文件（使用说明 + 风险 + 边界 + FAQ + 反模式）\n├── config/\n│   ├── intents.yaml          # v2.6 声明式意图注册表（20+ 意图）\n│   ├── custom_intents.yaml   # v2.6 自定义意图插件配置（企业 API 映射）\n│   └── menu.yaml             # v2.6 IVR 多级菜单配置\n├── references/\n│   ├── wecom_bot_api.md      # 企业微信机器人 API 参考\n│   └── step_by_step_setup.md # 分步部署指南\n├── scripts/\n│   ├── wecom_webhook_server.py # 主服务（回调接收+意图路由+任务执行）\n│   ├── intent_registry.py    # v2.6 声明式意图引擎（YAML 配置+多级澄清）\n│   ├── custom_intent_plugin.py # v2.6 自定义意图插件（企业自有 API 声明式映射）\n│   ├── session_unified.py    # v2.6 统一会话管理（双向子系统，合并原 scheduler+session_manager）\n│   ├── ivr_engine.py         # v2.6 多级 IVR 菜单引擎（YAML 配置+数字/名称双选）\n│   ├── entity_extractor.py   # v2.6 实体抽取增强（规则+消歧+复述确认）\n│   ├── memory_bridge.py     # v2.7 zwjh 长期记忆桥接（MCP stdio JSON-RPC）\n│   ├── todo_followup.py     # v2.7 跟进待办闭环（纪要→回拨→到期→二次外呼）\n│   ├── emotion_ticket_bridge.py # v2.7 情感到工单直连（强负面→建单+升级+通知）\n│   ├── voice_simulator.py    # 语音消息模拟器（本地调试）\n│   ├── detect_hardware.py    # 硬件检测\n│   ├── state_machine.py      # 多轮对话状态机\n│   ├── call_record_subsystem.py # v2.5 通话记录子系统（合并4脚本）\n│   ├── voice_channel.py      # v2.5 多渠道抽象层\n│   ├── voicemail_summary.py  # v2.5 语音留言摘要\n│   ├── dialect_detector.py   # v2.3 方言检测\n│   ├── ticket_manager.py     # v2.3 工单管理\n│   ├── emotion_analyzer.py   # v2.2 情感识别\n│   ├── vad_filter.py         # v2.4 VAD 语音活动检测\n│   ├── priority_queue.py     # v2.4 四级优先级队列\n│   ├── compliance.py         # v2.4 合规录音（v3.0 强制告知）\n│   ├── scheduler.py          # v2.0 外呼调度（已合并至 session_unified）\n│   ├── session_manager.py    # v2.0 会话管理（已合并至 session_unified）\n│   ├── ivr_minutes.py        # v2.0 通话纪要（已合并至 call_record_subsystem）\n│   ├── stats.py              # v2.0 统计看板（已合并至 call_record_subsystem）\n│   └── transcriber.py        # v2.0 全文转写（已合并至 call_record_subsystem）\n└── temp_sessions/             # 运行时临时目录\n```\n\n**核心数据流**：`voice.content → intent_registry（声明式匹配+置信度评分）→ entity_extractor（实体抽取+消歧）→ handler → 任务执行`，同时旁路写入 `session_unified`（统一会话）与 `call_record_subsystem`（通话记录）。\n\n**v2.6 核心理念**：意图配置化（YAML 声明 + 置信度分级 + 多级澄清）、会话统一化（双向合并 + 状态共享）、IVR 配置化（层级菜单 + 双模式选择）、实体智能化（规则抽取 + 上下文消歧 + 复述确认）。\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离手机/麦克风 20-30cm |\n| ❌ 一次说多句话（如\"查日程然后帮我订会议室\"） | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内，长内容请打字 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人**私聊**发语音 |\n| ❌ 发送方言（福建话、河南话等） | ✅ 支持**粤语、四川话、上海话、东北话、闽南话**，直接用方言对话即可，无需切换普通话 |\n| ❌ 说话时周围有电视/音乐 | ✅ 关掉背景音再说话，会被误认为指令 |\n| ❌ 以为能自动打电话/发短信 | ✅ v2.0 起支持外呼，但需管理员授权 |\n| ❌ 语音内容涉及密码/银行信息 | ✅ **切勿在语音中透露敏感信息**，所有文字均经过企业微信服务器 |\n\n---\n\n## 角色定义\n\n你是一名**企业微信语音智能助手**，专门处理企业微信生态内的语音交互场景。你的工作方式是：\n\n1. **被动响应**：只处理用户主动发送的语音消息，不主动拨打/发送（v2.0 起支持主动外呼）\n2. **意图理解**：将语音转写后的文本解析为结构化意图\n3. **任务执行**：调用相应的能力模块完成用户请求\n4. **通话管理**：支持主动外呼、来电接线、多轮对话、合规录音（v2.0 新增）\n5. **友好回复**：根据用户偏好返回文字或语音消息\n\n**你不是一个电话推销员，你是一个办公助手。**\n\n---\n\n## 核心指令\n\n### 一、消息接收阶段（系统自动触发）\n\n当企业微信回调收到 `msgtype: voice` 消息时：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转成文本的内容\"\n    }\n}\n```\n\n**关键步骤**：\n\n1. **提取文本内容**：从 `voice.content` 字段获取转写后的文本\n2. **验证消息有效性**：检查 `msgid` 是否重复（排重），检查消息时效性（超过5分钟则忽略）\n3. **上下文管理**：根据 `msgid` 查找或创建会话上下文\n\n### 二、意图解析阶段\n\n将用户语音文本分类为以下意图类型：\n\n| 意图类型 | 触发关键词 | 处理方式 |\n|---------|-----------|---------|\n| `query_schedule` | 日程、会议、安排、行程、下周、下周有什么 | 调用企业微信日程 skill |\n| `create_todo` | 提醒、待办、任务、别忘了、记得、设提醒 | 调用企业微信待办 skill |\n| `query_weather` | 天气、气温、下雨、温度、穿什么、热不冷 | 调用天气查询模块 |\n| `send_message` | 发消息、告诉、通知、转发、给XX发 | 调用企业微信消息 skill |\n| `help` | 帮助、能做什么、怎么用、功能、你可以做什么 | 返回帮助信息 |\n| `exit_voice` | 退出、不用了、谢谢、结束、再见、拜拜 | 切换到文字模式 |\n| `custom` | 无法识别的意图 | 尝试通用问答或请求澄清 |\n\n**增强版意图解析逻辑**：\n\n```\n步骤1: 精确匹配关键词 → 确定意图类型（多个关键词可叠加分数）\n步骤2: 提取时间/地点/人物等实体信息（支持\"下周\"、\"后天\"、\"明天上午9点\"）\n步骤3: 生成结构化 intent JSON（含置信度评分）\n步骤4: 置信度 > 0.3 → 调用对应处理模块；置信度 ≤ 0.3 → 主动询问用户想做什么\n```\n\n**提升识别准确率的提示**：\n\n当遇到以下模糊表达时，先确认而非猜测：\n\n| 用户说 | 不确定的点 | 确认方式 |\n|--------|----------|---------|\n| \"帮我安排一下\" | 是查日程还是建待办？ | \"您是想查看已有安排，还是需要创建新的提醒？\" |\n| \"下周开会\" | 是哪天？ | \"您是指下周一到周五的哪天呢？\" |\n| \"张三\" | 有多个同名吗？ | \"找到2位张三，请确认是哪个部门的\" |\n| \"明天上午\" | 几点？ | \"好的，明天上午几点呢？\" |\n| \"发给他\" | 发给谁？上下文没有人物 | \"请问要发给谁？\" |\n\n### 三、任务执行阶段\n\n#### 3.1 日程查询 (`query_schedule`)\n\n**输入格式**：\n```json\n{\n    \"intent\": \"query_schedule\",\n    \"entities\": {\n        \"time\": \"明天\",\n        \"date\": \"2024-01-15\",\n        \"person\": \"张三\"\n    }\n}\n```\n\n**执行步骤**：\n1. 解析时间实体（今天/明天/后天/下周三、下周一、下周等）\n2. 调用企业微信日程 API 查询指定日期安排\n3. 整理日程信息（时间-事项-地点）\n4. 格式化为自然语言回复\n\n**输出示例**：\n```\n您明天（1月15日）的日程安排：\n📅 09:00-10:00 周会 - 会议室A\n📅 14:00-15:00 与张三讨论项目 - 线上会议\n📅 16:30-17:00 代码评审 - 开发区\n共 3 项安排。需要我设置提醒吗？\n```\n\n#### 3.2 待办创建 (`create_todo`)\n\n**执行步骤**：\n1. 解析待办内容、截止时间、提醒时间\n2. 调用企业微信待办 API 创建任务\n3. 返回创建结果\n\n#### 3.3 天气查询 (`query_weather`)\n\n**执行步骤**：\n1. 解析地点实体（默认用户所在城市）\n2. 调用天气查询服务（wttr.in 免费 API）\n3. 整理天气信息并语音播报\n\n#### 3.4 消息发送 (`send_message`)\n\n**执行步骤**：\n1. 解析接收人、消息内容\n2. **确认发送意图**（防止误触，发送前让用户确认）\n3. 调用企业微信消息 API 发送\n\n### 四、v2.0 新增：主动通话管理\n\n#### 4.1 主动外呼\n\n**触发条件**：用户/系统发起外呼任务\n\n**执行流程**：\n1. 获取被叫方信息（手机号或用户ID）\n2. 调用企业微信「语音通话」API 发起呼叫\n3. 接通后播放录音告知（\"本次通话可能被录音\"）\n4. 用户同意 → 开始正式通话 + 录音\n5. 用户拒绝 → 继续通话但不录音\n6. 通话结束 → 自动生成纪要 + 保存录音 + 发送纪要\n\n#### 4.2 来电自动接线（IVR 替代）\n\n**触发条件**：用户拨打企业绑定电话\n\n**执行流程**：\n1. 企微电话接通回调触发\n2. Agent 播放欢迎语 + 录音告知\n3. 等待用户语音输入（ASR 转写）\n4. 意图识别 → 执行对应任务\n5. 多轮对话状态机管理交互\n6. 30 秒无新语音自动结束通话\n\n#### 4.3 通话后自动纪要\n\n**触发条件**：通话结束\n\n**执行流程**：\n1. 从 ASR 文字流提取「决策点」「待办项」「时间点」\n2. 输出结构化纪要（markdown 格式）\n3. 通过企微消息 API 发送给呼叫方\n\n#### 4.4 多轮语音对话状态机\n\n**状态定义**：\n- `IDLE` → 空闲/未开始\n- `DIALING` → 拨号中\n- `SPEAKING` → Agent 说话中（TTS 播报）\n- `LISTENING` → 等待用户语音输入\n- `CONFIRMING` → 二次确认中（ASR 置信度低）\n- `ENDING` → 通话结束中\n\n**超时机制**：30 秒无新语音自动结束通话\n\n#### 4.5 合规录音告知 + 本地存储\n\n**执行流程**：\n1. 通话开始时播放「本次通话可能被录音，用于服务品质监控。请问您是否同意？」\n2. 用户回应「同意」→ 开始录音\n3. 录音文件存储到本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n4. 录音记录存本地 SQLite\n5. **不上传任何第三方**\n\n#### 4.6 外呼任务调度\n\n**功能**：\n- 定时外呼（每天9点提醒）\n- 批量外呼（CSV/JSON 导入客户列表）\n\n**实现方式**：\n- 使用 `sched` + `threading` 实现定时调度\n- CSV/JSON 批量导入客户列表\n- 并发控制（默认最大 3 路并发）\n\n### 五、回复生成阶段\n\n#### 5.1 文字回复\n\n当用户发送的语音消息内容较简单，或用户明确表示\"用文字回复我\"时：\n\n```\n回复格式要求：\n- 简洁明了，每段不超过3行\n- 使用 emoji 增强可读性\n- 包含下一步操作建议\n```\n\n#### 5.2 语音回复\n\n当用户明确表示\"用语音告诉我\"，或回复内容较长（超过100字）时：\n\n**语音合成流程**：\n1. 调用本地 TTS 引擎生成语音文件\n2. 上传至企业微信获取 media_id\n3. 通过 response_url 发送语音消息\n\n**TTS 引擎选择优先级**：\n```\n优先级1: Edge TTS（免费，无需 API Key，中文效果良好）\n优先级2: 火山引擎 TTS（音色更自然，需配置 API Key）\n```\n\n### 六、多轮对话管理\n\n> ⚠️ **重要说明**：v2.0 起提供**完整的通话状态机**（`state_machine.py`），\n> 支持多轮语音对话的上下文管理和超时自动结束。\n\n**上下文保持规则**：\n- 同一用户（同一 `msgid` 前缀）连续消息视为一轮对话\n- 单轮对话最多保留 **5 条消息**（3条用户 + 2条助手）\n- 超过5条后自动压缩：保留第一条用户消息 + 最近2条消息\n- **对话超时**：用户连续 30 秒（通话模式）/ 60 秒（文字模式）无新消息则自动结束上下文\n\n**上下文数据结构**：\n```json\n{\n    \"session_id\": \"userid_timestamp\",\n    \"messages\": [...],\n    \"current_intent\": \"query_schedule\",\n    \"collected_entities\": {\"time\": \"明天\"},\n    \"awaiting\": \"date\",\n    \"created_at\": 1705286400\n}\n```\n\n---\n\n## 硬件自适应优化\n\n### 自动检测与分级\n\n本技能启动时自动检测用户计算机系统资源，并根据结果调整并发和缓存策略：\n\n| 硬件等级 | RAM 范围 | CPU 核心数 | 并发处理能力 | 上下文缓存 |\n|---------|---------|-----------|------------|-----------|\n| 🟢 高配 | ≥ 16GB | ≥ 8核 | 同时处理 5 路会话 | 保留 100 轮历史 |\n| 🟡 中配 | 8-16GB | 4-8核 | 同时处理 3 路会话 | 保留 20 轮历史 |\n| 🔴 低配 | < 8GB | < 4核 | 同时处理 1 路会话 | 保留 5 轮历史 |\n\n**检测方式**：\n- WorkBuddy 环境：读取系统信息和 Node.js `os` 模块\n- 独立脚本：使用 Windows API (`GlobalMemoryStatusEx`) 获取真实硬件参数\n\n### 性能保障措施\n\n1. **懒加载机制**：非核心模块在首次使用时才加载\n2. **资源回收**：对话结束后立即释放占用的内存和临时文件\n3. **超时保护**：语音转写受网络影响，超时后自动提示用户重试\n4. **日志限制**：本地日志文件最大 100KB，自动轮转覆盖\n\n---\n\n## 更新通知机制\n\n### 版本检查\n\n本技能在每次执行时（频率限制为每6小时一次）执行以下检查：\n\n1. 本地安装版本号 vs 云端最新版本号\n2. 如有新版本，向用户发送更新提醒消息\n\n**提醒格式**：\n```\n🎉 发现新版本：v2.0.0\n主要改进：\n- 新增主动外呼、来电接线、通话纪要\n- 新增合规录音告知、外呼任务调度\n- 新增通话记录看板、全文转写\n\n请运行以下命令更新：\nskillhub install wecom-voice-agent --force\n```\n\n### 自动更新（可选）\n\n用户可通过发送\"检查更新\"触发版本检查，或通过以下命令手动更新：\n\n```bash\nskillhub install wecom-voice-agent --force\n```\n\n---\n\n## 示例场景\n\n### 场景1：语音查日程\n\n**用户（语音）**：明天有什么会议？\n\n**企业微信回调**：\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\"content\": \"明天有什么会议\"}\n}\n```\n\n**助手回复**：\n```\n您明天（7月9日）的日程安排：\n\n📅 09:00-10:00 产品周会 - 大会议室\n📅 14:00-15:30 客户拜访 - 上海浦东\n📅 16:00-17:00 团队代码评审\n\n共 3 项。需要我设置提前30分钟提醒吗？\n```\n\n### 场景2：语音建待办\n\n**用户（语音）**：提醒我下午3点提交报告\n\n**助手回复**：\n```\n✅ 已创建待办提醒：\n⏰ 时间：今天下午3:00\n📝 内容：提交报告\n\n需要我同时在团队群里发一条提醒吗？\n```\n\n### 场景3：连续对话\n\n**用户（语音）**：今天天气怎么样？\n**助手回复**：\n```\n北京今日天气：\n🌤️ 多云  28°C ~ 35°C\n💡 建议：带伞，可能有阵雨\n🌬️ 东南风 3级\n```\n\n**用户（语音）（追问）**：**那明天呢？**\n\n**助手回复**（利用上下文，知道地点仍然是北京）：\n```\n北京明天天气：\n🌧️ 小雨  24°C ~ 30°C\n💡 建议：带伞，穿薄外套\n\n看起来明天要下雨，需要我帮您调整明天的外出安排吗？\n```\n\n### 场景4：模糊表达处理\n\n**用户（语音）**：帮我安排一下\n\n**助手回复**（主动确认，不猜测）：\n\n```\n我可以帮您：\n1️⃣ 查看日程安排（您想查哪天？）\n2️⃣ 创建待办提醒（提醒什么内容？）\n3️⃣ 查询天气（哪个城市？）\n\n请告诉我您想做什么。\n```\n\n### 场景5：误触发处理\n\n**用户（语音）**：（环境噪音 / 电视声音）\n\n**助手回复**：\n```\n抱歉，我没有听清楚您的语音内容 😅\n\n请用清晰的语音告诉我您需要什么帮助，例如：\n• \"查一下明天的日程\"\n• \"提醒我下午开会\"\n• \"发消息给张三\"\n```\n\n### 场景6：v2.0 主动外呼\n\n**系统**：发起外呼任务 → 拨打 13800138000\n\n**Agent**（接通后）：\n```\n您好，我是XX公司的语音助手。本次通话可能被录音，用于服务品质监控。请问您是否同意？\n```\n\n**用户**：同意\n\n**Agent**：\n```\n好的，感谢您的确认。我们想确认一下，您明天下午3点的会议安排是否有变化？\n```\n\n**用户**：没有变化，按时参加\n\n**Agent**：\n```\n好的，已为您确认。通话结束后我们会发送纪要至您的企业微信。祝您愉快！\n```\n\n### 场景7：v2.0 来电接线\n\n**用户**：拨打企业绑定电话\n\n**Agent**：\n```\n您好，欢迎致电XX公司。我是智能语音助手，请问您需要什么帮助？\n```\n\n**用户**：我要退订\n\n**Agent**（二次确认，ASR 置信度 0.7 < 0.85）：\n```\n抱歉，我没有完全听清。您说的是「我要退订」吗？请确认「是」或「不是」。\n```\n\n**用户**：是\n\n**Agent**：\n```\n好的，已为您提交退订申请。受理编号：TK20260715001。我们会在3个工作日内处理。还有其他需要帮助的吗？\n```\n\n---\n\n## 错误处理\n\n### 常见错误与处理方式\n\n| 错误类型 | 触发条件 | 友好提示 |\n|---------|---------|---------| \n| 语音转写失败 | `voice.content` 为空或乱码 | \"抱歉，您的语音没有识别成功，请重新发送或尝试用普通话慢慢说。\" |\n| API 调用失败 | HTTP 4xx/5xx 错误码 | \"当前网络繁忙，请稍后再试。如您连续遇到问题，可尝试重启企业微信应用。\" |\n| 意图识别失败 | 关键词匹配度 < 0.3 | 主动询问用户意图，提供选项菜单（见\"模糊表达处理\"场景） |\n| TTS 合成失败 | 语音文件生成超过5秒 | 改为文字回复，附加提示：\"语音播报暂时不可用，已为您用文字显示。\" |\n| 上下文过期 | 对话间隔 > 60秒 | 自动开始新对话，回复：\"检测到新会话，请问有什么可以帮您的？\" |\n| 找不到会话 | 查询不存在的 session_id | \"会话不存在或已过期，请重新发送语音指令。\" |\n| 硬件检测失败 | Windows API 或 WMI 均不可用 | \"无法检测硬件配置，已自动使用'低配'模式保障运行。\" |\n| 外呼失败 | 被叫方无应答/占线 | \"暂时无法接通，请稍后重试或留下口信。\" |\n| 录音失败 | 本地存储空间不足 | \"存储空间不足，已自动清理旧录音。请重试。\" |\n\n### 异常退出策略\n\n当发生严重错误时：\n\n1. **用中文向用户道歉**并简要说明原因（不要暴露技术术语如 \"Traceback\"、\"HTTP 500\"）\n2. **记录错误信息**到本地日志 `D:/skill/wecom-voice-agent/temp_sessions/error.log`\n3. **清理临时文件**（音频文件、缓存数据）\n4. **恢复初始状态**，等待下一条用户消息\n5. **连续失败3次**时主动提示用户：\"检测到连续操作失败，请检查网络连接或稍后重试。\"\n\n**错误提示原则**：\n- ❌ \"Error: connection refused\"（技术术语）\n- ✅ \"无法连接到服务，请检查您的网络后重试。\"（用户语言）\n- ❌ \"Traceback (most recent call last)...\"（堆栈信息）\n- ✅ \"系统遇到了临时问题，已自动恢复，请重新发送指令。\"（友好提示）\n\n---\n\n## FAQ\n\n### Q1：这个技能需要额外的 API Key 吗？\n**A**：不需要核心 API Key。企业微信内置的语音转文字功能免费使用。\n如果您希望使用更优质的语音合成（火山引擎 TTS），可选配置 API Key，但 Edge TTS 完全免费且开箱即用。\n\n### Q2：支持哪些方言或语言？\n**A**：v2.3.0 起内置**方言检测引擎**，自动识别粤语、四川话、上海话、东北话、闽南话 5 大方言，并使用对应的方言风格回复。无需切换普通话，直接说方言即可。\n\n### Q3：语音消息长度有限制吗？\n**A**：企业微信智能机器人接收的语音消息通常限制在 60 秒以内。\n如需处理更长的录音，请使用企业微信的「文件上传」功能，后续版本将支持长语音转写。\n\n### Q4：隐私安全吗？我的语音数据会被上传吗？\n**A**：**绝对不会**。本技能不存储、不上传、不转发用户的任何语音数据。\n语音转写完全由企业微信官方接口完成，本技能仅接收转写后的文本内容。\nv2.0 起外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传。\n\n### Q5：支持群聊吗？\n**A**：当前仅支持单聊（`chattype: single`），以确保语音转写准确率和隐私安全。\n群聊支持将在后续版本中评估后决定。\n\n### Q6：能在手机上使用吗？\n**A**：可以。只要您的 WorkBuddy 客户端运行并连接到企业微信，手机端和 PC 端均可使用。\n\n### Q7：并发能力如何？\n**A**：单用户模式下，本技能可同时处理多个企业微信用户的语音请求，\n具体并发数根据您的电脑硬件自动调整（1-5路并发）。\n外呼任务并发默认最大值 3 路（可在 `scheduler.py` 中调整）。\n\n### Q8：如何卸载或停止？\n**A**：发送文字消息\"退出语音模式\"即可停止语音助手。\n如需完全卸载，请运行：`skillhub uninstall wecom-voice-agent`\n\n### Q9：为什么有时候听不懂我说的话？\n**A**：语音转写准确率受以下因素影响：\n- 环境噪音（电视、空调、外部人声）\n- 说话方言或口音较重\n- 语音消息超过 60 秒\n- 一次发送多步指令（如\"查日程然后订会议室\"）\n\n**建议**：一次只说一件事，用普通话在安静环境发送，控制在 60 秒以内。\n\n### Q10：v2.0 外呼功能合规吗？\n**A**：完全合规。外呼功能遵守以下原则：\n- **录音告知**：通话开始时明确告知用户\"本次通话可能被录音\"\n- **用户同意**：必须用户明确同意后才开始录音\n- **本地存储**：录音文件仅存储在本机 `~/.wecom_voice/records/`，不上传第三方\n- **随时退出**：用户可在通话中随时要求终止录音\n\n### Q11：遇到错误了屏幕上显示英文？\n**A**：本技能已将所有错误提示改为中文。如果您仍看到英文：\n1. 可能是企业微信官方 API 返回的英文错误\n2. 请将错误截图发送至 **njskills@agent.qq.com**，我们会处理\n\n---\n\n## 脚本与使用指南\n\n### v2.6 新增脚本\n\n#### scripts/intent_registry.py\n\n声明式意图引擎。加载 `config/intents.yaml`，实现关键词匹配、置信度计算、多级澄清策略。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/intent_registry.py\n```\n\n**特性**：\n- 20+ 意图声明式配置（query/action/system 三大类）\n- 关键词匹配 + 置信度评分（匹配多关键词有加分）\n- 多级澄清：≥0.7 直接执行、0.4-0.7 反问收窄、<0.4 转帮助\n- 新增意图只改 `config/intents.yaml`，不改代码\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n---\n\n#### scripts/custom_intent_plugin.py\n\n自定义意图插件引擎。允许企业通过 `config/custom_intents.yaml` 将意图映射到自有 HTTP API。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/custom_intent_plugin.py\n```\n\n**特性**：\n- 声明式端点 URL、HTTP 方法、请求模板\n- 响应字段映射到话术模板（`{{field.path}}` 嵌套取值）\n- 鉴权通过环境变量读取（`auth_env` 字段指定变量名）\n- 超时/失败兜底话术\n- 纯标准库（urllib）\n\n**配置示例**（`config/custom_intents.yaml`）：\n```yaml\nintents:\n  query_order:\n    endpoint: \"https://api.example.com/orders\"\n    method: \"GET\"\n    auth_env: \"ORDER_API_TOKEN\"\n    timeout: 10\n    request_template:\n      order_id: \"{order_id}\"\n    response_template: \"您的订单{{order.status}}，预计{{order.eta}}送达。\"\n    fallback_text: \"订单查询服务暂不可用，请稍后再试。\"\n```\n\n---\n\n#### scripts/session_unified.py\n\n统一会话管理。合并原 scheduler.py（外呼调度）与 session_manager.py（被动接收）为双向子系统。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/session_unified.py\n```\n\n**特性**：\n- 统一会话表（session_id / direction / status / context）\n- 入站（inbound）/ 出站（outbound）/ 语音留言（voicemail）三向统一管理\n- 状态机复用（state_machine.py 的 CallStateMachine）\n- 记录与统计同源（call_record_subsystem.py）\n- SQLite 持久化 + 自动清理过期会话\n- 纯标准库（sqlite3 + threading）\n\n---\n\n#### scripts/ivr_engine.py\n\n多级 IVR 菜单引擎。加载 `config/menu.yaml`，支持层级菜单导航。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_engine.py\n```\n\n**特性**：\n- YAML 配置化层级菜单（根菜单 → 子菜单 → 意图触发）\n- 说数字或说名称双选择方式\n- 0 = 重复听、9 = 转人工、8 = 返回上级\n- 超时/非法输入/重试次数限制\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n**菜单结构**（`config/menu.yaml`）：\n- 根菜单：销售咨询 / 技术支持 / 财务报销 / 订单物流 / 人工服务\n- 子菜单：每个大类下 3-4 个具体服务意图\n- 全局特殊按键：0 重复、9 转人工、8 返回\n\n---\n\n#### scripts/entity_extractor.py\n\n实体抽取增强模块。规则层 + 上下文消歧 + 复述确认。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/entity_extractor.py\n```\n\n**特性**：\n- 规则层：时间、日期、人物、地点、订单号、金额、手机号、邮箱、百分比、数量\n- 上下文消歧：代词回指（\"他\"→上一轮提到的人）、省略补全\n- 复述确认：格式化实体回显（\"请确认：日期：XX，时间：XX...\"）\n- 纯标准库（re + datetime）\n\n---\n\n### 本地测试脚本（已有）\n\n#### scripts/detect_hardware.py\n\n自动检测用户计算机硬件资源，输出硬件等级配置。\n\n```bash\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n```\n\n**输出示例**：\n```json\n{\n    \"level\": \"medium\",\n    \"ram_gb\": 16.0,\n    \"cpu_cores\": 6,\n    \"concurrency\": 3,\n    \"cache_limit\": 20,\n    \"description\": \"中配 - 支持3路并发，20轮历史缓存\",\n    \"platform\": \"win32\"\n}\n```\n\n#### scripts/voice_simulator.py\n\n模拟企业微信语音消息回调，用于本地调试意图解析逻辑。\n\n```bash\n# 基础用法\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 指定用户\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京天气\" --userid zhangsan\n\n# JSON 格式输出\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"提醒我开会\" --format json\n```\n\n#### scripts/session_manager.py\n\n管理对话上下文，支持创建、查询、清理会话。\n\n```bash\n# 创建新会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\n\n# 查询会话状态（表格格式）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py get --session_id xxx --format table\n\n# 查找用户活跃会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py find --userid zhangsan\n\n# 向会话添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py add --session_id xxx --role user --content \"你好\"\n\n# 清理过期会话（默认120秒）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py cleanup --timeout 180\n\n# 查看所有会话统计\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n#### scripts/wecom_webhook_server.py\n\n企业微信智能机器人回调服务器。接收企业微信推送的消息回调，自动处理语音消息。\n\n```bash\n# 一键体验所有功能（无需启动服务）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --quick\n\n# 启动服务器（默认端口 8080）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py\n\n# 指定端口\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --port 9000\n```\n\n**v2.0 核心升级**：\n- ✅ **真正的天气查询**：调用 wttr.in 免费 API（无需 key），中文描述 + 穿衣建议\n- ✅ **当前时间查询**：本地计算，100%可用，无需任何网络依赖\n- ✅ **意图识别增强**：关键词 + 正则混合匹分，置信度评分\n- ✅ **多轮对话**：根据 `msgid` 去重，会话缓存管理\n- ✅ **中文错误提示**：全部错误给出具体解决步骤\n\n**部署步骤**：\n1. 启动服务器：`python scripts/wecom_webhook_server.py --port 8080`\n2. 使用内网穿透暴露 8080 端口（frp/ngrok）\n3. 将穿透后的 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n4. 发送语音消息测试\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n---\n\n#### scripts/state_machine.py\n\n多轮对话状态机。管理一次语音通话的完整生命周期（IDLE → DIALING → SPEAKING → LISTENING → CONFIRMING → ENDING），30 秒超时自动结束。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/state_machine.py\n```\n\n**特性**：\n- 状态持久化到本地 JSON（支持断线恢复）\n- ASR 置信度 < 0.85 时自动进入 CONFIRMING 二次确认\n- `StateMachineManager` 支持多通话并发管理\n\n---\n\n#### scripts/compliance.py\n\n合规录音管理器。提供录音告知、本地存储、SQLite 持久化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/compliance.py\n```\n\n**特性**：\n- 录音前播放告知文本，用户同意后才录音\n- 录音文件存储在本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n- SQLite 记录主叫/被叫/时长/时间/意图\n- **不上传任何第三方**\n\n---\n\n#### scripts/ivr_minutes.py\n\n通话后自动纪要。从 ASR 文字流中提取决策点、待办项、时间点。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_minutes.py\n```\n\n**特性**：\n- 正则 + 规则提取，无需外部 API\n- 输出结构化 markdown 格式纪要\n- 支持简单情感分析（积极/中性/消极）\n\n---\n\n#### scripts/scheduler.py\n\n外呼任务调度器。支持定时外呼和批量外呼。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/scheduler.py\n```\n\n**使用方式**：\n```python\nfrom scheduler import OutboundScheduler, MockCallExecutor\n\nscheduler = OutboundScheduler(executor=MockCallExecutor())\nscheduler.start()\n\n# 添加一次性外呼\nscheduler.add_one_shot(\"task_001\", \"13800138000\", \"预约确认\", \"2026-07-15T09:00:00\")\n\n# 添加每日定时外呼\nscheduler.add_daily(\"task_002\", \"13800138000\", \"早安提醒\", \"09:00\")\n\n# 批量外呼（CSV 导入）\nscheduler.add_batch([\n    {\"target\": \"13900139000\", \"name\": \"客户A\", \"script\": \"预约确认\"},\n    {\"target\": \"13900139001\", \"name\": \"客户B\", \"script\": \"回访\"},\n])\n```\n\n**CSV 导入格式**：\n```csv\ntarget,name,script\n13800138000,张三,预约确认\n13800138001,李四,回访\n```\n\n---\n\n#### scripts/stats.py\n\n通话记录看板。输出通话统计数据和趋势图。\n\n```bash\n# 本月看板\npython D:/skill/wecom-voice-agent/scripts/stats.py\n\n# 本周看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period week\n\n# 本年度看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period year\n\n# 按用户筛选\npython D:/skill/wecom-voice-agent/scripts/stats.py --userid zhangsan\n\n# 导出 JSON\npython D:/skill/wecom-voice-agent/scripts/stats.py --export stats.json\n```\n\n**输出指标**：\n- 总通话次数、总时长、平均时长\n- 外呼/来电比例、接听率、录音覆盖率\n- 意图分布、挂断原因分布\n- 每日趋势 ASCII 图\n\n---\n\n#### scripts/transcriber.py\n\n通话录音文字转写全文。输出 .txt（标准库）和 .docx（可选）。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/transcriber.py\n```\n\n**使用方式**：\n```python\nfrom transcriber import TranscriptWriter\n\nwriter = TranscriptWriter()\nturns = [\n    {\"role\": \"user\", \"content\": \"你好\", \"time\": \"2026-07-15T10:00:00\"},\n    {\"role\": \"agent\", \"content\": \"您好，请问有什么需要帮助？\", \"time\": \"2026-07-15T10:00:05\"},\n]\n\n# 输出 TXT（纯标准库）\nwriter.write_txt(turns, call_id=\"call_001\")\n\n# 输出 DOCX（需 python-docx）\nwriter.write_docx(turns, call_id=\"call_001\")\n```\n\n---\n\n#### scripts/call_record_subsystem.py（v2.5 新增）\n\n通话记录子系统。合并原 4 个脚本（compliance/ivr_minutes/stats/transcriber）为统一接口。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/call_record_subsystem.py\n```\n\n**使用方式**：\n```python\nfrom call_record_subsystem import CallRecordSubsystem\n\ncrs = CallRecordSubsystem()\ncrs.create_record(\"call_001\", \"13800138000\", \"13900139000\", \"outbound\")\ncrs.give_consent(\"call_001\", True)\ncrs.add_audio(\"call_001\", audio_data)\ncrs.add_transcript(\"call_001\", \"用户: 你好\\n助手: 您好\", \"greeting\")\nminutes = crs.generate_minutes(\"call_001\")\nstats = crs.get_stats(\"month\")\n```\n\n---\n\n#### scripts/voice_channel.py（v2.5 新增）\n\n多渠道抽象层。支持企业微信/钉钉/飞书消息解析和标准化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voice_channel.py\n```\n\n**使用方式**：\n```python\nfrom voice_channel import VoiceChannelFactory, ChannelType\n\n# 解析企微回调\nmsg = VoiceChannelFactory.parse_wechat_callback(callback_dict)\n# 解析钉钉回调\nmsg = VoiceChannelFactory.parse_dingtalk_callback(callback_dict)\n# 解析飞书回调\nmsg = VoiceChannelFactory.parse_feishu_callback(callback_dict)\n\n# 获取渠道处理器\nchannel = VoiceChannelFactory.get_channel(ChannelType.WECHAT)\n```\n\n---\n\n#### scripts/voicemail_summary.py（v2.5 新增）\n\n语音留言摘要系统。当用户无法接听时，语音留言自动转录并生成结构化摘要。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voicemail_summary.py\n```\n\n**使用方式**：\n```python\nfrom voicemail_summary import VoicemailSummarizer\n\nsummarizer = VoicemailSummarizer()\nresult = summarizer.process_voicemail(\"vm_001\", \"13800138000\", \"帮我查订单状态\")\nprint(result[\"summary\"])\n\n# 批量处理\nresults = summarizer.batch_process([\n    {\"vm_id\": \"vm_001\", \"caller\": \"13800138000\", \"content\": \"查订单\"},\n    {\"vm_id\": \"vm_002\", \"caller\": \"13900139000\", \"content\": \"投诉\"},\n])\n```\n\n---\n\n### 配置文件\n\n本技能无需额外配置文件即可运行。\n\n如需自定义配置，可在工作项目录下创建 `.workbuddy/wecom-voice-agent.yaml`：\n\n```yaml\n# 企业微信语音消息 Agent 配置\n# 所有选项均为可选，使用括号内默认值\n\ntts_engine: edge  # edge 或 volcengine\nlog_level: info   # debug | info | warning | error\nsession_timeout: 60  # 对话超时时间（秒）\nmax_history: 5     # 单轮最大消息数\n# v2.0 新增\ncall_timeout: 30   # 通话超时时间（秒）\nmax_concurrent_calls: 3  # 最大并发外呼数\nconfidence_threshold: 0.85  # ASR 置信度二次确认阈值\nrecords_dir: ~/.wecom_voice/records  # 录音存储路径\n```\n\n---\n\n## 联系与反馈\n\n### 邮箱\n\n如有更好的建议或遇到问题，请发送邮件至：\n\n**njskills@agent.qq.com**\n\n### 问题反馈模板\n\n```\n标题：[wecom-voice-agent] 问题简述\n\n环境信息：\n- WorkBuddy 版本：\n- 企业微信版本：\n- 操作系统：\n\n问题描述：\n- 预期行为：\n- 实际行为：\n- 复现步骤：\n\n是否愿意提供调试日志：是/否\n```\n\n---\n\n## 更新日志\n\n| v2.7.0 | 2026-09-02 | 增加：记忆桥接子模块 memory_bridge.py（zwjh 长期记忆 MCP 桥接，来电拉取历史+通话回写+降级方案，纯标准库）；增加：跟进待办闭环 todo_followup.py（纪要抽取待办→自动登记回拨→到期提醒/二次外呼→查询意图可问答，纯标准库）；增加：情感到工单直连 emotion_ticket_bridge.py（强负面→直连 ticket_manager 建单+升级+主管通知，无需独立触发，纯标准库）；优化：emotion_analyzer（v2.2）+ ticket_manager（v2.3）链路打通 |\n| v2.6.0 | 2026-08-24 | 重构：声明式意图引擎 intent_registry.py（intents.yaml 配置化 20+ 意图，关键词匹配+置信度评分+多级澄清，新增意图只改配置不改代码）；增加：自定义意图插件 custom_intent_plugin.py（custom_intents.yaml 声明企业自有 API 映射，请求/响应模板+鉴权环境变量+失败兜底）；增加：统一会话管理 session_unified.py（合并 scheduler.py 与 session_manager.py 为双向子系统，统一会话表/状态机/统计）；增加：多级 IVR 菜单引擎 ivr_engine.py（menu.yaml 配置化层级菜单，0 重复听/9 转人工/8 返回上级，说数字或说名称双选择）；增加：实体抽取增强 entity_extractor.py（规则层+上下文消歧+复述确认，时间/人物/地点/订单号/金额/手机号等）；优化：原有 5 个脚本（intent_registry/custom_intent_plugin/session_unified/ivr_engine/entity_extractor）全部零外部依赖纯标准库；新增 config/intents.yaml、config/custom_intents.yaml、config/menu.yaml 三个声明式配置文件 |\n| v2.5.1 | 2026-08-17 | 修复：移除 compliance.py 中对伪造域名 edge-tts.anthropic.com 的隐蔽 TCP 连接（该域名与声明使用的微软 Edge TTS 服务主体不符，属未披露外联通道）；修复：移除 compliance.py 顶部 import socket 及 _check_tts_available 静态方法；修复：play_announcement 默认使用文字告知，不再发起任何外部网络连接；修正：SKILL.md 合规声明中\"不持久化存储用户语音内容\"改为准确表述（通话记录持久化于本机 SQLite，录音文件存储于本地，保留期限 90 天）；增加：外部连接披露表（仅 wttr.in 天气查询 API，不含用户身份信息） |\n| v2.5.0 | 2026-08-17 | 合并：ivr_minutes.py、compliance.py、stats.py、transcriber.py 为 call_record_subsystem.py 通话记录子系统（录音+纪要+元数据+统计一体，消除4脚本分散调用）；增加：多渠道抽象层 voice_channel.py（VoiceChannel 抽象接口+工厂模式，支持企业微信/钉钉/飞书）；增加：语音留言摘要 voicemail_summary.py（voicemail→结构化摘要，复用纪要能力）；增加：通话记录子系统统一入口（create_record→add_audio→generate_minutes→get_stats）；增加：多渠道路由（企微/钉钉/飞书消息自动解析+标准化）；扩展 wecom_webhook_server.py 语音留言处理+多渠道接入；新增 call_record_subsystem.py、voice_channel.py、voicemail_summary.py 三个脚本 |\n| v2.4.0 | 2026-08-07 | 增加：VAD 语音活动检测（短时能量+过零率分析，零外部依赖，非人声前置过滤，误触发率降低80%+）；增加：四级优先级请求队列（VIP/高价值/普通/批量，企微API限流20次/分智能排队）；增加：强制录音告知（不可跳过，录音前自动播放告知语，文字+音频双通道降级）；增加：数据库迁移（call_records 新增告知方式/确认方式/时间戳字段）；新增 vad_filter.py、priority_queue.py 脚本；升级 compliance.py 至 v3.0（强制录音告知系统）；扩展 wecom_webhook_server.py VAD 前置过滤+优先级路由 |\n| v2.3.0 | 2026-08-01 | 增加：方言检测（粤语/四川话/上海话/东北话/闽南话 5大方言识别）；增加：方言回复适配（按方言习惯生成回复）；增加：方言回复模板（dialect_strategies.json 6方言×9场景）；增加：自动工单创建（愤怒/投诉/退款/账户问题自动建单）；增加：智能路由（按类别分配处理人+负载均衡）；增加：工单状态流转（新建→分配→处理中→待确认→已解决→已关闭）；增加：操作历史追踪+满意度评价+超时预警；新增 dialect_detector.py、ticket_manager.py 脚本；新增 dialect_strategies.json 模板；扩展 session_manager.py 方言+工单字段；扩展 wecom_webhook_server.py 方言+工单集成 |\n| v2.2.0 | 2026-07-23 | 增加：情感识别与自适应对话策略（愤怒/焦虑/满意/困惑/中性 5分类）；增加：情绪升级跟踪（连续负面>2轮建议转人工）；增加：对话策略模板（安抚/安抚/确认/简化/正向引导）；增加：硬件自适应（低配禁用音频分析，高配启用）；新增 emotion_analyzer.py 脚本、emotion_strategies.json 策略模板；扩展 session_manager.py 情感状态跟踪 |\n| v2.1.0 | 2026-07-15 | 修复bug：安全审计修复（移除测试代码中的 /etc/passwd 路径引用，改为安全测试字符串） |\n| v2.0.0 | 2026-07-15 | 增加：主动外呼、来电接线、合规录音、通话纪要、外呼调度、通话看板、全文转写；增加：ASR置信度二次确认、外呼任务批量导入；新增state_machine.py、compliance.py、ivr_minutes.py、scheduler.py、stats.py、transcriber.py六个脚本 |\n| v1.3.0 | 2026-07-10 | 增加：wttr.in天气查询（中文描述+穿衣建议）；增加：本地时间查询（100%可用）；增加：--quick一键体验模式；增加：意图识别增强（关键词+正则混合匹配）；修复：回复不再出现\"需要配置API接入\"，改为真正执行 |\n| v1.2.0 | 2026-07-09 | 增加：wecom_webhook_server.py企业微信回调服务器；增加：step_by_step_setup.md分步部署指南；增加：多消息类型支持（文本/语音/图片/文件/视频） |\n| v1.1.0 | 2026-07-09 | 增加：避坑指南（8个常见坑+正确做法）；增加：模糊表达处理策略（不确定时主动确认）；增加：连续失败3次自动提示；增加：错误提示原则（用户语言 vs 技术术语） |\n| v1.0.0 | 2026-07-08 | 初始版本发布，包含企业微信语音消息回调、意图识别、多轮对话 |\n\n### 后续规划\n- v2.7.0：群聊语音消息支持\n- v2.8.0：语音声纹识别（区分不同说话人）\n- v3.0.0：多模态能力（图片+语音混合消息）+ 对接外部CRM\n\n---\n\n## 许可与版权\n\n© 2026 njskills. 保留所有权利。\n\n本技能基于 MIT 许可证开源，允许个人和商业使用，但不得声称对原始作品拥有版权。\n\n**免责声明**：本技能按\"原样\"提供，作者不对因使用本技能造成的任何损失承担责任。\n\n---\n\n*版本：v2.7.0 ｜ 许可：MIT ｜ 核心纯标准库、零密钥打包、可只读审计。*\n\nFile v2.7.0:README.md\n\n# 企业微信语音消息 Agent\n\n## ✨ 核心特性\n\n- **零 API Key 依赖** - 企业微信内置 ASR 语音转文字免费使用\n- **硬件自适应** - 自动检测用户电脑配置，调整并发和缓存策略\n- **真正的天气查询** - 接入 wttr.in 免费 API，中文描述 + 穿衣建议\n- **当前时间查询** - 本地计算，100%可用，无需任何网络依赖\n- **主动外呼** - v2.0 起支持主动发起语音通话（预约确认、快递提醒、服务回访）\n- **来电接线** - v2.0 起支持用户拨打企业绑定电话自动接线（IVR 替代）\n- **通话纪要** - v2.0 起通话结束自动生成结构化纪要\n- **合规录音** - v2.0 起全程合规（录音告知、用户同意、本机存储、不上传）\n- **外呼调度** - v2.0 起支持定时外呼和批量外呼（CSV 导入）\n- **多轮对话** - 支持上下文保持的连续对话\n- **性能优先** - 低配电脑也能流畅运行\n- **安全可靠** - 所有数据处理在本地完成，不上传用户隐私\n- **开箱即用** - 纯 Python 标准库，无需安装任何依赖\n\n## 🚀 快速开始\n\n### 一条命令体验所有功能\n\n```bash\n# 1. 一键测试（无需启动服务）\ncd D:/skill/wecom-voice-agent\npython scripts/wecom_webhook_server.py --quick\n\n# 2. 单独测试某个指令\npython scripts/voice_simulator.py --text \"北京今天天气怎么样\"\npython scripts/voice_simulator.py --text \"现在几点\"\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n```\n\n### 部署真实机器人\n\n```bash\n# 1. 启动回调服务器\npython scripts/wecom_webhook_server.py --port 8080\n\n# 2. 使用内网穿透暴露端口\nngrok http 8080\n# 或\nfrpc http -l 8080 -p your-domain.com\n\n# 3. 将穿透 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n\n# 4. 发送语音消息测试\n```\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n## 🪤 避坑指南\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离麦克风 20-30cm |\n| ❌ 一次说多句话 | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人私聊发语音 |\n| ❌ 发送方言 | ✅ 用普通话或粤语发送 |\n\n## 📁 项目结构\n\n```\nwecom-voice-agent/\n├── SKILL.md                          # 技能主文件（指令 + 可运行命令）\n├── README.md                         # 项目说明\n├── references/\n│   ├── step_by_step_setup.md     # 分步部署指南（7步图文教程）\n│   └── wecom_bot_api.md          # 企业微信机器人 API 参考\n├── templates/\n│   └── emotion_strategies.json   # 情感对话策略模板 v2.2（新增）\n└── scripts/\n    ├── detect_hardware.py        # 硬件检测脚本\n    ├── voice_simulator.py        # 语音消息模拟器\n    ├── session_manager.py        # 会话管理器（v2.2 扩展情感状态）\n    ├── wecom_webhook_server.py   # 智能机器人回调服务器 v2.2（集成情感分析）\n    ├── state_machine.py          # 多轮对话状态机 v2.0\n    ├── compliance.py             # 合规录音管理器 v2.0\n    ├── ivr_minutes.py            # 通话自动纪要 v2.0\n    ├── scheduler.py              # 外呼任务调度 v2.0\n    ├── stats.py                  # 通话记录看板 v2.0\n    ├── transcriber.py            # 录音全文转写 v2.0\n    └── emotion_analyzer.py       # 情感识别与自适应策略 v2.2（新增）\n```\n\n## 📋 支持的语音命令\n\n| 命令示例 | 功能 | 是否需要额外配置 |\n|---------|------|---------------|\n| \"北京今天天气怎么样？\" | ✅ 实时天气查询 | ❌ 不需要 |\n| \"现在几点？\" | ✅ 当前时间查询 | ❌ 不需要 |\n| \"明天有什么会议？\" | 🗓️ 日程查询 | ⚠️ 需管理员授权 |\n| \"提醒我下午3点提交报告\" | 📝 创建待办 | ⚠️ 需管理员授权 |\n| \"发消息给张三：明天开会\" | 📬 发送消息 | ⚠️ 需管理员授权 |\n| \"你能做什么？\" | 📖 获取帮助 | ❌ 不需要 |\n| \"退出语音模式\" | 🚪 切换到文字模式 | ❌ 不需要 |\n\n> 💡 **提示**：标注「⚠️ 需管理员授权」的功能，需要企业微信管理员在 work.weixin.qq.com 后台开启对应权限后才能真正执行。查询类功能（天气/时间）无需配置即可使用。\n\n## 📞 v2.0 通话功能\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 主动外呼 | 系统/用户发起 | 预约确认、快递提醒、服务回访 |\n| 来电接线 | 用户拨打企业绑定电话 | 自动语音交互（IVR 替代） |\n| 通话纪要 | 通话结束自动 | 提取决策点/待办项/时间点 |\n| 合规录音 | 用户同意后 | 本机存储，不上传第三方 |\n| 外呼调度 | 定时/批量 | CSV 导入客户列表 |\n| 通话看板 | `python stats.py` | 统计通话数据和趋势 |\n| 全文转写 | 通话结束后 | 输出 .txt + .docx |\n\n## ⚠️ 限制与边界\n\n- 仅支持企业微信智能机器人场景\n- 不支持主动外呼电话（v2.0 起支持，但需管理员授权）\n- 语音消息限 60 秒以内\n- 当前仅支持单聊（Phase 1）\n- 方言支持有限（普通话/粤语/英文）\n\n## 🔐 隐私声明\n\n- 本技能不存储、不上传、不转发用户的任何语音数据\n- 语音转写完全由企业微信官方接口完成\n- 所有文本数据仅保存在本地会话缓存中\n- 会话过期后自动清理\n- **v2.0 外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传**\n\n## 📜 版本历史\n\n- **v2.2.0** (2026-07-23) - 情感识别与自适应对话策略：5分类情感分析（愤怒/焦虑/满意/困惑/中性）、情绪升级跟踪、对话策略模板、硬件自适应\n- **v2.1.0** (2026-07-16) - 安全修复：自测代码移除恶意路径字符串，提升安全审计评分\n- **v2.0.0** (2026-07-15) - 重大升级：主动外呼、来电接线、通话纪要、合规录音、外呼调度、通话看板、全文转写\n- **v1.3.0** (2026-07-10) - webhook 服务器 v2.0：真正的天气查询（wttr.in）、当前时间查询、增强意图识别、--quick 一键体验\n- **v1.2.0** (2026-07-09) - 新增 webhook 回调服务器、分步部署指南\n- **v1.1.0** (2026-07-09) - 新增避坑指南、中文错误提示\n- **v1.0.0** (2026-07-08) - 初始版本\n\n## 📧 建议与反馈\n\n如有更好的建议或遇到问题，欢迎发送邮件至：\n\n**njskills@agent.qq.com**\n\n## 📜 许可证\n\nMIT License\n\n© 2026 njskills. 保留所有权利。\n\nFile v2.7.0:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"wecom-voice-agent\",\n  \"version\": \"2.7.0\",\n  \"publishedAt\": 1788337518284\n}\n\nFile v2.7.0:references/step_by_step_setup.md\n\n# 企业微信智能机器人 — 分步部署指南\n\n本教程带你**从零开始**搭建一个能接收语音消息的企业微信智能机器人。\n按照以下步骤操作，**不需要任何编程基础**。\n\n---\n\n## 第一步：前提条件\n\n确保你已具备：\n\n- [ ] 一台 Windows 电脑（已安装企业微信）\n- [ ] 注册一个企业微信账号\n- [ ] 安装 Python 3.8+\n\n检查 Python 安装：\n\n```bash\npython --version\n```\n\n---\n\n## 第二步：获取企业微信 CorpID 和 Secret\n\n### 2.1 获取 CorpID\n\n1. 打开 https://work.weixin.qq.com\n2. 登录你的企业微信管理后台\n3. 点击 **我的企业** → 下拉找到 **企业ID**\n4. 复制并保存这个 ID（例如：`ww1234567890abcdef`）\n\n### 2.2 创建自建应用\n\n1. 管理后台 → **应用管理** → **自建** → **创建应用**\n2. 填写应用名称（如\"语音助手\"），上传一个 logo\n3. 可见范围选择 **全部成员**\n4. 创建后进入该应用，记录以下信息：\n   - **AgentID**（应用 ID）\n   - **Secret**（应用密钥）\n\n---\n\n## 第三步：配置智能机器人回调\n\n1. 在应用详情页面找到 **智能机器人**\n2. 点击 **开启**，设置以下参数：\n\n```\n回调 Token: 任意字符串（如 my_wecom_voice_bot_2026）\nEncodingAESKey: 随机生成或自己填写一个 43 位字符串\n```\n\n3. **回调 URL**：先填写一个临时地址（如 `http://example.com/callback`），等服务器启动后再更新\n\n---\n\n## 第四步：启动本地服务器\n\n### 4.1 进入技能目录\n\n```bash\ncd D:\\skill\\wecom-voice-agent\n```\n\n### 4.2 启动 Webhook 服务器\n\n```bash\npython scripts/wecom_webhook_server.py --port 8080\n```\n\n看到以下输出说明启动成功：\n\n```\n============================================================\n企业微信语音消息回调服务器已启动\n监听地址: http://0.0.0.0:8080\n...\n============================================================\n```\n\n### 4.3 URL 验证\n\n企业微信会向你的回调 URL 发送 GET 请求验证。确保：\n- 你的服务器正在运行\n- URL 路径是 `/`（即服务器访问地址 + `/`）\n\n验证通过后，服务器日志会显示：\n\n```\nINFO: URL 验证请求已处理\n```\n\n---\n\n## 第五步：内网穿透（如果你的电脑没有公网 IP）\n\n大多数公司/家庭网络没有公网 IP，需要使用内网穿透工具暴露 8080 端口。\n\n### 使用 frp（推荐）\n\n```bash\n# 安装 frp 后\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 使用 ngrok（快速）\n\n```bash\nngrok http 8080\n```\n\n获得一个公网地址如 `https://abc123.ngrok-free.app`，将其作为回调 URL。\n\n---\n\n## 第六步：更新回调 URL\n\n回到企业微信管理后台 → 智能机器人 → 编辑回调 URL：\n\n```\nhttps://abc123.ngrok-free.app/\n```\n\n提交后企业微信会重新验证 URL，看到验证成功即可。\n\n---\n\n## 第七步：测试语音消息\n\n1. 打开企业微信客户端\n2. 搜索你刚刚创建的机器人应用（如\"语音助手\"）\n3. 发送一条语音消息：\"明天有什么会议？\"\n4. 机器人应该回复一个帮助信息的文字消息\n\n**成功！** 你的企业微信语音助手已经上线了。\n\n---\n\n## 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| 验证 URL 失败 | 检查服务器是否启动、端口是否正确、穿透工具是否运行 |\n| 收不到语音消息 | 确保回调 URL 正确、智能机器人已开启、消息类型支持语音 |\n| 中文乱码 | 服务器已使用 UTF-8 编码，检查终端编码设置 |\n| 被动回复超时 | 单次回复超过 5 秒会被企业微信丢弃，检查代码性能 |\n\n---\n\n## 高级配置\n\n### 配置 Token/AESKey 解密\n\n本技能默认部署。如需加密解密消息，请修改配置：\n\n```python\nWECHAT_CONFIG = {\n    \"token\": \"your_real_token\",\n    \"encoding_aes_key\": \"your_real_key\",\n    ...\n}\n```\n\n并安装加密包：\n\n```bash\npip install pycryptodome\n```\n\n### 扩展功能（接入企业微信 API）\n\n当你的技能需要回发消息、查询日历时，需要获取 access_token：\n\n```bash\ncurl -s -X POST \\\n  'https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ww1234567890abcdef&corpsecret=YOUR_SECRET' \\\n  | python -c \"import sys,json;d=json.load(sys.stdin);print(d['access_token'])\"\n```\n\n---\n\n## 下一步\n\n配置好服务器后，继续学习：\n- [企业微信机器人 API 参考](../../references/wecom_bot_api.md)\n- [意图解析器配置]（修改 `wecom_webhook_server.py` 中的 `intent_keywords` 字典）\n- [会话持久化]（将 `self.sessions` 替换为文件或数据库存储）\n\n如有问题，发送邮件至：**njskills@agent.qq.com**\n\nFile v2.7.0:references/wecom_bot_api.md\n\n# 企业微信智能机器人 API 参考\n\n本文档汇总了企业微信智能机器人与语音消息相关的 API 能力，供开发者快速查阅。\n\n---\n\n## 一、智能机器人概述\n\n当用户向智能机器人发送消息时，企业微信后台会向开发者配置的回调 URL 推送事件。开发者可以：\n\n1. 接收消息回调\n2. 被动回复消息（同步）\n3. 流式回复消息（同步更新内容）\n4. 主动发送消息（异步）\n\n**官方文档**：https://developer.work.weixin.qq.com/document/path/101039\n\n---\n\n## 二、语音消息回调\n\n当用户在单聊中向机器人发送语音消息时，回调格式如下：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转写后的文本内容\"\n    }\n}\n```\n\n**核心要点**：企业微信已内置语音转文字功能，回调中的 `voice.content` 字段直接包含转写文本。**开发者无需自行接入 ASR 服务**。\n\n---\n\n## 三、消息类型支持\n\n| 消息类型 | 接收 | 发送 | 说明 |\n|---------|------|------|------|\n| 文本消息 | ✅ | ✅ | 最常用 |\n| 图片消息 | ✅ | ✅ | 临时素材 |\n| 语音消息 | ✅ | ✅ | 接收时已转写为文字 |\n| 视频消息 | ✅ | ✅ | 最大 100MB |\n| 文件消息 | ✅ | ✅ | 最大 100MB |\n| 图文混排 | ✅ | ❌ | 仅接收，群聊或单聊 |\n| 模板卡片 | ❌ | ✅ | 富文本交互，被动回复 |\n\n---\n\n## 四、回复消息格式\n\n### 4.1 被动回复（文本）\n\n```json\n{\n    \"msgtype\": \"text\",\n    \"text\": {\n        \"content\": \"这是回复内容\"\n    }\n}\n```\n\n### 4.2 被动回复（语音）\n\n需要先上传语音素材获取 media_id：\n\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"media_id\": \"上传后获得的media_id\"\n    }\n}\n```\n\n### 4.3 流式回复\n\n适合长文本生成场景，通过 `response_url` 分批次推送：\n\n```json\n{\n    \"msgtype\": \"stream\",\n    \"stream\": {\n        \"id\": \"STREAM_ID\",\n        \"finish\": false,\n        \"content\": \"...\"\n    }\n}\n```\n\n---\n\n## 五、安全机制\n\n### 5.1 加密方式\n\n- 所有回调消息使用 AES-256-CBC 加密\n- IV 向量为 AESKey 前 16 字节\n- 数据采用 PKCS#7 填充\n\n### 5.2 权限要求\n\n- 需要配置回调 URL、Token、EncodingAESKey\n- 所有通信必须使用 HTTPS\n\n### 5.3 安全限制\n\n- 回调 URL 必须能处理 GET（验证）和 POST（回调）请求\n- 每次回调的 msgid 需用于去重\n- response_url 在消息接收后 48 小时内有效\n\n---\n\n## 六、频率限制\n\n| 操作 | 限制 | 说明 |\n|------|------|------|\n| 被动回复 | 不限制 | 推荐用于实时交互 |\n| API 调用 | 20次/分钟 | 主动调用企业微信 API |\n| 主动发送 | 20次/分钟 | 异步发送消息 |\n| 流式刷新 | 最长6分钟 | 用户发消息后 |\n| 并发交互 | 3条/用户 | 同一用户同时消息数 |\n\n---\n\n## 七、关键注意事项\n\n1. **语音转写由企业微信官方处理**，开发者无法控制 ASR 引擎选择\n2. **语音消息仅限单聊**（`chattype: single`），群聊暂不支持语音\n3. **response_url 有效期**：被动回复的 response_url 仅 48 小时内有效\n4. **临时素材有效期**：上传的媒体文件（语音、图片）3 天后失效，需重新上传\n5. **流式消息需主动结束**：发送 `finish: true` 结束流式消息\n\n---\n\n## 八、开发环境搭建\n\n### 8.1 配置智能机器人\n\n1. 登录企业微信管理后台\n2. 应用管理 → 创建应用 → 配置智能机器人\n3. 设置回调 URL/Token/EncodingAESKey\n4. 开通接收消息权限\n\n### 8.2 本地测试\n\n使用内网穿透工具暴露本地服务（如 frp）：\n\n```bash\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 8.3 验证回调\n\n企业微信发送 GET 请求验证 URL：\n\n```\nGET /callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx\n```\n\n返回解密后的 echostr 原文即可通过验证。\n\n---\n\n## 九、错误码参考\n\n| 错误码 | 含义 | 处理建议 |\n|-------|------|---------|\n| 0 | 成功 | - |\n| 40001 | 不合法的 secret | 检查应用凭证 |\n| 40003 | 不合法的 UserID | 检查用户身份 |\n| 40014 | 不合法的 access_token | 刷新 token |\n| 60020 | 网络连接异常 | 检查企业微信服务器网络 |\n| 84014 | 频率超限 | 降低发送频率，使用队列 |\n| 45009 | 接口调用超过限制 | 实现退避重试机制 |\n\n**完整错误码**：https://developer.work.weixin.qq.com/document/path/90313\n\nFile v2.7.0:skill-card.md\n\n## Description:\n\nWeCom Voice Agent helps an enterprise WeChat assistant process voice callbacks, classify intents, manage multi-turn call workflows, and produce replies, summaries, follow-ups, and support tickets.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nEnterprise WeChat administrators and developers use this skill to operate a voice assistant for WeCom voice messages, inbound or outbound call handling, intent routing, reminders, call notes, and ticket escalation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The security scan reports under-disclosed network, webhook, memory, and sensitive-data handling risks.\n\nMitigation: Review before installation in a real enterprise environment and document every external destination, callback, memory bridge, and data transfer before deployment.\n\nRisk: Webhook and callback handling may expose enterprise messages or actions if callback verification and transport controls are incomplete.\n\nMitigation: Require authenticated WeCom callback verification, HTTPS, replay protection, and destination allowlists for webhooks and custom APIs.\n\nRisk: Recordings, transcripts, call metadata, follow-up tasks, and memory bridge data can contain sensitive personal or business information.\n\nMitigation: Require explicit consent, clear disclosure, retention limits, local storage protections, and access controls for recordings, transcripts, memory, and SQLite databases.\n\nRisk: The artifact includes webhook notification code that disables TLS certificate and hostname verification.\n\nMitigation: Remove disabled TLS verification before deployment and enforce certificate validation for all outbound HTTPS calls.\n\nRisk: Environment-sourced API tokens and webhook secrets could grant access to enterprise systems.\n\nMitigation: Store tokens in managed secrets, limit token scope, rotate credentials, and avoid logging secrets or callback URLs.\n\n## Reference(s):\n\n- [ClawHub release page](https://clawhub.ai/fyniujin/skills/wecom-voice-agent)\n- [WeCom Bot API reference](references/wecom_bot_api.md)\n- [Step-by-step setup guide](references/step_by_step_setup.md)\n- [WeCom intelligent robot documentation](https://developer.work.weixin.qq.com/document/path/101039)\n- [WeCom error code reference](https://developer.work.weixin.qq.com/document/path/90313)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and text responses with JSON-compatible webhook, session, ticket, and call-record data]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May create local SQLite records, local recording files, call summaries, follow-up tasks, and notification payloads when configured.]\n\n## Skill Version(s):\n\n2.7.0 (source: SKILL.md frontmatter and server release evidence)\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 v2.7.0:temp_sessions/call_c1.json\n\n{\r\n  \"call_id\": \"c1\",\r\n  \"userid\": \"u1\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9368465,\r\n  \"last_activity\": 1784103261.9368498,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.7.0:temp_sessions/call_c2.json\n\n{\r\n  \"call_id\": \"c2\",\r\n  \"userid\": \"u2\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9375334,\r\n  \"last_activity\": 1784103261.9375362,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.7.0:temp_sessions/call_c3.json\n\n{\r\n  \"call_id\": \"c3\",\r\n  \"userid\": \"u3\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9383094,\r\n  \"last_activity\": 1784103261.9383125,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.7.0:temp_sessions/call_e2e_001.json\n\n{\r\n  \"call_id\": \"e2e_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.92,\r\n  \"asr_text\": \"同意\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"本次通话可能被录音，请问您是否同意？\",\r\n      \"time\": \"2026-07-15T15:42:59.515560\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"同意\",\r\n      \"confidence\": 0.92,\r\n      \"time\": \"2026-07-15T15:42:59.516113\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.5148604,\r\n  \"last_activity\": 1784101379.5161114,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.7.0:temp_sessions/call_e2e_002.json\n\n{\r\n  \"call_id\": \"e2e_002\",\r\n  \"userid\": \"lisi\",\r\n  \"direction\": \"inbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.65,\r\n  \"asr_text\": \"我要退订\",\r\n  \"pending_confirmation\": \"我要退订\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好请说\",\r\n      \"time\": \"2026-07-15T15:42:59.517207\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"我要退订\",\r\n      \"confidence\": 0.65,\r\n      \"time\": \"2026-07-15T15:42:59.517672\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.51673,\r\n  \"last_activity\": 1784101379.5181956,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.7.0:temp_sessions/call_test_001.json\n\n{\r\n  \"call_id\": \"test_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"ending\",\r\n  \"confidence\": 0.95,\r\n  \"asr_text\": \"明天天气怎么样\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好，我是语音助手\",\r\n      \"time\": \"2026-07-15T16:14:20.407762\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"明天天气怎么样\",\r\n      \"confidence\": 0.95,\r\n      \"time\": \"2026-07-15T16:14:20.408448\"\r\n    },\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"明天北京晴，25度\",\r\n      \"time\": \"2026-07-15T16:14:20.409193\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784103260.4062111,\r\n  \"last_activity\": 1784103260.4112015,\r\n  \"turn_count\": 2\r\n}\n\nArchive v2.6.0: 44 files, 177746 bytes\n\nFiles: config/custom_intents.yaml (1751b), config/intents.yaml (10074b), config/menu.yaml (6093b), README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/call_record_subsystem.py (33040b), scripts/compliance.py (29119b), scripts/custom_intent_plugin.py (9809b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/entity_extractor.py (18803b), scripts/intent_registry.py (16291b), scripts/ivr_engine.py (15638b), scripts/ivr_minutes.py (15155b), scripts/priority_queue.py (21479b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/session_unified.py (24166b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_channel.py (15865b), scripts/voice_simulator.py (6881b), scripts/voicemail_summary.py (15592b), scripts/wecom_webhook_server.py (63393b), skill-card.md (2976b), SKILL.md (46285b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nFile v2.6.0:SKILL.md\n\n---\nname: wecom-voice-agent\nversion: 2.6.0\ndescription: >\n  企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。\n  支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。\n  v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、\n  统一会话管理（双向子系统合并）、多级 IVR 菜单引擎（YAML 配置层级菜单）、实体抽取增强（规则+消歧+复述确认）。\n  当用户向企业微信机器人发送语音消息时触发。核心价值：零 API Key 依赖、硬件自适应、轻量本地处理、全流程合规。\n---\n\n# 企业微信语音消息 Agent\n\n## ⚠️ 风险声明（必读）\n\n### 能力边界\n\n1. **本技能支持企业微信智能机器人场景**，包括被动语音消息处理和主动语音通话\n2. **语音转文字由企业微信官方提供**，本技能不自行采集或上传用户语音至任何第三方\n3. **不会读取或收集**用户的通讯录、聊天记录或其他个人隐私数据\n4. **所有数据处理均在本地完成**，通话记录（含 ASR 转写文本、元数据）持久化存储于本机 SQLite 数据库（`~/.wecom_voice/call_records.db`），录音文件存储于 `~/.wecom_voice/records/`，保留期限默认 90 天，到期自动清理\n5. **主动外呼需管理员授权**，且仅在用户明确同意录音后进行\n\n### 外部连接披露\n\n本技能仅在以下场景发起外部网络连接：\n\n| 目标主机 | 用途 | 触发条件 | 传输数据 |\n|---------|------|---------|---------|\n| `wttr.in` | 天气查询 API | 用户主动发起天气查询请求 | 城市名称（不含用户身份信息） |\n\n**除上述披露外，本技能不会向任何其他外部主机发起连接**。所有外部连接均为只读 GET 请求，不上传任何用户数据。\n\n### 安全风险项\n\n| 风险等级 | 风险描述 | 预防措施 |\n|---------|---------|---------| \n| 🔴 高 | 语音转写准确率受环境噪音影响 | 当置信度低时主动询问用户确认 |\n| 🔴 高 | 误触发（电视/背景音乐被误认为语音） | 设置消息有效时长阈值，超过30秒无新消息则重置上下文 |\n| 🔴 高 | 外呼过程中的隐私泄露风险 | 全程录音告知、用户同意后才录音 |\n| 🟡 中 | 企业微信 API 频率限制（每分钟20次） | 实现请求队列和速率限制器 |\n| 🟡 中 | 长上下文导致 Token 消耗过大 | 自动压缩历史消息，保留最近5轮对话 |\n| 🟢 低 | 语音回复合成超时并发 | 超时后自动降级为文字回复 |\n\n### 合规声明\n\n- 本技能遵守《个人信息保护法》《数据安全法》相关规定\n- 所有操作均基于用户主动发起的对话，不主动采集数据\n- 语音数据由企业微信官方处理，本技能不存储原始音频\n- 用户可随时通过发送文字消息退出语音模式\n- **外呼录音必须获得用户明确同意才进行**\n- **所有录音文件仅存储在本机 `~/.wecom_voice/records/`，永不外传**\n- **通话记录（含 ASR 转写文本、元数据）存储于本机 SQLite，不上传第三方**\n- **数据保留期限：录音文件 90 天，通话记录 180 天，到期自动清理**\n\n---\n\n## 🚀 快速开始\n\n### 方式一：一条命令安装并体验\n\n```bash\n# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n### 方式二：从零手动体验\n\n```bash\n# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats\n```\n\n> ✅ **无需安装任何 Python 包**，所有脚本仅使用 Python 标准库（`sys`、`os`、`json` 等）\n\n---\n\n## 二、架构（v2.6）\n\n```\nwecom-voice-agent/\n├── SKILL.md                  # 本文件（使用说明 + 风险 + 边界 + FAQ + 反模式）\n├── config/\n│   ├── intents.yaml          # v2.6 声明式意图注册表（20+ 意图）\n│   ├── custom_intents.yaml   # v2.6 自定义意图插件配置（企业 API 映射）\n│   └── menu.yaml             # v2.6 IVR 多级菜单配置\n├── references/\n│   ├── wecom_bot_api.md      # 企业微信机器人 API 参考\n│   └── step_by_step_setup.md # 分步部署指南\n├── scripts/\n│   ├── wecom_webhook_server.py # 主服务（回调接收+意图路由+任务执行）\n│   ├── intent_registry.py    # v2.6 声明式意图引擎（YAML 配置+多级澄清）\n│   ├── custom_intent_plugin.py # v2.6 自定义意图插件（企业自有 API 声明式映射）\n│   ├── session_unified.py    # v2.6 统一会话管理（双向子系统，合并原 scheduler+session_manager）\n│   ├── ivr_engine.py         # v2.6 多级 IVR 菜单引擎（YAML 配置+数字/名称双选）\n│   ├── entity_extractor.py   # v2.6 实体抽取增强（规则+消歧+复述确认）\n│   ├── voice_simulator.py    # 语音消息模拟器（本地调试）\n│   ├── detect_hardware.py    # 硬件检测\n│   ├── state_machine.py      # 多轮对话状态机\n│   ├── call_record_subsystem.py # v2.5 通话记录子系统（合并4脚本）\n│   ├── voice_channel.py      # v2.5 多渠道抽象层\n│   ├── voicemail_summary.py  # v2.5 语音留言摘要\n│   ├── dialect_detector.py   # v2.3 方言检测\n│   ├── ticket_manager.py     # v2.3 工单管理\n│   ├── emotion_analyzer.py   # v2.2 情感识别\n│   ├── vad_filter.py         # v2.4 VAD 语音活动检测\n│   ├── priority_queue.py     # v2.4 四级优先级队列\n│   ├── compliance.py         # v2.4 合规录音（v3.0 强制告知）\n│   ├── scheduler.py          # v2.0 外呼调度（已合并至 session_unified）\n│   ├── session_manager.py    # v2.0 会话管理（已合并至 session_unified）\n│   ├── ivr_minutes.py        # v2.0 通话纪要（已合并至 call_record_subsystem）\n│   ├── stats.py              # v2.0 统计看板（已合并至 call_record_subsystem）\n│   └── transcriber.py        # v2.0 全文转写（已合并至 call_record_subsystem）\n└── temp_sessions/             # 运行时临时目录\n```\n\n**核心数据流**：`voice.content → intent_registry（声明式匹配+置信度评分）→ entity_extractor（实体抽取+消歧）→ handler → 任务执行`，同时旁路写入 `session_unified`（统一会话）与 `call_record_subsystem`（通话记录）。\n\n**v2.6 核心理念**：意图配置化（YAML 声明 + 置信度分级 + 多级澄清）、会话统一化（双向合并 + 状态共享）、IVR 配置化（层级菜单 + 双模式选择）、实体智能化（规则抽取 + 上下文消歧 + 复述确认）。\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离手机/麦克风 20-30cm |\n| ❌ 一次说多句话（如\"查日程然后帮我订会议室\"） | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内，长内容请打字 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人**私聊**发语音 |\n| ❌ 发送方言（福建话、河南话等） | ✅ 支持**粤语、四川话、上海话、东北话、闽南话**，直接用方言对话即可，无需切换普通话 |\n| ❌ 说话时周围有电视/音乐 | ✅ 关掉背景音再说话，会被误认为指令 |\n| ❌ 以为能自动打电话/发短信 | ✅ v2.0 起支持外呼，但需管理员授权 |\n| ❌ 语音内容涉及密码/银行信息 | ✅ **切勿在语音中透露敏感信息**，所有文字均经过企业微信服务器 |\n\n---\n\n## 角色定义\n\n你是一名**企业微信语音智能助手**，专门处理企业微信生态内的语音交互场景。你的工作方式是：\n\n1. **被动响应**：只处理用户主动发送的语音消息，不主动拨打/发送（v2.0 起支持主动外呼）\n2. **意图理解**：将语音转写后的文本解析为结构化意图\n3. **任务执行**：调用相应的能力模块完成用户请求\n4. **通话管理**：支持主动外呼、来电接线、多轮对话、合规录音（v2.0 新增）\n5. **友好回复**：根据用户偏好返回文字或语音消息\n\n**你不是一个电话推销员，你是一个办公助手。**\n\n---\n\n## 核心指令\n\n### 一、消息接收阶段（系统自动触发）\n\n当企业微信回调收到 `msgtype: voice` 消息时：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转成文本的内容\"\n    }\n}\n```\n\n**关键步骤**：\n\n1. **提取文本内容**：从 `voice.content` 字段获取转写后的文本\n2. **验证消息有效性**：检查 `msgid` 是否重复（排重），检查消息时效性（超过5分钟则忽略）\n3. **上下文管理**：根据 `msgid` 查找或创建会话上下文\n\n### 二、意图解析阶段\n\n将用户语音文本分类为以下意图类型：\n\n| 意图类型 | 触发关键词 | 处理方式 |\n|---------|-----------|---------|\n| `query_schedule` | 日程、会议、安排、行程、下周、下周有什么 | 调用企业微信日程 skill |\n| `create_todo` | 提醒、待办、任务、别忘了、记得、设提醒 | 调用企业微信待办 skill |\n| `query_weather` | 天气、气温、下雨、温度、穿什么、热不冷 | 调用天气查询模块 |\n| `send_message` | 发消息、告诉、通知、转发、给XX发 | 调用企业微信消息 skill |\n| `help` | 帮助、能做什么、怎么用、功能、你可以做什么 | 返回帮助信息 |\n| `exit_voice` | 退出、不用了、谢谢、结束、再见、拜拜 | 切换到文字模式 |\n| `custom` | 无法识别的意图 | 尝试通用问答或请求澄清 |\n\n**增强版意图解析逻辑**：\n\n```\n步骤1: 精确匹配关键词 → 确定意图类型（多个关键词可叠加分数）\n步骤2: 提取时间/地点/人物等实体信息（支持\"下周\"、\"后天\"、\"明天上午9点\"）\n步骤3: 生成结构化 intent JSON（含置信度评分）\n步骤4: 置信度 > 0.3 → 调用对应处理模块；置信度 ≤ 0.3 → 主动询问用户想做什么\n```\n\n**提升识别准确率的提示**：\n\n当遇到以下模糊表达时，先确认而非猜测：\n\n| 用户说 | 不确定的点 | 确认方式 |\n|--------|----------|---------|\n| \"帮我安排一下\" | 是查日程还是建待办？ | \"您是想查看已有安排，还是需要创建新的提醒？\" |\n| \"下周开会\" | 是哪天？ | \"您是指下周一到周五的哪天呢？\" |\n| \"张三\" | 有多个同名吗？ | \"找到2位张三，请确认是哪个部门的\" |\n| \"明天上午\" | 几点？ | \"好的，明天上午几点呢？\" |\n| \"发给他\" | 发给谁？上下文没有人物 | \"请问要发给谁？\" |\n\n### 三、任务执行阶段\n\n#### 3.1 日程查询 (`query_schedule`)\n\n**输入格式**：\n```json\n{\n    \"intent\": \"query_schedule\",\n    \"entities\": {\n        \"time\": \"明天\",\n        \"date\": \"2024-01-15\",\n        \"person\": \"张三\"\n    }\n}\n```\n\n**执行步骤**：\n1. 解析时间实体（今天/明天/后天/下周三、下周一、下周等）\n2. 调用企业微信日程 API 查询指定日期安排\n3. 整理日程信息（时间-事项-地点）\n4. 格式化为自然语言回复\n\n**输出示例**：\n```\n您明天（1月15日）的日程安排：\n📅 09:00-10:00 周会 - 会议室A\n📅 14:00-15:00 与张三讨论项目 - 线上会议\n📅 16:30-17:00 代码评审 - 开发区\n共 3 项安排。需要我设置提醒吗？\n```\n\n#### 3.2 待办创建 (`create_todo`)\n\n**执行步骤**：\n1. 解析待办内容、截止时间、提醒时间\n2. 调用企业微信待办 API 创建任务\n3. 返回创建结果\n\n#### 3.3 天气查询 (`query_weather`)\n\n**执行步骤**：\n1. 解析地点实体（默认用户所在城市）\n2. 调用天气查询服务（wttr.in 免费 API）\n3. 整理天气信息并语音播报\n\n#### 3.4 消息发送 (`send_message`)\n\n**执行步骤**：\n1. 解析接收人、消息内容\n2. **确认发送意图**（防止误触，发送前让用户确认）\n3. 调用企业微信消息 API 发送\n\n### 四、v2.0 新增：主动通话管理\n\n#### 4.1 主动外呼\n\n**触发条件**：用户/系统发起外呼任务\n\n**执行流程**：\n1. 获取被叫方信息（手机号或用户ID）\n2. 调用企业微信「语音通话」API 发起呼叫\n3. 接通后播放录音告知（\"本次通话可能被录音\"）\n4. 用户同意 → 开始正式通话 + 录音\n5. 用户拒绝 → 继续通话但不录音\n6. 通话结束 → 自动生成纪要 + 保存录音 + 发送纪要\n\n#### 4.2 来电自动接线（IVR 替代）\n\n**触发条件**：用户拨打企业绑定电话\n\n**执行流程**：\n1. 企微电话接通回调触发\n2. Agent 播放欢迎语 + 录音告知\n3. 等待用户语音输入（ASR 转写）\n4. 意图识别 → 执行对应任务\n5. 多轮对话状态机管理交互\n6. 30 秒无新语音自动结束通话\n\n#### 4.3 通话后自动纪要\n\n**触发条件**：通话结束\n\n**执行流程**：\n1. 从 ASR 文字流提取「决策点」「待办项」「时间点」\n2. 输出结构化纪要（markdown 格式）\n3. 通过企微消息 API 发送给呼叫方\n\n#### 4.4 多轮语音对话状态机\n\n**状态定义**：\n- `IDLE` → 空闲/未开始\n- `DIALING` → 拨号中\n- `SPEAKING` → Agent 说话中（TTS 播报）\n- `LISTENING` → 等待用户语音输入\n- `CONFIRMING` → 二次确认中（ASR 置信度低）\n- `ENDING` → 通话结束中\n\n**超时机制**：30 秒无新语音自动结束通话\n\n#### 4.5 合规录音告知 + 本地存储\n\n**执行流程**：\n1. 通话开始时播放「本次通话可能被录音，用于服务品质监控。请问您是否同意？」\n2. 用户回应「同意」→ 开始录音\n3. 录音文件存储到本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n4. 录音记录存本地 SQLite\n5. **不上传任何第三方**\n\n#### 4.6 外呼任务调度\n\n**功能**：\n- 定时外呼（每天9点提醒）\n- 批量外呼（CSV/JSON 导入客户列表）\n\n**实现方式**：\n- 使用 `sched` + `threading` 实现定时调度\n- CSV/JSON 批量导入客户列表\n- 并发控制（默认最大 3 路并发）\n\n### 五、回复生成阶段\n\n#### 5.1 文字回复\n\n当用户发送的语音消息内容较简单，或用户明确表示\"用文字回复我\"时：\n\n```\n回复格式要求：\n- 简洁明了，每段不超过3行\n- 使用 emoji 增强可读性\n- 包含下一步操作建议\n```\n\n#### 5.2 语音回复\n\n当用户明确表示\"用语音告诉我\"，或回复内容较长（超过100字）时：\n\n**语音合成流程**：\n1. 调用本地 TTS 引擎生成语音文件\n2. 上传至企业微信获取 media_id\n3. 通过 response_url 发送语音消息\n\n**TTS 引擎选择优先级**：\n```\n优先级1: Edge TTS（免费，无需 API Key，中文效果良好）\n优先级2: 火山引擎 TTS（音色更自然，需配置 API Key）\n```\n\n### 六、多轮对话管理\n\n> ⚠️ **重要说明**：v2.0 起提供**完整的通话状态机**（`state_machine.py`），\n> 支持多轮语音对话的上下文管理和超时自动结束。\n\n**上下文保持规则**：\n- 同一用户（同一 `msgid` 前缀）连续消息视为一轮对话\n- 单轮对话最多保留 **5 条消息**（3条用户 + 2条助手）\n- 超过5条后自动压缩：保留第一条用户消息 + 最近2条消息\n- **对话超时**：用户连续 30 秒（通话模式）/ 60 秒（文字模式）无新消息则自动结束上下文\n\n**上下文数据结构**：\n```json\n{\n    \"session_id\": \"userid_timestamp\",\n    \"messages\": [...],\n    \"current_intent\": \"query_schedule\",\n    \"collected_entities\": {\"time\": \"明天\"},\n    \"awaiting\": \"date\",\n    \"created_at\": 1705286400\n}\n```\n\n---\n\n## 硬件自适应优化\n\n### 自动检测与分级\n\n本技能启动时自动检测用户计算机系统资源，并根据结果调整并发和缓存策略：\n\n| 硬件等级 | RAM 范围 | CPU 核心数 | 并发处理能力 | 上下文缓存 |\n|---------|---------|-----------|------------|-----------|\n| 🟢 高配 | ≥ 16GB | ≥ 8核 | 同时处理 5 路会话 | 保留 100 轮历史 |\n| 🟡 中配 | 8-16GB | 4-8核 | 同时处理 3 路会话 | 保留 20 轮历史 |\n| 🔴 低配 | < 8GB | < 4核 | 同时处理 1 路会话 | 保留 5 轮历史 |\n\n**检测方式**：\n- WorkBuddy 环境：读取系统信息和 Node.js `os` 模块\n- 独立脚本：使用 Windows API (`GlobalMemoryStatusEx`) 获取真实硬件参数\n\n### 性能保障措施\n\n1. **懒加载机制**：非核心模块在首次使用时才加载\n2. **资源回收**：对话结束后立即释放占用的内存和临时文件\n3. **超时保护**：语音转写受网络影响，超时后自动提示用户重试\n4. **日志限制**：本地日志文件最大 100KB，自动轮转覆盖\n\n---\n\n## 更新通知机制\n\n### 版本检查\n\n本技能在每次执行时（频率限制为每6小时一次）执行以下检查：\n\n1. 本地安装版本号 vs 云端最新版本号\n2. 如有新版本，向用户发送更新提醒消息\n\n**提醒格式**：\n```\n🎉 发现新版本：v2.0.0\n主要改进：\n- 新增主动外呼、来电接线、通话纪要\n- 新增合规录音告知、外呼任务调度\n- 新增通话记录看板、全文转写\n\n请运行以下命令更新：\nskillhub install wecom-voice-agent --force\n```\n\n### 自动更新（可选）\n\n用户可通过发送\"检查更新\"触发版本检查，或通过以下命令手动更新：\n\n```bash\nskillhub install wecom-voice-agent --force\n```\n\n---\n\n## 示例场景\n\n### 场景1：语音查日程\n\n**用户（语音）**：明天有什么会议？\n\n**企业微信回调**：\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\"content\": \"明天有什么会议\"}\n}\n```\n\n**助手回复**：\n```\n您明天（7月9日）的日程安排：\n\n📅 09:00-10:00 产品周会 - 大会议室\n📅 14:00-15:30 客户拜访 - 上海浦东\n📅 16:00-17:00 团队代码评审\n\n共 3 项。需要我设置提前30分钟提醒吗？\n```\n\n### 场景2：语音建待办\n\n**用户（语音）**：提醒我下午3点提交报告\n\n**助手回复**：\n```\n✅ 已创建待办提醒：\n⏰ 时间：今天下午3:00\n📝 内容：提交报告\n\n需要我同时在团队群里发一条提醒吗？\n```\n\n### 场景3：连续对话\n\n**用户（语音）**：今天天气怎么样？\n**助手回复**：\n```\n北京今日天气：\n🌤️ 多云  28°C ~ 35°C\n💡 建议：带伞，可能有阵雨\n🌬️ 东南风 3级\n```\n\n**用户（语音）（追问）**：**那明天呢？**\n\n**助手回复**（利用上下文，知道地点仍然是北京）：\n```\n北京明天天气：\n🌧️ 小雨  24°C ~ 30°C\n💡 建议：带伞，穿薄外套\n\n看起来明天要下雨，需要我帮您调整明天的外出安排吗？\n```\n\n### 场景4：模糊表达处理\n\n**用户（语音）**：帮我安排一下\n\n**助手回复**（主动确认，不猜测）：\n\n```\n我可以帮您：\n1️⃣ 查看日程安排（您想查哪天？）\n2️⃣ 创建待办提醒（提醒什么内容？）\n3️⃣ 查询天气（哪个城市？）\n\n请告诉我您想做什么。\n```\n\n### 场景5：误触发处理\n\n**用户（语音）**：（环境噪音 / 电视声音）\n\n**助手回复**：\n```\n抱歉，我没有听清楚您的语音内容 😅\n\n请用清晰的语音告诉我您需要什么帮助，例如：\n• \"查一下明天的日程\"\n• \"提醒我下午开会\"\n• \"发消息给张三\"\n```\n\n### 场景6：v2.0 主动外呼\n\n**系统**：发起外呼任务 → 拨打 13800138000\n\n**Agent**（接通后）：\n```\n您好，我是XX公司的语音助手。本次通话可能被录音，用于服务品质监控。请问您是否同意？\n```\n\n**用户**：同意\n\n**Agent**：\n```\n好的，感谢您的确认。我们想确认一下，您明天下午3点的会议安排是否有变化？\n```\n\n**用户**：没有变化，按时参加\n\n**Agent**：\n```\n好的，已为您确认。通话结束后我们会发送纪要至您的企业微信。祝您愉快！\n```\n\n### 场景7：v2.0 来电接线\n\n**用户**：拨打企业绑定电话\n\n**Agent**：\n```\n您好，欢迎致电XX公司。我是智能语音助手，请问您需要什么帮助？\n```\n\n**用户**：我要退订\n\n**Agent**（二次确认，ASR 置信度 0.7 < 0.85）：\n```\n抱歉，我没有完全听清。您说的是「我要退订」吗？请确认「是」或「不是」。\n```\n\n**用户**：是\n\n**Agent**：\n```\n好的，已为您提交退订申请。受理编号：TK20260715001。我们会在3个工作日内处理。还有其他需要帮助的吗？\n```\n\n---\n\n## 错误处理\n\n### 常见错误与处理方式\n\n| 错误类型 | 触发条件 | 友好提示 |\n|---------|---------|---------| \n| 语音转写失败 | `voice.content` 为空或乱码 | \"抱歉，您的语音没有识别成功，请重新发送或尝试用普通话慢慢说。\" |\n| API 调用失败 | HTTP 4xx/5xx 错误码 | \"当前网络繁忙，请稍后再试。如您连续遇到问题，可尝试重启企业微信应用。\" |\n| 意图识别失败 | 关键词匹配度 < 0.3 | 主动询问用户意图，提供选项菜单（见\"模糊表达处理\"场景） |\n| TTS 合成失败 | 语音文件生成超过5秒 | 改为文字回复，附加提示：\"语音播报暂时不可用，已为您用文字显示。\" |\n| 上下文过期 | 对话间隔 > 60秒 | 自动开始新对话，回复：\"检测到新会话，请问有什么可以帮您的？\" |\n| 找不到会话 | 查询不存在的 session_id | \"会话不存在或已过期，请重新发送语音指令。\" |\n| 硬件检测失败 | Windows API 或 WMI 均不可用 | \"无法检测硬件配置，已自动使用'低配'模式保障运行。\" |\n| 外呼失败 | 被叫方无应答/占线 | \"暂时无法接通，请稍后重试或留下口信。\" |\n| 录音失败 | 本地存储空间不足 | \"存储空间不足，已自动清理旧录音。请重试。\" |\n\n### 异常退出策略\n\n当发生严重错误时：\n\n1. **用中文向用户道歉**并简要说明原因（不要暴露技术术语如 \"Traceback\"、\"HTTP 500\"）\n2. **记录错误信息**到本地日志 `D:/skill/wecom-voice-agent/temp_sessions/error.log`\n3. **清理临时文件**（音频文件、缓存数据）\n4. **恢复初始状态**，等待下一条用户消息\n5. **连续失败3次**时主动提示用户：\"检测到连续操作失败，请检查网络连接或稍后重试。\"\n\n**错误提示原则**：\n- ❌ \"Error: connection refused\"（技术术语）\n- ✅ \"无法连接到服务，请检查您的网络后重试。\"（用户语言）\n- ❌ \"Traceback (most recent call last)...\"（堆栈信息）\n- ✅ \"系统遇到了临时问题，已自动恢复，请重新发送指令。\"（友好提示）\n\n---\n\n## FAQ\n\n### Q1：这个技能需要额外的 API Key 吗？\n**A**：不需要核心 API Key。企业微信内置的语音转文字功能免费使用。\n如果您希望使用更优质的语音合成（火山引擎 TTS），可选配置 API Key，但 Edge TTS 完全免费且开箱即用。\n\n### Q2：支持哪些方言或语言？\n**A**：v2.3.0 起内置**方言检测引擎**，自动识别粤语、四川话、上海话、东北话、闽南话 5 大方言，并使用对应的方言风格回复。无需切换普通话，直接说方言即可。\n\n### Q3：语音消息长度有限制吗？\n**A**：企业微信智能机器人接收的语音消息通常限制在 60 秒以内。\n如需处理更长的录音，请使用企业微信的「文件上传」功能，后续版本将支持长语音转写。\n\n### Q4：隐私安全吗？我的语音数据会被上传吗？\n**A**：**绝对不会**。本技能不存储、不上传、不转发用户的任何语音数据。\n语音转写完全由企业微信官方接口完成，本技能仅接收转写后的文本内容。\nv2.0 起外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传。\n\n### Q5：支持群聊吗？\n**A**：当前仅支持单聊（`chattype: single`），以确保语音转写准确率和隐私安全。\n群聊支持将在后续版本中评估后决定。\n\n### Q6：能在手机上使用吗？\n**A**：可以。只要您的 WorkBuddy 客户端运行并连接到企业微信，手机端和 PC 端均可使用。\n\n### Q7：并发能力如何？\n**A**：单用户模式下，本技能可同时处理多个企业微信用户的语音请求，\n具体并发数根据您的电脑硬件自动调整（1-5路并发）。\n外呼任务并发默认最大值 3 路（可在 `scheduler.py` 中调整）。\n\n### Q8：如何卸载或停止？\n**A**：发送文字消息\"退出语音模式\"即可停止语音助手。\n如需完全卸载，请运行：`skillhub uninstall wecom-voice-agent`\n\n### Q9：为什么有时候听不懂我说的话？\n**A**：语音转写准确率受以下因素影响：\n- 环境噪音（电视、空调、外部人声）\n- 说话方言或口音较重\n- 语音消息超过 60 秒\n- 一次发送多步指令（如\"查日程然后订会议室\"）\n\n**建议**：一次只说一件事，用普通话在安静环境发送，控制在 60 秒以内。\n\n### Q10：v2.0 外呼功能合规吗？\n**A**：完全合规。外呼功能遵守以下原则：\n- **录音告知**：通话开始时明确告知用户\"本次通话可能被录音\"\n- **用户同意**：必须用户明确同意后才开始录音\n- **本地存储**：录音文件仅存储在本机 `~/.wecom_voice/records/`，不上传第三方\n- **随时退出**：用户可在通话中随时要求终止录音\n\n### Q11：遇到错误了屏幕上显示英文？\n**A**：本技能已将所有错误提示改为中文。如果您仍看到英文：\n1. 可能是企业微信官方 API 返回的英文错误\n2. 请将错误截图发送至 **njskills@agent.qq.com**，我们会处理\n\n---\n\n## 脚本与使用指南\n\n### v2.6 新增脚本\n\n#### scripts/intent_registry.py\n\n声明式意图引擎。加载 `config/intents.yaml`，实现关键词匹配、置信度计算、多级澄清策略。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/intent_registry.py\n```\n\n**特性**：\n- 20+ 意图声明式配置（query/action/system 三大类）\n- 关键词匹配 + 置信度评分（匹配多关键词有加分）\n- 多级澄清：≥0.7 直接执行、0.4-0.7 反问收窄、<0.4 转帮助\n- 新增意图只改 `config/intents.yaml`，不改代码\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n---\n\n#### scripts/custom_intent_plugin.py\n\n自定义意图插件引擎。允许企业通过 `config/custom_intents.yaml` 将意图映射到自有 HTTP API。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/custom_intent_plugin.py\n```\n\n**特性**：\n- 声明式端点 URL、HTTP 方法、请求模板\n- 响应字段映射到话术模板（`{{field.path}}` 嵌套取值）\n- 鉴权通过环境变量读取（`auth_env` 字段指定变量名）\n- 超时/失败兜底话术\n- 纯标准库（urllib）\n\n**配置示例**（`config/custom_intents.yaml`）：\n```yaml\nintents:\n  query_order:\n    endpoint: \"https://api.example.com/orders\"\n    method: \"GET\"\n    auth_env: \"ORDER_API_TOKEN\"\n    timeout: 10\n    request_template:\n      order_id: \"{order_id}\"\n    response_template: \"您的订单{{order.status}}，预计{{order.eta}}送达。\"\n    fallback_text: \"订单查询服务暂不可用，请稍后再试。\"\n```\n\n---\n\n#### scripts/session_unified.py\n\n统一会话管理。合并原 scheduler.py（外呼调度）与 session_manager.py（被动接收）为双向子系统。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/session_unified.py\n```\n\n**特性**：\n- 统一会话表（session_id / direction / status / context）\n- 入站（inbound）/ 出站（outbound）/ 语音留言（voicemail）三向统一管理\n- 状态机复用（state_machine.py 的 CallStateMachine）\n- 记录与统计同源（call_record_subsystem.py）\n- SQLite 持久化 + 自动清理过期会话\n- 纯标准库（sqlite3 + threading）\n\n---\n\n#### scripts/ivr_engine.py\n\n多级 IVR 菜单引擎。加载 `config/menu.yaml`，支持层级菜单导航。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_engine.py\n```\n\n**特性**：\n- YAML 配置化层级菜单（根菜单 → 子菜单 → 意图触发）\n- 说数字或说名称双选择方式\n- 0 = 重复听、9 = 转人工、8 = 返回上级\n- 超时/非法输入/重试次数限制\n- 纯标准库（yaml 可选，不可用时降级 JSON）\n\n**菜单结构**（`config/menu.yaml`）：\n- 根菜单：销售咨询 / 技术支持 / 财务报销 / 订单物流 / 人工服务\n- 子菜单：每个大类下 3-4 个具体服务意图\n- 全局特殊按键：0 重复、9 转人工、8 返回\n\n---\n\n#### scripts/entity_extractor.py\n\n实体抽取增强模块。规则层 + 上下文消歧 + 复述确认。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/entity_extractor.py\n```\n\n**特性**：\n- 规则层：时间、日期、人物、地点、订单号、金额、手机号、邮箱、百分比、数量\n- 上下文消歧：代词回指（\"他\"→上一轮提到的人）、省略补全\n- 复述确认：格式化实体回显（\"请确认：日期：XX，时间：XX...\"）\n- 纯标准库（re + datetime）\n\n---\n\n### 本地测试脚本（已有）\n\n#### scripts/detect_hardware.py\n\n自动检测用户计算机硬件资源，输出硬件等级配置。\n\n```bash\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n```\n\n**输出示例**：\n```json\n{\n    \"level\": \"medium\",\n    \"ram_gb\": 16.0,\n    \"cpu_cores\": 6,\n    \"concurrency\": 3,\n    \"cache_limit\": 20,\n    \"description\": \"中配 - 支持3路并发，20轮历史缓存\",\n    \"platform\": \"win32\"\n}\n```\n\n#### scripts/voice_simulator.py\n\n模拟企业微信语音消息回调，用于本地调试意图解析逻辑。\n\n```bash\n# 基础用法\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 指定用户\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京天气\" --userid zhangsan\n\n# JSON 格式输出\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"提醒我开会\" --format json\n```\n\n#### scripts/session_manager.py\n\n管理对话上下文，支持创建、查询、清理会话。\n\n```bash\n# 创建新会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\n\n# 查询会话状态（表格格式）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py get --session_id xxx --format table\n\n# 查找用户活跃会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py find --userid zhangsan\n\n# 向会话添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py add --session_id xxx --role user --content \"你好\"\n\n# 清理过期会话（默认120秒）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py cleanup --timeout 180\n\n# 查看所有会话统计\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n#### scripts/wecom_webhook_server.py\n\n企业微信智能机器人回调服务器。接收企业微信推送的消息回调，自动处理语音消息。\n\n```bash\n# 一键体验所有功能（无需启动服务）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --quick\n\n# 启动服务器（默认端口 8080）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py\n\n# 指定端口\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --port 9000\n```\n\n**v2.0 核心升级**：\n- ✅ **真正的天气查询**：调用 wttr.in 免费 API（无需 key），中文描述 + 穿衣建议\n- ✅ **当前时间查询**：本地计算，100%可用，无需任何网络依赖\n- ✅ **意图识别增强**：关键词 + 正则混合匹分，置信度评分\n- ✅ **多轮对话**：根据 `msgid` 去重，会话缓存管理\n- ✅ **中文错误提示**：全部错误给出具体解决步骤\n\n**部署步骤**：\n1. 启动服务器：`python scripts/wecom_webhook_server.py --port 8080`\n2. 使用内网穿透暴露 8080 端口（frp/ngrok）\n3. 将穿透后的 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n4. 发送语音消息测试\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n---\n\n#### scripts/state_machine.py\n\n多轮对话状态机。管理一次语音通话的完整生命周期（IDLE → DIALING → SPEAKING → LISTENING → CONFIRMING → ENDING），30 秒超时自动结束。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/state_machine.py\n```\n\n**特性**：\n- 状态持久化到本地 JSON（支持断线恢复）\n- ASR 置信度 < 0.85 时自动进入 CONFIRMING 二次确认\n- `StateMachineManager` 支持多通话并发管理\n\n---\n\n#### scripts/compliance.py\n\n合规录音管理器。提供录音告知、本地存储、SQLite 持久化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/compliance.py\n```\n\n**特性**：\n- 录音前播放告知文本，用户同意后才录音\n- 录音文件存储在本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n- SQLite 记录主叫/被叫/时长/时间/意图\n- **不上传任何第三方**\n\n---\n\n#### scripts/ivr_minutes.py\n\n通话后自动纪要。从 ASR 文字流中提取决策点、待办项、时间点。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/ivr_minutes.py\n```\n\n**特性**：\n- 正则 + 规则提取，无需外部 API\n- 输出结构化 markdown 格式纪要\n- 支持简单情感分析（积极/中性/消极）\n\n---\n\n#### scripts/scheduler.py\n\n外呼任务调度器。支持定时外呼和批量外呼。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/scheduler.py\n```\n\n**使用方式**：\n```python\nfrom scheduler import OutboundScheduler, MockCallExecutor\n\nscheduler = OutboundScheduler(executor=MockCallExecutor())\nscheduler.start()\n\n# 添加一次性外呼\nscheduler.add_one_shot(\"task_001\", \"13800138000\", \"预约确认\", \"2026-07-15T09:00:00\")\n\n# 添加每日定时外呼\nscheduler.add_daily(\"task_002\", \"13800138000\", \"早安提醒\", \"09:00\")\n\n# 批量外呼（CSV 导入）\nscheduler.add_batch([\n    {\"target\": \"13900139000\", \"name\": \"客户A\", \"script\": \"预约确认\"},\n    {\"target\": \"13900139001\", \"name\": \"客户B\", \"script\": \"回访\"},\n])\n```\n\n**CSV 导入格式**：\n```csv\ntarget,name,script\n13800138000,张三,预约确认\n13800138001,李四,回访\n```\n\n---\n\n#### scripts/stats.py\n\n通话记录看板。输出通话统计数据和趋势图。\n\n```bash\n# 本月看板\npython D:/skill/wecom-voice-agent/scripts/stats.py\n\n# 本周看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period week\n\n# 本年度看板\npython D:/skill/wecom-voice-agent/scripts/stats.py --period year\n\n# 按用户筛选\npython D:/skill/wecom-voice-agent/scripts/stats.py --userid zhangsan\n\n# 导出 JSON\npython D:/skill/wecom-voice-agent/scripts/stats.py --export stats.json\n```\n\n**输出指标**：\n- 总通话次数、总时长、平均时长\n- 外呼/来电比例、接听率、录音覆盖率\n- 意图分布、挂断原因分布\n- 每日趋势 ASCII 图\n\n---\n\n#### scripts/transcriber.py\n\n通话录音文字转写全文。输出 .txt（标准库）和 .docx（可选）。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/transcriber.py\n```\n\n**使用方式**：\n```python\nfrom transcriber import TranscriptWriter\n\nwriter = TranscriptWriter()\nturns = [\n    {\"role\": \"user\", \"content\": \"你好\", \"time\": \"2026-07-15T10:00:00\"},\n    {\"role\": \"agent\", \"content\": \"您好，请问有什么需要帮助？\", \"time\": \"2026-07-15T10:00:05\"},\n]\n\n# 输出 TXT（纯标准库）\nwriter.write_txt(turns, call_id=\"call_001\")\n\n# 输出 DOCX（需 python-docx）\nwriter.write_docx(turns, call_id=\"call_001\")\n```\n\n---\n\n#### scripts/call_record_subsystem.py（v2.5 新增）\n\n通话记录子系统。合并原 4 个脚本（compliance/ivr_minutes/stats/transcriber）为统一接口。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/call_record_subsystem.py\n```\n\n**使用方式**：\n```python\nfrom call_record_subsystem import CallRecordSubsystem\n\ncrs = CallRecordSubsystem()\ncrs.create_record(\"call_001\", \"13800138000\", \"13900139000\", \"outbound\")\ncrs.give_consent(\"call_001\", True)\ncrs.add_audio(\"call_001\", audio_data)\ncrs.add_transcript(\"call_001\", \"用户: 你好\\n助手: 您好\", \"greeting\")\nminutes = crs.generate_minutes(\"call_001\")\nstats = crs.get_stats(\"month\")\n```\n\n---\n\n#### scripts/voice_channel.py（v2.5 新增）\n\n多渠道抽象层。支持企业微信/钉钉/飞书消息解析和标准化。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voice_channel.py\n```\n\n**使用方式**：\n```python\nfrom voice_channel import VoiceChannelFactory, ChannelType\n\n# 解析企微回调\nmsg = VoiceChannelFactory.parse_wechat_callback(callback_dict)\n# 解析钉钉回调\nmsg = VoiceChannelFactory.parse_dingtalk_callback(callback_dict)\n# 解析飞书回调\nmsg = VoiceChannelFactory.parse_feishu_callback(callback_dict)\n\n# 获取渠道处理器\nchannel = VoiceChannelFactory.get_channel(ChannelType.WECHAT)\n```\n\n---\n\n#### scripts/voicemail_summary.py（v2.5 新增）\n\n语音留言摘要系统。当用户无法接听时，语音留言自动转录并生成结构化摘要。\n\n```bash\n# 运行自测\npython D:/skill/wecom-voice-agent/scripts/voicemail_summary.py\n```\n\n**使用方式**：\n```python\nfrom voicemail_summary import VoicemailSummarizer\n\nsummarizer = VoicemailSummarizer()\nresult = summarizer.process_voicemail(\"vm_001\", \"13800138000\", \"帮我查订单状态\")\nprint(result[\"summary\"])\n\n# 批量处理\nresults = summarizer.batch_process([\n    {\"vm_id\": \"vm_001\", \"caller\": \"13800138000\", \"content\": \"查订单\"},\n    {\"vm_id\": \"vm_002\", \"caller\": \"13900139000\", \"content\": \"投诉\"},\n])\n```\n\n---\n\n### 配置文件\n\n本技能无需额外配置文件即可运行。\n\n如需自定义配置，可在工作项目录下创建 `.workbuddy/wecom-voice-agent.yaml`：\n\n```yaml\n# 企业微信语音消息 Agent 配置\n# 所有选项均为可选，使用括号内默认值\n\ntts_engine: edge  # edge 或 volcengine\nlog_level: info   # debug | info | warning | error\nsession_timeout: 60  # 对话超时时间（秒）\nmax_history: 5     # 单轮最大消息数\n# v2.0 新增\ncall_timeout: 30   # 通话超时时间（秒）\nmax_concurrent_calls: 3  # 最大并发外呼数\nconfidence_threshold: 0.85  # ASR 置信度二次确认阈值\nrecords_dir: ~/.wecom_voice/records  # 录音存储路径\n```\n\n---\n\n## 联系与反馈\n\n### 邮箱\n\n如有更好的建议或遇到问题，请发送邮件至：\n\n**njskills@agent.qq.com**\n\n### 问题反馈模板\n\n```\n标题：[wecom-voice-agent] 问题简述\n\n环境信息：\n- WorkBuddy 版本：\n- 企业微信版本：\n- 操作系统：\n\n问题描述：\n- 预期行为：\n- 实际行为：\n- 复现步骤：\n\n是否愿意提供调试日志：是/否\n```\n\n---\n\n## 更新日志\n\n| v2.6.0 | 2026-08-24 | 重构：声明式意图引擎 intent_registry.py（intents.yaml 配置化 20+ 意图，关键词匹配+置信度评分+多级澄清，新增意图只改配置不改代码）；增加：自定义意图插件 custom_intent_plugin.py（custom_intents.yaml 声明企业自有 API 映射，请求/响应模板+鉴权环境变量+失败兜底）；增加：统一会话管理 session_unified.py（合并 scheduler.py 与 session_manager.py 为双向子系统，统一会话表/状态机/统计）；增加：多级 IVR 菜单引擎 ivr_engine.py（menu.yaml 配置化层级菜单，0 重复听/9 转人工/8 返回上级，说数字或说名称双选择）；增加：实体抽取增强 entity_extractor.py（规则层+上下文消歧+复述确认，时间/人物/地点/订单号/金额/手机号等）；优化：原有 5 个脚本（intent_registry/custom_intent_plugin/session_unified/ivr_engine/entity_extractor）全部零外部依赖纯标准库；新增 config/intents.yaml、config/custom_intents.yaml、config/menu.yaml 三个声明式配置文件 |\n| v2.5.1 | 2026-08-17 | 修复：移除 compliance.py 中对伪造域名 edge-tts.anthropic.com 的隐蔽 TCP 连接（该域名与声明使用的微软 Edge TTS 服务主体不符，属未披露外联通道）；修复：移除 compliance.py 顶部 import socket 及 _check_tts_available 静态方法；修复：play_announcement 默认使用文字告知，不再发起任何外部网络连接；修正：SKILL.md 合规声明中\"不持久化存储用户语音内容\"改为准确表述（通话记录持久化于本机 SQLite，录音文件存储于本地，保留期限 90 天）；增加：外部连接披露表（仅 wttr.in 天气查询 API，不含用户身份信息） |\n| v2.5.0 | 2026-08-17 | 合并：ivr_minutes.py、compliance.py、stats.py、transcriber.py 为 call_record_subsystem.py 通话记录子系统（录音+纪要+元数据+统计一体，消除4脚本分散调用）；增加：多渠道抽象层 voice_channel.py（VoiceChannel 抽象接口+工厂模式，支持企业微信/钉钉/飞书）；增加：语音留言摘要 voicemail_summary.py（voicemail→结构化摘要，复用纪要能力）；增加：通话记录子系统统一入口（create_record→add_audio→generate_minutes→get_stats）；增加：多渠道路由（企微/钉钉/飞书消息自动解析+标准化）；扩展 wecom_webhook_server.py 语音留言处理+多渠道接入；新增 call_record_subsystem.py、voice_channel.py、voicemail_summary.py 三个脚本 |\n| v2.4.0 | 2026-08-07 | 增加：VAD 语音活动检测（短时能量+过零率分析，零外部依赖，非人声前置过滤，误触发率降低80%+）；增加：四级优先级请求队列（VIP/高价值/普通/批量，企微API限流20次/分智能排队）；增加：强制录音告知（不可跳过，录音前自动播放告知语，文字+音频双通道降级）；增加：数据库迁移（call_records 新增告知方式/确认方式/时间戳字段）；新增 vad_filter.py、priority_queue.py 脚本；升级 compliance.py 至 v3.0（强制录音告知系统）；扩展 wecom_webhook_server.py VAD 前置过滤+优先级路由 |\n| v2.3.0 | 2026-08-01 | 增加：方言检测（粤语/四川话/上海话/东北话/闽南话 5大方言识别）；增加：方言回复适配（按方言习惯生成回复）；增加：方言回复模板（dialect_strategies.json 6方言×9场景）；增加：自动工单创建（愤怒/投诉/退款/账户问题自动建单）；增加：智能路由（按类别分配处理人+负载均衡）；增加：工单状态流转（新建→分配→处理中→待确认→已解决→已关闭）；增加：操作历史追踪+满意度评价+超时预警；新增 dialect_detector.py、ticket_manager.py 脚本；新增 dialect_strategies.json 模板；扩展 session_manager.py 方言+工单字段；扩展 wecom_webhook_server.py 方言+工单集成 |\n| v2.2.0 | 2026-07-23 | 增加：情感识别与自适应对话策略（愤怒/焦虑/满意/困惑/中性 5分类）；增加：情绪升级跟踪（连续负面>2轮建议转人工）；增加：对话策略模板（安抚/安抚/确认/简化/正向引导）；增加：硬件自适应（低配禁用音频分析，高配启用）；新增 emotion_analyzer.py 脚本、emotion_strategies.json 策略模板；扩展 session_manager.py 情感状态跟踪 |\n| v2.1.0 | 2026-07-15 | 修复bug：安全审计修复（移除测试代码中的 /etc/passwd 路径引用，改为安全测试字符串） |\n| v2.0.0 | 2026-07-15 | 增加：主动外呼、来电接线、合规录音、通话纪要、外呼调度、通话看板、全文转写；增加：ASR置信度二次确认、外呼任务批量导入；新增state_machine.py、compliance.py、ivr_minutes.py、scheduler.py、stats.py、transcriber.py六个脚本 |\n| v1.3.0 | 2026-07-10 | 增加：wttr.in天气查询（中文描述+穿衣建议）；增加：本地时间查询（100%可用）；增加：--quick一键体验模式；增加：意图识别增强（关键词+正则混合匹配）；修复：回复不再出现\"需要配置API接入\"，改为真正执行 |\n| v1.2.0 | 2026-07-09 | 增加：wecom_webhook_server.py企业微信回调服务器；增加：step_by_step_setup.md分步部署指南；增加：多消息类型支持（文本/语音/图片/文件/视频） |\n| v1.1.0 | 2026-07-09 | 增加：避坑指南（8个常见坑+正确做法）；增加：模糊表达处理策略（不确定时主动确认）；增加：连续失败3次自动提示；增加：错误提示原则（用户语言 vs 技术术语） |\n| v1.0.0 | 2026-07-08 | 初始版本发布，包含企业微信语音消息回调、意图识别、多轮对话 |\n\n### 后续规划\n- v2.7.0：群聊语音消息支持\n- v2.8.0：语音声纹识别（区分不同说话人）\n- v3.0.0：多模态能力（图片+语音混合消息）+ 对接外部CRM\n\n---\n\n## 许可与版权\n\n© 2026 njskills. 保留所有权利。\n\n本技能基于 MIT 许可证开源，允许个人和商业使用，但不得声称对原始作品拥有版权。\n\n**免责声明**：本技能按\"原样\"提供，作者不对因使用本技能造成的任何损失承担责任。\n\n---\n\n*版本：v2.6.0 ｜ 许可：MIT ｜ 核心纯标准库、零密钥打包、可只读审计。*\n\nFile v2.6.0:README.md\n\n# 企业微信语音消息 Agent\n\n## ✨ 核心特性\n\n- **零 API Key 依赖** - 企业微信内置 ASR 语音转文字免费使用\n- **硬件自适应** - 自动检测用户电脑配置，调整并发和缓存策略\n- **真正的天气查询** - 接入 wttr.in 免费 API，中文描述 + 穿衣建议\n- **当前时间查询** - 本地计算，100%可用，无需任何网络依赖\n- **主动外呼** - v2.0 起支持主动发起语音通话（预约确认、快递提醒、服务回访）\n- **来电接线** - v2.0 起支持用户拨打企业绑定电话自动接线（IVR 替代）\n- **通话纪要** - v2.0 起通话结束自动生成结构化纪要\n- **合规录音** - v2.0 起全程合规（录音告知、用户同意、本机存储、不上传）\n- **外呼调度** - v2.0 起支持定时外呼和批量外呼（CSV 导入）\n- **多轮对话** - 支持上下文保持的连续对话\n- **性能优先** - 低配电脑也能流畅运行\n- **安全可靠** - 所有数据处理在本地完成，不上传用户隐私\n- **开箱即用** - 纯 Python 标准库，无需安装任何依赖\n\n## 🚀 快速开始\n\n### 一条命令体验所有功能\n\n```bash\n# 1. 一键测试（无需启动服务）\ncd D:/skill/wecom-voice-agent\npython scripts/wecom_webhook_server.py --quick\n\n# 2. 单独测试某个指令\npython scripts/voice_simulator.py --text \"北京今天天气怎么样\"\npython scripts/voice_simulator.py --text \"现在几点\"\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n```\n\n### 部署真实机器人\n\n```bash\n# 1. 启动回调服务器\npython scripts/wecom_webhook_server.py --port 8080\n\n# 2. 使用内网穿透暴露端口\nngrok http 8080\n# 或\nfrpc http -l 8080 -p your-domain.com\n\n# 3. 将穿透 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n\n# 4. 发送语音消息测试\n```\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n## 🪤 避坑指南\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离麦克风 20-30cm |\n| ❌ 一次说多句话 | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人私聊发语音 |\n| ❌ 发送方言 | ✅ 用普通话或粤语发送 |\n\n## 📁 项目结构\n\n```\nwecom-voice-agent/\n├── SKILL.md                          # 技能主文件（指令 + 可运行命令）\n├── README.md                         # 项目说明\n├── references/\n│   ├── step_by_step_setup.md     # 分步部署指南（7步图文教程）\n│   └── wecom_bot_api.md          # 企业微信机器人 API 参考\n├── templates/\n│   └── emotion_strategies.json   # 情感对话策略模板 v2.2（新增）\n└── scripts/\n    ├── detect_hardware.py        # 硬件检测脚本\n    ├── voice_simulator.py        # 语音消息模拟器\n    ├── session_manager.py        # 会话管理器（v2.2 扩展情感状态）\n    ├── wecom_webhook_server.py   # 智能机器人回调服务器 v2.2（集成情感分析）\n    ├── state_machine.py          # 多轮对话状态机 v2.0\n    ├── compliance.py             # 合规录音管理器 v2.0\n    ├── ivr_minutes.py            # 通话自动纪要 v2.0\n    ├── scheduler.py              # 外呼任务调度 v2.0\n    ├── stats.py                  # 通话记录看板 v2.0\n    ├── transcriber.py            # 录音全文转写 v2.0\n    └── emotion_analyzer.py       # 情感识别与自适应策略 v2.2（新增）\n```\n\n## 📋 支持的语音命令\n\n| 命令示例 | 功能 | 是否需要额外配置 |\n|---------|------|---------------|\n| \"北京今天天气怎么样？\" | ✅ 实时天气查询 | ❌ 不需要 |\n| \"现在几点？\" | ✅ 当前时间查询 | ❌ 不需要 |\n| \"明天有什么会议？\" | 🗓️ 日程查询 | ⚠️ 需管理员授权 |\n| \"提醒我下午3点提交报告\" | 📝 创建待办 | ⚠️ 需管理员授权 |\n| \"发消息给张三：明天开会\" | 📬 发送消息 | ⚠️ 需管理员授权 |\n| \"你能做什么？\" | 📖 获取帮助 | ❌ 不需要 |\n| \"退出语音模式\" | 🚪 切换到文字模式 | ❌ 不需要 |\n\n> 💡 **提示**：标注「⚠️ 需管理员授权」的功能，需要企业微信管理员在 work.weixin.qq.com 后台开启对应权限后才能真正执行。查询类功能（天气/时间）无需配置即可使用。\n\n## 📞 v2.0 通话功能\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 主动外呼 | 系统/用户发起 | 预约确认、快递提醒、服务回访 |\n| 来电接线 | 用户拨打企业绑定电话 | 自动语音交互（IVR 替代） |\n| 通话纪要 | 通话结束自动 | 提取决策点/待办项/时间点 |\n| 合规录音 | 用户同意后 | 本机存储，不上传第三方 |\n| 外呼调度 | 定时/批量 | CSV 导入客户列表 |\n| 通话看板 | `python stats.py` | 统计通话数据和趋势 |\n| 全文转写 | 通话结束后 | 输出 .txt + .docx |\n\n## ⚠️ 限制与边界\n\n- 仅支持企业微信智能机器人场景\n- 不支持主动外呼电话（v2.0 起支持，但需管理员授权）\n- 语音消息限 60 秒以内\n- 当前仅支持单聊（Phase 1）\n- 方言支持有限（普通话/粤语/英文）\n\n## 🔐 隐私声明\n\n- 本技能不存储、不上传、不转发用户的任何语音数据\n- 语音转写完全由企业微信官方接口完成\n- 所有文本数据仅保存在本地会话缓存中\n- 会话过期后自动清理\n- **v2.0 外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传**\n\n## 📜 版本历史\n\n- **v2.2.0** (2026-07-23) - 情感识别与自适应对话策略：5分类情感分析（愤怒/焦虑/满意/困惑/中性）、情绪升级跟踪、对话策略模板、硬件自适应\n- **v2.1.0** (2026-07-16) - 安全修复：自测代码移除恶意路径字符串，提升安全审计评分\n- **v2.0.0** (2026-07-15) - 重大升级：主动外呼、来电接线、通话纪要、合规录音、外呼调度、通话看板、全文转写\n- **v1.3.0** (2026-07-10) - webhook 服务器 v2.0：真正的天气查询（wttr.in）、当前时间查询、增强意图识别、--quick 一键体验\n- **v1.2.0** (2026-07-09) - 新增 webhook 回调服务器、分步部署指南\n- **v1.1.0** (2026-07-09) - 新增避坑指南、中文错误提示\n- **v1.0.0** (2026-07-08) - 初始版本\n\n## 📧 建议与反馈\n\n如有更好的建议或遇到问题，欢迎发送邮件至：\n\n**njskills@agent.qq.com**\n\n## 📜 许可证\n\nMIT License\n\n© 2026 njskills. 保留所有权利。\n\nFile v2.6.0:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"wecom-voice-agent\",\n  \"version\": \"2.6.0\",\n  \"publishedAt\": 1787574941274\n}\n\nFile v2.6.0:references/step_by_step_setup.md\n\n# 企业微信智能机器人 — 分步部署指南\n\n本教程带你**从零开始**搭建一个能接收语音消息的企业微信智能机器人。\n按照以下步骤操作，**不需要任何编程基础**。\n\n---\n\n## 第一步：前提条件\n\n确保你已具备：\n\n- [ ] 一台 Windows 电脑（已安装企业微信）\n- [ ] 注册一个企业微信账号\n- [ ] 安装 Python 3.8+\n\n检查 Python 安装：\n\n```bash\npython --version\n```\n\n---\n\n## 第二步：获取企业微信 CorpID 和 Secret\n\n### 2.1 获取 CorpID\n\n1. 打开 https://work.weixin.qq.com\n2. 登录你的企业微信管理后台\n3. 点击 **我的企业** → 下拉找到 **企业ID**\n4. 复制并保存这个 ID（例如：`ww1234567890abcdef`）\n\n### 2.2 创建自建应用\n\n1. 管理后台 → **应用管理** → **自建** → **创建应用**\n2. 填写应用名称（如\"语音助手\"），上传一个 logo\n3. 可见范围选择 **全部成员**\n4. 创建后进入该应用，记录以下信息：\n   - **AgentID**（应用 ID）\n   - **Secret**（应用密钥）\n\n---\n\n## 第三步：配置智能机器人回调\n\n1. 在应用详情页面找到 **智能机器人**\n2. 点击 **开启**，设置以下参数：\n\n```\n回调 Token: 任意字符串（如 my_wecom_voice_bot_2026）\nEncodingAESKey: 随机生成或自己填写一个 43 位字符串\n```\n\n3. **回调 URL**：先填写一个临时地址（如 `http://example.com/callback`），等服务器启动后再更新\n\n---\n\n## 第四步：启动本地服务器\n\n### 4.1 进入技能目录\n\n```bash\ncd D:\\skill\\wecom-voice-agent\n```\n\n### 4.2 启动 Webhook 服务器\n\n```bash\npython scripts/wecom_webhook_server.py --port 8080\n```\n\n看到以下输出说明启动成功：\n\n```\n============================================================\n企业微信语音消息回调服务器已启动\n监听地址: http://0.0.0.0:8080\n...\n============================================================\n```\n\n### 4.3 URL 验证\n\n企业微信会向你的回调 URL 发送 GET 请求验证。确保：\n- 你的服务器正在运行\n- URL 路径是 `/`（即服务器访问地址 + `/`）\n\n验证通过后，服务器日志会显示：\n\n```\nINFO: URL 验证请求已处理\n```\n\n---\n\n## 第五步：内网穿透（如果你的电脑没有公网 IP）\n\n大多数公司/家庭网络没有公网 IP，需要使用内网穿透工具暴露 8080 端口。\n\n### 使用 frp（推荐）\n\n```bash\n# 安装 frp 后\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 使用 ngrok（快速）\n\n```bash\nngrok http 8080\n```\n\n获得一个公网地址如 `https://abc123.ngrok-free.app`，将其作为回调 URL。\n\n---\n\n## 第六步：更新回调 URL\n\n回到企业微信管理后台 → 智能机器人 → 编辑回调 URL：\n\n```\nhttps://abc123.ngrok-free.app/\n```\n\n提交后企业微信会重新验证 URL，看到验证成功即可。\n\n---\n\n## 第七步：测试语音消息\n\n1. 打开企业微信客户端\n2. 搜索你刚刚创建的机器人应用（如\"语音助手\"）\n3. 发送一条语音消息：\"明天有什么会议？\"\n4. 机器人应该回复一个帮助信息的文字消息\n\n**成功！** 你的企业微信语音助手已经上线了。\n\n---\n\n## 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| 验证 URL 失败 | 检查服务器是否启动、端口是否正确、穿透工具是否运行 |\n| 收不到语音消息 | 确保回调 URL 正确、智能机器人已开启、消息类型支持语音 |\n| 中文乱码 | 服务器已使用 UTF-8 编码，检查终端编码设置 |\n| 被动回复超时 | 单次回复超过 5 秒会被企业微信丢弃，检查代码性能 |\n\n---\n\n## 高级配置\n\n### 配置 Token/AESKey 解密\n\n本技能默认部署。如需加密解密消息，请修改配置：\n\n```python\nWECHAT_CONFIG = {\n    \"token\": \"your_real_token\",\n    \"encoding_aes_key\": \"your_real_key\",\n    ...\n}\n```\n\n并安装加密包：\n\n```bash\npip install pycryptodome\n```\n\n### 扩展功能（接入企业微信 API）\n\n当你的技能需要回发消息、查询日历时，需要获取 access_token：\n\n```bash\ncurl -s -X POST \\\n  'https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ww1234567890abcdef&corpsecret=YOUR_SECRET' \\\n  | python -c \"import sys,json;d=json.load(sys.stdin);print(d['access_token'])\"\n```\n\n---\n\n## 下一步\n\n配置好服务器后，继续学习：\n- [企业微信机器人 API 参考](../../references/wecom_bot_api.md)\n- [意图解析器配置]（修改 `wecom_webhook_server.py` 中的 `intent_keywords` 字典）\n- [会话持久化]（将 `self.sessions` 替换为文件或数据库存储）\n\n如有问题，发送邮件至：**njskills@agent.qq.com**\n\nFile v2.6.0:references/wecom_bot_api.md\n\n# 企业微信智能机器人 API 参考\n\n本文档汇总了企业微信智能机器人与语音消息相关的 API 能力，供开发者快速查阅。\n\n---\n\n## 一、智能机器人概述\n\n当用户向智能机器人发送消息时，企业微信后台会向开发者配置的回调 URL 推送事件。开发者可以：\n\n1. 接收消息回调\n2. 被动回复消息（同步）\n3. 流式回复消息（同步更新内容）\n4. 主动发送消息（异步）\n\n**官方文档**：https://developer.work.weixin.qq.com/document/path/101039\n\n---\n\n## 二、语音消息回调\n\n当用户在单聊中向机器人发送语音消息时，回调格式如下：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转写后的文本内容\"\n    }\n}\n```\n\n**核心要点**：企业微信已内置语音转文字功能，回调中的 `voice.content` 字段直接包含转写文本。**开发者无需自行接入 ASR 服务**。\n\n---\n\n## 三、消息类型支持\n\n| 消息类型 | 接收 | 发送 | 说明 |\n|---------|------|------|------|\n| 文本消息 | ✅ | ✅ | 最常用 |\n| 图片消息 | ✅ | ✅ | 临时素材 |\n| 语音消息 | ✅ | ✅ | 接收时已转写为文字 |\n| 视频消息 | ✅ | ✅ | 最大 100MB |\n| 文件消息 | ✅ | ✅ | 最大 100MB |\n| 图文混排 | ✅ | ❌ | 仅接收，群聊或单聊 |\n| 模板卡片 | ❌ | ✅ | 富文本交互，被动回复 |\n\n---\n\n## 四、回复消息格式\n\n### 4.1 被动回复（文本）\n\n```json\n{\n    \"msgtype\": \"text\",\n    \"text\": {\n        \"content\": \"这是回复内容\"\n    }\n}\n```\n\n### 4.2 被动回复（语音）\n\n需要先上传语音素材获取 media_id：\n\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"media_id\": \"上传后获得的media_id\"\n    }\n}\n```\n\n### 4.3 流式回复\n\n适合长文本生成场景，通过 `response_url` 分批次推送：\n\n```json\n{\n    \"msgtype\": \"stream\",\n    \"stream\": {\n        \"id\": \"STREAM_ID\",\n        \"finish\": false,\n        \"content\": \"...\"\n    }\n}\n```\n\n---\n\n## 五、安全机制\n\n### 5.1 加密方式\n\n- 所有回调消息使用 AES-256-CBC 加密\n- IV 向量为 AESKey 前 16 字节\n- 数据采用 PKCS#7 填充\n\n### 5.2 权限要求\n\n- 需要配置回调 URL、Token、EncodingAESKey\n- 所有通信必须使用 HTTPS\n\n### 5.3 安全限制\n\n- 回调 URL 必须能处理 GET（验证）和 POST（回调）请求\n- 每次回调的 msgid 需用于去重\n- response_url 在消息接收后 48 小时内有效\n\n---\n\n## 六、频率限制\n\n| 操作 | 限制 | 说明 |\n|------|------|------|\n| 被动回复 | 不限制 | 推荐用于实时交互 |\n| API 调用 | 20次/分钟 | 主动调用企业微信 API |\n| 主动发送 | 20次/分钟 | 异步发送消息 |\n| 流式刷新 | 最长6分钟 | 用户发消息后 |\n| 并发交互 | 3条/用户 | 同一用户同时消息数 |\n\n---\n\n## 七、关键注意事项\n\n1. **语音转写由企业微信官方处理**，开发者无法控制 ASR 引擎选择\n2. **语音消息仅限单聊**（`chattype: single`），群聊暂不支持语音\n3. **response_url 有效期**：被动回复的 response_url 仅 48 小时内有效\n4. **临时素材有效期**：上传的媒体文件（语音、图片）3 天后失效，需重新上传\n5. **流式消息需主动结束**：发送 `finish: true` 结束流式消息\n\n---\n\n## 八、开发环境搭建\n\n### 8.1 配置智能机器人\n\n1. 登录企业微信管理后台\n2. 应用管理 → 创建应用 → 配置智能机器人\n3. 设置回调 URL/Token/EncodingAESKey\n4. 开通接收消息权限\n\n### 8.2 本地测试\n\n使用内网穿透工具暴露本地服务（如 frp）：\n\n```bash\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 8.3 验证回调\n\n企业微信发送 GET 请求验证 URL：\n\n```\nGET /callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx\n```\n\n返回解密后的 echostr 原文即可通过验证。\n\n---\n\n## 九、错误码参考\n\n| 错误码 | 含义 | 处理建议 |\n|-------|------|---------|\n| 0 | 成功 | - |\n| 40001 | 不合法的 secret | 检查应用凭证 |\n| 40003 | 不合法的 UserID | 检查用户身份 |\n| 40014 | 不合法的 access_token | 刷新 token |\n| 60020 | 网络连接异常 | 检查企业微信服务器网络 |\n| 84014 | 频率超限 | 降低发送频率，使用队列 |\n| 45009 | 接口调用超过限制 | 实现退避重试机制 |\n\n**完整错误码**：https://developer.work.weixin.qq.com/document/path/90313\n\nFile v2.6.0:skill-card.md\n\n## Description:\n\nWeCom Voice Agent helps an agent handle WeCom voice-message workflows, including intent recognition, multi-turn dialogue, task execution, outbound calling, call notes, compliant recording, call scheduling, declarative intents, custom intent plugins, unified session management, IVR menus, and entity extraction.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fyniujin](https://clawhub.ai/user/fyniujin)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nEmployees, support teams, and developers use this skill to build or operate a WeCom voice assistant that routes transcribed voice messages into intents, actions, IVR flows, call records, and user-facing replies. It is intended for enterprise WeCom bot scenarios that need local processing, configurable intents, and controlled handling of voice-call records.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Sensitive network, webhook, recording, and local retention behavior may be under-disclosed.\n\nMitigation: Review and reconcile the privacy and network disclosures before production use, including callback exposure, recording behavior, transcript storage, and retention periods.\n\nRisk: Webhook and custom API integrations can expose enterprise data or secrets if deployed without hardened controls.\n\nMitigation: Use verified WeCom callback authentication, restrict allowed custom API destinations, protect secrets, and avoid directly exposing a local webhook without enterprise access controls.\n\nRisk: Recordings, transcripts, sessions, tickets, and scheduled call data may persist locally beyond policy expectations.\n\nMitigation: Define and enforce retention, deletion, and access-control policies for all local voice, transcript, session, ticket, and scheduled-call data.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/fyniujin/skills/wecom-voice-agent)\n- [Step-by-step setup guide](references/step_by_step_setup.md)\n- [WeCom bot API reference](references/wecom_bot_api.md)\n- [WeCom smart bot documentation](https://developer.work.weixin.qq.com/document/path/101039)\n- [WeCom error code reference](https://developer.work.weixin.qq.com/document/path/90313)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with JSON, YAML, Python, and shell command examples.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce WeCom text or voice replies, structured intent data, call summaries, local session records, and configuration edits depending on the workflow.]\n\n## Skill Version(s):\n\n2.6.0 (source: frontmatter and server release evidence)\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 v2.6.0:temp_sessions/call_c1.json\n\n{\r\n  \"call_id\": \"c1\",\r\n  \"userid\": \"u1\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9368465,\r\n  \"last_activity\": 1784103261.9368498,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.6.0:temp_sessions/call_c2.json\n\n{\r\n  \"call_id\": \"c2\",\r\n  \"userid\": \"u2\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9375334,\r\n  \"last_activity\": 1784103261.9375362,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.6.0:temp_sessions/call_c3.json\n\n{\r\n  \"call_id\": \"c3\",\r\n  \"userid\": \"u3\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.0,\r\n  \"asr_text\": \"\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [],\r\n  \"start_time\": 1784103261.9383094,\r\n  \"last_activity\": 1784103261.9383125,\r\n  \"turn_count\": 0\r\n}\n\nFile v2.6.0:temp_sessions/call_e2e_001.json\n\n{\r\n  \"call_id\": \"e2e_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.92,\r\n  \"asr_text\": \"同意\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"本次通话可能被录音，请问您是否同意？\",\r\n      \"time\": \"2026-07-15T15:42:59.515560\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"同意\",\r\n      \"confidence\": 0.92,\r\n      \"time\": \"2026-07-15T15:42:59.516113\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.5148604,\r\n  \"last_activity\": 1784101379.5161114,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.6.0:temp_sessions/call_e2e_002.json\n\n{\r\n  \"call_id\": \"e2e_002\",\r\n  \"userid\": \"lisi\",\r\n  \"direction\": \"inbound\",\r\n  \"state\": \"speaking\",\r\n  \"confidence\": 0.65,\r\n  \"asr_text\": \"我要退订\",\r\n  \"pending_confirmation\": \"我要退订\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好请说\",\r\n      \"time\": \"2026-07-15T15:42:59.517207\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"我要退订\",\r\n      \"confidence\": 0.65,\r\n      \"time\": \"2026-07-15T15:42:59.517672\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784101379.51673,\r\n  \"last_activity\": 1784101379.5181956,\r\n  \"turn_count\": 1\r\n}\n\nFile v2.6.0:temp_sessions/call_test_001.json\n\n{\r\n  \"call_id\": \"test_001\",\r\n  \"userid\": \"zhangsan\",\r\n  \"direction\": \"outbound\",\r\n  \"state\": \"ending\",\r\n  \"confidence\": 0.95,\r\n  \"asr_text\": \"明天天气怎么样\",\r\n  \"pending_confirmation\": \"\",\r\n  \"history\": [\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"您好，我是语音助手\",\r\n      \"time\": \"2026-07-15T16:14:20.407762\"\r\n    },\r\n    {\r\n      \"role\": \"user\",\r\n      \"content\": \"明天天气怎么样\",\r\n      \"confidence\": 0.95,\r\n      \"time\": \"2026-07-15T16:14:20.408448\"\r\n    },\r\n    {\r\n      \"role\": \"agent\",\r\n      \"content\": \"明天北京晴，25度\",\r\n      \"time\": \"2026-07-15T16:14:20.409193\"\r\n    }\r\n  ],\r\n  \"start_time\": 1784103260.4062111,\r\n  \"last_activity\": 1784103260.4112015,\r\n  \"turn_count\": 2\r\n}\n\nArchive v2.5.1: 36 files, 145368 bytes\n\nFiles: README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/call_record_subsystem.py (33040b), scripts/compliance.py (29119b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/ivr_minutes.py (15155b), scripts/priority_queue.py (21479b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_channel.py (15865b), scripts/voice_simulator.py (6881b), scripts/voicemail_summary.py (15592b), scripts/wecom_webhook_server.py (63393b), skill-card.md (2703b), SKILL.md (37956b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nFile v2.5.1:SKILL.md\n\n---\nname: wecom-voice-agent\nversion: 2.5.1\ndescription: >\n---\n\n\n# 企业微信语音消息 Agent\n\n## ⚠️ 风险声明（必读）\n\n### 能力边界\n\n1. **本技能支持企业微信智能机器人场景**，包括被动语音消息处理和主动语音通话\n2. **语音转文字由企业微信官方提供**，本技能不自行采集或上传用户语音至任何第三方\n3. **不会读取或收集**用户的通讯录、聊天记录或其他个人隐私数据\n4. **所有数据处理均在本地完成**，通话记录（含 ASR 转写文本、元数据）持久化存储于本机 SQLite 数据库（`~/.wecom_voice/call_records.db`），录音文件存储于 `~/.wecom_voice/records/`，保留期限默认 90 天，到期自动清理\n5. **主动外呼需管理员授权**，且仅在用户明确同意录音后进行\n\n### 外部连接披露\n\n本技能仅在以下场景发起外部网络连接：\n\n| 目标主机 | 用途 | 触发条件 | 传输数据 |\n|---------|------|---------|---------|\n| `wttr.in` | 天气查询 API | 用户主动发起天气查询请求 | 城市名称（不含用户身份信息） |\n\n**除上述披露外，本技能不会向任何其他外部主机发起连接**。所有外部连接均为只读 GET 请求，不上传任何用户数据。\n\n### 安全风险项\n\n| 风险等级 | 风险描述 | 预防措施 |\n|---------|---------|---------| \n| 🔴 高 | 语音转写准确率受环境噪音影响 | 当置信度低时主动询问用户确认 |\n| 🔴 高 | 误触发（电视/背景音乐被误认为语音） | 设置消息有效时长阈值，超过30秒无新消息则重置上下文 |\n| 🔴 高 | 外呼过程中的隐私泄露风险 | 全程录音告知、用户同意后才录音 |\n| 🟡 中 | 企业微信 API 频率限制（每分钟20次） | 实现请求队列和速率限制器 |\n| 🟡 中 | 长上下文导致 Token 消耗过大 | 自动压缩历史消息，保留最近5轮对话 |\n| 🟢 低 | 语音回复合成超时并发 | 超时后自动降级为文字回复 |\n\n### 合规声明\n\n- 本技能遵守《个人信息保护法》《数据安全法》相关规定\n- 所有操作均基于用户主动发起的对话，不主动采集数据\n- 语音数据由企业微信官方处理，本技能不存储原始音频\n- 用户可随时通过发送文字消息退出语音模式\n- **外呼录音必须获得用户明确同意才进行**\n- **所有录音文件仅存储在本机 `~/.wecom_voice/records/`，永不外传**\n- **通话记录（含 ASR 转写文本、元数据）存储于本机 SQLite，不上传第三方**\n- **数据保留期限：录音文件 90 天，通话记录 180 天，到期自动清理**\n\n---\n\n## 🚀 快速开始\n\n### 方式一：一条命令安装并体验\n\n```bash\n# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n### 方式二：从零手动体验\n\n```bash\n# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats\n```\n\n> ✅ **无需安装任何 Python 包**，所有脚本仅使用 Python 标准库（`sys`、`os`、`json` 等）\n\n---\n\n## 🪤 避坑指南（新手必看）\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离手机/麦克风 20-30cm |\n| ❌ 一次说多句话（如\"查日程然后帮我订会议室\"） | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内，长内容请打字 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人**私聊**发语音 |\n| ❌ 发送方言（福建话、河南话等） | ✅ 支持**粤语、四川话、上海话、东北话、闽南话**，直接用方言对话即可，无需切换普通话 |\n| ❌ 说话时周围有电视/音乐 | ✅ 关掉背景音再说话，会被误认为指令 |\n| ❌ 以为能自动打电话/发短信 | ✅ v2.0 起支持外呼，但需管理员授权 |\n| ❌ 语音内容涉及密码/银行信息 | ✅ **切勿在语音中透露敏感信息**，所有文字均经过企业微信服务器 |\n\n---\n\n## 角色定义\n\n你是一名**企业微信语音智能助手**，专门处理企业微信生态内的语音交互场景。你的工作方式是：\n\n1. **被动响应**：只处理用户主动发送的语音消息，不主动拨打/发送（v2.0 起支持主动外呼）\n2. **意图理解**：将语音转写后的文本解析为结构化意图\n3. **任务执行**：调用相应的能力模块完成用户请求\n4. **通话管理**：支持主动外呼、来电接线、多轮对话、合规录音（v2.0 新增）\n5. **友好回复**：根据用户偏好返回文字或语音消息\n\n**你不是一个电话推销员，你是一个办公助手。**\n\n---\n\n## 核心指令\n\n### 一、消息接收阶段（系统自动触发）\n\n当企业微信回调收到 `msgtype: voice` 消息时：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转成文本的内容\"\n    }\n}\n```\n\n**关键步骤**：\n\n1. **提取文本内容**：从 `voice.content` 字段获取转写后的文本\n2. **验证消息有效性**：检查 `msgid` 是否重复（排重），检查消息时效性（超过5分钟则忽略）\n3. **上下文管理**：根据 `msgid` 查找或创建会话上下文\n\n### 二、意图解析阶段\n\n将用户语音文本分类为以下意图类型：\n\n| 意图类型 | 触发关键词 | 处理方式 |\n|---------|-----------|---------|\n| `query_schedule` | 日程、会议、安排、行程、下周、下周有什么 | 调用企业微信日程 skill |\n| `create_todo` | 提醒、待办、任务、别忘了、记得、设提醒 | 调用企业微信待办 skill |\n| `query_weather` | 天气、气温、下雨、温度、穿什么、热不冷 | 调用天气查询模块 |\n| `send_message` | 发消息、告诉、通知、转发、给XX发 | 调用企业微信消息 skill |\n| `help` | 帮助、能做什么、怎么用、功能、你可以做什么 | 返回帮助信息 |\n| `exit_voice` | 退出、不用了、谢谢、结束、再见、拜拜 | 切换到文字模式 |\n| `custom` | 无法识别的意图 | 尝试通用问答或请求澄清 |\n\n**增强版意图解析逻辑**：\n\n```\n步骤1: 精确匹配关键词 → 确定意图类型（多个关键词可叠加分数）\n步骤2: 提取时间/地点/人物等实体信息（支持\"下周\"、\"后天\"、\"明天上午9点\"）\n步骤3: 生成结构化 intent JSON（含置信度评分）\n步骤4: 置信度 > 0.3 → 调用对应处理模块；置信度 ≤ 0.3 → 主动询问用户想做什么\n```\n\n**提升识别准确率的提示**：\n\n当遇到以下模糊表达时，先确认而非猜测：\n\n| 用户说 | 不确定的点 | 确认方式 |\n|--------|----------|---------|\n| \"帮我安排一下\" | 是查日程还是建待办？ | \"您是想查看已有安排，还是需要创建新的提醒？\" |\n| \"下周开会\" | 是哪天？ | \"您是指下周一到周五的哪天呢？\" |\n| \"张三\" | 有多个同名吗？ | \"找到2位张三，请确认是哪个部门的\" |\n| \"明天上午\" | 几点？ | \"好的，明天上午几点呢？\" |\n| \"发给他\" | 发给谁？上下文没有人物 | \"请问要发给谁？\" |\n\n### 三、任务执行阶段\n\n#### 3.1 日程查询 (`query_schedule`)\n\n**输入格式**：\n```json\n{\n    \"intent\": \"query_schedule\",\n    \"entities\": {\n        \"time\": \"明天\",\n        \"date\": \"2024-01-15\",\n        \"person\": \"张三\"\n    }\n}\n```\n\n**执行步骤**：\n1. 解析时间实体（今天/明天/后天/下周三、下周一、下周等）\n2. 调用企业微信日程 API 查询指定日期安排\n3. 整理日程信息（时间-事项-地点）\n4. 格式化为自然语言回复\n\n**输出示例**：\n```\n您明天（1月15日）的日程安排：\n📅 09:00-10:00 周会 - 会议室A\n📅 14:00-15:00 与张三讨论项目 - 线上会议\n📅 16:30-17:00 代码评审 - 开发区\n共 3 项安排。需要我设置提醒吗？\n```\n\n#### 3.2 待办创建 (`create_todo`)\n\n**执行步骤**：\n1. 解析待办内容、截止时间、提醒时间\n2. 调用企业微信待办 API 创建任务\n3. 返回创建结果\n\n#### 3.3 天气查询 (`query_weather`)\n\n**执行步骤**：\n1. 解析地点实体（默认用户所在城市）\n2. 调用天气查询服务（wttr.in 免费 API）\n3. 整理天气信息并语音播报\n\n#### 3.4 消息发送 (`send_message`)\n\n**执行步骤**：\n1. 解析接收人、消息内容\n2. **确认发送意图**（防止误触，发送前让用户确认）\n3. 调用企业微信消息 API 发送\n\n### 四、v2.0 新增：主动通话管理\n\n#### 4.1 主动外呼\n\n**触发条件**：用户/系统发起外呼任务\n\n**执行流程**：\n1. 获取被叫方信息（手机号或用户ID）\n2. 调用企业微信「语音通话」API 发起呼叫\n3. 接通后播放录音告知（\"本次通话可能被录音\"）\n4. 用户同意 → 开始正式通话 + 录音\n5. 用户拒绝 → 继续通话但不录音\n6. 通话结束 → 自动生成纪要 + 保存录音 + 发送纪要\n\n#### 4.2 来电自动接线（IVR 替代）\n\n**触发条件**：用户拨打企业绑定电话\n\n**执行流程**：\n1. 企微电话接通回调触发\n2. Agent 播放欢迎语 + 录音告知\n3. 等待用户语音输入（ASR 转写）\n4. 意图识别 → 执行对应任务\n5. 多轮对话状态机管理交互\n6. 30 秒无新语音自动结束通话\n\n#### 4.3 通话后自动纪要\n\n**触发条件**：通话结束\n\n**执行流程**：\n1. 从 ASR 文字流提取「决策点」「待办项」「时间点」\n2. 输出结构化纪要（markdown 格式）\n3. 通过企微消息 API 发送给呼叫方\n\n#### 4.4 多轮语音对话状态机\n\n**状态定义**：\n- `IDLE` → 空闲/未开始\n- `DIALING` → 拨号中\n- `SPEAKING` → Agent 说话中（TTS 播报）\n- `LISTENING` → 等待用户语音输入\n- `CONFIRMING` → 二次确认中（ASR 置信度低）\n- `ENDING` → 通话结束中\n\n**超时机制**：30 秒无新语音自动结束通话\n\n#### 4.5 合规录音告知 + 本地存储\n\n**执行流程**：\n1. 通话开始时播放「本次通话可能被录音，用于服务品质监控。请问您是否同意？」\n2. 用户回应「同意」→ 开始录音\n3. 录音文件存储到本机 `~/.wecom_voice/records/YYYY-MM-DD/`\n4. 录音记录存本地 SQLite\n5. **不上传任何第三方**\n\n#### 4.6 外呼任务调度\n\n**功能**：\n- 定时外呼（每天9点提醒）\n- 批量外呼（CSV/JSON 导入客户列表）\n\n**实现方式**：\n- 使用 `sched` + `threading` 实现定时调度\n- CSV/JSON 批量导入客户列表\n- 并发控制（默认最大 3 路并发）\n\n### 五、回复生成阶段\n\n#### 5.1 文字回复\n\n当用户发送的语音消息内容较简单，或用户明确表示\"用文字回复我\"时：\n\n```\n回复格式要求：\n- 简洁明了，每段不超过3行\n- 使用 emoji 增强可读性\n- 包含下一步操作建议\n```\n\n#### 5.2 语音回复\n\n当用户明确表示\"用语音告诉我\"，或回复内容较长（超过100字）时：\n\n**语音合成流程**：\n1. 调用本地 TTS 引擎生成语音文件\n2. 上传至企业微信获取 media_id\n3. 通过 response_url 发送语音消息\n\n**TTS 引擎选择优先级**：\n```\n优先级1: Edge TTS（免费，无需 API Key，中文效果良好）\n优先级2: 火山引擎 TTS（音色更自然，需配置 API Key）\n```\n\n### 六、多轮对话管理\n\n> ⚠️ **重要说明**：v2.0 起提供**完整的通话状态机**（`state_machine.py`），\n> 支持多轮语音对话的上下文管理和超时自动结束。\n\n**上下文保持规则**：\n- 同一用户（同一 `msgid` 前缀）连续消息视为一轮对话\n- 单轮对话最多保留 **5 条消息**（3条用户 + 2条助手）\n- 超过5条后自动压缩：保留第一条用户消息 + 最近2条消息\n- **对话超时**：用户连续 30 秒（通话模式）/ 60 秒（文字模式）无新消息则自动结束上下文\n\n**上下文数据结构**：\n```json\n{\n    \"session_id\": \"userid_timestamp\",\n    \"messages\": [...],\n    \"current_intent\": \"query_schedule\",\n    \"collected_entities\": {\"time\": \"明天\"},\n    \"awaiting\": \"date\",\n    \"created_at\": 1705286400\n}\n```\n\n---\n\n## 硬件自适应优化\n\n### 自动检测与分级\n\n本技能启动时自动检测用户计算机系统资源，并根据结果调整并发和缓存策略：\n\n| 硬件等级 | RAM 范围 | CPU 核心数 | 并发处理能力 | 上下文缓存 |\n|---------|---------|-----------|------------|-----------|\n| 🟢 高配 | ≥ 16GB | ≥ 8核 | 同时处理 5 路会话 | 保留 100 轮历史 |\n| 🟡 中配 | 8-16GB | 4-8核 | 同时处理 3 路会话 | 保留 20 轮历史 |\n| 🔴 低配 | < 8GB | < 4核 | 同时处理 1 路会话 | 保留 5 轮历史 |\n\n**检测方式**：\n- WorkBuddy 环境：读取系统信息和 Node.js `os` 模块\n- 独立脚本：使用 Windows API (`GlobalMemoryStatusEx`) 获取真实硬件参数\n\n### 性能保障措施\n\n1. **懒加载机制**：非核心模块在首次使用时才加载\n2. **资源回收**：对话结束后立即释放占用的内存和临时文件\n3. **超时保护**：语音转写受网络影响，超时后自动提示用户重试\n4. **日志限制**：本地日志文件最大 100KB，自动轮转覆盖\n\n---\n\n## 更新通知机制\n\n### 版本检查\n\n本技能在每次执行时（频率限制为每6小时一次）执行以下检查：\n\n1. 本地安装版本号 vs 云端最新版本号\n2. 如有新版本，向用户发送更新提醒消息\n\n**提醒格式**：\n```\n🎉 发现新版本：v2.0.0\n主要改进：\n- 新增主动外呼、来电接线、通话纪要\n- 新增合规录音告知、外呼任务调度\n- 新增通话记录看板、全文转写\n\n请运行以下命令更新：\nskillhub install wecom-voice-agent --force\n```\n\n### 自动更新（可选）\n\n用户可通过发送\"检查更新\"触发版本检查，或通过以下命令手动更新：\n\n```bash\nskillhub install wecom-voice-agent --force\n```\n\n---\n\n## 示例场景\n\n### 场景1：语音查日程\n\n**用户（语音）**：明天有什么会议？\n\n**企业微信回调**：\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\"content\": \"明天有什么会议\"}\n}\n```\n\n**助手回复**：\n```\n您明天（7月9日）的日程安排：\n\n📅 09:00-10:00 产品周会 - 大会议室\n📅 14:00-15:30 客户拜访 - 上海浦东\n📅 16:00-17:00 团队代码评审\n\n共 3 项。需要我设置提前30分钟提醒吗？\n```\n\n### 场景2：语音建待办\n\n**用户（语音）**：提醒我下午3点提交报告\n\n**助手回复**：\n```\n✅ 已创建待办提醒：\n⏰ 时间：今天下午3:00\n📝 内容：提交报告\n\n需要我同时在团队群里发一条提醒吗？\n```\n\n### 场景3：连续对话\n\n**用户（语音）**：今天天气怎么样？\n**助手回复**：\n```\n北京今日天气：\n🌤️ 多云  28°C ~ 35°C\n💡 建议：带伞，可能有阵雨\n🌬️ 东南风 3级\n```\n\n**用户（语音）（追问）**：**那明天呢？**\n\n**助手回复**（利用上下文，知道地点仍然是北京）：\n```\n北京明天天气：\n🌧️ 小雨  24°C ~ 30°C\n💡 建议：带伞，穿薄外套\n\n看起来明天要下雨，需要我帮您调整明天的外出安排吗？\n```\n\n### 场景4：模糊表达处理\n\n**用户（语音）**：帮我安排一下\n\n**助手回复**（主动确认，不猜测）：\n\n```\n我可以帮您：\n1️⃣ 查看日程安排（您想查哪天？）\n2️⃣ 创建待办提醒（提醒什么内容？）\n3️⃣ 查询天气（哪个城市？）\n\n请告诉我您想做什么。\n```\n\n### 场景5：误触发处理\n\n**用户（语音）**：（环境噪音 / 电视声音）\n\n**助手回复**：\n```\n抱歉，我没有听清楚您的语音内容 😅\n\n请用清晰的语音告诉我您需要什么帮助，例如：\n• \"查一下明天的日程\"\n• \"提醒我下午开会\"\n• \"发消息给张三\"\n```\n\n### 场景6：v2.0 主动外呼\n\n**系统**：发起外呼任务 → 拨打 13800138000\n\n**Agent**（接通后）：\n```\n您好，我是XX公司的语音助手。本次通话可能被录音，用于服务品质监控。请问您是否同意？\n```\n\n**用户**：同意\n\n**Agent**：\n```\n好的，感谢您的确认。我们想确认一下，您明天下午3点的会议安排是否有变化？\n```\n\n**用户**：没有变化，按时参加\n\n**Agent**：\n```\n好的，已为您确认。通话结束后我们会发送纪要至您的企业微信。祝您愉快！\n```\n\n### 场景7：v2.0 来电接线\n\n**用户**：拨打企业绑定电话\n\n**Agent**：\n```\n您好，欢迎致电XX公司。我是智能语音助手，请问您需要什么帮助？\n```\n\n**用户**：我要退订\n\n**Agent**（二次确认，ASR 置信度 0.7 < 0.85）：\n```\n抱歉，我没有完全听清。您说的是「我要退订」吗？请确认「是」或「不是」。\n```\n\n**用户**：是\n\n**Agent**：\n```\n好的，已为您提交退订申请。受理编号：TK20260715001。我们会在3个工作日内处理。还有其他需要帮助的吗？\n```\n\n---\n\n## 错误处理\n\n### 常见错误与处理方式\n\n| 错误类型 | 触发条件 | 友好提示 |\n|---------|---------|---------| \n| 语音转写失败 | `voice.content` 为空或乱码 | \"抱歉，您的语音没有识别成功，请重新发送或尝试用普通话慢慢说。\" |\n| API 调用失败 | HTTP 4xx/5xx 错误码 | \"当前网络繁忙，请稍后再试。如您连续遇到问题，可尝试重启企业微信应用。\" |\n| 意图识别失败 | 关键词匹配度 < 0.3 | 主动询问用户意图，提供选项菜单（见\"模糊表达处理\"场景） |\n| TTS 合成失败 | 语音文件生成超过5秒 | 改为文字回复，附加提示：\"语音播报暂时不可用，已为您用文字显示。\" |\n| 上下文过期 | 对话间隔 > 60秒 | 自动开始新对话，回复：\"检测到新会话，请问有什么可以帮您的？\" |\n| 找不到会话 | 查询不存在的 session_id | \"会话不存在或已过期，请重新发送语音指令。\" |\n| 硬件检测失败 | Windows API 或 WMI 均不可用 | \"无法检测硬件配置，已自动使用'低配'模式保障运行。\" |\n| 外呼失败 | 被叫方无应答/占线 | \"暂时无法接通，请稍后重试或留下口信。\" |\n| 录音失败 | 本地存储空间不足 | \"存储空间不足，已自动清理旧录音。请重试。\" |\n\n### 异常退出策略\n\n当发生严重错误时：\n\n1. **用中文向用户道歉**并简要说明原因（不要暴露技术术语如 \"Traceback\"、\"HTTP 500\"）\n2. **记录错误信息**到本地日志 `D:/skill/wecom-voice-agent/temp_sessions/error.log`\n3. **清理临时文件**（音频文件、缓存数据）\n4. **恢复初始状态**，等待下一条用户消息\n5. **连续失败3次**时主动提示用户：\"检测到连续操作失败，请检查网络连接或稍后重试。\"\n\n**错误提示原则**：\n- ❌ \"Error: connection refused\"（技术术语）\n- ✅ \"无法连接到服务，请检查您的网络后重试。\"（用户语言）\n- ❌ \"Traceback (most recent call last)...\"（堆栈信息）\n- ✅ \"系统遇到了临时问题，已自动恢复，请重新发送指令。\"（友好提示）\n\n---\n\n## FAQ\n\n### Q1：这个技能需要额外的 API Key 吗？\n**A**：不需要核心 API Key。企业微信内置的语音转文字功能免费使用。\n如果您希望使用更优质的语音合成（火山引擎 TTS），可选配置 API Key，但 Edge TTS 完全免费且开箱即用。\n\n### Q2：支持哪些方言或语言？\n**A**：v2.3.0 起内置**方言检测引擎**，自动识别粤语、四川话、上海话、东北话、闽南话 5 大方言，并使用对应的方言风格回复。无需切换普通话，直接说方言即可。\n\n### Q3：语音消息长度有限制吗？\n**A**：企业微信智能机器人接收的语音消息通常限制在 60 秒以内。\n如需处理更长的录音，请使用企业微信的「文件上传」功能，后续版本将支持长语音转写。\n\n### Q4：隐私安全吗？我的语音数据会被上传吗？\n**A**：**绝对不会**。本技能不存储、不上传、不转发用户的任何语音数据。\n语音转写完全由企业微信官方接口完成，本技能仅接收转写后的文本内容。\nv2.0 起外呼录音存储在本机 `~/.wecom_voice/records/`，永不外传。\n\n### Q5：支持群聊吗？\n**A**：当前仅支持单聊（`chattype: single`），以确保语音转写准确率和隐私安全。\n群聊支持将在后续版本中评估后决定。\n\n### Q6：能在手机上使用吗？\n**A**：可以。只要您的 WorkBuddy 客户端运行并连接到企业微信，手机端和 PC 端均可使用。\n\n### Q7：并发能力如何？\n**A**：单用户模式下，本技能可同时处理多个企业微信用户的语音请求，\n具体并发数根据您的电脑硬件自动调整（1-5路并发）。\n外呼任务并发默认最大值 3 路（可在 `scheduler.py` 中调整）。\n\n### Q8：如何卸载或停止？\n**A**：发送文字消息\"退出语音模式\"即可停止语音助手。\n如需完全卸载，请运行：`skillhub uninstall wecom-voice-agent`\n\n### Q9：为什么有时候听不懂我说的话？\n**A**：语音转写准确率受以下因素影响：\n- 环境噪音（电视、空调、外部人声）\n- 说话方言或口音较重\n- 语音消息超过 60 秒\n- 一次发送多步指令（如\"查日程然后订会议室\"）\n\n**建议**：一次只说一件事，用普通话在安静环境发送，控制在 60 秒以内。\n\n### Q10：v2.0 外呼功能合规吗？\n**A**：完全合规。外呼功能遵守以下原则：\n- **录音告知**：通话开始时明确告知用户\"本次通话可能被录音\"\n- **用户同意**：必须用户明确同意后才开始录音\n- **本地存储**：录音文件仅存储在本机 `~/.wecom_voice/records/`，不上传第三方\n- **随时退出**：用户可在通话中随时要求终止录音\n\n### Q11：遇到错误了屏幕上显示英文？\n**A**：本技能已将所有错误提示改为中文。如果您仍看到英文：\n1. 可能是企业微信官方 API 返回的英文错误\n2. 请将错误截图发送至 **njskills@agent.qq.com**，我们会处理\n\n---\n\n## 脚本与使用指南\n\n本技能包含辅助脚本用于本地测试和调试。更多背景知识请参见 `references/wecom_bot_api.md`。\n\n### 本地测试脚本\n\n#### scripts/detect_hardware.py\n\n自动检测用户计算机硬件资源，输出硬件等级配置。\n\n```bash\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n```\n\n**输出示例**：\n```json\n{\n    \"level\": \"medium\",\n    \"ram_gb\": 16.0,\n    \"cpu_cores\": 6,\n    \"concurrency\": 3,\n    \"cache_limit\": 20,\n    \"description\": \"中配 - 支持3路并发，20轮历史缓存\",\n    \"platform\": \"win32\"\n}\n```\n\n#### scripts/voice_simulator.py\n\n模拟企业微信语音消息回调，用于本地调试意图解析逻辑。\n\n```bash\n# 基础用法\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 指定用户\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京天气\" --userid zhangsan\n\n# JSON 格式输出\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"提醒我开会\" --format json\n```\n\n#### scripts/session_manager.py\n\n管理对话上下文，支持创建、查询、清理会话。\n\n```bash\n# 创建新会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\n\n# 查询会话状态（表格格式）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py get --session_id xxx --format table\n\n# 查找用户活跃会话\npython D:/skill/wecom-voice-agent/scripts/session_manager.py find --userid zhangsan\n\n# 向会话添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py add --session_id xxx --role user --content \"你好\"\n\n# 清理过期会话（默认120秒）\npython D:/skill/wecom-voice-agent/scripts/session_manager.py cleanup --timeout 180\n\n# 查看所有会话统计\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n#### scripts/wecom_webhook_server.py\n\n企业微信智能机器人回调服务器。接收企业微信推送的消息回调，自动处理语音消息。\n\n```bash\n# 一键体验所有功能（无需启动服务）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --quick\n\n# 启动服务器（默认端口 8080）\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py\n\n# 指定端口\npython D:/skill/wecom-voice-agent/scripts/wecom_webhook_server.py --port 9000\n```\n\n**v2.0 核心升级**：\n- ✅ **真正的天气查询**：调用 wttr.in 免费 API（无需 key），中文描述 + 穿衣建议\n- ✅ **当前时间查询**：本地计算，100%可用，无需任何网络依赖\n- ✅ **意图识别增强**：关键词 + 正则混合匹分，置信度评分\n- ✅ **多轮对话**：根据 `msgid` 去重，会话缓存管理\n- ✅ **中文错误提示**：全部错误给出具体解决步骤\n\n**部署步骤**：\n1. 启动服务器：`python scripts/wecom_webhook_server.py --port 8080`\n2. 使用内网穿透暴露 8080 端口（frp/ngrok）\n3. 将穿透后的 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n4. 发送语音消息测试\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_s\n\nArchive v2.5.0: 36 files, 145092 bytes\n\nFiles: README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/call_record_subsystem.py (33040b), scripts/compliance.py (30024b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/ivr_minutes.py (15155b), scripts/priority_queue.py (21479b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_channel.py (15865b), scripts/voice_simulator.py (6881b), scripts/voicemail_summary.py (15592b), scripts/wecom_webhook_server.py (63393b), skill-card.md (2942b), SKILL.md (36452b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nArchive v2.4.0: 33 files, 125732 bytes\n\nFiles: README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/compliance.py (30024b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/ivr_minutes.py (15155b), scripts/priority_queue.py (21479b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/transcriber.py (16479b), scripts/vad_filter.py (17047b), scripts/voice_simulator.py (6881b), scripts/wecom_webhook_server.py (59502b), skill-card.md (2756b), SKILL.md (33632b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nArchive v2.3.0: 31 files, 110362 bytes\n\nFiles: README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/compliance.py (18740b), scripts/detect_hardware.py (4899b), scripts/dialect_detector.py (19842b), scripts/emotion_analyzer.py (26333b), scripts/ivr_minutes.py (15155b), scripts/scheduler.py (21398b), scripts/session_manager.py (15234b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/ticket_manager.py (37306b), scripts/transcriber.py (16479b), scripts/voice_simulator.py (6881b), scripts/wecom_webhook_server.py (51159b), skill-card.md (3107b), SKILL.md (32979b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/dialect_strategies.json (10677b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nArchive v2.2.0: 28 files, 90792 bytes\n\nFiles: README.md (6700b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/compliance.py (18740b), scripts/detect_hardware.py (4899b), scripts/emotion_analyzer.py (26333b), scripts/ivr_minutes.py (15155b), scripts/scheduler.py (21398b), scripts/session_manager.py (12517b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/transcriber.py (16479b), scripts/voice_simulator.py (6881b), scripts/wecom_webhook_server.py (42824b), skill-card.md (3040b), SKILL.md (32298b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), temp_sessions/d485f0fcb3f6d69a.json (1148b), templates/emotion_strategies.json (5934b), _meta.json (136b)\n\nArchive v2.1.0: 25 files, 77893 bytes\n\nFiles: README.md (6263b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/compliance.py (18740b), scripts/detect_hardware.py (4899b), scripts/ivr_minutes.py (15155b), scripts/scheduler.py (21398b), scripts/session_manager.py (10166b), scripts/state_machine.py (17289b), scripts/stats.py (17164b), scripts/transcriber.py (16479b), scripts/voice_simulator.py (6881b), scripts/wecom_webhook_server.py (35626b), skill-card.md (2945b), SKILL.md (31840b), temp_sessions/call_c1.json (281b), temp_sessions/call_c2.json (281b), temp_sessions/call_c3.json (281b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), temp_sessions/call_test_001.json (728b), temp_sessions/call_test_002.json (577b), temp_sessions/call_test_003.json (289b), temp_sessions/call_test_005.json (559b), _meta.json (136b)\n\nArchive v2.0.0: 18 files, 76036 bytes\n\nFiles: README.md (6225b), references/step_by_step_setup.md (4604b), references/wecom_bot_api.md (4576b), scripts/compliance.py (18654b), scripts/detect_hardware.py (4899b), scripts/ivr_minutes.py (15155b), scripts/scheduler.py (21398b), scripts/session_manager.py (10166b), scripts/state_machine.py (17294b), scripts/stats.py (17164b), scripts/transcriber.py (16486b), scripts/voice_simulator.py (6881b), scripts/wecom_webhook_server.py (35626b), skill-card.md (3569b), SKILL.md (34508b), temp_sessions/call_e2e_001.json (598b), temp_sessions/call_e2e_002.json (573b), _meta.json (136b)","readmeExcerpt":"Skill: wecom-voice-agent Owner: fyniujin Summary: 企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会... Tags: latest:2.8.0 Version history: v2.8.0 | 2026-09-20T15:52:21.374Z | auto **v2.8.0 introduces voice TTS multi-voice, voice clone, summary QA, and ops reporting tools.** - Added config/voices.yaml: Predefine","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats"},{"language":"bash","snippet":"# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats"},{"language":"bash","snippet":"cd D:/skill/wecom-voice-agent\n\n# 查看全部可用音色（3 套预设，来自 config/voices.yaml）\npython scripts/voice_policy.py list\n\n# 按场景+情感预览合成参数与 SSML（不发起合成）\npython scripts/voice_policy.py synth --scene outbound --emotion angry --confidence 0.9 --text \"您好，通知您明天下午3点参加评审。\" --ssml\n\n# 查看语音克隆模块状态（未配置 CLONE_PROVIDER/CLONE_API_KEY 时完全隐藏）\npython scripts/voice_clone.py status\n\n# 评审一段通话摘要（三要素评分，≥80 分达标）\npython scripts/summary_qa.py review --text \"会议决定：下周三18点前由张三负责提交修订方案。\" --id call_001\n\n# 查看最近 7 天运营摘要 / 生成上周 HTML 周报\npython scripts/report_generator.py summary --period week\npython scripts/report_generator.py weekly"},{"language":"text","snippet":"wecom-voice-agent/\n├── SKILL.md                  # 本文件（使用说明 + 风险 + 边界 + FAQ + 反模式）\n├── config/\n│   ├── intents.yaml          # v2.6 声明式意图注册表（20+ 意图）\n│   ├── custom_intents.yaml   # v2.6 自定义意图插件配置（企业 API 映射）\n│   ├── menu.yaml             # v2.6 IVR 多级菜单配置\n│   └── voices.yaml           # v2.8 TTS 音色库（3 套预设+情感调整+SSML+双链路）\n├── references/\n│   ├── wecom_bot_api.md      # 企业微信机器人 API 参考\n│   └── step_by_step_setup.md # 分步部署指南\n├── scripts/\n│   ├── wecom_webhook_server.py # 主服务（回调接收+意图路由+任务执行）\n│   ├── intent_registry.py    # v2.6 声明式意图引擎（YAML 配置+多级澄清）\n│   ├── custom_intent_plugin.py # v2.6 自定义意图插件（企业自有 API 声明式映射）\n│   ├── session_unified.py    # v2.6 统一会话管理（双向子系统，合并原 scheduler+session_manager）\n│   ├── ivr_engine.py         # v2.6 多级 IVR 菜单引擎（YAML 配置+数字/名称双选）\n│   ├── entity_extractor.py   # v2.6 实体抽取增强（规则+消歧+复述确认）\n│   ├── memory_bridge.py     # v2.7 zwjh 长期记忆桥接（MCP stdio JSON-RPC）\n│   ├── todo_followup.py     # v2.7 跟进待办闭环（纪要→回拨→到期→二次外呼）\n│   ├── emotion_ticket_bridge.py # v2.7 情感到工单直连（强负面→建单+升级+通知）\n│   ├── voice_policy.py      # v2.8 TTS 多音色与情感（voices.yaml+SSML+双链路降级）\n│   ├── voice_clone.py       # v2.8 语音克隆外呼（授权留痕+合规红线+未配置完全隐藏）\n│   ├── summary_qa.py        # v2.8 通话摘要质检（三要素评分+5%人工抽检+纠错回流）\n│   ├── report_generator.py  # v2.8 运营报表（接通率/漏斗/意图分布+周一HTML周报）\n│   ├── voice_simulator.py    # 语音消息模拟器（本地调试）\n│   ├── detect_hardware.py    # 硬件检测\n│   ├── state_machine.py      # 多轮对话状态机\n│   ├── call_record_subsystem.py # v2.5 通话记录子系统（合并4脚本）\n│   ├── voice_channel.py      # v2.5 多渠道抽象层\n│   ├── voicemail_summary.py  # v2.5 语音留言摘要\n│   ├── dialect_detector.py   # v2.3 方言检测\n│   ├── ticket_manager.py     # v2.3 工单管理\n│   ├── emotion_analyzer.py   # v2.2 情感识别\n│   ├── vad_filter.py         # v2.4 VAD 语音活动检测\n│   ├── priority_queue.py     # v2.4 四级优先级队列\n│   ├── compliance.py         # v2.4 合规录音（v3.0 强制告知）\n│   ├── scheduler.py          # v2.0 外呼调度（已合并至 session_unified）\n│   ├── session_manager.py    # v2.0 会话管理（已合并至 session_unified）\n│   ├── ivr_minutes.py        # v2.0 通话纪要（已合并至 call_record_subsystem）\n│  "},{"language":"json","snippet":"{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转成文本的内容\"\n    }\n}"},{"language":"text","snippet":"步骤1: 精确匹配关键词 → 确定意图类型（多个关键词可叠加分数）\n步骤2: 提取时间/地点/人物等实体信息（支持\"下周\"、\"后天\"、\"明天上午9点\"）\n步骤3: 生成结构化 intent JSON（含置信度评分）\n步骤4: 置信度 > 0.3 → 调用对应处理模块；置信度 ≤ 0.3 → 主动询问用户想做什么"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: wecom-voice-agent\nversion: 2.8.0\ndescription: >\n---\n\n\n# 企业微信语音消息 Agent\n\n## ⚠️ 风险声明（必读）\n\n### 能力边界\n\n1. **本技能支持企业微信智能机器人场景**，包括被动语音消息处理和主动语音通话\n2. **语音转文字由企业微信官方提供**，本技能不自行采集或上传用户语音至任何第三方\n3. **不会读取或收集**用户的通讯录、聊天记录或其他个人隐私数据\n4. **所有数据处理均在本地完成**，通话记录（含 ASR 转写文本、元数据）持久化存储于本机 SQLite 数据库（`~/.wecom_voice/call_records.db`），录音文件存储于 `~/.wecom_voice/records/`，保留期限默认 90 天，到期自动清理\n5. **主动外呼需管理员授权**，且仅在用户明确同意录音后进行\n\n### 外部连接披露\n\n本技能仅在以下场景发起外部网络连接：\n\n| 目标主机 | 用途 | 触发条件 | 传输数据 |\n|---------|------|---------|---------|\n| `wttr.in` | 天气查询 API | 用户主动发起天气查询请求 | 城市名称（不含用户身份信息） |\n| `openspeech.bytedance.com` | 火山引擎 TTS 语音合成（备用链路） | 仅当配置 `VOLC_TTS_KEY` 且 Edge TTS 主链路不可用 | 待合成文本（通话播报内容） |\n| `api.coze.cn` / `api.minimax.chat` | 语音克隆 API（豆包 / MiniMax） | 仅当配置 `CLONE_PROVIDER` + `CLONE_API_KEY` 主动创建克隆音色 | 音色名称与授权信息（不含通话内容） |\n\n**除上述披露外，本技能不会向任何其他外部主机发起连接**。天气查询为只读 GET 请求；火山 TTS 与语音克隆均为可选增强能力，**未配置对应 Key 时静默跳过、绝不发起连接**，全部功能降级可用。所有外部连接均不上传用户身份信息。\n\n### 安全风险项\n\n| 风险等级 | 风险描述 | 预防措施 |\n|---------|---------|---------| \n| 🔴 高 | 语音转写准确率受环境噪音影响 | 当置信度低时主动询问用户确认 |\n| 🔴 高 | 误触发（电视/背景音乐被误认为语音） | 设置消息有效时长阈值，超过30秒无新消息则重置上下文 |\n| 🔴 高 | 外呼过程中的隐私泄露风险 | 全程录音告知、用户同意后才录音 |\n| 🟡 中 | 企业微信 API 频率限制（每分钟20次） | 实现请求队列和速率限制器 |\n| 🟡 中 | 长上下文导致 Token 消耗过大 | 自动压缩历史消息，保留最近5轮对话 |\n| 🟢 低 | 语音回复合成超时并发 | 超时后自动降级为文字回复 |\n\n### 合规声明\n\n- 本技能遵守《个人信息保护法》《数据安全法》相关规定\n- 所有操作均基于用户主动发起的对话，不主动采集数据\n- 语音数据由企业微信官方处理，本技能不存储原始音频\n- 用户可随时通过发送文字消息退出语音模式\n- **外呼录音必须获得用户明确同意才进行**\n- **所有录音文件仅存储在本机 `~/.wecom_voice/records/`，永不外传**\n- **通话记录（含 ASR 转写文本、元数据）存储于本机 SQLite，不上传第三方**\n- **数据保留期限：录音文件 90 天，通话记录 180 天，到期自动清理**\n\n---\n\n## 🚀 快速开始\n\n### 方式一：一条命令安装并体验\n\n```bash\n# 安装技能（如果已安装则跳过此步）\nskillhub install wecom-voice-agent\n\n# 第一步：检测你的电脑配置\npython D:/skill/wecom-voice-agent/scripts/detect_hardware.py\n\n# 第二步：模拟语音消息测试\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"明天有什么会议\"\n\n# 第三步：试试天气查询\npython D:/skill/wecom-voice-agent/scripts/voice_simulator.py --text \"北京今天天气怎么样\"\n\n# 第四步：创建会话并添加消息\npython D:/skill/wecom-voice-agent/scripts/session_manager.py create --userid zhangsan\npython D:/skill/wecom-voice-agent/scripts/session_manager.py stats\n```\n\n### 方式二：从零手动体验\n\n```bash\n# 克隆技能目录\ncd D:/skill/wecom-voice-agent\n\n# 1. 硬件检测（纯Python标准库，无需安装任何依赖）\npython scripts/detect_hardware.py\n\n# 2. 语音消息模拟器测试\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n\n# 3. 会话管理\npython scripts/session_manager.py create --userid test\npython scripts/session_manager.py stats\n```\n\n### v2.8 运营工具速用\n\n```bash\ncd D:/skill/wecom-voice-agent\n\n# 查看全部可用音色（3 套预设，来自 config/voices.yaml）\npython scripts/voice_policy.py list\n\n# 按场景+情感预览合成参数与 SSML（不发起合成）\npython scripts/voice_policy.py synth --scene outbound --emotion angry --confidence 0.9 --text \"您好，通知您明天下午3点参加评审。\" --ssml\n\n# 查看语音克隆模块状态（未配置 CLONE_PROVIDER/CLONE_API_KEY 时完全隐藏）\npython scripts/voice_clone.py status\n\n# 评审一段通话摘要（三要素评分，≥80 分达标）\npython scripts/summary_qa.py review --text \"会议决定：下周三18点前由张三负责提交修订方案。\" --id call_001\n\n# 查看最近 7 天运营摘要 / 生成上周 HTML 周报\npython scripts/report_generator.py summary --period week\npython scripts/report_gener"},{"path":"README.md","content":"# 企业微信语音消息 Agent\n\n## ✨ 核心特性\n\n- **零 API Key 依赖** - 企业微信内置 ASR 语音转文字免费使用\n- **硬件自适应** - 自动检测用户电脑配置，调整并发和缓存策略\n- **真正的天气查询** - 接入 wttr.in 免费 API，中文描述 + 穿衣建议\n- **当前时间查询** - 本地计算，100%可用，无需任何网络依赖\n- **主动外呼** - v2.0 起支持主动发起语音通话（预约确认、快递提醒、服务回访）\n- **来电接线** - v2.0 起支持用户拨打企业绑定电话自动接线（IVR 替代）\n- **通话纪要** - v2.0 起通话结束自动生成结构化纪要\n- **合规录音** - v2.0 起全程合规（录音告知、用户同意、本机存储、不上传）\n- **外呼调度** - v2.0 起支持定时外呼和批量外呼（CSV 导入）\n- **多轮对话** - 支持上下文保持的连续对话\n- **性能优先** - 低配电脑也能流畅运行\n- **安全可靠** - 所有数据处理在本地完成，不上传用户隐私\n- **开箱即用** - 纯 Python 标准库，无需安装任何依赖\n\n## 🚀 快速开始\n\n### 一条命令体验所有功能\n\n```bash\n# 1. 一键测试（无需启动服务）\ncd D:/skill/wecom-voice-agent\npython scripts/wecom_webhook_server.py --quick\n\n# 2. 单独测试某个指令\npython scripts/voice_simulator.py --text \"北京今天天气怎么样\"\npython scripts/voice_simulator.py --text \"现在几点\"\npython scripts/voice_simulator.py --text \"提醒我下午3点开会\"\n```\n\n### 部署真实机器人\n\n```bash\n# 1. 启动回调服务器\npython scripts/wecom_webhook_server.py --port 8080\n\n# 2. 使用内网穿透暴露端口\nngrok http 8080\n# 或\nfrpc http -l 8080 -p your-domain.com\n\n# 3. 将穿透 URL 填入企业微信管理后台 → 智能机器人 → 回调 URL\n\n# 4. 发送语音消息测试\n```\n\n> 📖 **详细部署指南**：参见 `references/step_by_step_setup.md`\n\n## 🪤 避坑指南\n\n| 常见坑 | 正确做法 |\n|-------|---------|\n| ❌ 在嘈杂环境发送语音指令 | ✅ 在安静环境说话，距离麦克风 20-30cm |\n| ❌ 一次说多句话 | ✅ 一次只做一件事，分开发送 |\n| ❌ 发送超过60秒的语音 | ✅ 控制在 60 秒以内 |\n| ❌ 在群聊中发语音 | ✅ 只对机器人私聊发语音 |\n| ❌ 发送方言 | ✅ 用普通话或粤语发送 |\n\n## 📁 项目结构\n\n```\nwecom-voice-agent/\n├── SKILL.md                          # 技能主文件（指令 + 可运行命令）\n├── README.md                         # 项目说明\n├── references/\n│   ├── step_by_step_setup.md     # 分步部署指南（7步图文教程）\n│   └── wecom_bot_api.md          # 企业微信机器人 API 参考\n├── templates/\n│   └── emotion_strategies.json   # 情感对话策略模板 v2.2（新增）\n└── scripts/\n    ├── detect_hardware.py        # 硬件检测脚本\n    ├── voice_simulator.py        # 语音消息模拟器\n    ├── session_manager.py        # 会话管理器（v2.2 扩展情感状态）\n    ├── wecom_webhook_server.py   # 智能机器人回调服务器 v2.2（集成情感分析）\n    ├── state_machine.py          # 多轮对话状态机 v2.0\n    ├── compliance.py             # 合规录音管理器 v2.0\n    ├── ivr_minutes.py            # 通话自动纪要 v2.0\n    ├── scheduler.py              # 外呼任务调度 v2.0\n    ├── stats.py                  # 通话记录看板 v2.0\n    ├── transcriber.py            # 录音全文转写 v2.0\n    └── emotion_analyzer.py       # 情感识别与自适应策略 v2.2（新增）\n```\n\n## 📋 支持的语音命令\n\n| 命令示例 | 功能 | 是否需要额外配置 |\n|---------|------|---------------|\n| \"北京今天天气怎么样？\" | ✅ 实时天气查询 | ❌ 不需要 |\n| \"现在几点？\" | ✅ 当前时间查询 | ❌ 不需要 |\n| \"明天有什么会议？\" | 🗓️ 日程查询 | ⚠️ 需管理员授权 |\n| \"提醒我下午3点提交报告\" | 📝 创建待办 | ⚠️ 需管理员授权 |\n| \"发消息给张三：明天开会\" | 📬 发送消息 | ⚠️ 需管理员授权 |\n| \"你能做什么？\" | 📖 获取帮助 | ❌ 不需要 |\n| \"退出语音模式\" | 🚪 切换到文字模式 | ❌ 不需要 |\n\n> 💡 **提示**：标注「⚠️ 需管理员授权」的功能，需要企业微信管理员在 work.weixin.qq.com 后台开启对应权限后才能真正执行。查询类功能（天气/时间）无需配置即可使用。\n\n## 📞 v2.0 通话功能\n\n| 功能 | 触发方式 | 说明 |\n|-----|---------|------|\n| 主动外呼 | 系统/用户发起 | 预约确认、快递提醒、服务回访 |\n| 来电接线 | 用户拨打企业绑定电话 | 自动语音交互（IVR 替代） |\n| 通话纪要 | 通话结束自动 | 提取决策点/待办项/时间点 |\n| 合规录音 | 用户同意后 | 本机存储，不上传第三方 |\n| 外呼调度 | 定时/批量 | CSV 导入客户列表 |\n| 通话看板 | `python stats.py` | 统计通话数据和趋势 |\n| 全文转写 | 通话结束后 | 输出 .txt + .docx |\n\n## ⚠️ 限制与边界\n\n- 仅支持企业微信智能机器人场景\n- 不支持主动外呼电话（v2.0 起支持，但需管理员授权）\n- 语音消息限 60 秒以内\n"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"wecom-voice-agent\",\n  \"version\": \"2.8.0\",\n  \"publishedAt\": 1789919541374\n}"},{"path":"references/step_by_step_setup.md","content":"# 企业微信智能机器人 — 分步部署指南\n\n本教程带你**从零开始**搭建一个能接收语音消息的企业微信智能机器人。\n按照以下步骤操作，**不需要任何编程基础**。\n\n---\n\n## 第一步：前提条件\n\n确保你已具备：\n\n- [ ] 一台 Windows 电脑（已安装企业微信）\n- [ ] 注册一个企业微信账号\n- [ ] 安装 Python 3.8+\n\n检查 Python 安装：\n\n```bash\npython --version\n```\n\n---\n\n## 第二步：获取企业微信 CorpID 和 Secret\n\n### 2.1 获取 CorpID\n\n1. 打开 https://work.weixin.qq.com\n2. 登录你的企业微信管理后台\n3. 点击 **我的企业** → 下拉找到 **企业ID**\n4. 复制并保存这个 ID（例如：`ww1234567890abcdef`）\n\n### 2.2 创建自建应用\n\n1. 管理后台 → **应用管理** → **自建** → **创建应用**\n2. 填写应用名称（如\"语音助手\"），上传一个 logo\n3. 可见范围选择 **全部成员**\n4. 创建后进入该应用，记录以下信息：\n   - **AgentID**（应用 ID）\n   - **Secret**（应用密钥）\n\n---\n\n## 第三步：配置智能机器人回调\n\n1. 在应用详情页面找到 **智能机器人**\n2. 点击 **开启**，设置以下参数：\n\n```\n回调 Token: 任意字符串（如 my_wecom_voice_bot_2026）\nEncodingAESKey: 随机生成或自己填写一个 43 位字符串\n```\n\n3. **回调 URL**：先填写一个临时地址（如 `http://example.com/callback`），等服务器启动后再更新\n\n---\n\n## 第四步：启动本地服务器\n\n### 4.1 进入技能目录\n\n```bash\ncd D:\\skill\\wecom-voice-agent\n```\n\n### 4.2 启动 Webhook 服务器\n\n```bash\npython scripts/wecom_webhook_server.py --port 8080\n```\n\n看到以下输出说明启动成功：\n\n```\n============================================================\n企业微信语音消息回调服务器已启动\n监听地址: http://0.0.0.0:8080\n...\n============================================================\n```\n\n### 4.3 URL 验证\n\n企业微信会向你的回调 URL 发送 GET 请求验证。确保：\n- 你的服务器正在运行\n- URL 路径是 `/`（即服务器访问地址 + `/`）\n\n验证通过后，服务器日志会显示：\n\n```\nINFO: URL 验证请求已处理\n```\n\n---\n\n## 第五步：内网穿透（如果你的电脑没有公网 IP）\n\n大多数公司/家庭网络没有公网 IP，需要使用内网穿透工具暴露 8080 端口。\n\n### 使用 frp（推荐）\n\n```bash\n# 安装 frp 后\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 使用 ngrok（快速）\n\n```bash\nngrok http 8080\n```\n\n获得一个公网地址如 `https://abc123.ngrok-free.app`，将其作为回调 URL。\n\n---\n\n## 第六步：更新回调 URL\n\n回到企业微信管理后台 → 智能机器人 → 编辑回调 URL：\n\n```\nhttps://abc123.ngrok-free.app/\n```\n\n提交后企业微信会重新验证 URL，看到验证成功即可。\n\n---\n\n## 第七步：测试语音消息\n\n1. 打开企业微信客户端\n2. 搜索你刚刚创建的机器人应用（如\"语音助手\"）\n3. 发送一条语音消息：\"明天有什么会议？\"\n4. 机器人应该回复一个帮助信息的文字消息\n\n**成功！** 你的企业微信语音助手已经上线了。\n\n---\n\n## 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| 验证 URL 失败 | 检查服务器是否启动、端口是否正确、穿透工具是否运行 |\n| 收不到语音消息 | 确保回调 URL 正确、智能机器人已开启、消息类型支持语音 |\n| 中文乱码 | 服务器已使用 UTF-8 编码，检查终端编码设置 |\n| 被动回复超时 | 单次回复超过 5 秒会被企业微信丢弃，检查代码性能 |\n\n---\n\n## 高级配置\n\n### 配置 Token/AESKey 解密\n\n本技能默认部署。如需加密解密消息，请修改配置：\n\n```python\nWECHAT_CONFIG = {\n    \"token\": \"your_real_token\",\n    \"encoding_aes_key\": \"your_real_key\",\n    ...\n}\n```\n\n并安装加密包：\n\n```bash\npip install pycryptodome\n```\n\n### 扩展功能（接入企业微信 API）\n\n当你的技能需要回发消息、查询日历时，需要获取 access_token：\n\n```bash\ncurl -s -X POST \\\n  'https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ww1234567890abcdef&corpsecret=YOUR_SECRET' \\\n  | python -c \"import sys,json;d=json.load(sys.stdin);print(d['access_token'])\"\n```\n\n---\n\n## 下一步\n\n配置好服务器后，继续学习：\n- [企业微信机器人 API 参考](../../references/wecom_bot_api.md)\n- [意图解析器配置]（修改 `wecom_webhook_server.py` 中的 `intent_keywords` 字典）\n- [会话持久化]（将 `self.sessions` 替换为文件或数据库存储）\n\n如有问题，发送邮件至：**njskills@agent.qq.com**"},{"path":"references/wecom_bot_api.md","content":"# 企业微信智能机器人 API 参考\n\n本文档汇总了企业微信智能机器人与语音消息相关的 API 能力，供开发者快速查阅。\n\n---\n\n## 一、智能机器人概述\n\n当用户向智能机器人发送消息时，企业微信后台会向开发者配置的回调 URL 推送事件。开发者可以：\n\n1. 接收消息回调\n2. 被动回复消息（同步）\n3. 流式回复消息（同步更新内容）\n4. 主动发送消息（异步）\n\n**官方文档**：https://developer.work.weixin.qq.com/document/path/101039\n\n---\n\n## 二、语音消息回调\n\n当用户在单聊中向机器人发送语音消息时，回调格式如下：\n\n```json\n{\n    \"msgid\": \"CAIQrcjMjQYY/NGagIOAgAMg6PDc/w0=\",\n    \"aibotid\": \"AIBOTID\",\n    \"chattype\": \"single\",\n    \"from\": {\"userid\": \"USERID\"},\n    \"response_url\": \"RESPONSEURL\",\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"content\": \"这是语音转写后的文本内容\"\n    }\n}\n```\n\n**核心要点**：企业微信已内置语音转文字功能，回调中的 `voice.content` 字段直接包含转写文本。**开发者无需自行接入 ASR 服务**。\n\n---\n\n## 三、消息类型支持\n\n| 消息类型 | 接收 | 发送 | 说明 |\n|---------|------|------|------|\n| 文本消息 | ✅ | ✅ | 最常用 |\n| 图片消息 | ✅ | ✅ | 临时素材 |\n| 语音消息 | ✅ | ✅ | 接收时已转写为文字 |\n| 视频消息 | ✅ | ✅ | 最大 100MB |\n| 文件消息 | ✅ | ✅ | 最大 100MB |\n| 图文混排 | ✅ | ❌ | 仅接收，群聊或单聊 |\n| 模板卡片 | ❌ | ✅ | 富文本交互，被动回复 |\n\n---\n\n## 四、回复消息格式\n\n### 4.1 被动回复（文本）\n\n```json\n{\n    \"msgtype\": \"text\",\n    \"text\": {\n        \"content\": \"这是回复内容\"\n    }\n}\n```\n\n### 4.2 被动回复（语音）\n\n需要先上传语音素材获取 media_id：\n\n```json\n{\n    \"msgtype\": \"voice\",\n    \"voice\": {\n        \"media_id\": \"上传后获得的media_id\"\n    }\n}\n```\n\n### 4.3 流式回复\n\n适合长文本生成场景，通过 `response_url` 分批次推送：\n\n```json\n{\n    \"msgtype\": \"stream\",\n    \"stream\": {\n        \"id\": \"STREAM_ID\",\n        \"finish\": false,\n        \"content\": \"...\"\n    }\n}\n```\n\n---\n\n## 五、安全机制\n\n### 5.1 加密方式\n\n- 所有回调消息使用 AES-256-CBC 加密\n- IV 向量为 AESKey 前 16 字节\n- 数据采用 PKCS#7 填充\n\n### 5.2 权限要求\n\n- 需要配置回调 URL、Token、EncodingAESKey\n- 所有通信必须使用 HTTPS\n\n### 5.3 安全限制\n\n- 回调 URL 必须能处理 GET（验证）和 POST（回调）请求\n- 每次回调的 msgid 需用于去重\n- response_url 在消息接收后 48 小时内有效\n\n---\n\n## 六、频率限制\n\n| 操作 | 限制 | 说明 |\n|------|------|------|\n| 被动回复 | 不限制 | 推荐用于实时交互 |\n| API 调用 | 20次/分钟 | 主动调用企业微信 API |\n| 主动发送 | 20次/分钟 | 异步发送消息 |\n| 流式刷新 | 最长6分钟 | 用户发消息后 |\n| 并发交互 | 3条/用户 | 同一用户同时消息数 |\n\n---\n\n## 七、关键注意事项\n\n1. **语音转写由企业微信官方处理**，开发者无法控制 ASR 引擎选择\n2. **语音消息仅限单聊**（`chattype: single`），群聊暂不支持语音\n3. **response_url 有效期**：被动回复的 response_url 仅 48 小时内有效\n4. **临时素材有效期**：上传的媒体文件（语音、图片）3 天后失效，需重新上传\n5. **流式消息需主动结束**：发送 `finish: true` 结束流式消息\n\n---\n\n## 八、开发环境搭建\n\n### 8.1 配置智能机器人\n\n1. 登录企业微信管理后台\n2. 应用管理 → 创建应用 → 配置智能机器人\n3. 设置回调 URL/Token/EncodingAESKey\n4. 开通接收消息权限\n\n### 8.2 本地测试\n\n使用内网穿透工具暴露本地服务（如 frp）：\n\n```bash\nfrpc http -l 8080 -p your-domain.com\n```\n\n### 8.3 验证回调\n\n企业微信发送 GET 请求验证 URL：\n\n```\nGET /callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx\n```\n\n返回解密后的 echostr 原文即可通过验证。\n\n---\n\n## 九、错误码参考\n\n| 错误码 | 含义 | 处理建议 |\n|-------|------|---------|\n| 0 | 成功 | - |\n| 40001 | 不合法的 secret | 检查应用凭证 |\n| 40003 | 不合法的 UserID | 检查用户身份 |\n| 40014 | 不合法的 access_token | 刷新 token |\n| 60020 | 网络连接异常 | 检查企业微信服务器网络 |\n| 84014 | 频率超限 | 降低发送频率，使用队列 |\n| 45009 | 接口调用超过限制 | 实现退避重试机制 |\n\n**完整错误码**：https://developer.work.weixin.qq.com/document/path/90313"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会... Skill: wecom-voice-agent Owner: fyniujin Summary: 企业微信语音消息 AI Agent 技能，自动处理语音消息的意图识别、多轮对话与任务执行。 支持被动接收语音消息、主动外呼、来电接线、通话纪要、合规录音、外呼调度等完整电话场景。 v2.6 新增：声明式意图引擎（YAML 配置 20+ 意图 + 多级澄清）、自定义意图插件（企业自有 API 声明式映射）、 统一会... Tags: latest:2.8.0 Version history: v2.8.0 | 2026-09-20T15:52:21.374Z | auto **v2.8.0 introduces voice TTS multi-voice, voice clone, summary QA, and ops reporting tools.** - Added config/voices.yaml: Predefine","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1016,"uniquenessScore":50,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T01:23:56.511Z","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-10T01:23:56.511Z","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-10T06:44:53.820Z","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"}]}}}