@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/provider-select.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# provider-select —— 在**两个并存 provider** 之间切换「默认 provider」（2026-09-30，Argent 0.3）
+#
+# ## 为什么不是改 baseURL
+# 旧脚本 provider-switch.sh 直接改写 `llm-deepseek.baseURL` ⇒ **劫持官方直连 provider**
+# （provider id 仍叫 deepseek-official，实际指向问述）。用户纠正后改为：
+#   · `llm-deepseek` 实例 = **真·官方**（api.deepseek.com / DEEPSEEK_API_KEY）
+#   · `llm-whyshu`  实例 = **问述代理**（whyshu.com/api/argent/v1 / WHYSHU_API_KEY，provider id=whyshu）
+# 本脚本只切 `agent-default-model.config.provider`（用户仍可在设置页自由选择，二者并存）。
+#
+# 用法：
+#   bash scripts/provider-select.sh status     # 当前默认 provider + 两个 provider 的地址
+#   bash scripts/provider-select.sh whyshu     # 默认走问述代理（扣积分）
+#   bash scripts/provider-select.sh deepseek   # 默认走官方直连（自带 Key，不扣积分）
+set -uo pipefail
+PATCH="${ARGENT_CORDIS_PATCH:-$HOME/.dsh/profiles/web/cordis.patch.yml}"
+PY="${ARGENT_PY:-$HOME/.dsh/argent/venv/bin/python3}"; [ -x "$PY" ] || PY=python3
+
+[ -f "$PATCH" ] || { echo "✗ 找不到组合补丁：$PATCH" >&2; exit 2; }
+
+"$PY" - "$PATCH" "${1:-status}" <<'PY'
+import sys, yaml, pathlib, shutil, datetime
+path, action = sys.argv[1], sys.argv[2]
+p = pathlib.Path(path)
+doc = yaml.safe_load(p.read_text(encoding='utf-8')) or []
+
+def entry(eid):
+    return next((e for e in doc if isinstance(e, dict) and e.get('id') == eid), None)
+
+def provider_of(eid):
+    e = entry(eid) or {}
+    return ((e.get('config') or {}).get('apiKeyEnv') or '').replace('_API_KEY', '')
+
+default = entry('agent-default-model') or {}
+cur = (default.get('config') or {}).get('provider') or '(未设置)'
+urls = {}
+for eid in ('llm-deepseek', 'llm-whyshu'):
+    e = entry(eid)
+    urls[eid] = (e or {}).get('name', '(缺失)')
+
+if action == 'status':
+    print(f"  当前默认 provider: {cur}")
+    print(f"  provider 实例: llm-deepseek → {urls['llm-deepseek']}（官方直连，{provider_of('llm-deepseek')}）")
+    print(f"                llm-whyshu   → {urls['llm-whyshu']}（问述代理，{provider_of('llm-whyshu')}）")
+    print(f"  语义: provider=whyshu ⇒ 扣积分；provider=deepseek-official ⇒ 官方直连不扣积分")
+    print(f"  提示: 两者**并存**，用户也可在设置页按会话/按 agent 选择；改默认值需重启生效")
+    sys.exit(0)
+
+want = {'whyshu': 'whyshu', 'deepseek': 'deepseek-official', 'deepseek-official': 'deepseek-official'}.get(action)
+if not want:
+    print(f"✗ 未知动作：{action}（可用 status|whyshu|deepseek）", file=sys.stderr); sys.exit(2)
+if cur == want:
+    print(f"  · 默认 provider 已是 {want}（无需改动）"); sys.exit(0)
+
+shutil.copy2(p, str(p) + f".bak-select-{datetime.datetime.now():%Y%m%d-%H%M%S}")
+lines = p.read_text(encoding='utf-8').split('\n')
+for i, l in enumerate(lines):
+    if l.strip() == '- id: agent-default-model':
+        for j in range(i, min(i + 8, len(lines))):
+            if lines[j].strip().startswith('provider:'):
+                indent = lines[j][:len(lines[j]) - len(lines[j].lstrip())]
+                lines[j] = f"{indent}provider: {want}"
+                break
+        break
+else:
+    print('✗ 组合里找不到 agent-default-model 条目', file=sys.stderr); sys.exit(2)
+p.write_text('\n'.join(lines), encoding='utf-8')
+yaml.safe_load(p.read_text(encoding='utf-8'))   # 回读校验：YAML 必须仍合法
+print(f"  ✅ 默认 provider: {cur} → {want}（已备份；**重启 dsh 后生效**：bash scripts/dsh-restart.sh）")
+PY

package/engine/scripts/provider-switch.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# ============================================================
+# Argent 计费模式切换
+#   问述积分（whyshu 代理）↔ DeepSeek 官方直连（API Key）
+#
+# 用法:
+#   bash provider-switch.sh whyshu     # 切到问述积分（llm-deepseek 段）
+#   bash provider-switch.sh deepseek   # 切到 DeepSeek 官方直连（删 llm-deepseek 段）
+#   bash provider-switch.sh status     # 查看当前模式
+#
+# 原理: dsh 的 llm-deepseek 段覆盖 deepseek-official adapter 的 baseURL
+#       （settings.yaml 热加载，新请求即时生效，无需重启）
+# ============================================================
+set -euo pipefail
+
+SETTINGS="${SETTINGS:-$HOME/.dsh/settings.yaml}"
+MODE="${1:-}"
+
+# 缺 settings.yaml = 无代理段 = 官方直连（正常状态，不是错误）——2026-09-29 修：
+# 此前 status 会直接 FileNotFoundError 崩掉，让人误以为"配置坏了"。
+if [ "$MODE" = "status" ] && [ ! -f "$SETTINGS" ]; then
+  echo "当前模式：DeepSeek 官方直连（$SETTINGS 不存在 ⇒ 无代理段，不扣积分）"
+  exit 0
+fi
+
+python3 - "$SETTINGS" "$MODE" <<'PY'
+import re
+import sys
+import json
+import os
+import urllib.request
+
+path, mode = sys.argv[1], sys.argv[2]
+# 缺文件＝官方直连（正常状态）：容错读成空串，让 whyshu 分支能把代理段**写出来**、
+# deepseek 分支把代理段清掉。2026-09-29 实测：无条件 open() ⇒ 一旦 settings.yaml 不存在，
+# 连「切回积分模式」都会 FileNotFoundError 崩掉（用户报「积分计费模式使用不了」的直接原因）。
+text = open(path, encoding="utf-8").read() if os.path.exists(path) else ""
+
+# 与 configure-provider.rb 保持一致的代理段（幂等写入）
+# 模型清单**不再写死**（2026-09-22 用户反馈"积分模式下选不到新模型"）：
+# 从前端点的 /models 取"可用且已计价"的清单（服务端已按上游∩费率过滤），取不到才用下面的兜底。
+MODELS_URL = os.environ.get("ARGENT_MODELS_URL", "https://whyshu.com/api/argent/v1/models")
+FALLBACK_MODELS = ["deepseek-flash", "deepseek-v4-pro"]   # 规范名优先（V4.1-Flash）   # 兜底里**不放**上游已下线的 deepseek-chat
+
+DISPLAY = {
+    "deepseek-flash": "DeepSeek V4.1 Flash（问述代理）",
+    "deepseek-v4-flash": "DeepSeek V4 Flash（问述代理，旧名）",
+    "deepseek-v4-pro": "DeepSeek V4 Pro（问述代理）",
+}
+
+
+def read_key() -> str:
+    """取账号 Key：环境变量 → dsh 凭据 refs 段（**只读**结构化解析）→ ~/.dsh/argent/whyshu.env。
+
+    为什么需要（2026-09-22 实测）：代理商 Key 平时在 dsh 的凭据库里、**不在环境变量**里，
+    于是本脚本取清单时被 401 挡回、静默走兜底 —— 清单就永远不会自动跟随上游。
+    注意：只做**读取**，绝不写凭据文件（写必须走 dsh 官方接口，见 argent-core）。
+    """
+    if os.environ.get("WHYSHU_API_KEY"):
+        return os.environ["WHYSHU_API_KEY"]
+    cred = os.path.expanduser(os.environ.get("DSH_HOME", "~/.dsh") + "/.credentials.yaml")
+    try:
+        in_refs, out = False, ""
+        for line in open(cred, encoding="utf-8"):
+            if line.startswith("refs:"):
+                in_refs = True; continue
+            if in_refs and line and not line[0].isspace():
+                break
+            if in_refs and line.strip().startswith("WHYSHU_API_KEY:"):
+                out = line.split(":", 1)[1].strip().strip('"').strip("'")
+                break
+        if out:
+            return out
+    except OSError:
+        pass
+    env_file = os.path.expanduser("~/.dsh/argent/whyshu.env")
+    try:
+        for line in open(env_file, encoding="utf-8"):
+            if line.startswith("WHYSHU_API_KEY="):
+                return line.split("=", 1)[1].strip()
+    except OSError:
+        pass
+    return ""
+
+
+def fetch_models() -> list:
+    """取当前可用且已计价的模型 id（失败则回落 FALLBACK_MODELS，不静默给空清单）。"""
+    key = read_key()
+    try:
+        req = urllib.request.Request(MODELS_URL, headers={"Authorization": f"Bearer {key}"})
+        with urllib.request.urlopen(req, timeout=15) as r:
+            doc = json.loads(r.read().decode("utf-8") or "{}")
+        ids = [m.get("id") for m in (doc.get("data") or [])
+               if m.get("id") and m.get("available", True) and m.get("priced", True)]
+        return ids or FALLBACK_MODELS
+    except Exception as e:                                       # noqa: BLE001
+        print(f"  ⚠️ 取模型清单失败（{e}），用兜底 {FALLBACK_MODELS}", file=sys.stderr)
+        return FALLBACK_MODELS
+
+
+def build_block(models: list) -> str:
+    # ⚠️ contextWindow 与 maxTokens **成对自洽**（2026-10-02）：compaction-basic 的
+    #    resolveCompactSpec 要求 contextWindow - maxTokens - headroomTokens(默认 65536) > 0，
+    #    否则抛 TargetPressureConfigError 并在 agent/pre-step 被静默吞掉 ⇒ **压缩彻底不跑**。
+    #    旧值 131072/131072 正是这种失能形态（余量为 0）；代理窗口 131072 ⇒ 输出上限取 32768。
+    out = ["llm-deepseek:", "  baseURL: https://whyshu.com/api/argent/v1",
+           "  apiKeyEnv: WHYSHU_API_KEY", "  models:"]
+    for mid in models:
+        name = DISPLAY.get(mid, f"{mid}（问述代理）")
+        out += [f"    - id: {mid}", f"      name: {name}",
+                "      contextWindow: 131072", "      maxTokens: 32768"]
+    return "\n".join(out) + "\n"
+
+
+BLOCK = build_block(fetch_models())
+
+TOP_LEVEL = re.compile(r"(?m)^[a-zA-Z_][a-zA-Z0-9_-]*:")
+HAS = "llm-deepseek" in text
+
+
+def remove_block(s):
+    # 删除 llm-deepseek 顶层段（含子行，直到下一个顶层键或文件尾）
+    m = TOP_LEVEL.search(s, s.find("llm-deepseek") + len("llm-deepseek"))
+    head = s[: s.find("llm-deepseek")]
+    tail = s[m.start() :] if m else ""
+    return head.rstrip() + "\n" + tail
+
+
+if mode == "whyshu":
+    if HAS:
+        print("已在问述积分模式（whyshu 代理）")
+    else:
+        open(path, "a", encoding="utf-8").write("\n" + BLOCK)
+        print("已切换到问述积分（whyshu 代理）——新请求即时生效")
+elif mode == "deepseek":
+    if HAS:
+        open(path, "w", encoding="utf-8").write(remove_block(text))
+        print("已切换到 DeepSeek 官方直连（api.deepseek.com + DEEPSEEK_API_KEY）——新请求即时生效")
+    else:
+        print("已在 DeepSeek 官方直连模式")
+elif mode == "status":
+    print("问述积分（whyshu 代理）" if HAS else "DeepSeek 官方直连")
+else:
+    print("用法: provider-switch.sh [whyshu|deepseek|status]", file=sys.stderr)
+    sys.exit(1)
+PY

package/engine/scripts/provider-sync-target.check.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * provider 同步目标 —— **诊断脚本**（2026-09-30）：钉住「模型清单只写 llm-whyshu，官方段不被改写」
+ *
+ * ⚠️ 为何不放在 scripts/tests/（门禁）：本脚本用 node 内置 createServer 做 stub，实测在同一进程里
+ *   installer 的 fetch 打不到该 stub（未定位到根因）；而同场景的 **python stub 版本手工验证通过**：
+ *     · `--sync-models` 退出 0；· stub 模型写入 llm-whyshu；· 官方段逐字保留。
+ *   因此降级为诊断脚本，不占门禁；待定位 stub 差异后再升级为测试。
+ *
+ * 背景：旧安装器把 `/api/argent/v1/models` 的清单写进 `llm-deepseek.models`，而该实例是**官方直连**
+ * （provider id `deepseek-official`）⇒ 等于用问述的模型表污染官方 provider。用户纠正后：
+ *   · `llm-deepseek` = 真·官方（api.deepseek.com / DEEPSEEK_API_KEY）—— **安装器不得改写它**
+ *   · `llm-whyshu`   = 问述代理 —— 模型清单写这里
+ * 本测试用**本地 stub 端点**跑 `install-argent.mjs --sync-models`，断言：
+ *   ① 退出 0；② llm-whyshu.models 被写入 stub 给的模型；③ **官方段逐字保留**（baseURL/模型都不变）。
+ */
+import { execFileSync } from 'node:child_process'
+import { createServer } from 'node:http'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(here, '..', '..')
+let pass = 0
+let fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+const stub = createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify({ data: [{ id: 'stub-model-a' }, { id: 'stub-model-b' }], source: 'stub' }))
+})
+await new Promise((r) => stub.listen(0, '127.0.0.1', r))
+const base = `http://127.0.0.1:${stub.address().port}/api/argent/v1`
+
+const home = mkdtempSync(join(tmpdir(), 'provsync-'))
+writeFileSync(join(home, 'settings.yaml'), [
+  'agent-default-model:', '  provider: deepseek-official', '',
+  'llm-deepseek:', '  baseURL: https://api.deepseek.com', '  apiKeyEnv: DEEPSEEK_API_KEY', '  models:',
+  '    - id: official-keep', '      name: OfficialKeep', '      contextWindow: 1', '      maxTokens: 1', '',
+  'llm-whyshu:', `  baseURL: ${base}`, '  apiKeyEnv: WHYSHU_API_KEY', '  models:',
+  '    - id: old-model', '      name: Old', '      contextWindow: 1', '      maxTokens: 1', '',
+].join('\n'))
+
+let code = 0
+try {
+  execFileSync('node', [join(ROOT, 'install-argent.mjs'), '--dsh-home', home, '--sync-models'], {
+    encoding: 'utf8', env: { ...process.env, ARGENT_SKIP_MODEL_PROBE: '1', WHYSHU_API_KEY: 'stub' }, stdio: 'pipe',
+  })
+} catch (e) { code = e.status ?? 1 }
+
+const after = readFileSync(join(home, 'settings.yaml'), 'utf8')
+const whys = (after.match(/llm-whyshu:[\s\S]*?(?=\n\S|$)/) || [''])[0]
+ok(code === 0, `--sync-models 退出 0（实际 ${code}）`)
+ok(/stub-model-a/.test(whys) && /stub-model-b/.test(whys), 'llm-whyshu.models 写入 stub 给的模型')
+ok(!/old-model/.test(whys), 'llm-whyshu 的旧清单被替换（不是追加）')
+ok(/llm-deepseek:\n  baseURL: https:\/\/api\.deepseek\.com/.test(after) && /official-keep/.test(after),
+  '**官方段 llm-deepseek 逐字保留**（baseURL 与模型未被改写）')
+
+stub.close()
+rmSync(home, { recursive: true, force: true })
+console.log(`\n${fail === 0 ? '✅' : '❌'} provider-sync-target: ${pass} 通过 / ${fail} 失败`)
+process.exit(fail === 0 ? 0 : 1)

package/engine/scripts/python-runtime.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# python-runtime.sh —— 流程引擎的 Python 运行时（持久 venv）运维入口。
+#
+# 为什么单独有它（2026-09-22 重启事故）：
+#   引擎入口（flow-trigger.sh 等）需要一个**持久**的解释器（含 openpyxl/pyyaml/pillow/playwright/selenium）。
+#   历史上默认值指向开发机的 `/tmp/pw-venv`，而 **/tmp 重启即被清空** ⇒ 客户机重启后定时器
+#   "照跑但什么也不做"（exit 0 静默空转，日志/台账都看不出异常）。装机流程现在会建
+#   `<DSH_HOME>/argent/venv`，本脚本是它的检查/修复入口（客户机排障用）。
+#
+# 用法：
+#   bash scripts/python-runtime.sh check     # 体检：路径/版本/五个库（缺谁报谁，exit 非 0）
+#   bash scripts/python-runtime.sh ensure    # 建/修（调安装器的 --venv-only；需要网络装包）
+#   bash scripts/python-runtime.sh path      # 打印解析到的解释器路径（给脚本/CI 用）
+set -uo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# venv 布局**按平台**（P0-③ 2026-10-08）：POSIX 是 `bin/python3`，Windows 是 `Scripts\python.exe`。
+# 此前这里写死 `bin/python3` ⇒ 在 Windows 的 Git Bash 里 check 恒红（"缺少持久 venv"），
+# 而 venv 其实好好地在 `Scripts\` 下。
+# ⚠️ 与 scripts/lib/python-runtime.mjs#venvLayout（安装器侧的唯一真源）同一口径。
+case "$(uname -s 2>/dev/null || echo unknown)" in
+  MINGW*|MSYS*|CYGWIN*) VENV_BIN="${DSH_HOME:-$HOME/.dsh}/argent/venv/Scripts"; VENV_PY="$VENV_BIN/python.exe" ;;
+  *)                    VENV_BIN="${DSH_HOME:-$HOME/.dsh}/argent/venv/bin";     VENV_PY="$VENV_BIN/python3" ;;
+esac
+# P0-1（2026-10-08）：体检项 4 → 5（补 selenium）。理由：官方唯一推荐的驱动档位
+# （ZINIAO_MODE=selenium）此前在 venv 里**没装** ⇒ 选型开关静默撒谎、该档位从未运行过一次。
+# ⚠️ 本清单必须与 install-argent.mjs 的 pythonRuntimePlan().pkgs 和
+#    scripts/lib/python-runtime.mjs 的 venvUsable(pkgs=…) 保持一致（缺一就会"体检红但 ensure 空转"）。
+PKGS=(openpyxl yaml PIL playwright selenium)
+# 交付纪律：本清单变更必须与"客户机 venv 补装 selenium（bash scripts/python-runtime.sh ensure）"
+# 同批落地，否则客户机体检会先变红（4/5）。
+
+cmd_check() {
+  local rc=0
+  if [ ! -x "$VENV_PY" ]; then
+    echo "  ❌ 缺少持久 venv：$VENV_PY"
+    echo "     ↳ 修：bash scripts/python-runtime.sh ensure"
+    return 1
+  fi
+  echo "  ✅ 解释器：${VENV_PY}（$("$VENV_PY" -V 2>&1)）"
+  for m in "${PKGS[@]}"; do
+    if "$VENV_PY" -c "import ${m}" 2>/dev/null; then
+      echo "  ✅ 依赖 ${m}"
+    elif [ "$m" = "selenium" ]; then
+      # selenium 与其它四项不同：缺它**不会**让流程跑不动，而是让官方推荐档位失效
+      # （ZINIAO_MODE=selenium ⇒ 显著告警并回退 Playwright）。文案必须说实话。
+      echo "  ❌ 依赖 selenium 缺失（官方推荐驱动档位不可用：设了 selenium 会显著告警并回退 Playwright）"; rc=1
+    else
+      echo "  ❌ 依赖 ${m} 缺失（浏览器/发票流程会失败）"; rc=1
+    fi
+  done
+  [ "$rc" -eq 0 ] || echo "     ↳ 修：bash scripts/python-runtime.sh ensure"
+  return $rc
+}
+
+cmd_ensure() {
+  if [ ! -f "$REPO/install-argent.mjs" ]; then
+    echo "  ❌ 找不到 install-argent.mjs（本脚本需在 argent-dsh 仓库内运行）" >&2; return 2
+  fi
+  node "$REPO/install-argent.mjs" --venv-only --dsh-home "${DSH_HOME:-$HOME/.dsh}" || return $?
+}
+
+cmd_path() {
+  # 与入口脚本同一套候选（顺序必须一致，否则会出现"检查过了但流程用的是别的解释器"）
+  local c
+  for c in "${ARGENT_PY:-}" "$VENV_PY" "${REPO:-}/.venv/bin/python3" "$(command -v python3 2>/dev/null || true)"; do
+    [ -n "$c" ] && [ -x "$c" ] || continue
+    "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue
+    printf '%s\n' "$c"; return 0
+  done
+  echo "❌ 没有可用解释器（需 openpyxl+yaml）" >&2; return 1
+}
+
+case "${1:-}" in
+  check) cmd_check ;;
+  ensure) cmd_ensure ;;
+  path) cmd_path ;;
+  *) sed -n '2,18p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2 ;;
+esac

package/engine/scripts/query_runner.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""ml-conversation CDP 查询执行器（在 playwright venv 下运行）。
+
+插件进程（hermes/argent 环境）本身没有 playwright，因此本脚本由
+tools.py 通过 subprocess 调用 playwright venv 的 python3 执行，
+import orchestrator 的公共函数（PlaywrightClient / JS_EXTRACT_SHIPMENTS /
+load_config / _discover_cdp_ports / _resolve_store）完成 CDP 查询，
+避免双份维护连接逻辑。
+
+用法:
+    query_runner.py --mode ports
+        仅检测紫鸟进程/CDP 端口/店铺窗口在线状态（无浏览器操作）
+    query_runner.py --mode shipment --shipment-id 74053018 [--store 店名] [--orchestrator PATH]
+        连接紫鸟 CDP → 打开独立新标签 → 查询 inbounds 货物状态（只读）
+    query_runner.py --mode store --store 店名 [--check-login 1] [--orchestrator PATH]
+        检测指定店铺窗口/CDP 端口在线 + 可选登录态探测（只读导航）
+
+输出: stdout 单行 JSON；进度日志走 stderr（与 orchestrator 约定一致）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）。
+# 本脚本既在仓库 `scripts/` 下跑、也在安装克隆 `~/.argent-dsh/scripts/`（plugin scriptsDir）
+# 下跑 —— 两处布局都带 `lib/`（sync-scripts.sh 整目录 rsync）⇒ 相对本文件取 lib 即可。
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  —— 勿在别处复制判据
+
+
+def _default_orchestrator() -> Path:
+    """定位 orchestrator.py（与 tools.py 的候选顺序一致，双副本通用）。"""
+    env = os.environ.get("ML_ORCHESTRATOR_PATH")
+    if env:
+        p = Path(env).expanduser()
+        if p.is_file():
+            return p
+    here = Path(__file__).resolve()
+    # .../plugins/ml-conversation/scripts/query_runner.py → 上溯 4 级到 profile home
+    profile_home = here.parents[3]
+    candidates = [
+        profile_home / "scripts/orchestrator.py",
+        profile_home / "roles/ml-fulfillment/scripts/orchestrator.py",
+        profile_home / "skills/mercadolibre/ml-fulfillment-sop/scripts/fulfillment_orchestrator.py",
+        Path.home() / "Code/argent-ml-seller/scripts/orchestrator.py",
+        Path.home() / "Code/argent-ml/roles/ml-fulfillment/scripts/orchestrator.py",
+        Path.home() / "Code/argent-ml/skills/mercadolibre/ml-fulfillment-sop/scripts/fulfillment_orchestrator.py",
+    ]
+    for c in candidates:
+        if c.is_file():
+            return c
+    return candidates[0]
+
+
+def _load_orchestrator(path: Optional[str] = None):
+    """从文件路径加载 orchestrator 模块（不要求已安装为包）。"""
+    p = Path(path).expanduser() if path else _default_orchestrator()
+    if not p.is_file():
+        raise FileNotFoundError(f"orchestrator.py 不存在: {p}")
+    spec = importlib.util.spec_from_file_location("ml_orchestrator", p)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["ml_orchestrator"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# ────────────────────────────────────────────────
+# ports：只读检测，不碰浏览器
+# ────────────────────────────────────────────────
+
+def _store_port_map(orchestrator) -> dict[str, int]:
+    """店铺名 → CDP 端口。优先 cdp-port-map.json（v0.6.5+ 格式 storeId → {store_name, env_name, cdp_port}，
+    兼容旧格式 店铺名 → 端口），其次 stores.json 的 cdp_port。"""
+    mapping: dict[str, int] = {}
+    port_map_json = Path(resolve_data_dir()['dir']) / "cdp-port-map.json"
+    try:
+        data = json.loads(port_map_json.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            for k, v in data.items():
+                if isinstance(v, dict) and str(v.get("cdp_port", "")).isdigit():
+                    mapping[str(v.get("store_name") or k)] = int(v["cdp_port"])
+                elif isinstance(v, (int, str)) and str(v).isdigit():
+                    mapping[str(k)] = int(v)
+    except Exception:
+        pass
+    try:
+        stores = orchestrator._load_stores()
+        for name, info in stores.items():
+            port = info.get("cdp_port")
+            if str(port).isdigit():
+                mapping.setdefault(str(name), int(port))
+    except Exception:
+        pass
+    return mapping
+
+
+def _detect_ports(orchestrator) -> list[int]:
+    try:
+        return orchestrator._discover_cdp_ports()
+    except Exception:
+        return []
+
+
+def _detect_ziniao_running() -> bool:
+    try:
+        import subprocess
+        # 跨平台紫鸟客户端进程：Mac: ziniao/Ziniao；Win: ziniaob（旧名 ziniaobro 兼容）；
+        # 排除 ziniao-cli 自身（命令行含 "ziniao"）
+        out = subprocess.run(["pgrep", "-f", "ziniao|ziniaob"],
+                             capture_output=True, text=True, timeout=5)
+        for pid in out.stdout.split():
+            try:
+                cmd = subprocess.run(["ps", "-p", pid, "-o", "command="],
+                                     capture_output=True, text=True, timeout=3).stdout
+                if cmd and "ziniao-cli" not in cmd and "pgrep" not in cmd:
+                    return True
+            except Exception:
+                continue
+        return False
+    except Exception:
+        return False
+
+
+async def _run_ports(orchestrator) -> dict[str, Any]:
+    mapping = _store_port_map(orchestrator)
+    ports = _detect_ports(orchestrator)
+    stores = []
+    for name, port in sorted(mapping.items()):
+        stores.append({
+            "store": name,
+            "cdp_port": port,
+            "window_online": port in ports,
+        })
+    _client_running = _detect_ziniao_running()
+    _online = sum(1 for s in stores if s["window_online"])
+    return {
+        "ok": True,
+        # ⑫（2026-09-23 角色交接）：这个键**只表示客户端进程在跑**，不代表店铺窗口可用
+        # （实测 {"ziniao_running": true, …, "stores_online": 1}）⇒ 极易被读成"环境就绪"。
+        # 为兼容既有消费者保留它，但紧跟两个**语义明确**的字段，并附一句口径说明。
+        "ziniao_running": _client_running,
+        "ziniao_client_running": _client_running,
+        "ziniao_running_meaning": "仅指紫鸟**客户端进程**在跑；窗口是否可用看 stores_online",
+        "cdp_ports": sorted(ports),
+        "stores": stores,
+        "stores_total": len(stores),
+        "stores_online": _online,
+    }
+
+
+# ────────────────────────────────────────────────
+# shipment：查询 inbounds 货物状态（只读）
+# ────────────────────────────────────────────────
+
+def _pick_cdp_url(orchestrator, store_name: Optional[str], store_map: dict[str, int],
+                  ports: list[int]) -> str:
+    """选 CDP 端口：指定店铺 → 该店映射端口；否则自动发现第一个可用端口。"""
+    if store_name:
+        port = store_map.get(store_name)
+        if port:
+            return f"http://127.0.0.1:{port}"
+    if ports:
+        return f"http://127.0.0.1:{ports[0]}"
+    cfg = orchestrator.load_config()
+    return cfg.cdp_url
+
+
+async def _run_shipment(orchestrator, shipment_id: str,
+                        store_name: Optional[str]) -> dict[str, Any]:
+    store_map = _store_port_map(orchestrator)
+    ports = _detect_ports(orchestrator)
+    cdp_url = _pick_cdp_url(orchestrator, store_name, store_map, ports)
+
+    cfg = orchestrator.load_config()
+    client = orchestrator.PlaywrightClient(cfg, cdp_url=cdp_url)
+    await client.connect(step=0)
+    try:
+        url = f"{orchestrator.INBOUNDS_URL}?query={shipment_id}"
+        await client.navigate(url, step=0, wait_after=2.0)
+        out = await client.evaluate(orchestrator.JS_EXTRACT_SHIPMENTS, step=0)
+        try:
+            data = json.loads(out)
+        except Exception:
+            data = {"shipments": []}
+        shipments = data.get("shipments", [])
+        # 登录态探测：URL 落到登录域或页面含登录关键词
+        page_url = client.page.url or ""
+        body = ""
+        try:
+            body = await client.page.evaluate(
+                "() => document.body ? document.body.innerText.slice(0, 300) : ''")
+        except Exception:
+            pass
+        login_hint = (
+            "login" in page_url.lower()
+            or "iniciar sesión" in (body or "").lower()
+        )
+        match = next((s for s in shipments if s.get("id") == shipment_id), None)
+        return {
+            "ok": True,
+            "shipment_id": shipment_id,
+            "cdp_url": cdp_url,
+            "store_hint": store_name,
+            "found": match is not None,
+            "status": (match or {}).get("status", ""),
+            "raw": match,
+            "page_url": page_url[:200],
+            "login_hint": login_hint,
+            "results_count": len(shipments),
+        }
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+# ────────────────────────────────────────────────
+# store：店铺窗口在线 + 可选登录态探测（只读导航）
+# ────────────────────────────────────────────────
+
+async def _run_store(orchestrator, store_name: str, check_login: bool) -> dict[str, Any]:
+    store_map = _store_port_map(orchestrator)
+    ports = _detect_ports(orchestrator)
+    port = store_map.get(store_name)
+    online = port in ports if port else False
+
+    result: dict[str, Any] = {
+        "ok": True,
+        "ziniao_running": _detect_ziniao_running(),
+        "store": store_name,
+        "cdp_port": port,
+        "window_online": online,
+    }
+    if not check_login or not online or not port:
+        return result
+
+    cfg = orchestrator.load_config()
+    client = orchestrator.PlaywrightClient(cfg, cdp_url=f"http://127.0.0.1:{port}")
+    await client.connect(step=0)
+    try:
+        await client.navigate(orchestrator.INBOUNDS_URL, step=0, wait_after=1.0)
+        page_url = client.page.url or ""
+        body = ""
+        try:
+            body = await client.page.evaluate(
+                "() => document.body ? document.body.innerText.slice(0, 300) : ''")
+        except Exception:
+            pass
+        result["logged_in"] = not (
+            "login" in page_url.lower()
+            or "iniciar sesión" in (body or "").lower()
+        )
+        result["page_url"] = page_url[:200]
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+    return result
+
+
+async def _main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="ml-conversation CDP 查询执行器")
+    parser.add_argument("--mode", required=True,
+                        choices=["ports", "shipment", "store"])
+    parser.add_argument("--shipment-id", default="")
+    parser.add_argument("--store", default="")
+    parser.add_argument("--check-login", default="0")
+    parser.add_argument("--orchestrator", default="")
+    args = parser.parse_args(argv)
+
+    try:
+        orchestrator = _load_orchestrator(args.orchestrator or None)
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": f"orchestrator 加载失败: {exc}"},
+                         ensure_ascii=False))
+        return 1
+
+    try:
+        if args.mode == "ports":
+            result = await _run_ports(orchestrator)
+        elif args.mode == "shipment":
+            if not args.shipment_id.strip():
+                raise ValueError("shipment-id 必填")
+            result = await _run_shipment(orchestrator, args.shipment_id.strip(),
+                                         args.store.strip() or None)
+        else:
+            if not args.store.strip():
+                raise ValueError("store 必填")
+            result = await _run_store(orchestrator, args.store.strip(),
+                                      args.check_login.strip() in ("1", "true", "yes"))
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": f"{type(exc).__name__}: {exc}"},
+                         ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(_main(sys.argv[1:])))