@shulex/cxclawctl 0.1.2 → 0.1.3

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

@@ -1,231 +0,0 @@
-# 标签树管理
-
-这里对接的是 `tagSetting` 页面使用的标签树，用于维护标签组、标签节点，以及通过 Excel 批量初始化或更新标签。
-
-注意：当前页面使用的是 `/api_v2/gpt/label/project/...` 这组接口；`/ai-tag/*` 是另一套标签能力，不在本流程内。
-
-## API
-
-| 操作 | 方法 | 路径 | 说明 |
-|------|------|------|------|
-| 标签组列表 | GET | `/api_v2/gpt/label/project/{pid}/getTreeInfo` | 获取标签组，返回 `id/treeName/treeDescribe/condition` |
-| 创建/更新/删除标签组 | POST | `/api_v2/gpt/label/project/{pid}/updateTreeInfo` | body 用 `operateType=CREATE/UPDATE/DELETE` |
-| 标签树 | GET | `/api_v2/gpt/label/project/{pid}/getTagTree` | 参数 `treeId` 必填，`name` 可选 |
-| 标签详情 | POST | `/api_v2/gpt/label/project/{pid}/getDetailTree` | 支持 `nodeIds/nodeNames/parentIds` |
-| 创建/更新/删除标签节点 | POST | `/api_v2/gpt/label/project/{pid}/updateNode` | body 用 `operateType=CREATE/UPDATE/DELETE` |
-| 下载导入模板 | GET | `/api_v2/gpt/label/project/{pid}/downloadLabelTemplate` | 排查或人工编辑时使用，普通流程不用 |
-| 下载当前标签 | GET | `/api_v2/gpt/label/project/{pid}/downloadLabel` | 用于导出现有标签，更新后再导入 |
-| 批量导入标签 | POST | `/api_v2/gpt/label/project/{pid}/uploadLabel` | body 传 `treeId/file/uploadWay`；`file` 是上传到临时 S3 后的 key |
-
-## CLI
-
-### 标签组
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-label-groups --pretty
-npx --yes @shulex/cxclawctl@latest api list-label-groups --name "Default" --pretty
-
-npx --yes @shulex/cxclawctl@latest api create-label-group \
-  --name "售后问题" --pretty
-
-npx --yes @shulex/cxclawctl@latest api update-label-group --id <group_id> \
-  --data-file /workspace/state/solvea-kit/label_group_update.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api delete-label-group --id <group_id> --pretty
-```
-
-`update-label-group` 的 data-file 示例：
-
-```json
-{
-  "treeName": "售后问题",
-  "treeDescribe": "",
-  "condition": null,
-  "isMultiTag": true
-}
-```
-
-### 标签节点
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-label-tree \
-  --tree-id <tree_id> --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-label-tree \
-  --tree-id <tree_id> --name "退款" --pretty
-
-npx --yes @shulex/cxclawctl@latest api get-label-detail-tree \
-  --tree-id <tree_id> --node-ids <node_id> --pretty
-
-npx --yes @shulex/cxclawctl@latest api create-label-node \
-  --tree-id <tree_id> --name "退货退款" --content "用户咨询退货、退款、取消订单等售后问题" --pretty
-
-npx --yes @shulex/cxclawctl@latest api update-label-node \
-  --tree-id <tree_id> --id <node_id> \
-  --data-file /workspace/state/solvea-kit/label_node_update.json --pretty
-
-npx --yes @shulex/cxclawctl@latest api delete-label-node \
-  --tree-id <tree_id> --id <node_id> --pretty
-```
-
-`create-label-node` / `update-label-node` 的 data-file 示例：
-
-```json
-{
-  "nodeName": "退货退款",
-  "describe": "用户咨询退货、退款、取消订单等售后问题",
-  "parentId": 0,
-  "isTag": true,
-  "exampleList": [
-    "How can I return my order?",
-    "I want a refund."
-  ]
-}
-```
-
-`parentId=0` 表示一级标签。`isTag=false` 表示该节点不参与打标；关闭父节点时后端会影响子节点。
-
-## 批量导入
-
-主流程不是让用户下载模板手填。用户描述标签需求后，agent 应先整理标签树结构，写成 JSON，生成符合导入接口模板的 xlsx，再上传导入。
-
-推荐流程：
-
-1. 先 `list-label-groups` / `get-label-tree` 确认目标标签组是否为空、现有节点是什么。
-2. 根据用户描述整理标签层级、描述、样例，写入 `/workspace/state/solvea-kit/labels.json`。
-3. 用 `/skills/solvea-kit/scripts/generate_label_import_file.py` 生成 xlsx。
-4. 给用户展示将导入的层级摘要，确认后执行 `upload-labels`。
-
-### 生成导入文件
-
-空标签组初始化用 `--init`，JSON 示例：
-
-```json
-{
-  "labels": [
-    {
-      "path": ["售后问题", "物流问题", "配送延迟"],
-      "describe": "用户反馈包裹未按预计时间送达、配送时效过慢或物流长时间未更新。",
-      "examples": [
-        "My package is delayed.",
-        "Tracking has not updated for several days."
-      ]
-    }
-  ]
-}
-```
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/solvea-kit/scripts/generate_label_import_file.py \
-  --init \
-  --input /workspace/state/solvea-kit/labels.json \
-  --output /workspace/state/solvea-kit/labels_init.xlsx --pretty
-```
-
-已有标签更新或追加时，优先先 `download-labels` 导出现有标签，或 `get-label-tree` 查询节点 ID，再生成更新格式。JSON 示例：
-
-```json
-{
-  "labels": [
-    {
-      "id": "",
-      "name": "配送延迟",
-      "describe": "用户反馈包裹未按预计时间送达、配送时效过慢或物流长时间未更新。",
-      "parentId": 123456,
-      "isTag": true,
-      "examples": [
-        "My package is delayed.",
-        "Tracking has not updated for several days."
-      ],
-      "path": "售后问题/物流问题/配送延迟"
-    }
-  ]
-}
-```
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/solvea-kit/scripts/generate_label_import_file.py \
-  --input /workspace/state/solvea-kit/labels.json \
-  --output /workspace/state/solvea-kit/labels_update.xlsx --pretty
-```
-
-### 上传导入
-
-空标签组初始化：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api upload-labels \
-  --tree-id <tree_id> \
-  --file /workspace/state/solvea-kit/labels_init.xlsx \
-  --init --pretty
-```
-
-已有标签更新：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api upload-labels \
-  --tree-id <tree_id> \
-  --file /workspace/state/solvea-kit/labels_update.xlsx --pretty
-```
-
-### 模板下载（排查用）
-
-一般不需要让用户下载模板。只有在核对线上模板变化、排查导入失败，或需要人工离线编辑时才下载。普通场景直接用上面的生成脚本。
-
-```bash
-npx --yes @shulex/cxclawctl@latest api download-label-template \
-  --template-type update \
-  --output /workspace/state/solvea-kit/label_template.xlsx --pretty
-```
-
-更新已有标签时，优先先导出现有标签，在导出的 xlsx 上修改：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api download-labels \
-  --tree-id <tree_id> \
-  --output /workspace/state/solvea-kit/current_labels.xlsx --pretty
-```
-
-## Excel 模板口径
-
-当前标签导出 / 更新格式：
-
-| 列 | 含义 |
-|---|---|
-| `id` | 已有节点 ID；为空表示新增标签 |
-| `name` | 标签名称，不能为空；同一 parent 下不能重复 |
-| `describe` | 标签描述，供模型理解标签含义 |
-| `example1` ~ `example5` | 样例表达 |
-| `is_tag` | `1` 参与打标，`0` 不参与打标；为空按 `1` |
-| `level` | 展示字段，更新时主要依赖 `parent_id` |
-| `parent_id` | 父节点 ID；一级标签填 `0` 或空 |
-| `path` | 展示字段，便于人工核对路径 |
-
-初始化格式：
-
-| 列 | 含义 |
-|---|---|
-| `first_level` | 一级标签，不能为空 |
-| `second_level` | 二级标签，可空 |
-| `third_level` | 三级标签，可空 |
-| `fourth_level` | 四级标签，可空 |
-| `describe` | 叶子标签描述 |
-| `example1` ~ `example5` | 样例表达 |
-
-后端限制：
-
-- Excel 空数据会失败。
-- 最多支持 2000 个标签，超过会失败。
-- `id` / `parent_id` 必须是数字或空。
-- `id` 必须属于当前租户项目已有节点；`parent_id` 必须存在。
-- 同一父节点下的 `name` 不能重复。
-- 普通更新模板要求至少 12 列。
-
-## 操作原则
-
-- 新增或更新前，先 `list-label-groups` / `get-label-tree` 确认现状。
-- 删除标签组或标签节点前，先展示将删除的对象，并得到用户明确确认。
-- 批量导入前先基于用户描述整理结构化 JSON，再生成 xlsx；不要让用户手填模板。
-- 更新已有标签时，先查现有树或导出现有标签，避免 parentId / id 写错。
-- 批量导入文件放 `/workspace/state/solvea-kit/`，先说明影响范围，再执行 `upload-labels`。
-- 标签分析、分布报表、AI 测试不属于本页基础管理能力；需要时走分析类能力单独处理。

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

@@ -1,53 +0,0 @@
-# 变量系统字段
-
-变量系统字段为策略条件、工具参数、CHAT_FLOW 节点和 Agent prompt 提供结构化上下文。配置事实源是 Tars；CHAT_FLOW 画布的字段接口只用于画布兼容，不能代替这里的管理流程。
-
-## 查询与初始化
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-ai-field-guide --pretty
-npx --yes @shulex/cxclawctl@latest api list-managed-ai-fields --page 1 --page-size 50 --pretty
-npx --yes @shulex/cxclawctl@latest api get-managed-ai-field --id <field_id> --pretty
-```
-
-若 `get-ai-field-guide` 显示未初始化，先说明将创建系统预装字段，得到确认后再执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api initialize-ai-fields --pretty
-```
-
-## 创建与更新
-
-先列出或读取已有字段，展示名称、描述、数据类型、选项、应用范围和预期用途，再请求确认。确认后的 JSON 写入 `/workspace/state/solvea-kit/`，通过 CLI 提交：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-managed-ai-field \
-  --data-file /workspace/state/solvea-kit/ai_field_create.json --pretty
-npx --yes @shulex/cxclawctl@latest api update-managed-ai-field \
-  --data-file /workspace/state/solvea-kit/ai_field_update.json --pretty
-npx --yes @shulex/cxclawctl@latest api toggle-managed-ai-field --id <field_id> --pretty
-```
-
-常用字段：`name`、`description`、`dataType`、`aiFieldValueDTOS`（单选/多选选项）、`applyRang`、`useAgent`、`parentId`。不要猜测数据类型编码或应用范围；先读取同租户同类型字段作为模板。
-
-## 删除
-
-删除前必须先读取详情和列表中的 `usedIn`。字段已被使用时，不承诺可删除；先说明影响并引导用户迁移 Agent、策略、模板或 CHAT_FLOW 引用。仅在字段未使用且用户确认后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api delete-managed-ai-field --id <field_id> --pretty
-```
-
-## 使用场景
-
-| 场景 | 说明 |
-|---|---|
-| 策略条件 | 条件实体或 metadata 依赖变量系统字段提取结果 |
-| 工具参数 | 工具 requestParam 可从 LLM / METADATA / 固定值等来源取值 |
-| CHAT_FLOW | QUESTION(VARIABLE)、IF_ELSE、TOOL、VARIABLE_PROCESS 等节点会引用变量系统字段 |
-| AGENT / REPLY prompt | 通过 `ai_field_ids` 引用变量系统字段 |
-
-## 边界
-
-- 排查变量提取异常走 `shulex-support` Agent 会话诊断场景的 M4 变量系统字段链路。
-- CHAT_FLOW 内如何引用变量、如何把上游输出桥接到变量系统字段，走 `agent-builder` 的 chatflow 文档。

package/skills/solvea-kit/scripts/generate_label_import_file.py

@@ -1,151 +0,0 @@
-#!/usr/bin/env python3
-"""Generate label-tree import xlsx from structured JSON.
-
-This is a solvea-kit workflow helper, not a backend API wrapper. The generated
-xlsx is meant to be passed to:
-
-    npx --yes @shulex/cxclawctl@latest api upload-labels --tree-id <id> --file <xlsx>
-"""
-
-import os
-import sys
-sys.path.insert(0, os.path.join(
-    os.environ.get("SOLVEA_LIB_DIR", os.path.join(os.path.dirname(__file__), "..", "..", "__lib__")),
-    "skill-runtime",
-))
-from bootstrap import STATE_DIR  # noqa: E402
-
-import argparse
-import json
-from pathlib import Path
-
-from openpyxl import Workbook
-from openpyxl.styles import Alignment, Font, PatternFill
-from openpyxl.utils import get_column_letter
-
-
-INIT_NOTICE = (
-    "The information of this row cannot be deleted! Tips:\n"
-    "1. first_level is the first level that is not empty.\n"
-    "2. second_level is the second level.\n"
-    "3. third_level is the third level.\n"
-    "4. fourth_level is the fourth level.\n"
-    "5. \"Name\", \"describe\" and \"example\" are for the use of the large model. Do not repeat them."
-)
-
-UPDATE_NOTICE = (
-    "The information of this row cannot be deleted! Tips:\n"
-    "1. The \"id\" is automatically generated by the program. When it is empty, it indicates adding a new tag. When it is an existing ID, it represents updating the current tag information.\n"
-    "2. \"Name\", \"describe\" and \"example\" are for the use of the large model. Do not repeat them.\n"
-    "3. Fill in the \"parent_ID\" with the ID of the parent node tag.\n"
-    "4.If \"is_Tag\" is 1, it represents tagging as a tag. If it is 0, it will not be tagged to the work order."
-)
-
-
-def _load_labels(path: Path) -> list[dict]:
-    data = json.loads(path.read_text(encoding="utf-8"))
-    labels = data.get("labels") if isinstance(data, dict) else data
-    if not isinstance(labels, list) or not labels:
-        raise ValueError("input requires a non-empty labels array")
-    for label in labels:
-        if not isinstance(label, dict):
-            raise ValueError("each label must be a JSON object")
-    return labels
-
-
-def _examples(label: dict) -> list[str]:
-    examples = label.get("examples") or label.get("exampleList") or []
-    if not isinstance(examples, list):
-        raise ValueError("examples must be an array")
-    return [str(value).strip() for value in examples[:5]] + [""] * max(0, 5 - len(examples))
-
-
-def _init_rows(labels: list[dict]) -> list[list]:
-    rows = [
-        [INIT_NOTICE],
-        ["first_level", "second_level", "third_level", "fourth_level",
-         "describe", "example1", "example2", "example3", "example4", "example5"],
-    ]
-    for label in labels:
-        path = label.get("path") or [
-            label.get("firstLevel") or label.get("first_level") or "",
-            label.get("secondLevel") or label.get("second_level") or "",
-            label.get("thirdLevel") or label.get("third_level") or "",
-            label.get("fourthLevel") or label.get("fourth_level") or "",
-        ]
-        if not isinstance(path, list) or not path or not str(path[0]).strip():
-            raise ValueError("init labels require path or first_level/firstLevel")
-        path = [str(value).strip() for value in path[:4]] + [""] * max(0, 4 - len(path))
-        rows.append(path[:4] + [label.get("describe", "")] + _examples(label)[:5])
-    return rows
-
-
-def _update_rows(labels: list[dict]) -> list[list]:
-    rows = [
-        [UPDATE_NOTICE],
-        ["id", "name", "describe", "example1", "example2", "example3", "example4", "example5",
-         "is_tag", "level", "parent_id", "path"],
-    ]
-    for label in labels:
-        name = label.get("name") or label.get("nodeName")
-        if not name:
-            raise ValueError("update labels require name or nodeName")
-        is_tag = label.get("isTag", label.get("is_tag", 1))
-        if isinstance(is_tag, bool):
-            is_tag = 1 if is_tag else 0
-        rows.append([
-            label.get("id", ""),
-            name,
-            label.get("describe", label.get("nodeDescribe", "")),
-            *_examples(label)[:5],
-            is_tag,
-            label.get("level", ""),
-            label.get("parentId", label.get("parent_id", 0)),
-            label.get("path", ""),
-        ])
-    return rows
-
-
-def write_workbook(labels: list[dict], output_path: Path, init: bool = False) -> dict:
-    rows = _init_rows(labels) if init else _update_rows(labels)
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-
-    wb = Workbook()
-    ws = wb.active
-    ws.title = "labels"
-    for row in rows:
-        ws.append(row)
-
-    ws["A1"].font = Font(bold=True, color="9C6500")
-    ws["A1"].fill = PatternFill("solid", fgColor="FFF2CC")
-    ws["A1"].alignment = Alignment(wrap_text=True, vertical="top")
-    ws.row_dimensions[1].height = 78
-    for cell in ws[2]:
-        cell.font = Font(bold=True)
-        cell.fill = PatternFill("solid", fgColor="D9EAF7")
-    for column in range(1, ws.max_column + 1):
-        ws.column_dimensions[get_column_letter(column)].width = 18
-
-    wb.save(output_path)
-    return {
-        "file": str(output_path),
-        "format": "init" if init else "update",
-        "rows": len(labels),
-    }
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Generate label-tree import xlsx from JSON")
-    parser.add_argument("--input", "--data-file", dest="input", required=True, help="JSON file with labels array")
-    parser.add_argument("--output", help="Output xlsx path")
-    parser.add_argument("--init", action="store_true", help="Generate initialization format for empty trees")
-    parser.add_argument("--pretty", action="store_true", help="Pretty print JSON result")
-    args = parser.parse_args()
-
-    output_path = Path(args.output) if args.output else STATE_DIR / ("labels_init.xlsx" if args.init else "labels_update.xlsx")
-    result = write_workbook(_load_labels(Path(args.input)), output_path, init=args.init)
-    print(json.dumps(result, indent=2 if args.pretty else None, ensure_ascii=False))
-
-
-if __name__ == "__main__":
-    main()