@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/kb-builder/references/isolation-keywords.md

@@ -1,113 +0,0 @@
-# 隔离关键词管理
-
-隔离关键词用于控制知识命中时的隔离条件。关键词资源和绑定关系分开管理；所有写入都必须先向用户展示变更并取得明确确认。
-
-## 接口
-
-接口前缀由 `SolveaClient` 根据环境自动选择：
-
-```text
-prod     /api_v2/qam
-staging  /sns_v1
-```
-
-项目 ID 使用当前 `projectId`。
-
-| 能力 | 方法与路径 | 请求/参数 |
-|------|------------|-----------|
-| 搜索/查询 | `GET /project/{projectId}/isolation_keywords` | `keyword`、`pageIndex`、`pageSize` |
-| 创建 | `POST /project/{projectId}/isolation_keyword` | `{ "keyword": "hihi,oo" }`；逗号分隔输入会拆成多个关键词 |
-| 修改 | `POST /project/{projectId}/isolation_keyword/{id}` | `{ "keyword": "new-value" }` |
-| 删除 | `DELETE /project/{projectId}/isolation_keyword/{id}` | 无请求体 |
-| 绑定/解绑 | `POST /project/{projectId}/knowledge/isolation_keywords/batch` | 见下文 |
-
-对应公开 CLI：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-isolation-keywords --keyword "invoice" --pretty
-npx --yes @shulex/cxclawctl@latest api create-isolation-keyword --keyword "invoice,test" --pretty
-npx --yes @shulex/cxclawctl@latest api update-isolation-keyword --id 17 --keyword "0226" --pretty
-npx --yes @shulex/cxclawctl@latest api delete-isolation-keyword --id 16 --confirm-delete --pretty
-npx --yes @shulex/cxclawctl@latest api get-knowledge-isolation-keywords \
-  --id 486955 --type FILE --pretty
-npx --yes @shulex/cxclawctl@latest api batch-update-isolation-keyword-bindings \
-  --data-file /workspace/state/kb-builder/isolation_keyword_binding.json --pretty
-```
-
-批量绑定命令的 JSON 文件在接口结构 `items`、`directoryIds`、`keywordIds` 之外，使用 `operation` 声明业务操作：`append`（追加）、`remove`（移除）或 `replace`（替换）。知识级操作省略时默认为 `append`。
-
-查询结果通常是数组，每项包含：
-
-```text
-id / keyword / bindCount / projectId / tenantId / createdAt / updatedAt
-```
-
-创建结果包含 `duplicate`、`failed`、`success`；成功项包含 `keyword` 和 `rowNo`。删除和批量绑定接口成功时通常返回 `ok`。
-
-## 绑定请求
-
-CLI 计划中的 `knowledgeType` 使用知识列表返回的界面类型：`QA`、`LEARN_SELF`、`FILE`、`WEBSITE` 或 `PRODUCT`。client 会按最新后端契约转换绑定类型：问答和 AI自学习 → `QA`，文档和网页 → `DOCUMENT`，产品 → `PRODUCT`。Agent 不要自行把列表类型改成后端类型，也不向客户暴露这些内部值。
-
-具体知识级绑定：
-
-```json
-{
-  "operation": "append",
-  "items": [
-    {
-      "knowledgeType": "QA",
-      "knowledgeId": 486955,
-      "keywordIds": [11, 13]
-    }
-  ],
-  "directoryIds": [],
-  "keywordIds": [11, 13]
-}
-```
-
-目录级绑定：
-
-```json
-{
-  "operation": "replace",
-  "confirmReplace": true,
-  "items": [],
-  "directoryIds": [32951],
-  "keywordIds": [11, 13]
-}
-```
-
-`directoryIds`、`items`、`keywordIds` 都可以省略；但三者同时为空时不得调用接口。一次请求只处理一种目标：`items` 或 `directoryIds` 二选一，避免目录级和知识级语义混淆。client 会拒绝空更新、校验 ID、并对数组去重。
-
-后端绑定接口始终把提交的关键词 ID 当作最终集合，会先删除旧关系再写入新关系。CLI 对具体知识会自动读取现有绑定并按 `operation` 计算最终集合；读取失败时停止，不得猜测。目录级接口不能安全读取和合并目录内每条知识的现状，因此只允许显式 `replace`，并要求 `confirmReplace: true`。
-
-## 绑定与解绑流程
-
-1. 用 `list_isolation_keywords` 搜索关键词，确认目标关键词 ID；不存在时先创建。
-2. 绑定目录前用 `list-directories` 获取真实 `directoryId`，不要根据目录名称猜 ID。
-3. 绑定具体知识前用 `list-knowledge` 获取 `knowledgeId` 和类型，再用带 `--type` 的 `get-knowledge` 读取详情。
-4. 追加使用 `operation: "append"`，移除使用 `operation: "remove"`；两者都由 CLI 读取当前关系并计算最终集合。只有用户明确要求覆盖全部绑定时才使用 `operation: "replace"` 和 `confirmReplace: true`。
-5. 展示变更差异并取得用户明确确认后调用 `batch_update_isolation_keyword_bindings` 提交；没有现状快照不得提交。
-6. 调用 `get-knowledge-isolation-keywords --id ... --type ...` 回读绑定结果；结果不符合预期时停止，不自动覆盖重试。
-
-不要把关键词文本直接当作 `keywordIds`；绑定接口要求使用隔离关键词的数字 ID。目录绑定和知识绑定都必须保留目标对象的真实 ID。
-
-## 创建关键词前的查重
-
-用户要求新建关键词时，禁止直接调用创建接口。必须先执行：
-
-1. 用 `list_isolation_keywords` 分页拉取当前项目的关键词（需要全量查重时按 `totalCount` / 分页结果继续查询）。
-2. 将用户输入按逗号拆分、去除首尾空格并在本次输入内去重。
-3. 与现有关键词按规范化后的精确文本匹配；把已存在的关键词单独列出并告知用户，不重复提交。
-4. 只对不存在的关键词发起创建，并在写入前向用户展示待创建清单、重复清单和失败风险，取得明确确认。
-5. 根据创建响应的 `success`、`duplicate`、`failed` 汇报结果；创建失败的项不得自动重试或改名。
-
-如果所有输入都已存在，不调用创建接口，只告知用户现有关键词及其 ID，并继续询问是否需要绑定。
-
-## 用户交互要求
-
-- 用户说“建立隔离关键词 xxx”时，先解析并去重关键词，再展示将创建的列表。
-- 新建前必须先查询当前关键词并查重；重复项要明确告知用户，只创建不存在的项。
-- 创建完成后，询问是否绑定到某个知识目录；用户明确说不绑定时，仅创建关键词。
-- 用户指定目录名时，先查询目录树并展示匹配目录，确认后再绑定。
-- 删除关键词前检查 `bindCount`，提示可能影响的知识/目录；要求用户回复“我已知晓删除影响并确认删除”或等价强确认，然后才能使用 `--confirm-delete`。

package/skills/kb-builder/references/knowledge.md

@@ -1,153 +0,0 @@
-# 知识读取、更新与状态管理
-
-## 列表与详情的类型边界
-
-知识列表统一使用 `list-knowledge` / `getKnowledge`。后端返回同一套列表结构，但不同界面类型填充的字段不同：
-
-- 问答 / AI自学习：主要是 `question`、`answer`
-- 文档：主要是 `name`、`title`、`storageSize`
-- 网页：主要是 `name`、`title`、`url`
-- 产品：主要是 `productTitle`、`productId`、`sku`、`spuUrl` 等商品字段
-
-每条列表记录都使用统一的 `knowledgeId`、`directoryId`、`type`、`knowledgeStatus`、`isolationKeywords`。必须保留并使用记录返回的类型，不能只拿 ID 猜实体。
-
-详情接口按实体拆分：问答/AI自学习走 KU，文档/网页走 DOCUMENT，产品走 KU_PRODUCT。统一 CLI 用 `--type` 选择正确详情接口；这里的内部实体名只用于实现判断，不用于客户话术。
-
-## 读取
-
-已知知识 ID 时读取准确详情，不用关键词列表代替：
-
-QA / AI自学习知识：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-knowledge --id 3057821 --type QA --pretty
-```
-
-文档 / 网页知识使用同一个业务入口，但必须带对应类型；脚本会调用文档详情接口，而不是 QA 的详情接口：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-knowledge --id 3057821 --type FILE --pretty
-npx --yes @shulex/cxclawctl@latest api get-knowledge --id 3057821 --type WEBSITE --pretty
-```
-
-产品知识：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-knowledge --id 3057821 --type PRODUCT --pretty
-```
-
-## 更新问答 / AI自学习知识
-
-当前 `update-knowledge` 对应 KU 更新接口，不用于文档、网页或产品。文档/网页内容更新需要文档更新原子能力，不能拿本命令代替。
-
-1. 先读取当前知识，确认 ID、标题、内容和目录。
-2. 只把要修改的字段写入稳定文件 `/workspace/state/kb-builder/knowledge_update.json`。
-3. 向用户展示字段级变更，等待明确确认。
-4. 确认后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api update-knowledge --id 3057821 --data-file /workspace/state/kb-builder/knowledge_update.json --pretty
-```
-
-5. 再次读取同一 ID，核对实际结果。
-
-更新文件支持 `title`、`content`、`published`、`directoryId`、`status`、`forceIndex`。仅写需要修改的字段；除非明确需要重建或删除索引，不要设置 `forceIndex`。
-
-### 批量更新问答正文 / 标题
-
-当需要修改多条问答知识时，严禁使用循环单条 `update-knowledge`，应使用批量更新命令 `batch-update-knowledge`。
-
-将待修改列表写入 `/workspace/state/kb-builder/batch_knowledge_update.json`：
-
-```json
-[
-  {
-    "kuId": 3057821,
-    "content": "修改后的答案正文",
-    "directoryId": 145177
-  },
-  {
-    "kuId": 3057822,
-    "content": "修改后的答案正文",
-    "directoryId": 145178
-  }
-]
-```
-
-执行批量更新：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api batch-update-knowledge --data-file /workspace/state/kb-builder/batch_knowledge_update.json --pretty
-```
-
-- 每条记录支持 `kuId`（或 `id`）、`title`、`content`、`directoryId`、`published` 等字段。
-- 建议优先带上扫描时已获取的 `directoryId`；若未带 `directoryId`，CLI 会自动向后兼容继承原目录。
-- 批量更新建议单批 50~100 条。
-
-## 更新文档 / 网页正文
-
-文档和网页共用同一个正文更新入口。CLI 会先读取当前详情，保留目录、文件名和元数据，再合并本次变更；不要用 `update-knowledge` 更新这两类知识。
-
-将新正文写入 `/workspace/state/kb-builder/document_update.json`：
-
-```json
-{
-  "fileText": "更新后的 Markdown 或文本正文",
-  "title": "可选的新标题"
-}
-```
-
-展示变更摘要并获得确认后执行：
-
-```bash
-# 文档
-npx --yes @shulex/cxclawctl@latest api update-document-content --id 3057821 --type FILE --data-file /workspace/state/kb-builder/document_update.json --pretty
-
-# 网页
-npx --yes @shulex/cxclawctl@latest api update-document-content --id 3057821 --type WEBSITE --data-file /workspace/state/kb-builder/document_update.json --pretty
-```
-
-更新后用原类型重新读取详情。`filePath` 仅用于已上传的新 Markdown 文件；普通正文修改使用 `fileText`。
-
-## 删除、移动、发布状态与可见性
-
-这些操作支持界面上的五类知识。对客户只说“问答 / AI自学习 / 文档 / 网页 / 产品”；下表字段仅用于脚本计划文件：
-
-| 界面操作 | `operateType` |
-|---|---|
-| 删除 | `DELETE` |
-| 移动到目录 | `MOVE`，同时传 `directoryId` |
-| 发布 | `PUBLISH` |
-| 下架 | `UNPUBLISH` |
-| 显示 | `VISIBLE` |
-| 隐藏 | `INVISIBLE` |
-
-计划文件 `/workspace/state/kb-builder/knowledge_operations.json` 是 JSON 数组：
-
-```json
-[
-  {"knowledgeType": "FILE", "knowledgeId": 3057821, "operateType": "MOVE", "directoryId": 32188},
-  {"knowledgeType": "WEBSITE", "knowledgeId": 3057822, "operateType": "UNPUBLISH"},
-  {"knowledgeType": "PRODUCT", "knowledgeId": 3057823, "operateType": "INVISIBLE"}
-]
-```
-
-执行前必须：
-
-1. 用 `get-knowledge --id ... --type ...` 读取每个目标，确认 ID 和界面类型一致。
-2. 删除要列出具体标题和数量；移动要列出原目录和目标目录；状态变更要列出变更前后。
-3. 等待用户明确确认。不得把“查看一下”视为删除或状态变更授权。
-
-删除操作需要更强确认：展示影响后，要求用户明确回复“我已知晓删除影响并确认删除”或语义等价、同时包含“知晓影响”和“确认删除”的表达。英文用户可回复 `I understand the deletion impact and confirm deletion.`。只回复“确认”、`OK` 或“可以”不足以授权删除。
-
-确认后执行：
-
-```bash
-# 非删除操作
-npx --yes @shulex/cxclawctl@latest api operate-knowledge --data-file /workspace/state/kb-builder/knowledge_operations.json --pretty
-
-# 计划中包含删除时，仅在收到上述强确认后增加
-npx --yes @shulex/cxclawctl@latest api operate-knowledge --data-file /workspace/state/kb-builder/knowledge_operations.json --confirm-delete --pretty
-```
-
-CLI 会再次按类型读取每个目标，移动时还会确认目标目录存在，然后一次提交。提交后重新查询：删除要确认记录已不存在，其他操作要核对目录、发布状态或可见性。

package/skills/kb-builder/references/product.md

@@ -1,52 +0,0 @@
-# 产品知识创建与更新
-
-本 reference 只用于界面上的“产品”知识。对客户使用“产品 / Products”，不暴露内部实体名。
-
-## 创建
-
-创建计划写入 `/workspace/state/kb-builder/product_create.json`。至少包含：
-
-- `title`：产品名称
-- `spuUrl`：产品页地址，同一项目内不能重复
-
-常用可选字段包括 `describe`、`image`、`price`、`compareAtPrice`、`currency`、`skuList`、`directoryId`、`metadata`、`specialTagMap`、`published`和 `isVisible`。CLI 默认补齐手工创建来源、已发布和已显示；如果用户要求其他状态，在计划中显式写出。
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-product-knowledge --data-file /workspace/state/kb-builder/product_create.json --pretty
-```
-
-## 更新
-
-产品更新接口要求完整产品数据。使用下面的 CLI 时，它会先读取现有产品，再将变更字段合并到完整对象后提交，避免清空 SKU、图片、目录或状态。
-
-只将要改的字段写入 `/workspace/state/kb-builder/product_update.json`，展示字段级 diff 并等待确认，然后执行：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api update-product-knowledge --id 3057823 --data-file /workspace/state/kb-builder/product_update.json --pretty
-```
-
-如果现有产品缺少后端更新所必需的标题、描述、产品地址、图片、来源、发布状态或可见性，CLI 会拒绝提交并列出缺失字段；先让用户补齐，不自行编造。更新后用 `get-knowledge --type PRODUCT` 重新读取核对。
-
-## 批量更新产品状态
-
-当需要批量设置多个产品的状态（如批量设为主推、批量启用/停用）时，使用 `batch-update-products` 命令：
-
-将批量计划写入 `/workspace/state/kb-builder/batch_products_update.json`：
-
-```json
-[
-  { "id": 3057823, "mainPush": true },
-  { "id": 3057824, "enable": false }
-]
-```
-
-执行批量更新：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api batch-update-products --data-file /workspace/state/kb-builder/batch_products_update.json --pretty
-```
-
-- 每条记录支持 `id`（或 `kuProductId`）、`mainPush`（主推）、`enable`（或 `published`）。
-- **注意**：该批量接口仅用于更新商品的主推与启停状态；若需修改商品标题、描述、价格或 SKU 等内容，请使用单条 `update-product-knowledge`。
-
-产品的删除、移动、发布/下架、显示/隐藏统一按 [`knowledge.md`](knowledge.md) 的 `operate-knowledge` 流程执行。

package/skills/kb-builder/references/qa-from-help-center.md

@@ -1,58 +0,0 @@
-# 从帮助中心 / FAQ / 文档站提取 QA
-
-→ 通用质量规则见 `/skills/kb-builder/references/qa-quality.md`（必读）
-
-帮助中心目录在 KB 里建好后，此处直接提取知识内容。这里也适用于用户直接提供的 FAQ 页面、文档站、支持站、知识库文章列表。
-
-## 流程
-
-1. **拿帮助中心页面 URL 列表**：
-   - 优先从 `crawl_cache.json` 取出 `type == "help_center"` 的页面
-   - cache 不存在或不全 → 用户给帮助中心根 URL → `web_crawl(url=root, max_depth=2, limit=80)` 单独深抓一次
-2. **逐页 `web_fetch`** 拿完整 markdown（cache 里 snippet 只有 1200 字符不够）
-3. **提取 Q&A**：
-   - 页面本身已有明确的 FAQ / Q&A 结构（条目标题即问题、正文即答案）→ 按 `qa-quality.md` 的全局 FAQ 规则逐条提取
-   - 页面无明确 FAQ 结构（如产品说明、政策说明等连续正文）→ 自行归纳整理成 Q&A
-4. **归入 KB 中现有的 Help Center 子目录**（如 KB 已有「Getting Started > Setup Guide」），**不重新发明目录**
-5. 一个帮助页面若包含多个独立话题，可拆分为多条 QA
-
-## Help Center / 文档站 FAQ 条数规则
-
-帮助中心 / 文档站 / 支持站里的 FAQ / Q&A 页面不受 `qa-from-web.md` 中“产品整体介绍 1 条 + 潜在问题 ≤5 条”的产品页规则限制。
-
-- 有明确 FAQ 条目的页面：按页面上的有效条目逐条提取，原则上不压缩条数
-- 只有连续正文、没有 FAQ 结构的页面：按独立主题归纳为 QA
-- 真正的数量控制只在写文件和上传阶段：按 `upload.md` 每批 ≤4 KB 分片，避免截断
-
-## 示例
-
-```json
-{
-  "dir_path": ["Help Center", "Getting Started", "Setup Guide"],
-  "question": "Kasa Smart Plugs — How do I set up my Kasa smart plug for the first time?",
-  "answer": "1. Download the Kasa Smart app (iOS / Android)\n2. Open the app → tap '+' → select your device\n3. Follow the in-app setup wizard\n4. Connect to your 2.4GHz Wi-Fi network\n5. Name your device and assign it to a room\n\n![Kasa app setup](https://example.com/setup.png)"
-}
-```
-
-## 目录前置自查
-
-`list-directories` 看现有 Help Center 子目录树。提取过程中遇到帮助中心新栏目而 KB 还没建对应子目录时：
-- 该栏目内容不多 → 临时 `create-folder` 补建（详见 directory.md §5）
-- 实在难归类 → `["Pending Assignment"]`
-
-## 产出文件（每批写到 tmp）
-
-提取的 QA **不要**自己合并成 qa_plan，**也不要**一次 write_file 写完整数组。
-每批 ≤ 4 KB 写到 `/workspace/tmp/kb-builder/qa_parts/qa_help_<topic>.json`（如 `qa_help_setup.json` / `qa_help_troubleshooting.json`），
-最后由 `import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/` 自动合并 + 上传。
-
-详见 `/skills/kb-builder/references/upload.md`。
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| 帮助中心目录建好了但没提取知识 | 帮助中心页面内容也要提取为 QA |
-| 自己发明 Help Center 子目录而非照搬网站导航 | Help Center 子目录直接对齐网站真实导航 |
-| 只看 cache snippet 就写 QA | 必须 web_fetch 全文 |
-| FAQ 页面只抽 5 条 | FAQ 按有效条目逐条提取，不套产品页 ≤5 条潜在问题限制 |

package/skills/kb-builder/references/qa-from-pdf.md

@@ -1,94 +0,0 @@
-# 从产品说明书 PDF 提取 QA
-
-→ 通用质量规则见 `/skills/kb-builder/references/qa-quality.md`（必读）
-
-## 读 PDF：直接用 `read_file`
-
-**直接 `read_file` 读 PDF**，不要 inline `python3 -c "import pymupdf4llm..."`。read_file 工具内部已经把 PDF 解析链路封装好：
-
-- 对 `.pdf` 后缀自动走 MinerU API（OCR + 结构识别）→ 失败或未配置 token 时 fallback 到 `pymupdf4llm`
-- 解析结果按 markdown 返回，保留标题 / 段落 / 表格 / 列表 / 图片占位，已是 KB 期望的格式
-- 同轮内缓存到 `workspace/tmp/parsed/{file_name}.md`，重复读不会重新解析
-- 返回带行号 `lines X-Y of N`，长说明书用 `offset` / `limit` 分段读
-
-```
-read_file(file_path="/mounted/chat-files/user/manual.pdf")
-# 长 PDF 分段：
-read_file(file_path="/mounted/chat-files/user/manual.pdf", offset=0, limit=200)
-read_file(file_path="/mounted/chat-files/user/manual.pdf", offset=200, limit=200)
-```
-
-⚠️ **单次返回上限 ~32K chars**。超出时 read_file 会直接报 "Requested range is too large" 并给建议 `limit`，按提示调小再读，不要试图绕过。
-
-确认内容结构后，按下面规则拆 QA。
-
-## 目录前置自查
-
-提取前先 `list-directories` 看 Product Introduction 下是否已有本说明书产品的品类 / 型号目录。
-缺品类（如新出的"Diagnostic Scanners"）或型号目录 → 用 `create-folder` CLI 补建（详见 directory.md §5）。
-**不要回头跑全流程目录搭建**——补建单个目录就够了。
-
-## 拆 QA 规则
-
-对每份说明书，生成**两类** QA：
-
-### 第一类：说明书全文 QA（每份说明书 1 条）
-
-- Q：`[型号] — User Manual / Product Manual`
-- A：完整解读说明书全部内容，**保留 PDF 中的图片、表格、排版结构**，格式规范清晰
-
-```json
-{
-  "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-  "question": "Kasa EP25 Smart Plug — User Manual",
-  "answer": "## Package Contents\n- 1x EP25 Smart Plug\n- 1x Quick Start Guide\n\n## Setup\n1. Plug into wall outlet\n2. Download Kasa app\n3. Follow in-app setup wizard\n\n## Specifications\n| Spec | Value |\n|------|-------|\n| Voltage | 120V AC |\n| Max Load | 15A / 1800W |\n| Dimensions | 2.1\" x 1.4\" x 1.4\" |"
-}
-```
-
-### 第二类：说明书潜在问题（按内容密度拆，**不设条数上限**）
-
-按说明书的独立子主题逐一拆 QA——每个独立功能 / 设置项 / 配件 / 故障排查问题都各成一条。覆盖参考维度：
-
-- 产品概述（What is X / Key features）
-- 包装清单 / 配件
-- 技术规格 / 兼容性 / 适配范围
-- 安装 / 连接 / 首次设置
-- 各独立功能的使用步骤（按章节拆，每个功能 1 条）
-- 设置项（语言 / 单位 / WiFi / 自检 / 恢复出厂等）
-- 软件更新流程
-- 故障排查（每个独立问题 1 条）
-- 安全 / 警告事项（如有）
-
-> 一份功能丰富的说明书（多功能诊断仪、多模式智能设备等）拆出 15~30 条 QA 是常见的；**不要为了控制条数把多个独立功能塞进同一条 answer**。同一功能的多个步骤可合并；不同功能必须拆开。
-
-```json
-[
-  {
-    "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-    "question": "Kasa EP25 Smart Plug — What accessories are included in the box?",
-    "answer": "- 1x Kasa EP25 Smart Plug\n- 1x Quick Start Guide"
-  },
-  {
-    "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-    "question": "Kasa EP25 Smart Plug — How do I install and set up the EP25?",
-    "answer": "1. Plug the EP25 into any standard 120V wall outlet\n2. Download the Kasa Smart app\n3. Tap '+' to add a new device\n4. Follow the in-app setup wizard to connect to Wi-Fi"
-  }
-]
-```
-
-## 产出文件（每批写到 tmp）
-
-提取的 QA **不要**自己合并成 qa_plan，**也不要**一次 write_file 写完整数组。
-每批 ≤ 4 KB 写到 `/workspace/tmp/kb-builder/qa_parts/qa_pdf_<model>_<part>.json`，
-最后由 `import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/` 自动合并 + 上传。
-
-详见 `/skills/kb-builder/references/upload.md`。
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| inline `python3 -c "import pymupdf4llm..."` | 直接 `read_file(file_path="...pdf")` |
-| 说明书只按段落切 QA | 必须生成两类：全文 1 条 + 按内容密度拆潜在问题 |
-| 说明书潜在问题被压到 5 条以内、多个独立功能塞进同一条 answer | 无 ≤5 上限，每个独立功能 / 设置项 / 故障排查 / 配件主题独立成条 |
-| 缺品类目录就归到 Pending Assignment | 优先 `create-folder` 补建对应品类 / 型号目录 |

package/skills/kb-builder/references/qa-from-tickets.md

@@ -1,168 +0,0 @@
-# 从历史工单 xlsx 提取 QA
-
-→ 通用质量规则见 `/skills/kb-builder/references/qa-quality.md`（必读）
-
-工单原始对话含有噪声（情绪语言、订单号、客服套话），不能直接粘贴进知识库。流程：读表头样例 → 判断数据源列 → dry-run → 分页/并发提炼到 state → 汇总去重到 outputs → 用户确认后再 dry-run 上传。
-
-## 步骤一：检测 xlsx 格式
-
-**直接 `read_file` 读 xlsx**，不要 inline `python3 -c "import pandas..."`。read_file 工具内部用 markitdown 把 xlsx 转成 markdown 表格：
-
-- 每个 sheet 输出一段 `## SheetName` + 列名表头 + 数据行
-- 直接看到列名、行数（看返回的 `lines X-Y of N`）、前几行内容样例
-- 同一份 xlsx 同轮内缓存到 `workspace/tmp/parsed/`，重复读不会重新解析
-- 单 cell 超过 500 字符会被截断（middleware 层 `_MAX_LINE_CHARS`），看格式 / 列名足够；长对话原文走 `extract_ticket_qa.py` 全量提炼时再处理
-
-```
-read_file(file_path="/mounted/chat-files/user/tickets.xlsx", limit=20)
-```
-
-返回示例：
-
-```
-File: tickets.xlsx (lines 1-20 of 532)
-
-## Sheet1
-| conversation_id | customer_message | agent_reply |
-| --- | --- | --- |
-| T001 | my charger broke | please send photos of the damaged item |
-| T002 | battery drains fast | check motion sensitivity in app settings |
-...
-```
-
-⚠️ 同样有 ~32K chars 上限。检测列名只读前 20 行就够，不要全文加载。
-
-| 格式 | 特征 | 处理方式 |
-|------|------|----------|
-| **Shulex 导出** | 有 `conversations` 列 | 直接解析对话序列 |
-| **自定义系统导出** | 列名不固定 | 自动检测问题列 / 回复列 |
-
-## 步骤二：判断数据源列
-
-先根据表头和前几行判断真实客诉对话列，像 POC / Delivery 分类脚本一样显式传给脚本：
-
-| 参数 | 用途 | 常见列名 |
-|------|------|----------|
-| `--messages-col` | 完整对话列；或客户问题列 | `conversations` / `messages` / `comments_json` / `conversation` / `聊天记录` / `对话内容` / `customer_message` |
-| `--title-col` | 工单标题 / 主题（可选） | `subject` / `title` / `主题` / `工单标题` |
-| `--reply-col` | 客服回复列（仅问答分列时传） | `agent_reply` / `reply` / `answer` / `客服回复` |
-
-如果无法判断哪列是真实客诉对话，不要直接跑提取；先问用户确认列名。
-
-脚本保留自动检测兜底，但 agent 应优先显式传列名。
-
-## 步骤三：dry-run 确认提取逻辑
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/extract_ticket_qa.py \
-  --xlsx /mounted/chat-files/user/tickets.xlsx --brand "{品牌名称}" \
-  --messages-col conversations --title-col subject \
-  --page 1 --page-size 100 --batch-size 5 --workers 3 --dry-run
-```
-
-dry-run 必须检查：
-
-- `[detect]` 里的 `messages_col` / `reply_col` / `title_col` 是否符合表头判断
-- sample thread 是否是真实客诉对话
-- `Would call model=<模型> X times` 是否合理
-
-## 步骤四：批量分页运行提炼（OpenAI-compatible 模型）
-
-历史工单必须分页处理，避免单轮超过 20 分钟 SSE 上限。`page` 从 1 开始，`page-size` 最大 100。
-
-推荐优先用批处理 wrapper，一次处理完整 xlsx，但内部仍按页跑：
-
-```bash
-# 全表分页提取：每页 100 行，页内每 5 条对话一次模型调用，并发 3 个 batch
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/batch_extract_ticket_qa.py \
-  --xlsx /mounted/chat-files/user/tickets.xlsx --brand "{品牌名称}" \
-  --messages-col conversations --title-col subject \
-  --page-size 100 --batch-size 5 --workers 3 --resume
-```
-
-wrapper 行为：
-
-- 每页产物写入 `/workspace/state/kb-builder/ticket_extract/pages/page_001.json`
-- 进度写入 `/workspace/state/kb-builder/ticket_extract/progress.json`
-- 失败后可用同一命令 `--resume` 续跑，已完成 page 会跳过
-- 最终合并、过滤、去重后输出 `/workspace/outputs/kb-builder/ticket_qa_merged_<ts>.json`
-- **不会上传知识**
-
-必要时也可以只跑单页 worker（调试或补页）：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/extract_ticket_qa.py \
-  --xlsx /mounted/chat-files/user/tickets.xlsx --brand "{品牌名称}" \
-  --messages-col conversations --title-col subject \
-  --page 2 --page-size 100 --batch-size 5 --workers 3
-```
-
-## 步骤五：用户确认后再上传
-
-批处理完成后，先向用户展示：
-
-- 总行数 / 完成页 / 失败页
-- 模型调用数 / 提取数 / 过滤数 / 去重数
-- merged 输出文件路径
-- 3-5 条样例 QA
-
-用户确认后，再按 upload.md 进入 `import_qa.py --dry-run`。dry-run 通过后，用户再次确认才正式上传。
-
-## 工单来源特有过滤规则
-
-| 场景 | 处理方式 |
-|------|---------|
-| 与产品无关（发票 / 物流 / 订单流程） | 整条工单跳过，不提炼 |
-| 产品物理破损（摔坏 / 撞坏 / 外壳损坏） | 整条工单直接忽略 |
-| 向客户索要订单号 / 收据 / 照片 | 删除该句 |
-| 引导联系客服 / 提交工单 | 删除该句 |
-
-## 同一问题多种表达合并（重要）
-
-如果多个消费者表达了同一个产品问题但措辞不同，将多种表达**合并**进同一条 QA 的 Question 里：
-
-```json
-{
-  "question": "Kasa EC70 Camera — Why is my camera battery draining fast / discharging quickly / running out of charge quickly?",
-  "answer": "- Check motion sensitivity settings — high sensitivity triggers more recordings\n- Reduce clip length in app settings\n- Enable scheduled recording only during active hours\n- Ensure firmware is up to date"
-}
-```
-
-## 目录归类
-
-工单提炼出的知识**统一归入 Product Introduction** 目录下的对应产品文件夹：
-
-- 能识别产品型号 → `["Product Introduction", "<品类>", "<产品名>"]`
-- 只能识别品类 → `["Product Introduction", "<品类>"]`
-- 无法识别产品 → `["Pending Assignment"]`
-
-提取前用 `list-directories` 自查目录是否齐全；缺则 `create-folder` 补建（详见 directory.md §5）。
-
-## 产出文件（接入 tmp 合并流程）
-
-批处理 wrapper 的分页中间产物在 `/workspace/state/kb-builder/ticket_extract/pages/`，最终汇总产物在：
-
-```
-/workspace/outputs/kb-builder/ticket_qa_merged_<ts>.json
-```
-
-要把最终汇总产物接入合并上传流程时，**复制一份**到 tmp 目录（保留产物原文件）：
-
-```bash
-cp /workspace/outputs/kb-builder/ticket_qa_merged_<ts>.json /workspace/tmp/kb-builder/qa_parts/qa_tickets_<brand>.json
-```
-
-然后由 `import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/` 与其他来源一起合并上传。
-
-详见 `/skills/kb-builder/references/upload.md`。
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| 直接把工单原文粘贴进知识库 | 必须经过 `extract_ticket_qa.py` 提炼 |
-| 工单里有物理破损场景也提炼了 | 物理破损整条工单直接忽略 |
-| 无关工单（发票 / 物流 / 订单）也提炼 | 整条工单跳过 |
-| 同一产品问题多种表达各自成条 | 合并到同一条 QA 的 Question 里 |
-| 工单 QA 放进 Help Center | 工单知识统一归 Product Introduction 对应产品目录 |
-| 续跑时重复处理前 600 行 | 用 `--page 6 --page-size 100` 只跑第 501-600 行 |