@shulex/cxclawctl 0.1.2 → 0.1.4

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

@@ -1,98 +0,0 @@
-# 从网站产品/政策页提取 QA
-
-→ 通用质量规则见 `/skills/kb-builder/references/qa-quality.md`（必读）
-
-## 数据来源优先级
-
-**优先读取已有的爬取缓存**（`workspace/state/kb-builder/crawl_cache.json`），不重复爬取。
-
-用 `read_file` 工具读取 cache，按 `pages` 中的 `type` 字段分类处理：
-- `type == "product"` → Product Introduction
-- `type == "policy"` → Brand Policy
-- `type == "help_center"` → 走 `qa-from-help-center.md`
-- `type == "other"` → 跳过
-
-⚠️ cache 里的 `snippet` 只有 ≤1200 字符摘要，**做 QA 必须对每个目标 URL 单独调 `web_fetch(url=...)` 拿全文**（产品规格、政策原文、表格图片等只在全文里）。
-
-如果 cache 不存在（用户跳过了网站探查阶段，直接给若干产品页 / 政策页 URL）→ 直接对每个 URL 用 `web_fetch` 拿全文，按下面规则提取。
-
-## FAQ / Q&A 结构
-
-任何网站页面只要正文里有明确 FAQ / Q&A 结构，先按 `qa-quality.md` 的 FAQ 规则逐条提取，再按页面上下文归类：
-
-- 产品详情页里的产品 FAQ → `Product Introduction` 对应品类 / 型号目录
-- 政策页里的政策 FAQ → `Brand Policy` 对应政策目录
-- 帮助中心 / 文档站 / 支持站 FAQ → `Help Center` 对应真实导航目录
-
-FAQ 条数**不受**“产品整体介绍 1 条 + 潜在问题 ≤5 条”限制；页面有多少有效 FAQ 条目就提取多少条，只受 `upload.md` 的分批大小限制。
-
-## 1. 品牌政策知识（→ Brand Policy 目录）
-
-从政策页提取：售后政策、退换货政策、物流政策、质保 / 保修政策。
-
-每条政策生成 1 条 QA，归入对应 Brand Policy 二级目录：
-
-```json
-{
-  "dir_path": ["Brand Policy", "Warranty Policy"],
-  "question": "Kasa Smart Products — What is the warranty period and coverage?",
-  "answer": "- 18-month limited warranty from date of purchase\n- Covers manufacturing defects and hardware failures\n- Does not cover physical damage, water damage, or misuse\n- Warranty valid for original purchaser only"
-}
-```
-
-## 2. 产品落地页知识（→ Product Introduction 目录）
-
-对每个产品详情页，生成**两类** QA：
-
-**第一类：产品整体介绍**（每款产品 1 条）
-- Q：`[型号] — Product Overview` 或 `What is the [型号] and what does it do?`
-- A：详细产品描述、规格参数、尺寸、功能、卖点、产品对比、购买链接
-- **必须保留**落地页上的图片（`![描述](图片URL)`）和表格
-
-```json
-{
-  "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-  "question": "Kasa EP25 Smart Plug — What is the Kasa EP25 and what does it do?",
-  "answer": "The Kasa EP25 is a dual-outlet smart plug with built-in energy monitoring.\n\n**Key Features:**\n- Two independently controlled outlets\n- Real-time energy monitoring\n- Compatible with Alexa, Google Home, and Apple Home\n- Max load: 15A / 1800W\n\n**Dimensions:** 2.1\" x 1.4\" x 1.4\"\n\n![Kasa EP25](https://example.com/ep25.jpg)\n\n| Feature | EP25 | EP10 |\n|---------|------|------|\n| Dual outlet | ✓ | ✗ |\n| Energy monitor | ✓ | ✗ |"
-}
-```
-
-**第二类：产品潜在问题**（每款产品 ≤5 条）
-
-参考落地页信息，生成消费者可能会问的具体问题（颜色规格、尺寸参数、功能差异等）。如果产品页本身已有 FAQ / Q&A 结构，FAQ 逐条提取，不占用这 ≤5 条“自行归纳潜在问题”的额度：
-
-```json
-[
-  {
-    "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-    "question": "Kasa EP25 Smart Plug — What colors does the EP25 come in?",
-    "answer": "The Kasa EP25 is available in White only."
-  },
-  {
-    "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-    "question": "Kasa EP25 Smart Plug — What is the maximum wattage the EP25 supports?",
-    "answer": "The Kasa EP25 supports a maximum load of 15A / 1800W per outlet."
-  }
-]
-```
-
-## 目录前置自查
-
-提取前先 `list-directories` 看现有目录是否覆盖本次产品的品类 / 型号，缺则用 `create-folder` 补建（详见 directory.md §5）。
-
-## 产出文件（每批写到 tmp）
-
-提取的 QA **不要**自己合并成 qa_plan，**也不要**一次 write_file 写完整数组。
-每批 ≤ 4 KB 写到 `/workspace/tmp/kb-builder/qa_parts/qa_web_<topic>.json`（如 `qa_web_policy.json` / `qa_web_kasa-ep25.json`），
-最后由 `import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/` 自动合并 + 上传。
-
-详见 `/skills/kb-builder/references/upload.md`。
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| 只看 cache 里 1200 字 snippet 就生成 QA | 必须 web_fetch 全文 |
-| 产品落地页只生成一类 QA | 两类必须都有：整体介绍 + ≤5 条潜在问题 |
-| 产品页已有 FAQ 但只抽 5 条或放进 Help Center | FAQ 逐条提取，归 Product Introduction 对应产品目录 |
-| 政策 QA 放进 Help Center 或 Product Introduction | 政策只进 Brand Policy 对应二级目录 |

package/skills/kb-builder/references/qa-quality.md

@@ -1,73 +0,0 @@
-# QA 通用质量规则
-
-无论 QA 来源（网站 / 帮助中心 / FAQ / PDF / 工单），所有生成的 QA 都必须遵守本文规则。
-
-## 格式
-
-**Answer 全部用 markdown**——Shulex 知识库后台和客服回复链路均按 markdown 渲染。
-保留图片 `![alt](url)`、表格、列表 `-`、加粗 `**...**`、有序步骤 `1. ...`，不要写 HTML 标签。
-抓取阶段（`web_fetch` / `web_crawl` / `read_file` PDF）返回的就是 markdown，可直接保留结构、按需精简。
-
-**语言：** 用户明确指定的产物语言 > 会话上下文中的用户界面语言偏好 > 用户当前消息语言。Question、Answer 与新建的业务目录名使用目标语言；品牌名、产品型号和其他专有名词保留原文。网页、附件、PDF 或工单原文只是知识来源，不能单独改变目标语言。不得因为本文示例是英文而默认生成英文。
-
-目录路径必须跟随当前任务的目录 schema。用户或 SOP 明确给出目录层级时，按该 schema 原样归类；未给出 schema 时才使用默认标准模板，默认一级目录 `Product Introduction` / `Brand Policy` / `Help Center` / `Pending Assignment` 保持英文。
-
-## Question 格式
-
-- 品类通用问题（多款产品共有）→ 用品类名：`[品类名] — [问题]`
-- 特定型号专有问题 → 用型号名：`[型号名] — [问题]`
-
-✅ `Smart Security Cameras — How do I reset my camera to factory settings?`（品类通用）
-✅ `Kasa EP25 Smart Plug — What is the maximum wattage this plug supports?`（型号专有）
-❌ `How do I reset it?` ← 无产品信息
-❌ `Reset steps?` ← 不是完整问句
-
-## FAQ / Q&A 结构提取规则
-
-任何页面只要有明确 FAQ / Q&A 结构（条目标题是问题、正文是答案），都按下面规则处理：
-
-- 逐条提取原页面的有效 FAQ；问题加品牌 / 品类 / 型号前缀，答案保留原文 markdown 内容
-- 不受产品页“整体介绍 1 条 + 潜在问题 ≤5 条”限制；FAQ 有多少有效条目就提取多少条
-- 目录归类仍按页面上下文决定：产品页里的产品 FAQ 归产品对应品类/型号目录；政策页里的政策 FAQ 归政策目录；帮助中心 / 文档站 FAQ 才归帮助中心目录。使用默认标准模板时，这些目录分别对应 Product Introduction、Brand Policy、Help Center。
-- 真正的数量控制只在写文件和上传阶段：按 `upload.md` 每批 ≤4 KB 分片，避免截断
-
-## Answer 强制过滤
-
-- 删除所有向客户索要信息的话术（订单号、收据、产品照片、序列号等）
-- 删除所有引导联系客服 / 提交工单 / 发邮件的话术
-- 删除营销语言、品牌故事、公司介绍
-- 格式清晰有条理：分点用 `-`，保留图片 `![描述](URL)`，保留表格
-
-## 全局排除话题（不生成 QA、不建目录）
-
-- 物流 / 快递 / 配送时效 / 包裹追踪
-- 订单查询 / 修改 / 取消
-- 退货 / 退款 / 换货
-- 账号管理
-- 支付 / 账单
-
-## 目录归类规则
-
-每条 QA 归入最精确匹配的目录：
-
-1. 能匹配三级目录 → 归入三级
-2. 能匹配二级目录 → 归入二级
-3. 无法判断 → 归入 `["Pending Assignment"]`
-
-提取过程中发现品类/型号目录在 KB 里不存在时，**用 `create-folder` CLI 临时补建**，
-不要直接归到 Pending Assignment（兜底是给真的无法分类的内容）。
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| Question 不区分品类 / 型号 | 通用问题用品类名，型号专有问题用型号名 |
-| Answer 里向客户索要信息（订单号 / 照片 / 序列号） | 整句删除 |
-| Answer 里引导联系客服 / 提交工单 | 整句删除 |
-| 用户已指定目录 schema 时仍套默认 Product Introduction | 用户 schema 优先，严格按指定层级归类 |
-| 默认标准模板下自由发明一级目录名称 | 一级目录只有四个固定名称（见 directory.md） |
-| Product Introduction 二级是产品名 | 二级必须是品类，三级才是产品名 |
-| Brand Policy 下建了三级目录 | Brand Policy 只到二级 |
-| 无法归类的内容随意放置 | 统一放入 Pending Assignment |
-| 产品页 FAQ 被放进 Help Center | 产品页 FAQ 归 Product Introduction 对应产品目录 |
-| FAQ 页面只抽 5 条 | FAQ 按有效条目逐条提取，不套产品页潜在问题 ≤5 条限制 |

package/skills/kb-builder/references/reply-template.md

@@ -1,237 +0,0 @@
-# 回复模板库管理
-
-优先用 `/skill-lib/solvea-api/solvea_api.py` 管理模板；用户上传 Excel / CSV 批量导入时，用 `scripts/import_templates.py`。
-
-## 能力清单
-
-| 用户要做什么 | 使用方式 | 是否需要确认 | 输出 / 结果 |
-|--------------|----------|--------------|-------------|
-| 查模板 | `list-templates` | 否 | 返回 `id/name/content/status/scene` |
-| 创建单条模板 | `create-template` | 是 | 返回新模板 `id` |
-| 修改单条模板（改名 / 内容 / 状态） | `update-template --id ...` | 是 | 返回更新后的模板 |
-| 批量导入模板 | `import_templates.py --dry-run` → 用户确认 → 正式导入 | 是 | dry-run 生成 `template_import_plan_*`；正式导入生成 `template_import_result_*` |
-| 保留首条并跳过重复名 | `import_templates.py --skip-duplicates` | 是 | `skipped_duplicates` 记录被跳过的行 |
-| 删除模板 | `delete-templates --ids ... --confirm-delete` | 是，必须确认模板名称和 id | 按 id 删除 |
-| 单条发布 / 下架 | `update-template --id ... --status ENABLED/DISABLED` | 是 | 改单条模板状态 |
-| 批量发布 / 下架 | 暂无批量 CLI | 是 | 单条走 `update-template`；批量走前端“批量更新” |
-
-## 管理 CLI
-
-所有命令都走：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api <command> [args]
-```
-
-### `list-templates`
-
-查询模板库。只读，可直接执行。
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--keyword` | 否 | 按模板名 / 内容关键字查询；传数字时也可用于定位 id |
-| `--status` | 否 | 状态过滤，如 `ENABLED` / `DISABLED` |
-| `--scene` | 否 | 场景过滤；可重复传。普通模板一般不传，语音短信模板传 `voice_sms` |
-| `--page` | 否 | 页码，默认 `1` |
-| `--page-size` | 否 | 每页数量，默认 `50` |
-| `--pretty` | 否 | 格式化输出，排查时建议加 |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-templates \
-  --keyword "广告" --page-size 20 --pretty
-```
-
-### `create-template`
-
-创建单条模板。执行前先向用户确认模板名称和内容。
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--name` | 是，除非用 `--data-file` | 模板名称，项目内必须唯一 |
-| `--content` | 是，除非用 `--data-file` | 默认回复内容 |
-| `--status` | 否 | 模板状态；不传时后端默认 `ENABLED` |
-| `--scene` | 否 | 模板场景；普通模板不传，语音短信模板传 `voice_sms` |
-| `--data` | 否 | JSON 字符串；适合传 `multiContent` 等复杂字段 |
-| `--data-file` | 否 | JSON 文件路径；适合复杂模板 |
-| `--pretty` | 否 | 格式化输出 |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api create-template \
-  --name "广告关闭" \
-  --content "您好，您可以在APP右下角“我的”里关闭广告。" \
-  --status ENABLED \
-  --pretty
-```
-
-复杂模板用 JSON：
-
-```json
-{
-  "name": "广告关闭",
-  "content": "您好，您可以在APP右下角“我的”里关闭广告。",
-  "status": "ENABLED",
-  "multiContent": {
-    "AUTO": "您好，您可以在APP右下角“我的”里关闭广告。"
-  }
-}
-```
-
-### `update-template`
-
-修改单条已有模板，**部分更新**：只传要改的字段，未传的保持不变。执行前先向用户确认改哪条、改成什么。
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--id` | 是 | 要修改的模板 id（templateId） |
-| `--name` | 否 | 新模板名；项目内唯一，撞名会报 `template name is already existed` |
-| `--content` | 否 | 新默认回复内容；后端会自动同步到 `multiContent.AUTO` |
-| `--status` | 否 | `ENABLED` / `DISABLED` |
-| `--data` / `--data-file` | 否 | JSON；传 `multiContent` 等多语种字段 |
-| `--pretty` | 否 | 格式化输出 |
-
-至少要传一个可改字段（`--name` / `--content` / `--status` / `multiContent`），否则报错。
-
-```bash
-# 下架
-npx --yes @shulex/cxclawctl@latest api update-template --id 12008 --status DISABLED
-
-# 改名 + 内容
-npx --yes @shulex/cxclawctl@latest api update-template \
-  --id 12008 --name "转人工" --content "<p>这是转人工的模版文案</p>" --pretty
-```
-
-多语种内容用 JSON（`--data` / `--data-file`）：
-
-```json
-{ "multiContent": { "AUTO": "<p>…</p>", "ENGLISH": "<p>…</p>" } }
-```
-
-### `delete-templates`
-
-按 id 批量删除模板。删除前必须向用户展示模板名称和 id，并要求回复“我已知晓删除影响并确认删除”或等价强确认。
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--ids` | 是，除非用 `--data-file` | 要删除的模板 id 列表 |
-| `--data` | 否 | JSON 字符串，格式为 `{"templateIds":[123,124]}` 或 `{"ids":[123,124]}` |
-| `--data-file` | 否 | JSON 文件路径 |
-
-```bash
-npx --yes @shulex/cxclawctl@latest api delete-templates --ids 123 124 125 --confirm-delete
-```
-
-## 批量导入脚本
-
-脚本路径：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_templates.py [args]
-```
-
-### Excel / CSV 列
-
-| 列 | 必填 | 说明 | 兼容表头 |
-|----|------|------|----------|
-| `name` | 是 | 模板名称，必须唯一 | `模板名称` / `模板名` / `模版名称` / `模版名` / `名称` / `标题` / `主题` |
-| `content` | 是 | 默认回复内容 | `模板内容` / `模版内容` / `回复内容` / `回复话术` / `话术` / `答案` / `内容` |
-| `status` | 否 | 模板状态，默认 `ENABLED` | `状态` / `发布状态` |
-| `scene` | 否 | 普通模板留空；语音短信模板填 `voice_sms` | `场景` / `适用场景` |
-| `AUTO` | 否 | 默认语言内容；为空时自动使用 `content` | `AUTO` |
-| 其他语言列 | 否 | 多语言内容，如 `ENGLISH` / `CHINESE` / `JAPANESE` | 需使用脚本支持的语言枚举 |
-
-### 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--xlsx` | 二选一 | Excel / CSV 文件路径，支持 `.xlsx` / `.xlsm` / `.csv` |
-| `--plan-file` | 二选一 | 已确认的 `template_import_plan_*.json` 路径；正式导入优先用它，避免跨轮依赖临时 Excel |
-| `--sheet` | 否 | Excel sheet 名；不传用第一个 sheet |
-| `--name-col` | 否 | 指定模板名称列；表头不标准时必传 |
-| `--content-col` | 否 | 指定模板内容列；表头不标准时必传 |
-| `--status-col` | 否 | 指定状态列 |
-| `--scene-col` | 否 | 指定场景列 |
-| `--lang-col` | 否 | 指定多语言列，可重复传，格式 `LANGUAGE=列名`，如 `CHINESE=中文话术` |
-| `--skip-duplicates` | 否 | 文件内模板名重复时保留第一条，跳过后续同名行；结果写入 `skipped_duplicates` |
-| `--dry-run` | 否 | 只解析并生成导入计划，不创建模板 |
-
-`--xlsx` 和 `--plan-file` 二选一。dry-run 阶段通常用 `--xlsx`；正式导入阶段优先用 `--plan-file`。
-
-## 标准流程
-
-1. 先读用户文件表头和样例：
-
-   ```text
-   read_file(file_path="/mounted/chat-files/user/templates.xlsx", limit=20)
-   ```
-
-2. 先 dry-run：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_templates.py \
-     --xlsx /mounted/chat-files/user/templates.xlsx \
-     --dry-run
-   ```
-
-   表头不标准时显式传列名：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_templates.py \
-     --xlsx /mounted/chat-files/user/templates.xlsx \
-     --name-col "Topic" \
-     --content-col "Message" \
-     --scene-col "Usage" \
-     --lang-col "CHINESE=中文话术" \
-     --dry-run
-   ```
-
-   如果确实需要临时处理用户文件，例如手工去重、改列、清洗内容：可以把处理后的文件写到 `/workspace/tmp` 供本轮 dry-run 使用，但用户确认后不能再依赖这个 tmp 文件。跨轮稳定输入是 dry-run 生成的 `template_import_plan_*`。
-
-   用户要求跳过重复模板名时，可以用脚本参数生成最终 plan：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_templates.py \
-     --xlsx /mounted/chat-files/user/templates.xlsx \
-     --name-col "快捷词" \
-     --content-col "回复内容" \
-     --skip-duplicates \
-     --dry-run
-   ```
-
-3. 向用户汇报解析数量和计划文件，等待明确确认：
-
-   ```text
-   已解析 X 条模板，计划文件：
-   /workspace/outputs/kb-builder/template_import_plan_<ts>.json
-
-   确认上传到模板库吗？
-   ```
-
-4. 用户明确回复“确认 / 上传吧 / 没问题”后，用已确认的 plan 正式导入：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_templates.py \
-     --plan-file /workspace/outputs/kb-builder/template_import_plan_<ts>.json
-   ```
-
-   正式导入输出：
-
-   ```text
-   /workspace/outputs/kb-builder/template_import_result_<ts>.json
-   ```
-
-   结果文件包含 `created_items`：
-
-   ```json
-   [{"id": 123, "name": "Warranty reply"}]
-   ```
-
-## 规则
-
-- 查询模板可直接执行；创建、修改、正式批量导入、删除前必须等用户明确确认。
-- `update-template` 是部分更新：只改传入字段，未传字段不变；改名同样受“名称唯一”校验；改单条状态（上架 / 下架）用 `update-template --status`，无需依赖前端。
-- 删除模板前必须展示并确认模板名称和 id。
-- 后端校验模板名唯一；脚本不会覆盖已有模板。
-- Excel 导入没有后端批量创建接口，脚本会逐行调用单条创建接口。
-- 正式导入不会生成新的 import plan，只生成 import result。
-- 跨轮不要依赖 `/workspace/tmp` 临时文件；正式导入应使用 dry-run 生成的 `template_import_plan_*`。
-- plan 是用户确认的导入内容快照；正式导入不要重新解析 Excel，避免文件消失、表头参数不一致或临时处理丢失。

package/skills/kb-builder/references/tag-isolation-migration.md

@@ -1,61 +0,0 @@
-# 标签迁移与隔离关键词映射
-
-标签与隔离关键词是两个独立概念。标签绑定知识使用 `editTags`；隔离关键词绑定知识使用隔离关键词批量接口。两者之间不能直接按字段或 ID 推断关系。
-
-## 中间态文件
-
-先生成：
-
-```text
-/workspace/state/kb-builder/tag_isolation_keyword_mapping.json
-```
-
-格式：
-
-```json
-{
-  "mappings": [
-    {
-      "tag": "kb-test",
-      "isolationKeyword": "product-a",
-      "isolationKeywordId": 11,
-      "matchType": "semantic",
-      "status": "candidate",
-      "reason": "kb-test 与 product-a 都表示该知识内容属于 product-a 产品的测试知识范围"
-    }
-  ]
-}
-```
-
-- 文本完全一致时，`matchType` 为 `exact`。
-- 文本不一致但语义匹配时，`matchType` 为 `semantic`，`reason` 只说明二者为什么匹配。
-- 无法匹配或有歧义时，`status` 为 `unmatched`，不生成绑定项。
-- `isolationKeywordId` 必须来自隔离关键词接口返回的真实 ID。
-
-## 一次性迁移流程
-
-1. 批量读取知识及顶层 `tags`：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest api list-knowledge \
-     --directory-id <directory_id> --type QA --include-tags --page-size 500 --pretty
-   ```
-
-   测试环境使用 `--env staging`，生产环境使用 `--env prod`。根据总数继续分页。
-2. 读取项目标签定义：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest api list-knowledge-tags --pretty
-   ```
-3. 读取隔离关键词文本和真实 ID：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest api \
-     list-isolation-keywords --all --page-size 500 --pretty
-   ```
-4. CX 根据完全一致或语义关系生成中间态映射文件，并按映射生成知识到 `keywordIds` 的绑定计划。
-5. 一次性展示映射文件、未匹配项、歧义项及全部新增绑定；用户只确认这一次。
-6. 确认后调用隔离关键词批量绑定接口，整个迁移过程中不再逐条确认。
-7. 回读知识，验证 `isolationKeywords`。
-
-标签本身如需写入知识，另行使用 `editTags`；该动作也应纳入同一份迁移计划和同一次确认。

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

@@ -1,45 +0,0 @@
-# 知识库标签管理
-
-知识库标签是知识条目上的字符串标签，不是 `tagSetting` 标签树。读取问答时使用 QA 详情接口；读取文档/网页时使用 DOCUMENT 详情接口；写入统一使用 `editTags`，并把对应的 `type` 一并传给接口。
-
-## 接口
-
-```text
-POST /sns_v1/project/{projectId}/editTags
-```
-
-请求体：
-
-```json
-{
-  "type": "QA",
-  "knowledgeIds": [488523],
-  "tagList": ["123", "kb-test"]
-}
-```
-
-`tagList` 是最终标签列表。调用前必须先读取目标知识的顶层 `tags`，再按用户意图计算最终列表：默认追加；明确要求替换时覆盖；删除时计算差集。调用后重新读取知识核对 `tags`。
-
-示例状态文件：
-
-```json
-{
-  "type": "QA",
-  "knowledgeIds": [488523],
-  "tagList": ["kb-test"],
-  "operation": "append"
-}
-```
-
-`operation` 支持 `append`、`replace`、`remove`，默认是 `append`。`metadata.tags` 暂不作为标签写入字段；返回对象中的顶层 `tags` 是本能力的事实来源。
-
-文档和网页分别传列表返回的 `FILE`、`WEBSITE`；不要因为二者底层都属于 DOCUMENT 就把 `type` 写成 `DOCUMENT`。
-
-## 标签配置到知识
-
-标签绑定知识只使用 `editTags`，不使用隔离关键词接口：
-
-```text
-测试环境：POST /sns_v1/project/{projectId}/editTags
-生产环境：POST /api_v2/qam/project/{projectId}/editTags
-```

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

@@ -1,130 +0,0 @@
-# 合并 qa_plan 并上传
-
-→ 通用质量规则见 `/skills/kb-builder/references/qa-quality.md`（必读）
-
-各来源（网站 / 帮助中心 / FAQ / PDF / 工单）独立提取出 QA 后，按下面流程上传。
-
-## 工作流：分批写 tmp，脚本自动合并
-
-**核心思路**：agent 把每批 QA 写到 `/workspace/tmp/kb-builder/qa_parts/` 的多个小文件，
-`import_qa.py --from-dir` 自动按文件名排序合并、写一份带时间戳的成品到 outputs，再做 dry-run / 上传。
-
-### 为什么这样做
-
-直接 `write_file` 一份完整 qa_plan 大概率被 endpoint max_tokens 截断（一份典型计划 50~200 条 QA、30~100 KB）。
-任何 string 字段（write_file/edit_file 的 content/new_string）都是 LLM 一次性输出，**全部受 max_tokens 限制**。
-不要用占位 sentinel + edit_file 多次替换的老办法——edit_file 的 new_string 同样会被截。
-
-### 步骤
-
-1. **先 mkdir 干净的 tmp 目录**（避免上轮残留污染本轮）：
-
-   ```bash
-   mkdir -p /workspace/tmp/kb-builder/qa_parts && rm -f /workspace/tmp/kb-builder/qa_parts/*.json
-   ```
-
-2. **每批 ≤ 4 KB 写一个 json 文件**到 `/workspace/tmp/kb-builder/qa_parts/`。
-   命名约定（任意，按文件名字母序合并）：
-
-   | 文件名样例 | 来源 |
-   |-----------|------|
-   | `qa_web_policy.json` | 网站政策 QA |
-   | `qa_web_kasa-ep25.json` | 网站某产品 QA |
-   | `qa_help_setup.json` | 帮助中心某子目录 QA |
-   | `qa_pdf_av-d600_part1.json` `qa_pdf_av-d600_part2.json` | PDF 拆出来的 QA（分批） |
-   | `qa_tickets_camera.json` | 工单提炼出某品类 QA |
-
-   每个文件的 JSON 结构都是 **QA 数组**：
-
-   ```json
-   [
-     {
-       "dir_path": ["Product Introduction", "Smart Plugs", "Kasa EP25"],
-       "question": "Kasa EP25 Smart Plug — What is the maximum wattage?",
-       "answer": "..."
-     }
-   ]
-   ```
-
-   `dir_path` 必须是目录名数组，不是字符串路径。不要写 `"/kb/Kasa EP25"`、
-   `"Product Introduction/Smart Plugs/Kasa EP25"` 或其他带 `/` 的单个字符串；脚本会在
-   dry-run 阶段报错。上传到现有 SKU / 产品目录时，先 `list-directories` 确认真实父目录，
-   再写完整数组，例如 `["Product Introduction", "Speakers", "B0117-03018-BK"]`。
-
-   含图片的答案必须在 `answer` 中保留 markdown 图片语法 `![](url)`。如果来源是 DOCX / PDF / 网页，
-   优先使用能保留图片 markdown 的读取结果；不要用只读段落文本的解析方式生成最终 QA。
-
-3. **每批 size 控制**（防止单次 write_file 被截）：
-   - 普通 QA 每条 200~500 字符 → 每批 8~10 条
-   - 长 answer（含图表 / 多步骤 / 规格表 / 说明书全文 QA）每条 1~3 KB → 每批 2~3 条
-   - **每批 new_string ≤ 4 KB**（≈ 1K output tokens，留足余量）
-   - 估不准就保守一点，少塞几条没关系
-
-4. **被截的兜底**：如果某次 `write_file` 报 `content: Field required` 或日志出现
-   `output truncated by max_tokens`，**立刻把这批数量减半重写**。这是 max_tokens 截断信号。
-
-5. **合并 + dry-run**（脚本会把合并结果写到 `/workspace/outputs/kb-builder/qa_plan_{ts}.json` 留档）：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/ --dry-run
-   ```
-
-6. **向用户汇报数量**，等待明确确认：
-
-   ```
-   即将上传 X 条 QA：
-   - Product Introduction: N1 条
-   - Brand Policy: N2 条
-   - Help Center: N3 条
-   - Pending Assignment: N4 条
-
-   合并产物：/workspace/outputs/kb-builder/qa_plan_{ts}.json
-   确认上传吗？
-   ```
-
-   ⚠️ 等用户回「确认」「上传吧」「没问题」后再正式上传。「可以」「好」「嗯」**不算**。
-
-7. **正式上传**：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py --from-dir /workspace/tmp/kb-builder/qa_parts/
-   ```
-
-   或者用 dry-run 阶段已落盘的 qa_plan 文件（避免重新合并）：
-
-   ```bash
-   npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py --qa-file /workspace/outputs/kb-builder/qa_plan_<ts>.json
-   ```
-
-## 上传后验证
-
-```bash
-# 按 keyword 检索确认上传成功
-npx --yes @shulex/cxclawctl@latest api list-knowledge --keyword "Kasa EP25" --page-size 50 --pretty
-
-# 看目录的 kuCount 是否增加
-npx --yes @shulex/cxclawctl@latest api list-directories --pretty
-```
-
-## 已经有合并好的 qa_plan.json 时
-
-直接传文件路径，不走 tmp：
-
-```bash
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py --qa-file /path/to/qa_plan.json --dry-run
-npx --yes @shulex/cxclawctl@latest script skills/kb-builder/scripts/import_qa.py --qa-file /path/to/qa_plan.json
-```
-
-## 常见错误
-
-| 错误 | 正确做法 |
-|------|----------|
-| 一次 `write_file` 写整份 qa_plan | 分批写到 `/workspace/tmp/kb-builder/qa_parts/`，由 `import_qa.py --from-dir` 合并 |
-| 用占位 sentinel + 多次 `edit_file` 追加 | 已废弃。`edit_file` 的 `new_string` 同样受 max_tokens 限制，会被截 |
-| 单批塞太多导致截断 | 每批 ≤ 4 KB；长 answer 每批 2~3 条；截断信号出现立刻减半重试 |
-| 直接上传不先 dry-run | 必须先 dry-run 并向用户汇报数量 |
-| 用「可以」「好」「嗯」当确认 | 必须收到明确「确认 / 上传吧 / 没问题」|
-| `--qa-file` / `--from-dir` 路径用相对形式 | 用绝对路径 `/workspace/...` |
-| 上传后知识无效果 | 检查 `published: true` 和 `forceIndex: true` 是否已设置 |
-| `dir_path` 写成 `/kb/SKU` 字符串 | 改成目录名数组，例如 `["Product Introduction", "Speakers", "SKU"]` |
-| 回复说保留图片但知识里没有图片 | 检查 QA plan 的 `answer` 是否真的包含 `![](url)`，上传脚本不会自动从原文补图 |