@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/vertical-lint.mjs

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+/**
+ * vertical-lint —— 业务线门禁（P1，2026-09-29）
+ *
+ * 为什么需要它：注册表拆分后，"完全解耦"不能靠人记规矩 —— 必须由门禁保证：
+ *   ① **命名空间**：flow id / 角色 / 技能 / env / 暂停开关 / 定时器 label / 派发 preset
+ *      一律带业务线前缀（否则两条业务线同机必然撞名）；
+ *   ② **跨线引用为零**：`verticals/A` 不得引用 `verticals/B` 的任何文件、flow、角色、技能；
+ *   ③ **引擎不掺业务**：`scripts/` 与 `plugins/<plugin>/src/` 下不得出现业务词（新引入即失败，
+ *      历史存量用基线文件记账并逐阶段收敛 —— 见 `verticals/_engine-words.baseline.txt`）；
+ *   ④ **manifest 自洽**：必需字段齐、`requires` 有版本区间、声明的角色/技能真实存在。
+ *
+ * 合并/冲突判据**不在这里**（那是 `scripts/flow_registry.py` 的唯一职责）——本脚本
+ * 通过它的 `--json` 拿合并结果，避免"两处各判一套"（历史上 entitlements 三处各判就漂移过）。
+ *
+ * 用法：
+ *   node scripts/vertical-lint.mjs [--root <dir>] [--json] [--update-baseline]
+ * 退出码：0 通过（可有 warning）／1 有 error
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_ROOT = join(HERE, '..')
+const argOf = (name, dflt = null) => {
+  const i = process.argv.indexOf(name)
+  return i > -1 ? process.argv[i + 1] ?? dflt : dflt
+}
+const ROOT = argOf('--root', DEFAULT_ROOT)
+const JSON_OUT = process.argv.includes('--json')
+const UPDATE_BASELINE = process.argv.includes('--update-baseline')
+
+const errors = []
+const warnings = []
+const err = (rule, msg) => errors.push({ rule, msg })
+const warn = (rule, msg) => warnings.push({ rule, msg })
+
+// ── 0. 合并注册表（冲突由加载器判定）──────────────────────────────
+function mergedRegistry() {
+  const out = execFileSync('python3', [join(HERE, 'flow_registry.py'), '--json'], {   // W3 修：--root 只换注册表根，脚本恒在 lint 自身目录（否则夹具根下没有该脚本 ⇒ ENOENT 假红）
+    env: { ...process.env, ARGENT_REGISTRY_ROOT: ROOT },
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  })
+  return JSON.parse(out)
+}
+
+// 已实现的 source kind（P4 端口表，唯一真源：`flow_source.py --list-sources`）——
+// 引擎侧的声明必须与实现对齐，否则业务线会在运行到一半时才发现"这个数据面没人实现"。
+let SOURCE_KINDS = []
+try {
+  const raw = execFileSync('python3', [join(HERE, 'flow_source.py'), '--list-sources'], { encoding: 'utf8' })
+  SOURCE_KINDS = Object.keys(JSON.parse(raw))
+} catch { /* 加载器/源表不可用时跳过这条判据（其它判据照跑） */ }
+
+const verticalsRoot = join(ROOT, 'verticals')
+const listVerticals = () => {
+  if (!existsSync(verticalsRoot)) return []
+  return readdirSync(verticalsRoot)
+    .filter((d) => !d.startsWith('.') && !d.startsWith('_'))
+    .filter((d) => {
+      try { return statSync(join(verticalsRoot, d)).isDirectory() } catch { return false }
+    })
+    .filter((d) => existsSync(join(verticalsRoot, d, 'manifest.json')) || existsSync(join(verticalsRoot, d, 'flows.json')))
+    .sort()
+}
+
+const VIDS = listVerticals()
+let doc
+try {
+  doc = mergedRegistry()
+} catch (e) {
+  err('registry', `注册表合并失败：${(e.stderr || e.message || '').toString().trim().split('\n').slice(-3).join(' ')}`)
+  doc = { flows: {}, capabilities: {}, verticals: {} }
+}
+
+const canonicalFlows = doc.flows || {}
+const capabilities = Object.keys(doc.capabilities || {}).filter((k) => !k.startsWith('_'))
+const NAMESPACE = []
+/** P1-A：声明了 `trigger.schedule.enabled=true` 的流程（试点期约束用；见下方全局判据）。 */
+const SCHEDULE_ENABLED = []
+
+// ── 1. 逐业务线检查 ──────────────────────────────────────────────
+for (const vid of VIDS) {
+  const dir = join(verticalsRoot, vid)
+  const man = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'))
+  const fdoc = JSON.parse(readFileSync(join(dir, 'flows.json'), 'utf8'))
+  const at = (k) => `verticals/${vid}/${k}`
+  // 迁移期豁免清单（roles/skills）：见下方流程循环处的说明
+  const legacyNames = new Set(man.legacyNaming || [])
+  const legacyRoles = legacyNames.has('roles')
+
+  // 1.1 manifest 自洽
+  for (const k of ['version', 'title', 'requires', 'ports', 'capabilities']) {
+    if (!man[k]) err('manifest', `${at('manifest.json')} 缺必需字段 \`${k}\``)
+  }
+  const req = man.requires || {}
+  for (const k of ['argent', 'dsh']) {
+    const v = String(req[k] ?? '')
+    if (!/^[<>=~^0-9][^|]*$/.test(v) || v.trim() === '') {
+      err('manifest', `${at('manifest.json')} requires.${k} 必须是版本区间（如 ">=0.2 <0.3"），当前 ${JSON.stringify(req[k])}`)
+    }
+  }
+  if (!man.verifiedOn || !Object.keys(man.verifiedOn || {}).length) {
+    warn('manifest', `${at('manifest.json')} 缺 verifiedOn（"已在哪些版本验证过"）—— 装机时无法判断该线是否可用于目标版本`)
+  }
+  const KNOWN_PORTS = ['feishu-base', 'http-json', 'sql', 'file', 'manual', 'feishu', 'web', 'wecom', 'feishu-card', 'log', 'env', 'none', 'internal-http', 'portal']
+  for (const [name, impl] of Object.entries(man.ports || {})) {
+    if (name.startsWith('_')) continue   // `_note` 之类的说明键不参与判据（JSON 没有注释）
+    if (!KNOWN_PORTS.includes(String(impl))) {
+      warn('ports', `${at('manifest.json')} ports.${name}=${JSON.stringify(impl)} 不在已知端口实现表内（新增实现时同步更新 lint 的 KNOWN_PORTS）`)
+    }
+  }
+  for (const f of ['billing.json', 'preflight.py']) {
+    if (man[f.replace('.json', '')] && !existsSync(join(dir, f))) {
+      err('manifest', `${at('manifest.json')} 声明了 \`${f}\` 但文件不存在`)
+    }
+  }
+
+  // 1.2 声明的角色/技能必须存在且带前缀
+  for (const role of man.roles || []) {
+    if (!role.startsWith(`argent-${vid}-`)) {
+      if (legacyRoles) {
+        warn('namespace', `${at('manifest.json')} 角色 \`${role}\` 仍是旧名（manifest.legacyNaming 含 roles，P2b 退休）`)
+      } else {
+        err('namespace', `${at('manifest.json')} 角色 \`${role}\` 必须形如 \`argent-${vid}-<role>\``)
+      }
+    }
+    if (!existsSync(join(ROOT, 'presets', role))) {
+      err('manifest', `${at('manifest.json')} 声明的角色目录不存在：presets/${role}/`)
+    }
+  }
+  for (const sk of man.skills || []) {
+    if (!sk.startsWith(`${vid}-`)) {
+      if (legacyNames.has('skills')) {
+        warn('namespace', `${at('manifest.json')} 技能 \`${sk}\` 仍是旧名（manifest.legacyNaming 含 skills，P5 随重装窗口退休）`)
+      } else {
+        err('namespace', `${at('manifest.json')} 技能 \`${sk}\` 必须形如 \`${vid}-<skill>\``)
+      }
+    }
+    if (!existsSync(join(ROOT, 'skills', sk, 'SKILL.md'))) {
+      err('manifest', `${at('manifest.json')} 声明的技能不存在：skills/${sk}/SKILL.md`)
+    }
+  }
+
+  // 1.3 流程条目：命名空间与落位
+  const localFlows = Object.keys(fdoc.flows || {})
+  if (man.flows && man.flows.length && new Set(man.flows).size !== man.flows.length) {
+    err('manifest', `${at('manifest.json')} flows 列表有重复项`)
+  }
+  for (const local of localFlows) {
+    const id = `${vid}.${local}`
+    const flow = canonicalFlows[id]
+    if (!flow) {
+      err('registry', `流程 \`${id}\` 未出现在合并结果里（flows.json 与 manifest 不一致？）`)
+      continue
+    }
+    const role = String(flow.role || '')
+    if (!role.startsWith(`${vid}-`)) {
+      if (legacyRoles) warn('namespace', `${id}: role=\`${role}\` 仍是旧名（manifest.legacyNaming 含 roles，P2b 退休）`)
+      else err('namespace', `${id}: role=\`${role}\` 必须形如 \`${vid}-<role>\``)
+    }
+    // 缺省规则与 flow_config._derive 一致：未声明 dispatch.preset 时取 `argent-<role>`
+    const preset = String(flow.trigger?.dispatch?.preset || (role ? `argent-${role}` : ''))
+    if (!preset.startsWith(`argent-${vid}-`)) {
+      if (legacyRoles) warn('namespace', `${id}: preset=\`${preset}\` 仍是旧名（manifest.legacyNaming 含 roles，P2b 退休）`)
+      else err('namespace', `${id}: trigger.dispatch.preset=\`${preset}\` 必须形如 \`argent-${vid}-<role>\``)
+    }
+    const pause = String(flow.trigger?.pauseSwitch || '')
+    if (!pause.includes(`verticals/${vid}/`)) {
+      err('namespace', `${id}: trigger.pauseSwitch=\`${pause}\` 必须落在 \`verticals/${vid}/\` 命名空间内（两条线同机才不撞）`)
+    }
+    const promptTpl = String(flow.trigger?.promptTemplate || '')
+    if (!promptTpl.startsWith(`verticals/${vid}/`)) {
+      err('namespace', `${id}: trigger.promptTemplate=\`${promptTpl}\` 必须形如 \`verticals/${vid}/prompts/<flow>.md\``)
+    } else if (!existsSync(join(ROOT, promptTpl))) {
+      err('manifest', `${id}: 提示词模板不存在：${promptTpl}`)
+    }
+    const envFile = String(flow.source?.envFile || '')
+    // 只有**声明了** envFile 才校验落位：有的流程凭据由执行器自己加载（如日报读 daily-report.env），
+    // 注册表里没有这一项 —— 那不是违规，是还没把凭据搬到注册表（记为待办）。
+    if (envFile && !envFile.startsWith(`verticals/${vid}/`)) {
+      err('namespace', `${id}: source.envFile=\`${envFile}\` 必须落在 \`verticals/${vid}/env/\` 内`)
+    }
+    if (!envFile) {
+      warn('namespace', `${id}: 未声明 source.envFile（凭据由执行器自行加载？建议搬到 \`verticals/${vid}/env/\` 并在注册表声明）`)
+    }
+    const logf = String(flow.trigger?.log || '')
+    if (logf && !logf.includes(vid)) {
+      err('namespace', `${id}: trigger.log=\`${logf}\` 必须带业务线标识（否则两条线的日志会互相覆盖）`)
+    }
+    // P4：数据面必须在已实现表内（缺省 feishu-base = 历史行为）
+    const kind = String(flow.source?.kind || 'feishu-base')
+    if (SOURCE_KINDS.length && !SOURCE_KINDS.includes(kind)) {
+      err('ports', `${id}: source.kind=\`${kind}\` 未实现（已实现：${SOURCE_KINDS.join(', ')}）—— 新数据面要么先实现，要么别声明`)
+    }
+    if (flow.capability && !capabilities.includes(String(flow.capability))) {
+      err('registry', `${id}: capability=\`${flow.capability}\` 未在注册表 capabilities 中定义`)
+    }
+    // D2（2026-10-03）：「流程 → 技能目录」的**单一真源**是 `flow.skill` —— `argent sop` 只认它，
+    // 不再用 role 拼路径（角色名 ≠ 技能名：ml-invoice-wy ≠ ml-invoice）。缺声明 / 指向未声明的技能
+    // ⇒ 这里就拦住（否则只有运行时 `sop` 才响亮失败，装配期看不出来）。
+    const skill = String(flow.skill || '')
+    if (!skill) {
+      err('manifest', `${id}: 未声明 skill（流程→技能目录的单一真源；\`argent sop\` 缺它即报错）`
+        + `—— 请在 ${at('flows.json')} 该流程里加 "skill": "<技能名>"`)
+    } else {
+      if (!(man.skills || []).includes(skill)) {
+        err('manifest', `${id}: skill=\`${skill}\` 不在 ${at('manifest.json')}#skills 里（技能名必须由 manifest 声明）`)
+      }
+      if (!existsSync(join(ROOT, 'skills', skill, 'SKILL.md'))) {
+        err('manifest', `${id}: 技能不存在：skills/${skill}/SKILL.md`)
+      }
+    }
+    if (flow.integration) {
+      // P2a：适配器契约（`scripts/integration_contract.py` 的 INTEGRATIONS_DIR）尚未端口化，
+      // 因此**两处都认**：业务线内 `verticals/<id>/adapters/<name>/`（目标形态）或
+      // 引擎侧 `scripts/integrations/<name>/`（历史形态，P4 搬迁）。两处都没有才告警。
+      const inVertical = join(ROOT, 'verticals', vid, 'adapters', String(flow.integration))
+      const inEngine = join(ROOT, 'scripts', 'integrations', String(flow.integration))
+      if (!existsSync(inVertical) && !existsSync(inEngine)) {
+        warn('adapters', `${id}: integration=\`${flow.integration}\` 两处都不存在：${relative(ROOT, inVertical)}/ 或 ${relative(ROOT, inEngine)}/`)
+      }
+    }
+    if (String(flow.trigger?.mode) === 'real' && !(flow.guards?.writeFields || []).length) {
+      warn('guards', `${id}: mode=real 但没有声明 guards.writeFields（写路径白名单）—— 确认这是有意的`)
+    }
+    // ── 1.4 宿主排程声明（P1-A，2026-10-12）──────────────────────────────────
+    // 判据与运行期读取点（`scripts/flow_config.py` 的 schedule 段）**同一套**：这里是资产门禁，
+    // 那里是唯一读取点 —— 两处各判一次不是"第二份真源"，而是"声明期拦住 + 运行期不静默"。
+    // 为什么要有：`trigger.schedule` 是**排程器唯一会读**的一段，写错了没有第二个人会喊
+    // （宿主投递失败只写它自己的日志、不重试）⇒ 必须在装配期就拦住。
+    const sch = flow.trigger?.schedule
+    if (sch !== undefined) {
+      const atS = `${id}: trigger.schedule`
+      if (!sch || typeof sch !== 'object' || Array.isArray(sch)) {
+        err('schedule', `${atS} 必须是对象`)
+      } else {
+        // ① 键白名单（`_` 前缀的说明键不参与判据；JSON 没有注释）
+        const ALLOWED = ['enabled', 'kind', 'time', 'timeZone', 'weekdays', 'expression', 'at',
+          'everySecondsFrom', 'taskTitle', 'promptFile', 'onPause']
+        for (const k of Object.keys(sch)) {
+          if (k.startsWith('_') || ALLOWED.includes(k)) continue
+          err('schedule', `${atS} 出现未登记键 \`${k}\`（白名单：${ALLOWED.join(' / ')}；`
+            + '排程段只描述"排程器怎么叫醒"，⛔ 不许放业务规则/字段名/阈值/失败分类/白名单 —— 那属 L0/L1）')
+        }
+        // ② 选择器自洽
+        const KIND = String(sch.kind || '')
+        const KIND_OK = ['every', 'daily', 'weekly', 'cron', 'at']
+        const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?$/
+        if (!KIND_OK.includes(KIND)) err('schedule', `${atS}.kind=${JSON.stringify(sch.kind)} 不在 ${KIND_OK.join('|')} 内`)
+        if (typeof sch.enabled !== 'boolean') err('schedule', `${atS}.enabled 必须是布尔（当前 ${JSON.stringify(sch.enabled)}）`)
+        if (KIND === 'every') {
+          if (String(sch.everySecondsFrom || '') !== 'intervalSec') {
+            err('schedule', `${atS}: kind=every 必须写 "everySecondsFrom": "intervalSec"（周期只有一份真源：trigger.intervalSec）`)
+          }
+          const iv = Number(flow.trigger?.intervalSec)
+          if (!Number.isFinite(iv)) err('schedule', `${atS}: kind=every 但 trigger.intervalSec 缺失 ⇒ 没有周期可用`)
+          else if (iv < 60) err('schedule', `${atS}: trigger.intervalSec=${iv} < 60（宿主 every_seconds 硬下限 60）`)
+        }
+        if (['daily', 'weekly', 'cron'].includes(KIND)) {
+          if (!String(sch.timeZone || '')) {
+            err('schedule', `${atS}: kind=${KIND} 必须显式给 timeZone（IANA，如 Asia/Shanghai）—— 宿主按它算本地钟表时间`)
+          } else {
+            try { new Intl.DateTimeFormat('en-US', { timeZone: String(sch.timeZone) }) }
+            catch { err('schedule', `${atS}.timeZone=${JSON.stringify(sch.timeZone)} 不是合法 IANA 时区`) }
+          }
+        }
+        if (['daily', 'weekly'].includes(KIND) && !TIME_RE.test(String(sch.time || ''))) {
+          err('schedule', `${atS}.time=${JSON.stringify(sch.time)} 不是 \`HH:mm:ss\`（宿主只认本地钟表时间）`)
+        }
+        if (KIND === 'weekly') {
+          const wd = sch.weekdays
+          if (!Array.isArray(wd) || !wd.length || wd.some((d) => !Number.isInteger(d) || d < 1 || d > 7)) {
+            err('schedule', `${atS}: kind=weekly 的 weekdays 必须是 1..7 的非空整数数组（ISO 周一=1）`)
+          }
+        }
+        if (KIND === 'cron') {
+          const ex = String(sch.expression || '')
+          const fields = ex.trim().split(/\s+/).filter(Boolean)
+          if (fields.length !== 5) err('schedule', `${atS}: kind=cron 的 expression 必须是**五字段** Vixie（当前 ${fields.length} 段）`)
+          if (/[LW#]|\b(?:JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|MON|TUE|WED|THU|FRI|SAT|SUN)\b|^@/.test(ex)) {
+            err('schedule', `${atS}: cron 表达式用了宿主**明确拒绝**的方言（L/W/#、月份/星期英文名、@宏）`)
+          }
+        }
+        if (KIND === 'at') {
+          const v = String(sch.at || '')
+          if (!v || !Number.isFinite(Date.parse(v))) err('schedule', `${atS}: kind=at 必须给可解析的绝对时点 \`at\`（带显式时区）`)
+        }
+        // ③ 静态指令（宿主 prompt 创建时固定 ⇒ 必须是"一条 L1 命令"，⛔ 不能带票号占位符）
+        const title = String(sch.taskTitle || '')
+        if (!title.trim()) err('schedule', `${atS} 缺 taskTitle（宿主必填）`)
+        else if (title !== title.trim()) err('schedule', `${atS}.taskTitle 首尾有空白（宿主拒）`)
+        else if (title.length > 120) err('schedule', `${atS}.taskTitle 超长（${title.length} > 120，宿主硬上限）`)
+        const pf = String(sch.promptFile || '')
+        if (!pf) {
+          err('schedule', `${atS} 缺 promptFile（静态轮次指令；⛔ 与 trigger.promptTemplate 是**两份不同的东西**）`)
+        } else {
+          const abs = pf.startsWith('verticals/') ? join(ROOT, pf) : join(dir, pf)
+          if (!existsSync(abs)) err('schedule', `${atS}.promptFile 指向的文件不存在：${relative(ROOT, abs)}`)
+          else {
+            const body = readFileSync(abs, 'utf8')
+            if (/\{\{\s*[A-Za-z_][\w.-]*\s*\}\}/.test(body)) {
+              err('schedule', `${atS}.promptFile 含模板占位符（双花括号包住的**名字**，如票号类）—— `
+                + '宿主在**创建任务时**就把 prompt 固定了，占位符不会被替换 ⇒ 静态指令里 ⛔ 不许出现模板（那是 trigger.promptTemplate 的职责）')
+            }
+          }
+        }
+        const onPause = String(sch.onPause || '')
+        if (!['deactivate', 'prompt-guard'].includes(onPause)) {
+          err('schedule', `${atS}.onPause=${JSON.stringify(sch.onPause)} 不在 deactivate|prompt-guard 内`)
+        }
+        // ④ 试点期约束（P1-A：**只对日报试点**）：全局最多一条 enabled=true
+        if (sch.enabled === true) {
+          SCHEDULE_ENABLED.push({ id, taskTitle: title, promptFile: pf })
+          for (const need of ['kind', 'taskTitle', 'promptFile']) {
+            if (!sch[need]) err('schedule', `${atS}: enabled=true 必须同时给 \`${need}\``)
+          }
+        }
+      }
+    }
+    NAMESPACE.push({ id, vid, pause, preset, role, timerLabel: `com.whyshu.flow-trigger.${vid}.${local}` })
+  }
+
+  if (!existsSync(join(dir, 'tests'))) {
+    warn('scaffold', `${at('')} 缺 tests/ 目录（该线自己的测试与夹具）`)
+  }
+}
+
+// ── 1.5 宿主排程的**全局**判据（P1-A 试点期）────────────────────
+// 为什么是全局而不是逐流程：宿主那侧只有**一张**任务表，`taskTitle` 是"任务 ↔ 流程"的对应键
+// （`scripts/argent-schedule.mjs` 按它匹配）；两条流程同名 = 匹配歧义，两条流程同时启用 =
+// 试点期一次动两条生产流程（本批明确只批一条）。推广到多流程时改这一条（并在设计文档里登记）。
+if (SCHEDULE_ENABLED.length > 1) {
+  err('schedule', `宿主排程试点期只允许**一条**流程启用（enabled=true），当前 ${SCHEDULE_ENABLED.length} 条：`
+    + SCHEDULE_ENABLED.map((s) => s.id).join('、')
+    + '—— 推广（P2/P3 逐流程）时改这条判据 + 在设计文档登记，⛔ 不要顺手放开')
+}
+const seenTitle = new Map()
+for (const s of SCHEDULE_ENABLED) {
+  if (!s.taskTitle) continue
+  if (seenTitle.has(s.taskTitle)) err('schedule', `taskTitle 冲突：\`${s.taskTitle}\` 同时被 ${seenTitle.get(s.taskTitle)} 与 ${s.id} 使用（宿主只有一张任务表，标题是匹配键）`)
+  else seenTitle.set(s.taskTitle, s.id)
+}
+
+// ── 2. 跨业务线撞名（命名空间之外的东西必须唯一）──────────────────
+const collisions = (key) => {
+  const seen = new Map()
+  for (const n of NAMESPACE) {
+    const v = n[key]
+    if (!v) continue
+    if (seen.has(v)) err('collision', `${key} 冲突：\`${v}\` 同时被 ${seen.get(v)} 与 ${n.id} 使用`)
+    else seen.set(v, n.id)
+  }
+}
+collisions('pause')
+collisions('preset')
+collisions('role')
+collisions('timerLabel')
+
+for (const vid of VIDS) {
+  const man = JSON.parse(readFileSync(join(verticalsRoot, vid, 'manifest.json'), 'utf8'))
+  for (const other of VIDS) {
+    if (other === vid) continue
+    const otherMan = JSON.parse(readFileSync(join(verticalsRoot, other, 'manifest.json'), 'utf8'))
+    for (const sk of man.skills || []) {
+      if ((otherMan.skills || []).includes(sk)) err('collision', `技能 \`${sk}\` 同时被 ${vid} 与 ${other} 声明`)
+    }
+    for (const role of man.roles || []) {
+      if ((otherMan.roles || []).includes(role)) err('collision', `角色 \`${role}\` 同时被 ${vid} 与 ${other} 声明`)
+    }
+  }
+}
+
+// ── 3. 跨线引用为零（扫该线目录下的所有文本文件）──────────────────
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.')) continue
+    const p = join(dir, e.name)
+    if (e.isDirectory()) walk(p, out)
+    else if (/\.(mjs|js|py|json|md|sh|yml|yaml|txt)$/.test(e.name)) out.push(p)
+  }
+  return out
+}
+for (const vid of VIDS) {
+  const dir = join(verticalsRoot, vid)
+  const others = VIDS.filter((v) => v !== vid)
+  if (!others.length) continue
+  for (const f of walk(dir)) {
+    const text = readFileSync(f, 'utf8')
+    for (const other of others) {
+      if (text.includes(`verticals/${other}/`)) {
+        err('cross-ref', `${relative(ROOT, f)} 引用了别的业务线 \`${other}\`（跨线引用必须为零）`)
+      }
+      const otherMan = JSON.parse(readFileSync(join(verticalsRoot, other, 'manifest.json'), 'utf8'))
+      for (const token of [...(otherMan.roles || []), ...(otherMan.skills || []), ...(otherMan.flows || [])]) {
+        if (token && text.includes(token)) {
+          err('cross-ref', `${relative(ROOT, f)} 出现别的业务线的标识 \`${token}\`（属于 ${other}）`)
+        }
+      }
+    }
+  }
+}
+
+// ── 4. 引擎不掺业务（基线记账，只拦**新增**）──────────────────────
+const wordsFile = join(verticalsRoot, '_engine-words.json')
+const baselineFile = join(verticalsRoot, '_engine-words.baseline.txt')
+const ENGINE_GLOBS = ['scripts', 'plugins']
+function engineFiles() {
+  const out = []
+  for (const g of ENGINE_GLOBS) {
+    const base = join(ROOT, g)
+    if (!existsSync(base)) continue
+    for (const f of walk(base)) {
+      const rel = relative(ROOT, f)
+      if (rel.startsWith('scripts/tests/')) continue          // 测试可以引用业务夹具
+      if (rel.startsWith(`verticals/`)) continue
+      if (/\.(md|txt)$/.test(rel)) continue                    // 文档/说明不算引擎代码
+      // 生成产物：`capability-packs.lock.json` 记录**随包发布的文件路径**（含各业务线的提示词），
+      // 出现业务线名是正常现象；它由 --stamp 生成、无人手写，纳入扫描只会造成假红。
+      if (rel === 'scripts/capability-packs.lock.json') continue
+      // 生成产物（W3，0.6.0）：**智能体 bundle** 的 `package.json` 由 `scripts/gen-agent-bundles.mjs`
+      // 从 **L0 货架声明**（`agents/catalog.json`）**逐字投影**而来 —— 它必然带业务线词：
+      //   ① agent id（货架上的**商品名**本身就带）；② 包名**必须** == `@whyshu/<目录名>`（门禁 P6）
+      //   ⇒ 目录名里必然带那个词；③ 能力包名 / 凭据槽落点 / 集成清单（同样是 L0 声明的投影）。
+      // 它**零业务逻辑**（纯 bundle：零 JS，只被宿主读 `dsh.bundle`/`dependencies`/`argent.agent`），
+      // 与上面那条 lock 同类（生成产物、无人手写）⇒ 纳入扫描只会造成假红。
+      // ⛔ 判据没有放宽：业务词的**真源面** `agents/catalog.json` 不在扫描面内（`scripts/` + `plugins/` 之外），
+      //   而"货架声明 ⟺ 6 个产物"由 `scripts/tests/agent-bundle-generation.test.mjs` **逐字节**钉住。
+      if (/^plugins\/argent-agent-[^/]+\/package\.json$/.test(rel)) continue
+      out.push(f)
+    }
+  }
+  return out
+}
+if (existsSync(wordsFile)) {
+  const words = JSON.parse(readFileSync(wordsFile, 'utf8')).words || []
+  const counts = new Map()
+  for (const f of engineFiles()) {
+    const rel = relative(ROOT, f)
+    const text = readFileSync(f, 'utf8')
+    for (const w of words) {
+      const n = text.split(w).length - 1
+      if (n > 0) counts.set(`${rel}\t${w}`, n)
+    }
+  }
+  const lines = [...counts.entries()].map(([k, n]) => `${k}\t${n}`).sort()
+  if (UPDATE_BASELINE) {
+    writeFileSync(baselineFile, lines.join('\n') + (lines.length ? '\n' : ''))
+    console.log(`  ✓ 已更新引擎业务词基线：${relative(ROOT, baselineFile)}（${lines.length} 条）`)
+  } else {
+    const base = new Map()
+    if (existsSync(baselineFile)) {
+      for (const line of readFileSync(baselineFile, 'utf8').split('\n')) {
+        if (!line.trim()) continue
+        const [file, w, n] = line.split('\t')
+        base.set(`${file}\t${w}`, Number(n))
+      }
+    }
+    for (const [k, n] of counts) {
+      const b = base.get(k) ?? 0
+      if (n > b) {
+        const [file, w] = k.split('\t')
+        err('engine-words', `引擎文件 ${file} 新出现业务词 \`${w}\`（基线 ${b} → 现在 ${n}）—— 业务实现应落在 verticals/<id>/ 内`)
+      }
+    }
+  }
+}
+
+// ── 5. 输出 ─────────────────────────────────────────────────────
+if (JSON_OUT) {
+  console.log(JSON.stringify({ verticals: VIDS, flows: NAMESPACE.length, errors, warnings }, null, 2))
+} else {
+  console.log(`vertical-lint：业务线 ${VIDS.length} 条（${VIDS.join(', ') || '无'}）、命名空间化流程 ${NAMESPACE.length} 条`)
+  for (const w of warnings) console.log(`  ⚠️  [${w.rule}] ${w.msg}`)
+  for (const e of errors) console.log(`  ❌ [${e.rule}] ${e.msg}`)
+  console.log(`\n结果：${errors.length ? `❌ ${errors.length} 个 error` : '✅ 通过'}（warn ${warnings.length}）`)
+}
+process.exit(errors.length ? 1 : 0)

package/engine/scripts/wenyao-browser.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+set -euo pipefail
+# wenyao-browser.sh — 长驻文鳐门户浏览器（登录态可复用，供人工过一次验证 + 自动化复用）
+#
+# 用法：
+#   bash scripts/wenyao-browser.sh start    # 用独立 profile 启动 Chrome（CDP 9333，窗口常驻）+ 预填账号密码
+#   bash scripts/wenyao-browser.sh status   # CDP 是否在 + 是否已登录 + 页面顶部文案
+#   bash scripts/wenyao-browser.sh entries  # 打印页面入口文本（找《上海文鳐发票模版》下载入口）
+#   bash scripts/wenyao-browser.sh shot     # 截图到 ~/.dsh/argent/wenyao-probe/current.png
+#   bash scripts/wenyao-browser.sh stop     # 关闭这个实例（只杀本 profile 的 Chrome）
+#
+# 为什么长驻：门户登录是**阿里云行为验证码（滑块）**，自动化过不了（实测 2 次失败，且反复试会触发风控）。
+# 做法：人工过一次 → 登录态留在浏览器与 profile（~/.dsh/argent/wenyao-profile）里，可重复使用；
+# 后续自动化用 `connect_over_cdp http://127.0.0.1:9333` **接到同一个浏览器**（不新开），你还能看着它操作。
+# 只读侦察：不导入订单、不导出文件、不改对方任何业务数据。
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DATA="$HOME/.dsh/argent"
+PROFILE="$DATA/wenyao-profile"
+PORT="${WENYAO_CDP_PORT:-9333}"
+CHROME="${WENYAO_CHROME:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
+PROBE="$DATA/wenyao-probe"
+PY="${WENYAO_PY:-$HOME/.dsh/argent/venv/bin/python3}"
+[ -x "$PY" ] || PY="$(command -v python3 || true)"
+URL="$( [ -f "$DATA/wenyao.env" ] && grep -E '^WENYAO_URL=' "$DATA/wenyao.env" | cut -d= -f2- || echo https://my.ffl-tech.com )"
+
+cdp_up() { curl -s --max-time 3 "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; }
+
+case "${1:-start}" in
+  start)
+    if [ ! -x "$CHROME" ]; then echo "[wenyao-browser] 找不到 Chrome：$CHROME" >&2; exit 1; fi
+    if [ ! -f "$DATA/wenyao.env" ]; then
+      echo "[wenyao-browser] 缺凭据 ~/.dsh/argent/wenyao.env（WENYAO_URL/WENYAO_PHONE/WENYAO_PASSWORD，600）" >&2; exit 1
+    fi
+    mkdir -p "$PROFILE" "$PROBE"; chmod 700 "$PROFILE"
+    if cdp_up; then
+      echo "[wenyao-browser] 已有长驻实例在跑（CDP ${PORT}）"
+    else
+      echo "[wenyao-browser] 启动长驻 Chrome（独立 profile + CDP ${PORT}）…"
+      open -na "Google Chrome" --args \
+        --user-data-dir="$PROFILE" --remote-debugging-port="$PORT" \
+        --no-first-run --no-default-browser-check --disable-features=Translate \
+        "$URL" >/dev/null 2>&1 || true
+      for i in $(seq 1 30); do cdp_up && break; sleep 1; done
+      cdp_up || { echo "[wenyao-browser] CDP 未就绪（${PORT}）；Chrome 可能被策略阻止" >&2; exit 1; }
+    fi
+    # 预填账号密码（让你只需滑滑块）
+    "$PY" "$HERE/wenyao_attach.py" --prefill || true
+    echo
+    echo "👉 请在弹出的 Chrome 窗口里：① 把滑块拖到最右边  ② 点「登录」"
+    echo "   过完验证后跑：bash $0 status   （或让我来看）"
+    echo "   窗口会一直开着；登录态存在 ${PROFILE}（可重复使用）"
+    ;;
+  status)
+    if ! cdp_up; then echo "[wenyao-browser] CDP 未就绪（${PORT}）：先跑 bash $0 start" >&2; exit 1; fi
+    "$PY" "$HERE/wenyao_attach.py" --status
+    ;;
+  entries)
+    if ! cdp_up; then echo "[wenyao-browser] CDP 未就绪（${PORT}）：先跑 bash $0 start" >&2; exit 1; fi
+    "$PY" "$HERE/wenyao_attach.py" --status --entries
+    ;;
+  shot)
+    if ! cdp_up; then echo "[wenyao-browser] CDP 未就绪（${PORT}）：先跑 bash $0 start" >&2; exit 1; fi
+    mkdir -p "$PROBE"
+    "$PY" "$HERE/wenyao_attach.py" --shot "$PROBE/current.png"
+    echo "截图：$PROBE/current.png"
+    ;;
+  stop)
+    pkill -f "user-data-dir=$PROFILE" 2>/dev/null && echo "[wenyao-browser] 已停止长驻实例" || echo "[wenyao-browser] 无运行中的实例"
+    ;;
+  *)
+    echo "用法: bash $0 {start|status|entries|shot|stop}" >&2; exit 2;;
+esac