@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/argent-catalog.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * argent-catalog —— 业务线 / 能力目录（P1 数据层，2026-09-29）
+ *
+ * 为什么先有它：设计说明（docs/角色页-改造为业务线与能力页-设计说明.md）里 P1 的"只读清单"
+ * 需要三类事实：① 有哪些业务线/能力（仓库侧真源：注册表 + verticals manifest）；
+ * ② 本机版本是否满足声明（`requires.argent` / `requires.dsh`）；③ 装了没有（线索）。
+ * 这三类都只有**本机**知道 ⇒ 先把它们产成一份稳定 JSON，服务端接口与 UI tab 都消费它，
+ * 避免各自去猜（也避免把"仓库知识"塞进服务端）。
+ *
+ * 用法：node scripts/argent-catalog.mjs [--json] [--plan <free|pro|enterprise>]
+ *   `--plan` 显式给"账号档位"（缺省：env `ARGENT_ACCOUNT_PLAN` → `install.json#plan` →
+ *   **取不到就不做档位过滤**）；面板级 `minPlan` 由注册表派生，过滤在**服务端**算成布尔。
+ * 退出码：0 正常；2 环境/读取问题。
+ *
+ * 2026-09-30 扩展：同时产出**能力包设置页面板**（`settingsPanels`）—— 契约与聚合逻辑在
+ * `scripts/lib/settings-panels.mjs`，这里只负责"本机事实"的拼装（仓库根/家目录/数据目录）。
+ * `GET /api/argent-gateway/settings-panels` 与 `--json` 消费的是**同一份** panels 数组，
+ * 避免"接口一份、脚本一份"的第二真相。
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadRegistryDoc } from './lib/registry.mjs'   // 唯一真源（禁止直读 base：registry-single-source 门禁）
+import { buildPanelsDoc } from './lib/settings-panels.mjs'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const AS_JSON = process.argv.includes('--json')
+const PLAN_ARG = (() => { const i = process.argv.indexOf('--plan'); return i >= 0 ? String(process.argv[i + 1] || '') : '' })()
+
+const readJson = (p, d = null) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return d } }
+const localVersion = (cmd) => { try { return execFileSync(cmd[0], cmd.slice(1), { encoding: 'utf8' }).trim().split('\n').pop().trim() } catch { return '' } }
+
+/** 极简 semver 区间判定（只支持 >=x.y.z 与 >=a <b 这类安装器实际用法）。 */
+function satisfies(version, range) {
+  if (!range || !version) return null
+  const v = version.replace(/^v/, '').split('-')[0].split('.').map(Number)
+  const cmp = (a, b) => { for (let i = 0; i < 3; i += 1) { const d = (a[i] || 0) - (b[i] || 0); if (d) return d } return 0 }
+  return range.split(/\s+/).every((part) => {
+    const m = /^(>=|<=|>|<|=)?\s*v?([\d.]+)$/.exec(part.trim())
+    if (!m) return true
+    const [, op = '=', num] = m
+    const t = num.split('.').map(Number)
+    const c = cmp(v, t)
+    return op === '>=' ? c >= 0 : op === '<=' ? c <= 0 : op === '>' ? c > 0 : op === '<' ? c < 0 : c === 0
+  })
+}
+
+const argentVersion = (readFileSync(join(REPO, 'VERSION'), 'utf8') || '').trim()
+const dshVersion = localVersion(['dsh', '--version'])
+const installedSkills = existsSync(join(process.env.HOME || '', '.dsh', 'skills'))
+  ? readdirSync(join(process.env.HOME, '.dsh', 'skills')).filter((d) => !d.startsWith('.') && d !== 'README.md')
+  : []
+
+// ── ① 业务线（verticals/*/manifest.json；唯一真源）──
+const verticals = []
+const vroot = join(REPO, 'verticals')
+if (existsSync(vroot)) {
+  for (const d of readdirSync(vroot, { withFileTypes: true })) {
+    if (!d.isDirectory()) continue
+    const man = readJson(join(vroot, d.name, 'manifest.json'))
+    if (!man) continue
+    const req = man.requires || {}
+    const argentOk = satisfies(argentVersion, req.argent)
+    const dshOk = satisfies(dshVersion, req.dsh)
+    verticals.push({
+      id: man.id || d.name, title: man.title || d.name, version: man.version || '',
+      requires: req, argentVersion, dshVersion,
+      ok: argentOk !== false && dshOk !== false,
+      reason: argentOk === false ? `需要 Argent ${req.argent}（本机 ${argentVersion}）`
+        : dshOk === false ? `需要 dsh ${req.dsh}（本机 ${dshVersion}）` : '',
+      legacyNaming: man.legacyNaming || [],
+    })
+  }
+}
+
+// ── ② 能力（注册表 capabilities；按业务线归属）──
+// ⚠️ 必须走加载器：P2a 之后业务线流程**不在 base 注册表里**（直读会得到"流程 0 条"的假象），
+// 且 scripts/tests/registry-single-source.test.mjs 门禁禁止除加载器外直读 base。
+const reg = loadRegistryDoc()
+const capabilities = []
+for (const [id, cap] of Object.entries(reg.capabilities || {})) {
+  if (!cap || typeof cap !== 'object' || !cap.pack) continue
+  const flows = Object.entries(reg.flows || {}).filter(([, f]) => (f || {}).capability === id).map(([fid]) => fid)
+  // 归属业务线：从规范流程 id 的前缀推（`<vertical>.<local>`），比在 base 里再维护一份映射可靠
+  const vertical = cap.vertical || (flows[0] || '').split('.')[0] || ''
+  const skills = (cap.pack.skills || []).map((s) => String(s).replace(/^skills\//, ''))
+  const installedSkillsHit = skills.filter((s) => installedSkills.includes(s))
+  capabilities.push({
+    id, version: cap.pack.version, vertical,
+    flows, skills,
+    installedHint: skills.length ? { hit: installedSkillsHit.length, of: skills.length, skills: installedSkillsHit } : null,
+  })
+}
+
+// ── ③ 能力包设置页面板（声明在 verticals/<id>/manifest.json 或 capabilities.<c>.pack）──
+// 「未装即不显示」的判据就在这里算出来（installed/source/evidence），客户端只认这个布尔。
+// 数据目录口径与 host 侧一致：**三级链的唯一判据在内核**（core/lib/argent-datadir.mjs）
+// —— `ARGENT_DATA_DIR → $DSH_HOME/argent → ~/.dsh/argent`（2026-10-01 统一，此前不看 DSH_HOME）。
+const HOME_DIR = process.env.HOME || homedir()
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+// 账号档位：`--plan` → env ARGENT_ACCOUNT_PLAN → install.json.plan → 取不到则 known=false（不过滤）。
+// ⚠️ 档位**只用来算 planGated 布尔**（服务端口径），客户端拿到的仍是布尔，不拿档位表。
+const panelsDoc = buildPanelsDoc({
+  root: REPO, home: HOME_DIR, dataDir: DATA_DIR, registryDoc: reg,
+  accountPlan: PLAN_ARG || undefined,
+})
+
+const doc = {
+  generatedAt: new Date().toISOString(),
+  local: { argentVersion, dshVersion, installedSkills: installedSkills.length },
+  verticals, capabilities,
+  // 能力包设置页：**全部声明**的面板（各自带 installed 标记）；客户端"未装即不显示"。
+  // 只要已装的那一份（接口视角）由 host 的 /api/argent-gateway/settings-panels 过滤产出。
+  settingsPanels: panelsDoc.panels,
+  settingsPanelErrors: panelsDoc.errors,
+  settingsPanelNote: panelsDoc.note,
+  // 已购事实（来自 install.json#entitlement；known=false ⇒ 未知）。⛔ 未购/未装**都不是异常、
+  // 不是缺件**：二者只影响"显不显示"，一律按"未开通"中性呈现，不产生任何错误标记。
+  entitlement: panelsDoc.entitlement,
+  // 面板级档位（服务端过滤用）：账号档位是否已知 + 哪些面板被档位滤掉 + env 写入器开关
+  accountPlan: panelsDoc.plan,
+  settingsPanelsHiddenByPlan: panelsDoc.hiddenByPlan,
+  envWriter: panelsDoc.envWriter,
+  note: 'P1 只读目录：业务线/能力 + requires 判定 + 已装线索（installedHint 由 ~/.dsh/skills 推断，非权威安装记录）',
+}
+if (AS_JSON) { console.log(JSON.stringify(doc, null, 2)) } else {
+  console.log(`\nArgent 业务线/能力目录（本机 Argent ${argentVersion}｜dsh ${dshVersion}）\n`)
+  console.log('  业务线：')
+  for (const v of verticals) console.log(`    ${v.ok ? '✅' : '⚠️ '} ${v.id}（${v.title}）v${v.version}  requires: argent ${v.requires.argent || '-'} / dsh ${v.requires.dsh || '-'}${v.reason ? ' ⇒ ' + v.reason : ''}`)
+  console.log('\n  能力：')
+  for (const c of capabilities) {
+    const hint = c.installedHint ? `已装技能 ${c.installedHint.hit}/${c.installedHint.of}` : '（无技能声明）'
+    console.log(`    · ${c.id} v${c.version}｜流程 ${c.flows.length} 条｜${hint}`)
+    if (c.flows.length) console.log(`      流程: ${c.flows.join(', ')}`)
+  }
+  console.log('\n  能力包设置页（未装的不显示）：')
+  if (!panelsDoc.panels.length) console.log('    （没有任何能力包声明设置页）')
+  // ⚠️ 呈现口径（2026-10-09，针对性安装）：
+  //   **未购 / 未装都不是异常、不是缺件** —— 一律只说"未开通"。
+  //   本目录曾把二者渲染成 `⛔ 档位不足 / ⛔ 隐藏`，那会让"客户只买了 HR"看起来像坏了。
+  //   判定仍是 `installed`（已装？）与 `entitled`（已购？三态，null=未知）两个事实，标签只是派生。
+  for (const p of panelsDoc.panels) {
+    const pw = (p.fields || []).filter((f) => !f.readonly).length
+    // 「已购」三态：true 已购 / false 未购 / null 未知。⛔ 三态里的 null **不是**未购 ——
+    // 且 `mode=plan`（该账号未按购买裁剪）时"未购"这个概念**根本不适用**，不能说成"未购?"。
+    const entKnown = !!(panelsDoc.entitlement && panelsDoc.entitlement.known)
+    const entMode = (panelsDoc.entitlement && panelsDoc.entitlement.mode) || ''
+    const bought = p.entitled === true ? '已购'
+      : p.entitled === false ? '未购'
+        : entKnown && entMode === 'plan' ? '未购不适用（该账号按套餐下发，未被裁剪）'
+          : '未购?（无服务端已购清单）'
+    const mark = p.state === '已开通' ? '✅' : '·'      // ⛔ 非"已开通"一律中性标记，不报红
+    const fh = p.fieldsHiddenByPlan ? `，档位未覆盖 ${p.fieldsHiddenByPlan}` : ''
+    console.log(`    ${mark} ${p.state}｜${p.title}（${p.id}）`
+      + `｜能力 ${(p.capabilities || []).join('/') || '-'}｜字段 ${p.fields.length} 个（可写 ${pw}${fh}）`)
+    console.log(`        已购/已装：${bought} / ${p.installed ? '已装' : '未装'}`
+      + `｜安装判据 ${p.installSource}：${p.installDetail}`)
+    console.log(`        档位：${p.planGated ? `未覆盖（需 ${p.minPlan}，本账号 ${panelsDoc.plan.value || '?'}）` : '覆盖'}`
+      + `（面板 minPlan=${p.minPlan || '不限'} · ${p.minPlanSource || '未设'}）`
+      + `${p.installed && !p.enabled ? ' ｜ ⚠️ 已暂停（流程开关）' : ''}`)
+  }
+  // 被档位滤掉的**面板**与**字段**：同样是"未开通"，**不是**错误。
+  for (const h of panelsDoc.hiddenByPlan) {
+    console.log(h.kind === 'field'
+      ? `    · 未开通（字段）：${h.panelTitle || h.panel} › ${h.label || h.field}（未覆盖 ${h.minPlan}）—— ${h.reason}`
+      : `    · 未开通（整页）：${h.title}（${h.id}，未覆盖 ${h.minPlan}）—— ${h.reason}`)
+  }
+  if (panelsDoc.hiddenByPlan.length || panelsDoc.panels.some((p) => !p.installed || p.planGated)) {
+    console.log('    注：未开通 = 未购或未装，**不是异常、不是缺件**，不影响已在用的能力。')
+  }
+  // 已购事实的来源与口径（未配置 ⇒ 不产生假的"未购"）
+  const ent = panelsDoc.entitlement || {}
+  console.log(`  已购清单：${ent.known
+    ? `${ent.mode}（granted ${(ent.granted || []).join(',') || '无'}${ent.mode === 'plan' ? '；该账号未按购买裁剪 ⇒ 没有"未购"概念' : ''}）`
+    : '未知（install.json 没有 entitlement 块 ⇒ 一律按"未开通"中性呈现，不报红）'}`)
+  console.log(`\n  账号档位：${panelsDoc.plan.known ? `${panelsDoc.plan.value}（来自 ${panelsDoc.plan.source}）` : '未知 ⇒ 不做档位过滤'}`)
+  console.log(`  env 写入器：${panelsDoc.envWriter.enabled ? '✅ 已开启' : '⛔ 默认关闭'}（开关 ${panelsDoc.envWriter.switch}=1；可用字段 ${panelsDoc.envWriter.targets.length} 个）`)
+  for (const e of panelsDoc.errors) console.log(`    ❌ 声明错误 [${e.code}] ${e.message}`)
+  console.log(`\n  注：${doc.note}`)
+}
+process.exit(0)

package/engine/scripts/argent-datadir.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""`scripts/argent-datadir.py` —— 数据目录判据的 **CLI 包装**（给 shell 用）。
+
+**判据不在这里**：唯一实现在 `scripts/lib/argent_datadir.py`（与 JS 内核
+`core/lib/argent-datadir.mjs` 同语义）。本文件只做三件事：把 `scripts/lib` 加进 sys.path、
+解析参数、把结果打到 stdout —— 供 `flow-trigger.sh` 等 bash 脚本取目录
+（**⛔ 不要在 bash 里重写三级链**：`${ARGENT_DATA_DIR:-$HOME/.dsh/argent}` 那类写法正是
+"隔离实例一半写隔离目录、一半写生产"的病根）。
+
+用法：
+  DATA_DIR="$(python3 scripts/argent-datadir.py)"          # 只要目录（默认行为）
+  python3 scripts/argent-datadir.py --field source         # 命中的是哪一级
+  python3 scripts/argent-datadir.py --json                 # 解析结果 + 失败回路安全阀
+  python3 scripts/argent-datadir.py --dir /x --gate        # 对**给定**目录求安全阀
+退出码：0 成功；2 用法错误（**解析失败不会假装成功**：`dir` 为空串时调用方应自行停住）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / "lib"))
+
+import argent_datadir as _ad  # noqa: E402  —— 唯一实现（勿在此复制判据）
+from stdio_utf8 import use_utf8_stdio  # noqa: E402  出口编码钉 UTF-8（中文 Windows 的 GBK 管道下非 ASCII 会崩）
+
+FIELDS = ("dir", "raw", "source", "isolated", "defaultDir", "dshHome")
+
+
+def main(argv=None) -> int:
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    ap = argparse.ArgumentParser(add_help=True, description="Argent 数据目录（唯一判据的 CLI 包装）")
+    ap.add_argument("--json", action="store_true", help="输出 JSON（解析结果 + gate）")
+    ap.add_argument("--field", default="dir", choices=FIELDS, help="只输出某个字段（缺省 dir）")
+    ap.add_argument("--gate", action="store_true", help="只输出失败回路安全阀（JSON）")
+    ap.add_argument("--dir", default="", help="对**给定**目录求安全阀（宿主把目录写死在配置里时用）")
+    a = ap.parse_args(argv)
+
+    if a.dir:                                  # 显式目录：判据仍在库里（loop_gate_for_dir）
+        gate = _ad.loop_gate_for_dir(a.dir)
+        if a.json or a.gate:
+            print(json.dumps(gate, ensure_ascii=False, sort_keys=True))
+        else:
+            print(gate["dir"])
+        return 0
+
+    resolved = _ad.resolve_data_dir()
+    gate = _ad.loop_gate(resolved)
+    if a.json:
+        print(json.dumps({"resolved": resolved, "gate": gate}, ensure_ascii=False, sort_keys=True))
+    elif a.gate:
+        print(json.dumps(gate, ensure_ascii=False, sort_keys=True))
+    else:
+        print("true" if resolved[a.field] is True else
+              ("false" if resolved[a.field] is False else resolved[a.field]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())