@microi.net/cli 5.9.4 → 5.9.6

package/skills/playwright-e2e/SKILL.md

@@ -38,7 +38,7 @@ description: 按 Microi 系统真实业务逻辑进行 Playwright 全自动化
 不适合把 Playwright 用来替代 V8 单函数调试。单个接口引擎的入参输出优先用 VS Code 插件远程执行、MCP `microi_run_engine` 或后端单元测试。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=playwright-e2e-002 sha256=2e92ff117b1c3b450e988776204ccecd9dd4d6a83bb08d86d32032b467abc174 -->
+<!-- microi-progressive:chunk id=playwright-e2e-002 sha256=5874137c92e16fd5cc729fd9c23d051caa3e64438fc7bee1d717ae9c5a0f2a90 -->
 ## 临时文件与产物放置规则（必须遵守）
 
 AI 在工作区内生成的**一次性临时脚本、诊断文件、截图、测试报告**等，**绝对不能放在工作区根目录**，必须放在以下指定位置：
@@ -54,7 +54,7 @@ AI 在工作区内生成的**一次性临时脚本、诊断文件、截图、测
 
 **禁止在根目录创建的文件类型**：`*.mjs`、`*.py`、`*.ps1`、`*.sh`（一次性脚本）、`*.png`、`screenshots/`、`node_modules/`（无 package.json 时）、`obj/`（非 .NET 项目文件）、`dark-mode-*/`、`test-*/` 等临时目录。
 
-`.tmp/` 目录已在 `.gitignore` 中排除，AI 可以在此自由创建临时文件。任务完成后如无价值可以不清理，也可以整体删除该目录。
+`.tmp/` 目录已在 `.gitignore` 中排除，AI 可以在此创建临时文件。收尾清理只允许针对已确认归属的本任务子目录；删除前核对解析后的绝对路径、所有权和保留价值，不得整体删除共享 `.tmp/` 或其它任务的产物。临时文件保留不等于允许保留测试进程或容器。
 
 **2026-06 强制补充**：AI 手写的一次性 Playwright 验证脚本、运行日志、截图和报告只能写到工作区根目录 `.tmp/`。不要写到 `Microi.Client/`、`Microi.Server/`、`microi.doc/` 或其它子项目目录，即使这些目录已有 `tests/` 目录也不例外。只有 Microi.Agent 插件正式初始化的可复用 E2E 工程，才使用 `.microi-e2e/`。
 
@@ -140,20 +140,21 @@ PW_HOME_PATH=/#/pages/index/index
 不要只说“代码已编译”或“需要用户自己重启后端”；除非用户明确要求不要中断当前服务，否则 AI 要主动完成重启。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=playwright-e2e-007 sha256=6d285a719a85ce3f2c887b292c08cc69d9632964c341269f0f61bb2fdc403fac -->
+<!-- microi-progressive:chunk id=playwright-e2e-007 sha256=ee40e4f023e1da07269f9ebb82522720c4f014cfc9500885db09778dd819b9a6 -->
 ## 服务自启动纪律（必做）
 
 执行自动化测试、截图巡检、接口引擎回读、`/apiengine/{key}` 验收时，如果本地后端或前端不可达，不能把 `fetch failed`、`ECONNREFUSED`、`000 Failed to connect`、端口无人监听当作任务终点。必须先自动启动所需服务，再继续完整验证。
 
 同一工作区有多个 AI 对话时，服务自启动还必须遵守共享生命周期：
 
+- 先执行 `../workspace-conventions/SKILL.md` 的“本地测试程序与依赖生命周期”统一规则：优先复用健康的本地源码程序、隔离目录中的编译产物和同组既有依赖，不按测试任务重复创建 Docker/Compose。需要双节点时启动两个本机程序进程连接同组依赖，不等于建立两套 Docker 环境。
 - API 服务启动前执行 `node Microi.Server/tools/release-lock.mjs assert api <工作区根>`，PC 服务使用 `assert pc`。Playwright `webServer`、自愈脚本或 AI 只在对应范围发布时等待；官网/Agent 发布不阻塞 `61500/61501`。同时启动前后端时分别检查两项。旧锁仅在真实进程证明所属范围后缩小阻塞范围，未知锁继续保护，不得删除活跃锁。
 - 端口健康且 PID/命令行属于当前工作区时直接复用，不得每个对话都无条件“先杀再启动”。
   必须重载源码时才串行重启，并在状态播报中说明旧/新 PID。
 - 本地长期后端使用项目目录中的 `dotnet run --launch-profile Microi.net.Api`，禁止把
   `bin/Release/net10.0` 或 `bin/Release/publish` 的 DLL 作为长期测试服务，否则会锁住
   一键发布的 Release 输出。
-- 一次性测试要关闭自己创建的 browser/context 和临时 webServer。VS Code 持有的
+- 每次测试成功、失败、取消或因资源不足暂停时，都必须结束本次创建的 browser/context、临时 webServer 及其它自有测试进程；按统一规则收回新建临时容器，并独立回读进程、监听端口和容器状态确认无残留。复用的既有共享服务保持原状。VS Code 持有的
   `playwright test-server` 与用户 Edge/Chrome 不属于孤儿清理；禁止按进程名结束所有
   `node/dotnet/chrome/msedge`。
 - 只读盘点或精确停止使用 `Microi.Server/tools/Microi.LocalProcessManager.ps1` 的

package/skills/playwright-e2e/references/progressive-03-microi-helper-/346/250/241/346/235/277.md

@@ -134,7 +134,7 @@ test('公开接口引擎返回标准 DosResult', async ({ request }) => {
 6. 退出登录能清理 Token 并回到登录页。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=playwright-e2e-020 sha256=a267a39f5fe3dab714c5275759f7bdd1b6150990fa00555e07c091aee5795a29 -->
+<!-- microi-progressive:chunk id=playwright-e2e-020 sha256=63b5c2374f7e011a927ebd751d01c50e2d54d9e746d4d47ddd1665779a4487b9 -->
 ## 完整业务验收门槛
 
 当用户要求“完整测试”“全面测试”“不要让我手工测出接口 null/404/权限漏洞”时，不能只生成浅冒烟。至少补齐以下测试文件：
@@ -157,9 +157,9 @@ tests/e2e/
 4. UI 点击不能只断言 toast；必须用 `page.waitForResponse()` 捕捉对应接口，并验证响应体。
 5. 任何 FormEngine HTTP 路由必须使用 `/api/formengine/{action}-{table}`，不要生成 `/formengine/{table}/{action}`。
 6. ApiEngine 使用稳定路径 `/apiengine/{ApiEngineKey}`，并通过唯一的 `osclient` Header 传租户；JSON/Form Body 可冗余携带 `OsClient`。普通 POST/PUT/PATCH/DELETE 禁止追加 `--OsClient--...--`。仅第三方回调或无法设置 Header/Form/Query 的 GET/HEAD 才允许特殊路径。
-7. 页面级测试必须把 `请求失败`、`网络错误`、`null`、`待开发`、`开发中` 当成失败信号；这些文案如果出现在页面或 toast 中，说明功能未交付或接口契约错误。
+7. 最终业务页面级测试必须把 `请求失败`、`网络错误`、`null`、`待开发`、`开发中` 当成失败信号；最终菜单入口或业务 toast 出现占位文案仍表示未交付。菜单骨架阶段另用专门用例验收共享开发中页的菜单身份、布局、动画和权限，该阶段允许预期占位文案，但不算业务功能交付通过，不能套用此例外放过最终业务页面。
 8. 新增、保存、结算、转赠、确认、上传等按钮不能只弹“成功/待开发”toast；必须调用真实业务接口，并通过后端查询验证状态变化。
-9. 源码守卫可作为兜底：递归扫描 `src/**/*.vue`、`src/**/*.js`，禁止残留 `待开发|开发中` 占位文案。
+9. 源码守卫可作为兜底：递归扫描最终业务源码 `src/**/*.vue`、`src/**/*.js`，禁止残留 `待开发|开发中` 占位文案。平台共享 `Microi.Client/src/views/ai-engine/developing.vue` 及其专门占位验收用例可以按已核验的精确文件加入白名单；不得排除整个 `ai-engine`、`src` 或业务目录，也不得用源码白名单豁免最终菜单仍指向占位页的失败。
 10. 新建或更新 ApiEngine 后必须用 HTTP 路径复测一次；只用 `microi_run_engine` 通过不够，因为 HTTP 调用还受 `IsEnable`、`StopHttp`、`AllowAnonymous` 和动态路由缓存影响。
 11. 每个移动端项目都要有“接口清单驱动”的契约测试：静态扫描或维护清单覆盖所有 `callEngine('xxx')`，逐个 HTTP 调用并断言不是 404、不是空响应、不是字符串 `null`，且必须是标准 DosResult。
 12. 写业务闭环时必须准备可重复测试数据并清理：例如抢购要“创建测试挂单 → 调用抢购 → 验证订单 → 删除测试订单/挂单/提货卡”，购物车要“加入购物车 → 结算 → 验证订单/购物车状态 → 删除测试订单”。

package/skills/report-engine/SKILL.md

@@ -11,6 +11,12 @@ description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟
 
 报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
 
+完整 AI 系统开发默认必须交付需求相关的业务统计、老板经营、领导管理报表。
+这些决策看板基于界面引擎，读取 `../page-engine/SKILL.md`；本报表引擎负责其分页明细、
+查询汇总表与导出，不能用一个虚拟表格或列表角标代替全部看板。菜单骨架、占位切换和指标
+范围统一读取[菜单先行与经营报表增补要求](../microi-system-delivery/references/progressive-01-标准工作流.md#菜单先行与经营报表增补要求强制)。
+局部修改限相关报表，只读分析不写资源；完整开发不等于生产写入授权。
+
 ## 建模顺序
 
 1. 明确指标口径、时间粒度、维度、权限和导出上限。
@@ -60,6 +66,11 @@ var result = await V8.ApiEngine.Run('report_adjust_inventory', {
 
 界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
 
+与看板配套的明细/导出必须共享指标公式、业务状态、时间字段/时区/区间边界、比较基期和
+部门/人员/项目等筛选条件。聚合与穿透明细分别执行当前租户和用户数据权限，不能信任前端
+带来的老板/领导角色或任意字段名。真实零值、没有数据、未配置来源与查询失败分别表达；
+不能把失败转成成功零值。用同一筛选的明细合计独立核对看板数值，确无明细的汇总注明限制。
+
 ## 验收清单
 
 - [ ] 指标口径、时区和小数精度明确
@@ -69,3 +80,4 @@ var result = await V8.ApiEngine.Run('report_adjust_inventory', {
 - [ ] 分页、聚合、导出均有资源上限
 - [ ] 缓存按租户和权限隔离
 - [ ] 普通角色、无权限角色、跨租户负向测试通过
+- [ ] 配套界面引擎看板与穿透明细/导出使用同一口径，时间边界、筛选、零/空/失败及明细对账通过

package/skills/report-engine/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "报表引擎"
-  short_description: "设计遵守菜单与行级权限的报表、聚合接口、写操作与导出验收"
-  default_prompt: "使用 $report-engine 设计并验收当前 Microi 报表。"
+interface:
+  display_name: "报表引擎"
+  short_description: "设计遵守菜单与行级权限的报表、聚合接口、写操作与导出验收"
+  default_prompt: "使用 $report-engine 设计并验收当前 Microi 报表。"

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

@@ -1,204 +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}`)
+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

@@ -1,64 +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(', ')}`)
-
+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(', ')}`)
+