sophhub 0.4.69 → 0.4.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.69",
+  "version": "0.4.71",
   "description": "SophHub CLI - Manage and download AI Agent skills and agents",
   "type": "module",
   "bin": {

package/skills/flight-booking/src/scripts/flight_booking.py

@@ -9,6 +9,7 @@ import json
 import os
 import sys
 import time
+from datetime import datetime, timedelta
 
 import requests
 
@@ -355,6 +356,157 @@ def pick_flight_and_cabin(
 
 # ---------- 创建订单（常规） ----------
 
+def merge_verified_prices(
+    flight_detail: dict,
+    cabin: dict,
+    vdata: dict,
+    sale_price: float,
+    departure_tax: float,
+    fuel_tax: float,
+) -> tuple[dict, dict]:
+    """把验价得到的实时价格覆盖到 flight/cabin 的副本上，供创单使用。
+
+    创单的 productInfo 由这两个对象构造。若不覆盖，priceInfos/segmentInfos 写的是搜索
+    缓存的旧价格，而同一个请求里的 estimatedTotal 与 shoppingCode 用的是验价后的新值——
+    验价返回 10301（票价变动）或 isUpdatePrice=true 时，这种自相矛盾会让供应商拒单，
+    订单留痕也会与实际成交价不符。
+
+    只改价格相关字段，其余字段（cabinCode、flightNo、subCabinCode 等）原样保留；
+    入参对象不被修改。
+    """
+    merged_flight = dict(flight_detail)
+    merged_flight["departureTax"] = departure_tax
+    merged_flight["fuelTax"] = fuel_tax
+
+    merged_cabin = dict(cabin)
+    merged_cabin["salePrice"] = sale_price
+    face_price = vdata.get("facePrice")
+    if face_price is not None:
+        merged_cabin["facePrice"] = face_price
+    return merged_flight, merged_cabin
+
+
+# 接口文档 6.4：SegmentInfo / RefundChangeDetail 的字段。缺失的取值一律不传，
+# 不用 null 顶替——那会把"没有这个数据"变成"这个字段是空的"。
+_FULL_PRICE_FIELD_BY_GRADE = {"Y": "yPrice", "C": "cPrice", "F": "fPrice"}
+_REFUND_CHANGE_FIELDS = (
+    "baggageNum", "baggageKg", "baggage", "changeAmountList", "endorseRule",
+    "refundHeaders", "changeHeaders", "refundAmountList", "remark",
+    "changeRule", "refundRule",
+)
+
+
+def _text_or_none(value):
+    """只接受非空字符串；其它类型（含对象）一律视为无值。"""
+    if isinstance(value, str):
+        value = value.strip()
+        return value or None
+    return None
+
+
+def _stop_city_code(flight_detail: dict):
+    """经停城市三字码。
+
+    供应商把经停信息放在对象里（文档 6.1 `flightStopOver: FlightStopOver`，实测形如
+    ``{"cityName": "成都", "stopCityCode": "CTU", "stopDuration": "03:30"}``），非经停航班
+    为 null；这里兼容"直接给字符串"的写法，两者取不到值就返回 None（不传该字段）。
+    """
+    stop_over = flight_detail.get("flightStopOver")
+    if isinstance(stop_over, dict):
+        return _text_or_none(stop_over.get("stopCityCode"))
+    return _text_or_none(stop_over)
+
+
+def _full_price_of(flight_detail: dict, cabin: dict):
+    """舱位全价：供应商在 fullPriceCabin 里按舱位等级给出（Y→yPrice / C→cPrice / F→fPrice）。"""
+    full = flight_detail.get("fullPriceCabin") or {}
+    return full.get(_FULL_PRICE_FIELD_BY_GRADE.get((cabin.get("grade") or "").upper(), ""))
+
+
+def _refund_change_detail(refund_change: dict):
+    """退改规则：按文档 6.4 的 RefundChangeDetail 结构取字段。"""
+    if not isinstance(refund_change, dict):
+        return None
+    detail = {k: refund_change.get(k) for k in _REFUND_CHANGE_FIELDS
+              if refund_change.get(k) is not None}
+    return detail or None
+
+
+def _arrival_date(from_date: str, cross_day) -> str:
+    """到达日期：跨天航班算次日，否则与起飞同一天（文档要求必填）。"""
+    if not from_date or not cross_day:
+        return from_date
+    try:
+        return (datetime.strptime(from_date, "%Y-%m-%d") + timedelta(days=1)).strftime("%Y-%m-%d")
+    except ValueError:
+        return from_date
+
+
+def build_product_info(
+    flight_detail: dict,
+    cabin: dict,
+    from_city: str,
+    to_city: str,
+    from_date: str,
+    passenger_type: str = "ADU",
+) -> dict:
+    """构造创单 productInfo（接口文档 6.4）。
+
+    字段覆盖文档里 SegmentInfo / RefundChangeDetail / PriceInfo 的必填项；供应商未返回的
+    取值直接不传（例如经停城市、到达航站楼在非经停/无数据时为空），不用 null 顶替。
+
+    供应商用它记录订单的产品信息；网关侧也据此判定订单的价格类型并写入订单留痕
+    （price_type / price_type_reason）。不带这段时留痕只能记 UNKNOWN——服务端
+    没有别的可信来源。
+    """
+    segment = {
+        "aircraftType": (flight_detail.get("aircraft") or {}).get("code"),
+        "cabinClass": cabin.get("grade"),
+        "cabinCode": cabin.get("code"),
+        "cabinFullPrice": _full_price_of(flight_detail, cabin),
+        "cabinType": cabin.get("type"),
+        "carrierName": (flight_detail.get("carrier") or {}).get("name"),
+        "departureTax": flight_detail.get("departureTax"),
+        "facePrice": cabin.get("facePrice"),
+        "flightDuration": flight_detail.get("flightDuration"),
+        "flightNo": flight_detail.get("flightNo"),
+        "fromAirportCode": flight_detail.get("fromAirportCode"),
+        "fromAirportName": flight_detail.get("fromAirportName"),
+        "fromAirportNameEn": flight_detail.get("fromAirportEn"),
+        "fromCityCode": from_city,
+        "fromCityName": flight_detail.get("fromCityCN"),
+        "fromDate": from_date,
+        "fromTerminal": flight_detail.get("fromTerminal"),
+        "fromTime": flight_detail.get("fromTime"),
+        "fuelTax": flight_detail.get("fuelTax"),
+        "productType": cabin.get("productType"),
+        "refundChangeDetail": _refund_change_detail(cabin.get("refundChange")),
+        "stopCityCode": _stop_city_code(flight_detail),
+        "toAirportCode": flight_detail.get("toAirportCode"),
+        "toAirportName": flight_detail.get("toAirportName"),
+        "toAirportNameEn": flight_detail.get("toAirportEn"),
+        "toCityCode": to_city,
+        "toCityName": flight_detail.get("toCityCN"),
+        "toDate": _arrival_date(from_date, flight_detail.get("crossDay")),
+        "toTerminal": flight_detail.get("toTerminal"),
+        "toTime": flight_detail.get("toTime"),
+        "yprice": (flight_detail.get("fullPriceCabin") or {}).get("yPrice"),
+    }
+    if flight_detail.get("isShareFlight") and flight_detail.get("realFlightNo"):
+        segment["realFlightNo"] = flight_detail["realFlightNo"]
+    price = {
+        "passengerType": passenger_type,
+        "salePrice": cabin.get("salePrice"),
+        "departureTax": flight_detail.get("departureTax"),
+        "fuelTax": flight_detail.get("fuelTax"),
+        "rescheduledPrice": 0,
+    }
+    return {
+        "segmentInfos": [{k: v for k, v in segment.items() if v is not None}],
+        "priceInfos": [{k: v for k, v in price.items() if v is not None}],
+    }
+
+
 def create_order(
     flight_detail: dict,
     cabin: dict,
@@ -389,6 +541,10 @@ def create_order(
         "estimatedTotal": estimated_total,
         "travelBusiness": True,
         "passengerInfo": encrypted_passenger,
+        "productInfo": build_product_info(
+            flight_detail, cabin, from_city, to_city, from_date,
+            passenger.get("passengerType") or "ADU",
+        ),
     }
     if price_info:
         order_data["priceInfo"] = price_info
@@ -843,9 +999,15 @@ def cmd_create_order(args: argparse.Namespace) -> int:
             "message": verify_res.get("msg", ""),
         }
 
+    # 把验价后的实时价格覆盖到传入创单的对象上：productInfo 由它构造，
+    # 否则会出现 estimatedTotal/shoppingCode 用新值、productInfo 用缓存旧值的矛盾
+    order_flight, order_cabin = merge_verified_prices(
+        flight, cabin, vdata, sale_price, dep_tax, fuel_tax
+    )
+
     order_res = create_order(
-        flight_detail=flight,
-        cabin=cabin,
+        flight_detail=order_flight,
+        cabin=order_cabin,
         from_city=from_city,
         to_city=to_city,
         from_date=from_date,

package/skills/flight-booking/src/scripts/test_flight_booking.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""flight_booking 创单 productInfo 的单测（不触网、不需要密钥）。
+
+覆盖两类问题：
+1. 验价返回 10301（票价变动）或 isUpdatePrice=true 时，productInfo 必须用**验价后的
+   实时价格与税费**，与同一请求里的 estimatedTotal / shoppingCode 保持一致；
+2. productInfo 必须包含接口文档 6.4 规定的必填字段（SegmentInfo / RefundChangeDetail /
+   PriceInfo）。
+
+用法::
+
+    python3 skills/flight-booking/src/scripts/test_flight_booking.py
+
+依赖：脚本自身依赖 ``requests``（业务脚本在导入时即引入），运行前需已安装。
+"""
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# 先隔离运行环境，再导入被测模块：
+# 模块导入时要求 SOPH_API_KEY（或 ~/.openclaw/openclaw.json）且会创建数据目录，
+# 单测不应依赖密钥、也不该写真实用户目录。
+_TMP_HOME = tempfile.mkdtemp(prefix="flight-booking-test-")
+os.environ["HOME"] = _TMP_HOME
+os.environ["USERPROFILE"] = _TMP_HOME
+os.environ.setdefault("SOPH_API_KEY", "unit-test-key-not-used")
+
+HERE = Path(__file__).resolve().parent
+if str(HERE) not in sys.path:
+    sys.path.insert(0, str(HERE))
+
+import flight_booking as fb  # noqa: E402
+
+# 接口文档 6.4 SegmentInfo 的必填字段
+REQUIRED_SEGMENT_FIELDS = (
+    "aircraftType", "cabinClass", "cabinCode", "cabinFullPrice", "cabinType",
+    "carrierName", "departureTax", "facePrice", "flightDuration", "flightNo",
+    "fromAirportCode", "fromAirportName", "fromAirportNameEn", "fromCityCode",
+    "fromCityName", "fromDate", "fromTerminal", "fromTime", "fuelTax",
+    "productType", "refundChangeDetail", "stopCityCode",
+    "toAirportCode", "toAirportName", "toAirportNameEn", "toCityCode",
+    "toCityName", "toDate", "toTerminal", "toTime", "yprice",
+)
+
+# 接口文档 6.4 RefundChangeDetail 的必填字段
+REQUIRED_REFUND_CHANGE_FIELDS = (
+    "baggageNum", "baggageKg", "baggage", "changeAmountList", "endorseRule",
+    "refundHeaders", "changeHeaders", "refundAmountList", "remark",
+    "changeRule", "refundRule",
+)
+
+
+def _cached_flight() -> dict:
+    """搜索缓存里的航班对象（字段取自 Dev2 实测响应）。"""
+    return {
+        "flightNo": "MU5123",
+        "aircraft": {"code": "32N", "name": "空客A320"},
+        "carrier": {"code": "MU", "name": "东方航空"},
+        "departureTax": 50,
+        "fuelTax": 70,
+        "flightDuration": "02h15m",
+        "fromAirportCode": "SHA",
+        "fromAirportName": "虹桥国际机场",
+        "fromAirportEn": "Hongqiao International Airport",
+        "fromCityCode": "SHA",
+        "fromCityCN": "上海",
+        "fromTerminal": "T2",
+        "fromTime": "2026-10-01 19:00:00",
+        "toAirportCode": "PKX",
+        "toAirportName": "大兴国际机场",
+        "toAirportEn": "Daxing International Airport",
+        "toCityCode": "BJS",
+        "toCityCN": "北京",
+        "toTerminal": "T2",
+        "toTime": "2026-10-01 21:15:00",
+        "crossDay": False,
+        "flightStopOver": None,
+        "fullPriceCabin": {"yPrice": 3230, "cPrice": 3870, "fPrice": 8390},
+    }
+
+
+def _cached_cabin() -> dict:
+    """搜索缓存里的舱位对象（字段取自 Dev2 实测响应）。"""
+    return {
+        "code": "V",
+        "grade": "Y",
+        "type": "-1",
+        "salePrice": 700,
+        "facePrice": 700,
+        "productType": "STANDARD_REFUND",
+        "shoppingCode": "SC-CACHED",
+        "refundChange": {
+            "baggageNum": 1,
+            "baggageKg": 20.0,
+            "baggage": "免费托运行李额20KG",
+            "changeAmountList": [65, 194],
+            "endorseRule": "不可签转",
+            "refundHeaders": ["起飞前7天前", "起飞前2小时前"],
+            "changeHeaders": ["起飞前7天前", "起飞前2小时前"],
+            "refundAmountList": [129, 258],
+            "remark": "以航司最新规定为准",
+            "changeRule": "65-168-194-48",
+            "refundRule": "129-168-258-48",
+            # 供应商会额外返回这些字段；文档未要求，不应出现在 payload 里
+            "cabinCode": "V",
+            "cabinName": "经济舱",
+            "salePrice": 700,
+        },
+    }
+
+
+def _product_info(flight_detail: dict, cabin: dict, vdata: dict,
+                  sale_price: float, departure_tax: float, fuel_tax: float) -> dict:
+    """模拟 cmd_create_order 的取值路径：验价 → 覆盖价格 → 构造 productInfo。"""
+    merged_flight, merged_cabin = fb.merge_verified_prices(
+        flight_detail, cabin, vdata, sale_price, departure_tax, fuel_tax
+    )
+    return fb.build_product_info(merged_flight, merged_cabin, "SHA", "BJS", "2026-10-01")
+
+
+def test_product_info_uses_search_prices_when_unchanged() -> None:
+    """场景 1：验价价格不变 → productInfo 与搜索结果一致。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+    vdata = {"salePrice": 700, "departureTax": 50, "fuelTax": 70, "shoppingCode": "SC-LIVE"}
+
+    product_info = _product_info(flight, cabin, vdata, 700.0, 50.0, 70.0)
+
+    price = product_info["priceInfos"][0]
+    segment = product_info["segmentInfos"][0]
+    assert price["salePrice"] == 700, f"priceInfos.salePrice 应等于搜索结果 700，实际 {price['salePrice']}"
+    assert price["departureTax"] == 50 and price["fuelTax"] == 70, "税费应与搜索结果一致"
+    assert segment["facePrice"] == 700, "segmentInfos.facePrice 应等于搜索缓存票面价"
+
+
+def test_product_info_follows_verified_prices_when_price_changed() -> None:
+    """场景 2：验价返回 10301/isUpdatePrice → productInfo 必须用验价后的价格与税费。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+    # 搜索缓存：700 / 机建 50 / 燃油 70；验价后：750 / 60 / 80，票面价 800
+    vdata = {
+        "salePrice": 750, "departureTax": 60, "fuelTax": 80, "facePrice": 800,
+        "isUpdatePrice": True, "shoppingCode": "SC-LIVE",
+    }
+    sale_price, dep_tax, fuel_tax = 750.0, 60.0, 80.0
+
+    product_info = _product_info(flight, cabin, vdata, sale_price, dep_tax, fuel_tax)
+
+    price = product_info["priceInfos"][0]
+    segment = product_info["segmentInfos"][0]
+    assert price["salePrice"] == 750, f"priceInfos.salePrice 应为验价后的 750，实际 {price['salePrice']}"
+    assert price["departureTax"] == 60 and price["fuelTax"] == 80, "税费应为验价后的值"
+    assert segment["departureTax"] == 60 and segment["fuelTax"] == 80, "segmentInfos 的税费也应为验价后的值"
+    assert segment["facePrice"] == 800, "票面价应取验价响应里的 facePrice"
+
+    # 与同一请求里的 estimatedTotal 保持一致
+    estimated_total = sale_price + dep_tax + fuel_tax
+    assert price["salePrice"] + price["departureTax"] + price["fuelTax"] == estimated_total, \
+        "productInfo 的价格合计必须与 estimatedTotal 一致"
+
+
+def test_product_info_has_all_required_doc_fields() -> None:
+    """productInfo 必须满足文档 6.4 的必填字段（本轮 review 的问题点）。
+
+    夹具取"字段齐全"的航班（含经停城市）——经停城市是文档必填项，但只有经停航班才有值；
+    非经停航班上供应商返回 null，此时不传该字段（见 test_missing_fields_are_omitted_not_null）。
+    """
+    flight, cabin = _cached_flight(), _cached_cabin()
+    flight["flightStopOver"] = {"cityName": "成都", "stopCityCode": "CTU", "stopDuration": "03:30"}
+    product_info = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)
+
+    assert set(product_info) == {"segmentInfos", "priceInfos"}
+    assert len(product_info["segmentInfos"]) == 1 and len(product_info["priceInfos"]) == 1
+
+    segment = product_info["segmentInfos"][0]
+    missing = [f for f in REQUIRED_SEGMENT_FIELDS if f not in segment]
+    assert not missing, f"segmentInfos 缺少文档必填字段: {missing}"
+
+    refund = segment["refundChangeDetail"]
+    missing_refund = [f for f in REQUIRED_REFUND_CHANGE_FIELDS if f not in refund]
+    assert not missing_refund, f"refundChangeDetail 缺少文档必填字段: {missing_refund}"
+    assert "cabinName" not in refund, "文档未要求的供应商字段不应带进请求"
+
+    price = product_info["priceInfos"][0]
+    missing_price = [f for f in ("passengerType", "salePrice", "departureTax", "fuelTax",
+                                 "rescheduledPrice") if f not in price]
+    assert not missing_price, f"priceInfos 缺少必填字段: {missing_price}"
+
+
+def test_full_price_comes_from_full_price_cabin() -> None:
+    """cabinFullPrice / yprice 取供应商的 fullPriceCabin，而不是票面价。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+
+    assert segment["cabinFullPrice"] == 3230, "Y 舱应取 fullPriceCabin.yPrice"
+    assert segment["yprice"] == 3230, "yprice 为经济舱全价"
+
+
+def test_arrival_date_follows_cross_day() -> None:
+    """到达日期：跨天航班为次日，否则与起飞同一天（文档必填）。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+
+    same_day = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert same_day["toDate"] == "2026-10-01"
+
+    flight["crossDay"] = True
+    next_day = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert next_day["toDate"] == "2026-10-02", "跨天航班到达日期应为次日"
+
+
+def test_stop_city_code_read_from_nested_object() -> None:
+    """经停城市要从 flightStopOver 对象里取（真实响应形如 {"cityName":…, "stopCityCode":"CTU"}）。
+
+    回归护栏：曾经用 _text_or_none() 直接读该字段，遇到对象一律返回 None，
+    结果**恰恰在有经停的航班上**把文档必填的 stopCityCode 丢掉。
+    """
+    flight, cabin = _cached_flight(), _cached_cabin()
+
+    flight["flightStopOver"] = {"cityName": "成都", "stopCityCode": "CTU", "stopDuration": "03:30"}
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert segment.get("stopCityCode") == "CTU", "有经停时必须从对象里取出 stopCityCode"
+
+    # 非经停航班：字段为 null → 不传该字段
+    flight["flightStopOver"] = None
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert "stopCityCode" not in segment, "非经停航班不应传空的经停城市"
+
+    # 兼容供应商直接给字符串的写法
+    flight["flightStopOver"] = "CTU"
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert segment.get("stopCityCode") == "CTU", "字符串写法也应兼容"
+
+    # 对象里没有 stopCityCode → 不传
+    flight["flightStopOver"] = {"cityName": "成都"}
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+    assert "stopCityCode" not in segment
+
+
+def test_missing_fields_are_omitted_not_null() -> None:
+    """源数据缺失的字段直接不传，而不是传 null。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+    flight.pop("flightDuration")
+    flight.pop("toTerminal")
+    cabin.pop("type")
+    cabin.pop("refundChange")
+
+    segment = _product_info(flight, cabin, {}, 700.0, 50.0, 70.0)["segmentInfos"][0]
+
+    for absent in ("flightDuration", "toTerminal", "cabinType", "refundChangeDetail", "stopCityCode"):
+        assert absent not in segment, f"{absent} 无数据时不应出现在请求里"
+
+
+def test_merge_does_not_mutate_inputs() -> None:
+    """覆盖价格时不能改到搜索缓存对象本身（后续逻辑仍要用原值算价差）。"""
+    flight, cabin = _cached_flight(), _cached_cabin()
+    vdata = {"salePrice": 750, "facePrice": 800, "departureTax": 60, "fuelTax": 80}
+
+    fb.merge_verified_prices(flight, cabin, vdata, 750.0, 60.0, 80.0)
+
+    assert cabin["salePrice"] == 700 and cabin["facePrice"] == 700, "原始 cabin 不应被修改"
+    assert flight["departureTax"] == 50 and flight["fuelTax"] == 70, "原始 flight 不应被修改"
+
+
+if __name__ == "__main__":
+    tests = [(name, fn) for name, fn in sorted(globals().items())
+             if name.startswith("test_") and callable(fn)]
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"PASS  {name}")
+        except AssertionError as exc:
+            failed += 1
+            print(f"FAIL  {name}: {exc}")
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    sys.exit(1 if failed else 0)

package/skills/share-skill/skill.json

@@ -1,12 +1,21 @@
 {
   "name": "share-skill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "types": [
     "builtin"
   ],
   "displayName": "Skill分享",
-  "description": "分享自己的skill给虾友",
+  "description": "分享自己的 skill 给虾友或虾友群",
   "changelog": [
+    {
+      "version": "1.1.0",
+      "date": "2026-09-07",
+      "changes": [
+        "新增 list-groups 子命令与 send/preview 的 --group-id 目标，支持把 Skill 分享到虾友群",
+        "web_jwt 过期或临近过期时自动用 web_refresh_token 续期（逻辑适配自 claw-friend-message-capture）",
+        "SKILL.md 新增群目标回显确认流程与 Processing Mode 双轨规则"
+      ]
+    },
     {
       "changes": [
         "初次提交"
@@ -16,7 +25,7 @@
     }
   ],
   "createdAt": "2026-05-05",
-  "updatedAt": "2026-05-05",
+  "updatedAt": "2026-09-07",
   "emoji": "🔗",
   "tags": [
     "开发"

package/skills/share-skill/src/SKILL.md

@@ -1,15 +1,18 @@
 ---
 name: share-skill
-description: 列出当前用户容器中实际安装的 Skill，按 openclaw skills list 返回的 source 字段分组，引导用户选择 Skill、选择虾友后直接发送 web 格式 Skill 分享卡片。Use when the user asks to share or introduce an installed Skill to a Sophclaw friend / 虾友.
+description: 列出当前用户容器中实际安装的 Skill，按 openclaw skills list 返回的 source 字段分组，引导用户选择 Skill、选择虾友或虾友群后发送 web 格式 Skill 分享卡片（发群必须先回显确认）。Use when the user asks to share or introduce an installed Skill to a Sophclaw friend / 虾友 or a group / 虾友群.
 ---
 
 # 向虾友介绍 Skill
 
-用于把当前容器里实际安装的某个 Skill 按 web 前端一致的 Skill 分享卡片格式发送给虾友。必须按顺序执行：**选择 Skill → 选择虾友 → 直接发送**。
+用于把当前容器里实际安装的某个 Skill 按 web 前端一致的 Skill 分享卡片格式发送给虾友或虾友群。必须按顺序执行：**选择 Skill → 选择目标（虾友 / 群聊）→ 发送（群目标必须先回显确认）**。
 
 ## Processing Mode
 
-**STRICT SERIAL PROCESSING ONLY** — 不并行发送；用户选定 Skill 和虾友后直接发送，不再追加确认步骤。
+**STRICT SERIAL PROCESSING ONLY** — 不并行发送；各步骤严格按顺序执行，目标类型不同规则不同：
+
+- **虾友目标**：用户选定 Skill 和虾友后直接发送，不再追加确认步骤。
+- **群聊目标**：用户选定 Skill 和群后，必须先回显目标群名、成员数与内容摘要，得到用户明确确认后才能发送；未确认前不得调用 send。
 
 ## Prerequisites
 
@@ -33,7 +36,9 @@ uv run {baseDir}/scripts/share_skill_to_friend.py <command> [args...]
 ```bash
 uv run {baseDir}/scripts/share_skill_to_friend.py list-skills
 uv run {baseDir}/scripts/share_skill_to_friend.py list-friends
+uv run {baseDir}/scripts/share_skill_to_friend.py list-groups
 uv run {baseDir}/scripts/share_skill_to_friend.py send --skill "<skill-name>" --friend-id <id> --friend-name "<name>"
+uv run {baseDir}/scripts/share_skill_to_friend.py send --skill "<skill-name>" --group-id <id>
 ```
 
 脚本会优先解析 JSON；如果 OpenClaw 命令输出包含 banner/config warnings，会自动从噪声中提取 JSON；如果实际拿到的是 `openclaw skills list` 的表格输出，也会尽量解析表格中的 Skill 名称、描述、状态和 Source。展示标签直接使用返回的 `source` 字段。
@@ -94,7 +99,11 @@ uv run {baseDir}/scripts/share_skill_to_friend.py list-skills
 4. 标签（如 `[openclaw-workspace]`）**不显示**，保持界面简洁
 5. 排序：openclaw-workspace → openclaw-managed → 其他内置 skill
 
-## Step 2：选择虾友
+## Step 2：选择目标（虾友或群聊）
+
+默认目标为虾友；仅当用户明确要求发送到群（如"发到 XX 群"、"分享到群里"）时走群分支，不要替用户猜测目标类型。
+
+### 分支 A：选择虾友（默认）
 
 用户选定 Skill 后执行：
 
@@ -133,19 +142,99 @@ uv run {baseDir}/scripts/share_skill_to_friend.py list-friends
 
 `displayName` 的生成规则：优先使用虾友备注名 `remark`，没有备注时使用昵称 `nickname`，都没有时显示「未命名虾友」。内部保留 `friendId` 供脚本调用，但**不要向用户展示虾友号**。如果昵称重复，只用列表序号区分，并可提示用户按序号选择。
 
-## Step 3：发送（含敏感信息确认）
+### 分支 B：选择群聊
+
+用户选定 Skill 后执行：
+
+```bash
+uv run {baseDir}/scripts/share_skill_to_friend.py list-groups
+```
+
+输出 JSON（**内部使用，勿向用户展示 `groupId` / 群 rid**）：
+
+```json
+{
+  "groups": [
+    {
+      "index": 1,
+      "groupId": 123,
+      "name": "产品交流群",
+      "memberCount": 8,
+      "myRole": "member",
+      "rid": "room-abc123"
+    }
+  ]
+}
+```
+
+使用以下格式向用户展示：
+
+```text
+👥 **请选择要发送到哪个群聊**
+
+1️⃣ **产品交流群**（8 人）
+
+2️⃣ **测试群**（3 人）
+
+💬 请回复 **序号** 或 **群名称**。
+```
+
+规则与虾友分支一致：不替用户猜测群聊；群名称重复时只用列表序号区分。内部保留 `groupId` / `rid` 供脚本调用，但**不要向用户展示**。
+
+## Step 3：发送（群目标先确认；自定义 Skill 含敏感信息确认）
+
+### 群目标：先回显确认，再发送
+
+群消息会广播给全体群成员且无法撤回。用户选定群后，**必须**先回显以下确认信息，得到用户明确同意（如回复「确认发送」）后才可执行发送；虾友目标无需此步骤。
+
+```text
+📤 **即将发送到群聊（请确认）**
+
+• 目标群：**产品交流群**（8 人）
+• 内容：`operations-dashboard` 的 Skill 分享卡片
+   📝 <中文功能介绍>
+
+💬 请回复 **「确认发送」** 执行，或回复 **「取消」** 返回。
+```
+
+用户确认后执行：
+
+```bash
+uv run {baseDir}/scripts/share_skill_to_friend.py send \
+  --skill "<skill-name>" \
+  --group-id <groupId> \
+  --description-zh "<中文功能介绍>"
+```
+
+发送成功返回（群目标为 `"group"` 字段，虾友目标为 `"friend"` 字段）：
+
+```json
+{
+  "success": true,
+  "skill": "operations-dashboard",
+  "group": { "groupId": 123, "name": "产品交流群", "memberCount": 8 },
+  "messageId": "<message-id>",
+  "message": "📝 功能介绍：...\n[claw-skill-share]\n{\"v\":1,...}\n[/claw-skill-share]"
+}
+```
+
+成功提示：
+
+```text
+✅已发送 `operations-dashboard` skill 到群聊「产品交流群」
+```
 
-用户选定虾友后，发送自定义 Skill 前，脚本会先扫描 Skill 目录是否包含私钥、token、`.env`、凭据文件等秘钥相关敏感信息。
+群目标解析失败（如账号不在目标群）时脚本会报错提示，此时向用户说明其可能不在该群，请先核对群聊选择，不要重试其他群。
 
 ### 敏感信息检测
 
-脚本会检测以下敏感信息：
+用户选定目标后，发送自定义 Skill 前，脚本会先扫描 Skill 目录是否包含私钥、token、`.env`、凭据文件等秘钥相关敏感信息（对虾友与群目标一视同仁）。脚本会检测以下敏感信息：
 - 敏感文件名：`.env`、`.env.local`、`credentials.json`、`id_rsa` 等
 - 敏感文件后缀：`.pem`、`.key`、`.p12`、`.pfx` 等
 - 敏感文件名关键词：`token`、`secret`、`password`、`credential`、`private_key` 等
 - 文件内容：私钥块、AWS Access Key、GitHub Token、Slack Token、JWT 等
 
-### 发送流程
+### 虾友目标发送流程
 
 首次发送（不带 `--allow-sensitive`）：
 
@@ -259,3 +348,6 @@ Agent 应向用户提示：
 - 敏感信息检测到的文件路径和原因可向用户展示，但**不要展示文件内容或密钥值**。
 - 不要替用户猜测虾友；必须让用户从列表中选择，或在用户主动提供时内部使用 `friendId`。
 - 用户侧输出中不要展示虾友号 / `friendId`。
+- 群目标同样不替用户猜测；必须让用户从 `list-groups` 结果中选择，或在用户明确指定群名时内部使用 `groupId`。
+- 用户侧输出中不要展示 `groupId` / 群 rid。
+- 群消息会广播给全部群成员且无法撤回：群发送前必须完成回显确认（群名 + 成员数 + 内容摘要），未经确认不得调用 send。

package/skills/share-skill/src/scripts/share_skill_to_friend.py

@@ -26,6 +26,8 @@ from typing import Any, Dict, Iterable, List, Optional, Pattern, Set, Tuple
 DEFAULT_BASE_URL = "https://yagent.sophnet.com/api"
 DEFAULT_TIMEOUT = 30
 JWT_PATH = "/home/node/.openclaw/jwt.json"
+REFRESH_URL = "https://sophnet.com/api/sys/login/refresh"
+REFRESH_MARGIN_SECONDS = 300
 DEFAULT_SKILLS_COMMAND = "openclaw skills list --json"
 DEFAULT_SKILL_INFO_COMMAND_TEMPLATE = "openclaw skills info {skill} --json"
 STORE_SKILLS_PATH = "/open-apis/skill-store/skills"
@@ -159,17 +161,93 @@ def jwt_exp_unix(token: str) -> Optional[int]:
         return None
 
 
-def ensure_jwt_valid_for_use(
-    token: str,
-    jwt_path: str,
-    clock_skew_sec: int = 60,
-) -> None:
+def refresh_web_jwt(jwt_path: str, timeout: int) -> str:
+    """用 web_refresh_token 换新 web_jwt 并写回 jwt.json。
+
+    逻辑适配自 claw-friend-message-capture 的 sophclaw_auth.py
+    （各 skill 安装目录相互独立，不做跨 skill import）。
+    """
+    try:
+        with open(jwt_path, "r", encoding="utf-8") as fp:
+            data = json.load(fp)
+    except OSError as exc:
+        raise AppError(f"无法读取 JWT 文件 {jwt_path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise AppError(f"JWT 文件不是有效 JSON: {jwt_path}: {exc}") from exc
+
+    refresh_token = (
+        str(data.get("web_refresh_token") or "").strip() if isinstance(data, dict) else ""
+    )
+    if not refresh_token:
+        raise AppError(
+            f"{jwt_path} 缺少 web_refresh_token，无法自动续期；请重新登录后刷新"
+        )
+    body = json.dumps({"refreshToken": refresh_token}, ensure_ascii=False).encode("utf-8")
+    # refresh 接口只认 sophnet.com 域名，不认 yagent.sophnet.com
+    req = urllib.request.Request(
+        url=REFRESH_URL,
+        data=body,
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        if exc.code == 401:
+            raise AppError("refresh token 已失效，请重新登录获取新的 JWT") from exc
+        detail = exc.read().decode("utf-8", errors="replace")[:300]
+        raise AppError(f"刷新 JWT 失败: HTTP {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise AppError(f"刷新 JWT 请求失败: {exc}") from exc
+    try:
+        res = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise AppError(f"刷新 JWT 返回不是有效 JSON: {exc}") from exc
+    if isinstance(res, dict) and res.get("status") not in (None, 0):
+        raise AppError(
+            f"刷新 JWT 接口错误: status={res.get('status')} message={res.get('message')!r}"
+        )
+    result = unwrap_result(res) if isinstance(res, dict) else {}
+    if not isinstance(result, dict):
+        result = {}
+    new_token = result.get("token") or result.get("accessToken")
+    new_refresh = result.get("refreshToken")
+    if not isinstance(new_token, str) or not new_token.strip():
+        raise AppError(f"刷新 JWT 接口未返回 token: {raw[:300]}")
+    new_token = new_token.strip()
+    if new_token.lower().startswith("bearer "):
+        new_token = new_token[7:].strip()
+    data["web_jwt"] = new_token
+    if isinstance(new_refresh, str) and new_refresh.strip():
+        data["web_refresh_token"] = new_refresh.strip()
+    try:
+        with open(jwt_path, "w", encoding="utf-8") as fp:
+            json.dump(data, fp, ensure_ascii=False, indent=2)
+    except OSError as exc:
+        print(f"WARN: 续期成功但写回 {jwt_path} 失败: {exc}", file=sys.stderr)
+    return new_token
+
+
+def get_web_token(args: argparse.Namespace) -> str:
+    """读取 web_jwt；已过期或临近过期时自动用 web_refresh_token 续期。"""
+    token = read_bearer_token(args.jwt_path)
+    if getattr(args, "allow_expired_jwt", False):
+        return token
     exp = jwt_exp_unix(token)
-    if exp is None:
-        return
     now = int(time.time())
-    if now >= exp + clock_skew_sec:
-        raise AppError(f"JWT 已过期，请重新登录后刷新 {jwt_path}")
+    if exp is None or now < exp - REFRESH_MARGIN_SECONDS:
+        return token
+    try:
+        return refresh_web_jwt(args.jwt_path, args.timeout)
+    except AppError as exc:
+        if exp is not None and now >= exp:
+            raise AppError(
+                f"JWT 已过期且自动续期失败（{exc}）。请重新登录后刷新 {args.jwt_path}"
+            ) from exc
+        # 尚未真正过期：续期失败不阻断，沿用当前 token
+        print(f"WARN: JWT 自动续期失败（{exc}），使用当前 token 继续", file=sys.stderr)
+        return token
 
 
 def make_headers(token: str, content_type: Optional[str] = None) -> StringDict:
@@ -555,9 +633,7 @@ def merge_skill_detail(args: argparse.Namespace, skill: JsonDict) -> JsonDict:
 
 
 def load_friends(args: argparse.Namespace) -> List[JsonDict]:
-    token = read_bearer_token(args.jwt_path)
-    if not args.allow_expired_jwt:
-        ensure_jwt_valid_for_use(token, args.jwt_path)
+    token = get_web_token(args)
     url = f"{normalize_base_url(args.base_url)}/sys/openclaw/friend/list"
     data = request_json("GET", url, token, args.timeout)
     result = unwrap_result(data) or {}
@@ -589,6 +665,47 @@ def load_friends(args: argparse.Namespace) -> List[JsonDict]:
     return out
 
 
+def load_groups(args: argparse.Namespace) -> List[JsonDict]:
+    """列出当前账号所在的虾友群（含 groupId / 群 rid，仅内部使用，不向用户展示）。"""
+    token = get_web_token(args)
+    url = f"{normalize_base_url(args.base_url)}/sys/openclaw/group/list"
+    data = request_json("GET", url, token, args.timeout)
+    result = unwrap_result(data) or {}
+    groups = result.get("groups") if isinstance(result, dict) else None
+    if not isinstance(groups, list):
+        raise AppError("群列表接口缺少 groups 数组")
+
+    out: List[JsonDict] = []
+    for item in groups:
+        if not isinstance(item, dict):
+            continue
+        raw_id = item.get("id") if item.get("id") is not None else item.get("groupId")
+        try:
+            group_id = int(raw_id)
+        except (TypeError, ValueError):
+            continue
+        out.append({
+            "groupId": group_id,
+            "name": str(item.get("name") or "未命名群聊").strip(),
+            "memberCount": item.get("memberCount"),
+            "myRole": item.get("myRole"),
+            "rid": str(item.get("rid") or "").strip(),
+        })
+    out.sort(key=lambda g: str(g["name"]))
+    for idx, group in enumerate(out, start=1):
+        group["index"] = idx
+    return out
+
+
+def resolve_group(args: argparse.Namespace, group_id: int) -> JsonDict:
+    for group in load_groups(args):
+        if group["groupId"] == group_id:
+            return group
+    raise AppError(
+        f"未找到群聊 groupId={group_id}，当前账号可能不在该群或该群不存在；请用 list-groups 核对"
+    )
+
+
 def encode_skill_share_message(payload: JsonDict, prefix: str = "") -> str:
     head = f"{prefix.strip()}\n" if prefix and prefix.strip() else ""
     body = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
@@ -931,12 +1048,27 @@ def build_parser() -> argparse.ArgumentParser:
     p = sub.add_parser("list-friends", help="列出当前账号虾友")
     add_common_args(p)
 
+    p = sub.add_parser("list-groups", help="列出当前账号所在的虾友群")
+    add_common_args(p)
+
     for name in ("preview", "send"):
         p = sub.add_parser(name, help="预览或发送 Skill 功能介绍")
         add_common_args(p)
         p.add_argument("--skill", required=True, help="Skill 名称或 list-skills 返回的序号")
-        p.add_argument("--friend-id", type=int, required=True, help="目标虾友 friendId")
+        p.add_argument(
+            "--friend-id",
+            type=int,
+            default=0,
+            help="目标虾友 friendId（与 --group-id 二选一）",
+        )
         p.add_argument("--friend-name", default="", help="目标虾友展示名")
+        p.add_argument(
+            "--group-id",
+            type=int,
+            default=0,
+            help="目标群聊 groupId（与 --friend-id 二选一；群 rid 由脚本内部经 group/list 解析）",
+        )
+        p.add_argument("--group-name", default="", help="目标群聊展示名（仅 preview 展示用）")
         p.add_argument("--description-zh", default="", help="可选：由 Agent 改写的中文功能介绍")
         p.add_argument(
             "--allow-sensitive",
@@ -960,9 +1092,14 @@ def main(argv: Optional[List[str]] = None) -> int:
         if args.command == "list-friends":
             print_json({"friends": load_friends(args)})
             return 0
+        if args.command == "list-groups":
+            print_json({"groups": load_groups(args)})
+            return 0
 
-        if args.friend_id <= 0:
-            raise AppError("friend-id 必须为正整数")
+        if args.friend_id < 0 or args.group_id < 0:
+            raise AppError("friend-id / group-id 必须为正整数")
+        if (args.friend_id > 0) == (args.group_id > 0):
+            raise AppError("必须且只能指定 --friend-id 或 --group-id 之一")
         skill = merge_skill_detail(args, find_skill(args, args.skill))
         friend_name = (args.friend_name or "未命名虾友").strip()
         sensitive_findings: List[StringDict] = []
@@ -973,19 +1110,35 @@ def main(argv: Optional[List[str]] = None) -> int:
             )
         if args.command == "preview":
             message = build_preview_message(skill, args.description_zh)
+            target: JsonDict
+            if args.group_id > 0:
+                target = {
+                    "group": {"groupId": args.group_id, "name": args.group_name.strip()}
+                }
+            else:
+                target = {
+                    "friend": {"friendId": args.friend_id, "displayName": friend_name}
+                }
             print_json({
                 "skill": skill,
-                "friend": {"friendId": args.friend_id, "displayName": friend_name},
+                **target,
                 "message": message,
                 "sensitiveFindings": sensitive_findings if sensitive_findings else None,
             })
             return 0
 
-        token = read_bearer_token(args.jwt_path)
-        if not args.allow_expired_jwt:
-            ensure_jwt_valid_for_use(token, args.jwt_path)
+        token = get_web_token(args)
         base_url = normalize_base_url(args.base_url)
-        rid = get_or_create_dm(base_url, token, args.friend_id, args.timeout)
+        group: Optional[JsonDict] = None
+        if args.group_id > 0:
+            group = resolve_group(args, args.group_id)
+            rid = str(group.get("rid") or "")
+            if not rid:
+                raise AppError(
+                    f"群「{group.get('name')}」缺少 rid，无法发送；请联系管理员检查群数据"
+                )
+        else:
+            rid = get_or_create_dm(base_url, token, args.friend_id, args.timeout)
         prefix = build_intro_prefix(skill, args.description_zh)
         if skill.get("storeSlug"):
             payload = build_store_payload(skill, prefix)
@@ -1009,14 +1162,21 @@ def main(argv: Optional[List[str]] = None) -> int:
             )
             message = encode_skill_share_message(payload, prefix)
         sent = send_message(base_url, token, rid, message, args.timeout)
-        result = {
+        result: JsonDict = {
             "success": True,
             "skill": skill["name"],
-            "friend": {"friendId": args.friend_id, "displayName": friend_name},
             "rid": rid,
             "messageId": sent.get("_id"),
             "message": message,
         }
+        if group is not None:
+            result["group"] = {
+                "groupId": group["groupId"],
+                "name": group["name"],
+                "memberCount": group.get("memberCount"),
+            }
+        else:
+            result["friend"] = {"friendId": args.friend_id, "displayName": friend_name}
         if sensitive_findings:
             result["sensitiveFindings"] = sensitive_findings
             result["sensitiveWarning"] = "已发送包含敏感信息的 Skill，请确认接收方可信"