@microi.net/cli 5.1.0 → 5.1.1

package/.codebuddy-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "url": "https://microi.net"
   },
   "description": "Microi吾码官方 AI 插件市场",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "plugins": [
     {
       "name": "microi",
       "source": ".",
       "description": "Microi吾码 AI 开发插件：服务器连接、Skills、MCP、V8 全量同步与低代码交付",
-      "version": "5.1.0",
+      "version": "5.1.1",
       "strict": true
     }
   ]

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "microi",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Microi吾码 AI 开发插件：服务器连接、Skills、MCP、V8 全量同步与低代码交付",
   "author": {
     "name": "Microi.Net",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "microi",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Microi吾码低代码平台的 Codex 开发插件，共享 VS Code/CLI 的连接、同步、MCP、V8 与交付能力。",
   "author": {
     "name": "Microi.Net",

package/.workbuddy-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "url": "https://microi.net"
   },
   "description": "Microi吾码官方 AI 插件市场",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "plugins": [
     {
       "name": "microi",
       "source": ".",
       "description": "Microi吾码 AI 开发插件：服务器连接、Skills、MCP、V8 全量同步与低代码交付",
-      "version": "5.1.0",
+      "version": "5.1.1",
       "strict": true
     }
   ]

package/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "microi",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Microi吾码 AI 开发插件：服务器连接、Skills、MCP、V8 全量同步与低代码交付",
   "author": {
     "name": "Microi.Net",

package/assets/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "builtAt": "2026-08-18T03:50:53.675Z",
-  "version": "5.1.0",
+  "builtAt": "2026-08-18T18:48:14.956Z",
+  "version": "5.1.1",
   "sourceProducts": [
     "vscode-extension",
     "microi-cli",
@@ -13,6 +13,6 @@
     "cli": "5edab92236a3bea1e10a878584b97bbef20610b4448f655d7c42d2ab832532cb",
     "router": "ffc14787fc2d3d6173b7a779b77139b759eb1d482cea787f71283f4017a4e223",
     "broker": "42a9d89ad7b960a324da949939ef46266aa66e21068e6fbfd040cecc58b7c956",
-    "dshBundle": "0227b22867a76a5a7eb5e7ec828a3261b6b0382aa086d012cbd61afc646b8d2f"
+    "dshBundle": "e23cca3a809f95cc8297945969f252ab32660b78e8f6740b8f54eab9df39f7bc"
   }
 }

package/cordis.patch.yml

@@ -7,7 +7,7 @@
         serverName: microi
         transport: stdio
         command: !!js process.execPath
-        args: ["-e","/*\n * DeepSeek Harness 通过 profile bundle 加载此 `node -e` 引导脚本。\n * DSH 不保证 MCP 子进程 cwd 位于 npm 包根，因此按 DSH_HOME/profile 定位\n * 当前版本的 @microi.net/cli，再复用 Codex 同源适配器与多连接路由器。\n */\nconst fs = require('node:fs');\nconst os = require('node:os');\nconst path = require('node:path');\nconst packageName = '@microi.net/cli';\nconst expectedVersion = '5.1.0';\n\nfunction readJson(filePath) {\n  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }\n  catch { return undefined; }\n}\n\nfunction expandHome(value) {\n  if (value === '~') return os.homedir();\n  if (value.startsWith('~/') || value.startsWith('~\\\\')) return path.join(os.homedir(), value.slice(2));\n  return value;\n}\n\nfunction validRoot(value) {\n  const root = path.resolve(value);\n  const pkg = readJson(path.join(root, 'package.json'));\n  const patch = path.join(root, 'cordis.patch.yml');\n  const adapter = path.join(root, 'scripts', 'mcp-codex-stdio-adapter.js');\n  const router = path.join(root, 'scripts', 'microi-codex-router.js');\n  if (pkg?.name !== packageName || pkg?.version !== expectedVersion) return undefined;\n  if (pkg?.dsh?.bundle?.patch !== './cordis.patch.yml') return undefined;\n  if (![patch, adapter, router].every(filePath => fs.existsSync(filePath))) return undefined;\n  return { root: fs.realpathSync(root), adapter, router, modifiedAt: fs.statSync(router).mtimeMs };\n}\n\nfunction findPlugin() {\n  const explicit = String(process.env.MICROI_DSH_PLUGIN_ROOT || '').trim();\n  if (explicit) {\n    const plugin = validRoot(explicit);\n    if (!plugin) throw new Error(`MICROI_DSH_PLUGIN_ROOT 不是版本 ${expectedVersion} 的有效 Microi DSH bundle：${explicit}`);\n    return plugin;\n  }\n  const configuredHome = String(process.env.DSH_HOME || '').trim();\n  const dshHome = path.resolve(expandHome(configuredHome || path.join(os.homedir(), '.dsh')));\n  const profilesRoot = path.join(dshHome, 'profiles');\n  const candidates = [];\n  if (fs.existsSync(profilesRoot)) {\n    for (const entry of fs.readdirSync(profilesRoot, { withFileTypes: true })) {\n      if (!entry.isDirectory() || entry.name === 'node_modules') continue;\n      const root = path.join(profilesRoot, entry.name, 'node_modules', '@microi.net', 'cli');\n      const plugin = validRoot(root);\n      if (plugin) candidates.push(plugin);\n    }\n  }\n  candidates.sort((left, right) => right.modifiedAt - left.modifiedAt);\n  if (!candidates[0]) throw new Error(`未在 ${profilesRoot} 找到版本 ${expectedVersion} 的 ${packageName}`);\n  return candidates[0];\n}\n\ntry {\n  const plugin = findPlugin();\n  process.env.MICROI_DSH_PLUGIN_ROOT = plugin.root;\n  process.env.MICROI_CODEX_PLUGIN_ROOT = plugin.root;\n  process.env.MICROI_TOOL_SOURCE = 'dsh';\n  process.env.MICROI_TOOL_VERSION = expectedVersion;\n  process.env.MICROI_WORKSPACE_ROOT = process.env.MICROI_WORKSPACE_ROOT || process.cwd();\n  process.argv[2] = plugin.router;\n  require(plugin.adapter);\n} catch (error) {\n  console.error(`[microi-dsh-bootstrap] ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n"]
+        args: ["-e","/*\n * DeepSeek Harness 通过 profile bundle 加载此 `node -e` 引导脚本。\n * DSH 不保证 MCP 子进程 cwd 位于 npm 包根，因此按 DSH_HOME/profile 定位\n * 当前版本的 @microi.net/cli，再复用 Codex 同源适配器与多连接路由器。\n */\nconst fs = require('node:fs');\nconst os = require('node:os');\nconst path = require('node:path');\nconst packageName = '@microi.net/cli';\nconst expectedVersion = '5.1.1';\n\nfunction readJson(filePath) {\n  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }\n  catch { return undefined; }\n}\n\nfunction expandHome(value) {\n  if (value === '~') return os.homedir();\n  if (value.startsWith('~/') || value.startsWith('~\\\\')) return path.join(os.homedir(), value.slice(2));\n  return value;\n}\n\nfunction validRoot(value) {\n  const root = path.resolve(value);\n  const pkg = readJson(path.join(root, 'package.json'));\n  const patch = path.join(root, 'cordis.patch.yml');\n  const adapter = path.join(root, 'scripts', 'mcp-codex-stdio-adapter.js');\n  const router = path.join(root, 'scripts', 'microi-codex-router.js');\n  if (pkg?.name !== packageName || pkg?.version !== expectedVersion) return undefined;\n  if (pkg?.dsh?.bundle?.patch !== './cordis.patch.yml') return undefined;\n  if (![patch, adapter, router].every(filePath => fs.existsSync(filePath))) return undefined;\n  return { root: fs.realpathSync(root), adapter, router, modifiedAt: fs.statSync(router).mtimeMs };\n}\n\nfunction findPlugin() {\n  const explicit = String(process.env.MICROI_DSH_PLUGIN_ROOT || '').trim();\n  if (explicit) {\n    const plugin = validRoot(explicit);\n    if (!plugin) throw new Error(`MICROI_DSH_PLUGIN_ROOT 不是版本 ${expectedVersion} 的有效 Microi DSH bundle：${explicit}`);\n    return plugin;\n  }\n  const configuredHome = String(process.env.DSH_HOME || '').trim();\n  const dshHome = path.resolve(expandHome(configuredHome || path.join(os.homedir(), '.dsh')));\n  const profilesRoot = path.join(dshHome, 'profiles');\n  const candidates = [];\n  if (fs.existsSync(profilesRoot)) {\n    for (const entry of fs.readdirSync(profilesRoot, { withFileTypes: true })) {\n      if (!entry.isDirectory() || entry.name === 'node_modules') continue;\n      const root = path.join(profilesRoot, entry.name, 'node_modules', '@microi.net', 'cli');\n      const plugin = validRoot(root);\n      if (plugin) candidates.push(plugin);\n    }\n  }\n  candidates.sort((left, right) => right.modifiedAt - left.modifiedAt);\n  if (!candidates[0]) throw new Error(`未在 ${profilesRoot} 找到版本 ${expectedVersion} 的 ${packageName}`);\n  return candidates[0];\n}\n\ntry {\n  const plugin = findPlugin();\n  process.env.MICROI_DSH_PLUGIN_ROOT = plugin.root;\n  process.env.MICROI_CODEX_PLUGIN_ROOT = plugin.root;\n  process.env.MICROI_TOOL_SOURCE = 'dsh';\n  process.env.MICROI_TOOL_VERSION = expectedVersion;\n  process.env.MICROI_WORKSPACE_ROOT = process.env.MICROI_WORKSPACE_ROOT || process.cwd();\n  process.argv[2] = plugin.router;\n  require(plugin.adapter);\n} catch (error) {\n  console.error(`[microi-dsh-bootstrap] ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n}\n"]
         env:
           MICROI_TOOL_SOURCE: dsh
         cwd: !!js process.cwd()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microi.net/cli",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Microi吾码 AI 开发 CLI 与多宿主 Plugin：服务器连接、Skills、MCP、V8 同步和低代码交付",
   "license": "MIT",
   "homepage": "https://microi.net/doc/v8-engine/vs-code-plugin.html",

package/scripts/microi-skills.meta.json

@@ -1,13 +1,13 @@
 {
-  "builtAt": "2026-08-18T03:50:52.939Z",
+  "builtAt": "2026-08-18T18:48:13.688Z",
   "source": "../microi.skills",
   "extension": {
     "name": "v8-engine",
-    "version": "5.1.0",
+    "version": "5.1.1",
     "publisher": "Microi"
   },
   "skills": {
-    "version": "5.1.0",
+    "version": "5.1.1",
     "versionRule": "Microi version uses three numeric parts. Each publish increments the last part; when a part exceeds 9 it carries to the previous part: 1.0.9 -> 1.1.0, 1.9.9 -> 2.0.0.",
     "managedBy": "Microi.VSCode/bump-version.js"
   },
@@ -15,10 +15,10 @@
     "dir": "dist/microi.skills",
     "files": 172,
     "skills": 63,
-    "bytes": 2101802
+    "bytes": 2102023
   },
   "fileHashes": {
-    ".microi-skills-version.json": "5de4a38261cbf1d0e067b50c2cd2fc419ba1c4d024dfd45cf9fe3ede4c6026ca",
+    ".microi-skills-version.json": "2cbe12fb55c3edb813467260c7d1249cb4804d15130b942005d79c0b9c617193",
     ".progressive-disclosure-manifest.json": "dc5cfc483df88dfd1f9f5bfba62bceddec5bb28ab551d07b6ed9a91ec33c8e51",
     "README.md": "e4c36c39515953ac1953622f19671d2c377a8828aae20f877bdd39ab1dcb0cb1",
     "ai-engine/SKILL.md": "a9d3b152c6d8ca03bfa37669d4e81cf33c7361f3105165e40cb357f1b23b2bfb",
@@ -177,7 +177,7 @@
     "v8-table-event/SKILL.md": "8479380d0583279ee350534b7ed8d6c73ff0fe92ede028f15f80b9f02972f283",
     "v8-table-event/references/progressive-01-informv8-js-表单打开事件.md": "baa4e6670f693d62ab5fc9d5bd692dfd801ed30a530c5224c7c149088712b5d7",
     "v8-table-event/references/progressive-02-前端事件名-v8-eventname-可能的值.md": "e72d4ddf9dd29c7f96cdfc2efbeede33e7a50049b5d8971356a54f596d44e2bd",
-    "v8-tcp-integration/SKILL.md": "1572287f2541ffa049f8b0a4accd28680a3cf55c18bc8525559c9623596df680",
+    "v8-tcp-integration/SKILL.md": "1150cc84826eb38155ca14af68073ff3421b45e5b7d166e5f6d2617826957edf",
     "v8-tcp-integration/agents/openai.yaml": "0de66958f5fe4f3410c42578a5462daa0d9d282efd4a1f5a1fad1f8541110515",
     "v8-template-engine/SKILL.md": "19363a9e047737b62236f187946ac8398ee6cb19907de70ce0888681b75afb15",
     "v8-utilities/SKILL.md": "8313a3e0e0c5f7a29cb22231b751a52107e3efa3b790e994343e54807fcb7285",
@@ -192,178 +192,178 @@
     "workspace-conventions/references/progressive-03-cli-与-ide-插件错版共存约定.md": "86db1f03700fd54dd824d28c553c678202e8f74b796fd0f9d91f63bf53a530b1"
   },
   "fileVersions": {
-    ".microi-skills-version.json": "5.1.0",
-    ".progressive-disclosure-manifest.json": "5.1.0",
-    "README.md": "5.1.0",
-    "ai-engine/SKILL.md": "5.1.0",
-    "ai-engine/agents/openai.yaml": "5.1.0",
-    "ai-platform-governance/SKILL.md": "5.1.0",
-    "ai-platform-governance/references/progressive-01-功能开关.md": "5.1.0",
-    "app-store/SKILL.md": "5.1.0",
-    "app-store/agents/openai.yaml": "5.1.0",
-    "business-blueprint/SKILL.md": "5.1.0",
-    "datasource-engine/SKILL.md": "5.1.0",
-    "datasource-engine/agents/openai.yaml": "5.1.0",
-    "dos-orm/SKILL.md": "5.1.0",
-    "dos-orm/references/api-reference.md": "5.1.0",
-    "job-engine/SKILL.md": "5.1.0",
-    "job-engine/agents/openai.yaml": "5.1.0",
-    "message-notification/SKILL.md": "5.1.0",
-    "message-notification/agents/openai.yaml": "5.1.0",
-    "message-notification/references/contracts.md": "5.1.0",
-    "microi-ai-app-auth.js": "5.1.0",
-    "microi-ai-application/SKILL.md": "5.1.0",
-    "microi-ai-application/agents/openai.yaml": "5.1.0",
-    "microi-ai-application/references/frontend-baseline.md": "5.1.0",
-    "microi-client-frontend/SKILL.md": "5.1.0",
-    "microi-client-frontend/references/progressive-01-3-动态按钮系统.md": "5.1.0",
-    "microi-client-frontend/references/progressive-02-8-运行时高频坑复盘.md": "5.1.0",
-    "microi-client-frontend/references/progressive-03-vue3-前端微服务宿主规则.md": "5.1.0",
-    "microi-codex-installer/SKILL.md": "5.1.0",
-    "microi-codex-installer/agents/openai.yaml": "5.1.0",
-    "microi-codex/SKILL.md": "5.1.0",
-    "microi-datasource-mapping/SKILL.md": "5.1.0",
-    "microi-db-schema/SKILL.md": "5.1.0",
-    "microi-db-schema/agents/openai.yaml": "5.1.0",
-    "microi-db-schema/references/core-tables.md": "5.1.0",
-    "microi-db-schema/references/form-component-options.md": "5.1.0",
-    "microi-db-schema/references/schema-overview.md": "5.1.0",
-    "microi-db-schema/references/schema.md": "5.1.0",
-    "microi-db-schema/references/table-catalog.md": "5.1.0",
-    "microi-deployment/SKILL.md": "5.1.0",
-    "microi-deployment/references/deployment-matrix.md": "5.1.0",
-    "microi-docs-coverage/SKILL.md": "5.1.0",
-    "microi-docs-coverage/references/capability-map.md": "5.1.0",
-    "microi-docs-coverage/scripts/audit-doc-skill-coverage.mjs": "5.1.0",
-    "microi-form-engine/SKILL.md": "5.1.0",
-    "microi-form-engine/references/component-catalog.md": "5.1.0",
-    "microi-form-engine/references/data-source-events.md": "5.1.0",
-    "microi-form-layout/SKILL.md": "5.1.0",
-    "microi-form-layout/references/progressive-01-3-三种分组的存储与配置.md": "5.1.0",
-    "microi-frontend-sdk/SKILL.md": "5.1.0",
-    "microi-frontend-sdk/references/progressive-01-token-当前登录用户与当前终端登录协议.md": "5.1.0",
-    "microi-left-right-layout/SKILL.md": "5.1.0",
-    "microi-microservice/SKILL.md": "5.1.0",
-    "microi-microservice/references/runtime-delivery.md": "5.1.0",
-    "microi-mobile-app-quality/SKILL.md": "5.1.0",
-    "microi-mobile-app-quality/references/progressive-01-4-重要按钮必须带图标.md": "5.1.0",
-    "microi-mobile-app-quality/references/progressive-02-9-主题切换必须真实且全局生效.md": "5.1.0",
-    "microi-solution-quotation/SKILL.md": "5.1.0",
-    "microi-solution-quotation/agents/openai.yaml": "5.1.0",
-    "microi-solution-quotation/scripts/build_solution_quote.py": "5.1.0",
-    "microi-system-delivery/SKILL.md": "5.1.0",
-    "microi-system-delivery/references/progressive-01-标准工作流.md": "5.1.0",
-    "microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md": "5.1.0",
-    "microi-ui/SKILL.md": "5.1.0",
-    "microi-ui/references/progressive-01-移动端场景蓝图.md": "5.1.0",
-    "microi-uniapp-frontend/SKILL.md": "5.1.0",
-    "microi-uniapp-frontend/references/progressive-01-移动端分类-双栏列表独立滚动.md": "5.1.0",
-    "microi-uniapp-frontend/references/progressive-02-关键业务资产不得默认选中.md": "5.1.0",
-    "microi.v8.js": "5.1.0",
-    "module-engine/SKILL.md": "5.1.0",
-    "module-engine/references/module-config.md": "5.1.0",
-    "ocr-engine/SKILL.md": "5.1.0",
-    "ocr-engine/agents/openai.yaml": "5.1.0",
-    "page-engine/SKILL.md": "5.1.0",
-    "page-engine/references/progressive-01-所有组件类型.md": "5.1.0",
-    "page-engine/references/progressive-02-版本历史-并发保存与回滚.md": "5.1.0",
-    "performance-testing/SKILL.md": "5.1.0",
-    "playwright-e2e/SKILL.md": "5.1.0",
-    "playwright-e2e/references/progressive-01-全自动登录-免验证码-但不免密码-必读.md": "5.1.0",
-    "playwright-e2e/references/progressive-02-文字对比度与可读性自动化检查-必做.md": "5.1.0",
-    "playwright-e2e/references/progressive-03-microi-helper-模板.md": "5.1.0",
-    "playwright-e2e/references/progressive-04-ci-建议.md": "5.1.0",
-    "print-engine/SKILL.md": "5.1.0",
-    "production-readonly-audit/SKILL.md": "5.1.0",
-    "report-engine/SKILL.md": "5.1.0",
-    "report-engine/agents/openai.yaml": "5.1.0",
-    "scripts/optimize-progressive-disclosure.mjs": "5.1.0",
-    "scripts/refresh-progressive-disclosure.mjs": "5.1.0",
-    "scripts/validate-progressive-disclosure.mjs": "5.1.0",
-    "search-engine/SKILL.md": "5.1.0",
-    "search-engine/agents/openai.yaml": "5.1.0",
-    "spider-engine/SKILL.md": "5.1.0",
-    "translate-engine/SKILL.md": "5.1.0",
-    "translate-engine/agents/openai.yaml": "5.1.0",
-    "ui-design/SKILL.md": "5.1.0",
-    "ui-design/assets/pattern-showcase/app.js": "5.1.0",
-    "ui-design/assets/pattern-showcase/index.html": "5.1.0",
-    "ui-design/assets/pattern-showcase/styles.css": "5.1.0",
-    "ui-design/assets/templates/MCI-DESIGN.md": "5.1.0",
-    "ui-design/references/design-pattern-library.md": "5.1.0",
-    "ui-design/references/mci-design-contract.md": "5.1.0",
-    "ui-design/references/motion-and-media.md": "5.1.0",
-    "ui-design/references/product-flow-recipes.md": "5.1.0",
-    "ui-design/references/progressive-01-颜色体系-css-variables-支持主题切换.md": "5.1.0",
-    "ui-design/references/progressive-02-字体.md": "5.1.0",
-    "ui-design/references/progressive-03-动效规范-丰富但不卡.md": "5.1.0",
-    "ui-design/references/progressive-04-组件风格速查.md": "5.1.0",
-    "ui-design/references/progressive-05-移动端专用规范.md": "5.1.0",
-    "ui-design/references/progressive-06-主题切换实现.md": "5.1.0",
-    "ui-design/references/progressive-07-速查-从头搭建一个移动端页面.md": "5.1.0",
-    "ui-design/references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md": "5.1.0",
-    "uniapp-mall-assets/SKILL.md": "5.1.0",
-    "unity-integration/SKILL.md": "5.1.0",
-    "unity-integration/agents/openai.yaml": "5.1.0",
-    "unity-integration/references/ai-app-delivery.md": "5.1.0",
-    "unity-integration/references/sdk-api.md": "5.1.0",
-    "unity-integration/references/toolbox-migration.md": "5.1.0",
-    "unity-integration/references/webgl-hosting.md": "5.1.0",
-    "v8-api-config/SKILL.md": "5.1.0",
-    "v8-cache-pattern/SKILL.md": "5.1.0",
-    "v8-crud-api/SKILL.md": "5.1.0",
-    "v8-crud-api/references/progressive-01-查询列表-分页.md": "5.1.0",
-    "v8-crud-api/references/progressive-02-where-条件语法速查.md": "5.1.0",
-    "v8-debugging/SKILL.md": "5.1.0",
-    "v8-explorer-tree/SKILL.md": "5.1.0",
-    "v8-export-import/SKILL.md": "5.1.0",
-    "v8-export-import/references/progressive-01-excellayout-高级自由布局.md": "5.1.0",
-    "v8-export-import/references/progressive-02-powerpoint-导出.md": "5.1.0",
-    "v8-export-import/references/progressive-03-安全-性能注意.md": "5.1.0",
-    "v8-file-upload/SKILL.md": "5.1.0",
-    "v8-file-upload/references/progressive-01-公有桶-vs-私有桶.md": "5.1.0",
-    "v8-file-upload/references/progressive-02-office-文件在线编辑版本号规则.md": "5.1.0",
-    "v8-formengine-http/SKILL.md": "5.1.0",
-    "v8-frontend-events/SKILL.md": "5.1.0",
-    "v8-frontend-events/references/bluetooth-print-api.md": "5.1.0",
-    "v8-frontend-events/references/bluetooth-print.md": "5.1.0",
-    "v8-frontend-events/references/progressive-01-列表事件.md": "5.1.0",
-    "v8-http-integration/SKILL.md": "5.1.0",
-    "v8-http-integration/references/progressive-01-get-请求.md": "5.1.0",
-    "v8-http-integration/references/progressive-02-错误处理模式.md": "5.1.0",
-    "v8-image-processing/SKILL.md": "5.1.0",
-    "v8-image-processing/agents/openai.yaml": "5.1.0",
-    "v8-image-processing/references/api-reference.md": "5.1.0",
-    "v8-menu-buttons/SKILL.md": "5.1.0",
-    "v8-menu-buttons/references/progressive-01-2-按钮对象-schema.md": "5.1.0",
-    "v8-menu-buttons/references/progressive-02-8-模式-f-后台任务按钮-长任务.md": "5.1.0",
-    "v8-menu-buttons/references/progressive-03-10-反模式-避免.md": "5.1.0",
-    "v8-mongodb/SKILL.md": "5.1.0",
-    "v8-mq-mqtt/SKILL.md": "5.1.0",
-    "v8-mq-mqtt/references/mqtt-production.md": "5.1.0",
-    "v8-mq-mqtt/references/progressive-01-v8-mqtt-iot-物联网.md": "5.1.0",
-    "v8-mq-mqtt/scripts/check-mqtt-skill-coverage.mjs": "5.1.0",
-    "v8-saas-multi-tenant/SKILL.md": "5.1.0",
-    "v8-security/SKILL.md": "5.1.0",
-    "v8-security/references/progressive-01-2-权限校验.md": "5.1.0",
-    "v8-security/references/progressive-02-7-日志记录.md": "5.1.0",
-    "v8-sql-query/SKILL.md": "5.1.0",
-    "v8-table-event/SKILL.md": "5.1.0",
-    "v8-table-event/references/progressive-01-informv8-js-表单打开事件.md": "5.1.0",
-    "v8-table-event/references/progressive-02-前端事件名-v8-eventname-可能的值.md": "5.1.0",
-    "v8-tcp-integration/SKILL.md": "5.1.0",
-    "v8-tcp-integration/agents/openai.yaml": "5.1.0",
-    "v8-template-engine/SKILL.md": "5.1.0",
-    "v8-utilities/SKILL.md": "5.1.0",
-    "v8-utilities/references/client-api-index.md": "5.1.0",
-    "v8-utilities/references/platform-http-routes.md": "5.1.0",
-    "v8-utilities/references/server-api-index.md": "5.1.0",
-    "v8-workflow/SKILL.md": "5.1.0",
-    "v8-workflow/references/progressive-01-节点开始-v8-事件.md": "5.1.0",
-    "workspace-conventions/SKILL.md": "5.1.0",
-    "workspace-conventions/references/progressive-01-版本更新日志保护规则-强制.md": "5.1.0",
-    "workspace-conventions/references/progressive-02-microi-net-api-本地启动约定.md": "5.1.0",
-    "workspace-conventions/references/progressive-03-cli-与-ide-插件错版共存约定.md": "5.1.0"
+    ".microi-skills-version.json": "5.1.1",
+    ".progressive-disclosure-manifest.json": "5.1.1",
+    "README.md": "5.1.1",
+    "ai-engine/SKILL.md": "5.1.1",
+    "ai-engine/agents/openai.yaml": "5.1.1",
+    "ai-platform-governance/SKILL.md": "5.1.1",
+    "ai-platform-governance/references/progressive-01-功能开关.md": "5.1.1",
+    "app-store/SKILL.md": "5.1.1",
+    "app-store/agents/openai.yaml": "5.1.1",
+    "business-blueprint/SKILL.md": "5.1.1",
+    "datasource-engine/SKILL.md": "5.1.1",
+    "datasource-engine/agents/openai.yaml": "5.1.1",
+    "dos-orm/SKILL.md": "5.1.1",
+    "dos-orm/references/api-reference.md": "5.1.1",
+    "job-engine/SKILL.md": "5.1.1",
+    "job-engine/agents/openai.yaml": "5.1.1",
+    "message-notification/SKILL.md": "5.1.1",
+    "message-notification/agents/openai.yaml": "5.1.1",
+    "message-notification/references/contracts.md": "5.1.1",
+    "microi-ai-app-auth.js": "5.1.1",
+    "microi-ai-application/SKILL.md": "5.1.1",
+    "microi-ai-application/agents/openai.yaml": "5.1.1",
+    "microi-ai-application/references/frontend-baseline.md": "5.1.1",
+    "microi-client-frontend/SKILL.md": "5.1.1",
+    "microi-client-frontend/references/progressive-01-3-动态按钮系统.md": "5.1.1",
+    "microi-client-frontend/references/progressive-02-8-运行时高频坑复盘.md": "5.1.1",
+    "microi-client-frontend/references/progressive-03-vue3-前端微服务宿主规则.md": "5.1.1",
+    "microi-codex-installer/SKILL.md": "5.1.1",
+    "microi-codex-installer/agents/openai.yaml": "5.1.1",
+    "microi-codex/SKILL.md": "5.1.1",
+    "microi-datasource-mapping/SKILL.md": "5.1.1",
+    "microi-db-schema/SKILL.md": "5.1.1",
+    "microi-db-schema/agents/openai.yaml": "5.1.1",
+    "microi-db-schema/references/core-tables.md": "5.1.1",
+    "microi-db-schema/references/form-component-options.md": "5.1.1",
+    "microi-db-schema/references/schema-overview.md": "5.1.1",
+    "microi-db-schema/references/schema.md": "5.1.1",
+    "microi-db-schema/references/table-catalog.md": "5.1.1",
+    "microi-deployment/SKILL.md": "5.1.1",
+    "microi-deployment/references/deployment-matrix.md": "5.1.1",
+    "microi-docs-coverage/SKILL.md": "5.1.1",
+    "microi-docs-coverage/references/capability-map.md": "5.1.1",
+    "microi-docs-coverage/scripts/audit-doc-skill-coverage.mjs": "5.1.1",
+    "microi-form-engine/SKILL.md": "5.1.1",
+    "microi-form-engine/references/component-catalog.md": "5.1.1",
+    "microi-form-engine/references/data-source-events.md": "5.1.1",
+    "microi-form-layout/SKILL.md": "5.1.1",
+    "microi-form-layout/references/progressive-01-3-三种分组的存储与配置.md": "5.1.1",
+    "microi-frontend-sdk/SKILL.md": "5.1.1",
+    "microi-frontend-sdk/references/progressive-01-token-当前登录用户与当前终端登录协议.md": "5.1.1",
+    "microi-left-right-layout/SKILL.md": "5.1.1",
+    "microi-microservice/SKILL.md": "5.1.1",
+    "microi-microservice/references/runtime-delivery.md": "5.1.1",
+    "microi-mobile-app-quality/SKILL.md": "5.1.1",
+    "microi-mobile-app-quality/references/progressive-01-4-重要按钮必须带图标.md": "5.1.1",
+    "microi-mobile-app-quality/references/progressive-02-9-主题切换必须真实且全局生效.md": "5.1.1",
+    "microi-solution-quotation/SKILL.md": "5.1.1",
+    "microi-solution-quotation/agents/openai.yaml": "5.1.1",
+    "microi-solution-quotation/scripts/build_solution_quote.py": "5.1.1",
+    "microi-system-delivery/SKILL.md": "5.1.1",
+    "microi-system-delivery/references/progressive-01-标准工作流.md": "5.1.1",
+    "microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md": "5.1.1",
+    "microi-ui/SKILL.md": "5.1.1",
+    "microi-ui/references/progressive-01-移动端场景蓝图.md": "5.1.1",
+    "microi-uniapp-frontend/SKILL.md": "5.1.1",
+    "microi-uniapp-frontend/references/progressive-01-移动端分类-双栏列表独立滚动.md": "5.1.1",
+    "microi-uniapp-frontend/references/progressive-02-关键业务资产不得默认选中.md": "5.1.1",
+    "microi.v8.js": "5.1.1",
+    "module-engine/SKILL.md": "5.1.1",
+    "module-engine/references/module-config.md": "5.1.1",
+    "ocr-engine/SKILL.md": "5.1.1",
+    "ocr-engine/agents/openai.yaml": "5.1.1",
+    "page-engine/SKILL.md": "5.1.1",
+    "page-engine/references/progressive-01-所有组件类型.md": "5.1.1",
+    "page-engine/references/progressive-02-版本历史-并发保存与回滚.md": "5.1.1",
+    "performance-testing/SKILL.md": "5.1.1",
+    "playwright-e2e/SKILL.md": "5.1.1",
+    "playwright-e2e/references/progressive-01-全自动登录-免验证码-但不免密码-必读.md": "5.1.1",
+    "playwright-e2e/references/progressive-02-文字对比度与可读性自动化检查-必做.md": "5.1.1",
+    "playwright-e2e/references/progressive-03-microi-helper-模板.md": "5.1.1",
+    "playwright-e2e/references/progressive-04-ci-建议.md": "5.1.1",
+    "print-engine/SKILL.md": "5.1.1",
+    "production-readonly-audit/SKILL.md": "5.1.1",
+    "report-engine/SKILL.md": "5.1.1",
+    "report-engine/agents/openai.yaml": "5.1.1",
+    "scripts/optimize-progressive-disclosure.mjs": "5.1.1",
+    "scripts/refresh-progressive-disclosure.mjs": "5.1.1",
+    "scripts/validate-progressive-disclosure.mjs": "5.1.1",
+    "search-engine/SKILL.md": "5.1.1",
+    "search-engine/agents/openai.yaml": "5.1.1",
+    "spider-engine/SKILL.md": "5.1.1",
+    "translate-engine/SKILL.md": "5.1.1",
+    "translate-engine/agents/openai.yaml": "5.1.1",
+    "ui-design/SKILL.md": "5.1.1",
+    "ui-design/assets/pattern-showcase/app.js": "5.1.1",
+    "ui-design/assets/pattern-showcase/index.html": "5.1.1",
+    "ui-design/assets/pattern-showcase/styles.css": "5.1.1",
+    "ui-design/assets/templates/MCI-DESIGN.md": "5.1.1",
+    "ui-design/references/design-pattern-library.md": "5.1.1",
+    "ui-design/references/mci-design-contract.md": "5.1.1",
+    "ui-design/references/motion-and-media.md": "5.1.1",
+    "ui-design/references/product-flow-recipes.md": "5.1.1",
+    "ui-design/references/progressive-01-颜色体系-css-variables-支持主题切换.md": "5.1.1",
+    "ui-design/references/progressive-02-字体.md": "5.1.1",
+    "ui-design/references/progressive-03-动效规范-丰富但不卡.md": "5.1.1",
+    "ui-design/references/progressive-04-组件风格速查.md": "5.1.1",
+    "ui-design/references/progressive-05-移动端专用规范.md": "5.1.1",
+    "ui-design/references/progressive-06-主题切换实现.md": "5.1.1",
+    "ui-design/references/progressive-07-速查-从头搭建一个移动端页面.md": "5.1.1",
+    "ui-design/references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md": "5.1.1",
+    "uniapp-mall-assets/SKILL.md": "5.1.1",
+    "unity-integration/SKILL.md": "5.1.1",
+    "unity-integration/agents/openai.yaml": "5.1.1",
+    "unity-integration/references/ai-app-delivery.md": "5.1.1",
+    "unity-integration/references/sdk-api.md": "5.1.1",
+    "unity-integration/references/toolbox-migration.md": "5.1.1",
+    "unity-integration/references/webgl-hosting.md": "5.1.1",
+    "v8-api-config/SKILL.md": "5.1.1",
+    "v8-cache-pattern/SKILL.md": "5.1.1",
+    "v8-crud-api/SKILL.md": "5.1.1",
+    "v8-crud-api/references/progressive-01-查询列表-分页.md": "5.1.1",
+    "v8-crud-api/references/progressive-02-where-条件语法速查.md": "5.1.1",
+    "v8-debugging/SKILL.md": "5.1.1",
+    "v8-explorer-tree/SKILL.md": "5.1.1",
+    "v8-export-import/SKILL.md": "5.1.1",
+    "v8-export-import/references/progressive-01-excellayout-高级自由布局.md": "5.1.1",
+    "v8-export-import/references/progressive-02-powerpoint-导出.md": "5.1.1",
+    "v8-export-import/references/progressive-03-安全-性能注意.md": "5.1.1",
+    "v8-file-upload/SKILL.md": "5.1.1",
+    "v8-file-upload/references/progressive-01-公有桶-vs-私有桶.md": "5.1.1",
+    "v8-file-upload/references/progressive-02-office-文件在线编辑版本号规则.md": "5.1.1",
+    "v8-formengine-http/SKILL.md": "5.1.1",
+    "v8-frontend-events/SKILL.md": "5.1.1",
+    "v8-frontend-events/references/bluetooth-print-api.md": "5.1.1",
+    "v8-frontend-events/references/bluetooth-print.md": "5.1.1",
+    "v8-frontend-events/references/progressive-01-列表事件.md": "5.1.1",
+    "v8-http-integration/SKILL.md": "5.1.1",
+    "v8-http-integration/references/progressive-01-get-请求.md": "5.1.1",
+    "v8-http-integration/references/progressive-02-错误处理模式.md": "5.1.1",
+    "v8-image-processing/SKILL.md": "5.1.1",
+    "v8-image-processing/agents/openai.yaml": "5.1.1",
+    "v8-image-processing/references/api-reference.md": "5.1.1",
+    "v8-menu-buttons/SKILL.md": "5.1.1",
+    "v8-menu-buttons/references/progressive-01-2-按钮对象-schema.md": "5.1.1",
+    "v8-menu-buttons/references/progressive-02-8-模式-f-后台任务按钮-长任务.md": "5.1.1",
+    "v8-menu-buttons/references/progressive-03-10-反模式-避免.md": "5.1.1",
+    "v8-mongodb/SKILL.md": "5.1.1",
+    "v8-mq-mqtt/SKILL.md": "5.1.1",
+    "v8-mq-mqtt/references/mqtt-production.md": "5.1.1",
+    "v8-mq-mqtt/references/progressive-01-v8-mqtt-iot-物联网.md": "5.1.1",
+    "v8-mq-mqtt/scripts/check-mqtt-skill-coverage.mjs": "5.1.1",
+    "v8-saas-multi-tenant/SKILL.md": "5.1.1",
+    "v8-security/SKILL.md": "5.1.1",
+    "v8-security/references/progressive-01-2-权限校验.md": "5.1.1",
+    "v8-security/references/progressive-02-7-日志记录.md": "5.1.1",
+    "v8-sql-query/SKILL.md": "5.1.1",
+    "v8-table-event/SKILL.md": "5.1.1",
+    "v8-table-event/references/progressive-01-informv8-js-表单打开事件.md": "5.1.1",
+    "v8-table-event/references/progressive-02-前端事件名-v8-eventname-可能的值.md": "5.1.1",
+    "v8-tcp-integration/SKILL.md": "5.1.1",
+    "v8-tcp-integration/agents/openai.yaml": "5.1.1",
+    "v8-template-engine/SKILL.md": "5.1.1",
+    "v8-utilities/SKILL.md": "5.1.1",
+    "v8-utilities/references/client-api-index.md": "5.1.1",
+    "v8-utilities/references/platform-http-routes.md": "5.1.1",
+    "v8-utilities/references/server-api-index.md": "5.1.1",
+    "v8-workflow/SKILL.md": "5.1.1",
+    "v8-workflow/references/progressive-01-节点开始-v8-事件.md": "5.1.1",
+    "workspace-conventions/SKILL.md": "5.1.1",
+    "workspace-conventions/references/progressive-01-版本更新日志保护规则-强制.md": "5.1.1",
+    "workspace-conventions/references/progressive-02-microi-net-api-本地启动约定.md": "5.1.1",
+    "workspace-conventions/references/progressive-03-cli-与-ide-插件错版共存约定.md": "5.1.1"
   },
   "files": [
     ".microi-skills-version.json",

package/skills/.microi-skills-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "5.1.0",
+  "version": "5.1.1",
   "versionRule": "Microi version uses three numeric parts. Each publish increments the last part; when a part exceeds 9 it carries to the previous part: 1.0.9 -> 1.1.0, 1.9.9 -> 2.0.0.",
   "managedBy": "Microi.VSCode/bump-version.js",
-  "updatedAt": "2026-08-18T03:50:28.277Z"
+  "updatedAt": "2026-08-18T18:44:26.205Z"
 }

package/skills/v8-tcp-integration/SKILL.md

@@ -1,148 +1,151 @@
----
-name: v8-tcp-integration
-description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi V8 TCP 原始字节集成
-
-使用后端 `V8.Tcp` 完成一次性 TCP 连接、原始字节写入和可选的有界响应读取。典型场景是 RAW/JetDirect 9100 网络小票机、串口服务器和 PLC；具体协议帧、校验码与打印业务仍由接口引擎编排。
-
-文档维护时，只在 `microi.doc/docs/doc/v8-engine/v8-server.md` 原位更新后端 API；不要新建重复页面，也不要手工维护英文文档。改变公共契约时同步后端源码/测试、Microi.Client Monaco 定义、Microi.VSCode 类型与生成知识、AI Skill 镜像。
-
-## 先判断是否适用
-
-| 需求 | 选择 |
-|---|---|
-| 后端向设备 TCP 端口发送原始字节 | `V8.Tcp` |
-| HTTP/HTTPS API | `V8.Http`，不要用 TCP 重写 HTTP |
-| RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
-| 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
-| 长连接、TCP 服务端监听、TLS、自定义连接池 | 当前 `V8.Tcp` 不提供；设计独立网关/Worker |
-
-平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
-
-## API 契约
-
-| 方法 | 行为 |
-|---|---|
-| `V8.Tcp.Send({...})` | 连接、发送、关闭，返回 `DosResult` |
-| `await V8.Tcp.SendAsync({...})` | 当前请求内异步发送 |
-| `V8.Tcp.SendAndReceive({...})` | 发送后读取响应，再关闭 |
-| `await V8.Tcp.SendAndReceiveAsync({...})` | 当前请求内异步发送并读取响应 |
-
-必填目标参数：
-
-- `Host`：主机名或 IP；只允许主机，不传 `tcp://` URL。
-- `Port`：1-65535。
-
-发送内容必须且只能选择一组：
-
-- `Bytes`（别名 `RawBytes`、`ByteArray`）：每项为 0-255 的整数。
-- `ByteBase64`（别名 `BytesBase64`、`Base64`）。
-- `Hex`：允许空格、`0x`、`-`、`:`、逗号和下划线分隔。
-- `Text`：按 `Encoding` 编码。默认 `utf-8`，还支持 `ascii`、`gb18030`、`gbk/gb2312`、UTF-16/UTF-32 大小端。
-
-边界参数：
-
-| 参数 | 默认 | 范围 |
-|---|---:|---:|
-| `ConnectTimeout` | 10 秒 | 1-120 秒 |
-| `SendTimeout` | 10 秒 | 1-120 秒 |
-| `ReceiveTimeout` | 3 秒 | 1-120 秒 |
-| `MaxReceiveBytes` | 65536 | 1-1048576 |
-| `NoDelay` | `true` | 布尔值 |
-
-单次发送最多 4 MiB。`Send` 成功数据为 `{BytesSent, RemoteEndPoint}`。收发方法另有 `BytesReceived`、`RawBytes`、`ByteBase64`、`Hex`、`ReceiveEndReason`、`Truncated`；`ReceiveEndReason` 为 `RemoteClosed`、`Timeout` 或 `MaxReceiveBytes`。
-
-## 实现流程
-
-### 1. 固定并授权设备目标
-
-从 SaaS 可信配置或受行权限保护的设备表读取 `Host`、`Port`，按当前用户/门店/租户决定可用设备，再与精确白名单比较。禁止这样写：
-
-```javascript
-// 错误：匿名或普通调用者可扫描后端可达内网。
-return V8.Tcp.Send({
-  Host: V8.Param.Host,
-  Port: V8.Param.Port,
-  Hex: V8.Param.Hex
-});
-```
-
-### 2. 形成一个完整帧
-
-ESC/POS、Modbus TCP 或设备私有协议的命令、正文和校验码应先合成一个完整字节载荷。不要为了拼帧而打开多次连接；包含中文和控制命令时，优先在可信后端/上游把完整帧编码为 `Bytes`、`ByteBase64` 或 `Hex`。
-
-```javascript
-var result = V8.Tcp.Send({
-  Host: '192.168.1.88', // 示例；生产从可信配置读取
-  Port: 9100,
-  Bytes: [
-    27, 64,                         // ESC @ 初始化
-    77, 105, 99, 114, 111, 105, 10,
-    10, 10,
-    29, 86, 0                       // GS V 0 切纸
-  ],
-  ConnectTimeout: 5,
-  SendTimeout: 5
-});
-if (result.Code !== 1) return result;
-```
-
-只有纯文本时可使用打印机常见编码：
-
-```javascript
-var result = await V8.Tcp.SendAsync({
-  Host: '192.168.1.88',
-  Port: 9100,
-  Text: '吾码小票\n合计：12.00\n\n',
-  Encoding: 'gb18030'
-});
-if (result.Code !== 1) return result;
-```
-
-### 3. 需要协议响应时显式收取
-
-```javascript
-var result = V8.Tcp.SendAndReceive({
-  Host: '192.168.1.20',
-  Port: 4001,
-  Hex: '01 03 00 00 00 02 C4 0B',
-  ReceiveTimeout: 3,
-  MaxReceiveBytes: 4096
-});
-if (result.Code !== 1) return result;
-
-var bytes = result.Data.RawBytes;
-var hex = result.Data.Hex;
-```
-
-接收超时是整段接收的总时间。已收到部分数据后超时会返回成功和已有数据，并标记 `ReceiveEndReason='Timeout'`；未收到任何字节则失败。协议必须知道响应长度或结束条件，不能把超时默认当作完整帧。
-
-### 4. 分开判断写入、设备执行和实物结果
-
-- `Code=1` 只表示字节已写入 TCP 连接。
-- 设备协议回执可证明设备接受/处理到哪一步，但仍不一定证明机械动作完成。
-- “小票已打印”需要打印机状态、设备回执或实物/硬件验收证据。
-
-打印不是天然幂等。不确定失败时自动重试可能重复出纸；需要可靠打印时使用业务打印单号、设备回执、状态机以及 Job/MQ/outbox，且重试策略必须识别“尚未发送”和“结果未知”。
-
-## 安全与运行约束
-
-1. TCP 不经过 `V8.Http` 的 SSRF 防护。容器网络策略/防火墙只放行目标设备网段和端口；匿名接口不得暴露任意目标。
-2. 不把票据正文、设备口令、原始帧和响应秘密写入日志；日志只记录脱敏设备标识、业务单号、字节数、耗时和错误分类。
-3. `SendAsync` 只是在当前请求内等待 I/O，不能替代后台任务。不要遗留未等待 Promise、`setTimeout` 或 `Task.Run`。
-4. 每次调用都会创建并关闭连接；不能假设设备会保持会话状态。
-5. Docker 内的 `localhost` 指容器自身。验收前从实际后端容器验证到设备 IP/端口的路由和出站策略。
-6. 载荷、超时和响应均有硬上限；不要通过拆成无限循环规避限制。
-
-## 修改公共能力时的同步门禁
-
-- 源码：`Microi.Server/Microi.V8Engine/Extend/Tcp/V8Tcp.cs` 与 `V8Extend.cs`。
-- 测试：真实 Jint 注入、Byte/Base64/Hex/Text、回环收发、超时/上限/非法参数。
-- 编辑器：`Microi.Client/.../v8-api-server-definitions.js` 与 `Microi.VSCode/src/editor/typingsManager.ts`。
-- 文档与知识：官网中文后端 V8 页面、`microi.skills/README.md`、`v8-utilities` 索引、`Microi.AI/Resource` 镜像和向量资源列表。
-- 验收：目标测试、后端构建、精确重启与健康检查、独立 TCP 回环；真实打印机出纸必须单独报告，不能用回环测试替代。
-
+---
+name: v8-tcp-integration
+description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi V8 TCP 原始字节集成
+
+使用后端 `V8.Tcp` 完成一次性 TCP 连接、原始字节写入和可选的有界响应读取。典型场景是 RAW/JetDirect 9100 网络小票机、串口服务器和 PLC；具体协议帧、校验码与打印业务仍由接口引擎编排。
+
+文档维护时，只在 `microi.doc/docs/doc/v8-engine/v8-server.md` 原位更新后端 API；不要新建重复页面，也不要手工维护英文文档。改变公共契约时同步后端源码/测试、Microi.Client Monaco 定义、Microi.VSCode 类型与生成知识、AI Skill 镜像。
+
+## 先判断是否适用
+
+| 需求 | 选择 |
+|---|---|
+| 后端向设备 TCP 端口发送原始字节 | `V8.Tcp` |
+| HTTP/HTTPS API | `V8.Http`，不要用 TCP 重写 HTTP |
+| RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
+| 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
+| 长连接、TCP 服务端监听、TLS、自定义连接池 | 当前 `V8.Tcp` 不提供；设计独立网关/Worker |
+
+平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
+
+## API 契约
+
+| 方法 | 行为 |
+|---|---|
+| `V8.Tcp.Send({...})` | 连接、发送、关闭，返回 `DosResult` |
+| `await V8.Tcp.SendAsync({...})` | 当前请求内异步发送 |
+| `V8.Tcp.SendAndReceive({...})` | 发送后读取响应，再关闭 |
+| `await V8.Tcp.SendAndReceiveAsync({...})` | 当前请求内异步发送并读取响应 |
+
+必填目标参数：
+
+- `Host`：主机名或 IP；只允许主机，不传 `tcp://` URL。
+- `Port`：1-65535。
+
+发送内容必须且只能选择一组：
+
+- `Bytes`（别名 `RawBytes`、`ByteArray`）：每项为 0-255 的整数。
+- `ByteBase64`（别名 `BytesBase64`、`Base64`）。
+- `Hex`：允许空格、`0x`、`-`、`:`、逗号和下划线分隔。
+- `Text`：按 `Encoding` 编码。默认 `utf-8`，还支持 `ascii`、`gb18030`、`gbk/gb2312`、UTF-16/UTF-32 大小端。
+
+边界参数：
+
+| 参数 | 默认 | 范围 |
+|---|---:|---:|
+| `ConnectTimeout` | 10 秒 | 1-120 秒 |
+| `SendTimeout` | 10 秒 | 1-120 秒 |
+| `ReceiveTimeout` | 3 秒 | 1-120 秒 |
+| `MaxReceiveBytes` | 65536 | 1-1048576 |
+| `NoDelay` | `true` | 布尔值 |
+
+单次发送最多 4 MiB。`Send` 成功数据为 `{BytesSent, RemoteEndPoint}`。收发方法另有 `BytesReceived`、`RawBytes`、`ByteBase64`、`Hex`、`ReceiveEndReason`、`Truncated`；`ReceiveEndReason` 为 `RemoteClosed`、`Timeout` 或 `MaxReceiveBytes`。
+
+## 实现流程
+
+### 1. 固定并授权设备目标
+
+从 SaaS 可信配置或受行权限保护的设备表读取 `Host`、`Port`，按当前用户/门店/租户决定可用设备，再与精确白名单比较。禁止这样写：
+
+```javascript
+// 错误：匿名或普通调用者可扫描后端可达内网。
+return V8.Tcp.Send({
+  Host: V8.Param.Host,
+  Port: V8.Param.Port,
+  Hex: V8.Param.Hex
+});
+```
+
+### 2. 形成一个完整帧
+
+ESC/POS、Modbus TCP 或设备私有协议的命令、正文和校验码应先合成一个完整字节载荷。不要为了拼帧而打开多次连接；包含中文和控制命令时，优先在可信后端/上游把完整帧编码为 `Bytes`、`ByteBase64` 或 `Hex`。
+
+```javascript
+var result = V8.Tcp.Send({
+  Host: '192.168.1.88', // 示例；生产从可信配置读取
+  Port: 9100,
+  Bytes: [
+    27, 64,                         // ESC @ 初始化
+    77, 105, 99, 114, 111, 105, 10,
+    10, 10,
+    29, 86, 0                       // GS V 0 切纸
+  ],
+  ConnectTimeout: 5,
+  SendTimeout: 5
+});
+if (result.Code !== 1) return result;
+```
+
+只有纯文本时可使用打印机常见编码：
+
+```javascript
+var result = await V8.Tcp.SendAsync({
+  Host: '192.168.1.88',
+  Port: 9100,
+  Text: '吾码小票\n合计：12.00\n\n',
+  Encoding: 'gb18030'
+});
+if (result.Code !== 1) return result;
+```
+
+### 3. 需要协议响应时显式收取
+
+```javascript
+var result = V8.Tcp.SendAndReceive({
+  Host: '192.168.1.20',
+  Port: 4001,
+  Hex: '01 03 00 00 00 02 C4 0B',
+  ReceiveTimeout: 3,
+  MaxReceiveBytes: 4096
+});
+if (result.Code !== 1) return result;
+
+var bytes = result.Data.RawBytes;
+var hex = result.Data.Hex;
+```
+
+接收超时是整段接收的总时间。已收到部分数据后超时会返回成功和已有数据，并标记 `ReceiveEndReason='Timeout'`；未收到任何字节则失败。协议必须知道响应长度或结束条件，不能把超时默认当作完整帧。
+
+### 4. 分开判断写入、设备执行和实物结果
+
+- `Code=1` 只表示字节已写入 TCP 连接。
+- 设备协议回执可证明设备接受/处理到哪一步，但仍不一定证明机械动作完成。
+- “小票已打印”需要打印机状态、设备回执或实物/硬件验收证据。
+
+打印不是天然幂等。不确定失败时自动重试可能重复出纸；需要可靠打印时使用业务打印单号、设备回执、状态机以及 Job/MQ/outbox，且重试策略必须识别“尚未发送”和“结果未知”。
+
+## 安全与运行约束
+
+1. TCP 不经过 `V8.Http` 的 SSRF 防护。容器网络策略/防火墙只放行目标设备网段和端口；匿名接口不得暴露任意目标。
+2. 不把票据正文、设备口令、原始帧和响应秘密写入日志；日志只记录脱敏设备标识、业务单号、字节数、耗时和错误分类。
+3. `SendAsync` 只是在当前请求内等待 I/O，不能替代后台任务。不要遗留未等待 Promise、`setTimeout` 或 `Task.Run`。
+4. 每次调用都会创建并关闭连接；不能假设设备会保持会话状态。
+5. Docker 内的 `localhost` 指容器自身。验收前从实际后端容器验证到设备 IP/端口的路由和出站策略。
+6. 载荷、超时和响应均有硬上限；不要通过拆成无限循环规避限制。
+
+## 修改公共能力时的同步门禁
+
+- 源码：`Microi.Server/Microi.V8Engine/Extend/Tcp/V8Tcp.cs` 与 `V8Extend.cs`。
+- 测试：真实 Jint 注入、Byte/Base64/Hex/Text、回环收发、超时/上限/非法参数。
+- 编辑器：`Microi.Client/.../v8-api-server-definitions.js` 与 `Microi.VSCode/src/editor/typingsManager.ts`。
+- 文档与知识：官网中文后端 V8 页面、`microi.skills/README.md`、`v8-utilities` 索引、`Microi.AI/Resource` 镜像和向量资源列表。
+- 验收：目标测试、后端构建、精确重启与健康检查、独立 TCP 回环；真实打印机出纸必须单独报告，不能用回环测试替代。
+<<<<<<< HEAD
+
+=======
+>>>>>>> 79781472ddad81fb5217c2f25438dec3c9894dba