{"id":"fd76c9da-e21f-4e17-80cf-bad12ecb76eb","entityType":"agent","slug":"clawhub-fangfang19-wecom-weisheng-scrm","name":"微盛企微管家SCRM","canonicalUrl":"https://www.xpersona.co/agent/clawhub-fangfang19-wecom-weisheng-scrm","canonicalPath":"/agent/clawhub-fangfang19-wecom-weisheng-scrm","generatedAt":"2026-10-11T16:06:46.034Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T13:54:21.192Z","emptyReason":null},"description":"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Skill: 微盛企微管家SCRM Owner: fangfang19 Summary: 当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-06T08:15:13.771Z | user Version 1.0.4 - 移除了“联系支持”部分，将相关说明合并进“使用说明”。 - 更新了“处理原则”中关于不可执行操作模式的描述（去除了对 Craft 模式的限定）。 - 新增“安全与隐私”章节，明确 APP KEY 获取、保存及撤销方法，并声明本地安全策略。 - 其他文档结构优化，无功能变动","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1762jhymf8fapq8waemz2aky585dths:wecom-weisheng-scrm","sourceUrl":"https://clawhub.ai/fangfang19/wecom-weisheng-scrm","homepage":"https://clawhub.ai/fangfang19/skills/wecom-weisheng-scrm","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/fangfang19/wecom-weisheng-scrm","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/fangfang19/skills/wecom-weisheng-scrm","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Skill: 微盛企微管家S"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:54:21.192Z","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-11T13:54:21.192Z","emptyReason":null},"stars":null,"forks":null,"downloads":1054,"packageName":null,"latestVersion":"1.0.4","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:54:21.131Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T13:54:21.192Z","lastCrawledAt":"2026-10-11T13:54:21.131Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T13:54:21.131Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.4","createdAt":"2026-05-06T08:15:13.771Z","changelog":"Version 1.0.4 - 移除了“联系支持”部分，将相关说明合并进“使用说明”。 - 更新了“处理原则”中关于不可执行操作模式的描述（去除了对 Craft 模式的限定）。 - 新增“安全与隐私”章节，明确 APP KEY 获取、保存及撤销方法，并声明本地安全策略。 - 其他文档结构优化，无功能变动。","fileCount":19,"zipByteSize":42377},{"version":"1.0.3","createdAt":"2026-04-23T09:06:15.728Z","changelog":"首版发布：覆盖客户、标签、群聊、素材、活码、群发、跟进、会话存档、商机等SCRM全场景","fileCount":18,"zipByteSize":40515}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1762jhymf8fapq8waemz2aky585dths:wecom-weisheng-scrm","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","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-fangfang19-wecom-weisheng-scrm/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/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-11T16:06:46.033Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fangfang19-wecom-weisheng-scrm/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-11T13:54:21.192Z","emptyReason":null},"readme":"Skill: 微盛企微管家SCRM\n\nOwner: fangfang19\n\nSummary: 当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。\n\nTags: latest:1.0.4\n\nVersion history:\n\nv1.0.4 | 2026-05-06T08:15:13.771Z | user\n\nVersion 1.0.4\n\n- 移除了“联系支持”部分，将相关说明合并进“使用说明”。\n- 更新了“处理原则”中关于不可执行操作模式的描述（去除了对 Craft 模式的限定）。\n- 新增“安全与隐私”章节，明确 APP KEY 获取、保存及撤销方法，并声明本地安全策略。\n- 其他文档结构优化，无功能变动。\n\nv1.0.3 | 2026-04-23T09:06:15.728Z | user\n\n首版发布：覆盖客户、标签、群聊、素材、活码、群发、跟进、会话存档、商机等SCRM全场景\n\nArchive index:\n\nArchive v1.0.4: 19 files, 42377 bytes\n\nFiles: install.sh (2027b), README.md (6727b), references/agent-runbook.md (19620b), references/examples.md (631b), references/file-utils.md (2044b), references/guide.md (1453b), scripts/api_client.py (5852b), scripts/chat_mode.py (2570b), scripts/claw_client.py (10635b), scripts/environment.py (4089b), scripts/file_utils.py (4420b), scripts/get_access_token.py (5449b), scripts/identity_manager.py (4642b), scripts/raw_fetcher.py (2701b), scripts/scrm.py (11520b), scripts/utils.py (6654b), skill-card.md (3125b), SKILL.md (4007b), _meta.json (138b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: wecom-weisheng-scrm\ndescription: \"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。\"\ndescription_zh: \"微盛AI·企微管家提供的技能，帮助用户查询和管理企业微信 SCRM 中的客户、客户群、标签、活码、群发、跟进、聊天记录内容等业务数据，可询问AI当前支持的能力清单。\"\ndescription_en: \"Built for WeCom customer operations, helping teams review customer and group activity, prepare campaign assets, and move follow-up, messaging, and opportunity workflows forward.\"\nversion: 1.0.3\n---\n\n# 微盛企微管家SCRM\n\n微盛企微管家 SCRM 面向企业微信客户运营场景，帮助团队围绕客户、社群、素材、活码、群发、会话与商机等业务，更高效地完成查询、协同与执行。\n\n本 Skill 适用于客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、产品库、汇报、抽奖、日程等场景。你可以直接用业务语言提出问题，例如“帮我查最近7天新添加的客户”“看看某个客户的标签和跟进情况”“帮我查客户群或群发情况”。\n\n\n## 使用说明\n\n触发 Skill 后，应先用简短话术向用户说明：微盛AI·企微管家 SCRM 是基于企业微信的 AI 聊天、营销和服务平台，可协助客户运营、社群营销、SCRM 与会话管理，本技能支持查询或管理客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、汇报、抽奖、客户日程等相关能力；如需进一步支持，可联系专属客服。\n\n**触发 Skill 后，必须先阅读 [references/agent-runbook.md](references/agent-runbook.md) 并严格按其中的调用流程执行（包括 `check-env` → `check-identity` 的顺序），不得跳过或自行编排步骤。**\n\n### 推荐提问方式\n\n- 帮我查一下最近新增客户和重点跟进客户的情况。\n- 帮我看看这个客户的标签、跟进记录和聊天情况。\n- 帮我整理一下当前客户群和群发相关情况。\n- 帮我看一下最近活码和素材相关情况。\n\n### 处理原则\n\n- 默认使用业务语言回复用户，先说结论，再说明还缺什么信息或下一步怎么处理。\n- 如需补充条件，优先向用户追问时间范围、客户名称、标签、员工、群发范围等业务信息。\n- 查询类需求可直接处理；创建、编辑、删除、发送等写操作应在用户确认后再执行。\n- 若用户当前所在模式无法执行命令或脚本，应先提示切换到具备执行能力的模式。\n\n对普通用户回复时，不要主动暴露 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、代理调用等内部术语，除非用户明确要求查看。\n\n## 安全与隐私\n\n本 Skill 需要你的企微管家 APP KEY 授权。KEY 仅保存在本地设备（Shell 配置 / Windows 注册表），不会上传到 QClaw 服务器或任何第三方。\n\n- 获取：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY\n- 撤销：在企微管家后台重置 APP KEY，或执行 `python3 scripts/scrm.py set-app-key \"\"`\n\n## 文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [references/guide.md](references/guide.md) | 使用参考与常见业务场景 |\n| [references/examples.md](references/examples.md) | 示例问题与使用示例 |\n| [references/agent-runbook.md](references/agent-runbook.md) | AI 执行手册（流程、命令参考、权限、错误处理、数据依赖） |\n| [references/file-utils.md](references/file-utils.md) | 文件上传与下载（本地图片转公网 URL） |\n\nFile v1.0.4:README.md\n\n# wecom-weisheng-scrm\n\n面向 AI 代理的微盛企微管家 SCRM Skill 插件，提供与微盛企微管家开放平台（`https://open.wshoto.com`）的集成能力。本仓库不包含业务逻辑实现，而是通过动态接口发现和通用代理调用机制，将 AI 代理与企微管家 SCRM 系统打通，覆盖客户管理、标签、群聊、素材、活码、群发、跟进记录、会话存档、商机、产品库、汇报、抽奖、日程等业务场景。\n\n## 特性\n\n- **零外部依赖** — 仅使用 Python 标准库，无需 `pip install`\n- **动态接口发现** — 通过 Claw 模块实时拉取开放平台 API 目录，支持关键词模糊搜索\n- **通用代理转发** — 统一通过 `/openapi/claw/proxy/forward` 代理调用所有业务接口\n- **角色权限感知** — 自动识别当前用户身份（超管/分管/普通员工），约束数据访问范围\n- **写操作保护** — 自动识别写操作（新增、创建、删除、发送等），禁止失败自动重试\n- **结构化 JSON 输出** — 所有命令输出标准化 JSON，适合 AI 代理解析\n\n## 仓库结构\n\n```text\nwecom-weisheng-scrm/\n├── SKILL.md                  # Skill 描述文件，供 openclaw 平台识别\n├── install.sh                # 安装/卸载脚本（symlink 到 ~/.openclaw/skills/）\n├── references/               # AI 代理执行参考文档\n│   ├── agent-runbook.md      # 代理执行手册（流程、权限、错误处理）\n│   ├── examples.md           # 用户查询示例与预期输出\n│   ├── file-utils.md         # 文件上传/下载说明\n│   └── guide.md              # 用户使用指南\n├── scripts/                  # Python CLI 实现\n│   ├── scrm.py               # 主入口，命令分发\n│   ├── api_client.py         # HTTP 客户端（GET/POST/multipart）\n│   ├── claw_client.py        # Claw 模块客户端（API 目录 + 代理转发）\n│   ├── environment.py        # 环境检查（Python >= 3.9、APP_KEY）\n│   ├── file_utils.py         # 图片上传/下载工具\n│   ├── get_access_token.py   # Token 管理（获取 + 缓存 + 刷新）\n│   ├── identity_manager.py   # 用户身份管理（角色检测 + 缓存）\n│   ├── raw_fetcher.py        # 受控远程文档读取（域名白名单）\n│   ├── chat_mode.py          # 会话存档模式管理（key/zone）\n│   └── utils.py              # 公共工具（异常、日志、JSON 输出、时间处理）\n├── .cache/                   # 运行时缓存（Token、API 目录、身份信息）\n├── logs/                     # 运行日志\n└── README.md\n```\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n./install.sh install     # 创建 symlink 到 ~/.openclaw/skills/wecom-weisheng-scrm\n./install.sh uninstall   # 移除 symlink\n```\n\n### 2. 配置环境变量\n\n| 变量 | 必填 | 说明 |\n|------|------|------|\n| `SCRM_APP_KEY` | 是 | 企微管家个人访问令牌。获取路径：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY |\n| `SCRM_BASE_URL` | 否 | 覆盖默认地址（默认 `https://open.wshoto.com`） |\n| `SCRM_SKIP_SSL_VERIFY` | 否 | 设为 `1` 跳过 SSL 验证（内网环境使用） |\n| `SCRM_MEDIA_CATEGORY_ID` | 否 | 素材上传分类 ID |\n\n### 3. 检查运行环境\n\n```bash\npython3 scripts/scrm.py check-env\n```\n\n### 4. 设置凭证\n\n```bash\npython3 scripts/scrm.py set-app-key \"your_personal_access_token\"\n```\n\n### 5. 获取当前身份\n\n```bash\npython3 scripts/scrm.py check-identity\n```\n\n返回用户角色：超管（`super_user=1`）、分管（`super_user=2`）、普通员工（`super_user=0 或 3`）。\n\n## 命令说明\n\n| 命令 | 说明 |\n|------|------|\n| `check-env` | 检查运行环境（Python 版本、APP_KEY 配置） |\n| `set-app-key <key>` | 持久化写入 APP KEY 到 Shell 配置文件 |\n| `check-identity` | 获取当前用户身份与角色 |\n| `list-apis --keyword <关键词>` | 按关键词搜索 API 目录（逗号分隔多关键词） |\n| `call-api --service-name <服务名> --uri <路径> --biz-params <JSON>` | 通过通用代理调用业务接口 |\n| `fetch-raw-doc --url <文档URL>` | 获取远程接口文档原始内容（仅限 `open.wshoto.com` 域名） |\n| `upload-image --path <本地路径>` | 上传本地图片，返回公开 URL 和 file_id |\n| `set-chat-mode --mode <key\\|zone>` | 设置会话存档模式 |\n\n### 使用示例\n\n**搜索接口：**\n\n```bash\npython3 scripts/scrm.py list-apis --keyword \"客户,标签,群发\"\n```\n\n**调用接口：**\n\n```bash\npython3 scripts/scrm.py call-api \\\n  --service-name \"wshoto-basebiz-service\" \\\n  --uri \"/bff/crm/private/h5/customer/list\" \\\n  --biz-params '{\"currentIndex\":1,\"pageSize\":10}'\n```\n\n**获取文档：**\n\n```bash\npython3 scripts/scrm.py fetch-raw-doc \\\n  --url \"https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md\"\n```\n\n**上传图片：**\n\n```bash\npython3 scripts/scrm.py upload-image --path ./poster.png\n```\n\n## 工作机制\n\n```\n用户提问\n  ↓\ncheck-env → 校验环境\n  ↓\ncheck-identity → 确定用户角色\n  ↓\nfetch-raw-doc → 拉取远程接口目录\n  ↓\nlist-apis → 关键词搜索匹配接口\n  ↓\nfetch-raw-doc → 阅读对应接口文档\n  ↓\ncall-api → 通过代理转发调用业务接口\n  ↓\n结构化 JSON 返回结果\n```\n\n关键约束：\n\n- 每次会话首次触发时必须通过 `fetch-raw-doc` 获取远程接口目录原始内容，再按关键词搜索匹配接口\n- 普通员工（`super_user=0/3`）仅可查看个人数据，无法查询团队数据或搜索组织架构\n- 写操作（新增、创建、删除、发送等）失败后禁止自动重试，防止重复操作\n- 本地图片类输入需先通过 `upload-image` 上传，再将返回的 URL 用于后续业务接口\n- 读取接口文档必须使用 `fetch-raw-doc` 命令（受域名白名单约束），不可使用其他工具替代\n\n## 缓存策略\n\n| 缓存文件 | 内容 | TTL |\n|----------|------|-----|\n| `.cache/access_token.json` | OAuth Token + user_id + 过期时间 | Token 有效期 - 5 分钟 |\n| `.cache/api_list.json` | 完整 API 目录（约 44KB） | 2 小时 |\n| `.cache/identity.json` | 用户角色信息 | 2 小时 |\n\n## 技术栈\n\n| 组件 | 技术 |\n|------|------|\n| 语言 | Python 3.9+（零外部依赖） |\n| HTTP 客户端 | `urllib.request`（标准库） |\n| CLI 框架 | `argparse`（标准库） |\n| 数据格式 | JSON |\n| 日志 | `logging` 模块，输出到 `logs/scrm.log` |\n| 目标平台 | 微盛企微管家开放平台 |\n| 部署方式 | OpenClaw：symlink 到 `~/.openclaw/skills/`；QClaw：设置 → 技能管理一键启用 |\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn76jhdedxj61v2z5cpzgjt8r985c44f\",\n  \"slug\": \"wecom-weisheng-scrm\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1778055313771\n}\n\nFile v1.0.4:references/agent-runbook.md\n\n# AI 执行手册\n\n本文件供 AI 在执行本 Skill 时使用，不面向普通用户解释内部接口细节。\n\n## 用户沟通口径\n\n对普通用户回复时，默认使用业务语言和结果导向表达，不要主动使用过多技术术语。\n\n1. **默认不用技术词堆砌**：除非用户主动追问，否则不要直接说 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、接口编排、代理调用等术语。\n2. **先说能帮用户做什么**：优先说\"我先帮你看看\"\"我先帮你查一下\"\"我来帮你整理\"这类表达，再说明还需要用户补充什么。\n3. **权限提示说人话**：不要直接对用户说 TEAM、MINE、super_user；改为\"你当前可以看团队数据\"或\"你当前只能看自己的数据\"。\n4. **配置提示说人话**：不要只说\"未配置 SCRM_APP_KEY\"；改为\"你这边还没有完成企微管家授权，需要先获取 APP KEY 后我才能继续帮你查\"。\n5. **参数收集说业务信息**：不要说\"请提供 biz_params\"；改为\"还需要补充时间范围、客户名称、标签、员工等信息\"。\n6. **反馈结果先讲结论**：查询成功时先总结查到了什么；失败时先说发生了什么和下一步怎么办，不先抛错误码。\n7. **用户看不懂的内部信息不主动暴露**：接口路径、服务名、文档地址、原始返回结构，仅在用户明确要求查看时再展示。\n8. **读取接口目录时统一使用仓库内的受控原文读取命令**：应直接获取目标地址的原始内容，统一执行 `python3 scripts/scrm.py fetch-raw-doc --url <目标地址>`；不要先做网页搜索，不要先打开站点首页，也不要仅基于摘要页或搜索结果推断接口。\n9. **不要回退到 `web_fetch` 或其他网页抓取方式**：open.wshoto.com 文档读取统一走仓库内脚本命令，不使用网页正文抽取，不依赖首页跳转或搜索结果。\n\n### 推荐话术示例\n\n- 查询前：我先帮你看一下。\n- 继续追问信息时：还需要你补充一下时间范围 / 客户名称 / 标签信息，我再继续帮你查。\n- APP KEY 未配置时：你这边还没有完成企微管家授权，先去企业微信-工作台-企微管家-我的-我的 APP KEY 获取后发给我，我再继续帮你处理。\n- 普通员工查团队数据时：你当前只能查看自己的数据，团队数据这边暂时查不了。\n- 查询失败时：这次没有查成功，我把原因和下一步怎么处理跟你说一下。\n\n## 脚本位置\n\n脚本位于 SKILL.md 所在目录下的 `scripts/scrm.py`。AI 读取本文件时已知其路径，因此直接基于 SKILL.md 的目录拼接即可。\n\n## 环境检测\n\n触发 Skill 后，AI 应先检查当前是否具备脚本执行能力，以便运行仓库内命令读取原始文档并完成后续流程。\n\n若用户当前所在模式不具备脚本执行能力，应直接提示用户切换到具备命令执行能力的模式后再继续；不要在明知当前模式无法执行命令时继续后续接口流程。\n\n- **如果具备** → 正常继续后续调用流程。\n- **如果不具备** → 引导用户切换到可执行脚本的模式或补齐命令执行能力，完成前不要继续后续流程。\n\n处理原则：\n\n- 缺少脚本执行能力时，先解决环境问题，再继续接口目录读取和后续 API 流程。\n- 若已确认问题来自当前模式的执行能力限制，优先明确提示用户切换到具备所需能力的模式，不要只笼统提示\"稍后再试\"。\n- 不要在缺少原文读取能力的情况下，直接把接口目录读取降级成普通网页搜索或首页浏览。\n- 如果用户尚未完成重启，不要假装后续命令已经执行成功。\n\n## 调用流程\n\nAI 按以下编排流程执行：\n\n1. **执行环境检测** → 先确认当前是否具备脚本执行能力；若不具备，则按\"环境检测\"章节优先引导用户切换到可用模式或补齐必要能力，完成前不要继续后续流程\n   - 若已知用户当前模式无法执行命令，先明确提示其切换到具备所需能力的模式\n2. **执行 check-env** → 检查运行环境（Python ≥3.9、SCRM_APP_KEY）；`check-env` 内部会自动尝试从 shell profile 或 Windows 注册表中恢复已持久化的 APP_KEY\n   - 成功且返回中包含 `export_hint` → 说明 APP_KEY 是从持久化配置中恢复的，**立即执行返回的 `export_hint` 命令**（如 `export SCRM_APP_KEY='xxx'`）使当前 shell 会话生效，然后继续\n   - 成功且无 `export_hint` → APP_KEY 已在环境变量中，直接继续\n   - 失败（`config_error`）→ 引导用户获取 APP KEY 并执行 `set-app-key`，成功后执行 `export SCRM_APP_KEY='<值>'`，然后继续\n   - 若用户主动要求更换或更新 APP KEY（即使当前已配置），同样执行 `set-app-key` 用新值覆盖、export 后再继续\n3. **执行 check-identity** → 获取用户身份（超管/分管/员工）\n4. **阅读远程接口目录（强制步骤，不得跳过）** → 必须先读取 [CLAW_SUMMARY.md](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md) 的原始内容，再根据用户意图匹配目标接口；每次会话首次触发 Skill 时必须执行此步骤，不得凭已有认知直接跳到 list-apis。执行时统一使用仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url <url>`\n5. **执行 list-apis** → 用接口名称关键词匹配调用规则（service_name、api_path、doc_url）\n6. **阅读接口文档（doc_url）** → 阅读该文档获取完整参数定义，强制步骤，不得跳过\n7. **通过对话收集 biz_params** → 基于 doc_url 文档中的参数说明收集必要参数，不得仅凭 description 推断\n8. **执行 call-api** → 将 list-apis 返回的 service_name、api_path 及收集到的 biz_params 组装后通过通用代理调用\n\n### 接口目录与文档读取要求\n\n- 读取接口目录时，目标是拿到原始响应内容，而不是做网页正文抽取。\n- 统一执行仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md`。\n- 该命令内置超时、域名白名单和响应大小限制，比 `web_fetch` 更稳定，也更容易通过安全审查。\n- 读取 doc_url 对应在线文档时，也统一执行 `python3 scripts/scrm.py fetch-raw-doc --url <doc_url>`。\n- 不要退化为首页浏览、搜索摘要或人工猜测。\n\n> **⚠️ 文档内容截断处理：** 工具展示 stdout 时可能截断长文本，但数据本身未丢失。**必须通过管道解析完整 content**，不要直接读 stdout，否则会遗漏参数（如跟进记录接口的 `menu`、`searchField/searchValue` 曾因此被忽略）。\n>\n> ```bash\n> python3 scripts/scrm.py fetch-raw-doc --url <url> | python3 -c \"\n> import sys, json; data = json.load(sys.stdin); print(data['data']['content'])\n> \"\n> ```\n\n### 接口匹配规则\n\n1. 阅读远程接口目录后，根据用户意图匹配接口名称和使用说明\n2. 匹配到唯一接口时直接使用，无需询问用户\n3. 匹配到多个候选接口时，列出候选项让用户选择\n4. 无法匹配时，告知用户当前无匹配接口\n\n### 接口间数据依赖\n\ndoc_url 文档中的「业务参数数据来源说明」章节描述了每个参数的值从哪里获取。AI 组装 `biz_params` 时，**必须先识别依赖关系，按正确顺序调用前置接口获取参数值**，不能跳过或猜测。\n\n**参数来源识别：**\n\n| 来源描述关键词 | AI 行为 |\n|----------------|---------|\n| 「前端XX选择器」「前端输入框」 | 通过对话向用户收集 |\n| 「XX接口返回数据中的 `field` 字段」 | **必须先调用前置接口获取**，再用返回值填充 |\n| 「预设枚举值」 | 根据用户意图从固定选项中匹配 |\n| 「用户选择/用户输入」 | 通过对话收集，可能需要先列出选项 |\n\n**处理原则：**\n1. 每次调用接口前，先阅读 doc_url 的「业务参数数据来源说明」，确认是否有参数依赖其他接口\n2. 对于来源为其他接口的字段（如 tagId、userId、deptId），绝不能凭用户输入的名称自行构造，必须通过前置接口查询获取真实值\n3. 前置接口返回多条匹配记录时，列出选项让用户确认\n4. 同一会话内已获取的数据可复用，无需重复调用\n\n**典型场景 — 按标签名查客户：**\n\n用户说\"查一下有多少客户打了高意向客户标签\"，正确做法：\n1. `list-apis --keyword \"客户列表\"` → 找到「客户列表分页查询」\n2. 阅读 doc_url → 发现 `tagIds` 参数依赖「获取客户标签列表」接口\n3. `list-apis --keyword \"标签\"` → 找到「获取客户标签列表」，用 `keyValue=\"高意向客户\"` 搜索\n4. 从返回结果中匹配 `tagName`，提取对应 `tagId`（多个同名标签时列出让用户选择）\n5. 将 `tagId` 填入 `tagIds` 参数，调用客户列表接口\n\n> **错误做法**：直接猜测或构造 tagId 去查询。\n\n## 命令参考\n\n所有命令统一以如下格式执行，参数通过对话收集，不依赖 stdin 交互：\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" <command> [--param value ...]\n```\n\n> **首次调用某个命令前，必须先执行 `<command> --help` 确认参数名称和格式，不得凭猜测传参。**\n> **所有参数必须使用 `--param-name` 连字符格式，禁止使用下划线格式。**\n\n### check-env — 环境检查\n\n触发 Skill 时**立即**执行，失败则终止。检查项：Python ≥3.9、`SCRM_APP_KEY` 是否已配置。\n\n```bash\npython3 \"$SCRM_SCRIPT\" check-env\n```\n\n### check-env — 环境检查（含 APP_KEY 自动恢复）\n\n触发 Skill 时**立即**执行，失败则终止。检查项：Python ≥3.9、`SCRM_APP_KEY` 是否已配置。\n\n当 `SCRM_APP_KEY` 环境变量为空时，`check-env` 会自动尝试从 shell profile（Unix/macOS）或注册表（Windows）中读取之前通过 `set-app-key` 持久化的值。如果恢复成功，返回结果中会包含 `export_hint` 字段。\n\n```bash\npython3 \"$SCRM_SCRIPT\" check-env\n```\n\n**成功（APP_KEY 已在环境变量中）：**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"checks\": {\n      \"python_version\": {\"ok\": true, \"detail\": \"3.13.3\"},\n      \"app_key\": {\"ok\": true, \"detail\": \"已配置\"}\n    }\n  }\n}\n```\n\n**成功（APP_KEY 从持久化配置中恢复）：**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"checks\": {\n      \"app_key\": {\"ok\": true, \"detail\": \"从持久化配置中恢复（profile）\"}\n    },\n    \"app_key_restored\": {\"source\": \"profile\", \"profile\": \"/Users/xxx/.zshrc\", \"app_key\": \"xxx\"},\n    \"export_hint\": \"export SCRM_APP_KEY='xxx'\"\n  }\n}\n```\n\nAI 处理逻辑：\n- 成功且包含 `export_hint` → **立即执行返回的 `export_hint` 命令**使当前 shell 会话生效，然后继续\n- 成功且无 `export_hint` → 直接继续\n- 失败（`config_error`）→ 引导用户执行 `set-app-key`\n\n**失败：**\n\n```json\n{\n  \"success\": false,\n  \"error\": \"config_error\",\n  \"details\": {\n    \"checks\": {\n      \"app_key\": {\"ok\": false, \"detail\": \"未配置 SCRM_APP_KEY\"}\n    }\n  }\n}\n```\n\n### set-app-key — 设置 APP_KEY\n\n`SCRM_APP_KEY` 未配置时：先询问用户是否已有，若无则引导前往企微管家移动端「我的 → 我的 APP KEY」获取。用户提供后执行：\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" set-app-key \"<用户提供的APP_KEY>\"\n```\n\n成功后：\n1. 立即执行 `export SCRM_APP_KEY='<用户提供的APP_KEY>'`（Unix/macOS）使变量在当前 shell 会话中立即生效；Windows 平台跳过此步骤\n2. 将返回结果中的 `note` 告知用户一次\n3. 直接继续原始请求，不再追问用户是否已重启终端\n\n> ⚠️ **必须执行 `export` 步骤**：`set-app-key` 写入 shell profile 后，当前会话不会自动加载新变量，不执行 `export` 则后续命令（如 `check-env`、`check-identity`）在当前会话内仍读不到 `SCRM_APP_KEY`，导致每次新会话都重复追问用户。\n\n### check-identity — 获取用户身份\n\n无额外参数，自动使用缓存的 user_id。\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" check-identity\n```\n\n返回示例：\n\n```json\n{\n  \"success\": true,\n  \"action\": \"check-identity\",\n  \"data\": {\n    \"user_id\": \"xxx\",\n    \"user_name\": \"张三\",\n    \"super_user\": 1,\n    \"role_description\": \"超级管理员\"\n  }\n}\n```\n\n### set-chat-mode — 设置会话存档模式\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" set-chat-mode --mode <key|zone>\n```\n\n设置一次后永久生效。若用户在对话中明确告知模式，立即执行保存后继续查询；若从未设置且用户未提及，则询问。\n\n### list-apis — 接口仓库查询\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" list-apis --keyword \"关键词1,关键词2\"\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--keyword` | (必填) 多个关键词逗号分隔，模糊匹配 api_name |\n\n返回字段：\n\n| 字段 | 说明 | 用途 |\n|------|------|------|\n| `api_name` | 接口名称 | 确认匹配结果 |\n| `description` | 接口简要描述 | 辅助理解用途，**不含完整参数定义** |\n| `api_path` | 接口 URI | 作为 `call-api --uri` 的值 |\n| `service_name` | 下游微服务名 | 作为 `call-api --service-name` 的值 |\n| `doc_url` | 接口文档地址 | **必读**，获取完整参数定义 |\n\n### call-api — 通用代理调用\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" call-api \\\n  --service-name \"wshoto-basebiz-service\" \\\n  --uri \"/bff/bizCustomer/private/h5/chat/pageQuery\" \\\n  --biz-params '{\"currentIndex\":1,\"pageSize\":10}'\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--service-name` | (必填) 取自 list-apis 返回的 `service_name` |\n| `--uri` | (必填) 取自 list-apis 返回的 `api_path`（注意：字段名是 `api_path`，参数名是 `--uri`） |\n| `--method` | (可选) HTTP 方法，默认 POST |\n| `--biz-params` | (必填) 业务参数 JSON，参数名和类型以 doc_url 文档为准 |\n\n> **字段映射（易混淆）：** `list-apis.service_name` → `--service-name`；`list-apis.api_path` → `--uri`；`list-apis.doc_url` → 阅读后收集 `--biz-params`。\n\n### 参数收集标注含义\n\ndoc_url 文档中的参数标注，AI 必须严格按对应行为执行：\n\n| 标注 | AI 行为 |\n|------|---------|\n| **必须对话收集** | 执行前通过对话明确获取，不得自行推断 |\n| **展示选项让用户选择** | 列出所有选项含默认推荐，等用户选择 |\n| **展示默认值后确认** | 告知默认值，询问是否修改 |\n| 默认：`xxx` | 展示默认值，用户无需主动回复 |\n| 可选 | 用户未提及时跳过 |\n\n## 身份与权限\n\n不同业务接口用于区分团队/个人数据范围的参数名不统一，AI 必须通过阅读 doc_url 文档确认具体字段名。\n\n| check-identity 角色 | 数据范围 | 参数取值 |\n|---------------------|----------|----------|\n| 超管(super_user=1) / 分管(super_user=2) | 团队数据 | 团队对应的枚举值（如 TEAM） |\n| 普通员工(super_user=0或3) | 仅个人数据 | 个人对应的枚举值（如 MINE） |\n\nAI 应根据 check-identity 结果，在 biz_params 中自动填入对应值。当用户未明确指定视角范围时：超管/分管默认使用团队视角，普通员工默认使用个人视角。\n\n### 普通员工视角限制\n\n即使用户主动要求查询团队数据，普通员工也必须使用个人视角，不得使用团队视角。应告知用户\"您的身份是普通员工，只能查看个人数据，无法查看团队数据\"。\n\n### 员工操作限制\n\n当 check-identity 返回 `super_user` 为 `0` 或 `3` 时，当前用户为普通员工，AI 必须严格执行以下限制：\n\n#### 限制一：禁止指定其他员工\n\n普通员工只能操作自己的数据，不能将接口参数中的员工相关字段指定为其他员工。\n\n强制检查流程：\n\n1. 查看 check-identity 返回的 `user_id` 和 `user_name`\n2. 检查 biz_params 中是否包含员工名称、员工ID相关参数（如 `userIds`、`addUserIds`、`staffId` 等）\n3. 如果包含，此类参数必须且只能是 check-identity 返回的 `user_id` 或 `user_name`\n4. 如果用户要求使用其他员工，必须拒绝执行并告知\"您的身份是普通员工，只能操作自己的数据（{user_name}），无法指定其他员工\"\n\n示例：用户说\"创建活码，使用员工=芳芳\"，但 check-identity 返回 user_name=吴浩 → 芳芳≠吴浩，拒绝执行。\n\n#### 限制二：禁止调用员工/部门搜索接口\n\n普通员工无权搜索企业组织架构。员工&部门分类下的搜索接口，以及任何用于获取员工列表、部门列表、组织架构树的接口，普通员工都不得调用。\n\n## 错误处理\n\n| error 类型 | AI 处理方式 |\n|------------|-------------|\n| `config_error` | 用普通用户能理解的话说明还缺什么配置，并引导下一步，不直接抛技术细节 |\n| `validation_error` | 说明还缺哪些业务信息或填写有误，引导用户补充后重试 |\n| `scrm_error` | 用业务语言转述失败原因，并询问用户是否要调整条件后再试 |\n| `json_error` | 内部自行修正，不把 JSON 解析细节暴露给用户 |\n| `unexpected_error` | 告知用户这次没处理成功，建议稍后重试或联系管理员，不直接输出技术报错 |\n\n仅 `scrm_error` 且用户主动要求时才重试；其他类型错误优先修复根因。\n\n### 写操作重试限制\n\n写操作接口执行失败或超时后，禁止自动重试。写操作失败可能是服务端已成功执行但响应超时，自动重试会导致重复创建数据。\n\n具体规则：\n\n1. `call-api` 的输出中包含 `write_operation` 字段，`true` 表示写操作，`false` 表示读操作\n2. 写操作失败或超时时，AI 必须告知用户失败结果，由用户决定是否重试，AI 不得自行重新执行 `call-api`\n3. 读操作不受此限制，AI 可以在合理范围内重试\n\n## 行为规范\n\n以下规则优先级最高，始终遵守：\n\n1. 触发 Skill 时立即执行 `check-env`，在收集任何参数前完成；失败则告知用户并终止，不得继续\n2. 若 `SCRM_APP_KEY` 未配置，先询问用户是否已有 APP_KEY；若没有，则引导前往企业微信-工作台-企微管家应用-我的-我的 APP KEY 获取\n3. 写操作确认，读操作直接执行：查询类接口直接执行；写操作接口必须等待用户最终确认后再执行\n4. 参数收集通过对话完成，不依赖脚本 stdin 交互；执行时统一携带 `SCRM_NON_INTERACTIVE=1`\n5. 用户身份由 `SCRM_APP_KEY` 静默获取，禁止通过命令行参数传入\n6. 所有输出统一为 JSON，便于上层 Skill 编排解析\n7. 首次调用某个命令前，必须先执行 `<command> --help` 确认参数名称和格式，不得凭猜测传参\n8. 面向普通用户回复时，优先使用业务口径：先说能帮用户做什么、查到了什么、还缺什么信息，不主动输出底层接口与参数细节\n9. 涉及接口目录的读取动作一律走受控原文直读：读取 [CLAW_SUMMARY.md](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md) 时，统一使用 `python3 scripts/scrm.py fetch-raw-doc --url <url>`。若当前环境缺少该能力，先修复环境并提示用户切换模式或完成必要配置，再继续，不要直接降级为网页搜索、首页访问或 `web_fetch`\n\n## 文件上传与下载\n\n涉及图片/文件操作时，参考 [file-utils.md](file-utils.md)。\n\nFile v1.0.4:references/examples.md\n\n# 示例\n\n## 示例 1\n\n输入：帮我查一下最近新增客户和重点跟进客户的情况。\n\n输出：返回客户增长情况、重点客户和待跟进事项的汇总信息。\n\n## 示例 2\n\n输入：帮我看看这个客户的标签、跟进记录。\n\n输出：返回客户相关信息，并提示当前还需要补充的业务条件。\n\n## 示例 3\n\n输入：帮我创建我的员工活码。\n\n输出：创建员工活码，返回员工活码创建信息。\n\n## 示例 4\n\n输入：帮我看一下最近活码和素材相关情况。\n\n输出：返回活码和素材相关信息，并说明后续可继续处理的方向。\n\nFile v1.0.4:references/file-utils.md\n\n# 文件上传与下载\n\n`scripts/file_utils.py` 提供本地图片上传与远程文件下载能力，解决本地图片转为公网 URL 的问题。\n\n## 使用场景\n\n创建海报素材、个人活码等操作需要图片 URL。当用户提供本地文件路径时，需自动上传转换为公网地址。上传返回的 `file_id` 可用于后续创建素材等写操作。\n\n## 函数参考\n\n### ensure_public_image_url（推荐入口）\n\n自动判断图片来源并处理，仅需要 URL 时使用。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `source` | `str` | 是 | 远程 URL 或本地文件路径 |\n| `client` | `SCRMClient` | 否 | 本地图片上传时必填 |\n\n- 远程 URL → 直接返回原 URL\n- 本地路径 → 上传后返回公网地址\n\n```python\nurl = ensure_public_image_url(\"https://example.com/img.png\", client=client)\nurl = ensure_public_image_url(\"/Users/me/photo.png\", client=client)\n```\n\n### upload_image\n\n需要同时获取 `url` 和 `file_id` 时使用（如创建素材场景）。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `path` | `Path` | 是 | 本地图片文件路径 |\n| `client` | `SCRMClient` | 是 | SCRM 客户端实例 |\n\n返回 `dict`：`{\"url\": \"https://...\", \"file_id\": 12345}`\n\n### download_file\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | 远程文件地址 |\n| `target_dir` | `Path` | 否 | 下载目标目录 |\n| `filename` | `str` | 否 | 保存文件名，默认自动生成 |\n\n返回 `Path`（下载后的本地文件路径）。\n\n### is_remote_url\n\n判断字符串是否为公网 URL，返回 `bool`。\n\n## 异常类型\n\n| 异常类 | 触发场景 |\n|--------|---------|\n| `DownloadError` | 下载地址非法、网络请求失败 |\n| `UploadError` | 本地文件不存在、上传失败、响应中无法提取 URL 或 file_id |\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `SCRM_SKIP_SSL_VERIFY` | 设为 `1`/`true`/`yes` 跳过 SSL 验证，适用于内网环境 |\n\nFile v1.0.4:references/guide.md\n\n# 微盛企微管家SCRM 使用参考\n\n本 Skill 适用于企业微信客户运营与管理场景，可用于查询或管理客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、产品库、日程等相关能力。\n\n如需人工协助，可扫码联系专属客服：<https://pubres.wshbe.com/qrcode/20260416-53d7fee83fd04dbab3101546559490a6.png>\n\n建议使用流程：\n\n1. 先确认已完成企微管家授权并配置 APP KEY。\n2. 如当前在 WorkBuddy 的 Ask 模式且无法执行命令，请先切换到 Craft（或其他具备命令执行能力的模式）。\n3. 根据要处理的业务场景提出问题，例如客户查询、群发查看、活码查看、素材处理等。\n4. 如需更多条件，按提示补充客户名称、时间范围、标签、员工等业务信息。\n5. 查询结果优先查看结论；写操作需在确认后再执行。\n\n补充约束：\n\n- 读取接口目录时，必须直接获取目标地址的原始内容，并统一使用 `python3 scripts/scrm.py fetch-raw-doc --url <url>`。\n- 不要使用 `web_fetch` 或其他网页抓取方式读取 open.wshoto.com 文档。\n- 不要仅基于首页、搜索结果或网页摘要推断接口。\n\n常见场景包括：\n\n- 查询客户信息与客户标签\n- 查看客户群、群发和跟进记录\n- 查看会话存档与联系人情况\n- 处理活码、素材、商机、产品库和日程相关事项\n\nFile v1.0.4:skill-card.md\n\n## Description:\n\nHelps agents support WeCom customer operations by querying and managing Weisheng SCRM customers, tags, groups, campaign assets, live codes, mass messaging, follow-up records, conversations, opportunities, reports, lotteries, and schedules.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[fangfang19](https://clawhub.ai/user/fangfang19)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nCustomer-operations employees and teams use this skill through an agent to inspect Weisheng SCRM records, prepare campaign and customer-follow-up work, and perform confirmed business actions while respecting the current user's role and data scope.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles live CRM data and can access broad SCRM capabilities through proxy calls.\n\nMitigation: Review before installing, use only on a trusted single-user machine, confirm user identity and role scope before business calls, and require explicit confirmation before uploads or write actions.\n\nRisk: The skill stores an APP KEY and cached access tokens locally.\n\nMitigation: Treat the APP KEY like a password, do not provide APP KEY values from untrusted sources, avoid exposing credentials in logs or command output, and rotate the APP KEY if exposure is suspected.\n\nRisk: Changing the base URL or disabling TLS verification can weaken request integrity.\n\nMitigation: Keep the default Weisheng endpoint and TLS verification enabled unless a trusted controlled environment explicitly requires otherwise.\n\nRisk: Uploads and business write operations can change customer-operation records or publish uploaded assets.\n\nMitigation: Verify API documentation and collected parameters before execution, confirm the exact operation with the user, and do not automatically retry failed write operations.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/fangfang19/skills/wecom-weisheng-scrm)\n- [Publisher Profile](https://clawhub.ai/user/fangfang19)\n- [Weisheng Open Platform](https://open.wshoto.com)\n- [Claw API Summary](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md)\n- [Agent Runbook](artifact/references/agent-runbook.md)\n- [User Guide](artifact/references/guide.md)\n- [File Upload and Download Reference](artifact/references/file-utils.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, JSON, shell commands, configuration, guidance]\n\n**Output Format:** [Business-language responses with structured JSON command results and inline shell commands.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include public image URLs or file IDs after upload; write actions require explicit user confirmation and should not be automatically retried after failure.]\n\n## Skill Version(s):\n\n1.0.4 (source: server release metadata; artifact frontmatter says 1.0.3)\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\nArchive v1.0.3: 18 files, 40515 bytes\n\nFiles: install.sh (1919b), README.md (6667b), references/agent-runbook.md (19729b), references/examples.md (631b), references/file-utils.md (2044b), references/guide.md (1453b), scripts/api_client.py (5852b), scripts/chat_mode.py (2570b), scripts/claw_client.py (10635b), scripts/environment.py (4089b), scripts/file_utils.py (4420b), scripts/get_access_token.py (5449b), scripts/identity_manager.py (4642b), scripts/raw_fetcher.py (2701b), scripts/scrm.py (11520b), scripts/utils.py (6654b), SKILL.md (3733b), _meta.json (138b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: wecom-weisheng-scrm\ndescription: \"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。\"\ndescription_zh: \"微盛AI·企微管家提供的技能，帮助用户查询和管理企业微信 SCRM 中的客户、客户群、标签、活码、群发、跟进、聊天记录内容等业务数据，可询问AI当前支持的能力清单。\"\ndescription_en: \"Built for WeCom customer operations, helping teams review customer and group activity, prepare campaign assets, and move follow-up, messaging, and opportunity workflows forward.\"\nversion: 1.0.3\n---\n\n# 微盛企微管家SCRM\n\n微盛企微管家 SCRM 面向企业微信客户运营场景，帮助团队围绕客户、社群、素材、活码、群发、会话与商机等业务，更高效地完成查询、协同与执行。\n\n本 Skill 适用于客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、产品库、汇报、抽奖、日程等场景。你可以直接用业务语言提出问题，例如“帮我查最近7天新添加的客户”“看看某个客户的标签和跟进情况”“帮我查客户群或群发情况”。\n\n## 联系支持\n\n如需人工协助，可安装技能后输入「联系专属客服」。\n\n\n## 使用说明\n\n触发 Skill 后，应先用简短话术向用户说明：微盛AI·企微管家 SCRM 是基于企业微信的 AI 聊天、营销和服务平台，可协助客户运营、社群营销、SCRM 与会话管理，本技能支持查询或管理客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、汇报、抽奖、客户日程等相关能力；如需进一步支持，可联系专属客服。\n\n**触发 Skill 后，必须先阅读 [references/agent-runbook.md](references/agent-runbook.md) 并严格按其中的调用流程执行（包括 `check-env` → `check-identity` 的顺序），不得跳过或自行编排步骤。**\n\n### 推荐提问方式\n\n- 帮我查一下最近新增客户和重点跟进客户的情况。\n- 帮我看看这个客户的标签、跟进记录和聊天情况。\n- 帮我整理一下当前客户群和群发相关情况。\n- 帮我看一下最近活码和素材相关情况。\n\n### 处理原则\n\n- 默认使用业务语言回复用户，先说结论，再说明还缺什么信息或下一步怎么处理。\n- 如需补充条件，优先向用户追问时间范围、客户名称、标签、员工、群发范围等业务信息。\n- 查询类需求可直接处理；创建、编辑、删除、发送等写操作应在用户确认后再执行。\n- 若用户当前所在模式无法执行命令或脚本，应先提示切换到 Craft 或其他具备执行能力的模式。\n\n对普通用户回复时，不要主动暴露 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、代理调用等内部术语，除非用户明确要求查看。\n\n## 文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [references/guide.md](references/guide.md) | 使用参考与常见业务场景 |\n| [references/examples.md](references/examples.md) | 示例问题与使用示例 |\n| [references/agent-runbook.md](references/agent-runbook.md) | AI 执行手册（流程、命令参考、权限、错误处理、数据依赖） |\n| [references/file-utils.md](references/file-utils.md) | 文件上传与下载（本地图片转公网 URL） |\n\nFile v1.0.3:README.md\n\n# wecom-weisheng-scrm\n\n面向 AI 代理的微盛企微管家 SCRM Skill 插件，提供微盛企微管家开放平台（`https://open.wshoto.com`）的集成能力。本仓库不包含业务逻辑实现，而是通过动态接口发现和通用代理调用机制，将 AI 代理与企微管家 SCRM 系统打通，覆盖客户管理、标签、群聊、素材、活码、群发、跟进记录、会话存档、商机、产品库、汇报、抽奖、日程等业务场景。\n\n## 特性\n\n- **零外部依赖** — 仅使用 Python 标准库，无需 `pip install`\n- **动态接口发现** — 通过 Claw 模块实时拉取开放平台 API 目录，支持关键词模糊搜索\n- **通用代理转发** — 统一通过 `/openapi/claw/proxy/forward` 代理调用所有业务接口\n- **角色权限感知** — 自动识别当前用户身份（超管/分管/普通员工），约束数据访问范围\n- **写操作保护** — 自动识别写操作（新增、创建、删除、发送等），禁止失败自动重试\n- **结构化 JSON 输出** — 所有命令输出标准化 JSON，适合 AI 代理解析\n\n## 仓库结构\n\n```text\nwecom-weisheng-scrm/\n├── SKILL.md                  # Skill 描述文件，供 openclaw 平台识别\n├── install.sh                # 安装/卸载脚本（symlink 到 ~/.openclaw/skills/）\n├── references/               # AI 代理执行参考文档\n│   ├── agent-runbook.md      # 代理执行手册（流程、权限、错误处理）\n│   ├── examples.md           # 用户查询示例与预期输出\n│   ├── file-utils.md         # 文件上传/下载说明\n│   └── guide.md              # 用户使用指南\n├── scripts/                  # Python CLI 实现\n│   ├── scrm.py               # 主入口，命令分发\n│   ├── api_client.py         # HTTP 客户端（GET/POST/multipart）\n│   ├── claw_client.py        # Claw 模块客户端（API 目录 + 代理转发）\n│   ├── environment.py        # 环境检查（Python >= 3.9、APP_KEY）\n│   ├── file_utils.py         # 图片上传/下载工具\n│   ├── get_access_token.py   # Token 管理（获取 + 缓存 + 刷新）\n│   ├── identity_manager.py   # 用户身份管理（角色检测 + 缓存）\n│   ├── raw_fetcher.py        # 受控远程文档读取（域名白名单）\n│   ├── chat_mode.py          # 会话存档模式管理（key/zone）\n│   └── utils.py              # 公共工具（异常、日志、JSON 输出、时间处理）\n├── .cache/                   # 运行时缓存（Token、API 目录、身份信息）\n├── logs/                     # 运行日志\n└── README.md\n```\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n./install.sh install     # 创建 symlink 到 ~/.openclaw/skills/wecom-weisheng-scrm\n./install.sh uninstall   # 移除 symlink\n```\n\n### 2. 配置环境变量\n\n| 变量 | 必填 | 说明 |\n|------|------|------|\n| `SCRM_APP_KEY` | 是 | 企微管家个人访问令牌。获取路径：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY |\n| `SCRM_BASE_URL` | 否 | 覆盖默认地址（默认 `https://open.wshoto.com`） |\n| `SCRM_SKIP_SSL_VERIFY` | 否 | 设为 `1` 跳过 SSL 验证（内网环境使用） |\n| `SCRM_MEDIA_CATEGORY_ID` | 否 | 素材上传分类 ID |\n\n### 3. 检查运行环境\n\n```bash\npython3 scripts/scrm.py check-env\n```\n\n### 4. 设置凭证\n\n```bash\npython3 scripts/scrm.py set-app-key \"your_personal_access_token\"\n```\n\n### 5. 获取当前身份\n\n```bash\npython3 scripts/scrm.py check-identity\n```\n\n返回用户角色：超管（`super_user=1`）、分管（`super_user=2`）、普通员工（`super_user=0 或 3`）。\n\n## 命令说明\n\n| 命令 | 说明 |\n|------|------|\n| `check-env` | 检查运行环境（Python 版本、APP_KEY 配置） |\n| `set-app-key <key>` | 持久化写入 APP KEY 到 Shell 配置文件 |\n| `check-identity` | 获取当前用户身份与角色 |\n| `list-apis --keyword <关键词>` | 按关键词搜索 API 目录（逗号分隔多关键词） |\n| `call-api --service-name <服务名> --uri <路径> --biz-params <JSON>` | 通过通用代理调用业务接口 |\n| `fetch-raw-doc --url <文档URL>` | 获取远程接口文档原始内容（仅限 `open.wshoto.com` 域名） |\n| `upload-image --path <本地路径>` | 上传本地图片，返回公开 URL 和 file_id |\n| `set-chat-mode --mode <key\\|zone>` | 设置会话存档模式 |\n\n### 使用示例\n\n**搜索接口：**\n\n```bash\npython3 scripts/scrm.py list-apis --keyword \"客户,标签,群发\"\n```\n\n**调用接口：**\n\n```bash\npython3 scripts/scrm.py call-api \\\n  --service-name \"wshoto-basebiz-service\" \\\n  --uri \"/bff/crm/private/h5/customer/list\" \\\n  --biz-params '{\"currentIndex\":1,\"pageSize\":10}'\n```\n\n**获取文档：**\n\n```bash\npython3 scripts/scrm.py fetch-raw-doc \\\n  --url \"https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md\"\n```\n\n**上传图片：**\n\n```bash\npython3 scripts/scrm.py upload-image --path ./poster.png\n```\n\n## 工作机制\n\n```\n用户提问\n  ↓\ncheck-env → 校验环境\n  ↓\ncheck-identity → 确定用户角色\n  ↓\nfetch-raw-doc → 拉取远程接口目录\n  ↓\nlist-apis → 关键词搜索匹配接口\n  ↓\nfetch-raw-doc → 阅读对应接口文档\n  ↓\ncall-api → 通过代理转发调用业务接口\n  ↓\n结构化 JSON 返回结果\n```\n\n关键约束：\n\n- 每次会话首次触发时必须通过 `fetch-raw-doc` 获取远程接口目录原始内容，再按关键词搜索匹配接口\n- 普通员工（`super_user=0/3`）仅可查看个人数据，无法查询团队数据或搜索组织架构\n- 写操作（新增、创建、删除、发送等）失败后禁止自动重试，防止重复操作\n- 本地图片类输入需先通过 `upload-image` 上传，再将返回的 URL 用于后续业务接口\n- 读取接口文档必须使用 `fetch-raw-doc` 命令（受域名白名单约束），不可使用其他工具替代\n\n## 缓存策略\n\n| 缓存文件 | 内容 | TTL |\n|----------|------|-----|\n| `.cache/access_token.json` | OAuth Token + user_id + 过期时间 | Token 有效期 - 5 分钟 |\n| `.cache/api_list.json` | 完整 API 目录（约 44KB） | 2 小时 |\n| `.cache/identity.json` | 用户角色信息 | 2 小时 |\n\n## 技术栈\n\n| 组件 | 技术 |\n|------|------|\n| 语言 | Python 3.9+（零外部依赖） |\n| HTTP 客户端 | `urllib.request`（标准库） |\n| CLI 框架 | `argparse`（标准库） |\n| 数据格式 | JSON |\n| 日志 | `logging` 模块，输出到 `logs/scrm.log` |\n| 目标平台 | 微盛企微管家开放平台 |\n| 部署方式 | symlink 到 `~/.openclaw/skills/` |\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn76jhdedxj61v2z5cpzgjt8r985c44f\",\n  \"slug\": \"wecom-weisheng-scrm\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1776935175728\n}\n\nFile v1.0.3:references/agent-runbook.md\n\n# AI 执行手册\n\n本文件供 AI 在执行本 Skill 时使用，不面向普通用户解释内部接口细节。\n\n## 用户沟通口径\n\n对普通用户回复时，默认使用业务语言和结果导向表达，不要主动使用过多技术术语。\n\n1. **默认不用技术词堆砌**：除非用户主动追问，否则不要直接说 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、接口编排、代理调用等术语。\n2. **先说能帮用户做什么**：优先说\"我先帮你看看\"\"我先帮你查一下\"\"我来帮你整理\"这类表达，再说明还需要用户补充什么。\n3. **权限提示说人话**：不要直接对用户说 TEAM、MINE、super_user；改为\"你当前可以看团队数据\"或\"你当前只能看自己的数据\"。\n4. **配置提示说人话**：不要只说\"未配置 SCRM_APP_KEY\"；改为\"你这边还没有完成企微管家授权，需要先获取 APP KEY 后我才能继续帮你查\"。\n5. **参数收集说业务信息**：不要说\"请提供 biz_params\"；改为\"还需要补充时间范围、客户名称、标签、员工等信息\"。\n6. **反馈结果先讲结论**：查询成功时先总结查到了什么；失败时先说发生了什么和下一步怎么办，不先抛错误码。\n7. **用户看不懂的内部信息不主动暴露**：接口路径、服务名、文档地址、原始返回结构，仅在用户明确要求查看时再展示。\n8. **读取接口目录时统一使用仓库内的受控原文读取命令**：应直接获取目标地址的原始内容，统一执行 `python3 scripts/scrm.py fetch-raw-doc --url <目标地址>`；不要先做网页搜索，不要先打开站点首页，也不要仅基于摘要页或搜索结果推断接口。\n9. **不要回退到 `web_fetch` 或其他网页抓取方式**：open.wshoto.com 文档读取统一走仓库内脚本命令，不使用网页正文抽取，不依赖首页跳转或搜索结果。\n\n### 推荐话术示例\n\n- 查询前：我先帮你看一下。\n- 继续追问信息时：还需要你补充一下时间范围 / 客户名称 / 标签信息，我再继续帮你查。\n- APP KEY 未配置时：你这边还没有完成企微管家授权，先去企业微信-工作台-企微管家-我的-我的 APP KEY 获取后发给我，我再继续帮你处理。\n- 普通员工查团队数据时：你当前只能查看自己的数据，团队数据这边暂时查不了。\n- 查询失败时：这次没有查成功，我把原因和下一步怎么处理跟你说一下。\n\n## 脚本位置\n\n脚本位于 SKILL.md 所在目录下的 `scripts/scrm.py`。AI 读取本文件时已知其路径，因此直接基于 SKILL.md 的目录拼接即可。\n\n## 环境检测\n\n触发 Skill 后，AI 应先检查当前是否具备脚本执行能力，以便运行仓库内命令读取原始文档并完成后续流程。\n\n若用户当前处于 WorkBuddy 的 Ask 模式，且该模式下无法执行命令或脚本，应直接提示用户切换到 Craft（或其他具备命令执行能力的模式）后再继续；不要在明知当前模式无法执行命令时继续后续接口流程。\n\n- **如果具备** → 正常继续后续调用流程。\n- **如果不具备** → 引导用户切换到可执行脚本的模式或补齐命令执行能力，完成前不要继续后续流程。\n\n处理原则：\n\n- 缺少脚本执行能力时，先解决环境问题，再继续接口目录读取和后续 API 流程。\n- 若已确认问题来自 WorkBuddy 的 Ask 模式限制，优先明确提示用户切换到 Craft（或其他具备所需能力的模式），不要只笼统提示\"稍后再试\"。\n- 不要在缺少原文读取能力的情况下，直接把接口目录读取降级成普通网页搜索或首页浏览。\n- 如果用户尚未完成重启，不要假装后续命令已经执行成功。\n\n## 调用流程\n\nAI 按以下编排流程执行：\n\n1. **执行环境检测** → 先确认当前是否具备脚本执行能力；若不具备，则按\"环境检测\"章节优先引导用户切换到可用模式或补齐必要能力，完成前不要继续后续流程\n   - 若已知用户当前在 Ask 模式且无法执行命令，先明确提示其切换到 Craft（或其他具备所需能力的模式）\n2. **执行 check-env** → 检查运行环境（Python ≥3.9、SCRM_APP_KEY）；`check-env` 内部会自动尝试从 shell profile 或 Windows 注册表中恢复已持久化的 APP_KEY\n   - 成功且返回中包含 `export_hint` → 说明 APP_KEY 是从持久化配置中恢复的，**立即执行返回的 `export_hint` 命令**（如 `export SCRM_APP_KEY='xxx'`）使当前 shell 会话生效，然后继续\n   - 成功且无 `export_hint` → APP_KEY 已在环境变量中，直接继续\n   - 失败（`config_error`）→ 引导用户获取 APP KEY 并执行 `set-app-key`，成功后执行 `export SCRM_APP_KEY='<值>'`，然后继续\n   - 若用户主动要求更换或更新 APP KEY（即使当前已配置），同样执行 `set-app-key` 用新值覆盖、export 后再继续\n3. **执行 check-identity** → 获取用户身份（超管/分管/员工）\n4. **阅读远程接口目录（强制步骤，不得跳过）** → 必须先读取 [CLAW_SUMMARY.md](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md) 的原始内容，再根据用户意图匹配目标接口；每次会话首次触发 Skill 时必须执行此步骤，不得凭已有认知直接跳到 list-apis。执行时统一使用仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url <url>`\n5. **执行 list-apis** → 用接口名称关键词匹配调用规则（service_name、api_path、doc_url）\n6. **阅读接口文档（doc_url）** → 阅读该文档获取完整参数定义，强制步骤，不得跳过\n7. **通过对话收集 biz_params** → 基于 doc_url 文档中的参数说明收集必要参数，不得仅凭 description 推断\n8. **执行 call-api** → 将 list-apis 返回的 service_name、api_path 及收集到的 biz_params 组装后通过通用代理调用\n\n### 接口目录与文档读取要求\n\n- 读取接口目录时，目标是拿到原始响应内容，而不是做网页正文抽取。\n- 统一执行仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md`。\n- 该命令内置超时、域名白名单和响应大小限制，比 `web_fetch` 更稳定，也更容易通过安全审查。\n- 读取 doc_url 对应在线文档时，也统一执行 `python3 scripts/scrm.py fetch-raw-doc --url <doc_url>`。\n- 不要退化为首页浏览、搜索摘要或人工猜测。\n\n> **⚠️ 文档内容截断处理：** 工具展示 stdout 时可能截断长文本，但数据本身未丢失。**必须通过管道解析完整 content**，不要直接读 stdout，否则会遗漏参数（如跟进记录接口的 `menu`、`searchField/searchValue` 曾因此被忽略）。\n>\n> ```bash\n> python3 scripts/scrm.py fetch-raw-doc --url <url> | python3 -c \"\n> import sys, json; data = json.load(sys.stdin); print(data['data']['content'])\n> \"\n> ```\n\n### 接口匹配规则\n\n1. 阅读远程接口目录后，根据用户意图匹配接口名称和使用说明\n2. 匹配到唯一接口时直接使用，无需询问用户\n3. 匹配到多个候选接口时，列出候选项让用户选择\n4. 无法匹配时，告知用户当前无匹配接口\n\n### 接口间数据依赖\n\ndoc_url 文档中的「业务参数数据来源说明」章节描述了每个参数的值从哪里获取。AI 组装 `biz_params` 时，**必须先识别依赖关系，按正确顺序调用前置接口获取参数值**，不能跳过或猜测。\n\n**参数来源识别：**\n\n| 来源描述关键词 | AI 行为 |\n|----------------|---------|\n| 「前端XX选择器」「前端输入框」 | 通过对话向用户收集 |\n| 「XX接口返回数据中的 `field` 字段」 | **必须先调用前置接口获取**，再用返回值填充 |\n| 「预设枚举值」 | 根据用户意图从固定选项中匹配 |\n| 「用户选择/用户输入」 | 通过对话收集，可能需要先列出选项 |\n\n**处理原则：**\n1. 每次调用接口前，先阅读 doc_url 的「业务参数数据来源说明」，确认是否有参数依赖其他接口\n2. 对于来源为其他接口的字段（如 tagId、userId、deptId），绝不能凭用户输入的名称自行构造，必须通过前置接口查询获取真实值\n3. 前置接口返回多条匹配记录时，列出选项让用户确认\n4. 同一会话内已获取的数据可复用，无需重复调用\n\n**典型场景 — 按标签名查客户：**\n\n用户说\"查一下有多少客户打了高意向客户标签\"，正确做法：\n1. `list-apis --keyword \"客户列表\"` → 找到「客户列表分页查询」\n2. 阅读 doc_url → 发现 `tagIds` 参数依赖「获取客户标签列表」接口\n3. `list-apis --keyword \"标签\"` → 找到「获取客户标签列表」，用 `keyValue=\"高意向客户\"` 搜索\n4. 从返回结果中匹配 `tagName`，提取对应 `tagId`（多个同名标签时列出让用户选择）\n5. 将 `tagId` 填入 `tagIds` 参数，调用客户列表接口\n\n> **错误做法**：直接猜测或构造 tagId 去查询。\n\n## 命令参考\n\n所有命令统一以如下格式执行，参数通过对话收集，不依赖 stdin 交互：\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" <command> [--param value ...]\n```\n\n> **首次调用某个命令前，必须先执行 `<command> --help` 确认参数名称和格式，不得凭猜测传参。**\n> **所有参数必须使用 `--param-name` 连字符格式，禁止使用下划线格式。**\n\n### check-env — 环境检查\n\n触发 Skill 时**立即**执行，失败则终止。检查项：Python ≥3.9、`SCRM_APP_KEY` 是否已配置。\n\n```bash\npython3 \"$SCRM_SCRIPT\" check-env\n```\n\n### check-env — 环境检查（含 APP_KEY 自动恢复）\n\n触发 Skill 时**立即**执行，失败则终止。检查项：Python ≥3.9、`SCRM_APP_KEY` 是否已配置。\n\n当 `SCRM_APP_KEY` 环境变量为空时，`check-env` 会自动尝试从 shell profile（Unix/macOS）或注册表（Windows）中读取之前通过 `set-app-key` 持久化的值。如果恢复成功，返回结果中会包含 `export_hint` 字段。\n\n```bash\npython3 \"$SCRM_SCRIPT\" check-env\n```\n\n**成功（APP_KEY 已在环境变量中）：**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"checks\": {\n      \"python_version\": {\"ok\": true, \"detail\": \"3.13.3\"},\n      \"app_key\": {\"ok\": true, \"detail\": \"已配置\"}\n    }\n  }\n}\n```\n\n**成功（APP_KEY 从持久化配置中恢复）：**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"checks\": {\n      \"app_key\": {\"ok\": true, \"detail\": \"从持久化配置中恢复（profile）\"}\n    },\n    \"app_key_restored\": {\"source\": \"profile\", \"profile\": \"/Users/xxx/.zshrc\", \"app_key\": \"xxx\"},\n    \"export_hint\": \"export SCRM_APP_KEY='xxx'\"\n  }\n}\n```\n\nAI 处理逻辑：\n- 成功且包含 `export_hint` → **立即执行返回的 `export_hint` 命令**使当前 shell 会话生效，然后继续\n- 成功且无 `export_hint` → 直接继续\n- 失败（`config_error`）→ 引导用户执行 `set-app-key`\n\n**失败：**\n\n```json\n{\n  \"success\": false,\n  \"error\": \"config_error\",\n  \"details\": {\n    \"checks\": {\n      \"app_key\": {\"ok\": false, \"detail\": \"未配置 SCRM_APP_KEY\"}\n    }\n  }\n}\n```\n\n### set-app-key — 设置 APP_KEY\n\n`SCRM_APP_KEY` 未配置时：先询问用户是否已有，若无则引导前往企微管家移动端「我的 → 我的 APP KEY」获取。用户提供后执行：\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" set-app-key \"<用户提供的APP_KEY>\"\n```\n\n成功后：\n1. 立即执行 `export SCRM_APP_KEY='<用户提供的APP_KEY>'`（Unix/macOS）使变量在当前 shell 会话中立即生效；Windows 平台跳过此步骤\n2. 将返回结果中的 `note` 告知用户一次\n3. 直接继续原始请求，不再追问用户是否已重启终端\n\n> ⚠️ **必须执行 `export` 步骤**：`set-app-key` 写入 shell profile 后，当前会话不会自动加载新变量，不执行 `export` 则后续命令（如 `check-env`、`check-identity`）在当前会话内仍读不到 `SCRM_APP_KEY`，导致每次新会话都重复追问用户。\n\n### check-identity — 获取用户身份\n\n无额外参数，自动使用缓存的 user_id。\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" check-identity\n```\n\n返回示例：\n\n```json\n{\n  \"success\": true,\n  \"action\": \"check-identity\",\n  \"data\": {\n    \"user_id\": \"xxx\",\n    \"user_name\": \"张三\",\n    \"super_user\": 1,\n    \"role_description\": \"超级管理员\"\n  }\n}\n```\n\n### set-chat-mode — 设置会话存档模式\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" set-chat-mode --mode <key|zone>\n```\n\n设置一次后永久生效。若用户在对话中明确告知模式，立即执行保存后继续查询；若从未设置且用户未提及，则询问。\n\n### list-apis — 接口仓库查询\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" list-apis --keyword \"关键词1,关键词2\"\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--keyword` | (必填) 多个关键词逗号分隔，模糊匹配 api_name |\n\n返回字段：\n\n| 字段 | 说明 | 用途 |\n|------|------|------|\n| `api_name` | 接口名称 | 确认匹配结果 |\n| `description` | 接口简要描述 | 辅助理解用途，**不含完整参数定义** |\n| `api_path` | 接口 URI | 作为 `call-api --uri` 的值 |\n| `service_name` | 下游微服务名 | 作为 `call-api --service-name` 的值 |\n| `doc_url` | 接口文档地址 | **必读**，获取完整参数定义 |\n\n### call-api — 通用代理调用\n\n```bash\nSCRM_NON_INTERACTIVE=1 python3 \"$SCRM_SCRIPT\" call-api \\\n  --service-name \"wshoto-basebiz-service\" \\\n  --uri \"/bff/bizCustomer/private/h5/chat/pageQuery\" \\\n  --biz-params '{\"currentIndex\":1,\"pageSize\":10}'\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--service-name` | (必填) 取自 list-apis 返回的 `service_name` |\n| `--uri` | (必填) 取自 list-apis 返回的 `api_path`（注意：字段名是 `api_path`，参数名是 `--uri`） |\n| `--method` | (可选) HTTP 方法，默认 POST |\n| `--biz-params` | (必填) 业务参数 JSON，参数名和类型以 doc_url 文档为准 |\n\n> **字段映射（易混淆）：** `list-apis.service_name` → `--service-name`；`list-apis.api_path` → `--uri`；`list-apis.doc_url` → 阅读后收集 `--biz-params`。\n\n### 参数收集标注含义\n\ndoc_url 文档中的参数标注，AI 必须严格按对应行为执行：\n\n| 标注 | AI 行为 |\n|------|---------|\n| **必须对话收集** | 执行前通过对话明确获取，不得自行推断 |\n| **展示选项让用户选择** | 列出所有选项含默认推荐，等用户选择 |\n| **展示默认值后确认** | 告知默认值，询问是否修改 |\n| 默认：`xxx` | 展示默认值，用户无需主动回复 |\n| 可选 | 用户未提及时跳过 |\n\n## 身份与权限\n\n不同业务接口用于区分团队/个人数据范围的参数名不统一，AI 必须通过阅读 doc_url 文档确认具体字段名。\n\n| check-identity 角色 | 数据范围 | 参数取值 |\n|---------------------|----------|----------|\n| 超管(super_user=1) / 分管(super_user=2) | 团队数据 | 团队对应的枚举值（如 TEAM） |\n| 普通员工(super_user=0或3) | 仅个人数据 | 个人对应的枚举值（如 MINE） |\n\nAI 应根据 check-identity 结果，在 biz_params 中自动填入对应值。当用户未明确指定视角范围时：超管/分管默认使用团队视角，普通员工默认使用个人视角。\n\n### 普通员工视角限制\n\n即使用户主动要求查询团队数据，普通员工也必须使用个人视角，不得使用团队视角。应告知用户\"您的身份是普通员工，只能查看个人数据，无法查看团队数据\"。\n\n### 员工操作限制\n\n当 check-identity 返回 `super_user` 为 `0` 或 `3` 时，当前用户为普通员工，AI 必须严格执行以下限制：\n\n#### 限制一：禁止指定其他员工\n\n普通员工只能操作自己的数据，不能将接口参数中的员工相关字段指定为其他员工。\n\n强制检查流程：\n\n1. 查看 check-identity 返回的 `user_id` 和 `user_name`\n2. 检查 biz_params 中是否包含员工名称、员工ID相关参数（如 `userIds`、`addUserIds`、`staffId` 等）\n3. 如果包含，此类参数必须且只能是 check-identity 返回的 `user_id` 或 `user_name`\n4. 如果用户要求使用其他员工，必须拒绝执行并告知\"您的身份是普通员工，只能操作自己的数据（{user_name}），无法指定其他员工\"\n\n示例：用户说\"创建活码，使用员工=芳芳\"，但 check-identity 返回 user_name=吴浩 → 芳芳≠吴浩，拒绝执行。\n\n#### 限制二：禁止调用员工/部门搜索接口\n\n普通员工无权搜索企业组织架构。员工&部门分类下的搜索接口，以及任何用于获取员工列表、部门列表、组织架构树的接口，普通员工都不得调用。\n\n## 错误处理\n\n| error 类型 | AI 处理方式 |\n|------------|-------------|\n| `config_error` | 用普通用户能理解的话说明还缺什么配置，并引导下一步，不直接抛技术细节 |\n| `validation_error` | 说明还缺哪些业务信息或填写有误，引导用户补充后重试 |\n| `scrm_error` | 用业务语言转述失败原因，并询问用户是否要调整条件后再试 |\n| `json_error` | 内部自行修正，不把 JSON 解析细节暴露给用户 |\n| `unexpected_error` | 告知用户这次没处理成功，建议稍后重试或联系管理员，不直接输出技术报错 |\n\n仅 `scrm_error` 且用户主动要求时才重试；其他类型错误优先修复根因。\n\n### 写操作重试限制\n\n写操作接口执行失败或超时后，禁止自动重试。写操作失败可能是服务端已成功执行但响应超时，自动重试会导致重复创建数据。\n\n具体规则：\n\n1. `call-api` 的输出中包含 `write_operation` 字段，`true` 表示写操作，`false` 表示读操作\n2. 写操作失败或超时时，AI 必须告知用户失败结果，由用户决定是否重试，AI 不得自行重新执行 `call-api`\n3. 读操作不受此限制，AI 可以在合理范围内重试\n\n## 行为规范\n\n以下规则优先级最高，始终遵守：\n\n1. 触发 Skill 时立即执行 `check-env`，在收集任何参数前完成；失败则告知用户并终止，不得继续\n2. 若 `SCRM_APP_KEY` 未配置，先询问用户是否已有 APP_KEY；若没有，则引导前往企业微信-工作台-企微管家应用-我的-我的 APP KEY 获取\n3. 写操作确认，读操作直接执行：查询类接口直接执行；写操作接口必须等待用户最终确认后再执行\n4. 参数收集通过对话完成，不依赖脚本 stdin 交互；执行时统一携带 `SCRM_NON_INTERACTIVE=1`\n5. 用户身份由 `SCRM_APP_KEY` 静默获取，禁止通过命令行参数传入\n6. 所有输出统一为 JSON，便于上层 Skill 编排解析\n7. 首次调用某个命令前，必须先执行 `<command> --help` 确认参数名称和格式，不得凭猜测传参\n8. 面向普通用户回复时，优先使用业务口径：先说能帮用户做什么、查到了什么、还缺什么信息，不主动输出底层接口与参数细节\n9. 涉及接口目录的读取动作一律走受控原文直读：读取 [CLAW_SUMMARY.md](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md) 时，统一使用 `python3 scripts/scrm.py fetch-raw-doc --url <url>`。若当前环境缺少该能力，先修复环境并提示用户切换模式或完成必要配置，再继续，不要直接降级为网页搜索、首页访问或 `web_fetch`\n\n## 文件上传与下载\n\n涉及图片/文件操作时，参考 [file-utils.md](file-utils.md)。\n\nFile v1.0.3:references/examples.md\n\n# 示例\n\n## 示例 1\n\n输入：帮我查一下最近新增客户和重点跟进客户的情况。\n\n输出：返回客户增长情况、重点客户和待跟进事项的汇总信息。\n\n## 示例 2\n\n输入：帮我看看这个客户的标签、跟进记录。\n\n输出：返回客户相关信息，并提示当前还需要补充的业务条件。\n\n## 示例 3\n\n输入：帮我创建我的员工活码。\n\n输出：创建员工活码，返回员工活码创建信息。\n\n## 示例 4\n\n输入：帮我看一下最近活码和素材相关情况。\n\n输出：返回活码和素材相关信息，并说明后续可继续处理的方向。\n\nFile v1.0.3:references/file-utils.md\n\n# 文件上传与下载\n\n`scripts/file_utils.py` 提供本地图片上传与远程文件下载能力，解决本地图片转为公网 URL 的问题。\n\n## 使用场景\n\n创建海报素材、个人活码等操作需要图片 URL。当用户提供本地文件路径时，需自动上传转换为公网地址。上传返回的 `file_id` 可用于后续创建素材等写操作。\n\n## 函数参考\n\n### ensure_public_image_url（推荐入口）\n\n自动判断图片来源并处理，仅需要 URL 时使用。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `source` | `str` | 是 | 远程 URL 或本地文件路径 |\n| `client` | `SCRMClient` | 否 | 本地图片上传时必填 |\n\n- 远程 URL → 直接返回原 URL\n- 本地路径 → 上传后返回公网地址\n\n```python\nurl = ensure_public_image_url(\"https://example.com/img.png\", client=client)\nurl = ensure_public_image_url(\"/Users/me/photo.png\", client=client)\n```\n\n### upload_image\n\n需要同时获取 `url` 和 `file_id` 时使用（如创建素材场景）。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `path` | `Path` | 是 | 本地图片文件路径 |\n| `client` | `SCRMClient` | 是 | SCRM 客户端实例 |\n\n返回 `dict`：`{\"url\": \"https://...\", \"file_id\": 12345}`\n\n### download_file\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | 远程文件地址 |\n| `target_dir` | `Path` | 否 | 下载目标目录 |\n| `filename` | `str` | 否 | 保存文件名，默认自动生成 |\n\n返回 `Path`（下载后的本地文件路径）。\n\n### is_remote_url\n\n判断字符串是否为公网 URL，返回 `bool`。\n\n## 异常类型\n\n| 异常类 | 触发场景 |\n|--------|---------|\n| `DownloadError` | 下载地址非法、网络请求失败 |\n| `UploadError` | 本地文件不存在、上传失败、响应中无法提取 URL 或 file_id |\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `SCRM_SKIP_SSL_VERIFY` | 设为 `1`/`true`/`yes` 跳过 SSL 验证，适用于内网环境 |\n\nFile v1.0.3:references/guide.md\n\n# 微盛企微管家SCRM 使用参考\n\n本 Skill 适用于企业微信客户运营与管理场景，可用于查询或管理客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、产品库、日程等相关能力。\n\n如需人工协助，可扫码联系专属客服：<https://pubres.wshbe.com/qrcode/20260416-53d7fee83fd04dbab3101546559490a6.png>\n\n建议使用流程：\n\n1. 先确认已完成企微管家授权并配置 APP KEY。\n2. 如当前在 WorkBuddy 的 Ask 模式且无法执行命令，请先切换到 Craft（或其他具备命令执行能力的模式）。\n3. 根据要处理的业务场景提出问题，例如客户查询、群发查看、活码查看、素材处理等。\n4. 如需更多条件，按提示补充客户名称、时间范围、标签、员工等业务信息。\n5. 查询结果优先查看结论；写操作需在确认后再执行。\n\n补充约束：\n\n- 读取接口目录时，必须直接获取目标地址的原始内容，并统一使用 `python3 scripts/scrm.py fetch-raw-doc --url <url>`。\n- 不要使用 `web_fetch` 或其他网页抓取方式读取 open.wshoto.com 文档。\n- 不要仅基于首页、搜索结果或网页摘要推断接口。\n\n常见场景包括：\n\n- 查询客户信息与客户标签\n- 查看客户群、群发和跟进记录\n- 查看会话存档与联系人情况\n- 处理活码、素材、商机、产品库和日程相关事项","readmeExcerpt":"Skill: 微盛企微管家SCRM Owner: fangfang19 Summary: 当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-06T08:15:13.771Z | user Version 1.0.4 - 移除了“联系支持”部分，将相关说明合并进“使用说明”。 - 更新了“处理原则”中关于不可执行操作模式的描述（去除了对 Craft 模式的限定）。 - 新增“安全与隐私”章节，明确 APP KEY 获取、保存及撤销方法，并声明本地安全策略。 - 其他文档结构优化，无功能变动","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"wecom-weisheng-scrm/\n├── SKILL.md                  # Skill 描述文件，供 openclaw 平台识别\n├── install.sh                # 安装/卸载脚本（symlink 到 ~/.openclaw/skills/）\n├── references/               # AI 代理执行参考文档\n│   ├── agent-runbook.md      # 代理执行手册（流程、权限、错误处理）\n│   ├── examples.md           # 用户查询示例与预期输出\n│   ├── file-utils.md         # 文件上传/下载说明\n│   └── guide.md              # 用户使用指南\n├── scripts/                  # Python CLI 实现\n│   ├── scrm.py               # 主入口，命令分发\n│   ├── api_client.py         # HTTP 客户端（GET/POST/multipart）\n│   ├── claw_client.py        # Claw 模块客户端（API 目录 + 代理转发）\n│   ├── environment.py        # 环境检查（Python >= 3.9、APP_KEY）\n│   ├── file_utils.py         # 图片上传/下载工具\n│   ├── get_access_token.py   # Token 管理（获取 + 缓存 + 刷新）\n│   ├── identity_manager.py   # 用户身份管理（角色检测 + 缓存）\n│   ├── raw_fetcher.py        # 受控远程文档读取（域名白名单）\n│   ├── chat_mode.py          # 会话存档模式管理（key/zone）\n│   └── utils.py              # 公共工具（异常、日志、JSON 输出、时间处理）\n├── .cache/                   # 运行时缓存（Token、API 目录、身份信息）\n├── logs/                     # 运行日志\n└── README.md"},{"language":"bash","snippet":"./install.sh install     # 创建 symlink 到 ~/.openclaw/skills/wecom-weisheng-scrm\n./install.sh uninstall   # 移除 symlink"},{"language":"bash","snippet":"python3 scripts/scrm.py check-env"},{"language":"bash","snippet":"python3 scripts/scrm.py set-app-key \"your_personal_access_token\""},{"language":"bash","snippet":"python3 scripts/scrm.py check-identity"},{"language":"bash","snippet":"python3 scripts/scrm.py list-apis --keyword \"客户,标签,群发\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: wecom-weisheng-scrm\ndescription: \"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。\"\ndescription_zh: \"微盛AI·企微管家提供的技能，帮助用户查询和管理企业微信 SCRM 中的客户、客户群、标签、活码、群发、跟进、聊天记录内容等业务数据，可询问AI当前支持的能力清单。\"\ndescription_en: \"Built for WeCom customer operations, helping teams review customer and group activity, prepare campaign assets, and move follow-up, messaging, and opportunity workflows forward.\"\nversion: 1.0.3\n---\n\n# 微盛企微管家SCRM\n\n微盛企微管家 SCRM 面向企业微信客户运营场景，帮助团队围绕客户、社群、素材、活码、群发、会话与商机等业务，更高效地完成查询、协同与执行。\n\n本 Skill 适用于客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、产品库、汇报、抽奖、日程等场景。你可以直接用业务语言提出问题，例如“帮我查最近7天新添加的客户”“看看某个客户的标签和跟进情况”“帮我查客户群或群发情况”。\n\n\n## 使用说明\n\n触发 Skill 后，应先用简短话术向用户说明：微盛AI·企微管家 SCRM 是基于企业微信的 AI 聊天、营销和服务平台，可协助客户运营、社群营销、SCRM 与会话管理，本技能支持查询或管理客户信息、客户标签、客户群、素材、活码、群发、跟进记录、会话存档、联系人、商机、汇报、抽奖、客户日程等相关能力；如需进一步支持，可联系专属客服。\n\n**触发 Skill 后，必须先阅读 [references/agent-runbook.md](references/agent-runbook.md) 并严格按其中的调用流程执行（包括 `check-env` → `check-identity` 的顺序），不得跳过或自行编排步骤。**\n\n### 推荐提问方式\n\n- 帮我查一下最近新增客户和重点跟进客户的情况。\n- 帮我看看这个客户的标签、跟进记录和聊天情况。\n- 帮我整理一下当前客户群和群发相关情况。\n- 帮我看一下最近活码和素材相关情况。\n\n### 处理原则\n\n- 默认使用业务语言回复用户，先说结论，再说明还缺什么信息或下一步怎么处理。\n- 如需补充条件，优先向用户追问时间范围、客户名称、标签、员工、群发范围等业务信息。\n- 查询类需求可直接处理；创建、编辑、删除、发送等写操作应在用户确认后再执行。\n- 若用户当前所在模式无法执行命令或脚本，应先提示切换到具备执行能力的模式。\n\n对普通用户回复时，不要主动暴露 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、代理调用等内部术语，除非用户明确要求查看。\n\n## 安全与隐私\n\n本 Skill 需要你的企微管家 APP KEY 授权。KEY 仅保存在本地设备（Shell 配置 / Windows 注册表），不会上传到 QClaw 服务器或任何第三方。\n\n- 获取：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY\n- 撤销：在企微管家后台重置 APP KEY，或执行 `python3 scripts/scrm.py set-app-key \"\"`\n\n## 文档索引\n\n| 文档 | 说明 |\n|------|------|\n| [references/guide.md](references/guide.md) | 使用参考与常见业务场景 |\n| [references/examples.md](references/examples.md) | 示例问题与使用示例 |\n| [references/agent-runbook.md](references/agent-runbook.md) | AI 执行手册（流程、命令参考、权限、错误处理、数据依赖） |\n| [references/file-utils.md](references/file-utils.md) | 文件上传与下载（本地图片转公网 URL） |"},{"path":"README.md","content":"# wecom-weisheng-scrm\n\n面向 AI 代理的微盛企微管家 SCRM Skill 插件，提供与微盛企微管家开放平台（`https://open.wshoto.com`）的集成能力。本仓库不包含业务逻辑实现，而是通过动态接口发现和通用代理调用机制，将 AI 代理与企微管家 SCRM 系统打通，覆盖客户管理、标签、群聊、素材、活码、群发、跟进记录、会话存档、商机、产品库、汇报、抽奖、日程等业务场景。\n\n## 特性\n\n- **零外部依赖** — 仅使用 Python 标准库，无需 `pip install`\n- **动态接口发现** — 通过 Claw 模块实时拉取开放平台 API 目录，支持关键词模糊搜索\n- **通用代理转发** — 统一通过 `/openapi/claw/proxy/forward` 代理调用所有业务接口\n- **角色权限感知** — 自动识别当前用户身份（超管/分管/普通员工），约束数据访问范围\n- **写操作保护** — 自动识别写操作（新增、创建、删除、发送等），禁止失败自动重试\n- **结构化 JSON 输出** — 所有命令输出标准化 JSON，适合 AI 代理解析\n\n## 仓库结构\n\n```text\nwecom-weisheng-scrm/\n├── SKILL.md                  # Skill 描述文件，供 openclaw 平台识别\n├── install.sh                # 安装/卸载脚本（symlink 到 ~/.openclaw/skills/）\n├── references/               # AI 代理执行参考文档\n│   ├── agent-runbook.md      # 代理执行手册（流程、权限、错误处理）\n│   ├── examples.md           # 用户查询示例与预期输出\n│   ├── file-utils.md         # 文件上传/下载说明\n│   └── guide.md              # 用户使用指南\n├── scripts/                  # Python CLI 实现\n│   ├── scrm.py               # 主入口，命令分发\n│   ├── api_client.py         # HTTP 客户端（GET/POST/multipart）\n│   ├── claw_client.py        # Claw 模块客户端（API 目录 + 代理转发）\n│   ├── environment.py        # 环境检查（Python >= 3.9、APP_KEY）\n│   ├── file_utils.py         # 图片上传/下载工具\n│   ├── get_access_token.py   # Token 管理（获取 + 缓存 + 刷新）\n│   ├── identity_manager.py   # 用户身份管理（角色检测 + 缓存）\n│   ├── raw_fetcher.py        # 受控远程文档读取（域名白名单）\n│   ├── chat_mode.py          # 会话存档模式管理（key/zone）\n│   └── utils.py              # 公共工具（异常、日志、JSON 输出、时间处理）\n├── .cache/                   # 运行时缓存（Token、API 目录、身份信息）\n├── logs/                     # 运行日志\n└── README.md\n```\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n./install.sh install     # 创建 symlink 到 ~/.openclaw/skills/wecom-weisheng-scrm\n./install.sh uninstall   # 移除 symlink\n```\n\n### 2. 配置环境变量\n\n| 变量 | 必填 | 说明 |\n|------|------|------|\n| `SCRM_APP_KEY` | 是 | 企微管家个人访问令牌。获取路径：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY |\n| `SCRM_BASE_URL` | 否 | 覆盖默认地址（默认 `https://open.wshoto.com`） |\n| `SCRM_SKIP_SSL_VERIFY` | 否 | 设为 `1` 跳过 SSL 验证（内网环境使用） |\n| `SCRM_MEDIA_CATEGORY_ID` | 否 | 素材上传分类 ID |\n\n### 3. 检查运行环境\n\n```bash\npython3 scripts/scrm.py check-env\n```\n\n### 4. 设置凭证\n\n```bash\npython3 scripts/scrm.py set-app-key \"your_personal_access_token\"\n```\n\n### 5. 获取当前身份\n\n```bash\npython3 scripts/scrm.py check-identity\n```\n\n返回用户角色：超管（`super_user=1`）、分管（`super_user=2`）、普通员工（`super_user=0 或 3`）。\n\n## 命令说明\n\n| 命令 | 说明 |\n|------|------|\n| `check-env` | 检查运行环境（Python 版本、APP_KEY 配置） |\n| `set-app-key <key>` | 持久化写入 APP KEY 到 Shell 配置文件 |\n| `check-identity` | 获取当前用户身份与角色 |\n| `list-apis --keyword <关键词>` | 按关键词搜索 API 目录（逗号分隔多关键词） |\n| `call-api --service-name <服务名> --uri <路径> --biz-params <JSON>` | 通过通用代理调用业务接口 |\n| `fetch-raw-doc --url <文档URL>` | 获取远程接口文档原始内容（仅限 `open.wshoto.com` 域名） |\n| `upload-image --path <本地路径>` | 上传本地图片，返回公开 URL 和 file_id |\n| `set-chat-mode --mode <key\\|zone>` | 设置会话存档模式 |\n\n### 使用示例\n\n**搜索接口：**\n\n```bash\npython3 scripts/scrm.py list-apis --keyword \"客户,标签,群发\"\n```\n\n**调用接口：**\n\n```bash\npython3 scripts/scrm.py call-api \\\n  --service-name \"wshoto-basebiz-s"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn76jhdedxj61v2z5cpzgjt8r985c44f\",\n  \"slug\": \"wecom-weisheng-scrm\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1778055313771\n}"},{"path":"references/agent-runbook.md","content":"# AI 执行手册\n\n本文件供 AI 在执行本 Skill 时使用，不面向普通用户解释内部接口细节。\n\n## 用户沟通口径\n\n对普通用户回复时，默认使用业务语言和结果导向表达，不要主动使用过多技术术语。\n\n1. **默认不用技术词堆砌**：除非用户主动追问，否则不要直接说 `service_name`、`api_path`、`doc_url`、`biz_params`、JSON、接口编排、代理调用等术语。\n2. **先说能帮用户做什么**：优先说\"我先帮你看看\"\"我先帮你查一下\"\"我来帮你整理\"这类表达，再说明还需要用户补充什么。\n3. **权限提示说人话**：不要直接对用户说 TEAM、MINE、super_user；改为\"你当前可以看团队数据\"或\"你当前只能看自己的数据\"。\n4. **配置提示说人话**：不要只说\"未配置 SCRM_APP_KEY\"；改为\"你这边还没有完成企微管家授权，需要先获取 APP KEY 后我才能继续帮你查\"。\n5. **参数收集说业务信息**：不要说\"请提供 biz_params\"；改为\"还需要补充时间范围、客户名称、标签、员工等信息\"。\n6. **反馈结果先讲结论**：查询成功时先总结查到了什么；失败时先说发生了什么和下一步怎么办，不先抛错误码。\n7. **用户看不懂的内部信息不主动暴露**：接口路径、服务名、文档地址、原始返回结构，仅在用户明确要求查看时再展示。\n8. **读取接口目录时统一使用仓库内的受控原文读取命令**：应直接获取目标地址的原始内容，统一执行 `python3 scripts/scrm.py fetch-raw-doc --url <目标地址>`；不要先做网页搜索，不要先打开站点首页，也不要仅基于摘要页或搜索结果推断接口。\n9. **不要回退到 `web_fetch` 或其他网页抓取方式**：open.wshoto.com 文档读取统一走仓库内脚本命令，不使用网页正文抽取，不依赖首页跳转或搜索结果。\n\n### 推荐话术示例\n\n- 查询前：我先帮你看一下。\n- 继续追问信息时：还需要你补充一下时间范围 / 客户名称 / 标签信息，我再继续帮你查。\n- APP KEY 未配置时：你这边还没有完成企微管家授权，先去企业微信-工作台-企微管家-我的-我的 APP KEY 获取后发给我，我再继续帮你处理。\n- 普通员工查团队数据时：你当前只能查看自己的数据，团队数据这边暂时查不了。\n- 查询失败时：这次没有查成功，我把原因和下一步怎么处理跟你说一下。\n\n## 脚本位置\n\n脚本位于 SKILL.md 所在目录下的 `scripts/scrm.py`。AI 读取本文件时已知其路径，因此直接基于 SKILL.md 的目录拼接即可。\n\n## 环境检测\n\n触发 Skill 后，AI 应先检查当前是否具备脚本执行能力，以便运行仓库内命令读取原始文档并完成后续流程。\n\n若用户当前所在模式不具备脚本执行能力，应直接提示用户切换到具备命令执行能力的模式后再继续；不要在明知当前模式无法执行命令时继续后续接口流程。\n\n- **如果具备** → 正常继续后续调用流程。\n- **如果不具备** → 引导用户切换到可执行脚本的模式或补齐命令执行能力，完成前不要继续后续流程。\n\n处理原则：\n\n- 缺少脚本执行能力时，先解决环境问题，再继续接口目录读取和后续 API 流程。\n- 若已确认问题来自当前模式的执行能力限制，优先明确提示用户切换到具备所需能力的模式，不要只笼统提示\"稍后再试\"。\n- 不要在缺少原文读取能力的情况下，直接把接口目录读取降级成普通网页搜索或首页浏览。\n- 如果用户尚未完成重启，不要假装后续命令已经执行成功。\n\n## 调用流程\n\nAI 按以下编排流程执行：\n\n1. **执行环境检测** → 先确认当前是否具备脚本执行能力；若不具备，则按\"环境检测\"章节优先引导用户切换到可用模式或补齐必要能力，完成前不要继续后续流程\n   - 若已知用户当前模式无法执行命令，先明确提示其切换到具备所需能力的模式\n2. **执行 check-env** → 检查运行环境（Python ≥3.9、SCRM_APP_KEY）；`check-env` 内部会自动尝试从 shell profile 或 Windows 注册表中恢复已持久化的 APP_KEY\n   - 成功且返回中包含 `export_hint` → 说明 APP_KEY 是从持久化配置中恢复的，**立即执行返回的 `export_hint` 命令**（如 `export SCRM_APP_KEY='xxx'`）使当前 shell 会话生效，然后继续\n   - 成功且无 `export_hint` → APP_KEY 已在环境变量中，直接继续\n   - 失败（`config_error`）→ 引导用户获取 APP KEY 并执行 `set-app-key`，成功后执行 `export SCRM_APP_KEY='<值>'`，然后继续\n   - 若用户主动要求更换或更新 APP KEY（即使当前已配置），同样执行 `set-app-key` 用新值覆盖、export 后再继续\n3. **执行 check-identity** → 获取用户身份（超管/分管/员工）\n4. **阅读远程接口目录（强制步骤，不得跳过）** → 必须先读取 [CLAW_SUMMARY.md](https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md) 的原始内容，再根据用户意图匹配目标接口；每次会话首次触发 Skill 时必须执行此步骤，不得凭已有认知直接跳到 list-apis。执行时统一使用仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url <url>`\n5. **执行 list-apis** → 用接口名称关键词匹配调用规则（service_name、api_path、doc_url）\n6. **阅读接口文档（doc_url）** → 阅读该文档获取完整参数定义，强制步骤，不得跳过\n7. **通过对话收集 biz_params** → 基于 doc_url 文档中的参数说明收集必要参数，不得仅凭 description 推断\n8. **执行 call-api** → 将 list-apis 返回的 service_name、api_path 及收集到的 biz_params 组装后通过通用代理调用\n\n### 接口目录与文档读取要求\n\n- 读取接口目录时，目标是拿到原始响应内容，而不是做网页正文抽取。\n- 统一执行仓库内命令 `python3 scripts/scrm.py fetch-raw-doc --url https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md`。\n- 该命令内置超时、域名白名单和响应大小限制，比 `web_fetch` 更稳定，也更容易通过安全审查。\n- 读取 doc_url 对应在线文档时，也统一执行 `python3 scripts/scrm.py fetch"},{"path":"references/examples.md","content":"# 示例\n\n## 示例 1\n\n输入：帮我查一下最近新增客户和重点跟进客户的情况。\n\n输出：返回客户增长情况、重点客户和待跟进事项的汇总信息。\n\n## 示例 2\n\n输入：帮我看看这个客户的标签、跟进记录。\n\n输出：返回客户相关信息，并提示当前还需要补充的业务条件。\n\n## 示例 3\n\n输入：帮我创建我的员工活码。\n\n输出：创建员工活码，返回员工活码创建信息。\n\n## 示例 4\n\n输入：帮我看一下最近活码和素材相关情况。\n\n输出：返回活码和素材相关信息，并说明后续可继续处理的方向。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Skill: 微盛企微管家SCRM Owner: fangfang19 Summary: 当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、联系人、商机、汇报、抽奖、客户日程等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。 Tags: latest:1.0.4 Version history: v1.0.4 | 2026-05-06T08:15:13.771Z | user Version 1.0.4 - 移除了“联系支持”部分，将相关说明合并进“使用说明”。 - 更新了“处理原则”中关于不可执行操作模式的描述（去除了对 Craft 模式的限定）。 - 新增“安全与隐私”章节，明确 APP KEY 获取、保存及撤销方法，并声明本地安全策略。 - 其他文档结构优化，无功能变动","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":710,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T13:54:21.192Z","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-11T13:54:21.192Z","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-11T16:06:46.034Z","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"}]}}}