@microi.net/cli 5.9.2 → 5.9.3

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

package/skills/scripts/sync-embedded-skills.mjs

@@ -1,46 +1,46 @@
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// 后端只持有自包含的知识快照；规则正文仍以 microi.skills 为唯一可编辑事实源。
-const skillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const serverRoot = path.resolve(skillsRoot, '../Microi.Server/Microi.AI');
-const project = fs.readFileSync(path.join(serverRoot, 'Microi.AI.csproj'), 'utf8');
-const manifest = JSON.parse(fs.readFileSync(path.join(skillsRoot, '.progressive-disclosure-manifest.json'), 'utf8'));
-const check = process.argv.includes('--check');
-const names = process.argv.slice(2).filter(value => value !== '--check');
-if (!names.length) throw new Error('请显式指定本次需要同步的 Skill 名称。');
-const stripMarkers = text => text.replace(/<!--\s*\/?microi-progressive:[^>]*-->\r?\n?/g, '');
-const digest = text => crypto.createHash('sha256').update(text).digest('hex');
-const results = [];
-
-for (const name of names) {
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`无效 Skill 名称：${name}`);
-  const file = `skill-${name}.md`;
-  // 不擅自新增程序集资源；只有现有项目明确注册的知识快照可以由此脚本刷新。
-  if (!project.includes(`Resource\\${file}`)) throw new Error(`后端尚未注册 ${file}，请先审阅资源归属。`);
-  let text = fs.readFileSync(path.join(skillsRoot, name, 'SKILL.md'), 'utf8');
-  const references = manifest.skills[name]?.references || [];
-  if (references.length) {
-    const route = text.indexOf('## 详细参考路由（渐进披露）');
-    const end = text.indexOf('<!-- microi-progressive:end -->', route);
-    if (route < 0 || end < route) throw new Error(`${name} 缺少受控参考路由，停止覆盖快照。`);
-    text = text.slice(0, route) + text.slice(end + '<!-- microi-progressive:end -->'.length);
-    for (const reference of references) {
-      const source = path.resolve(skillsRoot, name, reference.path);
-      const relative = path.relative(path.join(skillsRoot, name), source);
-      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('参考文件越过 Skill 目录。');
-      // 平台 AI 读取程序集时不能打开工作区相对路径，必须带上渐进参考的完整正文。
-      text += `\n\n${fs.readFileSync(source, 'utf8')}`;
-    }
-  }
-  text = `${stripMarkers(text).replace(/\r\n/g, '\n').trimEnd()}\n`;
-  const target = path.join(serverRoot, 'Resource', file);
-  const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
-  const changed = before.replace(/\r\n/g, '\n') !== text;
-  if (changed && !check) fs.writeFileSync(target, text, 'utf8');
-  results.push({ name, changed, sha256: digest(text) });
-}
-console.log(JSON.stringify({ check, results }, null, 2));
-if (check && results.some(item => item.changed)) process.exitCode = 1;
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// 后端只持有自包含的知识快照；规则正文仍以 microi.skills 为唯一可编辑事实源。
+const skillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const serverRoot = path.resolve(skillsRoot, '../Microi.Server/Microi.AI');
+const project = fs.readFileSync(path.join(serverRoot, 'Microi.AI.csproj'), 'utf8');
+const manifest = JSON.parse(fs.readFileSync(path.join(skillsRoot, '.progressive-disclosure-manifest.json'), 'utf8'));
+const check = process.argv.includes('--check');
+const names = process.argv.slice(2).filter(value => value !== '--check');
+if (!names.length) throw new Error('请显式指定本次需要同步的 Skill 名称。');
+const stripMarkers = text => text.replace(/<!--\s*\/?microi-progressive:[^>]*-->\r?\n?/g, '');
+const digest = text => crypto.createHash('sha256').update(text).digest('hex');
+const results = [];
+
+for (const name of names) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`无效 Skill 名称：${name}`);
+  const file = `skill-${name}.md`;
+  // 不擅自新增程序集资源；只有现有项目明确注册的知识快照可以由此脚本刷新。
+  if (!project.includes(`Resource\\${file}`)) throw new Error(`后端尚未注册 ${file}，请先审阅资源归属。`);
+  let text = fs.readFileSync(path.join(skillsRoot, name, 'SKILL.md'), 'utf8');
+  const references = manifest.skills[name]?.references || [];
+  if (references.length) {
+    const route = text.indexOf('## 详细参考路由（渐进披露）');
+    const end = text.indexOf('<!-- microi-progressive:end -->', route);
+    if (route < 0 || end < route) throw new Error(`${name} 缺少受控参考路由，停止覆盖快照。`);
+    text = text.slice(0, route) + text.slice(end + '<!-- microi-progressive:end -->'.length);
+    for (const reference of references) {
+      const source = path.resolve(skillsRoot, name, reference.path);
+      const relative = path.relative(path.join(skillsRoot, name), source);
+      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('参考文件越过 Skill 目录。');
+      // 平台 AI 读取程序集时不能打开工作区相对路径，必须带上渐进参考的完整正文。
+      text += `\n\n${fs.readFileSync(source, 'utf8')}`;
+    }
+  }
+  text = `${stripMarkers(text).replace(/\r\n/g, '\n').trimEnd()}\n`;
+  const target = path.join(serverRoot, 'Resource', file);
+  const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+  const changed = before.replace(/\r\n/g, '\n') !== text;
+  if (changed && !check) fs.writeFileSync(target, text, 'utf8');
+  results.push({ name, changed, sha256: digest(text) });
+}
+console.log(JSON.stringify({ check, results }, null, 2));
+if (check && results.some(item => item.changed)) process.exitCode = 1;

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

@@ -1,57 +1,57 @@
-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
-
-// 可只验证显式修改的 Skill；默认仍检查全库，不能为并行工作区的历史漂移改写共同基线。
-const requested = process.argv.slice(2)
-for (const name of requested) {
-  if (!Object.hasOwn(manifest.skills, name)) throw new Error(`Unknown progressive-disclosure skill: ${name}`)
-}
-const selected = Object.entries(manifest.skills).filter(([name]) => requested.length === 0 || requested.includes(name))
-let checkedChunks = 0
-for (const [skillName, skill] of selected) {
-  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 ${selected.length} skills and ${checkedChunks} lossless chunks${requested.length ? ' (explicit scope)' : ''}.`)
+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
+
+// 可只验证显式修改的 Skill；默认仍检查全库，不能为并行工作区的历史漂移改写共同基线。
+const requested = process.argv.slice(2)
+for (const name of requested) {
+  if (!Object.hasOwn(manifest.skills, name)) throw new Error(`Unknown progressive-disclosure skill: ${name}`)
+}
+const selected = Object.entries(manifest.skills).filter(([name]) => requested.length === 0 || requested.includes(name))
+let checkedChunks = 0
+for (const [skillName, skill] of selected) {
+  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 ${selected.length} skills and ${checkedChunks} lossless chunks${requested.length ? ' (explicit scope)' : ''}.`)

package/skills/search-engine/SKILL.md

@@ -1,75 +1,75 @@
----
-name: search-engine
-description: Microi 搜索引擎索引、同步、查询与安全规范。用于 Elasticsearch 表索引、增量同步、字段映射、SearchAfter 分页、租户与菜单数据范围、重建和多节点验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi SearchEngine
-
-## 能力与事实源
-
-搜索引擎提供建索引/全量同步、单文档新增修改删除、字段映射、查询和 `SearchAfter` 深分页。数据库仍是业务事实源，搜索索引是可重建的读模型，不能直接作为权限、余额、库存或审批状态事实。
-
-## 租户隔离
-
-- 索引名必须包含规范化 `OsClient` 和表标识，禁止不同租户共用无过滤索引。
-- V8/HTTP 调用的 `OsClient` 必须由 Token/服务端上下文确定，不能信任 Query/Body。
-- 搜索服务连接、用户名和密码只从服务端 SaaS 配置读取，不进入前端 `SysConfig`、V8 返回或日志。
-
-## 索引流程
-
-1. 读取 `diy_table/diy_field` 确定可搜索字段、类型和分词需求。
-2. 先扩展索引映射，再开始双写/增量同步。
-3. 全量回填使用稳定游标或主键分页，记录 checkpoint。
-4. 对账数据库数量、抽样字段和删除记录。
-5. 切换读流量后保留旧索引回滚窗口。
-
-可用的服务端方法包括 `AsyncIndex`、`AsyncTableDataToIndex`、`AddDocument`、`UpdateDocument`、`DeleteDocument`、`AddField`、`GetSearchResponse`。
-
-## 查询安全
-
-- 用户关键词作为值参数，不允许决定索引名、任意字段、脚本或原始 DSL。
-- 排序字段从白名单映射；限制 `PageSize`、高亮长度和聚合桶数量。
-- 普通用户的菜单 `SqlWhere`/行级范围不会天然出现在 Elasticsearch 查询中。必须将服务端计算出的允许记录范围同步为可过滤字段，或先取得授权 Id 集合再查询；不能搜索后再在前端过滤。
-- 敏感字段不入索引，或使用独立受控索引；日志只记录 trace id、耗时和计数。
-
-## 同步可靠性
-
-数据库写成功、索引写失败时使用 outbox 事件，`EventId` 全局唯一。消费端按事件 Id 幂等；删除使用 tombstone。索引更新失败不能回滚已经提交的业务事务，应告警并重试。
-
-全量重建和增量消费可能在多个节点同时运行，需分布式租约与 checkpoint 条件更新；本机静态标志不能作为“正在重建”的事实。
-
-## 查询示例
-
-```csharp
-var result = await search.GetSearchResponse(new MicroiSearchEngineParam
-{
-    OsClient = osClient,
-    TableName = "Diy_Product",
-    Keyword = keyword,
-    PageSize = Math.Min(pageSize, 100),
-    Sorts = new List<MicroiSearchEngineSortModel>
-    {
-        new MicroiSearchEngineSortModel { Field = "UpdateTime", Order = "desc" }
-    }
-});
-```
-
-字段名与排序必须在进入此对象前经过服务端白名单。
-
-## MCP/交付流程
-
-- 先用 `microi_get_db_schema` 和菜单元数据确认字段与权限。
-- 搜索配置写入后回读实际索引名、字段映射和租户连接。
-- 用管理员、普通有权限用户、无权限用户和另一个租户验收。
-- 覆盖全量重建中断、重复事件、删除、滚动升级、搜索服务短暂故障。
-
-## 验收清单
-
-- [ ] 索引按租户隔离，跨租户搜索为零
-- [ ] 菜单/行级范围在查询前生效
-- [ ] 字段、排序、分页、聚合均有白名单和上限
-- [ ] 数据库与索引可对账、可重建
-- [ ] outbox 重试幂等，无永久漏同步
-- [ ] 密钥和敏感字段不进入前端/日志/索引
+---
+name: search-engine
+description: Microi 搜索引擎索引、同步、查询与安全规范。用于 Elasticsearch 表索引、增量同步、字段映射、SearchAfter 分页、租户与菜单数据范围、重建和多节点验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi SearchEngine
+
+## 能力与事实源
+
+搜索引擎提供建索引/全量同步、单文档新增修改删除、字段映射、查询和 `SearchAfter` 深分页。数据库仍是业务事实源，搜索索引是可重建的读模型，不能直接作为权限、余额、库存或审批状态事实。
+
+## 租户隔离
+
+- 索引名必须包含规范化 `OsClient` 和表标识，禁止不同租户共用无过滤索引。
+- V8/HTTP 调用的 `OsClient` 必须由 Token/服务端上下文确定，不能信任 Query/Body。
+- 搜索服务连接、用户名和密码只从服务端 SaaS 配置读取，不进入前端 `SysConfig`、V8 返回或日志。
+
+## 索引流程
+
+1. 读取 `diy_table/diy_field` 确定可搜索字段、类型和分词需求。
+2. 先扩展索引映射，再开始双写/增量同步。
+3. 全量回填使用稳定游标或主键分页，记录 checkpoint。
+4. 对账数据库数量、抽样字段和删除记录。
+5. 切换读流量后保留旧索引回滚窗口。
+
+可用的服务端方法包括 `AsyncIndex`、`AsyncTableDataToIndex`、`AddDocument`、`UpdateDocument`、`DeleteDocument`、`AddField`、`GetSearchResponse`。
+
+## 查询安全
+
+- 用户关键词作为值参数，不允许决定索引名、任意字段、脚本或原始 DSL。
+- 排序字段从白名单映射；限制 `PageSize`、高亮长度和聚合桶数量。
+- 普通用户的菜单 `SqlWhere`/行级范围不会天然出现在 Elasticsearch 查询中。必须将服务端计算出的允许记录范围同步为可过滤字段，或先取得授权 Id 集合再查询；不能搜索后再在前端过滤。
+- 敏感字段不入索引，或使用独立受控索引；日志只记录 trace id、耗时和计数。
+
+## 同步可靠性
+
+数据库写成功、索引写失败时使用 outbox 事件，`EventId` 全局唯一。消费端按事件 Id 幂等；删除使用 tombstone。索引更新失败不能回滚已经提交的业务事务，应告警并重试。
+
+全量重建和增量消费可能在多个节点同时运行，需分布式租约与 checkpoint 条件更新；本机静态标志不能作为“正在重建”的事实。
+
+## 查询示例
+
+```csharp
+var result = await search.GetSearchResponse(new MicroiSearchEngineParam
+{
+    OsClient = osClient,
+    TableName = "Diy_Product",
+    Keyword = keyword,
+    PageSize = Math.Min(pageSize, 100),
+    Sorts = new List<MicroiSearchEngineSortModel>
+    {
+        new MicroiSearchEngineSortModel { Field = "UpdateTime", Order = "desc" }
+    }
+});
+```
+
+字段名与排序必须在进入此对象前经过服务端白名单。
+
+## MCP/交付流程
+
+- 先用 `microi_get_db_schema` 和菜单元数据确认字段与权限。
+- 搜索配置写入后回读实际索引名、字段映射和租户连接。
+- 用管理员、普通有权限用户、无权限用户和另一个租户验收。
+- 覆盖全量重建中断、重复事件、删除、滚动升级、搜索服务短暂故障。
+
+## 验收清单
+
+- [ ] 索引按租户隔离，跨租户搜索为零
+- [ ] 菜单/行级范围在查询前生效
+- [ ] 字段、排序、分页、聚合均有白名单和上限
+- [ ] 数据库与索引可对账、可重建
+- [ ] outbox 重试幂等，无永久漏同步
+- [ ] 密钥和敏感字段不进入前端/日志/索引

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

@@ -1,4 +1,4 @@
-interface:
-  display_name: "搜索引擎"
-  short_description: "配置租户隔离的索引、同步、查询、重建、权限过滤和故障恢复"
-  default_prompt: "使用 $search-engine 设计并验收当前 Microi 搜索能力。"
+interface:
+  display_name: "搜索引擎"
+  short_description: "配置租户隔离的索引、同步、查询、重建、权限过滤和故障恢复"
+  default_prompt: "使用 $search-engine 设计并验收当前 Microi 搜索能力。"