@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/final-check.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// 0.7.0 **唯一终检入口**：一条命令跑完全部门禁（串行、遇错继续但最终按最差判）。
+// 用法：node scripts/final-check.mjs [--json]
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLI = process.env.ARGENT_CLI_REPO || join(REPO, '..', 'argent-cli')
+const CHECKS = [
+  ['kernel-purity',           'node', ['scripts/tests/kernel-purity.test.mjs']],
+  ['S1 赋值行门禁',            'node', ['scripts/tests/datadir-literal-gate.test.mjs']],
+  ['S1 非赋值写入门禁',         'node', ['scripts/tests/datadir-writes-gate.test.mjs']],
+  ['JS/Python 目录一致性',      'node', ['scripts/tests/datadir-parity.test.mjs']],
+  ['引擎包逐字节一致',          'node', ['scripts/tests/engine-package.test.mjs']],
+  ['退役面盘点只读',            'node', ['scripts/tests/retire-inventory.test.mjs']],
+  ['安装指南命令核对',          'node', ['scripts/tests/setup-guide.test.mjs']],
+
+  ['命名空间/业务词 lint',      'node', ['scripts/vertical-lint.mjs']],
+  ['能力包盖章自检',            'python3', ['scripts/capability_pack.py', '--check-stamp']],
+  ['能力包 validate',          'python3', ['scripts/capability_pack.py', '--validate']],
+]
+const rows = []
+for (const [name, cmd, args] of CHECKS) {
+  const t0 = Date.now(); let ok = false, out = ''
+  try { out = execFileSync(cmd, args, { cwd: REPO, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); ok = true }
+  catch (e) { out = `${e.stdout || ''}${e.stderr || ''}` || String(e.message) }
+  rows.push({ name, ok, ms: Date.now() - t0, tail: out.trim().split('\n').slice(-1)[0]?.slice(0, 90) || '' })
+}
+if (existsSync(CLI)) {
+  const t0 = Date.now(); let ok = false, out = ''
+  try { out = execFileSync('node', ['scripts/prepublish-check.mjs'], { cwd: CLI, encoding: 'utf8' }); ok = true }
+  catch (e) { out = `${e.stdout || ''}${e.stderr || ''}` }
+  rows.push({ name: '新仓发布前自检', ok, ms: Date.now() - t0, tail: out.trim().split('\n').slice(-1)[0]?.slice(0, 90) || '' })
+}
+const bad = rows.filter((r) => !r.ok)
+if (process.argv.includes('--json')) { console.log(JSON.stringify({ ok: bad.length === 0, rows }, null, 2)) }
+else {
+  console.log('0.7.0 串行终检：')
+  for (const r of rows) console.log(`  ${r.ok ? '✅' : '❌'} ${r.name.padEnd(22)} ${String(r.ms).padStart(6)}ms  ${r.tail}`)
+  console.log(`\n${bad.length ? '❌' : '✅'} 终检：${rows.length - bad.length}/${rows.length} 通过${bad.length ? '（失败：' + bad.map((b) => b.name).join('、') + '）' : ''}`)
+}
+process.exit(bad.length ? 1 : 0)

package/engine/scripts/fix-skill-frontmatter.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""修复/校验仓库技能的 frontmatter（2026-09-11）
+
+**这不是格式洁癖——不合法就是技能根本不生效。** 三处硬性要求都来自
+`dsh-skill-filesystem` → `parseSkillFile()`（0.1.5-rc.1 `lib/index.js:664-695`）：
+
+  ① **首行 `---` + 必须有闭合 `---`**（`parseFrontmatter()`，`:772-798`）。
+     找不到闭合 ⇒ `return undefined` ⇒ 整文件丢弃，只 warn
+     `skill file ... ignored: missing YAML frontmatter`。
+     ⚠️ 隐蔽形态：正文里的水平线 `---` 会被**当成闭合**，中间几十~上百行正文被当 YAML 解析 → 失败 → 同样丢弃。
+
+  ② **`name` 必须是严格小写 kebab-case**（`:685` 调 `isSkillName()`，
+     `@deepseek-ai/dsh-skill` 的 `SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/`）。
+     不合法 ⇒ warn `invalid skill name "…"` ⇒ 丢弃。
+     ⚠️ **中文名（如 `name: 美客多账户健康诊断`）一律非法**；技能目录里显示、`skill` 工具要调用的
+     就是这个名字 ⇒ 人读的标题应放 `description`，或保留在自定义 `title` 字段（加载器不读它）。
+     本脚本把 `name` 归一为**目录名**（与现有可加载技能一致），原标题搬到 `title:`。
+  ③ 另要求 frontmatter **同时含 `name` 与 `description`**（`:679-684`）。
+
+用法：
+  python3 scripts/fix-skill-frontmatter.py --check   # 只报告（门禁/CI 用），有问题 exit 1
+  python3 scripts/fix-skill-frontmatter.py --write    # 就地修复（补闭合 + name 归一为目录名）
+  python3 scripts/fix-skill-frontmatter.py --list     # 列出全部技能状态
+"""
+import pathlib
+import re
+import sys
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'scripts' / 'lib'))
+from stdio_utf8 import use_utf8_stdio  # noqa: E402  出口编码钉 UTF-8（中文 Windows 的 GBK 管道下非 ASCII 会崩）
+SKILLS = ROOT / 'skills'
+REQUIRED = ('name', 'description')
+# 与 @deepseek-ai/dsh-skill 的 SKILL_NAME 完全一致
+NAME_RE = re.compile(r'^[a-z0-9]+(?:-[a-z0-9]+)*$')
+
+
+def closing_line(lines):
+    for i, line in enumerate(lines[1:], start=2):
+        if line.rstrip('\r') == '---':
+            return i
+    return None
+
+
+def first_heading(lines):
+    for i, line in enumerate(lines[1:], start=2):
+        if line.startswith('#'):
+            return i
+    return None
+
+
+def split_frontmatter(text):
+    """返回 (yaml_text, close_line, body)；闭合位置不可信时 yaml_text=None。"""
+    lines = text.split('\n')
+    if not lines or lines[0].rstrip('\r') != '---':
+        return None, None, text
+    close = closing_line(lines)
+    head = first_heading(lines)
+    if close is None or (head is not None and close > head):
+        return None, close, text
+    return '\n'.join(lines[1:close - 1]), close, '\n'.join(lines[close:])
+
+
+def raw_state(text):
+    lines = text.split('\n')
+    close = closing_line(lines)
+    head = first_heading(lines)
+    if close is None or (head is not None and close > head):
+        return {'reason': 'missing-closing-delimiter', 'head': head, 'stray': close}
+    return {'reason': 'ok'}
+
+
+def diagnose(text, expect_name=None):
+    lines = text.split('\n')
+    if not lines or lines[0].rstrip('\r') != '---':
+        return {'ok': False, 'reason': 'no-leading-delimiter'}
+    state = raw_state(text)
+    if state['reason'] != 'ok':
+        head = state['head']
+        return {'ok': False, 'reason': 'missing-closing-delimiter',
+                'head': head, 'stray': state['stray'],
+                'insert_after': (head - 2) if head else None}
+    fm, close, _ = split_frontmatter(text)
+    if yaml is not None:
+        try:
+            data = yaml.safe_load(fm)
+        except Exception as e:
+            return {'ok': False, 'reason': f'invalid-yaml: {e}'}
+        if not isinstance(data, dict):
+            return {'ok': False, 'reason': 'frontmatter-not-a-mapping'}
+        missing = [k for k in REQUIRED if not data.get(k)]
+        if missing:
+            return {'ok': False, 'reason': f'missing-required: {",".join(missing)}'}
+        name = str(data.get('name', ''))
+        if not NAME_RE.match(name):
+            return {'ok': False, 'reason': 'invalid-skill-name', 'name': name}
+        if expect_name is not None and name != expect_name:
+            return {'ok': False, 'reason': 'name-dir-mismatch', 'name': name, 'expect': expect_name}
+        return {'ok': True, 'close': close, 'name': name}
+    return {'ok': True, 'close': close, 'name': None}
+
+
+def fix(text, dir_id):
+    """返回 (新文本, [修复说明])。"""
+    notes = []
+    # ① 先补闭合
+    state = raw_state(text)
+    if state['reason'] == 'missing-closing-delimiter':
+        lines = text.split('\n')
+        head = state['head']
+        j = head - 2
+        while j >= 1 and lines[j].strip() == '':
+            j -= 1
+        lines = lines[:j + 1] + ['---'] + lines[j + 1:]
+        text = '\n'.join(lines)
+        notes.append('补闭合 `---`（原先命中的是正文水平线）' if state['stray'] is not None else '补闭合 `---`')
+    # ② 再归一 name
+    fm, close, _ = split_frontmatter(text)
+    if fm is None:
+        return text, notes + ['⚠️ 仍无法定位 frontmatter，需人工处理']
+    lines = text.split('\n')
+    name_idx = old_name = title_idx = None
+    for i in range(1, close - 1):
+        m = re.match(r'^name:\s*(.*)$', lines[i])
+        if m:
+            name_idx, old_name = i, m.group(1).strip().strip('"').strip("'")
+        if re.match(r'^title:\s*', lines[i]):
+            title_idx = i
+    if name_idx is None:
+        anchor = 1
+        while anchor < close - 1 and not re.match(r'^id:\s*', lines[anchor]):
+            anchor += 1
+        if anchor >= close - 1:
+            anchor = 1
+        lines.insert(anchor + 1, f'name: {dir_id}')
+        notes.append(f'补 `name: {dir_id}`')
+    elif old_name != dir_id:
+        lines[name_idx] = f'name: {dir_id}'
+        notes.append(f'`name: {old_name}` → `name: {dir_id}`')
+        if title_idx is None and old_name:
+            lines.insert(name_idx + 1, f'title: {old_name}')
+            notes.append(f'原标题保留为 `title: {old_name}`')
+    return '\n'.join(lines), notes
+
+
+def iter_skills():
+    if not SKILLS.is_dir():
+        return
+    for d in sorted(SKILLS.iterdir()):
+        f = d / 'SKILL.md'
+        if d.is_dir() and f.is_file():
+            yield d.name, f
+
+
+def main():
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    mode = '--list' if '--list' in sys.argv else ('--write' if '--write' in sys.argv else '--check')
+    bad, fixed, total = [], [], 0
+    for name, path in iter_skills():
+        total += 1
+        text = path.read_text()
+        d = diagnose(text, expect_name=name)
+        if d['ok']:
+            if mode == '--list':
+                print(f'  ✅ {name}')
+            continue
+        bad.append((name, d))
+        if mode == '--write':
+            new, notes = fix(text, name)
+            path.write_text(new)
+            again = diagnose(new, expect_name=name)
+            if again['ok']:
+                fixed.append((name, notes))
+            else:
+                print(f'  ❌ {name}: 修复后仍不合法（{again["reason"]}）')
+        elif mode == '--list':
+            print(f'  ❌ {name}: {d["reason"]}' + (f'（name={d.get("name")!r}）' if d.get('name') else ''))
+            if d.get('insert_after'):
+                print(f'       应插在第 {d["insert_after"]} 行后')
+
+    if mode == '--write':
+        for name, notes in fixed:
+            print(f'  ✅ {name}: ' + '；'.join(notes))
+        print(f'修复 {len(fixed)}/{len(bad)} 个')
+        return 0 if len(fixed) == len(bad) else 1
+
+    if mode == '--list':
+        return 0
+
+    if bad:
+        print(f'❌ {len(bad)} 个技能 frontmatter 不合法（这些技能**不会被加载**）：')
+        for name, d in bad:
+            extra = f'（name={d.get("name")!r}）' if d.get('name') else ''
+            if d.get('insert_after'):
+                extra += f'（应插在第 {d["insert_after"]} 行后）'
+            print(f'  - {name}: {d["reason"]}{extra}')
+        print('\n修法：python3 scripts/fix-skill-frontmatter.py --write')
+        return 1
+    print(f'✅ 全部 {total} 个技能 frontmatter 合法（闭合 + name 为 kebab-case 且等于目录名 + description）')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())