@microi.net/cli 5.7.3 → 5.7.5

package/skills/v8-workflow/SKILL.md

@@ -1,21 +1,48 @@
 ---
 name: v8-workflow
-description: Microi V8 工作流事件指南。用于编写审批流条件、节点 V8 代码、wf_flowdesign/wf_node/wf_line 逻辑、V8.WF 变量和工作流路由。
+description: Microi V8 工作流事件指南。用于编写审批流条件、节点 V8 代码、wf_flowdesign/wf_node/wf_line 逻辑、V8.WF 变量和工作流路由。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi V8 工作流事件开发
 
-你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
-
-## 后端类库与接口边界
-
-- 工作流运行时固定属于独立 `Microi.WorkFlow` 类库；`Microi.net.Api` 只注册 `AddMicroiWorkFlow()`，不得恢复 `WorkFlowController` 或把流程业务写回 `Program.cs`。
-- 对外与旧移动端路由统一由官方 Managed `platform-workflow` 接口引擎承载，历史 `/api/WorkFlow/*` 地址写入同一记录的 `ApiRoutes`。租户个性化逻辑写在 CreateIfMissing `platform-workflow-custom-hook`，默认只返回 `{ Code: 1 }`。
-- `Microi.Core` 只保留避免循环引用所需的 `IWFEngine`、模型和最小运行时合同；发起、审批、撤回、移交、退回及审批人计算实现在 `Microi.WorkFlow`，并按职责拆分 partial 文件。
-- 新业务规则仍优先写工作流 V8/接口引擎。只有事务、流程状态机、可信当前用户和运行时内核缺少不可伪造的底层原子时，才扩展 `Microi.WorkFlow`。
-- 官方发布时 `Microi.WorkFlow` 必须生成 NuGet 包，并与 `Microi.AI` 使用同一 Obfuscar 配置加密后替换包内 DLL；不得推送未加密的 WorkFlow 包。开源安装只消费 NuGet，不要求存在私有源码。
+## AI / MCP 生成流程的必检契约
+
+这里的流程是 `wf_flowdesign + wf_node + wf_line` 审批引擎，不是 `ai-workflow`。
+先用 `microi_get_db_schema` 查询 `wf_flowdesign`、`wf_node`、`wf_line`、
+`sys_menu` 与目标业务表，再用 `microi_list_roles` 或管理员只读表查询确认当前租户的
+真实用户、角色、部门、岗位 Id。人工节点 `Approve/Countersign/End` 必须配置
+`Users/Roles/Depts/BindJobs` 至少一种真实 `[{"Id":"...","Name":"..."}]`
+绑定，或明确采用上游节点 `AllowSelectUsers=1` 手动选人。
+`SameDeptApprove=1` 只筛选候选人，不能单独产生审批人。
+不能把 `Roles:"Manager"`、字符串 Id 数组或另一个租户的 Id 当作绑定。
+
+节点类型只使用 `Start/Auto/Business/Approve/Countersign/End/AutoEnd`；
+`End` 是人工节点，自动结束用 `AutoEnd`。每个节点应有稳定 Id；
+`PositionLeft/PositionTop` 使用像素（如 `"320px"`）。新版 MCP 对缺失坐标按
+拓扑层级布局并补 `px`，明确重叠、非法类型、断线、不可达、无人审批会在写入前失败。
+节点人员绑定在写入时仅保留 `Id/Name`，不能把完整 `sys_user` 记录及密码字段嵌入流程。
+MCP 写入前会回读当前租户的用户、角色、部门和岗位 Id；回读失败或 Id 不存在时停止保存。
+
+模块入口使用 `sys_menu.OpenType="WorkFlow"`、`FlowDesignId=<已启用流程真实 Id>`，
+`DiyTableId` 与 `wf_flowdesign.TableId` 相同。完整 Manifest 内可用模块
+`flowName` 指向同一份 `workflows[].FlowDesign.FlowName`，生成器保存流程后补写并回读
+`FlowDesignId`；引用既有流程时传 `flowDesignId`。上线前从模块打开并发起一条真实
+业务记录，确认流程图节点、人员待办、审批、历史与模块入口均正确。
+
+全部配置字段、节点类型和运行操作见
+[流程配置清单](references/workflow-configuration.md)。
+
+你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
+
+## 后端类库与接口边界
+
+- 工作流运行时固定属于独立 `Microi.WorkFlow` 类库；`Microi.net.Api` 只注册 `AddMicroiWorkFlow()`，不得恢复 `WorkFlowController` 或把流程业务写回 `Program.cs`。
+- 对外与旧移动端路由统一由官方 Managed `platform-workflow` 接口引擎承载，历史 `/api/WorkFlow/*` 地址写入同一记录的 `ApiRoutes`。租户个性化逻辑写在 CreateIfMissing `platform-workflow-custom-hook`，默认只返回 `{ Code: 1 }`。
+- `Microi.Core` 只保留避免循环引用所需的 `IWFEngine`、模型和最小运行时合同；发起、审批、撤回、移交、退回及审批人计算实现在 `Microi.WorkFlow`，并按职责拆分 partial 文件。
+- 新业务规则仍优先写工作流 V8/接口引擎。只有事务、流程状态机、可信当前用户和运行时内核缺少不可伪造的底层原子时，才扩展 `Microi.WorkFlow`。
+- 官方发布时 `Microi.WorkFlow` 必须生成 NuGet 包，并与 `Microi.AI` 使用同一 Obfuscar 配置加密后替换包内 DLL；不得推送未加密的 WorkFlow 包。开源安装只消费 NuGet，不要求存在私有源码。
 
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=v8-workflow-000 sha256=9030cd2de9f1febfb9a749c82cf83e97ccb8fb972a3f8f0ff11067488e14cd8e -->
@@ -27,11 +54,11 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 ```javascript
 /*
- * V8 工作流
- * WorkflowKey: 示例流程Key
+ * V8 工作流
+ * WorkflowKey: 示例流程Key
  * EventType: WFNodeLine/WFNodeStart/WFNodeEnd
  * Version: v1.0.0
- * 功能说明：
+ * 功能说明：
  * - 完整说明该工作流 V8 控制的节点动作、路线条件、审批变量和副作用。
  */
 ```
@@ -42,7 +69,7 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-workflow-001 sha256=53550786c531c347cfe9d92247b07d127c348210f07e302a1b68f278136c3e77 -->
-## 工作流物理表
+## 工作流物理表
 
 | 表名 | 说明 |
 |------|------|
@@ -51,51 +78,51 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 | `wf_line` | 节点间连线/条件 |
 | `wf_flow` | 流程实例（一次发起对应一行） |
 | `wf_work` | 待办/已办工作 |
-| `wf_history` | 审批历史（每次同意/拒绝/撤回的记录） |
-
-### 原生人员、自动结束与取消快照契约
-
-- `wf_node.Users` 是 JSON 序列化的 `IdName` 对象数组，例如 `[{"Id":"<user-id>","Name":"审核人"}]`；不能保存为字符串 Id 数组。`Name` 仅供显示，业务授权仍须按当前主库用户、角色和实际待办接收人判断。前端 `V8.WF.ForceSelectUsers` 的字符串数组是另一份 API 契约，不能混用。
-- 自动结束节点的 `NodeType` 使用 `AutoEnd`。它可能继承上一人工节点的 `ApprovalType=Agree`，并生成一条结束历史；核对独立审批人数时只计入明确配置的人工节点，不能把结束节点当成额外审核人。
-- 原生 `CancelFlow` 可将请求中的 `FormData` 写回 `wf_flow.FormData`；未传时可能保存 `{}`。应用不能把取消后的实例 `FormData` 当成不可变的原始提交快照。需要恢复冻结业务单时，优先核对业务表保存的服务端快照摘要；若使用原生历史，必须限定同一实例、同一业务表/行、唯一原始开始节点及发起人、自动提交历史，并检查版本、金额、配置摘要和零待办。此分支只能恢复草稿或驳回状态，不能据此批准或过账。
-- 当前 `CancelFlow(WFParam)` 使用独立事务，没有 `StartWork/SendWork` 的共享 `DbTrans` 重载。应用不得在持有实例、工作或业务行锁的接口事务内调用取消，也不能假设给它多传一个参数便会共享事务。微服务可顺序执行“服务端核验并返回真实待办坐标 → 原生取消 → 业务终态复核”，每个请求完成后释放其事务；网络结果未知时先复核终态，不能盲目重发取消或提前恢复业务状态。
-- 验收至少覆盖真实取消时不传 `FormData`、伪造取消载荷、退回后直接重提被拒绝、取消后新实例重提、自动结束继承 `Agree`，以及普通角色不能修改取证用的流程历史。模拟正确 JSON 不替代原生 HTTP 验收。
-
-直接 SQL 查询常用场景：
+| `wf_history` | 审批历史（每次同意/拒绝/撤回的记录） |
+
+### 原生人员、自动结束与取消快照契约
+
+- `wf_node.Users` 是 JSON 序列化的 `IdName` 对象数组，例如 `[{"Id":"<user-id>","Name":"审核人"}]`；不能保存为字符串 Id 数组。`Name` 仅供显示，业务授权仍须按当前主库用户、角色和实际待办接收人判断。前端 `V8.WF.ForceSelectUsers` 的字符串数组是另一份 API 契约，不能混用。
+- 自动结束节点的 `NodeType` 使用 `AutoEnd`。它可能继承上一人工节点的 `ApprovalType=Agree`，并生成一条结束历史；核对独立审批人数时只计入明确配置的人工节点，不能把结束节点当成额外审核人。
+- 原生 `CancelFlow` 可将请求中的 `FormData` 写回 `wf_flow.FormData`；未传时可能保存 `{}`。应用不能把取消后的实例 `FormData` 当成不可变的原始提交快照。需要恢复冻结业务单时，优先核对业务表保存的服务端快照摘要；若使用原生历史，必须限定同一实例、同一业务表/行、唯一原始开始节点及发起人、自动提交历史，并检查版本、金额、配置摘要和零待办。此分支只能恢复草稿或驳回状态，不能据此批准或过账。
+- 当前 `CancelFlow(WFParam)` 使用独立事务，没有 `StartWork/SendWork` 的共享 `DbTrans` 重载。应用不得在持有实例、工作或业务行锁的接口事务内调用取消，也不能假设给它多传一个参数便会共享事务。微服务可顺序执行“服务端核验并返回真实待办坐标 → 原生取消 → 业务终态复核”，每个请求完成后释放其事务；网络结果未知时先复核终态，不能盲目重发取消或提前恢复业务状态。
+- 验收至少覆盖真实取消时不传 `FormData`、伪造取消载荷、退回后直接重提被拒绝、取消后新实例重提、自动结束继承 `Agree`，以及普通角色不能修改取证用的流程历史。模拟正确 JSON 不替代原生 HTTP 验收。
+
+直接 SQL 查询常用场景：
 
 ```javascript
 // 我的待办
-var todo = V8.Db.FromSql(
-  'SELECT Id, FlowId, NodeId, FlowTitle, WorkState, ReceiverId, TableRowId FROM wf_work WHERE ReceiverId = @p0 AND WorkState = @p1 ORDER BY CreateTime DESC'
-).AddInParameter("@p0", V8.CurrentUser.Id)
- .AddInParameter("@p1", 'Todo')
- .ToArray();
-
-// 我发起的
-var mine = V8.Db.FromSql(
-  'SELECT Id, FlowTitle, FlowState, SenderId, TableRowId FROM wf_flow WHERE SenderId = @p0 ORDER BY CreateTime DESC'
-).AddInParameter("@p0", V8.CurrentUser.Id)
- .ToArray();
-
-// 流程历史
-var history = V8.Db.FromSql(
-  'SELECT * FROM wf_history WHERE FlowId = @p0 ORDER BY CreateTime ASC'
-).AddInParameter("@p0", V8.Param.flowId)
- .ToArray();
-```
+var todo = V8.Db.FromSql(
+  'SELECT Id, FlowId, NodeId, FlowTitle, WorkState, ReceiverId, TableRowId FROM wf_work WHERE ReceiverId = @p0 AND WorkState = @p1 ORDER BY CreateTime DESC'
+).AddInParameter("@p0", V8.CurrentUser.Id)
+ .AddInParameter("@p1", 'Todo')
+ .ToArray();
+
+// 我发起的
+var mine = V8.Db.FromSql(
+  'SELECT Id, FlowTitle, FlowState, SenderId, TableRowId FROM wf_flow WHERE SenderId = @p0 ORDER BY CreateTime DESC'
+).AddInParameter("@p0", V8.CurrentUser.Id)
+ .ToArray();
+
+// 流程历史
+var history = V8.Db.FromSql(
+  'SELECT * FROM wf_history WHERE FlowId = @p0 ORDER BY CreateTime ASC'
+).AddInParameter("@p0", V8.Param.flowId)
+ .ToArray();
+```
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-workflow-002 sha256=377698ecb64266fb74399ea664010e0a46156d13c3e047de1b2cbae3dbba15c7 -->
-## 流程 V8 事件执行顺序
-
-工作流合并提交请求的 `_FormSubmitAction` 可使用 `Add/Edit`；表单后端事件中的
-`V8.FormSubmitAction` 实际为 `Insert/Update/Delete`，两者不能混淆。删除事件把服务端
-读取的待删除行放在 `V8.Form`，`V8.OldForm` 为空；校验删除归属、状态或引用时应以
-`V8.Form.Id` 在共享事务中重新读取并锁定原行，不应假定 `OldForm` 与修改事件相同。
-
-节点开始事件成功继续流转时保持 `V8.Result` 为空或设为布尔 `true`；不要用
-`V8.Result={Code:1}`，非布尔结果会提前结束当前流转。节点校验失败应抛出异常，
-尤其节点结束事件不可依赖 `return {Code:0}` 阻止事务提交。
+## 流程 V8 事件执行顺序
+
+工作流合并提交请求的 `_FormSubmitAction` 可使用 `Add/Edit`；表单后端事件中的
+`V8.FormSubmitAction` 实际为 `Insert/Update/Delete`，两者不能混淆。删除事件把服务端
+读取的待删除行放在 `V8.Form`，`V8.OldForm` 为空；校验删除归属、状态或引用时应以
+`V8.Form.Id` 在共享事务中重新读取并锁定原行，不应假定 `OldForm` 与修改事件相同。
+
+节点开始事件成功继续流转时保持 `V8.Result` 为空或设为布尔 `true`；不要用
+`V8.Result={Code:1}`，非布尔结果会提前结束当前流转。节点校验失败应抛出异常，
+尤其节点结束事件不可依赖 `return {Code:0}` 阻止事务提交。
 
 1. 用户点击发起流程或处理工作
 2. **表单进入 V8 事件（前端 FormIn）**
@@ -178,7 +205,7 @@ if (V8.Form.Money <= 100) {
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-workflow-006 sha256=8e2a82330c7f49c3a03920123531d310ea329fd310179918d835e3c05d49771a -->
-## 前端发起流程
+## 前端发起流程
 
 ```javascript
 // 在 V8 按钮或自定义逻辑中发起流程
@@ -197,18 +224,18 @@ V8.WF.StartWork({
     V8.Tips(result.Msg, false);
   }
 });
-```
-
-<!-- /microi-progressive:chunk -->
-## “我的工作”与审核界面交付规则
-
-- 模块使用“流程引擎”打开方式时，关联流程只能选择已启用的 `wf_flowdesign`；交付前同时验证流程已启用、模块 `OpenType=WorkFlow`、`FlowDesignId` 正确，且开始节点不存在测试阻断 V8。
-- `StartWork` / `DoWork` 必须通过工作流与表单合并提交能力保存。审核态只保留“处理工作”、流转记录/流程图和关闭；不得同时显示普通保存、取消编辑、草稿箱、删除、显示隐藏字段或普通表单更多按钮。
-- “我的工作”菜单角标使用“未处理待办 + 未读抄送”。待办 Tab 显示未处理数，抄送 Tab 显示未读数；我发起的、我处理的、我相关的按各自列表查询口径统计，不能用 `wf_work` 的近似口径代替 `wf_flow` 列表口径。
-- 新抄送项应显式保存 `IsRead=false`，用户打开后由可信后端按当前身份标记已读。历史 `CopyUsers` 项没有 `IsRead` 时按已读兼容，避免升级后把全部历史抄送误报为未读。
-- “查看流程图”验收必须从真实流转记录入口打开，确认流程定义、当前节点高亮、连线和弹窗尺寸正常，并检查浏览器无脚本错误；只验证流程 JSON 拓扑不等于完成 UI 验收。
-
-## 详细参考路由（渐进披露）
+```
+
+<!-- /microi-progressive:chunk -->
+## “我的工作”与审核界面交付规则
+
+- 模块使用“流程引擎”打开方式时，关联流程只能选择已启用的 `wf_flowdesign`；交付前同时验证流程已启用、模块 `OpenType=WorkFlow`、`FlowDesignId` 正确，且开始节点不存在测试阻断 V8。
+- `StartWork` / `DoWork` 必须通过工作流与表单合并提交能力保存。审核态只保留“处理工作”、流转记录/流程图和关闭；不得同时显示普通保存、取消编辑、草稿箱、删除、显示隐藏字段或普通表单更多按钮。
+- “我的工作”菜单角标使用“未处理待办 + 未读抄送”。待办 Tab 显示未处理数，抄送 Tab 显示未读数；我发起的、我处理的、我相关的按各自列表查询口径统计，不能用 `wf_work` 的近似口径代替 `wf_flow` 列表口径。
+- 新抄送项应显式保存 `IsRead=false`，用户打开后由可信后端按当前身份标记已读。历史 `CopyUsers` 项没有 `IsRead` 时按已读兼容，避免升级后把全部历史抄送误报为未读。
+- “查看流程图”验收必须从真实流转记录入口打开，确认流程定义、当前节点高亮、连线和弹窗尺寸正常，并检查浏览器无脚本错误；只验证流程 JSON 拓扑不等于完成 UI 验收。
+
+## 详细参考路由（渐进披露）
 
 仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
 

package/skills/v8-workflow/references/workflow-configuration.md

@@ -0,0 +1,49 @@
+# 工作流引擎配置清单
+
+事实源：当前租户 `microi_get_db_schema`、`Microi.Core/Param/WFParam.cs`、
+`Microi.WorkFlow` 运行时、PC `views/workflow/component`。下表只描述审批工作流。
+
+## 定义、节点、连线
+
+| 资源 | 可配置字段 | 用途与注意 |
+|---|---|---|
+| `wf_flowdesign` | `FlowName, Category, Description, Remark, Sort, Preview, JsonData` | 名称、分类、说明、排序、预览与画布数据；画布最终按 `wf_node/wf_line` 渲染。 |
+| `wf_flowdesign` | `TableId, IsEnable, Roles, StartV8, EndV8` | 关联业务 `diy_table.Id`、启用、允许发起角色、流程开始/结束事件。模块流程只选已启用项。 |
+| `wf_node` | `Id, NodeName, NodeType, Icon, Description, Remark, PositionLeft, PositionTop` | 稳定节点身份、类型和画布位置。坐标写为 CSS 像素；缺失时 MCP 自动布局。 |
+| `wf_node` | `Users, Roles, Depts, BindJobs, SameDeptApprove` | 前四者是 `[{Id,Name}]` JSON 审批人来源；`SameDeptApprove` 只进一步筛选同部门候选人，不能单独提供接收人。不能伪造跨租户 Id。 |
+| `wf_node` | `AllowSelectUsers, AllowAddUsers, AllowRecall, AllowHandOver, HideHandOverSelect, BackNodes, Timeout` | 上游手选下节点人员、加签、撤回、移交、隐藏移交选择、可退回节点、超时。`BackNodes` 保存 `[{Id,NodeName}]`；会签通常不启用手选。 |
+| `wf_node` | `CopyUsers, DisplayFields, HideFields, EditFields, FieldsConfig, FieldsConfigComponent, TableId` | 抄送 `IdName` 列表、节点表单字段权限、配置组件与业务表。字段配置应从当前表真实字段建模。 |
+| `wf_node` | `StartV8, StartV8Server, EndV8, EndV8Server, LineValueV8, AllowAddUserV8Code` | 前后端节点开始/结束事件、多出线选择与加签过滤代码。条件写在当前节点，不要误放在 `wf_line.V8Code`。 |
+| `wf_line` | `Id, FromNodeId, ToNodeId, LineName, LineValue, V8Code` | 稳定线身份、端点、展示标题、条件值与兼容线代码。标题用“起点 到 终点”；分支由源节点 `LineValueV8` 指定 `V8.NextNodeId` 或 `V8.LineValue`。 |
+
+`NodeType`：`Start` 发起；`Auto` 自动；`Business` 业务提交；
+`Approve` 审批；`Countersign` 会签；`End` 人工结束；`AutoEnd` 自动结束。
+人工节点必须有真实接收人策略，否则流程可能创建实例却无待办。
+
+## 实例与操作
+
+| 资源/动作 | 功能 |
+|---|---|
+| `wf_flow` | 流程实例、业务表/行、发起人、状态、最近表单 JSON、经办人与抄送汇总。`FormData` 会变化，不是原始快照。 |
+| `wf_work` | 每个接收人的待办/已办；按 `ReceiverId + WorkState` 确定可处理工作。 |
+| `wf_history` | 每一步的起止节点、连线、处理人、意见、表单与抄送历史。 |
+| `StartWork / StartWorkWithForm` | 发起流程；新业务行建议使用合并表单提交接口。 |
+| `SendWork / SendWorkWithForm` | 处理审批、业务节点、会签及后续自动节点。 |
+| `GetStartWFNode / GetWFNodeModel / GetNextNodeConfirmUsers` | 查询开始节点、节点属性及下一节点接收人。 |
+| `RecallWork / CancelFlow / HandOverWork` | 撤回、取消、移交。取消独立事务且可改写实例 `FormData`，须按业务终态复核。 |
+| `GetWFWork / GetWFFlow / GetWFHistory / GetWFStats / MarkCopyRead` | 待办、实例、历史、统计与抄送已读。普通用户须走身份与菜单/工作权限边界。 |
+
+## MCP 到模块的生成顺序
+
+1. 查询当前租户业务表、角色、用户、部门、岗位和现有流程；不要复制其它租户 Id。
+2. Manifest 写入 `workflows[]` 的 `FlowDesign/Nodes/Lines`；人工节点设置人员策略，
+   所有连线指向同包节点，分支节点写 `LineValueV8`。
+3. 模块设置 `openType:"WorkFlow"`、`table:"业务表名"`，同包流程传
+   `flowName:"流程名称"`；现有流程传 `flowDesignId:"真实 Id"`。
+4. 执行 `microi_plan_system`、`microi_check_workflow_package`，分支调用
+   `microi_test_workflow_condition`；写入后回读三张定义表与 `sys_menu`，
+   用实际账号发起、处理、查看历史与流程图。
+
+`microi_check_workflow_package` 是本地结构检查；MCP 保存前还会核对当前租户的
+用户、角色、部门和岗位 Id。账号是否仍有效、审批人是否有业务权限以及实际到达待办，
+仍必须通过运行时与真实业务回读。