1688-item-title-optimizer — 商品标题智能优化

技能概述

1688 商品标题智能优化助手。自动并发执行两种优化算法生成结果：1) 添加热词优化（快速、基于规则）2) LLM 深度重写（高质量、自然流畅）。只需提供商品 ID，即可同时获得两种优化方案供对比选择。支持用户偏好参数（如"加入'防潮'单词"）。

使用场景

• 商品标题修改、改写、优化
• 新品发布，需要高质量标题
• 批量优化商品标题
• 用户有特定优化偏好（如指定关键词、风格）

CLI 命令

configure — 配置 AK

# 查看 AK 状态
python3 {baseDir}/cli.py configure
# 设置 AK
python3 {baseDir}/cli.py configure YOUR_AK

配置网关鉴权所需的 AK。所有操作命令都依赖 AK，首次使用前需先配置。

optimize_title — 添加热词优化（方式A）

python3 {baseDir}/cli.py optimize_title --item_id <商品ID>

基于规则和统计的标题优化，保留原标题结构，快速添加高价值热搜词。

optimize_title_llm — LLM 深度重写（方式B）

# 基础调用
python3 {baseDir}/cli.py optimize_title_llm --item_id <商品ID>

# 带用户偏好
python3 {baseDir}/cli.py optimize_title_llm --item_id <商品ID> --preference "加入防潮单词"

基于大语言模型的智能标题重写，全面改写标题，支持用户偏好定制。

get_keyword_info — 获取关键词信息

# 基础调用
python3 {baseDir}/cli.py get_keyword_info --item_id <商品ID>

# 添加自定义关键词
python3 {baseDir}/cli.py get_keyword_info --item_id <商品ID> --custom_keywords "保温杯;不锈钢;便携"

获取标题优化所需的全部关键词数据（热搜词、曝光词、类目信息）。

get_tokenizers — 获取分词器列表

python3 {baseDir}/cli.py get_tokenizers

获取所有可用的分词器列表及说明。

⚠️ 重要：技能skill 使用规范

规则2：获取到商品ID后，自动并发执行两种优化

当用户请求标题优化时，必须按以下步骤执行，关键节点需等待用户确认后再继续：

1. ⏸️ 参数要求（硬性阻断点）：如果用户未提供商品 ID，严禁弹 card 询问，必须按规则1输出JSON

2. ⏸️ 多商品澄清（≥3 个商品时必须触发）：

   • 如果用户一次传入 3 个及以上商品 ID，必须先触发 select_items_to_optimize 交互，让用户筛选需要优化的商品
   • 展示所有商品 ID 及其当前标题（如能获取），让用户选择要优化的商品
   • 必须等待用户选择后再继续，禁止自动对所有商品执行优化
   • 如果用户传入 1-2 个商品，可直接跳过此步骤进入下一步

3. 自动执行：收到用户的优化请求后（或用户在澄清点选定商品后），必须自动并发调用两种优化命令

4. 并发调用：在同一个消息中同时发起两个工具调用：

   • optimize_title（方式A：添加热词优化）
   • optimize_title_llm（方式B：AI深度重写）

5. 提取偏好：如果用户在请求中提到特殊要求（如"加入'防潮'单词"），提取偏好并传入 optimize_title_llm 的 --preference 参数

6. 展示结果：触发 title_comparison_card（type: table，在左侧弹出表格）

   • 3 列（方案 + 属性 + 内容），每个方案 4 行（方案名称、新标题、生成逻辑及优化说明、预估曝光变化）
   • 利用 mergedColumns: ["plan"] + selectionGranularity: "group" + groupBy: "plan" + selectionMode: "single" 实现方案列合并单元格 + 组级单选勾选
   • 通过 actions 配置一个 key: "adopt" / label: "采用此方案" / variant: "primary" 的按钮替代默认"确认选择"
   • rows 的 plan 字段：同组所有 4 行都填相同方案名（如全部填"方案A"或全部填"方案B"），端侧依靠相同值进行合并和分组

7. ⏸️ 应用确认

   • 向用户展示选定的新标题，与原标题对比
   • 触发 confirm_apply_title 交互，让用户选择：
     • ✅ 确认，应用到商品标题
     • ✏️ 我想手动微调后再应用（用户可输入修改后的标题）
     • 💾 仅记录，暂不应用
   • 必须等待用户确认后再继续，禁止自动跳过

8. 应用到商品：

   • 如果用户确认应用，且存在技能 1688-item-one-click，则调用技能更新商品标题
   • 如果用户手动微调了标题，使用微调后的版本应用

具体的交互组件数据结构请查阅 references/interaction-specs.md 中对应交互的章节。

规则3：结果展示规范（左侧 Table 表格）

展示时必须使用 title_comparison_card（type: table）交互组件，在左侧弹出表格，3 列（方案 + 属性 + 内容），每个方案 4 行，方案列合并为大单元格，组级互斥单选勾选。

⚠️ 端侧版本依赖（v2 协议）：本交互依赖 mergedColumns / selectionGranularity / selectionMode / groupBy 4 个 v2 字段，仅在已升级到 v2 的客户端才会生效。当前 1688 工作台 / 找工厂客户端尚未升级，会忽略这 4 个字段，退化为默认的 row + multiple（每行一个 checkbox、可任意多勾、无方案列合并）。

Agent 必须知道：

• payload 不要为兼容降级而修改——协议字段写法是正确的，等客户端升级即可自动生效
• 看到「每行一个 checkbox」不是 payload 错了，是端侧降级渲染
• 处理 selectedRows 时必须用下方"用户回传后处理"统一兼容算法，不能假设回传一定是同一方案的 4 行
• 完整端侧能力对比与降级表见 references/interaction-specs.md 中"端侧版本依赖"小节

展示规范（title_comparison_card）：

1. title：格式为"请选择新标题 — 商品名称（商品ID）"

2. columns 固定 3 列：

   • plan（方案标识列，宽 80px，不传 editable）
   • field（属性标签列，宽 140px，必须显式声明 editable: false）—— ⚠️ 用户实测：省略 editable 字段会让端侧把该列误渲染为可编辑，显式写 false 才能保证只读
   • value（内容列，宽 620px，列级不传 editable，由行级 rows[i].editable: true 仅在"新标题"行开启）

   ⚠️ 行级 editable 协议（2026-05 用户实测有效）：1688 端侧官方曾答复"列级 editable 不支持行级控制"，但用户实测确认端侧已支持 rows[i].editable: true 行级控制。本场景配合"field 列显式 editable: false + value 列不传 + 仅新标题行 rows[i].editable: true"的组合写法，达到"仅新标题行可编辑、其他所有 cell 都只读"的预期效果。

   双层保护（防御性设计）：即使端侧某天回退、行级 editable 失效，Agent 在读取回传时仍必须软兜底：只采用「新标题」行的编辑值，其他 3 行编辑显式忽略（详见下方"用户回传后处理"第 6 步），保证业务正确性不依赖于端侧能力

3. v2 协议合并/勾选字段（4 个，缺一不可）：

   • mergedColumns: ["plan"]：方案列按相邻同值合并为大 rowSpan 单元格
   • groupBy: "plan"：按方案字段切分相邻分组（selectionGranularity:"group" 时必填）
   • selectionGranularity: "group"：勾选单位为组（每组组首行渲染一个 checkbox，整组共用）
   • selectionMode: "single"：勾选数量为单选（方案 A / B 互斥；选新组自动取消旧组；点已选项 = 清空；空选 = 跳过）

4. 协议硬约束（违反会被主进程 validator 拒绝 / 端侧渲染异常）：

   • mergedColumns 中的列不能是列级 editable: true —— 本场景 value 列已改为不开启列级 editable（用行级 rows[i].editable 替代），所以约束自动满足；仍只合并 plan，因为 value 每行内容不同没有相邻同值可合并
   • field 列必须显式 editable: false（不可省略）—— 用户实测：省略时端侧会把该列误渲染为可编辑
   • rows.length ≤ 10 —— 超过会触发端侧分页并自动关闭合并；本场景最多 8 行（仅成功方案入表），安全
   • 同方案的所有行 plan 字段必须填相同值且连续排列（不能"方案A、方案B、方案A"这样交错），否则相邻同值合并失效

5. actions 自定义按钮：配置 [{ key: "adopt", label: "采用此方案", variant: "primary", description: "..." }] 替代默认"确认选择"

6. rows 仅填入成功方案的行（4 行或 8 行，严禁填入失败方案的行）：两个都成功 = 方案 A 4 行 + 方案 B 4 行共 8 行；一个成功一个失败 = 仅成功方案的 4 行（禁止为失败方案填占位行）；两个都失败 = 不弹表格。每方案 4 个属性维度，行级 editable 配置（仅"新标题"行设 editable: true，端侧识别后这 3 行渲染只读）：

   • 方案名称（不设 editable，端侧默认只读；即使端侧不识别行级 editable，Agent 也忽略此行编辑值）
   • 新标题（设 "editable": true，可 cell 内编辑；用户编辑会被采用为最终标题）
   • 生成逻辑及优化说明（不设 editable，端侧默认只读；Agent 完全不读此行编辑值）
   • 预估曝光变化（不设 editable，端侧默认只读；Agent 完全不读此行编辑值）

7. 生成逻辑维度构造（写入"生成逻辑及优化说明"行的 value，按热度 weight 标注）：

   • 🔥 热词（tag=热词）：词名(热度:weight值)
   • 📈 流量获取（tag=时间词/修饰词）
   • ✨ 吸引力（tag=场景词/风格词）
   • 👀 买家关注（tag=属性词/材质词/品类词/功能词）

8. 📈 曝光量变化预测（必须）：基于热词数据给出"+X% ~ +Y%"区间，写入"预估曝光变化"行的 value，必须附带"实际效果受类目竞争、商品权重、市场环境等多因素影响，仅供参考"免责说明（具体规则见 references/interaction-specs.md 中"曝光量变化预测规则"小节）

9. 部分失败处理（严禁展示失败方案）：若任一方案 CLI 返回 success: false 或异常，直接跳过该方案，rows 中仅填入成功方案的 4 行，禁止为失败方案填入任何占位行/兜底行。具体规则：

   • 一个成功一个失败 → title_comparison_card 只展示成功方案的 4 行（rows.length = 4）；由于只有 1 个方案可选，用户直接勾选该方案即可；在对话中简要告知用户另一方案本次未生成成功
   • 两个都失败 → 不弹 title_comparison_card 表格；直接在对话中告知用户"两种优化方案均未生成成功，建议稍后重试"，并提示可重新触发优化
   • 两个都成功 → 正常展示 8 行（不变）

用户回传后处理（统一兼容 v2 客户端 与 未升级客户端，无需事先判断端侧版本，按此顺序执行）：

前置要求：触发本交互之前，Agent 必须确保 optimize_title（方案A）和 optimize_title_llm（方案B）的 CLI 完整返回 JSON 仍可在当前对话上下文中访问（用于降级场景下重新弹窗时重构 payload，禁止为此重新调用 CLI）。

1. 空选判定：selectedRows.length === 0 → 视为跳过，禁止进入 confirm_apply_title，应回退询问"是否重新生成 / 结束优化"

2. 按 plan 字段分组聚合：groups = group_by(selectedRows, row => row.plan)

3. 跨方案混勾的兜底（分组数 ≥ 2，仅未升级客户端可能出现）：严禁用"取行数最多的方案"等启发式猜测算法。必须：

   1. 给用户对话提示："检测到您勾选了多个方案的行（方案 A：N₁ 行 / 方案 B：N₂ 行），由于本次只能采用一个方案，请在重新弹出的表格中仅勾选您想采用的那一个方案，再点「采用此方案」"
   2. 重新触发 title_comparison_card，用前置小节提到的成功方案的原始 CLI 返回值重新构造 payload（仅填入成功方案的行；禁止重新调用 optimize_title / optimize_title_llm）
   3. 等待新一轮回传，从第 1 步重新走

4. 缺字段的兜底（分组数 = 1 但唯一方案的行集合中缺少 "方案名称" 或 "新标题"，仅未升级客户端可能出现）：

   1. 给用户对话提示："您勾选的行不完整（缺少 <缺失的 field 列表>），请在重新弹出的表格中勾选包含「方案名称」和「新标题」的完整行集合"
   2. 重新触发 title_comparison_card（同第 3 步：用原始 CLI 返回值重构 payload，禁止重调 CLI）
   3. 等待新一轮回传，从第 1 步重新走

5. （已移除）：由于失败方案不再进入表格，无需在回传后识别失败方案。直接进入第 6 步

6. 读取最终新标题（仅采用「新标题」行的编辑值）：在唯一选中方案的行集合里找 field === "新标题" 的行（第 4 步已保证此行存在），取其 value（可能已被用户在 cell 内编辑，以此为准，禁止回退读 CLI 原始 new_title，禁止用其他 field 的 value 当标题）。

   • ⚠️ 关于其他 3 行的用户编辑：协议层已通过不在这 3 行设置 editable: true 让端侧渲染为只读。但万一端侧暂不识别 rows[i].editable 退化为"全部 cell 可编辑"，Agent 仍须显式忽略这些行的编辑值（双层保护）：
     • 方案名称行的 value 仅用于"识别选中方案"，不参与最终标题构造
     • 生成逻辑 / 预估曝光变化 行的 value 完全不读，仅作 UI 展示
     • 严禁因用户改了其他行就把它当成新标题写入 confirm_apply_title

7. 进入应用确认：携带"方案标识（来自分组的唯一 key）+ 最终新标题（仅来自「新标题」行的编辑值）+ 商品 ID + 商品原标题"触发 confirm_apply_title

设计原则：上述算法只依赖 selectedRows 的扁平结构 + plan/field 字段语义，不依赖端侧"组"/"单选"实现细节。在 v2 客户端上第 3、4 步的兜底永不触发（端侧已保证完整性），算法退化为"取 groups 唯一 key + 找新标题行"的极简路径；在未升级客户端上兜底按需启用，依靠 context 中已有的 CLI 原始返回值重构 payload 重新弹窗，不再调用任何 CLI。待 1688 客户端升级到 v2 后无需任何回滚。完整算法说明见 references/interaction-specs.md 中"Agent 处理逻辑"小节。

规则4：用户偏好提取

如果用户在优化请求中提到特殊要求，需要提取并传入 --preference 参数：

识别偏好的关键词：

• "加入xxx"、"添加xxx"、"包含xxx" → 提取关键词
• "突出xxx"、"强调xxx"、"体现xxx" → 提取特点要求
• "要xxx风格"、"面向xxx" → 提取风格要求

示例：

用户："优化商品831034165952的标题，加入'防潮'这个词"
  ↓
提取：preference = "加入'防潮'单词"
  ↓
调用：cli.py optimize_title_llm --item_id 831034165952 --preference "加入'防潮'单词"

安全声明

所有命令均为只读操作，不会修改商品标题。优化结果仅供参考，需用户确认后手动应用。

异常处理

任何命令输出 success: false 时：

1. 先输出 markdown 字段（已包含用户可读的错误描述）
2. 再根据关键词追加引导：

环境变量（.env）

项目根目录的 .env 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。

已存在的系统环境变量优先级高于 .env，CI/CD 注入的变量不会被覆盖。

埋点上报

每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。

• 实现位置：scripts/_tracker.py → report_skill_usage()，在 cli.py 的 main() 中每次命令执行后自动调用

• 上报接口：POST /api/reportSkillsUsage/1.0.0

• 上报参数：

  参数	值来源	说明
  apiName	固定 null	固定传 null
  skillsName	.env SKILL_NAME	skill 名称
  version	.env SKILL_VERSION	skill 版本号
  scene	固定 CLI	固定值
  channel	.env SKILL_CHANNEL	发布渠道

• 失败处理：上报失败静默忽略，不影响主流程

输出格式

采用标准 JSON 输出：

{
  "success": true,
  "markdown": "✅ 标题优化完成",
  "data": {
    "item_id": 831034165952,
    "old_title": "304不锈钢水杯",
    "new_title": "304不锈钢保温杯便携大容量",
    "optimize_reason": "添加热词:保温杯,便携,大容量",
    "new_title_words": [...],
    "other_words": [...]
  }
}

两种优化方式对比

规则5：曝光量变化预测

展示优化结果时，必须对每种方案给出曝光量变化预估。预估规则如下：

1. 热词数量变化：新标题相比原标题每新增 1 个类目热搜词（tag=热词），预估曝光提升 5%-15%
2. 热词权重参考：new_title_words 和 other_words 中的 weight（权重值）、min_rnk（搜索排名）可辅助判断词的流量价值——权重越高、排名越靠前，预估提升越大
3. 年份更新加成：如果新标题包含当前年份词（如"2026新款"），预估额外提升 3%-8% 曝光
4. 综合预估：给出一个保守区间（如 "+10% ~ +25%"），并标注免责说明

免责说明（必须展示）：

⚠️ 曝光预估基于关键词热度数据，实际效果受类目竞争、商品权重、市场环境等多因素影响，仅供参考。

示例：

使用原则

1. 所有命令均为只读操作，不会修改商品标题
2. 优化结果仅供参考，需用户确认后手动应用
3. 收到优化请求后，应同时调用两种方式并展示结果
4. 如果用户有特殊偏好，应提取并传入 --preference 参数
5. 传入 ≥3 个商品时，必须先触发 select_items_to_optimize 交互让用户筛选
6. 结果展示必须使用 title_comparison_card 表格（3列×每方案4行，方案列合并单元格 + 组级单选），标注生成逻辑及优化说明（含热度）和曝光预估

执行前置（首次命中能力时必须）

• 如果用户没有提供商品ID（上下文里没有商品ID），直接按 references/interaction-specs.md 中 open_tab_select_product 的数据结构输出 JSON，流程结束，不允许反问用户，不允许输出其他内容
• 首次执行 optimize_title 前：先完整阅读 capabilities/optimize_title.md
• 首次执行 optimize_title_llm 前：先完整阅读 capabilities/optimize_title_llm.md
• 首次执行 get_keyword_info 前：先完整阅读 capabilities/get_keyword_info.md
• 首次执行 get_tokenizers 前：先完整阅读 capabilities/get_tokenizers.md

Agent 执行检查清单

在执行优化时，请确认：

• 提取商品ID
• 若商品数 ≥ 3，已触发 select_items_to_optimize 交互并等待用户选择
• 已识别并提取用户偏好（如果有）
• 并发调用 optimize_title 和 optimize_title_llm 命令
• 等待两个结果都返回
• 使用 title_comparison_card 表格展示两个结果（含生成逻辑 + 曝光预估）
• 已给出每种方案的曝光量变化预估及免责说明