@microi.net/cli 5.6.0 → 5.6.1

package/skills/v8-sql-query/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: v8-sql-query
-description: Microi V8 安全 SQL 查询指南。用于选择 V8.FormEngine _Where 或 V8.Db.FromSql，处理参数化查询、联表、聚合并避免 SQL 注入。
+description: Microi V8 安全 SQL 查询指南。用于选择 V8.FormEngine _Where 或 V8.Db.FromSql，处理参数化查询、联表、聚合并避免 SQL 注入。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi V8 安全 SQL 查询
 
-你正在开发 Microi 吾码平台的 V8 引擎代码。数据库查询有两种方式：`V8.FormEngine`（推荐）和 `V8.Db`（原始 SQL）。必须遵守安全规范。
-
-## 性能门禁（必须执行）
-
-写接口引擎前必须先做数据访问计划，避免“循环套循环查数据库”：
-
-- 禁止在 `for` / `while` / `forEach` / `map` 循环内调用 `V8.FormEngine.GetFormData`、`GetTableData`、`V8.Db.FromSql`、`V8.ApiEngine.Run` 或 `V8.Http.*`。确实无法避免时，必须先说明原因，并加分页、缓存或限流。
-- 多条 Id、编码、外键查询必须一次性用 `_Where: [['Id','In', ids]]`、SQL `IN`、JOIN 或聚合查询取回，再用内存字典映射。
-- 需要父子、主从、用户/部门/角色名称映射时，先批量取关联表，只保留 `_SelectFields` 必要列，不要逐行查名称。
-- 统计、计数、汇总优先让数据库一次 `GROUP BY` / `COUNT` / `SUM` 完成，不要把大表全部拉到 V8 里循环统计。
-- 列表接口必须限制 `_PageSize`，管理端默认不要超过 100，导出或批处理必须显式分批。
-- 每次查询都要写 `_SelectFields` 或明确 SQL 字段列表，禁止 `SELECT *` 用在大表、接口列表、循环前置查询中。
-- 外部 HTTP、翻译、短信、AI 等慢调用不能放在数据库事务和大循环中；要么异步队列，要么批量预处理并设置超时。
-- 返回前自检一次：数据库访问次数应与数据量无关或近似常数级，不能随着行数线性增长为 N 次查询。
-
-## 首选：V8.FormEngine + _Where（自动防注入）
+你正在开发 Microi 吾码平台的 V8 引擎代码。数据库查询有两种方式：`V8.FormEngine`（推荐）和 `V8.Db`（原始 SQL）。必须遵守安全规范。
+
+## 性能门禁（必须执行）
+
+写接口引擎前必须先做数据访问计划，避免“循环套循环查数据库”：
+
+- 禁止在 `for` / `while` / `forEach` / `map` 循环内调用 `V8.FormEngine.GetFormData`、`GetTableData`、`V8.Db.FromSql`、`V8.ApiEngine.Run` 或 `V8.Http.*`。确实无法避免时，必须先说明原因，并加分页、缓存或限流。
+- 多条 Id、编码、外键查询必须一次性用 `_Where: [['Id','In', ids]]`、SQL `IN`、JOIN 或聚合查询取回，再用内存字典映射。
+- 需要父子、主从、用户/部门/角色名称映射时，先批量取关联表，只保留 `_SelectFields` 必要列，不要逐行查名称。
+- 统计、计数、汇总优先让数据库一次 `GROUP BY` / `COUNT` / `SUM` 完成，不要把大表全部拉到 V8 里循环统计。
+- 列表接口必须限制 `_PageSize`，管理端默认不要超过 100，导出或批处理必须显式分批。
+- 每次查询都要写 `_SelectFields` 或明确 SQL 字段列表，禁止 `SELECT *` 用在大表、接口列表、循环前置查询中。
+- 外部 HTTP、翻译、短信、AI 等慢调用不能放在数据库事务和大循环中；要么异步队列，要么批量预处理并设置超时。
+- 返回前自检一次：数据库访问次数应与数据量无关或近似常数级，不能随着行数线性增长为 N 次查询。
+
+## 首选：V8.FormEngine + _Where（自动防注入）
 
 `_Where` 是参数化查询语法，自动防 SQL 注入，**永远优先使用**。
 
@@ -75,57 +75,59 @@ var newWhere = V8.Method.ParseWhere(V8.Param._Where);
 V8.FormEngine.GetTableData('Table', { _Where: newWhere });
 ```
 
-## 次选：V8.Db.FromSql（仅 SQL 字符串 + AddInParameter）
-
-> **⚠️ FormEngine 优先原则：** 增删改操作（INSERT / UPDATE / DELETE）必须**优先**使用 `V8.FormEngine.AddFormData` / `UptFormData` / `UptFormDataByWhere` / `DelFormData` 等方法。**只有**多表 JOIN、复杂子查询、GROUP BY 聚合等 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`。
-
-> **⚠️ FromSql 调用规则：** `V8.Db.FromSql` 在 V8 中只传 SQL 字符串，不要把动态值作为第二个或后续参数传给 `FromSql`。动态值必须用链式 `.AddInParameter('@p0', value)` 绑定；否则会生成平台不支持的调用签名。
-
-```javascript
-// ❌ 错误形态：不要把动态值作为 FromSql 的第二个参数传入
-
-// ✅ 优先：改用 FormEngine（单表增删改查都优先这样写）
-V8.FormEngine.UptFormData('t', { Id: id, A: val1, B: val2 });
-
-// ✅ 必须用原生 SQL 时：FromSql 只传 SQL，参数用 AddInParameter
-V8.Db.FromSql("UPDATE t SET A=@p0, B=@p1 WHERE Id=@p2")
-     .AddInParameter("@p0", val1)
-     .AddInParameter("@p1", val2)
-     .AddInParameter("@p2", id)
-     .ExecuteNonQuery();
-```
+## 次选：V8.Db.FromSql（仅 SQL 字符串 + AddInParameter）
+
+> **⚠️ FormEngine 优先原则：** 增删改操作（INSERT / UPDATE / DELETE）必须**优先**使用 `V8.FormEngine.AddFormData` / `UptFormData` / `UptFormDataByWhere` / `DelFormData` 等方法。**只有**多表 JOIN、复杂子查询、GROUP BY 聚合等 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`。
+
+> **⚠️ FromSql 调用规则：** `V8.Db.FromSql` 在 V8 中只传 SQL 字符串，不要把动态值作为第二个或后续参数传给 `FromSql`。动态值必须用链式 `.AddInParameter('@p0', value)` 绑定；否则会生成平台不支持的调用签名。
+
+> **共享事务：** `V8.Db` 是主库会话，`V8.Db.FromSql` 不会自动加入接口引擎事务。需要与表单、其它 SQL 或流程共同提交/回滚的操作，必须使用 `V8.DbTrans.FromSql`；依赖本事务尚未提交结果的查询也一样。`V8.FormEngine`、`V8.ApiEngine.Run` 继续显式传第三参数 `V8.DbTrans`。禁止从安全代理取内部事务并自行提交。
+
+```javascript
+// ❌ 错误形态：不要把动态值作为 FromSql 的第二个参数传入
+
+// ✅ 优先：改用 FormEngine（单表增删改查都优先这样写）
+V8.FormEngine.UptFormData('t', { Id: id, A: val1, B: val2 });
+
+// ✅ 必须用原生 SQL 时：FromSql 只传 SQL，参数用 AddInParameter
+V8.DbTrans.FromSql("UPDATE t SET A=@p0, B=@p1 WHERE Id=@p2")
+     .AddInParameter("@p0", val1)
+     .AddInParameter("@p1", val2)
+     .AddInParameter("@p2", id)
+     .ExecuteNonQuery();
+```
 
 当 `_Where` 无法满足复杂查询（多表 JOIN、子查询、聚合统计）时使用 `V8.Db`：
 
 ```javascript
-// ✅ 安全：使用 @p0, @p1 占位符，并用 AddInParameter 绑定
-var list = V8.Db.FromSql(
-  'SELECT a.Id, a.Name, b.OrderCount FROM Customer a LEFT JOIN (SELECT CustomerId, COUNT(*) OrderCount FROM OrderHeader GROUP BY CustomerId) b ON a.Id = b.CustomerId WHERE a.Status = @p0'
-).AddInParameter("@p0", 1).ToArray();
-
-// ✅ 安全：多个参数
-var row = V8.Db.FromSql(
-  'SELECT * FROM SysUser WHERE Account = @p0 AND DeptId = @p1'
-).AddInParameter("@p0", V8.Param.account)
- .AddInParameter("@p1", V8.Param.deptId)
- .First();
-
-// 统计
-var count = V8.Db.FromSql(
-  'SELECT COUNT(*) FROM OrderHeader WHERE Status = @p0 AND CreateTime >= @p1'
-).AddInParameter("@p0", 1)
- .AddInParameter("@p1", V8.Param.startDate)
- .ToScalar();
-
-// 非查询（UPDATE / INSERT / DELETE）
-V8.Db.FromSql(
-  'UPDATE SysUser SET LastLoginTime = @p0 WHERE Id = @p1'
-).AddInParameter("@p0", DateNow('yyyy-MM-dd HH:mm:ss'))
- .AddInParameter("@p1", V8.CurrentUser.Id)
- .ExecuteNonQuery();
-```
-
-> 老版本兼容：要把维护接口复制到旧部署时，不要假定 `DateNow` 或 `System.DateTime.Now.ToString(...)` 一定可用。若数据库类型固定，可直接使用该数据库的当前时间表达式（例如 MySQL 的 `NOW()`）；跨数据库代码则应按数据库类型选择表达式或传入平台已确认支持的时间值。
+// ✅ 安全：使用 @p0, @p1 占位符，并用 AddInParameter 绑定
+var list = V8.Db.FromSql(
+  'SELECT a.Id, a.Name, b.OrderCount FROM Customer a LEFT JOIN (SELECT CustomerId, COUNT(*) OrderCount FROM OrderHeader GROUP BY CustomerId) b ON a.Id = b.CustomerId WHERE a.Status = @p0'
+).AddInParameter("@p0", 1).ToArray();
+
+// ✅ 安全：多个参数
+var row = V8.Db.FromSql(
+  'SELECT * FROM SysUser WHERE Account = @p0 AND DeptId = @p1'
+).AddInParameter("@p0", V8.Param.account)
+ .AddInParameter("@p1", V8.Param.deptId)
+ .First();
+
+// 统计
+var count = V8.Db.FromSql(
+  'SELECT COUNT(*) FROM OrderHeader WHERE Status = @p0 AND CreateTime >= @p1'
+).AddInParameter("@p0", 1)
+ .AddInParameter("@p1", V8.Param.startDate)
+ .ToScalar();
+
+// 非查询（UPDATE / INSERT / DELETE）
+V8.DbTrans.FromSql(
+  'UPDATE SysUser SET LastLoginTime = @p0 WHERE Id = @p1'
+).AddInParameter("@p0", DateNow('yyyy-MM-dd HH:mm:ss'))
+ .AddInParameter("@p1", V8.CurrentUser.Id)
+ .ExecuteNonQuery();
+```
+
+> 老版本兼容：要把维护接口复制到旧部署时，不要假定 `DateNow` 或 `System.DateTime.Now.ToString(...)` 一定可用。若数据库类型固定，可直接使用该数据库的当前时间表达式（例如 MySQL 的 `NOW()`）；跨数据库代码则应按数据库类型选择表达式或传入平台已确认支持的时间值。
 
 ### V8.Db 方法速查
 
@@ -140,52 +142,52 @@ V8.Db.FromSql(
 
 ### 读写分离
 
-```javascript
-V8.Db.FromSql(...)      // 主库（读写）
-V8.DbRead.FromSql(...)  // 从库（只读，适合报表和大量查询）
+```javascript
+V8.Db.FromSql(...)      // 主库（读写）
+V8.DbRead.FromSql(...)  // 从库（只读，适合报表和大量查询）
 // 未部署读写分离时 V8.DbRead 与 V8.Db 一致
 ```
 
-### 跨应用查询（扩展数据库）
-
-```javascript
-var list = V8.Dbs.OracleDB1.FromSql('SELECT * FROM Table WHERE Id = @p0')
-  .AddInParameter("@p0", id)
-  .ToArray();
-
-// 不写入 microi_database：创建仅当前请求使用的临时会话
-var tempDb = V8.Dbs.Open(
-  'SqlServer',
-  'Server=127.0.0.1,1433;Database=app;User Id=user;Password=***;TrustServerCertificate=True;'
-);
-var tempList = tempDb.FromSql('SELECT Id, Name FROM Customer WHERE Status = @p0')
-  .AddInParameter('@p0', 1)
-  .ToArray();
-```
-
-`V8.Dbs.Open` 与保存连接均只支持 Dos.ORM 已认证的 `MySql`、`SqlServer`、`Oracle`、`PostgreSql`、`DaMeng`、`KingBase`。动态连接串只能来自可信服务端密钥或管理员代码，禁止使用 `V8.Param.ConnectionString`，禁止记录或返回。外部 SQL 的表名、列名、排序字段必须来自已校验元数据白名单；动态值继续使用 `AddInParameter`。
-
-MCP 结构发现使用 `microi_inspect_external_database`，安全抽样默认使用只读的 `microi_query_external_database`。当用户明确要求数据库管理级能力时，使用独立的 `microi_execute_external_database`：它只允许后端确认的 `Level >= 9999` 当前用户调用，显式确认后可执行目标数据库账号有权执行的任意 DML、DDL、存储过程、数据库原生命令或多语句。输出行数限制只保护 MCP 传输，不限制数据库副作用；审计只记录 SQL 哈希、长度、模式和结果，不得记录 SQL 正文、连接串或密码。
-
-不要用 `microi_get_db_schema` 读取第三方库，也不要在对话中搬运全库数据；持续同步应创建参数化、分页、幂等的服务端任务。最高权限入口不等于跨租户，也不能超越目标数据库账号自身权限。
+### 跨应用查询（扩展数据库）
+
+```javascript
+var list = V8.Dbs.OracleDB1.FromSql('SELECT * FROM Table WHERE Id = @p0')
+  .AddInParameter("@p0", id)
+  .ToArray();
+
+// 不写入 microi_database：创建仅当前请求使用的临时会话
+var tempDb = V8.Dbs.Open(
+  'SqlServer',
+  'Server=127.0.0.1,1433;Database=app;User Id=user;Password=***;TrustServerCertificate=True;'
+);
+var tempList = tempDb.FromSql('SELECT Id, Name FROM Customer WHERE Status = @p0')
+  .AddInParameter('@p0', 1)
+  .ToArray();
+```
+
+`V8.Dbs.Open` 与保存连接均只支持 Dos.ORM 已认证的 `MySql`、`SqlServer`、`Oracle`、`PostgreSql`、`DaMeng`、`KingBase`。动态连接串只能来自可信服务端密钥或管理员代码，禁止使用 `V8.Param.ConnectionString`，禁止记录或返回。外部 SQL 的表名、列名、排序字段必须来自已校验元数据白名单；动态值继续使用 `AddInParameter`。
+
+MCP 结构发现使用 `microi_inspect_external_database`，安全抽样默认使用只读的 `microi_query_external_database`。当用户明确要求数据库管理级能力时，使用独立的 `microi_execute_external_database`：它只允许后端确认的 `Level >= 9999` 当前用户调用，显式确认后可执行目标数据库账号有权执行的任意 DML、DDL、存储过程、数据库原生命令或多语句。输出行数限制只保护 MCP 传输，不限制数据库副作用；审计只记录 SQL 哈希、长度、模式和结果，不得记录 SQL 正文、连接串或密码。
+
+不要用 `microi_get_db_schema` 读取第三方库，也不要在对话中搬运全库数据；持续同步应创建参数化、分页、幂等的服务端任务。最高权限入口不等于跨租户，也不能超越目标数据库账号自身权限。
 
 ## 数据库事务
 
 ### 接口引擎事务（自动管理）
 
 ```javascript
-// 接口引擎中 V8.Db 自动开启事务：
+// 接口引擎创建 V8.DbTrans；V8.Db 是独立主库会话，不自动加入它：
 // 返回 Code=1 → 自动提交事务
 // 返回 Code≠1 → 自动回滚事务
 // 手动调用 V8.DbTrans.Commit() 或 V8.DbTrans.Rollback() 均无效
-V8.Db.FromSql('UPDATE Account SET Balance = Balance - @p0 WHERE Id = @p1')
-  .AddInParameter("@p0", 100)
-  .AddInParameter("@p1", fromId)
-  .ExecuteNonQuery();
-V8.Db.FromSql('UPDATE Account SET Balance = Balance + @p0 WHERE Id = @p1')
-  .AddInParameter("@p0", 100)
-  .AddInParameter("@p1", toId)
-  .ExecuteNonQuery();
+V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance - @p0 WHERE Id = @p1')
+  .AddInParameter("@p0", 100)
+  .AddInParameter("@p1", fromId)
+  .ExecuteNonQuery();
+V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance + @p0 WHERE Id = @p1')
+  .AddInParameter("@p0", 100)
+  .AddInParameter("@p1", toId)
+  .ExecuteNonQuery();
 
 // V8.DbTrans 可传给 FormEngine 和 ApiEngine.Run 共享事务
 V8.FormEngine.UptFormData('Table1', { Id: 'x', Status: 1 }, V8.DbTrans);
@@ -196,16 +198,16 @@ V8.ApiEngine.Run('other-engine', { Id: 'x' }, V8.DbTrans);
 
 ```javascript
 // 扩展数据库需要手动管理事务
-var exTrans = V8.Dbs.OracleDB1.BeginTransaction();
-try {
-  exTrans.FromSql('UPDATE t1 SET a = @p0 WHERE Id = @p1')
-    .AddInParameter("@p0", 1)
-    .AddInParameter("@p1", id1)
-    .ExecuteNonQuery();
-  exTrans.FromSql('UPDATE t2 SET b = @p0 WHERE Id = @p1')
-    .AddInParameter("@p0", 2)
-    .AddInParameter("@p1", id2)
-    .ExecuteNonQuery();
+var exTrans = V8.Dbs.OracleDB1.BeginTransaction();
+try {
+  exTrans.FromSql('UPDATE t1 SET a = @p0 WHERE Id = @p1')
+    .AddInParameter("@p0", 1)
+    .AddInParameter("@p1", id1)
+    .ExecuteNonQuery();
+  exTrans.FromSql('UPDATE t2 SET b = @p0 WHERE Id = @p1')
+    .AddInParameter("@p0", 2)
+    .AddInParameter("@p1", id2)
+    .ExecuteNonQuery();
   exTrans.Commit();
 } catch (ex) {
   exTrans.Rollback();
@@ -224,11 +226,11 @@ V8.Db.FromSql(sql).ToArray();  // SQL 注入漏洞！
 // ❌ 禁止：动态拼接表名
 var sql = "SELECT * FROM " + V8.Param.tableName + " WHERE Id = @p0";
 
-// ✅ 正确做法：单表查询优先使用 FormEngine + _Where
-var result = V8.FormEngine.GetTableData('SysUser', {
-  _Where: [['Account', '=', V8.Param.account]],
-  _PageSize: 20
-});
+// ✅ 正确做法：单表查询优先使用 FormEngine + _Where
+var result = V8.FormEngine.GetTableData('SysUser', {
+  _Where: [['Account', '=', V8.Param.account]],
+  _PageSize: 20
+});
 ```
 
 ## 常见查询模式
@@ -271,21 +273,21 @@ var result = V8.FormEngine.GetTableData('Customer', {
 ### 关联查询（SQL JOIN）
 
 ```javascript
-var list = V8.Db.FromSql(`
-  SELECT o.Id, o.OrderNo, o.TotalAmount, c.Name AS CustomerName
-  FROM OrderHeader o
-  INNER JOIN Customer c ON o.CustomerId = c.Id
-  WHERE o.Status = @p0 AND o.CreateTime >= @p1
-  ORDER BY o.CreateTime DESC
-`).AddInParameter("@p0", 1)
-  .AddInParameter("@p1", V8.Param.startDate)
-  .ToArray();
-```
-
-## 注意事项
-
-- `V8.Db.FromSql` 只传 SQL 字符串，参数占位符从 `@p0` 开始递增，动态值用 `.AddInParameter("@p0", value)` 绑定
-- 服务端 `V8.FormEngine` 操作默认不触发表单 V8 事件；确需触发时在参数中加 `_InvokeType: 'Client'`
+var list = V8.Db.FromSql(`
+  SELECT o.Id, o.OrderNo, o.TotalAmount, c.Name AS CustomerName
+  FROM OrderHeader o
+  INNER JOIN Customer c ON o.CustomerId = c.Id
+  WHERE o.Status = @p0 AND o.CreateTime >= @p1
+  ORDER BY o.CreateTime DESC
+`).AddInParameter("@p0", 1)
+  .AddInParameter("@p1", V8.Param.startDate)
+  .ToArray();
+```
+
+## 注意事项
+
+- `V8.Db.FromSql` 只传 SQL 字符串，参数占位符从 `@p0` 开始递增，动态值用 `.AddInParameter("@p0", value)` 绑定
+- 服务端 `V8.FormEngine` 操作默认不触发表单 V8 事件；确需触发时在参数中加 `_InvokeType: 'Client'`
 - 查询结果数量较大时务必分页，`_PageSize` 默认最大 1000
 - `V8.DbRead` 适用于不需要实时性的报表查询
 - 接口引擎的事务由平台自动管理，**不要手动调用** `V8.DbTrans.Commit/Rollback`

package/skills/v8-table-event/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: v8-table-event
-description: Microi V8 表单事件开发。用于编写 InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8 和事务感知事件。
+description: Microi V8 表单事件开发。用于编写 InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8 和事务感知事件。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -13,29 +13,29 @@ description: Microi V8 表单事件开发。用于编写 InFormV8、SubmitFormV8
 <!-- microi-progressive:chunk id=v8-table-event-000 sha256=dd86294c8cf42f580b2eb806d981c239c0efc2934505c0716e804de2f8a9235c -->
 ## 本地优先与版本头（必做）
 
-AI 本地开发表单 V8 事件时，优先修改 `microi-v8-engine/<租户>/<项目>/表单引擎/.../<事件Label>（<EventType>）.js` 本地文件，再通过 MCP 或 VS Code 插件同步到数据库。文件中文名必须取 `diy_table` 对应 `diy_field.Label`，其中 `SubmitFormV8` 为 `前端表单提交前V8事件（SubmitFormV8）.js`，`OutFormV8` 为 `前端表单提交后V8事件（OutFormV8）.js`。若插件显示“本地和远端不一致”，先读取本地与远端并合并有效差异，不能直接覆盖。
+AI 本地开发表单 V8 事件时，优先修改 `microi-v8-engine/<租户>/<项目>/表单引擎/.../<事件Label>（<EventType>）.js` 本地文件，再通过 MCP 或 VS Code 插件同步到数据库。文件中文名必须取 `diy_table` 对应 `diy_field.Label`，其中 `SubmitFormV8` 为 `前端表单提交前V8事件（SubmitFormV8）.js`，`OutFormV8` 为 `前端表单提交后V8事件（OutFormV8）.js`。若插件显示“本地和远端不一致”，先读取本地与远端并合并有效差异，不能直接覆盖。
 
 每一次修改、上传、推送 `InFormV8.js`、`SubmitFormV8.js`、`SubmitBeforeServerV8.js`、`SubmitAfterServerV8.js`、`OutFormV8.js`、`DataFilterV8.js` 等事件文件，都必须维护顶部版本区域。版本号从 `v1.0.0` 开始；每次上传/推送/修改递增 1；补丁位和次版本位最大为 9 并向前进位（`v1.0.9 -> v1.1.0`、`v1.9.9 -> v2.0.0`、`v9.9.9 -> v10.0.0`）。代码头只写完整功能说明，不写修改历史、时间戳或 ChangeLog。
 
 ```javascript
 /*
  * V8 Event
- * TableKey: 示例表Key
+ * TableKey: 示例表Key
  * EventType: SubmitBeforeServerV8
  * Version: v1.0.0
- * 功能说明：
+ * 功能说明：
  * - 完整说明该事件的触发时机、校验/加工逻辑、读写字段和阻止提交条件。
  */
 ```
 
-同步流程：`读取远端 -> 修改本地并递增语义版本头 -> JS 语法检查 -> 保存远端 -> 回读远端确认版本头一致 -> 查询 mic_data_version 确认形成新版本 -> 执行触发该事件的最小表单操作验证`。表单设计器保存和 MCP 保存共用服务端代码版本链路；只有代码真实变化才新增版本，普通布局/字段属性保存不得产生代码版本。修改记录不得写进事件代码头。
-
-使用 MCP 时，先调用 `microi_list_events` 发现事件，再用
-`microi_get_event_code` 读取目标源码；修改后通过 `microi_save_event_code`
-保存并回读。不要把接口引擎的保存工具用于表单事件，也不要在未读取远端
-版本时直接覆盖。
-
-生成 V8 事件代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；提交前校验、提交后联动、字段显隐、数据脱敏、跨表写入、复杂条件判断等代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。
+同步流程：`读取远端 -> 修改本地并递增语义版本头 -> JS 语法检查 -> 保存远端 -> 回读远端确认版本头一致 -> 查询 mic_data_version 确认形成新版本 -> 执行触发该事件的最小表单操作验证`。表单设计器保存和 MCP 保存共用服务端代码版本链路；只有代码真实变化才新增版本，普通布局/字段属性保存不得产生代码版本。修改记录不得写进事件代码头。
+
+使用 MCP 时，先调用 `microi_list_events` 发现事件，再用
+`microi_get_event_code` 读取目标源码；修改后通过 `microi_save_event_code`
+保存并回读。不要把接口引擎的保存工具用于表单事件，也不要在未读取远端
+版本时直接覆盖。
+
+生成 V8 事件代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；提交前校验、提交后联动、字段显隐、数据脱敏、跨表写入、复杂条件判断等代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-table-event-001 sha256=7bad55ca6781e6ca458a0333a47c71a3bad30334d146e940496c45c4ffa7ddf5 -->
@@ -57,8 +57,8 @@ AI 本地开发表单 V8 事件时，优先修改 `microi-v8-engine/<租户>/<
 - 后端 V8 事件 / 接口引擎中调用 `V8.FormEngine` 增删改 → **不触发**表单 V8 事件
 - 传入 `_InvokeType: 'Client'` → **触发**表单 V8 事件
 - Postman 等直接调用接口 → 前端事件**不执行**，后端事件**仍执行**
-- 服务器端提交前/后 V8 事件在**同一事务**中执行
-- `diy_table.V8Limit` 是表后端提交前、提交后和数据处理 V8 的正向开关：缺失、`null`、`0/false` 均不设置 Jint 单次超时、语句、函数递归和累计分配预算，只有 `1/true` 才启用这些限制。旧 `V8Unlimited` 仅在新字段不存在时反向推断，新的 MCP、Manifest 和应用资源只写 `V8Limit`。进程常驻内存、取消、并发、接口嵌套深度、权限和数据库保护始终生效。
+- 服务器端提交前/后 V8 事件在**同一事务**中执行
+- `diy_table.V8Limit` 是表后端提交前、提交后和数据处理 V8 的正向开关：缺失、`null`、`0/false` 均不设置 Jint 单次超时、语句、函数递归和累计分配预算，只有 `1/true` 才启用这些限制。旧 `V8Unlimited` 仅在新字段不存在时反向推断，新的 MCP、Manifest 和应用资源只写 `V8Limit`。进程常驻内存、取消、并发、接口嵌套深度、权限和数据库保护始终生效。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-table-event-003 sha256=65a1e728982d4e534d06dc2440eac111fe53a08f0a3012c6a9f8b1de45b4b81f -->
@@ -75,7 +75,7 @@ if (V8.LoadMode === 'Design') return;
 
 - ❌ **禁止** 在 `SubmitFormV8.js` 中调 `V8.FormSubmit()` —— 无限递归
 - ❌ **禁止** 在 `FieldValueChange` 中 `V8.FormSet(同字段, ...)` —— 循环触发
-- ❌ **禁止** 在后端提交前/后事件中再次写当前表；即使默认 Server 调用不递归，也可能覆盖本次增量数据、引发死锁或重复副作用。确需跨表联动时使用同一 `V8.DbTrans`，且不要传 `_InvokeType:'Client'`
+- ❌ **禁止** 在后端提交前/后事件中再次写当前表；即使默认 Server 调用不递归，也可能覆盖本次增量数据、引发死锁或重复副作用。确需跨表联动时使用同一 `V8.DbTrans`，且不要传 `_InvokeType:'Client'`
 
 ### 3. 阻止提交（后端）
 
@@ -96,10 +96,17 @@ V8.ApiEngine.Run('other-engine', { Form: V8.Form }, V8.DbTrans);
 // 不传 V8.DbTrans 会导致并行事务、可能死锁或脏读
 ```
 
-### 5. 模板引擎与 DataFilterV8 的区别
+### 5. 模板引擎与 DataFilterV8 的区别
 
 - 数据**加工**（计算字段、脱敏、查关联表名）→ 用 `DataFilterV8`（后端，每行执行，可用 `V8.CacheData` 防 N+1）
-- 数据**渲染**（颜色徽章、HTML、图片）→ 用【表格 V8 模板引擎】，详见 `v8-template-engine/SKILL.md`
+- 数据**渲染**（颜色徽章、HTML、图片）→ 用【表格 V8 模板引擎】，详见 `v8-template-engine/SKILL.md`
+
+### 6. 新增主键与跨表引用
+
+- 原生新增管线先独立确定真实主键；`SubmitBeforeServerV8` 中的 `V8.Form.Id` 可能尚未提供。不得自行给 `V8.Form.Id` 补一个 GUID，并把它当作最终插入主键去创建条码、明细、关系或审计。
+- 依赖最终主键的附属记录放在 `SubmitAfterServerV8`，核验 `V8.Form.Id` 后在同一 `V8.DbTrans` 中回读主记录，再创建附属记录。After 仍在提交前，任一附属写入失败必须返回失败并回滚主表；外部消息仍走 outbox。
+- 原生删除事件的权威删除前记录由 `V8.Form` 提供，`V8.OldForm` 可能为空；删除审计、关系清理应按 `FormSubmitAction` 选择上下文。原生删除的 `Form.Version` 来自数据库快照，不能把它当作客户端最后看到的版本。需要拒绝过期删除时，通过受控接口接收期望版本、锁定主库记录并验证，再在同一事务执行删除。
+- 回归必须比较“新增接口返回 Id、主表实际 Id、附属外键、审计 RowId”四者一致，并覆盖唯一冲突时主表及附属记录同时回滚，不能只断言新增接口 `Code=1`。
 
 ---
 
@@ -108,8 +115,8 @@ V8.ApiEngine.Run('other-engine', { Form: V8.Form }, V8.DbTrans);
 ## 前端事件特有 API
 
 ```javascript
-// 普通 diy-form 中设置字段值（触发目标字段值变更事件）
-// diy-table 列表上下文只更新当前行和模板，不递归触发目标字段 V8
+// 普通 diy-form 中设置字段值（触发目标字段值变更事件）
+// diy-table 列表上下文只更新当前行和模板，不递归触发目标字段 V8
 V8.FormSet('FieldName', 'value');
 V8.FormSet('DropdownField', { Id: 1, Name: '选项' }); // 下拉框
 
@@ -127,9 +134,9 @@ var isReadonly = V8.Field.UserName.Readonly;
 V8.Tips('操作成功', true);    // 成功提示（1秒消失）
 V8.Tips('操作失败', false);   // 错误提示（5秒消失）
 
-// 确认框
-V8.ConfirmTips('确定删除？', function() { /* 确定 */ }, function() { /* 取消 */ });
-// content 使用 HTML 模式渲染；只能传固定文案或已转义内容，复杂交互用 OpenAppDialog
+// 确认框
+V8.ConfirmTips('确定删除？', function() { /* 确定 */ }, function() { /* 取消 */ });
+// content 使用 HTML 模式渲染；只能传固定文案或已转义内容，复杂交互用 OpenAppDialog
 
 // 前端 HTTP 请求
 V8.Post('/api/xxx', { key: 'value' }, function(res) { });

package/skills/v8-table-event/references/progressive-01-informv8-js-/350/241/250/345/215/225/346/211/223/345/274/200/344/272/213/344/273/266.md

@@ -104,13 +104,13 @@ if (V8.FormSubmitAction === 'Insert' || V8.FormSubmitAction === 'Update') {
 // 此时数据已成功写入数据库（仍在事务中）
 // 返回 { Code: 0 } 仍可回滚事务
 
-// 新增后：自动创建关联数据。保持默认 Server 调用，不触发目标表事件
-if (V8.FormSubmitAction === 'Insert') {
-  V8.FormEngine.AddFormData('UserProfile', {
-    UserId: V8.Form.Id,
-    NickName: V8.Form.Name
-  }, V8.DbTrans);
-}
+// 新增后：自动创建关联数据。保持默认 Server 调用，不触发目标表事件
+if (V8.FormSubmitAction === 'Insert') {
+  V8.FormEngine.AddFormData('UserProfile', {
+    UserId: V8.Form.Id,
+    NickName: V8.Form.Name
+  }, V8.DbTrans);
+}
 
 // 更新后：同步更新其它表的冗余字段
 if (V8.FormSubmitAction === 'Update') {
@@ -129,14 +129,14 @@ V8.ApiEngine.Run('send-notification', {
 }, V8.DbTrans);
 
 // 记录操作日志
-V8.Method.AddSysLog({
+V8.Method.AddSysLog({
   Title: V8.FormSubmitAction + ' ' + V8.TableModel.Name,
   Content: JSON.stringify({ Id: V8.Form.Id }),
   Type: '业务日志'
-});
-```
-
-`SubmitAfterServerV8` 的“After”仍是“写入后、提交前”。需要在事务真正提交后才发布的缓存版本、跨节点通知等副作用，不能直接在事件中执行。平台为 `microi_database` 提供专用 `V8.Method.RefreshExtensionDatabases()`：事件调用时只登记提交后回调，提交成功才递增当前租户共享 Redis 版本，回滚时自动丢弃。普通业务的外部消息仍优先使用同事务 outbox，不能把任意不可撤销副作用都塞进内存回调。
+});
+```
+
+`SubmitAfterServerV8` 的“After”仍是“写入后、提交前”。需要在事务真正提交后才发布的缓存版本、跨节点通知等副作用，不能直接在事件中执行。平台为 `microi_database` 提供专用 `V8.Method.RefreshExtensionDatabases()`：事件调用时只登记提交后回调，提交成功才递增当前租户共享 Redis 版本，回滚时自动丢弃。普通业务的外部消息仍优先使用同事务 outbox，不能把任意不可撤销副作用都塞进内存回调。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-table-event-009 sha256=d415302a8108d9e11755a046bdbffe0c84a135ec6ed0e6b1dc3fc128a8ef38b6 -->
@@ -181,21 +181,21 @@ if (V8.Form.Phone) {
 
 | 变量 | 说明 | 可用事件 |
 |------|------|---------|
-| `V8.Form` | 当前表单数据（新增时也有 Id） | 全部 |
-| `V8.OldForm` | 已加载的修改前旧数据 | 普通表单；提交前/后 |
+| `V8.Form` | 当前表单数据；原生新增提交前可能没有 Id，依赖真实主键的跨表写入在提交后事件执行 | 全部 |
+| `V8.OldForm` | 已加载的修改前旧数据 | 普通表单；提交前/后 |
 | `V8.FormMode` | `'Add'` / `'Edit'` / `'View'` | 全部 |
 | `V8.FormOutAction` | `'Insert'`/`'Update'`/`'Close'`/`'Delete'` | FormOut |
 | `V8.FormSubmitAction` | `'Insert'` / `'Update'` / `'Delete'` | SubmitBefore |
 | `V8.EventName` | 当前事件名 | 全部 |
 | `V8.CurrentUser` | 当前用户 | 全部 |
 | `V8.TableId` / `V8.TableName` | 当前表 Id / Name | 全部 |
-| `V8.SelectedData` / `V8.TableRowSelected` | 选中的行数组 | 列表/批量按钮 |
+| `V8.SelectedData` / `V8.TableRowSelected` | 选中的行数组 | 列表/批量按钮 |
 | `V8.CurrentTableData` | 当前表当页数据 | 全部 |
 | `V8.ClientType` | `'PC'`/`'IOS'`/`'Android'`/`'H5'`/`'WeChat'` | 全部 |
-| `V8.ThisValue` | 当前字段新值：可能是对象、原始值或行内 `{New,Old}` | FieldValueChange |
-| `V8.OldValue` | 当前字段旧值，仅行内编辑可靠 | 表格行内 FieldValueChange |
-| `V8.KeyCode` | 键盘事件的键码 | FieldOnKeyup |
-| `V8.Event` | 原生事件；键盘事件目前不提供 | FieldSlotButtonClick 等显式事件 |
+| `V8.ThisValue` | 当前字段新值：可能是对象、原始值或行内 `{New,Old}` | FieldValueChange |
+| `V8.OldValue` | 当前字段旧值，仅行内编辑可靠 | 表格行内 FieldValueChange |
+| `V8.KeyCode` | 键盘事件的键码 | FieldOnKeyup |
+| `V8.Event` | 原生事件；键盘事件目前不提供 | FieldSlotButtonClick 等显式事件 |
 | `V8.ParentV8` | 子表中访问父表 V8 对象 | 子表事件 |
 
 ### 后端事件