@microi.net/cli 5.5.9 → 5.6.1

package/skills/production-readonly-audit/SKILL.md

@@ -1,41 +1,41 @@
----
-name: production-readonly-audit
-description: Microi 正式环境只读业务巡检规范。用于在不改动线上数据的前提下，检查会员、余额、订单、库存卡、奖励、积分、兑换金额、日志和结算正确性等生产业务数据。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 正式环境只读业务巡检
-
-## 核心边界
-
-- 正式环境已有真实用户、余额、订单、卡券或收益数据时，线上巡检默认是只读任务。
-- 优先使用目标租户 MCP 的读表、查结构、查日志工具；不得调用新增、更新、删除、清库、重算、补发、扣减接口。
-- 如果用户要求“检查是否正常”，先输出异常证据、影响范围、建议修复方式和回读验证方式；没有明确授权前，不修线上业务数据。
-- MCP 不可用时，可使用官方后台登录 token + FormEngine `getTableData` 做只读兜底，但必须在结果中说明“非 MCP，只读 API 兜底”；不得调用 `add/upt/del/run` 维护接口。
-- 任何资金/资产异常即使明显，也只能先报告。获得修复授权后，必须小范围条件更新，并在方案文档留下 SQL/接口说明、执行时间、影响行数和回读结果。
-
-## 商城类固定巡检表
-
-- 会员与团队：`mall_member`
-- 提货卡与挂单：`mall_stock_card`、`mall_stock_card_listing`
-- 抢购/约单/商品订单：`mall_buy_order`、`mall_appointment_order`、`mall_redeem_order`
-- 积分/兑换金/奖励：`mall_point_log`、`mall_redeem_money_log`、`mall_reward_log`
-- 上架服务费：`mall_storage_fee_order`
-- 提货卡扣除/流转：`mall_stock_card_redeem`、`mall_stock_card_history`
-- 规则配置：`mall_system_config`
-
-## 固定检查项
-
-- 提货卡：`CardNo` 必须为 6 位大写字母+数字；金额不得为负；`OwnerId` 必须存在；同一卡只能有一条活跃挂单；状态机必须和挂单/订单一致。
-- 抢购订单：`PendingPay` 必须有关联锁定卡与付款截止时间；`Paid` 必须有支付凭证和付款时间；`Confirmed/Completed` 必须确认卡 OwnerId 已转为 BuyerId，并有对应流转历史。
-- 上架服务费：服务费应等于持有价 × `PlatformServiceRate`；已支付服务费必须有对应负数积分流水。
-- 推荐奖励：`Amount = BaseAmount × Rate / 100`；直推、间推、品牌补贴合计不得超过 `MaxPerformanceCommissionRate`；`Pending` 不得生成积分流水或增加余额；`Settled` 必须有积分流水并真实到账。
-- 商品支付：提货卡专区订单必须生成 `mall_stock_card_redeem` 并扣卡余额；兑换金专区订单必须生成负数 `mall_redeem_money_log` 并扣兑换金。
-- 会员资产：会员页展示的提货卡资产应以当前名下有效提货卡 `HoldPrice/StockValue` 汇总为准；如 `mall_member.StockValue` 是冗余字段，必须与实际资产保持一致。
-
-## 输出要求
-
-- 报告必须区分“硬错误”和“风险警告”。
-- 不输出密码、token、支付凭证图片原文、完整身份证等敏感信息。
-- 报告需包含巡检通道、读取表数量、状态分布、异常数量、核心异常证据、未覆盖范围。
+---
+name: production-readonly-audit
+description: Microi 正式环境只读业务巡检规范。用于在不改动线上数据的前提下，检查会员、余额、订单、库存卡、奖励、积分、兑换金额、日志和结算正确性等生产业务数据。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 正式环境只读业务巡检
+
+## 核心边界
+
+- 正式环境已有真实用户、余额、订单、卡券或收益数据时，线上巡检默认是只读任务。
+- 优先使用目标租户 MCP 的读表、查结构、查日志工具；不得调用新增、更新、删除、清库、重算、补发、扣减接口。
+- 如果用户要求“检查是否正常”，先输出异常证据、影响范围、建议修复方式和回读验证方式；没有明确授权前，不修线上业务数据。
+- MCP 不可用时，可使用官方后台登录 token + FormEngine `getTableData` 做只读兜底，但必须在结果中说明“非 MCP，只读 API 兜底”；不得调用 `add/upt/del/run` 维护接口。
+- 任何资金/资产异常即使明显，也只能先报告。获得修复授权后，必须小范围条件更新，并在方案文档留下 SQL/接口说明、执行时间、影响行数和回读结果。
+
+## 商城类固定巡检表
+
+- 会员与团队：`mall_member`
+- 提货卡与挂单：`mall_stock_card`、`mall_stock_card_listing`
+- 抢购/约单/商品订单：`mall_buy_order`、`mall_appointment_order`、`mall_redeem_order`
+- 积分/兑换金/奖励：`mall_point_log`、`mall_redeem_money_log`、`mall_reward_log`
+- 上架服务费：`mall_storage_fee_order`
+- 提货卡扣除/流转：`mall_stock_card_redeem`、`mall_stock_card_history`
+- 规则配置：`mall_system_config`
+
+## 固定检查项
+
+- 提货卡：`CardNo` 必须为 6 位大写字母+数字；金额不得为负；`OwnerId` 必须存在；同一卡只能有一条活跃挂单；状态机必须和挂单/订单一致。
+- 抢购订单：`PendingPay` 必须有关联锁定卡与付款截止时间；`Paid` 必须有支付凭证和付款时间；`Confirmed/Completed` 必须确认卡 OwnerId 已转为 BuyerId，并有对应流转历史。
+- 上架服务费：服务费应等于持有价 × `PlatformServiceRate`；已支付服务费必须有对应负数积分流水。
+- 推荐奖励：`Amount = BaseAmount × Rate / 100`；直推、间推、品牌补贴合计不得超过 `MaxPerformanceCommissionRate`；`Pending` 不得生成积分流水或增加余额；`Settled` 必须有积分流水并真实到账。
+- 商品支付：提货卡专区订单必须生成 `mall_stock_card_redeem` 并扣卡余额；兑换金专区订单必须生成负数 `mall_redeem_money_log` 并扣兑换金。
+- 会员资产：会员页展示的提货卡资产应以当前名下有效提货卡 `HoldPrice/StockValue` 汇总为准；如 `mall_member.StockValue` 是冗余字段，必须与实际资产保持一致。
+
+## 输出要求
+
+- 报告必须区分“硬错误”和“风险警告”。
+- 不输出密码、token、支付凭证图片原文、完整身份证等敏感信息。
+- 报告需包含巡检通道、读取表数量、状态分布、异常数量、核心异常证据、未覆盖范围。

package/skills/report-engine/SKILL.md

@@ -1,71 +1,71 @@
----
-name: report-engine
-description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 报表引擎
-
-## 定位
-
-报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
-
-## 建模顺序
-
-1. 明确指标口径、时间粒度、维度、权限和导出上限。
-2. 创建只读数据源（SQL/V8/JSON），使用稳定 `DataSourceKey`。
-3. 创建报表并绑定数据源。
-4. 配置字段 `Name/Label/Component`、查询列、排序、格式和表内编辑。
-5. 如需写操作，为查询/新增/修改/删除分别绑定专用接口引擎。
-6. 菜单只暴露用户需要的报表入口，配置数据范围。
-
-## 权限与 SQL
-
-- 报表数据源必须应用当前租户和服务端用户数据范围。菜单权限不会自动保护任意聚合 SQL。
-- 聚合结果也可能泄露敏感信息；小样本、人员薪资、客户金额等需最小分组阈值或字段脱敏。
-- SQL 动态值参数化，维度/排序/指标使用白名单映射，不接收原始 SQL、列名或 `GROUP BY`。
-- 管理员专用平台表不能作为普通用户报表数据源；只读委托表只有获得真实 `Read` 授权后才能查询，`mic_page/mic_print` 继续按角色权限处理。
-
-## 写入型报表
-
-统计报表通常来自多表。新增、修改、删除必须调用接口引擎，在一个事务中完成校验与写入：
-
-```js
-var result = await V8.ApiEngine.Run('report_adjust_inventory', {
-  RowId: V8.Form.Id,
-  ExpectedVersion: V8.Form.Version,
-  Quantity: Number(V8.Form.Quantity || 0)
-});
-```
-
-接口引擎重新校验角色、记录范围、当前版本和业务状态。前端隐藏按钮、只读字段或报表行数据不能作为授权。
-
-## 性能
-
-- 默认分页，限制最大页数/每页行数/导出行数。
-- 大聚合在数据库建立合适索引或使用预聚合表；不要每次全表扫描。
-- 缓存 Key 包含 `OsClient + ReportId + 权限主体/授权版本 + 查询参数哈希`。
-- 导出走后台任务；生成文件放私有桶并绑定菜单、记录和字段访问上下文。
-
-## MCP 工作流
-
-1. `microi_get_db_schema` 读取 `Rpt_Report`、数据源、字段、菜单和业务表。
-2. `microi_save_data_source` 保存数据源并回读。
-3. 创建/更新报表及字段；复杂写操作先创建接口引擎。
-4. 设置菜单与角色权限。
-5. 用真实普通角色验收列表、筛选、汇总、详情、编辑与导出。
-
-## 图表
-
-界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
-
-## 验收清单
-
-- [ ] 指标口径、时区和小数精度明确
-- [ ] 当前租户与行级范围在数据库查询中生效
-- [ ] 虚拟字段与物理字段没有混用
-- [ ] 写操作走事务接口引擎并校验并发版本
-- [ ] 分页、聚合、导出均有资源上限
-- [ ] 缓存按租户和权限隔离
-- [ ] 普通角色、无权限角色、跨租户负向测试通过
+---
+name: report-engine
+description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 报表引擎
+
+## 定位
+
+报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
+
+## 建模顺序
+
+1. 明确指标口径、时间粒度、维度、权限和导出上限。
+2. 创建只读数据源（SQL/V8/JSON），使用稳定 `DataSourceKey`。
+3. 创建报表并绑定数据源。
+4. 配置字段 `Name/Label/Component`、查询列、排序、格式和表内编辑。
+5. 如需写操作，为查询/新增/修改/删除分别绑定专用接口引擎。
+6. 菜单只暴露用户需要的报表入口，配置数据范围。
+
+## 权限与 SQL
+
+- 报表数据源必须应用当前租户和服务端用户数据范围。菜单权限不会自动保护任意聚合 SQL。
+- 聚合结果也可能泄露敏感信息；小样本、人员薪资、客户金额等需最小分组阈值或字段脱敏。
+- SQL 动态值参数化，维度/排序/指标使用白名单映射，不接收原始 SQL、列名或 `GROUP BY`。
+- 管理员专用平台表不能作为普通用户报表数据源；只读委托表只有获得真实 `Read` 授权后才能查询，`mic_page/mic_print` 继续按角色权限处理。
+
+## 写入型报表
+
+统计报表通常来自多表。新增、修改、删除必须调用接口引擎，在一个事务中完成校验与写入：
+
+```js
+var result = await V8.ApiEngine.Run('report_adjust_inventory', {
+  RowId: V8.Form.Id,
+  ExpectedVersion: V8.Form.Version,
+  Quantity: Number(V8.Form.Quantity || 0)
+});
+```
+
+接口引擎重新校验角色、记录范围、当前版本和业务状态。前端隐藏按钮、只读字段或报表行数据不能作为授权。
+
+## 性能
+
+- 默认分页，限制最大页数/每页行数/导出行数。
+- 大聚合在数据库建立合适索引或使用预聚合表；不要每次全表扫描。
+- 缓存 Key 包含 `OsClient + ReportId + 权限主体/授权版本 + 查询参数哈希`。
+- 导出走后台任务；生成文件放私有桶并绑定菜单、记录和字段访问上下文。
+
+## MCP 工作流
+
+1. `microi_get_db_schema` 读取 `Rpt_Report`、数据源、字段、菜单和业务表。
+2. `microi_save_data_source` 保存数据源并回读。
+3. 创建/更新报表及字段；复杂写操作先创建接口引擎。
+4. 设置菜单与角色权限。
+5. 用真实普通角色验收列表、筛选、汇总、详情、编辑与导出。
+
+## 图表
+
+界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
+
+## 验收清单
+
+- [ ] 指标口径、时区和小数精度明确
+- [ ] 当前租户与行级范围在数据库查询中生效
+- [ ] 虚拟字段与物理字段没有混用
+- [ ] 写操作走事务接口引擎并校验并发版本
+- [ ] 分页、聚合、导出均有资源上限
+- [ ] 缓存按租户和权限隔离
+- [ ] 普通角色、无权限角色、跨租户负向测试通过

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}`)