@shulex/cxclawctl 0.1.2 → 0.1.4

package/skills/solvea-desk/scripts/tickets/ticket_tags.py

@@ -1,305 +0,0 @@
-#!/usr/bin/env python3
-"""Query and safely mutate Tars ticket tags."""
-
-import os
-import sys
-sys.path.insert(0, os.path.join(os.environ["SOLVEA_LIB_DIR"], "skill-runtime"))
-from bootstrap import SOLVEA_ENV  # noqa: E402,F401
-
-import argparse
-import json
-from pathlib import Path
-from typing import Any
-
-import httpx
-
-from desk_api import DeskApiConfig, request_json, resolve_desk_api_config
-
-
-TAG_LIST_PATH = "/api_v2/tars/api/tags/list"
-TICKET_TAGS_PATH = "/api_v2/tars/api/tags/ticket_tags"
-BATCH_TICKET_TAGS_PATH = "/api_v2/tars/api/tags/new/getTags"
-TAG_SEARCH_PATH = "/api_v2/tars/api/tags/new/find"
-BIND_TAGS_PATH = "/api_v2/tars/api/tags/manual/binding"
-UNBIND_TAGS_PATH = "/api_v2/tars/api/tags/manual/unbinding"
-
-
-class TagVerificationError(RuntimeError):
-    def __init__(
-        self,
-        *,
-        before: dict[str, Any],
-        requested: dict[str, Any],
-        after: dict[str, Any],
-        operation: str,
-    ) -> None:
-        super().__init__(f"{operation} tag verification failed")
-        self.evidence = {
-            "operation": operation,
-            "before": before,
-            "requested": requested,
-            "after": after,
-        }
-
-
-def list_tags(client: httpx.Client, config: DeskApiConfig) -> Any:
-    return request_json(client, config, "GET", TAG_LIST_PATH).get("data", [])
-
-
-def get_ticket_tags(
-    client: httpx.Client,
-    config: DeskApiConfig,
-    ticket_number: str,
-) -> dict[str, Any]:
-    normalized = ticket_number.strip()
-    if not normalized:
-        raise ValueError("ticket number cannot be empty")
-    data = request_json(
-        client,
-        config,
-        "GET",
-        TICKET_TAGS_PATH,
-        params={"ticketNum": normalized},
-    ).get("data", {})
-    if not isinstance(data, dict):
-        raise ValueError("ticket tag response data must be an object")
-    return data
-
-
-def batch_get_ticket_tags(
-    client: httpx.Client,
-    config: DeskApiConfig,
-    ticket_ids: list[int],
-) -> list[Any]:
-    if not ticket_ids or any(
-        isinstance(value, bool) or not isinstance(value, int) for value in ticket_ids
-    ):
-        raise ValueError("ticketIdList must be a non-empty integer list")
-    data = request_json(
-        client,
-        config,
-        "POST",
-        BATCH_TICKET_TAGS_PATH,
-        json_body={"ticketIdList": ticket_ids},
-    ).get("data", [])
-    if not isinstance(data, list):
-        raise ValueError("batch ticket tag response data must be a list")
-    return data
-
-
-def search_tags(
-    client: httpx.Client,
-    config: DeskApiConfig,
-    name: str,
-) -> list[Any]:
-    normalized = name.strip()
-    if not normalized:
-        raise ValueError("tag name cannot be empty")
-    data = request_json(
-        client,
-        config,
-        "GET",
-        TAG_SEARCH_PATH,
-        params={"tagName": normalized},
-    ).get("data", [])
-    if not isinstance(data, list):
-        raise ValueError("tag search response data must be a list")
-    return data
-
-
-def load_ticket_ids_file(path: str | Path) -> list[int]:
-    payload = json.loads(Path(path).read_text(encoding="utf-8"))
-    ticket_ids = payload.get("ticketIdList") if isinstance(payload, dict) else None
-    if not isinstance(ticket_ids, list) or not ticket_ids or any(
-        isinstance(value, bool) or not isinstance(value, int) for value in ticket_ids
-    ):
-        raise ValueError("ticketIdList must be a non-empty integer list")
-    return ticket_ids
-
-
-def load_tags_file(path: str | Path) -> list[dict[str, int | str]]:
-    payload = json.loads(Path(path).read_text(encoding="utf-8"))
-    tags = payload.get("tags") if isinstance(payload, dict) else None
-    return _normalize_tags(tags)
-
-
-def _normalize_tags(tags: Any) -> list[dict[str, int | str]]:
-    if not isinstance(tags, list) or not tags:
-        raise ValueError("tags must be a non-empty list")
-    normalized = []
-    for tag in tags:
-        if (
-            not isinstance(tag, dict)
-            or isinstance(tag.get("id"), bool)
-            or not isinstance(tag.get("id"), int)
-        ):
-            raise ValueError("each tag id must be an integer")
-        if not isinstance(tag.get("name"), str) or not tag["name"].strip():
-            raise ValueError("each tag name must be non-empty")
-        normalized.append({"id": tag["id"], "name": tag["name"].strip()})
-    return normalized
-
-
-def _user_tag_ids(tag_state: dict[str, Any]) -> set[int]:
-    values = tag_state.get("userTags", [])
-    if not isinstance(values, list):
-        return set()
-    result = set()
-    for tag in values:
-        if not isinstance(tag, dict) or isinstance(tag.get("id"), bool):
-            continue
-        try:
-            result.add(int(tag["id"]))
-        except (KeyError, TypeError, ValueError):
-            continue
-    return result
-
-
-def change_tags(
-    client: httpx.Client,
-    config: DeskApiConfig,
-    *,
-    operation: str,
-    ticket_number: str,
-    tags: list[dict[str, int | str]],
-    confirmed: bool,
-) -> dict[str, Any]:
-    if operation not in {"bind", "unbind"}:
-        raise ValueError("operation must be bind or unbind")
-    normalized_ticket_number = ticket_number.strip()
-    if not normalized_ticket_number:
-        raise ValueError("ticket number cannot be empty")
-    normalized_tags = _normalize_tags(tags)
-    before = get_ticket_tags(client, config, normalized_ticket_number)
-    requested = {"ticketNum": normalized_ticket_number, "tags": normalized_tags}
-    if not confirmed:
-        return {
-            "ok": False,
-            "status": "confirmation_required",
-            "operation": operation,
-            "before": before,
-            "requested": requested,
-        }
-
-    path = BIND_TAGS_PATH if operation == "bind" else UNBIND_TAGS_PATH
-    server_payload = request_json(client, config, "POST", path, json_body=requested)
-    after = get_ticket_tags(client, config, normalized_ticket_number)
-    requested_ids = {int(tag["id"]) for tag in normalized_tags}
-    after_user_ids = _user_tag_ids(after)
-    verified = (
-        requested_ids <= after_user_ids
-        if operation == "bind"
-        else requested_ids.isdisjoint(after_user_ids)
-    )
-    if not verified:
-        raise TagVerificationError(
-            before=before,
-            requested=requested,
-            after=after,
-            operation=operation,
-        )
-    return {
-        "ok": True,
-        "operation": operation,
-        "verified": True,
-        "before": before,
-        "requested": requested,
-        "after": after,
-        "server_result": server_payload.get("data"),
-    }
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Query and manage Shulex Desk ticket tags")
-    subparsers = parser.add_subparsers(dest="operation", required=True)
-    subparsers.add_parser("list-tags", help="Return the complete Tars tag tree")
-
-    get_parser = subparsers.add_parser("get-ticket-tags", help="Get one ticket's tags")
-    get_parser.add_argument("--ticket-number", required=True)
-
-    batch_parser = subparsers.add_parser(
-        "batch-get-ticket-tags", help="Get tags for internal ticket IDs"
-    )
-    batch_parser.add_argument("--ticket-ids-file", required=True)
-
-    search_parser = subparsers.add_parser("search-tags", help="Search tag paths by node name")
-    search_parser.add_argument("--name", required=True)
-
-    for operation in ("bind-tags", "unbind-tags"):
-        write_parser = subparsers.add_parser(
-            operation,
-            help="Bind tags to a ticket" if operation == "bind-tags" else "Unbind tags from a ticket",
-        )
-        write_parser.add_argument("--ticket-number", required=True)
-        write_parser.add_argument("--tags-file", required=True)
-        write_parser.add_argument(
-            "--confirm",
-            action="store_true",
-            help="Send the write request after the user explicitly confirms the preview",
-        )
-    return parser
-
-
-def main() -> int:
-    parser = build_parser()
-    args = parser.parse_args()
-    config = resolve_desk_api_config()
-    if not config.token:
-        print(json.dumps({
-            "ok": False,
-            "operation": args.operation,
-            "error": "desk_runtime_not_configured",
-            "message": "Check SOLVEA_ENV and the corresponding Solvea token environment variable.",
-        }, ensure_ascii=False, indent=2))
-        return 2
-
-    try:
-        with httpx.Client(timeout=60.0) as client:
-            if args.operation == "list-tags":
-                data = list_tags(client, config)
-            elif args.operation == "get-ticket-tags":
-                data = get_ticket_tags(client, config, args.ticket_number)
-            elif args.operation == "batch-get-ticket-tags":
-                data = batch_get_ticket_tags(
-                    client, config, load_ticket_ids_file(args.ticket_ids_file)
-                )
-            elif args.operation == "search-tags":
-                data = search_tags(client, config, args.name)
-            else:
-                data = change_tags(
-                    client,
-                    config,
-                    operation="bind" if args.operation == "bind-tags" else "unbind",
-                    ticket_number=args.ticket_number,
-                    tags=load_tags_file(args.tags_file),
-                    confirmed=args.confirm,
-                )
-    except TagVerificationError as exc:
-        print(json.dumps({
-            "ok": False,
-            "operation": args.operation,
-            "error": type(exc).__name__,
-            "message": str(exc),
-            **exc.evidence,
-        }, ensure_ascii=False, indent=2))
-        return 3
-    except (OSError, ValueError, RuntimeError, json.JSONDecodeError, httpx.HTTPError) as exc:
-        print(json.dumps({
-            "ok": False,
-            "operation": args.operation,
-            "error": type(exc).__name__,
-            "message": str(exc),
-        }, ensure_ascii=False, indent=2))
-        return 1
-
-    result = data if args.operation in {"bind-tags", "unbind-tags"} else {
-        "ok": True,
-        "operation": args.operation,
-        "data": data,
-    }
-    print(json.dumps(result, ensure_ascii=False, indent=2))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/skills/solvea-kit/SKILL.md

@@ -1,84 +0,0 @@
----
-name: solvea-kit
-description: Shulex 路由与运营配置工具包。用于意图、策略、变量系统、AI 质检和标签树的查询与管理；也负责将 Agent/工具/CHAT_FLOW/知识库/测试/数据分析等需求分流到对应 skill。
----
-
-# Solvea Kit
-
-Solvea Kit 保留路由与运营相关配置：意图、策略、变量系统、AI 质检和标签树。Agent、工具、CHAT_FLOW、测试、知识库和分析类需求按下方分流。
-
-## Solvea API CLI
-
-所有查询与写入操作，均使用 `/skill-lib/solvea-api/solvea_api.py`：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api <command> --pretty
-# 例如：
-npx --yes @shulex/cxclawctl@latest api list-agents --pretty
-```
-
-## 能力分流
-
-| 用户诉求 | 去哪里 |
-|---|---|
-| 通用意图分类实现（供 POC / Delivery 调用） | 本 skill：`scripts/intent_classify.py` |
-| 意图创建、查询、更新、启停 | 本 skill：`references/intent.md` |
-| 策略创建、查询、更新、启停、entity condition | 本 skill：`references/strategy.md` |
-| 变量系统字段查询、初始化、创建、更新、删除、启停 | 本 skill：`references/variables.md` |
-| AI 质检开关、规则、自定义规则、预警 | 本 skill：`references/quality-inspection.md` |
-| 标签树 / 标签组 / 标签节点 / 批量导入 | 本 skill：`references/tagging.md` |
-| SINGLE_AGENT / 语音 Agent / MULTI_AGENT / CHAT_FLOW / 工具配置 | `agent-builder` |
-| CHAT_FLOW 图构建、校验、迁移 | `agent-builder` |
-| 售前 POC 流程、POC 测试手册 | `poc` |
-| 正式交付流程、交付回归 | `delivery` |
-| 知识库内容、目录、QA、隔离关键词、回复模板库 | `kb-builder` |
-| badcase、异常回复、失败节点，或按 ChatId / External ID 定位会话 | `shulex-support`（优先级高于所有数据分析入口，进入 Agent 会话诊断场景） |
-| Agent 运营数据、指标、趋势、原始会话列表下钻（不要求解释异常根因） | `agent-analytics` |
-| Shulex Desk 工单查询、报表和标签操作 | `solvea-desk` |
-| 售后咨询、创建/查询/追加售后工单 | `shulex-support` |
-
-## 核心约束（必须遵守，不用查文档也要记住）
-
-1. **统一走 CLI** — 所有查询与写入都通过文档指定的 CLI；鉴权和调用目标由工程逻辑处理，agent 不读取、不切换、不解释底层配置。
-2. **先查后改** — 更新任何资源前必须先 get 或 list 确认现状
-3. **写入配置落 state** — 大 JSON 或待用户确认的配置写 `/workspace/state/solvea-kit/`，不要写 `/workspace/tmp/`
-4. **写入操作需确认** — 修改线上数据前必须与用户确认
-
-## 模块文档（按需读取）
-
-遇到具体问题时，用 `read_file` 读取对应模块文档：
-
-| 文档                                                    | 内容 | 何时读 |
-|-------------------------------------------------------|------|--------|
-| `/skills/solvea-kit/references/intent.md` | 意图管理 | 创建、更新、启用、禁用意图 |
-| `/skills/solvea-kit/references/strategy.md` | 策略管理 | 创建、更新、启用、禁用策略；查看 entity condition |
-| `/skills/solvea-kit/references/variables.md` | 变量系统管理 | 查询、初始化、创建、更新、删除、启停及使用边界 |
-| `/skills/solvea-kit/references/quality-inspection.md` | AI 质检管理 | 查看质检、管理规则/自定义规则/预警 |
-| `/skills/solvea-kit/references/tagging.md` | 标签树管理 | 标签组、标签节点、模板下载、批量导入 |
-
-## 目录结构
-
-```text
-solvea-kit/
-├── SKILL.md
-├── scripts/
-│   ├── generate_label_import_file.py  # 根据标签 JSON 生成标签树导入 xlsx
-│   └── intent_classify.py             # 通用意图分类实现，POC/Delivery 通过 wrapper 调用
-└── references/
-    ├── intent.md
-    ├── strategy.md
-    ├── variables.md                 # 变量系统管理
-    ├── quality-inspection.md        # AI 质检管理
-    ├── tagging.md                   # 标签树管理
-    ├── agent.md                     # 历史兼容，不作新入口
-    ├── plugin.md                    # 历史兼容，不作新入口
-    └── chat.md                      # 历史兼容，不作新入口
-```
-
-## 过时文档
-
-以下文档暂时保留用于历史兼容，不作为新任务入口：
-
-- `/skills/solvea-kit/references/agent.md`：已迁入 `agent-builder`
-- `/skills/solvea-kit/references/plugin.md`：工具能力已迁入 `agent-builder`
-- `/skills/solvea-kit/references/chat.md`：测试和会话分析已拆到 `poc` / `delivery` / `agent-analytics` / `shulex-support`

package/skills/solvea-kit/references/agent.md

@@ -1,145 +0,0 @@
-# Agent 管理
-
-> 已过时：Agent 构建、修改、复制、语音 Agent、CHAT_FLOW 和工具绑定已迁入 `agent-builder`。本文件仅保留历史兼容，不作为新任务入口。
-
-## 能力概览
-
-| 类型 | 适用场景 | 何时选用 |
-|------|---------|---------|
-| SINGLE_AGENT | 单一目标：FAQ问答、查询、生成 | 任务目标明确、不超过3个流程分支、一个 Prompt 能说清职责边界 |
-| CHAT_FLOW | 多分支流程：意图分类、条件路由、多步骤处理 | 需要条件分支、人工审批、超过3个流程节点，Prompt 无法涵盖 |
-| Voice Agent | 语音对话 | 同上，但 category=voice |
-
-CHAT_FLOW 图构建、修改、校验和发布由 `chatflow` skill 维护，本文件不展开节点规则。
-
----
-
-## SINGLE_AGENT
-
-### 能力
-
-用户输入 → [Prompt + Tools] → LLM 自主推理（可多轮工具调用） → 输出
-
-适用条件：
-- 任务目标单一明确（问答、查询、生成）
-- 不需要条件分支或人工审批
-- 一个 Prompt 能说清职责边界
-- 客服FAQ问答、预约助手、数据查询
-- 流程不超过3个分支；超过时改用 CHAT_FLOW，太长的 prompt 难以维护
-
-### API
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 列表/详情 | POST | `/api_v2/gpt/ap/queryAgent` | 不返回 chatFlowGraph |
-| 创建 | POST | `/api_v2/gpt/ap/createAgent` | |
-| 更新 | POST | `/api_v2/gpt/ap/updateAgent` | 必须提交完整对象 |
-
-### CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-agents --pretty
-npx --yes @shulex/cxclawctl@latest api get-agent --id <agent_id> --pretty
-npx --yes @shulex/cxclawctl@latest api create-agent \
-  --data '{"name":"FAQ_Bot","type":"SINGLE_AGENT","prompt":"...","displayPrompt":"..."}' --pretty
-```
-
-### 原则
-
-- 更新前必须先 `get-agent` 获取完整对象，`update-agent` 不支持 partial patch
-- `prompt` 和 `displayPrompt` 必须同步更新，两者不一致导致执行与展示不符
-- `agentId` 字段必须等于 `id`，否则更新失败
-
-## Voice Agent
-
-语音 Agent 与文本 Agent **共用** `POST /api_v2/gpt/ap/createAgent` / `updateAgent` 接口。后端按 `meta.category == "voice"` 分流到语音处理逻辑。语音对话记录走独立 internal API。
-
-### 创建示例
-
-```json
-{
-  "projectId": 103,
-  "name": "Voice_Support",
-  "description": "客服语音助手",
-  "type": "SINGLE_AGENT",
-  "source": "MANUAL",
-  "prompt": "你是一个语音客服助手。用简短的口语化句子回答，避免列表和 markdown。涉及专业术语时附上通俗解释。",
-  "displayPrompt": "你是一个语音客服助手。用简短的口语化句子回答，避免列表和 markdown。涉及专业术语时附上通俗解释。",
-  "meta": {
-    "category": "voice",
-    "version": "v1",
-    "assistant": {
-      "callType": "INBOUND_PHONE_CALL",
-      "firstMessage": "您好，请问有什么可以帮您？",
-      "language": "zh-CN"
-    },
-    "knowledgeAiReplyPlugin": {
-      "type": "KNOWLEDGE_AI_REPLY",
-      "meta": {
-        "knowledgeAiReplyConfig": {
-          "enable": true,
-          "directoryIds": [32254, 32255],
-          "useAgentPrompt": true
-        }
-      }
-    }
-  }
-}
-```
-
-### 字段说明
-
-| 字段 | 必填 | 说明 |
-|---|---|---|
-| `projectId` | ✅ | 当前租户 project ID |
-| `name` | ✅ | 长度 ≤ 40 |
-| `type` | ✅ | 固定 `SINGLE_AGENT`（MULTI_AGENT 后端会拒） |
-| `source` | 推荐 | `MANUAL` 区分手动创建；`SYSTEM` 系统自动生成 |
-| `prompt` | 可选 | agent 角色/语气/策略。**和 `displayPrompt` 文本必须一致**（不一致执行与展示分裂） |
-| `displayPrompt` | 可选 | 同 `prompt`；不传则后端按 `meta.version` 自动用默认模板 |
-| `description` | 可选 | agent 描述 |
-| `meta.category` | ✅ | 固定 `"voice"`。**必须放 `meta` 里**，顶层不走语音分流 |
-| `meta.version` | 推荐 | `"v1"` 走新版默认 prompt（KB_Reply + Transfer_To_Agent 工具引用） |
-| `meta.assistant` | ✅ | 整个对象不能为 null，否则 400 `"Assistant config cannot be empty"` |
-| `meta.assistant.callType` | ✅ | 枚举：`INBOUND_PHONE_CALL`（入呼）/ `OUTBOUND_PHONE_CALL`（出呼）/ `WEB_CALL`（网页语音） |
-| `meta.assistant.firstMessage` | 可选 | 接通后第一句话 |
-| `meta.assistant.language` | 可选 | 语言代码，如 `zh-CN` / `ja-JP` / `en-US`，决定语音识别和合成 |
-| `meta.assistant.specials[]` | 可选 | 绑定真实电话号码：`[{phoneNumberId, language}]`。`phoneNumberId` 必须存在且未被其它 agent 绑定 |
-| `meta.assistant.voiceTone` | 看场景 | 音色配置。**create 不传**（后端不强制）；**update 必传**（含 `voiceId` / `voiceProvider`） |
-| `meta.knowledgeAiReplyPlugin` | 可选 | 覆盖后端默认注入的 KB_Reply 内置工具，绑到指定知识库目录 |
-| `...knowledgeAiReplyConfig.directoryIds` | 绑 KB 时必填 | 知识库目录 ID 数组（用 `list-directories` 查） |
-| `...knowledgeAiReplyConfig.enable` | 绑 KB 时必填 | `true` 启用 KB 检索 |
-| `...knowledgeAiReplyConfig.useAgentPrompt` | 推荐 | `true` 让 KB 检索结果用 agent 的 prompt 改写（语气一致） |
-
-> ⚠️ **上表是完整 schema，没列的字段一律不要发明**。出现 400 优先回看上表，**不要靠改字段组合反复试**（见 rules.md §4 调试预算）。
-
-### API 端点
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 列表 | POST | `/api_v2/gpt/ap/queryAgent` | `category=voice` 作为顶层过滤参数 |
-| 创建 / 更新 | POST | `/api_v2/gpt/ap/createAgent` 或 `updateAgent` | |
-| 对话记录分页 | POST | `/api_v2/as_bot/voice-report/transcript-page` | internal.shulex.com |
-| 对话详情 | GET | `/api_v2/gpt/voice/transcript/projectId/{pid}/history/{hid}` | internal.shulex.com |
-
-### CLI
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-voice-agents --pretty
-
-# 创建：payload 存成 json 文件，避免 shell 转义出问题（多语言 prompt 尤其推荐）
-npx --yes @shulex/cxclawctl@latest api create-agent \
-  --data-file /workspace/tmp/voice_agent_payload.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api list-voice-transcripts --pretty
-npx --yes @shulex/cxclawctl@latest api get-voice-transcript \
-  --history-id 019d4dac-aa36-744d-8c5d-d54bc3f7e528 --pretty
-```
-
-### 注意事项
-
-- **接口说明**：对话记录接口由 CLI 内部处理域名与鉴权
-- **额外 header**：`x-language: cn` + `x-token-domain: .shulex.com`
-- **时间戳**：`beginTimestamp` / `endTimestamp` 毫秒级
-- 音色 ID 从 `/api_v2/gpt/ap/voiceConfig` 查询，可选条件 gender / language / provider
-- `list-voice-agents` 等价于 `list-agents --category voice`