sino-bc-cli 1.8.26 → 1.8.27

package/dist/skills/custom/biz-line-strategy-generate/scripts/run_workflow.py

@@ -22,9 +22,10 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from build_report import default_output_path, validate_xlsx, write_xlsx
 from cleanup import OwnedDirectory, MARKER
-from cli_json import cli_context
-from fetch_data import argument_parser, fetch_business
+from cli_json import cli_context, load_json_file
+from fetch_data import argument_parser, fetch_business, resolve_periods
 from summarize import summarize_request
+from strategy_output import (TagCache, GenerationOutcome, attach_tags, review_tags, ready_body, upload_excel, save_result)
 
 _output_lock = threading.Lock()
 
@@ -68,6 +69,9 @@ def execute_business(target, args, batch, cancel, progress=emit):
     current_stage = 'fetch'
     started = time.perf_counter()
     final = None
+    database = args.output_mode == 'database'
+    save_attempted = False
+    context = None
 
     def stage(name, function):
         nonlocal current_stage
@@ -83,25 +87,70 @@ def execute_business(target, args, batch, cancel, progress=emit):
 
     try:
         # 最终目录必须在整个批次临时树之外，而非仅在当前业务线之外。
-        output_dir = Path(args.output_dir).resolve()
-        if output_dir.is_relative_to(batch.path):
+        output_dir = Path(args.output_dir or Path(default_output_path()).parent).resolve() if not database else None
+        if output_dir is not None and output_dir.is_relative_to(batch.path):
             raise ValueError('最终 Excel 目录不能位于批次临时目录内')
         local_args = Namespace(**{**vars(args), 'id': target or 0, 'request_dir': str(owned.path)})
         with cli_context(cancel, lambda text: progress({'id': result['id'], 'stage': 'fetch', 'detail': text})):
             biz = stage('fetch', lambda: fetch_business(local_args))
         result['id'], result['name'] = int(biz['id']), str(biz.get('name') or '')
+        context = load_json_file(owned.path / 'save-context.json') if database else None
         payload, summary = stage('analyze', lambda: summarize_request(owned.path))
         result['detail_count'] = summary['detail_count']
-        safe_name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '_', result['name'])[:55].rstrip(' .') or '业务线'
-        final = output_dir / f'业务线策略_{result["id"]}_{safe_name}_{owned.token[:12]}.xlsx'
-        output_dir.mkdir(parents=True, exist_ok=True)
+        if database and summary['curr_total'] <= 0:
+            raise GenerationOutcome('NO_DELIVERY_DATA', '目标周期无投放消耗')
+        with cli_context(cancel, lambda text: progress({'id': result['id'], 'stage': 'tags', 'detail': text})):
+            dictionaries = args.tag_cache.get(biz)
+            evidence = summary.get('tag_evidence', {})
+            selections = stage('tag_review', lambda: review_tags(payload['rows'][0], dictionaries, evidence,
+                               owned.path, cancel, lambda event: progress({'id': result['id'], **event})))
+            stage('tags', lambda: attach_tags(payload['rows'][0], dictionaries, evidence, selections))
+        if database:
+            if not context:
+                raise ValueError('缺少可保存业务线及周期上下文')
+            ready_body(context, payload['rows'][0], 'preflight')
         temp = owned.path / 'final.xlsx'
         stage('export', lambda: write_xlsx(payload['rows'], str(temp), payload['details']))
-        stage('validate_publish', lambda: publish(temp, final, payload))
-        result['output_path'] = str(final)
+        if database:
+            stage('validate', lambda: validate_xlsx(temp, payload['rows'], payload['details']))
+            with cli_context(cancel, lambda text: progress({'id': result['id'], 'stage': current_stage, 'detail': text})):
+                result['storageKey'] = stage('upload', lambda: upload_excel(owned.path, temp))
+                # 仅删除自己创建且归属已验证的临时文件，上传成功后不留桌面副本。
+                owned.validate()
+                stage('remove_excel', temp.unlink)
+                body = ready_body(context, payload['rows'][0], result['storageKey'])
+                if cancel.is_set():
+                    raise InterruptedError('任务已取消')
+                save_attempted = True
+                result['aiStrategyId'] = stage('save', lambda: save_result(owned.path, body))
+            result.update(generateCode='READY', database_saved=True)
+        else:
+            safe_name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '_', result['name'])[:55].rstrip(' .') or '业务线'
+            final = output_dir / f'业务线策略_{result["id"]}_{safe_name}_{owned.token[:12]}.xlsx'
+            output_dir.mkdir(parents=True, exist_ok=True)
+            stage('validate_publish', lambda: publish(temp, final, payload))
+            result['output_path'] = str(final)
         result['ok'] = True
     except Exception as exc:
         result.update(error=str(exc), failed_stage=current_stage)
+        # 保存请求发出后不补写失败状态；超时可能已成功，补写会替换有效记录。
+        if database and not save_attempted and not cancel.is_set():
+            context = context or load_json_file(owned.path / 'save-context.json')
+            if context:
+                code = exc.code if isinstance(exc, GenerationOutcome) else 'GENERATION_FAILED'
+                result.update(id=context['bizLineId'], generateCode=code)
+                try:
+                    with cli_context(cancel, lambda _: None):
+                        result['aiStrategyId'] = stage('save_status', lambda: save_result(owned.path, {
+                            **context, 'generateCode': code, 'remark': str(exc),
+                        }))
+                    result['database_saved'] = True
+                    # 不可生成是业务结果；技术失败即使状态保存成功仍返回失败。
+                    result['ok'] = isinstance(exc, GenerationOutcome)
+                except Exception as save_error:
+                    result.update(database_saved=False, save_error=str(save_error), save_result_unknown=True)
+        elif save_attempted:
+            result.update(database_saved=False, save_result_unknown=True)
         if isinstance(exc, PublishError):
             result['residual_output'] = exc.residual_path
     finally:
@@ -115,61 +164,109 @@ def execute_business(target, args, batch, cancel, progress=emit):
     return result
 
 
+def retry_allowed(result):
+    """只重跑未交付的技术失败；保存未知、残留文件及已处理业务状态需单独报告。"""
+    return not (result.get('ok') or result.get('save_result_unknown')
+                or result.get('cleanup_failed') or result.get('residual_output')
+                or result.get('output_path')
+                or result.get('failed_stage') in ('cancelled', 'worker')
+                or (result.get('database_saved') and result.get('generateCode') != 'GENERATION_FAILED'))
+
+
 def run_batch(args, *, cancel=None, worker=execute_business, progress=emit, temp_parent=None):
-    """只提交可立即运行的三个任务；已完成任务交付后继续补位。"""
+    """每轮最多三个并发，整轮结束才重跑失败项，每条含首次最多三次。"""
     if args.concurrency not in (1, 2, 3):
         raise ValueError('并发只能设置为 1、2 或 3')
+    if args.output_mode not in ('excel', 'database'):
+        raise ValueError('输出模式必须为 excel 或 database')
+    if args.output_mode == 'database' and args.output_dir:
+        raise ValueError('database 模式不接受 --output-dir，不向桌面发布 Excel')
     if any(i <= 0 for i in args.id):
         raise ValueError('业务线 ID 必须为正整数')
-    for prefix in ('curr', 'prev'):
-        if bool(getattr(args, f'{prefix}_start')) != bool(getattr(args, f'{prefix}_end')):
-            raise ValueError('用户指定的起止日期必须成对提供')
+    # 批次开始时固定日期，避免任务跨越周一零点后使用不同的默认周。
+    periods = resolve_periods(args)
+    args = Namespace(**{**vars(args), **{
+        key + suffix: bounds[index]
+        for key, bounds in periods.items()
+        for index, suffix in enumerate(('_start', '_end'))
+    }})
     targets = list(dict.fromkeys(args.id)) if args.id else [None]
     cancel = cancel or threading.Event()
     batch = OwnedDirectory.create(Path(temp_parent or tempfile.gettempdir()) / 'sino-bc-strategy', 'batch-')
-    results, pending = [], {}
-    remaining = iter(targets)
+    # 共享字典独立归属；业务线清理不触碰它，批次结束单独清理。
+    tags_owned = OwnedDirectory.create(batch.path, 'tags-')
+    args = Namespace(**{**vars(args), 'tag_cache': TagCache(tags_owned.path)})
+    latest, history = {}, {target: [] for target in targets}
+    round_targets = targets
     started = time.perf_counter()
     try:
         with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
-            while True:
-                while not cancel.is_set() and len(pending) < args.concurrency:
-                    try:
-                        target = next(remaining)
-                    except StopIteration:
+            for attempt in range(1, 4):
+                if attempt > 1:
+                    if cancel.is_set():
                         break
-                    pending[pool.submit(worker, target, args, batch, cancel, progress)] = target
-                if not pending:
+                    args.tag_cache.reset_errors()
+                    progress({'event': 'retry_round', 'attempt': attempt, 'targets': round_targets})
+                pending, remaining = {}, iter(round_targets)
+                while True:
+                    while not cancel.is_set() and len(pending) < args.concurrency:
+                        try:
+                            target = next(remaining)
+                        except StopIteration:
+                            break
+                        pending[pool.submit(worker, target, args, batch, cancel, progress)] = target
+                    if not pending:
+                        break
+                    finished, _ = wait(pending, timeout=0.2, return_when=FIRST_COMPLETED)
+                    for future in finished:
+                        target = pending.pop(future)
+                        try:
+                            result = future.result()
+                        except Exception as exc:
+                            # worker 之外异常无法保证副作用状态，不能盲目整条重放。
+                            result = {'id': target, 'ok': False, 'error': str(exc), 'failed_stage': 'worker'}
+                        result['attempt'] = attempt
+                        history[target].append(result.copy())
+                        latest[target] = result
+                        progress({'event': 'completed', **result})
+                # 取消时保留此前失败记录；首次未启动条目仍计入最终结果。
+                for target in remaining:
+                    if target not in latest:
+                        latest[target] = {'id': target, 'ok': False, 'failed_stage': 'cancelled',
+                                          'error': '任务未启动，已取消'}
+                round_targets = [target for target in round_targets if retry_allowed(latest[target])]
+                if not round_targets or cancel.is_set():
                     break
-                finished, _ = wait(pending, timeout=0.2, return_when=FIRST_COMPLETED)
-                for future in finished:
-                    target = pending.pop(future)
-                    try:
-                        result = future.result()
-                    except Exception as exc:
-                        result = {'id': target, 'ok': False, 'error': str(exc), 'failed_stage': 'worker'}
-                    results.append(result)
-                    progress({'event': 'completed', **result})
-            # 未启动任务也要明确返回取消状态，不能从批次结果中消失。
-            for target in remaining:
-                results.append({'id': target, 'ok': False, 'failed_stage': 'cancelled', 'error': '任务未启动，已取消'})
     finally:
+        tags_cleanup = tags_owned.cleanup()
         # 已失败的清理目录保留并报告，不由父级递归重试掩盖错误。
         batch.validate()
         children = [p for p in batch.path.iterdir() if p.name != MARKER]
         cleanup = ({'ok': False, 'residual': [{'path': str(p), 'error': '业务线目录尚有残留'} for p in children]} if children else batch.cleanup())
+        if not tags_cleanup['ok']:
+            cleanup['ok'] = False
+            cleanup.setdefault('residual', []).extend(tags_cleanup.get('residual', []))
+    # 同一业务线仅按最终一次统计，历史失败供定位，不重复计入失败数。
+    results = [{**latest[target], 'attempts': len(history[target]), 'attempt_history': history[target]}
+               for target in targets]
     success = sum(r['ok'] for r in results)
     return {'ok': success == len(targets) and cleanup['ok'] and not cancel.is_set(), 'success': success,
             'failed': len(results) - success, 'results': results, 'cleanup': cleanup,
             'elapsed_seconds': round(time.perf_counter() - started, 3)}
 
 
-def main():
+def workflow_parser():
+    """入口参数集中构建，便于验证默认本地输出和显式数据库输出。"""
     parser = argument_parser(batch=True)
     parser.description = __doc__
     parser.add_argument('--concurrency', type=int, choices=(1, 2, 3), default=3)
-    parser.add_argument('--output-dir', default=str(Path(default_output_path()).parent))
-    args = parser.parse_args()
+    parser.add_argument('--output-dir', default=None)
+    parser.add_argument('--output-mode', choices=('excel', 'database'), default='excel')
+    return parser
+
+
+def main():
+    args = workflow_parser().parse_args()
     cancel = threading.Event()
     # 可处理的 Ctrl+C/SIGTERM 只发信号，worker 关闭自己的 CLI 后清理。
     previous = {sig: signal.signal(sig, lambda *_: cancel.set()) for sig in (signal.SIGINT, signal.SIGTERM)}

package/dist/skills/custom/biz-line-strategy-generate/scripts/strategy_output.py

@@ -0,0 +1,277 @@
+"""策略工作流的标签、业务预检及入库计划；所有网络请求仍由 CLI 执行。"""
+from datetime import date, timedelta
+import json
+import re
+import threading
+import time
+
+from cli_json import optional_num, require_ok, run_cli
+
+# 本地行字段与服务字段集中映射，Excel 和数据库共享同一份分析结果。
+STRATEGIES = {'budget': 'budget', 'product': 'media', 'audience': 'audience', 'creative': 'creative'}
+SCENES = {'budget': 'BUDGET_STRATEGY', 'product': 'MEDIA_STRATEGY', 'audience': 'AUDIENCE_STRATEGY'}
+CHANNEL_NAMES = {'facebook', 'meta', 'fb', 'google', 'gg', 'tiktok', 'tik tok', 'tt'}
+RESULT_CODES = {'READY', 'NO_PROJECT', 'UNSUPPORTED_CHANNEL', 'NO_AD_ACCOUNT', 'NO_DELIVERY_DATA', 'GENERATION_FAILED'}
+
+
+def industry_condition(biz):
+    """行业筛选严格取业务线第一个行业 ID，不使用后续行业或人工默认值兜底。"""
+    ids = biz.get('adCategoryIndustryIds')
+    if not isinstance(ids, list) or not ids or type(ids[0]) is not int or ids[0] <= 0:
+        raise ValueError('业务线 adCategoryIndustryIds 缺少有效的首个行业 ID，无法查询策略标签')
+    return str(ids[0])
+
+
+class TagCache:
+    """同批次按行业缓存三类标签与错误；锁内加载避免并发重复查询。"""
+    def __init__(self, root):
+        self.root = root
+        self.lock = threading.Lock()
+        self.values, self.errors = {}, {}
+
+    def reset_errors(self):
+        """整轮结束后才清除失败缓存，成功行业字典继续在本批次复用。"""
+        with self.lock:
+            self.errors.clear()
+
+    def get(self, biz):
+        """同行业复用，不同行业使用独立文件目录；不跨批次复用过期字典。"""
+        condition = industry_condition(biz)
+        with self.lock:
+            if condition in self.errors:
+                raise RuntimeError(self.errors[condition])
+            if condition not in self.values:
+                try:
+                    industry_root = self.root / ('industry-' + condition)
+                    industry_root.mkdir(parents=True, exist_ok=True)
+                    self.values[condition] = load_tags(industry_root, condition)
+                except Exception as exc:
+                    self.errors[condition] = str(exc)
+                    raise
+            return self.values[condition]
+
+
+class GenerationOutcome(RuntimeError):
+    """预期不可生成结果，与传输错误分开，防止失败回包被解释成无数据。"""
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+
+
+def validate_period(start, end, today=None):
+    """保存接口只接受已结束且受支持的完整自然周，不发送展示状态。"""
+    start, end = date.fromisoformat(start), date.fromisoformat(end)
+    if start.weekday() != 0 or end != start + timedelta(days=6):
+        raise ValueError('入库周期必须是同一自然周的周一至周日')
+    if end >= (today or date.today()):
+        raise ValueError('入库周期尚未结束')
+    if start < date(2026, 9, 7):
+        raise ValueError('入库周期早于当前契约支持的 2026-09-07')
+
+
+def precheck_projects(root, biz_id, expected_ids=None, *, skip_spend_check=False):
+    """逐页统计上周消耗及全部项目渠道，不缓存全量项目、不按消耗预筛。"""
+    total = None
+    count = 0
+    all_zero, positive, channels_complete = True, False, True
+    channels, seen = set(), set()
+    for page in range(1, 81):
+        env = require_ok(run_cli(['biz-line', '+queryByPage'], {
+            'bizLineIdList': [biz_id], 'pageNum': page, 'pageSize': 100,
+        }, root / f'precheck.p{page}.out.json'), '项目预检')
+        data = env.get('data')
+        if not isinstance(data, dict) or not isinstance(data.get('result'), list) or type(data.get('total')) is not int or data['total'] < 0:
+            raise RuntimeError('项目预检分页格式无效')
+        if total is not None and total != data['total']:
+            raise RuntimeError('项目预检分页总数变化')
+        total = data['total']
+        rows = data['result']
+        for item in rows:
+            if not isinstance(item, dict) or item.get('projectId') is None or item['projectId'] in seen:
+                raise RuntimeError('项目预检含无效或重复项目')
+            seen.add(item['projectId'])
+            value = optional_num(item, 'lastWeekSpend')
+            if isinstance(item.get('lastWeekSpend'), bool):
+                value = None
+            all_zero = all_zero and value == 0
+            positive = positive or (value is not None and value > 0)
+            ids = item.get('channelIdList')
+            if not isinstance(ids, list) or not ids:
+                channels_complete = False
+            else:
+                channels.update(str(v).strip() for v in ids)
+        count += len(rows)
+        if count > total:
+            raise RuntimeError('项目预检累计数量超过总数')
+        if count == total:
+            break
+        if not rows or page == 80:
+            raise RuntimeError('项目预检分页未取全')
+    # 服务端默认只查代投服务，必须用业务线关联 ID 校验覆盖，防止漏项目误判全零。
+    if expected_ids is not None and {str(v) for v in seen} != {str(v) for v in expected_ids}:
+        raise RuntimeError('项目分页未覆盖业务线全部关联项目（接口默认服务范围为 1、85），不能判断无项目或消耗全零')
+    if not count:
+        raise GenerationOutcome('NO_PROJECT', '业务线未关联项目')
+    # 仅用户显式跳过时不按项目上周消耗拦截；项目完整性、渠道及后续目标周期检查仍保留。
+    if not skip_spend_check and all_zero:
+        raise GenerationOutcome('NO_DELIVERY_DATA', '全部关联项目上周消耗 lastWeekSpend 均为 0')
+    if not skip_spend_check and not positive:
+        raise RuntimeError('项目上周消耗缺失或异常，不能判断为全零')
+    env = require_ok(run_cli(['media', '+channels'], None, root / 'channels.out.json'), '渠道字典')
+    if not isinstance(env.get('data'), list):
+        raise RuntimeError('渠道字典格式无效')
+    supported = {str(item['channelId']) for item in env['data'] if isinstance(item, dict)
+                 and item.get('channelId') is not None and str(item.get('channelName', '')).strip().lower() in CHANNEL_NAMES}
+    if not channels_complete or not channels or not channels <= supported:
+        raise GenerationOutcome('UNSUPPORTED_CHANNEL', '全部项目渠道必须完整且只包含 FB、GG、TT')
+
+
+def load_tags(root, condition):
+    """每批次串行获取三类字典，保留服务返回的 ID 与名称，不虚构枚举。"""
+    if not isinstance(condition, str) or not condition.isdecimal() or int(condition) <= 0:
+        raise ValueError('策略字典筛选值必须是业务线首个行业 ID 的字符串')
+    result = {}
+    for key, scene in SCENES.items():
+        # 三个场景共用该业务线首个行业 ID，保留真实字典 ID/name。
+        query = {'sceneCode': scene, 'filterCondition': condition}
+        env = require_ok(run_cli(['biz-line', '+categories'], query,
+                                 root / f'tags-{key}.out.json'), f'{scene} 字典')
+        data = env.get('data')
+        if not isinstance(data, list) or not data:
+            raise ValueError(f'{scene} 字典为空或格式无效，无法取得标签 ID，请核对服务端场景字典配置')
+        result[key] = flatten_tags(data)
+    return result
+
+
+def flatten_tags(items):
+    """兼容字典 children 树，重复 ID 必须对应同名，避免输出与写入不一致。"""
+    found = {}
+    def visit(nodes):
+        for item in nodes:
+            if not isinstance(item, dict) or type(item.get('id')) is not int or item['id'] <= 0 or not isinstance(item.get('name'), str) or not item['name'].strip():
+                raise ValueError('策略字典缺少有效 ID/name')
+            if item['id'] in found and found[item['id']]['name'] != item['name']:
+                raise ValueError('策略字典同 ID 对应不同名称')
+            found[item['id']] = item
+            children = item.get('children')
+            if children is not None:
+                if not isinstance(children, list):
+                    raise ValueError('策略字典 children 格式无效')
+                visit(children)
+    visit(items)
+    return list(found.values())
+
+
+def reviewed_tags(labels, selections):
+    """校验 Agent 内容分析结果：只接受本场景真实 ID、有理由的非重复选择。"""
+    by_id = {item['id']: item for item in flatten_tags(labels)}
+    if not isinstance(selections, list) or not selections:
+        raise ValueError('每类策略必须提供至少一个标签选择及理由')
+    matched = []
+    for choice in selections:
+        if not isinstance(choice, dict) or type(choice.get('id')) is not int or choice['id'] not in by_id:
+            raise ValueError('标签选择包含不属于本行业本场景的 ID')
+        if not isinstance(choice.get('reason'), str) or not choice['reason'].strip():
+            raise ValueError('标签选择必须说明策略内容与标签的对应关系；其他须说明无适合项')
+        item = by_id[choice['id']]
+        if item in matched:
+            raise ValueError('标签选择包含重复 ID')
+        matched.append(item)
+    if len(matched) > 1 and any(item.get('isOther') == 1 or item['name'].strip() == '其他' for item in matched):
+        raise ValueError('有适合标签时不能同时选其他')
+    if any(item.get('isOther') == 1 or item['name'].strip() == '其他' for item in matched):
+        others = [item for item in by_id.values() if item.get('isOther') == 1 or item['name'].strip() == '其他']
+        if len(others) != 1:
+            raise ValueError('本场景缺少唯一其他标签，不能任意选择兜底')
+    if len(json.dumps([item['id'] for item in matched])) > 500:
+        raise ValueError('策略标签 ID 数组序列化后超过 500 字符')
+    return matched
+
+
+def review_tags(row, dictionaries, evidence, root, cancel, progress):
+    """向当前 Agent 交接正文与候选标签，等待其语义分析结果；不自动退回其他。"""
+    request = root / 'tag-review.request.json'
+    response = root / 'tag-review.response.json'
+    content = {key: {'strategy': row[key + 'Strategy'], 'labels': dictionaries[key],
+                     'facts': evidence.get(key, [])} for key in SCENES}
+    request.write_text(json.dumps(content, ensure_ascii=False, indent=2), encoding='utf-8')
+    progress({'event': 'tag_review_required', 'request_path': str(request), 'response_path': str(response)})
+    deadline = time.monotonic() + 1800
+    while not cancel.is_set():
+        if response.exists():
+            selections = json.loads(response.read_text(encoding='utf-8-sig'))
+            if not isinstance(selections, dict) or set(selections) != set(SCENES):
+                raise ValueError('标签分析结果必须包含 budget/product/audience 三类')
+            # 返回前校验三类全部有效，避免部分赋值后继续导出。
+            for key in SCENES:
+                reviewed_tags(dictionaries[key], selections[key])
+            return selections
+        if time.monotonic() >= deadline:
+            raise TimeoutError('等待 Agent 分析策略标签超时，未自动选择其他')
+        cancel.wait(0.2)
+    raise InterruptedError('任务已取消')
+
+
+def attach_tags(row, dictionaries, evidence, selections):
+    """展示名称与保存 ID 同时生成，防止 Excel 与数据库各自重新匹配。"""
+    for key in SCENES:
+        matched = reviewed_tags(dictionaries[key], selections[key])
+        row[key + 'TagIds'] = [item['id'] for item in matched]
+        row[key + 'Tags'] = '\n'.join(item['name'] for item in matched)
+
+
+def effect_code(verdict):
+    """以分析器的结构化结论编码，预警仍归入待观察。"""
+    if verdict == '有效':
+        return 1
+    if verdict == '无效':
+        return 2
+    if verdict in ('待观察', '待观察（预警）', '待观察（潜力）'):
+        return 3
+    raise ValueError(f'未知策略效果结论：{verdict}')
+
+
+def ready_body(context, row, storage_key):
+    """组装服务条件必填字段；上传前也可用占位 key 预检，避免产生无用上传。"""
+    if not isinstance(storage_key, str) or not storage_key.strip() or len(storage_key) > 512:
+        raise ValueError('缺少有效 Excel storageKey')
+    body = {**context, 'generateCode': 'READY', 'fileStorageKey': storage_key}
+    for local, remote in STRATEGIES.items():
+        for suffix, destination in [('Strategy', 'creativeStrategy' if local == 'creative' else remote + 'StrategySupplement'),
+                                    ('Learning', remote + 'StrategyLearning')]:
+            value = row.get(local + suffix)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f'{local + suffix} 不能为空')
+            body[destination] = value
+        effect = row.get(local + 'Effect')
+        if type(effect) is not int or effect not in (1, 2, 3):
+            raise ValueError(f'{local} 效果必须为 1/2/3')
+        body[remote + 'StrategyEffect'] = effect
+        if local in SCENES:
+            tags = row.get(local + 'TagIds')
+            if not isinstance(tags, list) or not tags or any(type(v) is not int or v <= 0 for v in tags) or len(json.dumps(tags)) > 500:
+                raise ValueError(f'{local} 策略标签 ID 无效')
+            body[remote + 'StrategyTags'] = tags
+    return body
+
+
+def upload_excel(root, path):
+    """通用上传返回值已经被 CLI 解包为 data；不使用营销协同 file 域。"""
+    env = require_ok(run_cli(['common-file', '+upload'], {'file': str(path), 'serviceName': 'sino-opti-hive'},
+                             root / 'upload.out.json'), 'Excel 上传')
+    data = env.get('data')
+    key = data.get('storageKey') if isinstance(data, dict) else None
+    if not isinstance(key, str) or not key.strip() or len(key) > 512:
+        raise RuntimeError('上传未返回有效 storageKey')
+    return key
+
+
+def save_result(root, body):
+    """非幂等保存只尝试一次，错误或不完整回包交由调用方报告，不重试。"""
+    if body.get('generateCode') not in RESULT_CODES:
+        raise ValueError('禁止保存展示状态或未知 generateCode')
+    env = require_ok(run_cli(['biz-line', '+ai-strategy-save'], body, root / 'save.out.json'), 'AI 策略保存失败或结果未知')
+    ident = env.get('data')
+    if type(ident) is not int or ident <= 0:
+        raise RuntimeError('保存未返回有效 aiStrategyId，结果未知，不自动重试')
+    return ident