@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/skills/ml-store-daily-report/scripts/generate.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * ml-store-daily-report generate script
+ * Converts extract.js JSON output into a formatted Chinese Markdown daily report.
+ *
+ * Input (single store, backward compatible):
+ *   { "store": "墨西哥站", "orders": {...}, "reputation": {...}, ... }
+ *
+ * Input (multi store, v1.1.0):
+ *   { "stores": [{ "store": "墨西哥站", "orders": {...}, ... }, ...] }
+ *
+ * Usage:
+ *   node generate.js data.json              # Markdown output
+ *   node generate.js data.json --json       # JSON output {markdown, push}
+ *   node generate.js data.json --push       # Push card JSON only
+ *   cat data.json | node generate.js        # Markdown from stdin
+ */
+
+function normalizeInput(data) {
+  if (data.stores && Array.isArray(data.stores) && data.stores.length > 0) {
+    return data.stores;
+  }
+  // Single store — wrap in array for uniform processing
+  return [data];
+}
+
+function generateReport(data) {
+  const stores = normalizeInput(data);
+  const lines = [];
+  const date = stores[0]?.date || new Date().toISOString().slice(0, 10);
+
+  // ---- Header ----
+  if (stores.length === 1) {
+    const s = stores[0];
+    const storeName = s.store && s.store !== '未知站' ? s.store : '墨西哥站';
+    lines.push('# 美客多运营日报');
+    lines.push(`**日期**: ${date} | **店铺**: ${storeName} | **站点**: 墨西哥`);
+  } else {
+    lines.push('# 美客多运营日报（多店铺汇总）');
+    lines.push(`**日期**: ${date} | **店铺数**: ${stores.length}`);
+  }
+  lines.push('');
+
+  // ---- 汇总概览 ----
+  if (stores.length > 1) {
+    lines.push('## 📦 汇总概览');
+    lines.push('| 店铺 | 订单量 | 销售额 | 退货 | 声誉 |');
+    lines.push('|------|--------|--------|------|------|');
+
+    let totalOrders = 0, totalAmount = 0, totalReturns = 0;
+    for (const s of stores) {
+      const count = s.orders?.count ?? 0;
+      const amount = s.orders?.total_amount_mxn ?? 0;
+      const returns = s.after_sales?.pending ?? 0;
+      const repScore = s.reputation?.score || '—';
+      totalOrders += Number(count) || 0;
+      totalAmount += Number(amount) || 0;
+      totalReturns += Number(returns) || 0;
+      lines.push(`| ${s.store || '—'} | ${count || '—'} | ${amount ? '$' + amount.toFixed(2) : '—'} | ${returns || '—'} | ${repScore} |`);
+    }
+    lines.push(`| **合计** | **${totalOrders}** | **$${totalAmount.toFixed(2)}** | **${totalReturns}** | — |`);
+    lines.push('');
+  }
+
+  // ---- 逐店详情 ----
+  for (const s of stores) {
+    const sectionTitle = stores.length > 1
+      ? `## 📊 ${s.store || '未知站'}`
+      : '## 📦 数据概览';
+
+    lines.push(sectionTitle);
+    if (stores.length === 1) {
+      lines.push('| 指标 | 今日 | 环比昨日 |');
+      lines.push('|------|------|----------|');
+    } else {
+      lines.push('| 指标 | 今日 |');
+      lines.push('|------|------|');
+    }
+
+    const orderCount = s.orders?.count ?? '—';
+    const totalAmount = s.orders?.total_amount_mxn != null
+      ? `$${s.orders.total_amount_mxn.toFixed(2)}`
+      : '—';
+    const returns = s.after_sales?.pending ?? 0;
+
+    lines.push(`| 订单量 | ${orderCount} |${stores.length === 1 ? ' — |' : ''}`);
+    lines.push(`| 销售额 | ${totalAmount}${totalAmount === '—' ? '' : ' MXN'} |${stores.length === 1 ? ' — |' : ''}`);
+    lines.push(`| 退货/售后 | ${returns} |${stores.length === 1 ? ' — |' : ''}`);
+    // Show order detail count only for real parsed items (skip metrics synthetic entry)
+    const realItems = (s.orders?.items || []).filter(item => item.sku !== 'METRICS');
+    if (realItems.length > 0) lines.push(`| 订单明细数 | ${realItems.length} |${stores.length === 1 ? ' — |' : ''}`);
+    lines.push('');
+
+    // 发货
+    if (s.shipping) {
+      const sh = s.shipping;
+      lines.push('### 🚚 发货');
+      lines.push(`今日 ${sh.today ?? 0} | 未来 ${sh.upcoming ?? 0} | 运输中 ${sh.in_transit ?? 0}`);
+      lines.push('');
+    }
+
+    // 声誉
+    const rep = s.reputation || {};
+    lines.push('### 🌟 声誉');
+    if (rep.level) {
+      const emoji = rep.level.includes('Gold') ? '🥇' : rep.level.includes('Platinum') ? '🥈' : rep.level.includes('Silver') ? '🥉' : '';
+      lines.push(`**${emoji} ${rep.level}**${rep.score ? `  评分: ${rep.score}` : ''}`);
+    } else if (rep.score) {
+      lines.push(`**评分**: ${rep.score}`);
+    }
+    if (rep.complaints) {
+      const c = rep.complaints;
+      const parts = [];
+      if (c.reclamos_pct != null) parts.push(`Reclamos ${c.reclamos_pct}`);
+      if (c.mediaciones_pct != null) parts.push(`Mediaciones ${c.mediaciones_pct}`);
+      if (c.cancel_pct != null) parts.push(`取消率 ${c.cancel_pct}`);
+      if (c.envio_err_pct != null) parts.push(`错误发货 ${c.envio_err_pct}`);
+      if (parts.length > 0) lines.push(parts.join(' | '));
+    }
+    if (rep.new_questions != null) lines.push(`新买家提问: ${rep.new_questions} 条`);
+    const hasRep = rep.level || rep.score || rep.complaints || rep.new_questions != null;
+    if (!hasRep) lines.push('*暂无声誉数据*');
+    lines.push('');
+
+    // FULL
+    const full = s.full || {};
+    lines.push('### 📦 FULL 库存');
+    if (full.pending_count != null) lines.push(`待处理货件: ${full.pending_count} 件`);
+    if (full.not_apt_total > 0) lines.push(`不适配 FULL: ${full.not_apt_total} 单位`);
+    if (full.shipments && full.shipments.length > 0) {
+      for (const sh of full.shipments) {
+        const emoji = sh.status === 'Vencido' ? '❌' : sh.status === 'En preparación' ? '🔄' : '✅';
+        lines.push(`- ${emoji} #${sh.id || '—'} ${sh.status} | 申报:${sh.declared ?? '?'} 适配:${sh.apt_for_full ?? '?'} | ${sh.appointment || '—'}`);
+      }
+    } else {
+      lines.push('*暂无 FULL 货件数据*');
+    }
+
+    // Alerts
+    const alerts = _collectAlerts(s);
+    if (alerts.length > 0) {
+      lines.push('');
+      lines.push('### ⚠️ 告警');
+      for (const a of alerts) lines.push(`- ${a}`);
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function _collectAlerts(data) {
+  const items = [];
+  const rep = data.reputation || {};
+  const full = data.full || {};
+
+  if (data.alerts && data.alerts.length > 0) {
+    for (const a of data.alerts) {
+      switch (a) {
+        case 'auth_code_missing': items.push('🔴 授权码缺失'); break;
+        case 'no_orders_found': items.push('🟡 无订单数据'); break;
+        case 'pending_after_sales': items.push(`🔴 售后待处理 ${data.after_sales?.pending ?? 0} 单`); break;
+        default: items.push(`🟡 ${a}`);
+      }
+    }
+  }
+  if (rep.complaints) {
+    const c = rep.complaints;
+    if (c.reclamos_pct && parseFloat(c.reclamos_pct) > 5) items.push(`🔴 Reclamos 过高 ${c.reclamos_pct}`);
+    if (c.mediaciones_pct && parseFloat(c.mediaciones_pct) > 3) items.push(`🔴 Mediaciones 过高 ${c.mediaciones_pct}`);
+    if (c.cancel_pct && parseFloat(c.cancel_pct) > 5) items.push(`🟡 取消率过高 ${c.cancel_pct}`);
+  }
+  if (full.shipments) {
+    const expired = full.shipments.filter(s => s.status === 'Vencido');
+    if (expired.length > 0) items.push(`🔴 ${expired.length} 件货件过期`);
+  }
+  return items;
+}
+
+// ================================================================
+// Push data builder
+// ================================================================
+
+function buildPushData(data) {
+  const stores = normalizeInput(data);
+  const multi = stores.length > 1;
+  const date = stores[0]?.date || new Date().toISOString().slice(0, 10);
+
+  // Aggregate metrics
+  let totalOrders = 0, totalAmount = 0, totalReturns = 0;
+  const perStore = [];
+  const allAlerts = [];
+
+  for (const s of stores) {
+    const count = Number(s.orders?.count) || 0;
+    const amount = Number(s.orders?.total_amount_mxn) || 0;
+    const returns = Number(s.after_sales?.pending) || 0;
+    totalOrders += count;
+    totalAmount += amount;
+    totalReturns += returns;
+
+    perStore.push({ store: s.store || '未知', count, amount, returns, score: s.reputation?.score || '' });
+
+    const alerts = _collectAlerts(s);
+    if (alerts.length > 0) allAlerts.push({ store: s.store, alerts });
+  }
+
+  const metrics = [
+    { label: '总订单', value: String(totalOrders), change: '' },
+    { label: '总销售额', value: `$${totalAmount.toFixed(2)} MXN`, change: '' },
+  ];
+  if (totalReturns > 0) metrics.push({ label: '退货/售后', value: String(totalReturns), change: '' });
+
+  // Per-store breakdown as highlight
+  const breakdown = multi
+    ? perStore.map(p => `${p.store}: ${p.count}单 $${p.amount.toFixed(2)}`).join('\n')
+    : '';
+
+  // Alerts
+  let highlight = '';
+  if (allAlerts.length > 0) {
+    const alertSummary = allAlerts.map(a => `⚠️ ${a.store}: ${a.alerts.slice(0, 2).join('、')}`).join('\n');
+    highlight = alertSummary;
+  } else if (multi) {
+    highlight = '今日所有店铺运营数据正常';
+  } else {
+    highlight = '今日运营数据正常';
+  }
+
+  return {
+    card: {
+      template: 'daily_report',
+      data: {
+        title: multi ? `美客多运营日报（${stores.length}店汇总）` : '美客多运营日报',
+        date,
+        store: multi ? `${stores.length} 个店铺` : (stores[0]?.store || '—'),
+        metrics,
+        highlight: breakdown ? `${breakdown}\n\n${highlight}` : highlight,
+      },
+    },
+  };
+}
+
+// ---- CLI Entry ----
+function main() {
+  const args = process.argv.slice(2).filter(a => a !== '--json' && a !== '--push');
+  const mode = process.argv.includes('--push') ? 'push'
+    : process.argv.includes('--json') ? 'json'
+    : 'markdown';
+  const fileArg = args[0];
+
+  function processJSON(input) {
+    try {
+      const data = JSON.parse(input);
+      const markdown = generateReport(data);
+
+      if (mode === 'push') {
+        console.log(JSON.stringify(buildPushData(data), null, 2));
+      } else if (mode === 'json') {
+        console.log(JSON.stringify({ markdown, push: buildPushData(data) }, null, 2));
+      } else {
+        console.log(markdown);
+      }
+    } catch (e) {
+      console.error('Error: Invalid JSON input — ' + e.message);
+      process.exit(1);
+    }
+  }
+
+  if (fileArg) {
+    const fs = require('fs');
+    let content;
+    try {
+      content = fs.readFileSync(fileArg, 'utf8');
+    } catch (e) {
+      console.error(`Error: Cannot read file "${fileArg}" — ${e.message}`);
+      process.exit(1);
+    }
+    processJSON(content);
+  } else {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { input += chunk; });
+    process.stdin.on('end', () => {
+      if (!input.trim()) {
+        console.error('Error: No input received.');
+        process.exit(1);
+      }
+      processJSON(input);
+    });
+  }
+}
+
+if (require.main === module) {
+  main();
+} else {
+  module.exports = { generateReport, buildPushData, normalizeInput };
+}

package/engine/skills/pet-dev/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pet-dev
+description: 云宠乐园开发者角色技能：问述服务器部署（whyshu-deploy）与 whyshu pet 开发知识。接 whyshu-pm 任务，完成后飞书群 @ 汇报。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: pet-dev
+    tags: [pet, whyshu, deploy]
+---
+
+# 云宠乐园开发者（pet-dev）
+
+## 角色定位
+
+云宠乐园（whyshu pet）产品开发者，负责需求实现、缺陷修复、代码评审与发布。
+
+## 核心知识入口
+
+- **问述服务器部署**：使用 `whyshu-deploy` 技能（问述科技 whyshu 项目部署专用）完成
+  whyshu-svr（Fastify 后端）与 whyshu-web（Next.js 前端）的构建、部署与验证。
+- **pet 开发知识**：以 `/Users/chester/Code/whyshu` 仓库为准——
+  - `whyshu/docs/`：产品文档与策划案
+  - `whyshu-svr/`：后端服务（路由/服务/数据层）
+  - `whyshu-web/`：前端（app 路由 / argent 页面等）
+- 部署目标服务器：**问述科技**腾讯云 `81.69.222.211`（域名 `whyshu.com`，私钥 `~/.ssh/whyshu.pem`）；
+  **IP / 私钥 / 部署目录以 `whyshu-deploy` 技能为唯一判据**（本行只作定位，变更以该技能为准）。
+  ⛔ LKTOP（力库拓，**另一腾讯云账号**）的服务器 / 部署目录 / 私钥与本角色无关，**一律不得使用**——
+  本技能此前曾误写 LKTOP 的服务器 IP，是 2026-10-04 修掉的一处**跨业务事实错配**
+  （据 `docs/Argent-角色合并与收敛-操作方案-2026-10-04.md` §2.6）。
+
+## 协作流
+
+1. whyshu-pm 在飞书群 @ 开发者分配任务并附验收标准（旧看板已退场；新任务机制上线前以此为准）；
+2. 在飞书群/会话中确认需求与验收标准；
+3. 完成后在飞书群 @whyshu-pm 汇报（改动摘要 + 验证结果）。
+
+## 红线
+
+- 部署/发布前核对目标环境与回滚预案；
+- 涉及生产数据/凭据的操作先与用户确认。

package/engine/skills/whyshu-pm/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: whyshu-pm
+description: 问述科技PM角色技能：策划案需求掌握与任务分发（飞书群 @ + 会话），验收闭环。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: whyshu-pm
+    tags: [pm, planning, task]
+---
+
+# 问述科技PM（whyshu-pm）
+
+## 角色定位
+
+问述科技产品经理：掌握策划案需求，拆解并分发任务给开发者，验收闭环。
+
+## 核心知识入口
+
+- **策划案需求**：`/Users/chester/Code/whyshu/docs/products/`（如
+  `argent-edition-multi-instance-plan.md`、`argent-service-monetization.md` 等）
+- **任务分发**：lark-task（飞书任务）/ lark-doc（需求文档）/ lark-im（群通知）
+
+## 协作流
+
+1. 需求拆解 → 在飞书群 @ 开发者派单（旧看板已退场；新任务机制上线前以此为准）（必须含：标题、描述、验收标准、优先级、截止时间）；
+2. 分配给云宠乐园开发者（pet-dev）/ Argent开发者（argent-dev）；
+3. 分配完成后在飞书群 @ 对应开发者 Bot 通知（标题/链接/验收标准）；
+4. 开发者完成 @ 汇报 → 查看改动与验证 → 在飞书群/会话中确认验收或打回并说明原因；
+5. 用户会在群中直接指正，及时响应。
+
+## 约定
+
+- 任务信息在会话与飞书群保持同步；派单信息完整，避免开发者猜测。

package/engine/skills/whyshu-web-dev/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: whyshu-web-dev
+description: 问述官网开发者角色技能：whyshu.com 官网（whyshu-web Next.js 项目）开发与部署（whyshu-deploy）。接 whyshu-pm 任务，完成后飞书群 @ 汇报。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: whyshu-web-dev
+    tags: [whyshu-web, website, frontend, deploy]
+---
+
+# 问述官网开发者（whyshu-web-dev）
+
+## 角色定位
+
+whyshu.com 官网（whyshu-web 项目）开发者，负责官网需求实现、页面开发、缺陷修复、构建部署与线上验证。
+
+## 核心知识入口
+
+- **官网代码仓库**：`/Users/chester/Code/whyshu-web`（Next.js 16 静态导出项目，
+  `output: "export"`，构建产物在 `out/`；含 nginx/ 配置与 whyshu.com 站点结构）
+- **部署技能**：使用 `whyshu-deploy` 技能（问述科技 whyshu 项目部署专用）完成
+  whyshu-web 的构建、部署与验证——服务器腾讯云 `81.69.222.211`（域名 `whyshu.com`），
+  前端部署路径 `/var/www/whyshu-web/`，rsync 部署**禁止 `--delete`**（保留旧 chunk 防缓存白屏）。
+- **需求文档**：`/Users/chester/Code/whyshu/docs/`（产品文档与策划案，如 `docs/products/` 下策划案）
+- **相关仓库**：`/Users/chester/Code/whyshu`（产品文档/资产）、`/Users/chester/Code/whyshu-svr`（后端 API，
+  官网页面涉及接口时参考 `whyshu-svr` 的 API_CONTRACT.md）
+- **腾讯云 API 凭据（2026-09-10 起统一用子账号，唯一入口）**：
+  - 凭据文件 `~/.tccli/whyshu-sub.credential`（600 权限，子账号 `svc-argent-ops`；主账号 UIN 100000884591）
+  - 调用工具 `~/Code/whyshu-svr/scripts/tc-api.py`（TC3-HMAC-SHA256 签名，仅标准库，不回显密钥）：
+    `python3 scripts/tc-api.py --profile whyshu-sub --service ssl --action DescribeCertificates --region ap-shanghai --params '{"Limit":50}'`
+  - 覆盖范围：SSL 证书（`ssl:*`）、轻量实例 `lhins-3vjhv134`（上海 81.69.222.211，快照/防火墙/重启；`Describe*` 全量）、whyshu.com 解析（DNSPod）
+  - **Whyshu 旧凭据已退役**：仅 `~/.tccli/whyshu.credential`（Whyshu 旧 OAuth 临时凭据）已移至 `~/.tccli/_deprecated-20260910/` → 对 Whyshu 不要再 `tccli auth login`、不要复用该 profile
+  - ⚠️ **范围边界（勿动）**：`~/.tccli/default.credential`、`~/.tccli/likituo.credential` **不属于 Whyshu**（LKTOP/力库拓账号，default 被 LKTOP 侧流程引用）→ 不得归档、覆盖、删除或改写
+  - 完整说明与红线：`whyshu-svr/docs/tencent-cloud-subaccount-guide.md`
+
+## 协作流
+
+1. whyshu-pm 在飞书群 @ 开发者分配任务并附验收标准（旧看板已退场；新任务机制上线前以此为准）；
+2. 在飞书群/会话中确认需求与验收标准后再动手；
+3. 完成后在飞书群 @whyshu-pm 汇报（改动摘要 + 验证结果）。
+
+## 红线
+
+- 部署/发布前核对目标环境与回滚预案；
+- 生产域名 `whyshu.com` 下 rsync **禁用 `--delete`**（IP 预览阶段可清理）；
+- 涉及生产数据/凭据/服务器配置的操作先与用户确认；
+- **腾讯云操作只用子账号 `whyshu-sub`**（见上「腾讯云 API 凭据」）：不新建/不复用其他腾讯云密钥，不购买付费资源（证书/套餐/带宽），不执行重装系统、重置密码、删除实例、变更套餐；**不触碰 LKTOP 资源**（LKTOP 属另一腾讯云账号 APPID 1331053332）。SSH 部署用的 `~/.ssh/whyshu.pem` 是服务器密钥，与腾讯云 CAM 凭据无关，继续使用；
+- 代码改动在开发仓库（`/Users/chester/Code/whyshu-web`）修改并 git commit + push 提交。

package/engine/version.mjs

@@ -0,0 +1 @@
+export const VERSION = "0.6.1"

package/engine/verticals/README.md

@@ -0,0 +1,103 @@
+# 业务线（vertical）契约
+
+> Argent 0.2 起，**底座与业务线分离**：底座（引擎/角色运行时/装机器/门禁/商业机制）业务中立，
+> 一条业务线 = 一个可独立开发、安装、授权、迭代、回滚的单元。
+> 本文件是**业务线作者**（含将来的第三方）的唯一入口；引擎侧规则见
+> `docs/Argent-0.2-平台与业务线架构-评审稿-2026-09-29.md`。
+
+## 一条业务线长什么样
+
+```
+verticals/<id>/
+  manifest.json      元数据：版本、依赖区间、端口、能力、角色、技能、流程清单
+  flows.json         流程声明（局部 id；合并后规范 id = <id>.<local>）
+  prompts/<flow>.md  派发提示词（引擎按轮次投给角色）
+  roles/             角色 preset 源 → 安装到 `presets/argent-<id>-<role>/`
+  skills/            技能源 → 安装到 `skills/<id>-<skill>/`
+  adapters/<system>/ 外部系统适配器（人工门、错误词表、可执行计划）
+  billing.json       计费单位（只算成功 / 一票一结 / 证据可核）
+  preflight.py       本线验收检查段（由 customer-preflight 汇总）
+  tests/             本线测试与夹具（run-all-tests.sh 自动收集）
+  env/               本线环境变量（600；**只在本线可见**）
+```
+
+## 三条硬规矩（`vertical-lint.mjs` 会拦）
+
+1. **命名空间**：所有对外可见的名字都带业务线前缀 —— 两条线装在同一台机器上不允许撞名。
+
+   | 对象 | 规则 | 例（`id=customer-order`） |
+   |---|---|---|
+   | flow id | `<id>.<local>` | `customer-order.intake` |
+   | 角色（preset） | `argent-<id>-<role>` | `argent-customer-order-clerk` |
+   | 技能 | `<id>-<skill>` | `customer-order-intake` |
+   | 暂停开关 | `verticals/<id>/PAUSE.<flow>` | `verticals/customer-order/PAUSE.intake` |
+   | 定时器 label | `com.whyshu.flow-trigger.<id>.<flow>` | 自动派生 |
+   | env 文件 | `verticals/<id>/env/*.env` | `verticals/customer-order/env/prod.env` |
+   | 提示词 | `verticals/<id>/prompts/*.md` | — |
+   | 能力包 id | `<id>.<unit>` | `customer-order.intake` |
+
+2. **跨线引用为零**：`verticals/A` 不得引用 `verticals/B` 的路径、flow、角色、技能。
+   两条线需要共享的东西，**上提到引擎或端口**，不要在业务线之间拉手。
+
+3. **引擎不掺业务**：`scripts/` 与 `plugins/<plugin>/src/` 不得出现业务词（美客多/文鳐/紫鸟/…）。
+   历史存量记在 `_engine-words.baseline.txt`，门禁只拦**新增**；搬迁完成后基线应清零。
+
+## 冲突判据在加载器，不在 lint
+
+`scripts/flow_registry.py` 负责合并 **base（`scripts/flow-requirements.json`）+ 各业务线**，并保证：
+同名 flow / 能力 / 计费单位 / 失败类 / 别名 **一律 fail（不静默覆盖）**；`manifest.id`、
+`flows.json#vertical` 与目录名不一致也 fail（防复制粘贴串线）。
+
+```bash
+python3 scripts/flow_registry.py --check     # 合并与冲突
+python3 scripts/flow_registry.py --list      # 规范 flow id
+python3 scripts/flow_registry.py --flow intake   # 别名 → 规范 id
+node scripts/vertical-lint.mjs               # 业务线门禁
+```
+
+回退开关：`ARGENT_REGISTRY_MODE=legacy`（只读 base，不扫业务线）；显式 `--registry <file>` 亦为 legacy 单文件行为。
+
+## 端口（该线用到哪些底座能力）
+
+在 `manifest.json#ports` 声明；新增实现时同步更新 `vertical-lint.mjs` 的 `KNOWN_PORTS`。
+
+| 端口 | 职责 | 现有实现 |
+|---|---|---|
+| `source` | 任务队列/数据源 | `feishu-base`（唯一实现；`http-json`/`sql`/`file`/`manual` 待做，见 P4） |
+| `transport` | 人机通道（收指令、唤醒） | `feishu`（`gateway-core` 拆分后可有 `web`/`wecom`） |
+| `notify` | 出站通知/卡片 | `feishu-card`、`log` |
+| `actor` | 外部系统动作 | `none`、`internal-http`；货代类见 `scripts/integrations/`（待泛化） |
+| `identity` | 凭据/身份 | `env`（`verticals/<id>/env/*.env`） |
+
+## 开一条新线
+
+```bash
+node scripts/vertical-init.mjs --id customer-order --title "客单系统" \
+     --flow intake --role clerk --skill intake
+```
+
+生成物是**安全态**（`wake=off`、`mode=shadow`），按 `verticals/<id>/README.md` 的待办清单逐项填。
+上线顺序固定：**只读跑通 → `mode=real` → `wake=session`**。
+
+## 门禁（每条线都要过）
+
+```bash
+node scripts/vertical-lint.mjs          # 本文件的三条硬规矩 + manifest 自洽
+python3 scripts/flow_registry.py --check
+node scripts/tests/run-all-tests.sh     # 平台回归 + 本线测试（tests/ 自动收集）
+node scripts/gen-preset-rows.mjs        # 改了角色后必跑（0.1.7 行式 preset）
+node scripts/validate-preset-schema.mjs --runtime && node scripts/plugin-bootcheck.mjs
+```
+
+## 安装与授权
+
+- 业务线是**安装边界**：`install-argent.mjs --add-capability <id>` 只落本线声明的文件，
+  别的线的文件不会上机器；`--rollback` 按线回退上一版。
+- 授权：`manifest.capabilities[].minPlan` + 注册表 `entitlements`（档位矩阵是唯一出处）。
+- 装机前校验 `manifest.requires.{argent,dsh}` 与 `verifiedOn`（"已在哪些版本实测过"）——
+  不允许把没验过的线装到目标机器上。
+
+## 与 profile 的关系
+
+**能力包能分开的，用包分；包分不开的（专属插件/专属通道/不同 dsh 版本/独立 UI），
+才用 dsh profile 分**（`dsh web --profile <v> --port <n>`）。默认形态是"业务线包 + 共用 base profile"。