@microi.net/cli 4.9.6 → 4.9.8

package/skills/scripts/optimize-progressive-disclosure.mjs

@@ -0,0 +1,204 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const skillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const manifestPath = path.join(skillsRoot, '.progressive-disclosure-manifest.json')
+const maxEntryLines = 285
+const keepBudgetLines = 170
+const referenceBudgetLines = 245
+
+const hash = (value) => crypto.createHash('sha256').update(value).digest('hex')
+const lineCount = (value) => value.length === 0 ? 0 : value.split(/\r?\n/).length
+const slug = (value) => value
+  .replace(/^#+\s*/, '')
+  .replace(/[`*_]/g, '')
+  .trim()
+  .toLowerCase()
+  .replace(/[^\p{L}\p{N}]+/gu, '-')
+  .replace(/^-|-$/g, '')
+  .slice(0, 48) || 'reference'
+
+const splitAtHeading = (value, headingPattern) => {
+  const matches = [...value.matchAll(headingPattern)]
+  if (matches.length <= 1) return [value]
+  const parts = []
+  if (matches[0].index > 0) parts.push(value.slice(0, matches[0].index))
+  for (let index = 0; index < matches.length; index += 1) {
+    parts.push(value.slice(matches[index].index, matches[index + 1]?.index ?? value.length))
+  }
+  return parts.filter(Boolean)
+}
+
+const splitOversized = (value, eol) => {
+  if (lineCount(value) <= referenceBudgetLines) return [value]
+  let parts = splitAtHeading(value, /^###\s+.+$/gm)
+  if (parts.length === 1) parts = splitAtHeading(value, /^####\s+.+$/gm)
+  const output = []
+  for (const part of parts) {
+    if (lineCount(part) <= referenceBudgetLines) {
+      output.push(part)
+      continue
+    }
+    const lines = part.split(/\r?\n/)
+    let start = 0
+    while (start < lines.length) {
+      let end = Math.min(start + referenceBudgetLines - 8, lines.length)
+      if (end < lines.length) {
+        for (let cursor = end; cursor > start + 40; cursor -= 1) {
+          if (lines[cursor - 1].trim() === '') {
+            end = cursor
+            break
+          }
+        }
+      }
+      const hasTrailingBreak = end < lines.length || part.endsWith(eol)
+      output.push(lines.slice(start, end).join(eol) + (hasTrailingBreak ? eol : ''))
+      start = end
+    }
+  }
+  return output
+}
+
+const headingOf = (value, fallback) => value.match(/^#{2,4}\s+(.+)$/m)?.[1]?.trim() || fallback
+
+const skillDirectories = fs.readdirSync(skillsRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillsRoot, entry.name, 'SKILL.md')))
+  .map((entry) => entry.name)
+  .sort()
+
+const manifest = {
+  version: 1,
+  generatedAt: new Date().toISOString(),
+  policy: {
+    maxEntryLines,
+    referenceBudgetLines,
+    note: 'Original prefix and ordered chunks reconstruct the exact pre-split SKILL.md bytes.'
+  },
+  skills: {}
+}
+
+for (const skillName of skillDirectories) {
+  const skillPath = path.join(skillsRoot, skillName, 'SKILL.md')
+  const original = fs.readFileSync(skillPath, 'utf8')
+  if (lineCount(original) <= 300) continue
+  if (original.includes('<!-- microi-progressive:begin -->')) {
+    throw new Error(`${skillName} is already optimized; validate instead of running twice`)
+  }
+
+  const eol = original.includes('\r\n') ? '\r\n' : '\n'
+  const sectionMatches = [...original.matchAll(/^##\s+.+$/gm)]
+  if (sectionMatches.length < 2) {
+    throw new Error(`${skillName} needs at least two level-2 sections for safe semantic splitting`)
+  }
+  const prefix = original.slice(0, sectionMatches[0].index)
+  const sections = sectionMatches.map((match, index) => ({
+    heading: match[0].replace(/^##\s+/, '').trim(),
+    raw: original.slice(match.index, sectionMatches[index + 1]?.index ?? original.length),
+  }))
+
+  const kept = []
+  const moved = []
+  let keptLines = lineCount(prefix)
+  for (const section of sections) {
+    // Keep one contiguous prefix only. Picking a later short section after an
+    // earlier section was moved would reorder the original knowledge stream.
+    if (moved.length === 0 && (kept.length === 0 || keptLines + lineCount(section.raw) <= keepBudgetLines)) {
+      kept.push(section)
+      keptLines += lineCount(section.raw)
+    } else {
+      moved.push(section)
+    }
+  }
+  if (moved.length === 0) {
+    moved.push(kept.pop())
+  }
+
+  const fragments = moved.flatMap((section) => splitOversized(section.raw, eol).map((raw, index) => ({
+    raw,
+    heading: headingOf(raw, `${section.heading} (${index + 1})`),
+  })))
+
+  const referenceGroups = []
+  let current = []
+  let currentLines = 5
+  for (const fragment of fragments) {
+    const cost = lineCount(fragment.raw) + 3
+    if (current.length && currentLines + cost > referenceBudgetLines) {
+      referenceGroups.push(current)
+      current = []
+      currentLines = 5
+    }
+    current.push(fragment)
+    currentLines += cost
+  }
+  if (current.length) referenceGroups.push(current)
+
+  const referencesDirectory = path.join(skillsRoot, skillName, 'references')
+  fs.mkdirSync(referencesDirectory, { recursive: true })
+  const chunkRecords = []
+  let ordinal = 0
+  const wrapChunk = (raw, destination) => {
+    const id = `${skillName}-${String(ordinal).padStart(3, '0')}`
+    const record = {
+      id,
+      ordinal,
+      destination: destination.replaceAll('\\', '/'),
+      sha256: hash(raw),
+      lines: lineCount(raw),
+      heading: headingOf(raw, skillName),
+    }
+    chunkRecords.push(record)
+    ordinal += 1
+    return `<!-- microi-progressive:chunk id=${id} sha256=${record.sha256} -->${eol}${raw}<!-- /microi-progressive:chunk -->${eol}`
+  }
+
+  const entryChunks = kept.map((section) => wrapChunk(section.raw, `${skillName}/SKILL.md`)).join('')
+  const referenceRecords = []
+  referenceGroups.forEach((group, index) => {
+    const fileName = `progressive-${String(index + 1).padStart(2, '0')}-${slug(group[0].heading)}.md`
+    const relative = `references/${fileName}`
+    const destination = `${skillName}/${relative}`
+    const body = group.map((fragment) => wrapChunk(fragment.raw, destination)).join('')
+    const title = `# ${skillName} 详细参考 ${index + 1}${eol}${eol}`
+    const note = `> 按需读取；本文件由 SKILL.md 的原章节无损拆分。${eol}${eol}`
+    fs.writeFileSync(path.join(referencesDirectory, fileName), title + note + body, 'utf8')
+    referenceRecords.push({
+      path: relative,
+      headings: group.map((fragment) => fragment.heading),
+    })
+  })
+
+  const routerLines = [
+    '## 详细参考路由（渐进披露）',
+    '',
+    '仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。',
+    '',
+    ...referenceRecords.map((reference) =>
+      `- [${reference.path}](${reference.path})：${reference.headings.join('；')}`),
+    '',
+  ].join(eol)
+  const rewritten = prefix
+    + `<!-- microi-progressive:begin -->${eol}`
+    + entryChunks
+    + routerLines
+    + `<!-- microi-progressive:end -->${eol}`
+  if (lineCount(rewritten) > maxEntryLines) {
+    throw new Error(`${skillName} entry remains ${lineCount(rewritten)} lines; lower keepBudgetLines`)
+  }
+  fs.writeFileSync(skillPath, rewritten, 'utf8')
+
+  manifest.skills[skillName] = {
+    originalSha256: hash(original),
+    originalLines: lineCount(original),
+    prefixSha256: hash(prefix),
+    prefixBytes: Buffer.byteLength(prefix),
+    entryLines: lineCount(rewritten),
+    chunks: chunkRecords,
+    references: referenceRecords,
+  }
+}
+
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+console.log(`Optimized ${Object.keys(manifest.skills).length} skills; manifest: ${manifestPath}`)

package/skills/scripts/refresh-progressive-disclosure.mjs

@@ -0,0 +1,64 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const skillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const manifestPath = path.join(skillsRoot, '.progressive-disclosure-manifest.json')
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+const requested = process.argv.slice(2)
+if (requested.length === 0) {
+  throw new Error('Pass each intentionally changed skill name explicitly.')
+}
+const hash = (value) => crypto.createHash('sha256').update(value).digest('hex')
+
+for (const skillName of requested) {
+  const skill = manifest.skills[skillName]
+  if (!skill) throw new Error(`${skillName} is not a progressive-disclosure skill`)
+  const sources = new Map()
+  const entryPath = path.join(skillsRoot, skillName, 'SKILL.md')
+  sources.set(`${skillName}/SKILL.md`, fs.readFileSync(entryPath, 'utf8'))
+  for (const reference of skill.references) {
+    const destination = `${skillName}/${reference.path}`
+    sources.set(destination, fs.readFileSync(path.join(skillsRoot, destination), 'utf8'))
+  }
+
+  const ordered = []
+  for (const chunk of skill.chunks) {
+    let source = sources.get(chunk.destination)
+    const openPattern = new RegExp(`<!-- microi-progressive:chunk id=${chunk.id} sha256=[a-f0-9]{64} -->`)
+    const match = source.match(openPattern)
+    if (!match) throw new Error(`${skillName}: missing chunk ${chunk.id}`)
+    const markerStart = match.index
+    const markerEnd = markerStart + match[0].length
+    const contentStart = markerEnd + (source.startsWith('\r\n', markerEnd) ? 2 : 1)
+    const close = '<!-- /microi-progressive:chunk -->'
+    const contentEnd = source.indexOf(close, contentStart)
+    const raw = source.slice(contentStart, contentEnd)
+    const digest = hash(raw)
+    source = source.slice(0, markerStart)
+      + `<!-- microi-progressive:chunk id=${chunk.id} sha256=${digest} -->`
+      + source.slice(markerEnd)
+    sources.set(chunk.destination, source)
+    chunk.sha256 = digest
+    chunk.lines = raw.split(/\r?\n/).length
+    ordered[chunk.ordinal] = raw
+  }
+
+  for (const [destination, source] of sources) {
+    fs.writeFileSync(path.join(skillsRoot, destination), source, 'utf8')
+  }
+  const entry = sources.get(`${skillName}/SKILL.md`)
+  const begin = entry.indexOf('<!-- microi-progressive:begin -->')
+  const prefix = entry.slice(0, begin)
+  skill.prefixSha256 = hash(prefix)
+  skill.prefixBytes = Buffer.byteLength(prefix)
+  skill.originalSha256 = hash(prefix + ordered.join(''))
+  skill.originalLines = (prefix + ordered.join('')).split(/\r?\n/).length
+  skill.entryLines = entry.split(/\r?\n/).length
+}
+
+manifest.generatedAt = new Date().toISOString()
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+console.log(`Accepted intentional knowledge updates for: ${requested.join(', ')}`)
+

package/skills/scripts/validate-progressive-disclosure.mjs

@@ -0,0 +1,52 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const skillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const manifest = JSON.parse(fs.readFileSync(path.join(skillsRoot, '.progressive-disclosure-manifest.json'), 'utf8'))
+const hash = (value) => crypto.createHash('sha256').update(value).digest('hex')
+const lineCount = (value) => value.length === 0 ? 0 : value.split(/\r?\n/).length
+
+let checkedChunks = 0
+for (const [skillName, skill] of Object.entries(manifest.skills)) {
+  const entryPath = path.join(skillsRoot, skillName, 'SKILL.md')
+  const entry = fs.readFileSync(entryPath, 'utf8')
+  const begin = entry.indexOf('<!-- microi-progressive:begin -->')
+  if (begin < 0) throw new Error(`${skillName}: missing progressive begin marker`)
+  const prefix = entry.slice(0, begin)
+  if (hash(prefix) !== skill.prefixSha256) throw new Error(`${skillName}: entry prefix changed`)
+  if (lineCount(entry) > manifest.policy.maxEntryLines) throw new Error(`${skillName}: entry exceeds line budget`)
+
+  const sources = new Map([[`${skillName}/SKILL.md`, entry]])
+  for (const reference of skill.references) {
+    const relative = `${skillName}/${reference.path}`
+    const content = fs.readFileSync(path.join(skillsRoot, relative), 'utf8')
+    if (lineCount(content) > 300) throw new Error(`${relative}: reference exceeds 300 lines`)
+    sources.set(relative, content)
+  }
+
+  const ordered = []
+  for (const chunk of skill.chunks) {
+    const source = sources.get(chunk.destination)
+    if (source == null) throw new Error(`${skillName}: missing ${chunk.destination}`)
+    const open = `<!-- microi-progressive:chunk id=${chunk.id} sha256=${chunk.sha256} -->`
+    const startMarker = source.indexOf(open)
+    if (startMarker < 0) throw new Error(`${skillName}: missing chunk ${chunk.id}`)
+    const contentStart = startMarker + open.length + (source.startsWith('\r\n', startMarker + open.length) ? 2 : 1)
+    const close = '<!-- /microi-progressive:chunk -->'
+    const contentEnd = source.indexOf(close, contentStart)
+    if (contentEnd < 0) throw new Error(`${skillName}: unterminated chunk ${chunk.id}`)
+    const raw = source.slice(contentStart, contentEnd)
+    if (hash(raw) !== chunk.sha256) throw new Error(`${skillName}: chunk ${chunk.id} changed`)
+    ordered[chunk.ordinal] = raw
+    checkedChunks += 1
+  }
+  const reconstructed = prefix + ordered.join('')
+  if (hash(reconstructed) !== skill.originalSha256) {
+    throw new Error(`${skillName}: reconstructed knowledge differs from original`)
+  }
+}
+
+console.log(`Validated ${Object.keys(manifest.skills).length} skills and ${checkedChunks} lossless chunks.`)
+