@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/lib/notify/dedup.mjs

@@ -0,0 +1,101 @@
+/**
+ * 通知**幂等**与审计（判断⑩；J10 的"通知不重发"落点）—— P2，2026-10-03。
+ *
+ * ## 判据从哪来（不是本文件新立的）
+ * | 事实 | 唯一权威 |
+ * |---|---|
+ * | 通知幂等 | `core/contracts/argent.contracts.json#judgments.J10-sideeffect-boundary`（"同一事实不重发"） |
+ * | 存储位置的链 | `core/lib/argent-datadir.mjs#resolveDataDir`（**唯一判据**；本文件不复制那条链） |
+ * | 语义先例 | `scripts/daily-report.mjs` 的 `.pushed-<date>-<storeKey>` 标记（"推送过就不再推"） |
+ *
+ * ## 判据（可判）
+ *   · **键**：显式 `--idempotency-key` 优先；未给则用**内容摘要**（`channel|target|kind|summary|text`
+ *     的 sha256 前 16 位）当键 ⇒ "同一事实"天然同键。两个来源都在回显里如实标注
+ *     （`idempotencyKeySource: explicit|derived`）—— 客户不会莫名其妙收到"被跳过"。
+ *   · **标记落盘**：`$ARGENT_DATA_DIR/notify-outbox/.sent-<key16>.json`（0600），内容 = 那次投递的
+ *     `{key, at, channel, target, kind, summary, status, bytes}` —— 既是去重证据，也是投递回执。
+ *   · **审计**：`$ARGENT_DATA_DIR/notify-outbox/audit.jsonl`（每**真发**一次一行；dry-run 一行都不落）。
+ *   · **只有投递成功才落标记** ⇒ 失败可以原样重试（不会因为"试过一次"而被永久跳过）。
+ *   · **判据 = 跑两次 dry-run 后数据目录逐字节不变**（A3 的 `judge`；由
+ *     `scripts/tests/notify-verb.test.mjs` 断言）。
+ *
+ * ⛔ 本文件不判断"这条通知该不该发"（那是业务判断，归 L1 的调用方）；
+ *   它只回答"这一份**已经决定要发**的意图，是否已经发过"。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+
+/** 数据目录下的通知收件箱（标记 + 审计同处一处，便于"这个目录能删"一句话解释）。 */
+export const OUTBOX_DIRNAME = 'notify-outbox'
+/** 投递审计文件名（与 `invoice-writeback/audit.jsonl`、`license-gate.jsonl` 同为审计 JSONL）。 */
+export const AUDIT_NAME = 'audit.jsonl'
+
+/** 数据目录内的收件箱路径。 */
+export const outboxDir = (dataDir) => join(String(dataDir), OUTBOX_DIRNAME)
+
+/** 投递审计文件路径。 */
+export const auditPath = (dataDir) => join(outboxDir(dataDir), AUDIT_NAME)
+
+/** 内容 → 幂等键（未显式给键时的**确定性**来源：同样的事实 ⇒ 同样的键）。 */
+export function deriveIdempotencyKey(intent = {}) {
+  const parts = [intent.channel, intent.target, intent.kind, intent.summary, intent.text].map((v) => String(v == null ? '' : v))
+  return createHash('sha256').update(parts.join('\u0000')).digest('hex').slice(0, 16)
+}
+
+/**
+ * 解析幂等键。
+ * @returns {{key:string, source:'explicit'|'derived'}}
+ */
+export function resolveIdempotencyKey(intent = {}, explicit = null) {
+  const raw = explicit == null ? '' : String(explicit).trim()
+  if (raw) return { key: raw, source: 'explicit' }
+  return { key: deriveIdempotencyKey(intent), source: 'derived' }
+}
+
+/** 去重标记路径（键取 sha256 前 16 位 ⇒ 文件名恒定长度、不含用户输入）。 */
+export function dedupMarkerPath(dataDir, key) {
+  const h = createHash('sha256').update(String(key)).digest('hex').slice(0, 16)
+  return join(outboxDir(dataDir), `.sent-${h}.json`)
+}
+
+/** 读标记（不存在/坏文件 ⇒ null，**不抛**：读不到就是"没发过"，这是安全方向）。 */
+export function readDedupMarker(dataDir, key) {
+  const p = dedupMarkerPath(dataDir, key)
+  if (!existsSync(p)) return null
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return { raw: true, path: p } }
+}
+
+/**
+ * 落标记（**只有投递成功才调用**）。目录不可写 ⇒ 抛出，由调用方转成 `internal_error`（fail-closed）。
+ */
+export function writeDedupMarker(dataDir, key, record = {}) {
+  const dir = outboxDir(dataDir)
+  mkdirSync(dir, { recursive: true })
+  const p = dedupMarkerPath(dataDir, key)
+  writeFileSync(p, `${JSON.stringify({ ...record, key, at: new Date().toISOString() })}\n`, { mode: 0o600 })
+  return p
+}
+
+/** 追一行审计（每次**真发**一行；dry-run 不调用它）。 */
+export function appendNotifyAudit(dataDir, record = {}) {
+  const dir = outboxDir(dataDir)
+  mkdirSync(dir, { recursive: true })
+  const line = JSON.stringify({ at: new Date().toISOString(), ...record })
+  appendFileSync(auditPath(dataDir), `${line}\n`, { mode: 0o600 })
+  return auditPath(dataDir)
+}
+
+/** 只读快照（dry-run 用：回答"这一份**若真发**会不会被跳过"，且不落任何文件）。 */
+export function inspectDedup(dataDir, key) {
+  const marker = readDedupMarker(dataDir, key)
+  return {
+    applied: true,
+    key,
+    marker: dedupMarkerPath(dataDir, key),
+    exists: marker !== null,
+    sentAt: marker && marker.at ? marker.at : null,
+    status: marker && marker.status != null ? marker.status : null,
+    decision: marker !== null ? 'skip' : 'send',
+  }
+}

package/engine/core/lib/notify/feishu.mjs

@@ -0,0 +1,38 @@
+/**
+ * `feishu` 通道 —— **预留位**（P2 第二批；本批不实现）。
+ *
+ * 为什么现在只放一个空壳：端口契约（`core/lib/notify/index.mjs` 头部）必须先定下来，
+ * 后来者才知道"新增一条通道要导出什么"。**选了但没实现 ⇒ 明确报缺声明（exit 2）**，
+ * 绝不放行成"看起来发了"（那正是 §2.2④ 那类恒 `ok:true` 的假绿）。
+ *
+ * 落地时的判据（先写在这里，免得实现时又自创一套）：
+ *   · 投递实现**照抄** `scripts/feishu-card.mjs`（它已默认 dry-run、`--send` 才发）——
+ *     ⛔ 不要把它的 `--send` 语义搬进通道：dry-run 由 verb 层决定"根本不调 send"（一处判据）。
+ *   · 目标 = 群 webhook 或 `chat_id`（身份/profile 走既有 `LARK_PROFILE` 链，不新开一套凭据）。
+ *   · 错误映射：未登录/缺权限 ⇒ `needs_human`（要人授权）；网络/半开连接 ⇒ `retryable`
+ *     （唯一权威 = `scripts/flow-requirements.json#failureClasses`；本文件只做**翻译**）。
+ */
+export const CHANNEL = 'feishu'
+export const IMPLEMENTED = false
+export const NOTE = '飞书卡片投递（P2 第二批）；本批只落端口位，实现在 scripts/feishu-card.mjs 之上收口'
+export const TARGET = {
+  required: true,
+  label: '--target',
+  schemes: ['http:', 'https:'],
+  note: '群 webhook / 群 chat_id（待实现）',
+}
+
+export function validateTarget(target) {
+  const raw = String(target == null ? '' : target).trim()
+  if (!raw) return { ok: false, reason: 'target_required', error: 'feishu 通道缺少目标（群 webhook 或 chat_id）' }
+  return { ok: true, target: raw }
+}
+
+/** 预留位：**永不**返回成功（否则调用方会以为真发了）。 */
+export function send() {
+  return {
+    ok: false,
+    reason: 'channel_not_implemented',
+    error: 'feishu 通道尚未实现（预留位）⇒ 本批请用 --channel webhook；实现落点见本文件头注释',
+  }
+}

package/engine/core/lib/notify/index.mjs

@@ -0,0 +1,95 @@
+/**
+ * 通知**端口**（P2，2026-10-03）—— 通道注册表 + 投递意图的路由。
+ *
+ * ## 为什么有它（缺口②）
+ * 实施方案 §2.2②：`notify` 通道今天**一个都没有命令入口**；对外发声散在角色提示词与
+ * `scripts/daily-report.mjs` 里。本目录把"投递"变成**可替换件**：每个通道一个文件、
+ * 导出同一个契约，新增通道 = 新增一个文件（照 `scripts/flow_sources/` 的端口形态）。
+ *
+ * ## 分工（判据不许下沉，§3.5②/P2①）
+ * | 层 | 做什么 | 在哪 |
+ * |---|---|---|
+ * | **判断（L1）** | 通道选择、**幂等键与去重**、dry-run、审计 —— 产出"投递意图" | `core/lib/notify/dedup.mjs`、`core/lib/notify/verb.mjs` |
+ * | **投递（端口实现）** | 把已决定要发的意图送到目标 | 本文件登记的通道模块（`webhook.mjs` / `feishu.mjs` / `wecom.mjs`） |
+ *
+ * ⛔ **通道实现里不得出现"该不该发"**：不读业务表、不看开关、不做重试策略、不自己判 dry-run
+ * （dry-run 由 verb 层决定"根本不调 send"）。通道只回答一件事：**这一份意图，送到了没有**。
+ *
+ * ## 通道契约（新增实现照抄，别自创）
+ * ```js
+ * export const CHANNEL = 'webhook'            // 通道 id（与 --channel 的取值逐字一致）
+ * export const IMPLEMENTED = true             // false = 预留位（选了 ⇒ usage/缺声明，不是静默成功）
+ * export const TARGET = {                     // 目标形态（verb 层据此做**用法**校验，不做业务判断）
+ *   required: true, label: '--url', schemes: ['http:', 'https:'],
+ *   note: '通用 HTTP POST',
+ * }
+ * export function validateTarget(target)      // → {ok:true, target} | {ok:false, reason, error}
+ * export function send(intent, opts)          // → {ok:true, status, ...} | {ok:false, reason, error}
+ * ```
+ *
+ * ## 层归属说明（免得被物理路径骗，§P2① 括号那段的同一口径）
+ * 通道实现物理落在 `core/lib/` 只表示它是**宿主无关的投递实现**（换宿主不用改内核），
+ * 不表示"投递进了判据层"。实施方案 §P2① 建议落在 `scripts/notify/`；本批落在 `core/lib/notify/`
+ * 的理由：`core/lib/*.mjs` 是 CLI/MCP **共用**的内核模块（MCP 侧要复用同一个端口），
+ * 而 `scripts/notify/` 需要额外的分发/同步面。**判据与投递的分工不因路径改变**（上表仍是判据）。
+ */
+import * as webhook from './webhook.mjs'
+import * as feishu from './feishu.mjs'
+import * as wecom from './wecom.mjs'
+
+/** 通道模块表（id → 模块）。**新增通道只改这一行**（不改分发逻辑）。 */
+export const CHANNEL_MODULES = { webhook, feishu, wecom }
+
+/** 已登记的通道 id（顺序即 --help 的展示顺序）。 */
+export const CHANNEL_IDS = Object.keys(CHANNEL_MODULES)
+
+/** 通道清单（只读；给 `--help`/画像/宿主读，不复制任何判据）。 */
+export function listChannels() {
+  return CHANNEL_IDS.map((id) => {
+    const m = CHANNEL_MODULES[id]
+    return {
+      channel: id,
+      implemented: m.IMPLEMENTED === true,
+      targetRequired: Boolean(m.TARGET && m.TARGET.required),
+      targetLabel: (m.TARGET && m.TARGET.label) || null,
+      schemes: (m.TARGET && m.TARGET.schemes) || [],
+      note: (m.TARGET && m.TARGET.note) || '',
+    }
+  })
+}
+
+/**
+ * 解析通道。
+ * @returns {{ok:true, module:object} | {ok:false, reason:'unknown_channel'|'channel_not_implemented', error:string}}
+ */
+export function resolveChannel(id) {
+  const key = String(id || '')
+  const m = CHANNEL_MODULES[key]
+  if (!m) {
+    return { ok: false, reason: 'unknown_channel', error: `未知通道：${key || '(缺)'}（已登记：${CHANNEL_IDS.join('、')}）` }
+  }
+  if (m.IMPLEMENTED !== true) {
+    return {
+      ok: false,
+      reason: 'channel_not_implemented',
+      error: `通道 ${key} 是**预留位**：端口契约已定，投递实现未落地`
+        + `${(m.NOTE && `（${m.NOTE}）`) || ''} ⇒ 本批只有 webhook 可用`,
+    }
+  }
+  return { ok: true, module: m }
+}
+
+/**
+ * 投递一份**已经决定要发**的意图（dry-run 不该走到这里）。
+ * @param {object} intent `{channel, target, kind, summary, text, idempotencyKey}`
+ * @param {{timeoutMs?:number, deps?:object}} [opts]
+ */
+export async function deliver(intent, opts = {}) {
+  const r = resolveChannel(intent && intent.channel)
+  if (!r.ok) return { ok: false, reason: r.reason, error: r.error }
+  const m = r.module
+  const v = typeof m.validateTarget === 'function' ? m.validateTarget(intent.target) : { ok: true, target: intent.target }
+  if (!v.ok) return { ok: false, reason: v.reason, error: v.error }
+  const out = await m.send({ ...intent, target: v.target }, { timeoutMs: opts.timeoutMs, deps: opts.deps })
+  return { ...out, ok: out.ok === true, reason: out.ok === true ? null : (out.reason || 'delivery_failed') }
+}

package/engine/core/lib/notify/verb.mjs

@@ -0,0 +1,327 @@
+/**
+ * `argent notify` 适配层（P2，2026-10-03）—— 把"投递"这件事接成机器可判的 verb（A1/A2/A3）。
+ *
+ * ## 用法
+ * ```
+ * argent notify --channel webhook --url <http(s)://…> [--text <s>|--file <path>|--body-json <json>]
+ *               [--kind <k>] [--summary <s>] [--header 'K: V']… [--idempotency-key <k>]
+ *               [--timeout-ms <n>] [--apply|--send|--confirm|--yes] [--dry-run] [--json]
+ * ```
+ *
+ * ## A1 退出码（`$?` 即结论）
+ * | 码 | 何时 | reason |
+ * |---|---|---|
+ * | `0` | 投递成功 / **成功但被去重跳过** / dry-run 预演 | `null` ｜ `duplicate_suppressed`（带 `empty:true`） |
+ * | `2` | 用法：未知通道 / 通道是预留位 / 缺目标 / 目标非法 / 缺正文 / 正文文件读不到 / 正文不是 JSON / 未知参数 | `unknown_channel` `channel_not_implemented` `target_required` `bad_target` `missing_body` `body_unreadable` `bad_body_json` `usage_error` |
+ * | `1` | 运行失败：投递失败（非 2xx、超时、连接失败）｜数据目录写不下（fail-closed） | `delivery_failed` `internal_error` |
+ *
+ * ## A2 JSON
+ * `ok/empty/code/reason` 恒在；`$? == json.code`；`--json` 时 stdout 只有一份 JSON（诊断走 stderr）。
+ * 回显**实际生效值**：`channel`/`target`（**去掉凭据与 query**）/`kind`/`bodySource`/`bodyBytes`/
+ * `idempotencyKey` + `idempotencyKeySource`/`dryRun`/`sent`/`skipped`/`dedup{...}`/`http{...}`。
+ *
+ * ## A3 dry-run
+ * **默认即 dry-run**；真发要显式确权（`--apply`/`--send`/`--confirm`/`--yes`）。
+ * dry-run **零持久副作用**：不投递、**不落去重标记、不写审计**（判据 = 跑两次后数据目录逐字节不变）。
+ * dry-run 与真跑**共用同一条判据路径**（通道校验、目标校验、去重查询、正文装载全部照跑），
+ * 只是最后不调 `send`、不落盘 ⇒ 输出仍带 `dedup.decision`（`skip`/`send`）回答"真发会怎样"。
+ *
+ * ## 与实施方案的一处用词差异（如实标注）
+ * P2① 的验收示例写的是 `--target`，本 verb 的主名字用 `--url`（`--target` 作同义词保留）；
+ * `--json <payload>` 与 A2 的输出开关**同名**：**后跟值 ⇒ 当正文**，**裸写 ⇒ 当输出开关**
+ * （两种用法都在回显里说明，不做静默猜测）。
+ */
+import { readFileSync } from 'node:fs'
+import { resolveDataDir } from '../argent-datadir.mjs'
+import { listChannels, deliver as defaultDeliver, resolveChannel } from './index.mjs'
+import { appendNotifyAudit, inspectDedup, outboxDir, resolveIdempotencyKey, writeDedupMarker } from './dedup.mjs'
+import { sanitizeTarget } from './webhook.mjs'
+
+/** 带值参数（重复 ⇒ 用法错误；`--header` 例外，可重复）。 */
+export const VALUE_FLAGS = ['--channel', '--url', '--target', '--text', '--file', '--body-json', '--kind', '--summary', '--idempotency-key', '--timeout-ms']
+/** 可重复参数。 */
+export const REPEAT_FLAGS = ['--header']
+/** 布尔参数。 */
+export const BOOL_FLAGS = ['--dry-run', ...CONFIRM_LIST()]
+/** 显式确权（真发）。 */
+function CONFIRM_LIST() { return ['--apply', '--send', '--confirm', '--yes'] }
+export const CONFIRM_FLAGS = CONFIRM_LIST()
+/** 默认投递超时（ms）。 */
+export const DEFAULT_TIMEOUT_MS = 10000
+
+const flag = (v) => (v === undefined || v === null ? null : v)
+
+/** 首行摘要（正文没给 `--summary` 时的**确定性**来源；不猜语义）。 */
+export function firstLineSummary(text, max = 200) {
+  const line = String(text == null ? '' : text).split('\n').map((l) => l.trim()).find(Boolean) || ''
+  return line.length > max ? `${line.slice(0, max)}…` : line
+}
+
+/**
+ * 参数解析（纯函数；未知参数一律拒绝 —— "别的参数我替你吃了"是错误推迟暴露的经典坑）。
+ * @returns {{ok:true, plan:object} | {ok:false, code:2, reason:string, error:string}}
+ */
+export function parseNotifyArgs(argv = []) {
+  const a = [...argv]
+  const values = {}
+  const headers = []
+  const bools = new Set()
+  let jsonOut = false
+  for (let i = 0; i < a.length; i++) {
+    const t = a[i]
+    if (t === '--json') {
+      const nxt = a[i + 1]
+      if (nxt !== undefined && !String(nxt).startsWith('--')) {          // 带值 ⇒ 正文 JSON
+        if (values['--body-json'] !== undefined) return { ok: false, code: 2, reason: 'usage_error', error: '正文给了两次（--body-json / --json）' }
+        values['--body-json'] = nxt
+        i++
+      }
+      jsonOut = true                                                        // 裸写 ⇒ A2 的输出开关
+      continue
+    }
+    if (BOOL_FLAGS.includes(t)) { bools.add(t); continue }
+    if (REPEAT_FLAGS.includes(t)) {
+      const v = a[i + 1]
+      if (v === undefined || String(v).startsWith('--')) return { ok: false, code: 2, reason: 'usage_error', error: `参数 ${t} 缺值` }
+      headers.push(v); i++
+      continue
+    }
+    if (VALUE_FLAGS.includes(t)) {
+      const v = a[i + 1]
+      if (v === undefined || String(v).startsWith('--')) return { ok: false, code: 2, reason: 'usage_error', error: `参数 ${t} 缺值` }
+      if (values[t] !== undefined) return { ok: false, code: 2, reason: 'usage_error', error: `参数 ${t} 给了两次（值：${JSON.stringify(values[t])} / ${JSON.stringify(v)}）` }
+      values[t] = v; i++
+      continue
+    }
+    return { ok: false, code: 2, reason: 'usage_error', error: `未知参数：${t}（用法见 core/lib/notify/verb.mjs 头注释或 argent notify --help）` }
+  }
+
+  // 通道
+  const channel = flag(values['--channel'])
+  if (!channel) return { ok: false, code: 2, reason: 'usage_error', error: `缺必填参数 --channel（已登记：${listChannels().map((c) => c.channel).join('、')}）` }
+  const ch = resolveChannel(channel)
+  if (!ch.ok) return { ok: false, code: 2, reason: ch.reason, error: ch.error }
+
+  // 目标：`--url` 与 `--target` 是同义词；同时给且不同值 ⇒ 明确报错（不静默取一个）
+  const url = flag(values['--url'])
+  const target = flag(values['--target'])
+  if (url && target && url !== target) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `--url 与 --target 是同义词，不能给不同的值（${url} / ${target}）` }
+  }
+  const targetInput = url || target || ''
+  const tv = typeof ch.module.validateTarget === 'function' ? ch.module.validateTarget(targetInput) : { ok: true, target: targetInput }
+  if (!tv.ok) return { ok: false, code: 2, reason: tv.reason, error: tv.error }
+
+  // 正文：三选一
+  const sources = ['--text', '--file', '--body-json'].filter((f) => values[f] !== undefined)
+  if (!sources.length) {
+    return { ok: false, code: 2, reason: 'missing_body', error: '缺正文：请给 --text <s> 或 --file <path> 或 --body-json <json>' }
+  }
+  if (sources.length > 1) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `正文只能给一个来源，实得 ${sources.join(' + ')}` }
+  }
+  const source = sources[0]
+  let text = ''
+  let payload = null
+  if (source === '--text') {
+    text = String(values['--text'])
+    if (!text.trim()) return { ok: false, code: 2, reason: 'missing_body', error: '--text 是空串 ⇒ 没有可投递的正文（空通知不是"成功但空"）' }
+  } else if (source === '--file') {
+    const p = String(values['--file'])
+    try { text = readFileSync(p, 'utf8') } catch (e) {
+      return { ok: false, code: 2, reason: 'body_unreadable', error: `正文文件读不到：${p}（${(e && e.message) || e}）` }
+    }
+  } else {
+    const raw = String(values['--body-json'])
+    try { payload = JSON.parse(raw) } catch (e) {
+      return { ok: false, code: 2, reason: 'bad_body_json', error: `--body-json 不是合法 JSON：${(e && e.message) || e}` }
+    }
+    text = typeof payload === 'string' ? payload : JSON.stringify(payload)
+  }
+
+  const timeoutRaw = values['--timeout-ms']
+  const timeoutMs = timeoutRaw === undefined ? DEFAULT_TIMEOUT_MS : Number(timeoutRaw)
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+    return { ok: false, code: 2, reason: 'usage_error', error: `--timeout-ms 必须是 ≥1 的整数，实得 ${JSON.stringify(timeoutRaw)}` }
+  }
+
+  const confirmed = CONFIRM_FLAGS.some((f) => bools.has(f))
+  const dryRun = bools.has('--dry-run') || !confirmed          // A3：默认 dry-run；--dry-run 恒优先（fail-safe）
+  const kind = flag(values['--kind']) || (payload && typeof payload === 'object' && payload.kind ? String(payload.kind) : 'generic')
+  const summary = flag(values['--summary']) || (payload && typeof payload === 'object' && payload.summary ? String(payload.summary) : firstLineSummary(text))
+  return {
+    ok: true,
+    plan: {
+      channel, target: tv.target, targetInput: String(targetInput),
+      kind, summary, text, bodySource: source.slice(2), bodyBytes: Buffer.byteLength(text, 'utf8'),
+      headers, timeoutMs, dryRun, confirmed, jsonOut,
+      idempotencyKeyInput: flag(values['--idempotency-key']),
+    },
+  }
+}
+
+const parseHeaders = (list) => {
+  const out = {}
+  for (const h of list) {
+    const i = String(h).indexOf(':')
+    if (i < 1) return { ok: false, error: `--header 形态应为 'Name: value'，实得 ${JSON.stringify(h)}` }
+    out[String(h).slice(0, i).trim()] = String(h).slice(i + 1).trim()
+  }
+  return { ok: true, headers: out }
+}
+
+/** 失败信封（照 A2：ok/empty/code/reason 恒在）。 */
+function fail(code, reason, error, echo = {}) {
+  return {
+    json: { ok: false, empty: false, code, reason, error, verb: 'notify', ...echo },
+    human: `❌ ${reason}：${error}`,
+    stderr: '',
+    exit: code,
+  }
+}
+
+export const NOTIFY_USAGE = () => [
+  '用法：argent notify --channel <c> --url <http(s)://…> [--text <s>|--file <path>|--body-json <json>]',
+  `       [--kind <k>] [--summary <s>] [--header 'K: V']… [--idempotency-key <k>] [--timeout-ms <n>]`,
+  `       [--apply|--send|--confirm|--yes] [--dry-run] [--json]`,
+  '',
+  '通道：' + listChannels().map((c) => `${c.channel}${c.implemented ? '' : '（预留位）'}`).join('、'),
+  '默认 dry-run（只打印投递意图）；真发加 --apply。去重按幂等键（未给则用内容摘要）。',
+].join('\n')
+
+/**
+ * verb 入口：`argent notify …`。
+ * @param {string[]} argv
+ * @param {{repo?:string, env?:object, dataDir?:string, deliver?:Function, now?:Date}} [deps]
+ * @returns {Promise<{json:object, human:string, stderr:string, exit:number}>}
+ */
+export async function runNotifyVerb(argv = [], deps = {}) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'notify', usage: NOTIFY_USAGE(), channels: listChannels() }, human: NOTIFY_USAGE(), stderr: '', exit: 0 }
+  }
+  const parsed = parseNotifyArgs(argv)
+  if (!parsed.ok) return fail(parsed.code, parsed.reason, parsed.error, { channel: null, target: null, dryRun: null })
+  const plan = parsed.plan
+
+  const hv = parseHeaders(plan.headers)
+  if (!hv.ok) return fail(2, 'usage_error', hv.error, { channel: plan.channel, target: sanitizeTarget(plan.target), dryRun: plan.dryRun })
+
+  const env = deps.env || process.env
+  const dataDir = deps.dataDir || defaultDataDirOf(env)
+  const sentAt = (deps.now || new Date()).toISOString()
+  const { key, source: keySource } = resolveIdempotencyKey(
+    { channel: plan.channel, target: plan.target, kind: plan.kind, summary: plan.summary, text: plan.text },
+    plan.idempotencyKeyInput,
+  )
+  const echo = {
+    channel: plan.channel,
+    target: sanitizeTarget(plan.target),
+    targetHasCredentials: /\/\/[^/@]*@/.test(plan.targetInput),
+    kind: plan.kind,
+    summary: plan.summary,
+    bodySource: plan.bodySource,
+    bodyBytes: plan.bodyBytes,
+    idempotencyKey: key,
+    idempotencyKeySource: keySource,
+    timeoutMs: plan.timeoutMs,
+    dryRun: plan.dryRun,
+    dataDir,
+    outbox: outboxDir(dataDir),
+  }
+
+  // 同一条判据路径：dry-run 也查去重（只读）⇒ 能回答"真发会怎样"
+  const before = inspectDedup(dataDir, key)
+  const dedup = { applied: true, key, marker: before.marker, preexisting: before.exists, preexistingSentAt: before.sentAt, decision: 'would_send', sentAt: null, status: null }
+  if (before.decision === 'skip') {
+    const json = {
+      ok: true, empty: true, code: 0, reason: 'duplicate_suppressed', verb: 'notify',
+      sent: false, skipped: true, skippedReason: 'already_delivered',
+      dedup: { ...dedup, decision: 'skip', sentAt: before.sentAt, status: before.status },
+      http: null, audit: { appended: false, file: null }, deliveredAt: before.sentAt, ...echo,
+      note: `同一事实已投递过（幂等键 ${key}${keySource === 'derived' ? '，由内容摘要推出' : ''}，${before.sentAt || '时间未知'}）`
+        + '；要重发请显式换一个 --idempotency-key。',
+    }
+    return {
+      json,
+      human: `⏭️ 已跳过（duplicate_suppressed）：同一事实投递过（key=${key} @ ${before.sentAt || '?'}）\n   要重发：换一个 --idempotency-key`,
+      stderr: '', exit: 0,
+    }
+  }
+
+  if (plan.dryRun) {
+    const json = {
+      ok: true, empty: false, code: 0, reason: null, verb: 'notify',
+      sent: false, skipped: false, wouldSend: true,
+      dedup, http: null, audit: { appended: false, file: null }, deliveredAt: null, ...echo,
+      note: 'dry-run（默认）：未投递、未落去重标记、未写审计；真发加 --apply',
+    }
+    return {
+      json,
+      human: `🧪 [dry-run] notify ${plan.channel} → ${json.target}\n`
+        + `   kind=${plan.kind} 正文=${plan.bodySource} ${plan.bodyBytes} B 幂等键=${key}(${keySource})\n`
+        + `   摘要：${plan.summary || '(空)'}\n`
+        + '   ⛔ 未投递（真发加 --apply）；去重标记与审计都未落盘',
+      stderr: '', exit: 0,
+    }
+  }
+
+  // ── 真发（唯一副作用点：一次 HTTP 请求 + 标记 + 审计）────────────────────
+  const deliver = deps.deliver || defaultDeliver
+  let res = null
+  try {
+    res = await deliver({ channel: plan.channel, target: plan.target, kind: plan.kind, summary: plan.summary, text: plan.text, headers: hv.headers, idempotencyKey: key, sentAt }, { timeoutMs: plan.timeoutMs, deps: deps.deliverDeps })
+  } catch (e) {
+    res = { ok: false, reason: 'delivery_failed', error: `通道抛异常：${(e && e.message) || e}` }
+  }
+  const http = { status: res && res.status != null ? res.status : null, responseExcerpt: (res && res.responseExcerpt) || null, bytes: (res && res.bytes != null ? res.bytes : plan.bodyBytes) }
+
+  if (!res || res.ok !== true) {
+    const code = res && res.reason === 'internal_error' ? 1 : 1
+    const json = {
+      ok: false, empty: false, code, reason: res && res.reason && res.reason !== 'delivery_failed' ? res.reason : 'delivery_failed',
+      error: (res && res.error) || '投递失败（未知原因）', verb: 'notify',
+      sent: false, skipped: false, dedup, http, audit: { appended: false, file: null }, deliveredAt: null, ...echo,
+      note: '投递失败 ⇒ **未落去重标记**（原样重试即可，不会被"试过一次"永久跳过）',
+    }
+    return { json, human: `❌ 投递失败（${json.reason}）：${json.error}\n   目标 ${json.target}｜HTTP ${http.status ?? '—'}｜未落标记、可原样重试`, stderr: '', exit: code }
+  }
+
+  // 成功 ⇒ 落标记 + 审计（fail-closed：写不下就报 internal_error，绝不当成功）
+  try {
+    writeDedupMarker(dataDir, key, { channel: plan.channel, target: echo.target, kind: plan.kind, summary: plan.summary, status: http.status, bytes: http.bytes })
+    appendNotifyAudit(dataDir, {
+      verb: 'notify', channel: plan.channel, target: echo.target, kind: plan.kind, summary: plan.summary,
+      idempotencyKey: key, idempotencyKeySource: keySource, status: http.status, bytes: http.bytes, ok: true,
+      who: 'argent/notify P2',
+    })
+  } catch (e) {
+    const json = {
+      ok: false, empty: false, code: 1, reason: 'internal_error',
+      error: `投递已发出但**标记/审计写不下**（${(e && e.message) || e}）⇒ 按 fail-closed 报失败；`
+        + '后果：下一次调用会**再发一次**（去重标记没落成），请先修数据目录可写性。',
+      verb: 'notify', sent: true, skipped: false,
+      dedup: { ...dedup, decision: 'sent', sentAt, status: http.status },
+      http, audit: { appended: false, file: null }, deliveredAt: sentAt, ...echo,
+    }
+    return { json, human: `⚠️ ${json.error}`, stderr: '', exit: 1 }
+  }
+
+  const json = {
+    ok: true, empty: false, code: 0, reason: null, verb: 'notify',
+    sent: true, skipped: false, wouldSend: null,
+    dedup: { ...dedup, decision: 'sent', sentAt, status: http.status },
+    http, audit: { appended: true, file: `${outboxDir(dataDir)}/audit.jsonl` }, deliveredAt: sentAt, ...echo,
+    note: null,
+  }
+  return {
+    json,
+    human: `✅ 已投递：${plan.channel} → ${json.target}（HTTP ${http.status}，${http.bytes} B，幂等键 ${key}）\n`
+      + `   去重标记与审计已落：${json.outbox}`,
+    stderr: '', exit: 0,
+  }
+}
+
+/** 数据目录：**唯一判据**在 `core/lib/argent-datadir.mjs`（本文件不复制那条链）。 */
+function defaultDataDirOf(env) {
+  return resolveDataDir({ env }).dir
+}