@shulex/cxclawctl 0.0.0-stage → 0.1.2

package/skills/poc/scripts/inspect_chatflow.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""为 POC 案例设计精简 chatflow 图视图。
+
+把 raw graph（完整 nodes/edges + UUID + 渲染坐标）压成 agent 看一眼就能设计 case 的形态：
+- 节点按 category 提取**业务关键字段**（NOTE 的 noteText、AGENT/REPLY 的 prompt、
+  INTENT 的 intents 列表、TOOL 的 inputParams 等），不仅是字段名
+- edge label 中的 intent uuid / next_step uuid **自动解码**为人类可读的名字
+- 去掉 position 坐标、UUID 中段（保留前 8 位）等纯渲染元素
+
+为什么这段不放 solvea-api：solvea-api 是纯封装层（API + CLI 透传），不掺业务视图加工。
+这种 POC 设计 case 的特定 view 属于 poc skill 自己的职责。
+
+用法：
+    python3 inspect_chatflow.py --agent-id 38099 --pretty
+    python3 inspect_chatflow.py --agent-id 38099 --agent-id 38100 --agent-id 38101 --pretty
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.environ.get("SOLVEA_LIB_DIR", os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "__lib__"))), "skill-runtime"))
+from bootstrap import *  # noqa: F401,F403
+from client import SolveaClient
+
+
+# 长 prompt 的截断阈值；prompt / desc 超过这个长度时尾部加 …<truncated>
+_PROMPT_TRUNCATE = 1500
+
+
+def _truncate(text: str, limit: int = _PROMPT_TRUNCATE) -> str:
+    if not isinstance(text, str):
+        return text
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"\n…<truncated, total {len(text)} chars>"
+
+
+def _short_id(uuid: str) -> str:
+    return (uuid or "")[:8]
+
+
+def _summarize_node(n: dict) -> dict:
+    """按 category 提取关键业务字段。未识别的 category 退回到 raw config。"""
+    data = n.get("data") or {}
+    config = data.get("config") or {}
+    category = data.get("category") or ""
+    title = data.get("title") or "(start)"
+
+    out: dict = {
+        "id": _short_id(n.get("id")),
+        "category": category,
+        "title": title,
+    }
+    desc = data.get("desc")
+    if desc:
+        out["desc"] = desc
+
+    if category == "START":
+        return out
+
+    if category == "NOTE":
+        out["note_text"] = config.get("noteText", "")
+        return out
+
+    if category in ("AGENT", "KNOWLEDGE_REPLY"):
+        agent_data = config.get("agentData") or {}
+        prompt = agent_data.get("prompt") or (config.get("knowledgeReply") or {}).get("prompt")
+        if prompt:
+            out["prompt"] = _truncate(prompt)
+        next_steps = config.get("nextStep") or []
+        if next_steps:
+            out["next_step"] = [
+                {k: v for k, v in {"id": ns.get("id"), "title": ns.get("title"), "prompt": _truncate(ns.get("prompt") or "", 300)}.items() if v}
+                for ns in next_steps
+            ]
+        if config.get("maxRounds"):
+            out["max_rounds"] = config["maxRounds"]
+        return out
+
+    if category == "REPLY":
+        rc = config.get("replyContent") or {}
+        if rc.get("prompt"):
+            out["reply_prompt"] = _truncate(rc["prompt"])
+        if rc.get("type") and rc["type"] != "PROMPT":
+            out["reply_type"] = rc["type"]
+        return out
+
+    if category == "INTENT":
+        out["intents"] = [
+            {k: v for k, v in {"id": it.get("id"), "name": it.get("name"), "desc": _truncate(it.get("desc") or "", 400)}.items() if v}
+            for it in (config.get("intents") or [])
+        ]
+        return out
+
+    if category == "TOOL":
+        tool = config.get("tool") or {}
+        out["tool_id"] = tool.get("id")
+        out["tool_type"] = tool.get("type")
+        params = tool.get("inputParams") or []
+        if params:
+            out["input_params"] = [
+                {"name": p.get("name"), "var_type": p.get("varType"), "from": p.get("variableSelector")}
+                for p in params
+            ]
+        return out
+
+    if category == "VARIABLE_EXTRACT":
+        ve = config.get("variableExtract") or {}
+        out["extracts"] = [
+            {k: v for k, v in {"name": e.get("name"), "describe": e.get("describe"), "type": e.get("type")}.items() if v}
+            for e in (ve.get("extracts") or [])
+        ]
+        return out
+
+    if category == "VARIABLE_ASSIGNMENT":
+        out["assignments"] = [
+            {"source": a.get("source"), "target": a.get("target"), "operation": a.get("operation")}
+            for a in (config.get("variableAssignment") or [])
+        ]
+        return out
+
+    if category == "TRANSFER_TO_HUMAN":
+        h = config.get("transferToHuman") or {}
+        if h.get("prompt"):
+            out["handoff_prompt"] = _truncate(h["prompt"])
+        return out
+
+    # 未知 category：保留原始 config（截断长字符串）便于后续扩展
+    if config:
+        out["config"] = config
+    return out
+
+
+def _build_handle_index(raw_nodes: list) -> dict:
+    """构造 source_handle uuid → 可读 label 的反查表。
+
+    INTENT 节点的 intents[].id 和 AGENT/KNOWLEDGE_REPLY 节点的 nextStep[].id 都是 uuid，
+    会出现在 edge.sourceHandle 上。把它们映射成 `[Intent] xxx` / `[NextStep] xxx`，
+    edge label 立刻可读，不再是裸 uuid。
+    """
+    idx: dict[str, str] = {}
+    for n in raw_nodes:
+        data = n.get("data") or {}
+        config = data.get("config") or {}
+        category = data.get("category") or ""
+        if category == "INTENT":
+            for it in (config.get("intents") or []):
+                if it.get("id") and it.get("name"):
+                    idx[it["id"]] = f"[Intent] {it['name']}"
+        elif category in ("AGENT", "KNOWLEDGE_REPLY"):
+            for ns in (config.get("nextStep") or []):
+                if ns.get("id") and ns.get("title"):
+                    idx[ns["id"]] = f"[NextStep] {ns['title']}"
+    return idx
+
+
+def build_summary(client: SolveaClient, agent_id: int) -> dict:
+    g = client.get_chatflow_graph(agent_id)
+    graph = g.get("graph") or {}
+    raw_nodes = graph.get("nodes") or []
+    raw_edges = graph.get("edges") or []
+    by_id = {n.get("id"): n for n in raw_nodes}
+    handle_idx = _build_handle_index(raw_nodes)
+
+    def _title(nid):
+        return ((by_id.get(nid) or {}).get("data") or {}).get("title") or "(start)"
+
+    nodes = [_summarize_node(n) for n in raw_nodes]
+
+    edges = []
+    for e in raw_edges:
+        handle = e.get("sourceHandle") or ""
+        # 优先解码 intent / next_step uuid，否则回退到 handle 原值
+        label = handle_idx.get(handle) or handle or e.get("label") or ""
+        edges.append({
+            "from": f"{_short_id(e.get('source'))} ({_title(e.get('source'))})",
+            "to": f"{_short_id(e.get('target'))} ({_title(e.get('target'))})",
+            "label": label,
+        })
+
+    return {
+        "agent_id": g.get("agentId"),
+        "version": g.get("chatFlowVersion") or g.get("version"),
+        "stats": {"nodes": len(raw_nodes), "edges": len(raw_edges)},
+        "nodes": nodes,
+        "edges": edges,
+    }
+
+
+def main():
+    p = argparse.ArgumentParser(description="Inspect chatflow graph for POC case design")
+    p.add_argument("--agent-id", type=int, action="append", required=True,
+                   help="Agent ID (可重复传多个，例如 --agent-id 38099 --agent-id 38100)")
+    p.add_argument("--pretty", action="store_true", help="Pretty print JSON")
+    args = p.parse_args()
+
+    client = SolveaClient()
+    result = [build_summary(client, aid) for aid in args.agent_id]
+    out = result[0] if len(result) == 1 else result
+
+    if args.pretty:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print(json.dumps(out, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/skills/poc/scripts/plan.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""POC 顶层状态规划器。
+
+只维护 `/workspace/state/poc/progress.json`，不执行 intent / agent / KB / batch
+等底层能力。其他 skill 的状态只通过路径引用记录在本文件中，避免职责泄漏。
+"""
+import os, sys
+sys.path.insert(0, os.path.join(os.environ.get("SOLVEA_LIB_DIR", os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "__lib__"))), "skill-runtime"))
+from bootstrap import *  # noqa: F401,F403
+
+import argparse
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+
+STATE_FILE = STATE_DIR / "progress.json"
+
+STATUS_ORDER = [
+    "empty",
+    "classified",
+    "business_agents_created",
+    "fallback_agent_created",
+    "fallback_strategy_linked",
+    "kb_done",
+    "cases_ready",
+    "test_done",
+    "done",
+]
+
+
+def default_state() -> dict[str, Any]:
+    return {
+        "status": "empty",
+        "tenant": SOLVEA_TENANT_ID or "",
+        "brand_name": "",
+        "brand_website": "",
+        "intent": {
+            "progress_path": "/workspace/state/poc/progress.json",
+            "created_log_path": "",
+            "classification_report_path": "",
+            "classification_excel_path": "",
+        },
+        "fallback_agent": {
+            "agent_id": "",
+            "agent_name": "",
+            "created": False,
+        },
+        "kb": {
+            "enabled": False,
+            "source_url": "",
+            "directory_plan_path": "",
+            "qa_plan_path": "",
+            "upload_result_path": "",
+        },
+        "test": {
+            "agents": [],
+            "cases_json_path": "",
+            "results_path": "",
+            "manual_path": "",
+        },
+        "updated_at": "",
+    }
+
+
+def read_state() -> dict[str, Any]:
+    if not STATE_FILE.exists():
+        return default_state()
+    try:
+        loaded = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return default_state()
+    state = default_state()
+    merge_dict(state, loaded)
+    return state
+
+
+def merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> None:
+    for key, value in patch.items():
+        if isinstance(value, dict) and isinstance(base.get(key), dict):
+            merge_dict(base[key], value)
+        else:
+            base[key] = value
+
+
+def write_state(state: dict[str, Any]) -> None:
+    state["updated_at"] = datetime.now(timezone.utc).isoformat()
+    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def set_path(state: dict[str, Any], dotted_key: str, raw_value: str) -> None:
+    parts = [p for p in dotted_key.split(".") if p]
+    if not parts:
+        raise ValueError("empty key")
+    cur = state
+    for part in parts[:-1]:
+        nxt = cur.get(part)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cur[part] = nxt
+        cur = nxt
+    value: Any = raw_value
+    if raw_value.lower() == "true":
+        value = True
+    elif raw_value.lower() == "false":
+        value = False
+    elif raw_value.startswith("[") or raw_value.startswith("{"):
+        value = json.loads(raw_value)
+    cur[parts[-1]] = value
+
+
+def recommendation(status: str) -> str:
+    return {
+        "empty": "下一步：读取 poc/interfaces/classify.md 和 poc/interfaces/create-agents.md，确认从 xlsx 分类还是固定 7 意图开始。",
+        "classified": "下一步：展示分类结果并等待用户确认；确认后调用 /skills/poc/scripts/create_agents.py --mode poc。",
+        "business_agents_created": "下一步：通过 agent-builder/interfaces/fallback-chatflow.md 创建兜底 CHAT_FLOW agent。",
+        "fallback_agent_created": "下一步：调用 /skills/poc/scripts/create_agents.py --mode poc --poc-fallback-agent-id <agent_id> 绑定兜底策略。",
+        "fallback_strategy_linked": "下一步：询问是否进入可选 KB 阶段；跳过则进入 POC 批测。",
+        "kb_done": "下一步：读取 poc/interfaces/poc-test.md，设计并确认测试 cases。",
+        "cases_ready": "下一步：执行 poc_test.py，然后生成 POC 测试手册。",
+        "test_done": "下一步：汇总 POC 测试手册和原始结果，确认交付完成。",
+        "done": "当前 POC 已完成；如需重跑，请明确要重跑的阶段。",
+    }.get(status, "状态未知：请检查 progress.json。")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="POC top-level progress planner")
+    parser.add_argument("--init", action="store_true", help="Create progress.json if missing")
+    parser.add_argument("--status", choices=STATUS_ORDER, help="Update top-level status")
+    parser.add_argument("--tenant", default=None)
+    parser.add_argument("--brand-name", default=None)
+    parser.add_argument("--brand-website", default=None)
+    parser.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                        help="Set a dotted state path, e.g. intent.created_log_path=/workspace/...")
+    parser.add_argument("--json", action="store_true", help="Print JSON only")
+    args = parser.parse_args()
+
+    existed = STATE_FILE.exists()
+    state = read_state()
+    changed = False
+
+    if args.init and not existed:
+        changed = True
+    if args.status:
+        state["status"] = args.status
+        changed = True
+    if args.tenant is not None:
+        state["tenant"] = args.tenant
+        changed = True
+    if args.brand_name is not None:
+        state["brand_name"] = args.brand_name
+        changed = True
+    if args.brand_website is not None:
+        state["brand_website"] = args.brand_website
+        changed = True
+    for item in args.set:
+        if "=" not in item:
+            raise SystemExit(f"--set expects KEY=VALUE, got: {item}")
+        key, value = item.split("=", 1)
+        set_path(state, key, value)
+        changed = True
+
+    if changed:
+        write_state(state)
+
+    if args.json:
+        print(json.dumps(state, ensure_ascii=False, indent=2))
+        return
+
+    print(f"POC progress: {STATE_FILE}")
+    print(f"status={state.get('status')} tenant={state.get('tenant') or '-'} brand={state.get('brand_name') or '-'}")
+    print(recommendation(str(state.get("status") or "")))
+    print(json.dumps(state, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()