@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/poc/assets/poc_test_template.md

@@ -1,104 +0,0 @@
-# {{brand_name}} POC 测试手册
-
-> 生成时间：{{generated_at}}　·　Powered by Shulex
-
----
-
-## 测试账号
-
-| 项目 | 内容 |
-|---|---|
-| 控制台地址 | <{{console_url}}> |
-| 测试账号 | `{{account_email}}` |
-| 登录密码 | `{{account_password}}` |
-
-> 请妥善保管账号信息，仅限本次测试用途。
-
----
-
-## 已提供资料
-
-- 客户官网：<{{brand_website}}>
-
-测试场景覆盖：
-
-- **包裹与物流问题**：涵盖包裹漏发、错发、破损，以及物流查询和物流异常处理（Package issues + Logistics Issues 共用同一 Agent）
-- **售前咨询**：涵盖产品推荐、折扣与价格咨询、库存确认、支付问题等购买前常见疑问
-- **产品问题**：涵盖产品使用指导、物理损坏（破损/故障）及非物理功能问题（功能异常、系统设置等）
-
----
-
-## 测试摘要
-
-| 指标 | 数值 |
-|---|---|
-| 总用例数 | **{{total_cases}}** |
-| 涵盖场景数 | {{scene_count}} |
-
-涉及场景：{{scene_tags_html}}
-
----
-
-## 操作步骤
-
-1. 使用上方测试账号登录 Shulex 控制台
-2. 进入 **Agents** 模块，选择想测试的场景，点击对应 Agent 进入画布
-3. 点击 **Preview** 打开测试窗口
-
-   ![Preview 入口](step3_preview.png)
-
-4. 模拟测试时，需要订单号的环节，可以使用节点备注里的不同类型订单号
-
-   ![订单号备注示例](step4_order_note.png)
-
----
-
-## 测试结果回放
-
-下面按 Agent 分组展示本次测试覆盖的所有用例及对话回放：
-
-{{agent_sections_html}}
-
----
-
-## 测试注意事项
-
-### 关于新对话
-
-每次开始新对话前，请点击 **NewChat** 按钮，否则 AI 会参考上文聊天记录回答，影响准确性。
-
-![NewChat 入口](notice_new_chat.png)
-
-### 关于知识范围
-
-提问时请注意查看机器人是否学习了对应知识。未学习的知识会按转人工流程处理。
-
-### 关于转人工
-
-默认转人工话术：
-
-> Please wait for our team and we'll get back to you as soon as possible.
-
-出现该话术时，说明 AI 由于以下原因转入人工：
-
-- 缺乏对应知识
-- 识别到转人工意图
-- 命中红线问题
-
-具体原因可查看对话下方的小字或点击 **生成过程** 查看。
-
-![转人工通知话术](notice_escalate.png)
-
-转人工后 AI 不再回复，避免与人工客服抢答。如需继续向 AI 提问，请开启新对话。
-
-![转人工后开新对话](notice_escalate2.png)
-
----
-
-## 关于本次测试
-
-当前账号为专为 **{{brand_name}}** 搭建。如无必要，请不要改动账号设置或增减知识。如需扩展体验，可联系 Shulex 协助处理。
-
-本次测试的功能仅供演示和体验。正式环境下我们可根据具体业务需求部署多功能的 AI Agent。
-
-感谢您参与本次测试。如有问题，欢迎随时联系我们的技术支持团队。

package/skills/poc/interfaces/classify.md

@@ -1,38 +0,0 @@
-# POC Intent Classification
-
-POC 专属分类入口。入口和状态归属 POC skill；通用意图分类实现调用 `solvea-kit/scripts/intent_classify.py`，状态写入 `/workspace/state/poc/progress.json`。
-
-## Commands
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/classify.py --xlsx <xlsx> --messages-col <col> [--title-col <col>]
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/classify.py --no-excel
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/gen_report.py --brand <brand>
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/gen_excel.py --brand <brand>
-```
-
-## Inputs
-
-- `xlsx`：用户上传的客诉表，可选。
-- `--messages-col`：xlsx 模式必填，由 POC 先读样例推断。
-- `--title-col`：可选。
-- `--no-excel`：使用固定 taxonomy。
-
-## Guarantees
-
-- xlsx 模式不会自动降级到 `--no-excel`。
-- 模型选择由 Solvea Kit 的 service-managed LLM 通道决定，POC 不维护具体模型名。
-- 分类结果通过 `results_path` 落盘。
-- 报告和 Excel 路径通过 POC state 暴露。
-
-## State Fields
-
-- `status`
-- `tenant`
-- `run_id`
-- `results_path`
-- `items_path`
-- `report_path`
-- `excel_path`
-- `mode`
-- `updated_at`

package/skills/poc/interfaces/create-agents.md

@@ -1,108 +0,0 @@
-# POC Intent Onboarding
-
-POC 专属能力：创建全部意图，优先克隆 3 个预置业务 agent，绑定 3 条业务策略；兜底 chatflow agent 由 POC 编排调用 `agent-builder` 创建后，再回填第 4 条兜底策略。
-
-这份 SOP 属于 `poc` skill。POC 的意图创建、业务 agent 创建、兜底策略回填都从本 skill 的脚本入口执行。
-
-## Commands
-
-```bash
-# POC 业务阶段：建全部意图 + 优先克隆 3 个业务 agent + 3 条业务策略
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/create_agents.py --mode poc
-
-# POC 兜底阶段：fallback chatflow agent 创建完成后，绑定所有 pending intents
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/create_agents.py --mode poc --poc-fallback-agent-id <agent_id>
-
-# POC 恢复阶段：预置 agent 不可用，用户确认从零新建或使用替代 agent 后，绑定业务策略
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/create_agents.py --mode poc \
-  --custom-agent-map /workspace/state/poc/custom_agent_map.json
-```
-
-`custom_agent_map.json` 使用 POC binding 名作为 key：
-
-```json
-{
-  "Package_Logistics": 2641,
-  "PreSales": 2642,
-  "Product": 2643
-}
-```
-
-## SOP
-
-1. 通过 `/skills/poc/interfaces/classify.md` 完成分类。
-2. 展示分类结果，等用户确认。
-3. 执行 `/skills/poc/scripts/create_agents.py --mode poc`。
-4. 读取 `/workspace/state/poc/progress.json` 的 `created_log_path`。
-5. 读取 created log，展示意图、agent、strategy 和 `fallback_pending`。
-6. 如果 created log 或 state 出现 `preset_agent_errors` / `status=preset_agent_missing`，不要说“只能等开发修复”，也不要直接崩溃；应向用户说明缺失的预置 agent，并请用户选择：
-   - 从零新建对应 CHAT_FLOW 业务 agent；
-   - 或指定现有 agent 作为替代。
-   用户确认后再调用 `agent-builder` 创建新 agent，或按用户给定替代 agent 继续绑定策略。
-7. 如果用户选择从零新建或使用替代 agent，把已确认的 agent id 写入 `custom_agent_map.json`，执行 `--custom-agent-map` 绑定业务策略。
-8. 调用 `/skills/agent-builder/interfaces/fallback-chatflow.md` 创建兜底 CHAT_FLOW agent。
-9. 拿到 `agent_id` 后执行 `/skills/poc/scripts/create_agents.py --mode poc --poc-fallback-agent-id <agent_id>`。
-10. 展示 fallback strategy 结果，等用户确认是否进入 KB 或测试阶段。
-
-## POC Guarantees
-
-- 创建全部标准意图和分类中新发现的 L1。
-- 当前租户已有同名意图时复用现有意图 id，继续克隆 agent 和创建策略；不要因为 create intent 返回同名冲突而中断。
-- 优先克隆 3 个固定业务 agent；如果预置 agent 不存在或复制失败，必须把它作为可恢复分支处理，询问用户从零新建还是使用替代 agent。
-- 创建 3 条业务策略，其中 Package issues 与 Logistics Issues 共用一条策略。
-- 兜底策略 priority=999，业务策略默认 priority=0。
-- 不更新 X-Token。
-- 不在 intent 脚本内创建兜底 chatflow agent。
-- 新发现 L1 或不在 3 个业务 binding 内的意图自动进入 fallback pending。
-
-## POC Fixed Bindings
-
-| Binding | 意图 | 默认 squareAgent_id |
-|---|---|---|
-| `Package_Logistics` | Package issues, Logistics Issues | 38433 |
-| `PreSales` | Pre-Sales Inquiry | 38429 |
-| `Product` | Product issues | 38428 |
-| `Fallback` | 不在上述 3 个 binding 里的所有意图 | 由 agent-builder 创建后传入 |
-
-默认 `squareAgent_id` 只是首选来源，不是硬阻塞依赖。找不到时按上面的可恢复分支处理。
-
-## Outputs
-
-状态文件：`/workspace/state/poc/progress.json`。
-
-POC 顶层只读取以下字段：
-
-- `status`
-- `mode`
-- `created_log_path`
-- `updated_at`
-
-`created_log_path` 指向 JSON，POC 可读取：
-
-- `intents[]`
-- `intents[].intent_name`
-- `intents[].intent_id`
-- `intents[].agent_id`
-- `intents[].strategy_id`
-- `intents[].binding`
-- `intents[].fallback_pending`
-- `fallback_pending_intent_ids`
-- `fallback_strategy`
-- `custom_agent_strategies[]`
-- `preset_agent_errors[]`
-- `next_action`
-
-## Fallback Chatflow Requirements
-
-POC 只声明兜底 agent 的业务目的：
-
-- 回复“当前问题不在本次 POC 测试范围内”或等价业务话术。
-- 需要保持 CHAT_FLOW agent 类型。
-- 需要输出可回填的 `agent_id`。
-
-具体节点选择、graph 结构、变量、回复节点和结束节点由 agent-builder 在读取自身能力说明后创建。POC 不维护 chatflow graph 字段，也不复制 agent-builder 的构图规则。
-
-## Non-Guarantees
-
-- POC 不依赖策略 API payload、copyAgent payload 或 chatflow graph 内部结构。
-- POC 不读取其他 skill 的完整业务流程，只调用公开 interface。

package/skills/poc/interfaces/poc-test.md

@@ -1,94 +0,0 @@
-# POC Test
-
-POC 专属测试能力：为 POC 业务 agent 设计并执行测试，生成 POC 测试手册。
-
-这份 interface 属于 `poc` skill。POC 测试 runner 和手册资产都在本 skill 内。
-
-## Commands
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/inspect_chatflow.py --agent-id <id> [--agent-id <id>] --pretty
-
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/poc_test.py \
-  --test-file /workspace/outputs/poc/poc_test_cases_<ts>.json \
-  --max-turns 3 \
-  --output /workspace/outputs/poc/results_<ts>.json \
-  --report
-
-npx --yes @shulex/cxclawctl@latest script skills/poc/scripts/gen_poc_manual.py \
-  --results /workspace/outputs/poc/results_<ts>.json \
-  --output /workspace/outputs/poc/poc_test_manual_<ts>.html \
-  --title "Shulex POC 测试手册 - <brand>" \
-  --brand-name "<brand>" \
-  --brand-website "<url>" \
-  --account-email "<email>"
-```
-
-## Agent Scope
-
-- 只测试 3 个业务 agent。
-- 跳过 Fallback agent。
-- 如果刚跑完 POC 意图创建，从 `/workspace/state/poc/progress.json` 或 `intent.created_log_path` 展开业务 agent。
-- 如果用户显式给了 agent ID，以用户输入为准。
-
-## Case Design
-
-- 每个业务 agent 默认 5 个 case。
-- 单 case 1 到 3 轮，`--max-turns 3` 是 POC 硬上限。
-- 覆盖不同分支，优先覆盖步骤多、链路长的路径。
-- KB 节点要设计能触发 KB 检索的问题。
-- 订单号必须向用户索取真实订单号集，不要编造。
-- 至少保留 1 个故意触发转人工的 case。
-- 展示结构化 case 清单，用户确认后再执行。
-
-## cases.json
-
-主字段是 `case_name`，不是 `name`。
-
-```json
-[
-  {
-    "case_name": "P1_Shipping_Inquiry",
-    "agent_name": "Pre-Sales Inquiry",
-    "agent_id": 38059,
-    "scenario": "Customer asks about shipping to Canada",
-    "messages": ["Do you ship to Canada?"],
-    "expected": {
-      "intent": "Pre-Sales Inquiry",
-      "content_contains": ["Canada"]
-    }
-  }
-]
-```
-
-## Behavior Guarantees
-
-- 触发 `handoff=True` 或 `TRANSFER_TO_HUMANS` 成功节点时停止当前 case。
-- 结果 JSON 包含 `stopped_reason`。
-- 结果 JSON 包含 chatflow 执行链路摘要。
-- 手册生成前必须确认 `brand_name`、`brand_website`、`account_email`。
-- 用户只要求重新出报告时，复用已有 `results_path`，不要重跑测试。
-
-## State
-
-POC 顶层状态写 `/workspace/state/poc/progress.json`：
-
-- `test.agents`
-- `test.cases_json_path`
-- `test.results_path`
-- `test.manual_path`
-
-不读取其他测试 skill 的状态作为 POC 顶层状态源。
-
-## User-Facing Message
-
-面向业务人员，只突出手册：
-
-```text
-## 交付物
-
-- POC 测试手册：`poc_test_manual_<ts>.html`
-- 测试结果原始数据：`results_<ts>.json`
-
-共 N 个测试案例，覆盖 M 个场景。
-```

package/skills/poc/references/flow.md

@@ -1,47 +0,0 @@
-# POC 流程
-
-## 阶段一：意图分类与 POC agent 创建
-
-1. 通过 `poc/interfaces/classify.md` 完成分类：
-   - 有 xlsx：分类用户数据。
-   - 无 xlsx：使用固定 7 个标准意图。
-2. 展示分类结果，等用户确认。
-3. 通过 `poc/interfaces/create-agents.md` 执行 POC 业务阶段：
-   - 创建全部意图。
-   - 优先克隆 3 个固定业务 agent。
-   - 如果预置 agent 找不到，询问用户从零新建还是使用其他现有 agent 替代，不要直接中断等待研发修复。
-   - 预置可用时自动创建 3 条业务策略。
-   - 用户确认替代方案后，通过 `--custom-agent-map` 将自定义/替代 agent 按业务 binding 写入策略。
-   - 获取 `fallback_pending_intent_ids`。
-4. 展示 intent / agent / strategy 表，等用户确认。
-
-## 阶段一补充：兜底 chatflow agent
-
-1. 通过 `agent-builder/interfaces/fallback-chatflow.md` 创建兜底 CHAT_FLOW agent。
-2. 首版允许由 agent-builder reference 创建；POC 不维护 graph 细节。
-3. 拿到 `agent_id` 后，通过 `poc/interfaces/create-agents.md` 执行 fallback-link。
-4. 展示 fallback strategy 结果，等用户确认。
-
-## 阶段二：知识库，可选
-
-用户希望体验产品/政策问答时才进入。
-
-1. 先读 `poc/references/kb-directory.md`，确定本次 POC 是否使用标准目录模板，还是用户显式目录 schema。
-2. 通过 `kb-builder/interfaces/web-kb.md` 处理网页、帮助中心或文档站。
-3. 通过 `kb-builder/interfaces/qa-upload.md` 处理现成 `qa_plan.json` 或 QA parts。
-4. POC 只维护业务目录规范选择；crawl provider、QA 提取和上传实现仍归 `kb-builder`。
-
-## 阶段三：批量测试 + POC 手册
-
-1. 通过 `poc/interfaces/poc-test.md` 获取业务 agent 列表。
-2. 跳过 Fallback agent。
-3. 每个业务 agent 设计测试 case，展示给用户确认。
-4. 执行 POC 测试。
-5. 生成 POC 测试手册。
-
-## 交付物
-
-- 意图分类报告（HTML / Excel）。
-- 已创建的 POC 意图、3 个业务 agent、1 个兜底 chatflow agent、4 条策略。
-- 可选知识库目录与 QA。
-- POC 测试手册 HTML。

package/skills/poc/references/kb-directory.md

@@ -1,22 +0,0 @@
-# POC KB 目录规范
-
-POC 阶段负责决定知识库目录 schema，kb-builder 只按 schema 执行目录创建、QA 归类和上传。
-
-## 优先级
-
-1. 用户当前消息明确指定的目录层级。
-2. 客户已有知识库目录或上传文件中的目录字段。
-3. POC 标准目录模板。
-
-用户或上游已经提供目录 schema 时，必须把该 schema 传给 kb-builder，并要求 kb-builder 严格按输入结构执行。schema 定义了根节点和层级时，不得在其外额外增加 POC 标准目录，也不得擅自重排层级。
-
-## POC 标准目录模板
-
-仅当用户没有指定目录 schema、也没有已有目录可复用时，才使用：
-
-- Product Introduction
-- Brand Policy
-- Help Center（仅发现帮助中心/FAQ/文档站时创建）
-- Pending Assignment
-
-使用标准模板时，这 4 个一级目录是稳定路径标识，保持英文；其下业务目录使用目标业务语言，品牌名、型号和其他专有名词保留原文。

package/skills/poc/references/validation.md

@@ -1,17 +0,0 @@
-# POC 验证清单
-
-## 基础验证
-
-- `/poc` 空参数会询问起点。
-- “接着上次”会优先读取 `/workspace/state/poc/progress.json`。
-- 顶层 state 只保存路径引用，不复制底层完整 state。
-
-## 阶段验证
-
-- xlsx 分类路径可生成报告。
-- no-excel 路径可展示固定 7 意图。
-- POC 业务阶段不更新 X-Token。
-- Fallback agent 创建后可回填 `--poc-fallback-agent-id`。
-- 知识库阶段可跳过。
-- POC 批测跳过 Fallback，只测业务 agent。
-- 手册生成前已确认品牌、官网、账号邮箱。

package/skills/poc/scripts/classify.py

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-"""POC wrapper for the shared Solvea Kit intent classifier."""
-from __future__ import annotations
-
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-
-def main() -> int:
-    script = Path(__file__).resolve().parents[2] / "solvea-kit" / "scripts" / "intent_classify.py"
-    env = os.environ.copy()
-    env.setdefault(
-        "SOLVEA_LIB_DIR",
-        str(Path(__file__).resolve().parents[2] / "__lib__"),
-    )
-    return subprocess.call([sys.executable, str(script), "--owner", "poc", *sys.argv[1:]], env=env)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())