@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/delivery/scripts/render_summary.py

@@ -1,38 +0,0 @@
-#!/usr/bin/env python3
-"""Render a concise Delivery progress / deliverables summary."""
-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 json
-
-
-STATE_FILE = STATE_DIR / "progress.json"
-
-
-def main() -> None:
-    if not STATE_FILE.exists():
-        print("Delivery progress not found. Run `python3 /skills/delivery/scripts/plan.py --init` first.")
-        return
-    state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
-    print("# Delivery Progress Summary")
-    print(f"- status: `{state.get('status', 'empty')}`")
-    print(f"- tenant: `{state.get('tenant') or '-'}`")
-    print(f"- brand: `{state.get('brand_name') or '-'}`")
-    intent = state.get("intent") or {}
-    kb = state.get("kb") or {}
-    regression = state.get("regression") or {}
-    if intent.get("classification_report_path"):
-        print(f"- classification report: `{intent['classification_report_path']}`")
-    if intent.get("created_log_path"):
-        print(f"- created log: `{intent['created_log_path']}`")
-    if kb.get("qa_plan_path"):
-        print(f"- kb qa plan: `{kb['qa_plan_path']}`")
-    if regression.get("report_html"):
-        print(f"- regression HTML: `{regression['report_html']}`")
-    if regression.get("report_md"):
-        print(f"- regression MD: `{regression['report_md']}`")
-
-
-if __name__ == "__main__":
-    main()

package/skills/delivery/scripts/sample_history_cases.py

@@ -1,109 +0,0 @@
-#!/usr/bin/env python3
-"""按意图配额从历史会话抽样 → 标准 cases.json（喂给 batch_test.py）。
-
-CLI：
-  --total 100              整批配额（按意图分配，floor + 余数 +1）
-  --intents A --intents B  指定意图（可重复）；不传则 list_intents() 全量
-  --mode single|multi      single=只取首条 USER；multi=取所有 USER（默认 single）
-  --with-metadata          抽样时把会话首轮 metadata 带进 case；默认不带
-  --max-conversations 50   每个意图 limit
-  --output cases.json      输出 cases.json 路径
-
-stdout：完成 `Wrote {N} cases → {output}`；意图列表为空 → exit 2。
-"""
-
-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
-
-
-def allocate_quota(total: int, intents: list[str]) -> dict[str, int]:
-    """按意图均匀分配总配额：floor 分配 + 余数从前往后各 +1。"""
-    n = len(intents)
-    if n == 0 or total <= 0:
-        return {it: 0 for it in intents}
-    base = total // n
-    extra = total - base * n
-    quota = {}
-    for i, it in enumerate(intents):
-        quota[it] = base + (1 if i < extra else 0)
-    return quota
-
-
-def _slim_messages(messages: list[str], mode: str) -> list[str]:
-    if mode == "single":
-        return messages[:1]
-    return messages
-
-
-def main():
-    parser = argparse.ArgumentParser(description="按意图配额抽历史会话 → cases.json")
-    parser.add_argument("--total", type=int, default=100, help="整批配额")
-    parser.add_argument("--intents", action="append", default=None,
-                        help="指定意图名（可重复传）；不传则 list_intents 全量")
-    parser.add_argument("--mode", choices=["single", "multi"], default="single",
-                        help="single=只取首条 USER；multi=取所有 USER")
-    parser.add_argument("--with-metadata", action="store_true",
-                        help="把会话首轮 metadata 带进 case")
-    parser.add_argument("--max-conversations", type=int, default=50,
-                        help="每个意图最多拉多少 chat（API limit）")
-    parser.add_argument("--output", required=True, help="输出 cases.json 路径")
-    args = parser.parse_args()
-
-    client = SolveaClient()
-
-    intents = args.intents
-    if not intents:
-        all_resp = client.list_intents(category=None)
-        all_list = all_resp if isinstance(all_resp, list) else \
-            all_resp.get("data", all_resp.get("list", []))
-        intents = [it.get("name") for it in all_list
-                   if isinstance(it, dict) and it.get("name")]
-
-    if not intents:
-        print("意图列表为空：list-intents 返回空，且 --intents 也未指定", file=sys.stderr)
-        sys.exit(2)
-
-    quota = allocate_quota(args.total, intents)
-
-    cases = []
-    for intent in intents:
-        want = quota.get(intent, 0)
-        if want <= 0:
-            continue
-        try:
-            convs = client.get_conversations_by_intent(intent, limit=args.max_conversations)
-        except Exception as e:
-            print(f"  WARN: get_conversations_by_intent({intent}) failed: {e}",
-                  file=sys.stderr)
-            convs = []
-        print(f"  Loaded {len(convs)} conversations for intent '{intent}'",
-              file=sys.stderr)
-        # 取前 want 条（API 已经做了排序，这里不再重排）
-        for c in convs[:want]:
-            messages = _slim_messages(c.get("messages") or [], args.mode)
-            if not messages:
-                continue
-            case = {
-                "name": c.get("source_chat_id") or "",
-                "messages": messages,
-                "intent": intent,
-                "source_chat_id": c.get("source_chat_id", ""),
-            }
-            if args.with_metadata and c.get("metadata"):
-                case["metadata"] = c["metadata"]
-            cases.append(case)
-
-    os.makedirs(os.path.dirname(os.path.abspath(args.output)) or ".", exist_ok=True)
-    with open(args.output, "w", encoding="utf-8") as f:
-        json.dump(cases, f, ensure_ascii=False, indent=2)
-    print(f"Wrote {len(cases)} cases → {args.output}")
-
-
-if __name__ == "__main__":
-    main()

package/skills/kb-builder/SKILL.md

@@ -1,80 +0,0 @@
----
-name: kb-builder
-description: Shulex 知识库搭建与原子管理能力。用于目录管理，问答、文档、网页和产品知识的导入、查询、更新、状态管理与导出，以及标签、隔离关键词和回复模板管理。
-requires:
-  libs: [solvea-api]
----
-
-# Shulex KB Builder
-
-本 skill 提供知识库的原子管理能力、场景 reference 路由和通用执行规范。
-
-详细格式、字段、确认步骤和异常处理都以对应 reference 为准；只在命中具体场景时读取相关 reference。
-
-## 能力路由
-
-| 用户意图 | 读取的 interface / reference | 主要执行入口 |
-|---|---|---|
-| 网页建知识库、探查网站、设计目录 | [`interfaces/web-kb.md`](interfaces/web-kb.md)、[`references/directory.md`](references/directory.md) | `crawl_site.py`、`build_directory_plan.py`、`create_dirs.py` |
-| 网页/Word/PDF 保留原文 | 本文件“来源模式” | `import_source_documents.py` |
-| 网页/文件/工单整理成问答 | [`qa-quality.md`](references/qa-quality.md)、[`qa-from-web.md`](references/qa-from-web.md)、[`qa-from-help-center.md`](references/qa-from-help-center.md)、[`qa-from-pdf.md`](references/qa-from-pdf.md)、[`qa-from-tickets.md`](references/qa-from-tickets.md) | `extract_web_qa.py`、`batch_extract_ticket_qa.py`、`import_qa.py` |
-| 上传已有 QA 计划 | [`references/upload.md`](references/upload.md) | `import_qa.py` |
-| 回复模板库导入 | [`references/reply-template.md`](references/reply-template.md) | `import_templates.py` |
-| 查看、更新、移动、删除或改变知识状态 | [`references/knowledge.md`](references/knowledge.md) | 按 reference 提供的固定入口 |
-| 创建或更新产品知识 | [`references/product.md`](references/product.md) | `create-product-knowledge`、`update-product-knowledge` |
-| 导出知识 | [`references/export.md`](references/export.md) | `export_knowledge.py` |
-| 知识库目录管理 | [`references/directory.md`](references/directory.md) | 按 reference 提供的操作入口 |
-| 标签管理 | [`references/tags.md`](references/tags.md) | 按 reference 提供的操作入口 |
-| 隔离关键词及绑定 | [`references/isolation-keywords.md`](references/isolation-keywords.md)、[`references/tag-isolation-migration.md`](references/tag-isolation-migration.md) | 按 reference 提供的操作入口 |
-
-## 来源模式
-
-- 网页可保存为“网页”，也可整理成“问答”；Word/PDF 可保存为“文档”，也可整理成“问答”。
-- 用户只提供网址或文件时，默认准备保留原文，但提交前询问：直接保存原始资料，还是整理成问答？用户已明确要求 FAQ/问答时不重复确认。
-- 保留原文计划格式：`{"source": "URL 或本地文件路径", "dir_path": ["一级", "二级", "三级"]}`。多条记录组成 JSON 数组；Word/PDF 先通过 `read_file` 物化。
-- 先运行 `import_source_documents.py --plan-file <plan>` 预览，用户明确确认后再加 `--execute`。脚本对本次计划内 URL 去重；历史重复由后端处理，执行结果保留后端响应。
-
-## 基础查询入口
-
-以下是本 skill 约定的只读查询入口，按需直接使用；涉及写入、查重、迁移、导出或结果校验时，再读取对应 reference。不要自行猜测其他 CLI 命令。
-
-| 查询内容 | 固定命令 |
-|---|---|
-| 目录树 | `npx --yes @shulex/cxclawctl@latest api list-directories --pretty` |
-| 知识列表 | `npx --yes @shulex/cxclawctl@latest api list-knowledge --type ALL --page-size 50 --page 1 --pretty` |
-| 按关键词查知识 | `npx --yes @shulex/cxclawctl@latest api list-knowledge --keyword "关键词" --page-size 50 --pretty` |
-| 单条知识 | `npx --yes @shulex/cxclawctl@latest api get-knowledge --id <knowledge_id> --type {QA,LEARN_SELF,FILE,WEBSITE,PRODUCT} --pretty` |
-| 知识标签定义 | `npx --yes @shulex/cxclawctl@latest api list-knowledge-tags --pretty` |
-| 隔离关键词 | `npx --yes @shulex/cxclawctl@latest api list-isolation-keywords --page-size 50 --page 1 --pretty` |
-| 单条知识已绑定的隔离关键词 | `npx --yes @shulex/cxclawctl@latest api get-knowledge-isolation-keywords --id <knowledge_id> --type {QA,LEARN_SELF,FILE,WEBSITE,PRODUCT} --pretty` |
-| 回复模板 | `npx --yes @shulex/cxclawctl@latest api list-templates --page-size 50 --pretty` |
-
-`list-knowledge` 分页时先看返回的 `total`，再按需增加 `--page`；接口最大 `--page-size` 为 1000，不要用不断增大页大小的方式探测总量。
-
-## 写入入口索引
-
-以下能力仍由本 skill 提供，但必须先读对应 reference、展示变更计划并取得明确确认，再使用其中规定的参数：
-
-| 写入能力 | 固定入口 | 必读 reference |
-|---|---|---|
-| 更新问答 / AI自学习 / 文档 / 网页 | `update-knowledge` / `batch-update-knowledge` / `update-document-content` | [`knowledge.md`](references/knowledge.md) |
-| 创建或更新产品知识 | `create-product-knowledge` / `update-product-knowledge` / `batch-update-products` | [`product.md`](references/product.md) |
-| 删除、移动、发布/下架、显示/隐藏各类知识 | `operate-knowledge` | [`knowledge.md`](references/knowledge.md) |
-| 创建、重命名、移动或删除目录 | `create-folder` / `create_dirs.py` / `update-directory` / `move-directory` / `delete-directory` | [`directory.md`](references/directory.md) |
-| 导入问答 | `import_qa.py` | [`upload.md`](references/upload.md) |
-| 导入文档或网页 | `import_source_documents.py` | 本文件“来源模式” |
-| 修改知识标签 | `edit-knowledge-tags` | [`tags.md`](references/tags.md) |
-| 创建、修改、删除或绑定隔离关键词 | `create-isolation-keyword` / `update-isolation-keyword` / `delete-isolation-keyword` / `batch-update-isolation-keyword-bindings` | [`isolation-keywords.md`](references/isolation-keywords.md) |
-| 创建、修改或删除回复模板 | `create-template` / `update-template` / `delete-templates` | [`reply-template.md`](references/reply-template.md) |
-
-## 统一规则
-
-- 客户侧始终使用产品界面术语，并跟随用户的界面语言：中文使用“AI自学习 / 问答 / 文档 / 网页 / 产品”，英文使用“AI Self-learning / Q&A / Documents / Websites / Products”；不要向客户暴露 `QA`、`KU`、`FILE`、`DOCUMENT`、`WEBSITE` 等内部字段。
-- 网页和 Word/PDF 在执行前确认“保留原文”还是“整理成问答”；用户明确要求 FAQ/问答时才直接走 QA 流程。
-- 未明确指定时，目录默认最多三级；超过三级只能在用户明确要求后通过 `--max-depth` 覆盖。
-- 业务产物语言遵循：用户明确指定的产物语言 > 会话上下文中的用户界面语言偏好 > 用户当前消息语言。
-- 所有线上写入（创建目录、上传知识、修改知识、关键词变更）都必须先展示计划并等待明确确认。
-- 删除前必须展示影响范围，并获得同时表达“已知晓影响”和“确认删除”的强确认；简单的“确认 / OK / 可以”不足以授权删除。
-- 具体格式、目录规则、查重、结果校验和 API 参数以对应 reference 为准；不要把这些细节复制到本文件。
-
-根据用户明确意图读取上表对应 reference，再执行相应的原子能力。

package/skills/kb-builder/interfaces/qa-upload.md

@@ -1,55 +0,0 @@
-# QA Upload Interface
-
-公开能力：合并 QA parts 或现成 qa_plan，并上传到 Shulex 知识库。
-
-## Stable commands
-
-```bash
-# QA parts 合并 + dry-run
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py \
-  --from-dir /workspace/tmp/kb-builder/qa_parts/ \
-  --dry-run
-
-# 使用 dry-run 已落盘的 qa_plan 正式上传
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py \
-  --qa-file /workspace/outputs/kb-builder/qa_plan_<ts>.json
-
-# 或直接从 parts 合并并上传
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py \
-  --from-dir /workspace/tmp/kb-builder/qa_parts/
-```
-
-## Input qa item
-
-```json
-{
-  "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-  "question": "Kasa EP25 — What is the product overview?",
-  "answer": "Markdown answer"
-}
-```
-
-`dir_path` 必须是目录名数组，每一段都是一个实际文件夹名称。禁止写成字符串路径，例如
-`"/kb/B0117-03018-BK"` 或 `"Product Introduction/Speakers/B0117-03018-BK"`；这类输入会在
-dry-run 阶段失败。上传到已有目录前先用 `list-directories` 确认真实目录层级，并按该层级写数组。
-
-如果 `answer` 包含图片，必须保留 markdown 图片语法：
-
-```markdown
-![](https://example.com/image.png)
-```
-
-处理 DOCX / PDF / 网页来源时，优先使用能保留 markdown 图片的读取结果。不要把含图文档重新降级为
-纯段落文本后再生成 QA，否则会丢失图片但上传仍可能成功。
-
-## Guarantees
-
-- `--from-dir` 会合并多个 QA part 并输出 `qa_plan_<ts>.json`。
-- 正式上传前必须先 dry-run 并获得用户明确确认。
-- `dir_path` schema 错误会在 dry-run 和正式上传前失败，不会创建目录。
-- `answer` 使用 markdown；上传脚本透传 answer 内容，不会替调用方补图片。
-
-## Non-guarantees
-
-- 上传 API payload 结构不对调用方暴露。
-- 去重和目录匹配细节归 kb-builder 内部维护。

package/skills/kb-builder/interfaces/web-kb.md

@@ -1,84 +0,0 @@
-# Web KB Interface
-
-公开能力：从网站、产品站、帮助中心或文档站构建知识库目录与 QA，也支持在确认“保留网页原文”后创建网页资料。
-
-网页地址先做模式确认：保留原始网页时使用
-`../scripts/import_source_documents.py --plan-file <plan> --execute`；选择整理问答时才进入下面的 crawl → extract → import_qa 流程。
-
-## Modes
-
-```text
-auto    # 默认；适合网页整理的任务使用 crawl pipeline，其他任务走 legacy
-crawl   # 新脚本化网页 pipeline，可使用 Crawl4AI
-legacy  # 旧 reference + Tavily 工具路径，兼容历史行为
-```
-
-## Provider
-
-```text
-auto | crawl4ai | tavily
-```
-
-原则：
-
-- Crawl4AI 只用于适合网页抓取/整理的任务。
-- PDF / xlsx / qa_plan.json / 回复模板 / 导出 / 单条知识更新不使用 Crawl4AI。
-- Crawl4AI 作为 Python 依赖运行在 sandbox 内的 skill 脚本中，不接入主服务全局工具。
-- 默认 `provider=auto` 保持轻量兼容路径；需要 JS/动态页面抓取时显式使用 `provider=crawl4ai`。
-
-## Stable commands
-
-首版脚本化 pipeline 目标入口：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/crawl_site.py \
-  --url <source_url> \
-  --mode auto \
-  --provider auto \
-  --max-depth 3 \
-  --max-pages 100 \
-  --output /workspace/outputs/kb-builder/crawl_result_<ts>.json
-
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/build_directory_plan.py \
-  --crawl-result /workspace/outputs/kb-builder/crawl_result_<ts>.json \
-  --output /workspace/outputs/kb-builder/directory_plan_<ts>.json
-
-# 展示 directory_plan_<ts>.json，等待用户明确确认后写入 confirmed_tree
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/build_directory_plan.py \
-  --crawl-result /workspace/outputs/kb-builder/crawl_result_<ts>.json \
-  --output /workspace/outputs/kb-builder/directory_plan_<ts>.json \
-  --write-confirmed-tree
-
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/create_dirs.py
-
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/extract_web_qa.py \
-  --crawl-result /workspace/outputs/kb-builder/crawl_result_<ts>.json \
-  --output-dir /workspace/tmp/kb-builder/qa_parts
-```
-
-兼容路径：
-
-- `mode=legacy` 或 `provider=tavily` 时，按 `kb-builder/SKILL.md` 和对应 reference 走 legacy。
-- `provider=crawl4ai` 只在 sandbox 依赖可用时执行；失败时输出显式错误，不把调用方切到其他 skill 内部实现。
-
-## Outputs
-
-- `crawl_result_<ts>.json`
-- `directory_plan_<ts>.json`
-- `/workspace/state/kb-builder/confirmed_tree.json`
-- `/workspace/tmp/kb-builder/qa_parts/*.json`
-
-## Guarantees
-
-- 用户或上游 SOP 明确给出目录 schema 时，按输入 schema 生成目录树，不额外增加 Product Introduction 等默认根目录。
-- 未给出目录 schema 时，使用 kb-builder 默认标准模板：Product Introduction / Brand Policy / Help Center / Pending Assignment。
-- `Help Center` 仅在发现帮助中心/FAQ/文档站时创建。
-- QA parts 兼容 `import_qa.py --from-dir`。
-- `create_dirs.py` 前必须已经存在 `/workspace/state/kb-builder/confirmed_tree.json`；没有用户确认时不得写入或创建目录。
-- 调用方不需要知道 crawl provider 内部策略。
-
-## Non-guarantees
-
-- 页面顺序不保证稳定。
-- Markdown 具体格式不保证完全一致。
-- Crawl provider 的具体实现不对调用方暴露。