h3factory 0.0.0-stage → 0.2.2

package/projects/demo/generated/product.cs

@@ -0,0 +1,82 @@
+// =====================================================================
+// 产品登记表 —— product 提交时 OnSubmit 服务端代码（h3factory cli gen 骨架）
+// 【粘贴位置】表单设计器 → 业务规则/后端事件 → 提交时
+// 【类名】必须等于当前表单 SchemaCode（本文件已填：product）
+//
+// 通用模式参考（奥驰样例已编译通过的实现，可直接照抄结构）：
+//   料号生成_料号申请表.cs —— 5-key 计数 upsert(NextCounter)、跨表查重、
+//   表单存名称→字典查代码、规格描述按模板单遍替换
+//   D:\AI\自动编号\料号生成_料号申请表.cs
+// =====================================================================
+using System;
+using System.Collections.Generic;
+using System.Data;
+using System.Text;
+using System.Text.RegularExpressions;
+using H3;
+
+public class product : H3.SmartForm.SmartFormController
+{
+    // ---------------- SchemaCode（与本工程 projects registry.json 一致） ----------------
+    private const string SELF_SCHEMA = "product";   // 产品登记表（本表）
+
+    private const string F_PCODE          = "pcode";                 // 产品编码
+    private const string F_PNAME          = "pname";                 // 品名
+    private const string F_BIGCAT         = "bigcat";                // 大类别
+    private const string F_PRICE          = "price";                 // 参考价
+    private const string F_ENABLED        = "enabled";               // 启用
+    private const string F_SPECDESC       = "specdesc";              // 规格描述
+    private const string F_STATUS         = "status";                // 状态
+    // ================= 工具 =================
+    private static string SqlStr(string v) { return (v + string.Empty).Replace("'", "''"); }
+    private static string S(object v) { return (v + string.Empty).Trim(); }   // BizObject 字段值为 object
+    private bool Flag(object v)
+    {
+        if (v == null) return false;
+        string s = (v + string.Empty).ToLower();
+        return s == "true" || s == "1" || s == "是";
+    }
+    private long AsLong(object v)
+    {
+        long n;
+        if (v == null || !long.TryParse(v + string.Empty, out n)) return 0;
+        return n;
+    }
+
+    public product(H3.SmartForm.SmartFormRequest request) : base(request) { }
+
+    protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
+    {
+        base.OnLoad(response);
+    }
+
+    // ================= 提交时入口 =================
+    protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue,
+                                     H3.SmartForm.SubmitSmartFormResponse response)
+    {
+        try
+        {
+            H3.DataModel.BizObject form = this.Request.BizObject;
+
+            // 仅"草稿 → 首次提交"触发生成；编辑重提/流转保存直接跳过。
+            bool firstSubmit = actionName == "Submit" &&
+                this.Request.BizObject.Status == H3.DataModel.BizObjectStatus.Draft;
+            if (!firstSubmit) return;
+
+            // ============================================================
+            // TODO 业务规则写在这里：
+            //   1. 读本表单字段  string v = S(form[F_XXX]);
+            //   2. 读关联表记录  BizObject rule = BizObject.Load(this.Request.UserContext.UserId,
+            //                      this.Engine, REF_SCHEMA, refId, false);
+            //   3. 计数/查重等跨表逻辑参考 料号生成_料号申请表.cs
+            //      （Engine.Query.QueryTable / COALESCE / BizObject.Create+Update）
+            //   4. 错误拦截      response.Errors.Add("提示信息"); return;
+            //   5. 生成字段写回  form[F_XXX] = "结果";   （本表字段直接改 form 即保存）
+            // ============================================================
+        }
+        catch (Exception ex)
+        {
+            response.Errors.Add("生成失败: " + ex.Message);
+        }
+    }
+}

package/projects/demo/groups.json

@@ -0,0 +1,3 @@
+[
+  { "name": "主数据" }
+]

package/projects/demo/sheets/product.json

@@ -0,0 +1,24 @@
+{
+  "title": "产品登记表",
+  "nameSchema": "{pname}",
+  "useOwner": true,
+  "layout": "auto4",
+  "group": "主数据",
+  "controls": [
+    { "type": "text", "key": "pcode", "label": "产品编码" },
+    { "type": "text", "key": "pname", "label": "品名", "required": true },
+    { "type": "dropdown", "key": "bigcat", "label": "大类别", "dict": "大类别" },
+    { "type": "number", "key": "price", "label": "参考价", "decimal": 2 },
+    { "type": "switch", "key": "enabled", "label": "启用", "checked": true },
+    { "type": "textarea", "key": "specdesc", "label": "规格描述", "rows": 2 },
+    { "type": "dropdown", "key": "status", "label": "状态", "options": ["在制", "已停产"],
+      "hideWhen": "{enabled}==\"false\"" },
+    { "type": "subtable", "key": "specs", "label": "规格参数明细",
+      "columns": [
+        { "type": "text", "key": "param", "label": "参数名" },
+        { "type": "dropdown", "key": "unit", "label": "单位", "options": ["mm", "kg", "件"] },
+        { "type": "number", "key": "val", "label": "数值", "decimal": 2 },
+        { "type": "date", "key": "since", "label": "生效日期" }
+      ] }
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * npm postinstall：把包内 skills/ 安装到所有已知 AI 工具的用户级技能目录。
+ * 这样 Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder 等
+ * 安装完 npm 包后都能直接识别 h3factory 技能。
+ * 任何失败都不阻断 npm install；可用 H3FACTORY_SKIP_SKILLS=1 跳过。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILLS_SRC = path.join(PACKAGE_ROOT, 'skills');
+const HOME = os.homedir();
+const QUIET = process.argv.includes('--quiet');
+
+// 与 cli.py 的 TOOL_SKILL_DIRS 保持一致
+const TOOL_DIRS = [
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.opencode',
+  '.qwenworkcn',
+  '.qoder',
+  '.qoderwork',
+  '.mulerun',
+  '.codebuddy',
+  '.workbuddy',
+];
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(from, to);
+    } else {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function skillNames() {
+  if (!fs.existsSync(SKILLS_SRC)) {
+    return [];
+  }
+  return fs
+    .readdirSync(SKILLS_SRC, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        fs.existsSync(path.join(SKILLS_SRC, entry.name, 'SKILL.md'))
+    )
+    .map((entry) => entry.name);
+}
+
+if (process.env.H3FACTORY_SKIP_SKILLS === '1') {
+  if (!QUIET) {
+    console.log('[h3factory] H3FACTORY_SKIP_SKILLS=1，跳过技能安装');
+  }
+  process.exit(0);
+}
+
+try {
+  const skills = skillNames();
+  if (skills.length) {
+    const installed = [];
+    for (const toolDir of TOOL_DIRS) {
+      const destination = path.join(HOME, toolDir, 'skills');
+      let touched = false;
+      for (const skill of skills) {
+        try {
+          const target = path.join(destination, skill);
+          fs.rmSync(target, { recursive: true, force: true });
+          copyDir(path.join(SKILLS_SRC, skill), target);
+          touched = true;
+        } catch (error) {
+          if (!QUIET) {
+            console.warn(
+              '[h3factory] 技能 ' + skill + ' 安装到 ' + destination +
+                ' 失败（不影响 CLI）: ' + error.message
+            );
+          }
+        }
+      }
+      if (touched) {
+        installed.push(destination);
+      }
+    }
+    if (!QUIET && installed.length) {
+      console.log(
+        '[h3factory] 已安装技能: ' +
+          skills.join(', ') +
+          ' → ' +
+          installed.join(', ')
+      );
+    }
+  }
+} catch (error) {
+  if (!QUIET) {
+    console.warn('[h3factory] 技能安装跳过（不影响 CLI）: ' + error.message);
+  }
+}
+
+process.exit(0);

package/skills/h3factory/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: h3factory
+description: 氚云（H3Yun）表单工厂总入口。用户提到氚云自动建表、表单工厂、批量建表/建表单、需求转表单、h3factory、check/build/verify/gen 时使用。负责澄清需求、产出 sheets JSON、调用 h3factory CLI 建表与只读核对；平台二开代码规范路由到 h3yun-dev-assistant。
+---
+
+# h3factory 编排技能
+
+把「需求文档 → 表单设计 JSON → 线上建表 → 只读核对 → 代码骨架」串成流水线。
+确定性部分（校验/建表/回读/导数据/生成骨架）全部由 `h3factory` CLI 完成；
+你负责需求澄清、JSON 设计和业务规则代码。
+
+## 第 0 步：凭据门禁（每次会话必须先执行）
+
+> **硬门禁**：没有通过 `auth status`，不得执行 `build/verify/group/import`。
+
+1. 确认命令可用：`h3factory --version`。失败则让客户安装：`npm install -g h3factory`。
+2. 运行 `h3factory auth status --json`，读取 `ok`、`missing`、`jwt_expired`。
+3. 如果 `ok=false`，**优先让客户在自己的终端录入**（token 不会进入对话记录）：
+   - 只缺 `authorization`：客户运行 `h3factory auth set-token`，输入时回显被隐藏。
+   - 还缺 `baseUrl/engineCode/engineSecret/appCode`：客户运行 `h3factory init` 交互式填全部。
+   - 客户执行完后，你再运行 `h3factory auth status --json`，直到 `ok=true`。
+4. 只有客户**主动在对话里给出 token** 时，才用 stdin 写入；禁止放进命令行参数，
+   禁止在回答里回显。写入后提醒客户：token 已进入对话记录，完成后建议轮换。
+   ```bash
+   h3factory auth set --json <<'JSON'
+   {"authorization": "<客户提供的 token>"}
+   JSON
+   ```
+   多个字段放在同一个 JSON 对象里即可。
+5. token 会过期：**每次新会话都重新检查**，过期就重复第 3/4 步换新 token。
+
+## 不可违反的规则
+
+1. **绝不打印或回显** `config.json`、`engineSecret`、`authorization` 的内容；不要把配置文件贴进回答。
+2. **建表前必须让用户过目设计**（表数量、字段、下拉取值、编号规则、存储口径）。这是唯一不能省的环节。
+3. `verify` 只读、可重复跑；`build` 默认跳过线上已存在的表。**只有用户明确要求**才加 `--force`——它会整表覆盖，抹掉界面上手工配置的必填/联动/审批。
+4. 设计文件和 registry 一律写在工作区的 `projects/<项目名>/`，不要写进 npm 安装目录。
+5. 不确定的表单编码、控件编码、接口签名，先查 `h3factory docs` 里的文档或问用户，不得臆造。
+6. 二开 C#/ES5/SQL 代码规范、平台控件与事件细节，读取并遵循 `h3yun-dev-assistant` 技能，不要凭记忆猜。
+
+## 工作区与安装
+
+- 命令：`h3factory`（npm 包名 `h3factory`；源码目录也可 `python -X utf8 cli.py`）。
+- **当前目录 = 工作区**；项目在 `./projects/<项目名>/`。
+- 配置查找顺序：`H3FACTORY_CONFIG` → `./config.json` → `~/.h3factory/config.json`；项目级 `projects/<项目名>/config.json` 优先于以上。
+- 首次使用：`h3factory auth status --json` → 需要时 `auth set` 录入 token → `h3factory doctor`。
+- 安装包会把技能自动装到 Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun / CodeBuddy / WorkBuddy 的用户技能目录；手动重装用 `h3factory skill install --tool all`。
+- 不自动加载技能的 Agent，用 `h3factory prompt` 打印通用提示语，或在项目里运行 `h3factory init` 写入 `AGENTS.md`。
+- 查看内置文档：`h3factory docs` 列出，`h3factory docs schema_doc` 打印内容。
+
+## 标准流程
+
+### 1. 澄清需求
+先读 `docs/requirement_checklist.md`（`h3factory docs requirement_checklist`），逐条确认：
+表单盘点、字段类型/必填/唯一、枚举与「存名称还是代码」、编号规则、
+审批流、权限、数据来源、界面手工配置项。歧义不澄清就建表 = 返工。
+
+### 2. 产出设计 JSON
+在工作区创建 `projects/<项目名>/`：
+- `sheets/<表单key>.json` —— 每张表单一个文件，格式见 `docs/schema_doc.md`
+- `dicts.json` —— 枚举字典
+- `groups.json` —— 可选，表单分组与菜单顺序
+- 一页设计说明：表关系、编号规则、口径决定
+
+同时把平台坑位过一遍：`h3factory docs platform_gotchas`。
+
+### 3. 本地校验（不联网）
+```bash
+h3factory check <项目名> [表..]
+```
+检查字段数、隐藏规则、行组、关联、子表、布局项、分组声明。语法/引用错误会直接报。
+
+### 4. 用户过目
+把设计说明和 `check` 输出交给用户确认。**未确认不得 build。**
+
+### 5. 建表
+```bash
+h3factory build <项目名> [表..]          # 已存在且结构一致会跳过
+h3factory build <项目名> <表> --force    # 仅用户明确要求时；整表覆盖
+```
+
+### 6. 只读核对
+```bash
+h3factory verify <项目名> [表..]
+h3factory list <项目名>
+```
+报告写到 `projects/<项目名>/logs/verify_report.txt`。有 FAIL 先修定义/重跑，不要掩盖。
+
+### 7. 生成代码骨架
+```bash
+h3factory gen <项目名> <表>
+```
+输出 `projects/<项目名>/generated/<表>.cs`。按 TODO 补业务规则；
+代码规范、控件编码、事件签名调用 `h3yun-dev-assistant` 技能确认。
+
+### 8. 交付
+除代码外，必须给用户「界面手工配置清单」：必填、审批流、字段联动、只读、
+按钮、权限等 API 配不了的项（参考 `docs/platform_gotchas.md`）。
+
+## 命令速查
+
+| 命令 | 作用 | 是否联网 |
+|---|---|---|
+| `h3factory auth status [--json]` | 凭据门禁：检查配置与 JWT | 否 |
+| `h3factory auth set --json` | 从 stdin 读 JSON 写入凭据（不回显） | 否 |
+| `h3factory auth set-token` | 从 stdin 读 token 写入 | 否 |
+| `h3factory init [--no-input]` | 交互生成工作区 config.json | 否 |
+| `h3factory doctor` | 检查 Python/配置/JWT/技能 | 否 |
+| `h3factory check <p> [表..]` | 本地校验表单定义 | 否 |
+| `h3factory list <p>` | 查看 registry 表编码与状态 | 否 |
+| `h3factory build <p> [表..] [--force]` | 建表 | 是 |
+| `h3factory verify <p> [表..]` | LoadForm 只读回读比对 | 是 |
+| `h3factory group <p> [表..]` | 建分组并归位（幂等） | 是 |
+| `h3factory import <p> <表> <data.json> [--submit]` | 批量导数据 | 是 |
+| `h3factory gen <p> <表>` | 生成 .cs 骨架 | 否 |
+| `h3factory docs [名称]` | 列出/打印内置文档 | 否 |
+| `h3factory skill install` | 安装本技能与二开技能 | 否 |
+
+## 目录约定（工作区）
+
+```
+projects/<项目名>/
+├─ config.json      # 可选，覆盖工作区凭据（勿提交）
+├─ dicts.json       # 枚举字典
+├─ groups.json      # 可选，分组顺序
+├─ sheets/*.json    # 表单定义（每表一个）
+├─ registry.json    # 平台编码注册表，勿手改
+├─ logs/            # verify/group 报告
+└─ generated/       # .cs 骨架
+```
+
+## 与 h3yun-dev-assistant 的分工
+
+- 本技能：需求 → 表单 JSON → CLI 建表/核对 → 生成骨架 → 交付清单。
+- `h3yun-dev-assistant`：C# 后端、ES5 前端、SQL、控件编码、事件、平台限制。
+  写或改业务代码前先加载它，尤其是 OnLoad/OnSubmit、PostForm、ListView.Post、
+  高级数据源和权限相关实现。

package/skills/h3yun-dev-assistant/BACKEND_GUIDELINES.md

@@ -0,0 +1,120 @@
+# 后端 C# 规则
+
+## 硬性限制
+
+- 使用 .NET Framework 4.6.2 兼容语法；不使用 C# 8+ 特性、反射、`HashSet<T>` 或三目运算符。
+- `if`、`else if`、`else`、`for`、`foreach`、`while`、`do while` 等控制流语句必须使用大括号，即使代码块中只有一条语句也不得省略；大括号采用 Allman 风格，单独占一行。只调整既有代码格式时不得改变业务逻辑。
+- 不使用 `Task`、线程、线程池、普通 .NET 定时器或本地文件 I/O。涉及这些场景时先读取 `PLATFORM_CONSTRAINTS.md`。
+- 不自行建立数据库连接，不使用 DDL，不直接用 SQL 增删改业务数据；业务数据操作使用 `BizObject`，批量操作使用平台批量接口。
+- 在表单 `Post` 请求中，如果需要更新或删除当前业务对象，不能直接操作 `this.Request.BizObject`；必须先使用当前业务对象的 `ObjectId` 调用 `H3.DataModel.BizObject.Load` 加载完整业务对象，再执行赋值、`Update()` 或 `Remove()`。
+- 避免循环调用 Engine、数据库或服务端接口；大数据量须分页或增加过滤条件。
+
+## 事件与异常
+
+- `OnLoad` 通常调用 `base.OnLoad(response)`。
+- `OnSubmit` 无论成功、校验失败或提前返回，都必须调用 `base.OnSubmit(actionName, postValue, response)`。
+- 校验方法优先命名为 `CheckData(H3.IEngine engine, H3.DataModel.BizObject thisBo)`，失败时 `throw new Exception("明确的错误说明")`。
+- `OnSubmit` 统一捕获业务异常，以 `response.Errors.Add(ex.Message)` 返回。
+- 比较时优先常量在前，例如 `"Submit".Equals(actionName)`。
+- 流程表单的 `Submit` 同时可能表示发起提交和审批同意。仅在发起时执行的后端逻辑，必须结合数据状态和当前流程节点判断，不能只判断 `"Submit".Equals(actionName)`。
+
+## 列表删除获取选中数据
+
+- 列表后端处理系统删除按钮时，使用 `postValue.Data["ObjectIds"]` 获取用户选中的业务对象 Id 数组，标准写法为：`string[] selectedIds = (string[]) postValue.Data["ObjectIds"];`。
+- 该写法来自官方后端代码示例“列表-删除时获得用户选择的数据”：https://h3yunpro.github.io/docs/cs-example/#%E5%88%97%E8%A1%A8-%E5%88%A0%E9%99%A4%E6%97%B6%E8%8E%B7%E5%BE%97%E7%94%A8%E6%88%B7%E9%80%89%E6%8B%A9%E7%9A%84%E6%95%B0%E6%8D%AE 。不得猜测为 `postValue["seIds"]`、`postValue["ObjectIds"]` 或其他参数名。
+- 使用前必须判断数组不为 `null` 且长度大于 0；需要批量查询时，用 `ObjectId` 配合 `ComparisonOperatorType.In` 构造筛选器，并校验查询结果数量与选中 Id 数量一致。
+- 列表 `OnSubmit` 处理删除时，无论自定义逻辑成功或异常，都必须保证 `base.OnSubmit(actionName, postValue, response)` 执行；异常应写入 `response.Errors` 后返回。
+
+```csharp
+protected override void OnSubmit(string actionName, H3.SmartForm.ListViewPostValue postValue, H3.SmartForm.SubmitListViewResponse response)
+{
+    try
+    {
+        if("Remove".Equals(actionName))
+        {
+            // 列表删除-用户选中的业务对象 Id
+            string[] selectedIds = (string[]) postValue.Data["ObjectIds"];
+            if(selectedIds != null && selectedIds.Length > 0)
+            {
+                // 列表表单-按选中业务对象 Id 批量查询
+                H3.Data.Filter.Filter filter = new H3.Data.Filter.Filter();
+                H3.Data.Filter.And andMatcher = new H3.Data.Filter.And();
+                andMatcher.Add(new H3.Data.Filter.ItemMatcher("ObjectId", H3.Data.ComparisonOperatorType.In, selectedIds));
+                filter.Matcher = andMatcher;
+                filter.FromRowNum = 0;
+                filter.ToRowNum = 1000;
+                H3.DataModel.BizObject[] boArray = H3.DataModel.BizObject.GetList(
+                    this.Engine,
+                    H3.Organization.User.SystemUserId,
+                    this.Request.Schema,
+                    H3.DataModel.GetListScopeType.GlobalAll,
+                    filter
+                );
+            }
+        }
+    }
+    catch(Exception ex)
+    {
+        response.Errors.Add(ex.Message);
+        base.OnSubmit(actionName, postValue, response);
+        return;
+    }
+
+    base.OnSubmit(actionName, postValue, response);
+}
+```
+
+## 表单按钮增删
+
+- 在表单后端 `OnLoad` 中，先调用 `base.OnLoad(response)`，再通过 `response.Actions` 调整按钮。
+- 删除已有按钮前先用 `response.Actions.ContainsKey("按钮编码")` 判断，避免不存在时异常。
+- 动态新增按钮使用 `response.Actions.Add("按钮编码", new H3.SmartForm.ViewAction("按钮编码", "按钮名称", ""))`。
+- 需要按业务状态显示按钮时，读取 `this.Request.BizObject["字段编码"]` 后再决定是否添加；不要依赖前端直接操作 DOM。
+- 动态按钮的编码必须与 `OnSubmit` 的 `actionName` 判断完全一致。
+
+```csharp
+protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
+{
+    base.OnLoad(response);
+
+    if(response.Actions != null && response.Actions.ContainsKey("Save"))
+    {
+        response.Actions.Remove("Save");
+    }
+
+    // 示例表单-执行状态：F0000004
+    string executeStatus = this.Request.BizObject["F0000004"] + string.Empty;
+    if("暂停".Equals(executeStatus) && !response.Actions.ContainsKey("ContinueRecognition"))
+    {
+        response.Actions.Add(
+            "ContinueRecognition",
+            new H3.SmartForm.ViewAction("ContinueRecognition", "继续执行", "")
+        );
+    }
+}
+```
+
+## 主表与子表控件取值
+
+- 生成后端主表或子表控件的取值、赋值或类型转换代码前，必须先查阅氚专开发文档：https://h3yunpro.github.io/docs/bo-set-get/ 。
+- 字符串、人员/部门单选、关联表单、人员/部门多选、关联表单多选、日期、数字、复选框、是/否、地址、位置、附件和图片的值类型及读写方式，必须以该文档为准，不得猜测类型。
+- 从业务对象读取子表控件值时，必须转换为 `H3.DataModel.BizObject[]`，例如：`H3.DataModel.BizObject[] detailRows = thisBo["子表控件编码"] as H3.DataModel.BizObject[];`。
+- 禁止将子表控件值转换为 `List<H3.DataModel.BizObject>`；平台返回的子表值类型为数组，错误转换会导致读取结果为空或运行异常。
+- 使用子表数据前先判断数组是否为 `null` 或长度为 `0`，再用 `foreach` 遍历每一行。
+
+## 自定义类
+
+- 同一应用的后端会共同编译。新增辅助类必须以当前完整表单编码为前缀：`表单编码_类名`。
+- 第一次引用辅助类时，在上一行标注：`// 类名类及方法名方法定义于【表单名称】表单设计页后端代码中`。
+- 类内只定义字段，禁止使用 `{ get; set; }` 自动属性；氚云后端编译器不支持自动属性。
+- 每个字段定义时必须同时给出默认值；对象类型字段可默认为 null。例如：`public string name = "";`、`public decimal qty = 0;`、`public List<string> ids = null;`。
+
+## 方法复用
+
+- 封装方法内部需要使用 `H3.IEngine` 时，必须将 `H3.IEngine engine` 作为方法入参传入，不直接使用 `this.Engine`，以提高方法复用性。
+- 封装方法内部需要使用 `H3.DataModel.BizObject` 时，必须将业务对象作为方法入参传入，不直接使用 `this.Request.BizObject`，以提高方法复用性。
+
+## 编码注释
+
+- 表单编码旁标注表单名称；字段编码旁标注“表单名称-字段名称”。
+- 新增封装方法上方添加一句中文注释说明处理目标。

package/skills/h3yun-dev-assistant/DEV_DOC_ROUTING.md

@@ -0,0 +1,39 @@
+# 氚专开发文档按需读取路由
+
+处理氚云需求时，先读取本表；仅在需求命中对应主题、用户要求按氚专开发文档实现，或现有规则无法确认 API 签名、参数、返回值、事件时机或控件类型时，再读取对应开发文档。不要为简单需求加载全部文档。
+
+| 需求意图或关键词 | 必读开发文档 |
+| --- | --- |
+| 按钮编码、自定义按钮、`actionName`、动态增删表单按钮、`response.Actions` | 读取技能内置 `FORM_ACTIONS_GUIDELINES.md`；动态按钮不再依赖旧版官方网页 |
+| 自动化、业务规则与代码的执行顺序或副作用 | [代码跟自动化混用](https://h3yunpro.github.io/docs/automation/) |
+| 创建、加载、查询、提交、删除 `BizObject` | [业务对象](https://h3yunpro.github.io/docs/biz-object/) |
+| 后端读取或设置主表、子表控件值 | [业务对象之控件的取值与赋值](https://h3yunpro.github.io/docs/bo-set-get/) |
+| 获取应用、表单、子表、控件编码 | [应用、表单、控件编码查看](https://h3yunpro.github.io/docs/check-code/) |
+| 后端 API 用法、`Engine`、常用 C# 示例 | [后端常用实例](https://h3yunpro.github.io/docs/cs-instance/)；必要时参考 [后端代码示例](https://h3yunpro.github.io/docs/cs-example/) |
+| JSON 序列化或反序列化 | [后端 JSON 序列化与反序列化](https://h3yunpro.github.io/docs/cs-json/) |
+| 数据库系统表、字段、附件表、流程表 | [数据库表结构详解](https://h3yunpro.github.io/docs/database/) |
+| 开发环境、编辑器、调试工具 | [开发工具](https://h3yunpro.github.io/docs/dev-tools/) |
+| 后端 SQL 查询、参数化 SQL | [后端执行 SQL](https://h3yunpro.github.io/docs/exec-sql/) |
+| 平台报错、现象或 FAQ 类问题 | [常见问题解答](https://h3yunpro.github.io/docs/faq/) |
+| 表单后端或前端事件、提交时机 | [表单事件](https://h3yunpro.github.io/docs/form-events/) |
+| 表单前端 API、控件操作 | [表单前端 API](https://h3yunpro.github.io/docs/form-js-api/)；控件取值和赋值另读 [表单前端 GetValue 与 SetValue](https://h3yunpro.github.io/docs/form-js-set-get/) |
+| 表单或列表前后端请求、`PostForm`、`ListView.Post` | [前后端交互示例](https://h3yunpro.github.io/docs/interactive-example/)；必要时参考 [纯净代码示例](https://h3yunpro.github.io/docs/pure-example/) |
+| 表单前端完整示例、事件代码示例 | [前端代码示例](https://h3yunpro.github.io/docs/js-example/)；常见组合场景参考 [前端常用实例](https://h3yunpro.github.io/docs/js-instance/) |
+| .NET/C#、JavaScript、浏览器兼容性 | [技术栈](https://h3yunpro.github.io/docs/language/) |
+| 列表前端或后端事件 | [列表事件](https://h3yunpro.github.io/docs/list-events/)；列表删除获取选中数据时，另读 [后端代码示例-列表删除时获得用户选择的数据](https://h3yunpro.github.io/docs/cs-example/#%E5%88%97%E8%A1%A8-%E5%88%A0%E9%99%A4%E6%97%B6%E8%8E%B7%E5%BE%97%E7%94%A8%E6%88%B7%E9%80%89%E6%8B%A9%E7%9A%84%E6%95%B0%E6%8D%AE) |
+| 列表前端 API、选中行、刷新、列表按钮 | [列表前端 API](https://h3yunpro.github.io/docs/list-js-api/) |
+| 短信、通知、提醒 | [消息通知与提醒](https://h3yunpro.github.io/docs/notification/) |
+| 平台术语、状态或对象含义 | [常见名词](https://h3yunpro.github.io/docs/noun/) |
+| 外部系统调用氚云 | [第三方调用氚云 OpenAPI](https://h3yunpro.github.io/docs/open-api/) |
+| 人员、部门、角色、组织关系 | [部门、人员与角色管理](https://h3yunpro.github.io/docs/organization/) |
+| 氚云后端调用第三方 HTTP 接口 | [氚云调用 WebAPI](https://h3yunpro.github.io/docs/req-api/) |
+| 氚云后端调用第三方 WebService | [氚云调用 WebService](https://h3yunpro.github.io/docs/req-ws/) |
+| SQL 高级数据源 | [SQL 高级数据源](https://h3yunpro.github.io/docs/sql-dashboard/) |
+| SQL 报表 | [SQL 报表](https://h3yunpro.github.io/docs/sql-report/) |
+| SQL 查询范例 | [数据库操作示例](https://h3yunpro.github.io/docs/sql-example/) |
+| 平台编程规范或代码风格 | [编程规范](https://h3yunpro.github.io/docs/standard/) |
+| 计划、周期、延时执行 | [定时器](https://h3yunpro.github.io/docs/timer/) |
+| 流程实例、节点、发起、审批、撤回、作废 | [流程操作](https://h3yunpro.github.io/docs/workflow/) |
+| 常用工具函数 | [工具方法合集](https://h3yunpro.github.io/docs/tool-function/) |
+
+无法归类或开发文档目录新增主题时，读取总索引：https://h3yunpro.github.io/llms.txt 。

package/skills/h3yun-dev-assistant/FORM_ACTIONS_GUIDELINES.md

@@ -0,0 +1,116 @@
+# 氚云表单按钮规则
+
+本文件整理自氚云官方“表单按钮”开发说明，用于在官方旧文档下架后继续指导表单按钮开发。
+
+## 适用范围
+
+- 表单后端 `OnLoad` 中删除、替换、动态增加按钮。
+- 表单后端 `OnSubmit` 中按按钮编码处理业务。
+- 根据当前业务对象字段值决定按钮是否显示。
+
+## 关键对象
+
+- `response.Actions`：表单加载响应中的按钮字典，键为按钮编码，值为 `H3.SmartForm.ViewAction`。
+- `H3.SmartForm.ViewAction`：按钮定义，构造参数为按钮编码、显示名称和说明文本。
+- `actionName`：表单后端 `OnSubmit` 的按钮编码。
+- `this.Request.BizObject`：当前表单业务对象，可读取字段值决定是否动态添加按钮。
+
+## 基本规则
+
+- `OnLoad` 必须先调用 `base.OnLoad(response)`。
+- 操作 `response.Actions` 前先判断其不为 `null`。
+- 删除按钮前先使用 `response.Actions.ContainsKey("按钮编码")` 判断。
+- 新增按钮前同样判断编码不存在，避免重复添加异常。
+- 动态添加的按钮编码必须与 `OnSubmit` 中判断的 `actionName` 完全一致。
+- 自定义按钮编码只使用英文字母和数字，避免中文、空格及特殊字符。
+- 不通过前端 DOM 操作新增或隐藏表单头部按钮，应由后端 `response.Actions` 决定。
+
+## 删除与新增按钮
+
+```csharp
+protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
+{
+    base.OnLoad(response);
+
+    if(response.Actions == null)
+    {
+        return;
+    }
+
+    if(response.Actions.ContainsKey("Save"))
+    {
+        response.Actions.Remove("Save");
+    }
+
+    if(!response.Actions.ContainsKey("TestAction"))
+    {
+        response.Actions.Add(
+            "TestAction",
+            new H3.SmartForm.ViewAction("TestAction", "测试按钮", "")
+        );
+    }
+}
+```
+
+## 按字段状态动态添加按钮
+
+```csharp
+protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
+{
+    base.OnLoad(response);
+
+    if(response.Actions == null)
+    {
+        return;
+    }
+
+    // 示例表单-处理状态：F0000001
+    string processStatus = this.Request.BizObject["F0000001"] + string.Empty;
+    if("待处理".Equals(processStatus) && !response.Actions.ContainsKey("TestAction"))
+    {
+        response.Actions.Add(
+            "TestAction",
+            new H3.SmartForm.ViewAction("TestAction", "测试按钮", "")
+        );
+    }
+}
+```
+
+## OnSubmit 处理动态按钮
+
+```csharp
+protected override void OnSubmit(
+    string actionName,
+    H3.SmartForm.SmartFormPostValue postValue,
+    H3.SmartForm.SubmitSmartFormResponse response)
+{
+    try
+    {
+        if("TestAction".Equals(actionName))
+        {
+            // 处理测试按钮业务。
+        }
+    }
+    catch(Exception ex)
+    {
+        response.Errors.Add(ex.Message);
+    }
+
+    base.OnSubmit(actionName, postValue, response);
+}
+```
+
+## 系统按钮编码
+
+| 名称 | 编码 |
+| --- | --- |
+| 暂存 | `Save` |
+| 提交/同意 | `Submit` |
+| 删除 | `Remove` |
+| 撤回 | `RetrieveInstance` |
+| 不同意 | `Reject` |
+| 作废 | `CancelInstance` |
+| 打印 | `Print` |
+| 关闭 | `Close` |
+
+`Submit` 同时可能表示发起提交和流程审批同意。需要区分时，必须结合表单数据状态或流程节点编码判断。