h3factory 0.0.0-stage → 0.2.2

package/cli.py

@@ -0,0 +1,951 @@
+# -*- coding: utf-8 -*-
+"""h3factory CLI —— 氚云 new-engine 表单工厂（确定性层，零 LLM 依赖）。
+
+npm 全局安装后（工作区 = 当前目录）:
+  h3factory init                       # 生成工作区 config.json（自 config.example.json）
+  h3factory doctor                     # 检查 Python/配置/JWT/技能
+  h3factory check <proj> [t1..]        # 本地加载并校验表单定义（不联网）
+  h3factory list <proj>                # registry：各表编码与状态
+  h3factory build <proj> [t1..]        # 建表（已注册且线上存在则跳过；--force 重存）
+  h3factory verify <proj> [t1..]       # LoadForm 只读回读比对（安全可重复）
+  h3factory group <proj> [t1..]        # 表单归组：建分组并移入（幂等，见 docs）
+  h3factory import <proj> <sheet> <data.json> [--submit]
+  h3factory gen <proj> <sheet>         # 生成 .cs 提交时代码骨架
+
+源码目录也可用: python -X utf8 cli.py <命令> ...
+项目 = <工作区>/projects/<proj>/：config.json（缺省用工作区/用户配置）+ sheets/*.json
+      + dicts.json + registry.json（编码注册表，勿手改）
+定义格式见 docs/schema_doc.md；平台坑位见 docs/platform_gotchas.md。"""
+import argparse
+import base64
+import datetime
+import json
+import os
+import random
+import shutil
+import string
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import h3design.dsl as DSL
+import h3verify.verify as V
+from h3platform import settings
+
+ROOT = settings.CODE_ROOT
+EXAMPLE_CONFIG = os.path.join(ROOT, "config.example.json")
+
+
+def _read_version():
+    try:
+        with open(os.path.join(ROOT, "package.json"), encoding="utf-8") as f:
+            return json.load(f).get("version", "0.0.0")
+    except Exception:
+        return "0.0.0"
+
+
+VERSION = _read_version()
+
+REQUIRED_KEYS = ("baseUrl", "engineCode", "engineSecret",
+                 "authorization", "appCode")
+
+# 各 AI 工具的用户级技能目录（参考 OpenYida 的安装位置）
+TOOL_SKILL_DIRS = (
+    (".claude", "claude"),
+    (".codex", "codex"),
+    (".cursor", "cursor"),
+    (".opencode", "opencode"),
+    (".qwenworkcn", "qwenwork"),
+    (".qoder", "qoder"),
+    (".qoderwork", "qoderwork"),
+    (".mulerun", "mulerun"),
+    (".codebuddy", "codebuddy"),
+    (".workbuddy", "workbuddy"),
+)
+
+
+def _err(msg):
+    print("错误: " + msg)
+    sys.exit(1)
+
+
+def project_dir(name):
+    p = settings.project_dir(name)
+    if not os.path.isdir(p):
+        _err("项目 %r 不存在（%s）。请在工作区 projects/ 下创建（可参考 demo），"
+             "或设置 H3FACTORY_HOME 指向已有工作区" % (name, p))
+    return p
+
+
+def read_json(path):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json(path, obj):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(obj, f, ensure_ascii=False, indent=1)
+
+
+def cfg_for(proj=None, required=True):
+    """项目 config.json 覆盖工作区/用户配置。凭据文件——勿提交/分享。
+    required=False 供纯本地命令（check/list）用，无凭据给空配置。"""
+    if proj:
+        pc = os.path.join(project_dir(proj), "config.json")
+        if os.path.isfile(pc):
+            return read_json(pc)
+    try:
+        return settings.load_config(required=required)
+    except settings.ConfigError as e:
+        _err(str(e))
+
+
+def reg_path(proj):
+    return os.path.join(project_dir(proj), "registry.json")
+
+
+def load_registry(proj):
+    try:
+        return read_json(reg_path(proj))
+    except Exception:
+        return {}
+
+
+def save_registry(proj, reg):
+    write_json(reg_path(proj), reg)
+
+
+def new_sheet_code(app_code):
+    return app_code[:7] + "".join(random.choice("0123456789abcdef") for _ in range(32))
+
+
+def new_child_code(app_code):
+    """子表 child schema 编码：appCode前7位 + F + 32位hex（40位；UI 实证 D001599F3ec...）。"""
+    return app_code[:7] + "F" + "".join(random.choice("0123456789abcdef")
+                                        for _ in range(32))
+
+
+def resolve_targets(proj, sheets, targets):
+    keys = [t for t in (targets or sorted(sheets))]
+    bad = [k for k in keys if k not in sheets]
+    if bad:
+        _err("表单 %s 不在项目 %r（现有 %s）" % (bad, proj, sorted(sheets)))
+    return keys
+
+
+# ---------------------------------------------------------------- commands
+AGENT_MD_BEGIN = "<!-- h3factory:begin -->"
+AGENT_MD_END = "<!-- h3factory:end -->"
+AGENT_MD_BLOCK = """<!-- h3factory:begin -->
+## 氚云表单工厂（h3factory）
+
+本工作区使用 `h3factory`。任何 Agent 会话开始必须先执行：
+
+    h3factory auth status --json
+
+如果 `ok=false`，让用户在自己的终端运行 `h3factory auth set-token`（输入隐藏）
+或 `h3factory init`；`ok=true` 后才允许执行 `build/verify/group/import`。
+
+- 命令：`h3factory --help`
+- 流程：`h3factory docs workflow`
+- 需求澄清：`h3factory docs requirement_checklist`
+- 通用提示语：`h3factory prompt`
+<!-- h3factory:end -->"""
+
+
+def _ensure_agent_md(path):
+    """幂等写入 AGENTS.md 的托管块，保留用户原有内容。"""
+    text = ""
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+    if AGENT_MD_BEGIN in text and AGENT_MD_END in text:
+        pre = text.split(AGENT_MD_BEGIN, 1)[0].rstrip()
+        post = text.split(AGENT_MD_END, 1)[1].lstrip("\n")
+        parts = [p for p in (pre, AGENT_MD_BLOCK, post) if p.strip()]
+        new = "\n\n".join(parts) + "\n"
+    else:
+        new = (text.rstrip() + "\n\n" if text.strip() else "") + AGENT_MD_BLOCK + "\n"
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(new)
+    return path
+
+
+def cmd_agent(args):
+    if args.action == "init":
+        path = _ensure_agent_md(os.path.join(settings.workspace_root(), "AGENTS.md"))
+        print("已写入 h3factory 指令块: %s" % path)
+
+
+def cmd_prompt(args):
+    if args.short:
+        print("用 h3factory 帮我做这个需求：<需求>")
+        return
+    print("""请使用 h3factory 帮我完成以下需求：
+<把需求贴在这里>
+
+执行要求：
+1. 先运行 h3factory auth status --json；若 ok=false，让我运行 h3factory auth set-token 录入 token。
+2. 运行 h3factory docs workflow 和 h3factory docs requirement_checklist，按流程先澄清需求。
+3. 产出 projects/<项目名>/ 设计后停下来让我过目，确认后再 build。""")
+
+
+def cmd_init(args):
+    if not getattr(args, "no_agent_md", False):
+        try:
+            path = _ensure_agent_md(os.path.join(settings.workspace_root(), "AGENTS.md"))
+            print("已写入 Agent 指令: %s" % path)
+        except Exception as e:
+            print("警告: 写 AGENTS.md 失败: %s" % e)
+    existing = settings.resolve_config_path()
+    if existing:
+        print("config.json 已存在（%s），不覆盖。要重填请删除后重跑" % existing)
+        return
+    if not os.path.isfile(EXAMPLE_CONFIG):
+        _err("缺 config.example.json（安装包不完整）")
+    cfg = read_json(EXAMPLE_CONFIG)
+    if not getattr(args, "no_input", False) and sys.stdin.isatty():
+        print("填写氚云连接配置（回车保留默认值；凭据不要分享或提交）")
+        prompts = [
+            ("baseUrl", "氚云地址"),
+            ("engineCode", "引擎编码 engineCode"),
+            ("engineSecret", "引擎密钥 engineSecret"),
+            ("authorization", "authorization（Bearer JWT，会过期）"),
+            ("appCode", "目标应用 appCode"),
+            ("appName", "应用名称（可选）"),
+        ]
+        for key, label in prompts:
+            cur = cfg.get(key, "")
+            if key in ("engineSecret", "authorization"):
+                shown = "已填" if cur else "空"
+            else:
+                shown = cur or "空"
+            val = input("%s [%s]: " % (label, shown)).strip()
+            if val:
+                cfg[key] = val
+    target = settings.default_config_path()
+    write_json(target, cfg)
+    print("已生成 %s" % target)
+    print("下一步: 填好凭据后运行 h3factory doctor 检查登录态")
+
+
+def check_registry(proj):
+    """check 用 registry：给每个已声明但未建表的表单补占位编码。
+    check 是**建表前**的关卡，此时 registry 还是空的，assoc/query 解析不到被引用表
+    编码会直接报错——占位码让关联定义照常走通（真实编码只在 build 时用）。"""
+    reg = dict(load_registry(proj) or {})
+    sj = os.path.join(project_dir(proj), "sheets")
+    if os.path.isdir(sj):
+        for fn in os.listdir(sj):
+            if fn.endswith(".json"):
+                k = os.path.splitext(fn)[0]
+                e = dict(reg.get(k) or {})
+                if not e.get("code"):
+                    e["code"] = "0" * 39          # 占位，非真实编码
+                reg[k] = e
+    return reg
+
+
+def cmd_check(args):
+    proj = args.proj
+    cfg = cfg_for(proj, required=False)
+    sheets = DSL.load_project(project_dir(proj), cfg["appCode"], check_registry(proj))
+    for key in resolve_targets(proj, sheets, args.targets):
+        d = sheets[key]()
+        n_rules = sum(1 for c in d["fields"]
+                      if (c.get("Options") or {}).get("DisplayRule", {}).get("Rule"))
+        n_rows = sum(1 for g in d.get("layout", []) if isinstance(g, list))
+        subs = d.get("subs") or []
+        n_sub = len(subs)
+        n_scol = sum(len(s["cols"]) for s in subs)
+        extra = " 子表=%d(列%d)" % (n_sub, n_scol) if n_sub else ""
+        n_ex = len(d.get("extras") or [])
+        if n_ex:
+            extra += " 布局项=%d" % n_ex
+        line = ("%-12s 字段=%-3d 隐藏规则=%d 行组(fourCols)=%d 关联=%s%s 标题=%s"
+                % (key, len(d["fields"]), n_rules, n_rows,
+                   ",".join(d["assoc"]) or "-", extra, d["title"]))
+        if d.get("group"):
+            line += " 分组=%s" % d["group"]
+        print(line)
+
+
+def cmd_list(args):
+    proj = args.proj
+    reg = load_registry(proj)
+    if not reg:
+        print("registry 为空 —— 尚未建表")
+        return
+    for k, v in sorted(reg.items()):
+        if k.startswith("_"):
+            continue   # 系统段（_groups 等），单独打印
+        sub = " ".join("%s=%s" % (sk, (sv or {}).get("code", ""))
+                       for sk, sv in sorted(((v or {}).get("subs") or {}).items()))
+        print("%-12s code=%s created=%s %s %s%s"
+              % (k, v.get("code"), v.get("created"), v.get("detail"),
+                 v.get("err"), (" 子表: " + sub) if sub else ""))
+    gs = reg.get("_groups")
+    if gs:
+        print("分组:")
+        for name, g in sorted(gs.items()):
+            g = g or {}
+            print("  %-10s code=%s objectId=%s"
+                  % (name, g.get("code"), g.get("objectId")))
+
+
+def _expect_field_count(form):
+    """回读设计树期望字段总数（与 V.collect_live 同口径）：
+    主字段 + 布局项（分组标题/描述：无 DataField，回读按 key 计一个节点）
+    + 每子表（1 子表主属性 + 列数）。
+    useOwner=true 时平台随表单附带系统拥有者两字段（OwnerId/OwnerDeptId），
+    回读设计树计入其 Options.DataField（verify 白名单同源）——须补 2。"""
+    n = (len(form["fields"]) + len(form.get("extras") or [])
+         + sum(1 + len(s["cols"]) for s in (form.get("subs") or [])))
+    return n + (2 if form.get("useOwner") else 0)
+
+
+def _live_design_count(con, code):
+    """LoadForm 回读设计树字段数（collect_live 口径）；线上不存在/失败 → None"""
+    try:
+        rd = con.load_form(code)
+        if not (rd and rd.get("Successful") is True):
+            return None
+        return len(V.collect_live(rd.get("ReturnData"))[0])
+    except Exception:
+        return None
+
+
+def build_one(proj, cfg, sheets, key, force=False, quiet=False, reg=None):
+    from h3platform.h3console import H3Console, save_form_console
+    from h3design import newbuilder as NB
+    reg = load_registry(proj) if reg is None else reg
+    con = H3Console(cfg)
+    app = cfg["appCode"]
+    rec = reg.get(key) or {}
+    # 编码一律复用（换码 = 断关联引用 + 线上留一张孤儿表）；force 只跳过下面
+    # "已存在即跳过" 的短路，不做换码。想重建新表：先删 registry 里该表的记录。
+    code = rec.get("code")
+    live_n = _live_design_count(con, code) if code else None
+    if code and live_n is not None and not force:
+        # 已存在：只读快速核对字段数，一致则登记 created=True（不重存）
+        try:
+            form = sheets[key]()
+        except Exception as e:
+            print("%-12s 已存在 code=%s —— 跳过（定义装载失败，未核对: %s）"
+                  % (key, code, str(e)[:200]))
+            return rec
+        n_expect = _expect_field_count(form)
+        if live_n == n_expect:
+            reg[key] = {"code": code, "created": True, "title": form["title"],
+                        "detail": "线上已存在，字段结构一致", "err": "",
+                        "subs": rec.get("subs", {})}
+            save_registry(proj, reg)
+            print("%-12s 已存在且结构一致 code=%s —— 跳过" % (key, code))
+        else:
+            print("%-12s 已存在但字段数不符 %d != %d —— 跳过（--force 才整表重存，"
+                  "会覆盖界面必填/联动配置）" % (key, live_n, n_expect))
+        return reg[key]
+    if code and live_n is None:
+        print("%-12s 注册表编码 %s 线上探测不到 —— 按不存在处理，发新编码" % (key, code))
+        code = None
+    if not code:
+        code = new_sheet_code(app)
+    form = sheets[key]()
+    subs = form.get("subs") or []
+    schema = NB.build_schema_str(form["fields"], form["name_schema"],
+                                 assoc=form["assoc"], app_package=app, subs=subs)
+    biz = NB.build_biz_sheet(code, form["fields"], layout=form.get("layout"),
+                             subs=subs)
+    # 第三段：位置控件的 Meters/PCEnabled/Editable 只能落在 ControlSettingsStr
+    settings = NB.build_control_settings(form["fields"])
+    err, detail, ok = "", "", False
+    try:
+        resp = save_form_console(con, code, cfg["engineCode"], app, app,
+                                 form["title"], schema, biz, pc_layout=1,
+                                 mobile_layout=1,
+                                 control_settings_str=settings)
+    except Exception as e:
+        err = str(e)[:500]
+        resp = None
+    ok = bool(resp and resp.get("Successful") is True)
+    # 期望字段总数 = 主字段 + 每个子表（1 主属性 + 列数）；useOwner 另含两系统字段
+    n_expect = _expect_field_count(form)
+    if ok:
+        import time
+        time.sleep(0.5)
+        rd = con.load_form(code).get("ReturnData")
+        dmc = rd.get("DesignModeContent")
+        dmc = json.loads(dmc) if isinstance(dmc, str) else dmc
+        live = V.collect_live(rd)
+        n_sub = len(subs)
+        detail = ("fields=%d(子表%d/列%d) nameSchema=%s"
+                  % (n_expect, n_sub, sum(len(s["cols"]) for s in subs),
+                     rd.get("NameSchema")))
+        if len(live[0]) != n_expect:
+            ok, err = False, "字段数不符 %d != %d（可能子表编码被 UI 改动）" \
+                % (len(live[0]), n_expect)
+    reg[key] = {"code": code, "created": ok, "title": form["title"],
+                "detail": detail, "err": err[:500],
+                "subs": (reg.get(key) or {}).get("subs", {})}
+    save_registry(proj, reg)
+    print("%-12s created=%s code=%s %s %s" % (key, ok, code, detail, err))
+    return reg[key]
+
+
+def cmd_build(args):
+    proj = args.proj
+    _require_auth(proj)
+    cfg = cfg_for(proj)
+    reg = load_registry(proj)
+    sheets = DSL.load_project(project_dir(proj), cfg["appCode"], reg)
+    for key in resolve_targets(proj, sheets, args.targets):
+        # 预注册子表 child schema 编码（须在 loader() 调用前写入 reg —— loader 惰性闭包
+        # 捕获同一个 reg dict；registry 条目结构 reg[key]["subs"][subkey]={"code":..}）
+        p = os.path.join(project_dir(proj), "sheets", key + ".json")
+        if os.path.isfile(p):
+            sreg = reg.setdefault(key, {}).setdefault("subs", {})
+            for spec in DSL.sheet_sub_specs(p):
+                sk = spec.get("key")
+                if not sk:
+                    _err("%s: 子表 spec 缺 key（%s）" % (key, spec))
+                ent = sreg.setdefault(sk, {})
+                # --force 重存须连子表编码一起换新：child schema 编码平台全局唯一，
+                # 沿用旧子码会与线上旧设计撞码（SaveForm 报"控件编码重复"）
+                if args.force or not ent.get("code"):
+                    ent["code"] = new_child_code(cfg["appCode"])
+        build_one(proj, cfg, sheets, key, force=args.force, reg=reg)
+
+
+def cmd_verify(args):
+    proj = args.proj
+    _require_auth(proj)
+    cfg = cfg_for(proj)
+    reg = load_registry(proj)
+    from h3platform.h3console import H3Console
+    con = H3Console(cfg)
+    sheets = DSL.load_project(project_dir(proj), cfg["appCode"], reg)
+    lines = []
+    allok = True
+    for key in resolve_targets(proj, sheets, args.targets):
+        rec = reg.get(key) or {}
+        code = rec.get("code")
+        if not code:
+            lines.append("== %s == 未建表（registry 无编码）" % key)
+            allok = False
+            continue
+        rd = con.load_form(code)
+        if not (rd and rd.get("Successful") is True):
+            lines.append("== %s == LoadForm 失败: %s" % (key, rd))
+            allok = False
+            continue
+        r = V.compare(sheets[key](), rd["ReturnData"])
+        lines.append(V.format_report("表", code, sheets[key](), rd["ReturnData"]))
+        allok = allok and r["ok"]
+    report = "\n".join(lines)
+    logp = os.path.join(project_dir(proj), "logs", "verify_report.txt")
+    os.makedirs(os.path.dirname(logp), exist_ok=True)
+    with open(logp, "w", encoding="utf-8") as f:
+        f.write(report)
+    sys.stdout.write(report[:6000])
+    print("\n报告: %s | 汇总: %s" % (logp, "ALL PASS" if allok else "有 FAIL"))
+
+
+def cmd_group(args):
+    """表单归组：确保 sheets JSON 声明的分组存在，把对应表移入所属分组。
+    幂等：分组编码/objectId 存 registry["_groups"]，已有组不重建；
+    每次运行把声明的表重新归位（界面上拖走的会被拉回声明组）。
+    平台没有分组读/删接口（2026-09-09 实证）——编码只认 registry，勿手删 _groups 段。"""
+    proj = args.proj
+    _require_auth(proj)
+    cfg = cfg_for(proj)
+    from h3platform import api as H3A
+    h3 = H3A.H3(cfg)
+    app = cfg["appCode"]
+    reg = load_registry(proj)
+    sheets = DSL.load_project(project_dir(proj), app, reg)
+    order = DSL.group_order(project_dir(proj))      # groups.json 顺序；None=不校验
+    pairs = []
+    for key in resolve_targets(proj, sheets, args.targets):
+        d = sheets[key]()
+        g = (d.get("group") or "").strip()
+        code = (reg.get(key) or {}).get("code")
+        if not g:
+            print("%-12s 未声明 group（sheets JSON 顶层）—— 跳过" % key)
+        elif not code:
+            print("%-12s 未建表（registry 无编码，先 build）—— 跳过" % key)
+        else:
+            pairs.append((key, g, code))
+    used = []
+    for _, g, _ in pairs:
+        if g not in used:
+            used.append(g)
+    if order is not None:
+        used = [g for g in order if g in used]
+    if not pairs:
+        return
+    greg = reg.setdefault("_groups", {})
+    lines = []
+    for g in used:
+        ent = greg.get(g) or {}
+        if ent.get("code") and ent.get("objectId"):
+            lines.append("分组 %-8s 已存在 code=%s —— 跳过" % (g, ent["code"]))
+            continue
+        try:
+            code, oid = h3.create_group(app, g)
+            time.sleep(0.3)
+            h3.update_group(app, code, oid, g)    # create→update 两步落定（UI 同款）
+            greg[g] = {"code": code, "objectId": oid}
+            lines.append("新建分组 %-8s code=%s objectId=%s" % (g, code, oid))
+        except H3A.H3Error as e:
+            lines.append("分组 %-8s 创建失败: %s" % (g, str(e)[:200]))
+        time.sleep(0.3)
+    save_registry(proj, reg)
+    for key, g, code in pairs:
+        gc = (greg.get(g) or {}).get("code")
+        if not gc:
+            lines.append("%-12s → %s: 分组不存在（上一步失败），跳过" % (key, g))
+            continue
+        try:
+            h3.move_node(code, gc)
+            lines.append("%-12s → 分组 %s" % (key, g))
+        except H3A.H3Error as e:
+            lines.append("%-12s → 分组 %s 失败: %s" % (key, g, str(e)[:200]))
+        time.sleep(0.2)
+    report = "\n".join(lines)
+    logp = os.path.join(project_dir(proj), "logs", "group_report.txt")
+    os.makedirs(os.path.dirname(logp), exist_ok=True)
+    with open(logp, "w", encoding="utf-8") as f:
+        f.write(report)
+    print(report)
+    print("\n报告: %s" % logp)
+    print("提示: 分组码只存 registry（平台无读/删分组接口）；多余分组在界面删。")
+
+
+def cmd_import(args):
+    proj, sheet, dataf = args.proj, args.sheet, args.data
+    _require_auth(proj)
+    cfg = cfg_for(proj)
+    reg = load_registry(proj)
+    code = (reg.get(sheet) or {}).get("code")
+    if not code:
+        _err("表单 %r 未建表（registry 无编码）" % sheet)
+    rows = read_json(dataf)
+    if isinstance(rows, dict):
+        rows = [rows]
+    from h3platform import api as H3A
+    h3 = H3A.H3(cfg)
+    n, failed = h3.create_biz_objects(code, rows, is_submit=args.submit)
+    print("导入 %s 成功 %d 条" % (sheet, n))
+    if failed:
+        print("失败 %d 条，首条: %s" % (len(failed), str(failed[0][1])[:300]))
+
+
+def cmd_gen(args):
+    proj, key = args.proj, args.sheet
+    cfg = cfg_for(proj, required=False)   # 本地渲染骨架，不需要真实凭据
+    reg = load_registry(proj)
+    sheets = DSL.load_project(project_dir(proj), cfg["appCode"], reg)
+    if key not in sheets:
+        _err("表单 %r 不在项目 %r" % (key, proj))
+    d = sheets[key]()
+    code = (reg.get(key) or {}).get("code") or ""
+    if not code:
+        print("警告: %s 尚未建表，生成的 schema 常量留空 —— 先跑 build" % key)
+    consts = []
+    for c in d["fields"]:
+        fkey, label = c["Key"], (c.get("Options") or {}).get("DisplayName", "")
+        consts.append('    private const string F_%-14s = %-24s // %s'
+                      % (fkey.upper(), '"%s";' % fkey, label))
+    for s in d.get("subs") or []:
+        # 子表: GRID_<SUBKEY> = child schema 编码；行集合访问见模板 TODO
+        subcode = s.get("code") or ""
+        consts.append('    private const string GRID_%-8s = %-30s // 子表 %s'
+                      % (s["key"].upper(), '"%s";' % subcode, s["label"]))
+        for col in s["cols"]:
+            consts.append('    //     子表行列 %s = %s'
+                          % (col["Key"], (col.get("Options") or {}).get("DisplayName", "")))
+    schema_consts = []
+    for k, v in sorted(reg.items()):
+        c = (v or {}).get("code")
+        if c:
+            # 常量名用完整 key（不截断）：截断 12 字符会让 contractcollect/contractpay、
+            # dailyreport/dailywage、invoiceapply/invoicereceipt 撞名编译失败
+            schema_consts.append('    private const string %-24s = "%s";   // %s'
+                                 % ("SCHEMA_" + k.upper(), c, v.get("title")))
+    with open(os.path.join(ROOT, "templates", "controller.cs.tpl"), encoding="utf-8") as f:
+        tpl = string.Template(f.read())
+    out = tpl.substitute(SCHEMA_CODE=code or key, SHEET_KEY=key, TITLE=d["title"],
+                         FIELD_CONSTS="\n".join(consts),
+                         SCHEMA_CONSTS="\n".join(schema_consts))
+    outp = os.path.join(project_dir(proj), "generated", key + ".cs")
+    os.makedirs(os.path.dirname(outp), exist_ok=True)
+    with open(outp, "w", encoding="utf-8") as f:
+        f.write(out)
+    print("已生成 %s" % outp)
+    print("下一步：按 TODO 补业务规则 → 粘贴到表单设计器 → 业务规则/后端事件 → 提交时")
+
+
+def cmd_demo(args):
+    src = os.path.join(ROOT, "projects", "demo")
+    if not os.path.isdir(src):
+        _err("安装包缺 projects/demo 示例")
+    dest = settings.project_dir("demo")
+    if os.path.isdir(dest):
+        print("示例项目已存在: %s" % dest)
+        return
+    shutil.copytree(src, dest)
+    print("已创建示例项目: %s" % dest)
+    print("下一步: h3factory check demo")
+
+
+def _jwt_payload(token):
+    """解码 JWT payload（不校验签名），用于判断 authorization 是否过期。"""
+    tok = (token or "").strip()
+    if tok.lower().startswith("bearer "):
+        tok = tok[7:].strip()
+    parts = tok.split(".")
+    if len(parts) < 2:
+        return None
+    try:
+        pad = "=" * (-len(parts[1]) % 4)
+        return json.loads(base64.urlsafe_b64decode(parts[1] + pad).decode("utf-8"))
+    except Exception:
+        return None
+
+
+def _config_state(proj=None):
+    """机器可读的凭据状态，供 agent 第一步做门禁。"""
+    path = None
+    cfg = {}
+    error = ""
+    if proj:
+        pc = os.path.join(settings.project_dir(proj), "config.json")
+        if os.path.isfile(pc):
+            path = pc
+            try:
+                cfg = read_json(pc)
+            except Exception as e:
+                error = "读取项目配置失败 %s: %s" % (pc, e)
+    if path is None:
+        path = settings.resolve_config_path()
+        if path:
+            try:
+                cfg = settings.load_config()
+            except settings.ConfigError as e:
+                error = str(e)
+    missing = [k for k in REQUIRED_KEYS if not cfg.get(k)]
+    info = _jwt_payload(cfg.get("authorization"))
+    exp = (info or {}).get("exp") if info else None
+    expired = bool(exp and exp < time.time())
+    expires_at = None
+    if exp:
+        expires_at = datetime.datetime.fromtimestamp(exp).astimezone().isoformat()
+    return {
+        "ok": bool(path) and not error and not missing and not expired,
+        "config_path": path,
+        "workspace": settings.workspace_root(),
+        "missing": missing,
+        "jwt_parseable": bool(info),
+        "jwt_exp": exp,
+        "jwt_expires_at": expires_at,
+        "jwt_expired": expired,
+        "app_code": cfg.get("appCode") or "",
+        "error": error,
+    }
+
+
+def _require_auth(proj=None):
+    """联网命令的硬门禁：凭据缺失或 token 过期直接拒绝执行。"""
+    state = _config_state(proj)
+    if state["ok"]:
+        return
+    if state["error"]:
+        reason = state["error"]
+    elif state["missing"]:
+        reason = "缺字段: %s" % ", ".join(state["missing"])
+    elif state["jwt_expired"]:
+        reason = "authorization 已过期（%s）" % state["jwt_expires_at"]
+    else:
+        reason = "凭据不可用"
+    _err("%s。先运行 h3factory auth status --json；客户提供 token 后"
+         "用 h3factory auth set --json（从 stdin 写入）" % reason)
+
+
+def cmd_auth(args):
+    if args.action == "status":
+        state = _config_state()
+        if args.json:
+            print(json.dumps(state, ensure_ascii=False, indent=2))
+        else:
+            print("配置文件: %s" % (state["config_path"] or "未找到"))
+            print("工作区  : %s" % state["workspace"])
+            if state["error"]:
+                print("[FAIL] %s" % state["error"])
+            if state["missing"]:
+                print("[FAIL] 缺字段: %s" % ", ".join(state["missing"]))
+            else:
+                print("[PASS] 凭据字段齐全（appCode=%s）" % state["app_code"])
+            if state["jwt_expired"]:
+                print("[FAIL] authorization 已过期: %s" % state["jwt_expires_at"])
+            elif state["jwt_exp"]:
+                print("[PASS] authorization 有效至 %s" % state["jwt_expires_at"])
+            elif state["app_code"]:
+                print("[WARN] authorization 不是可解析的 JWT")
+            print("结果: %s" % ("OK" if state["ok"] else "NEED_TOKEN"))
+        sys.exit(0 if state["ok"] else 2)
+
+    if args.action in ("set", "set-token"):
+        path = settings.resolve_config_path() or settings.default_config_path()
+        existing = {}
+        if os.path.isfile(path):
+            try:
+                existing = read_json(path)
+            except Exception as e:
+                _err("读取现有配置失败 %s: %s" % (path, e))
+        elif os.path.isfile(EXAMPLE_CONFIG):
+            existing = read_json(EXAMPLE_CONFIG)
+
+        if args.action == "set-token":
+            if sys.stdin.isatty():
+                import getpass
+                token = getpass.getpass("authorization token（输入不回显）: ").strip()
+            else:
+                token = sys.stdin.read().strip()
+            if not token:
+                _err("未收到 token（交互式直接运行 h3factory auth set-token；"
+                     "非交互式用 ... | h3factory auth set-token）")
+            existing["authorization"] = token
+            changed = ["authorization"]
+        else:
+            if sys.stdin.isatty():
+                _err("auth set 需要从 stdin 传 JSON；交互式请运行 h3factory init "
+                     "或 h3factory auth set-token")
+            try:
+                payload = json.load(sys.stdin)
+            except Exception as e:
+                _err("stdin 需要 JSON 对象: %s" % e)
+            if not isinstance(payload, dict):
+                _err("stdin 需要 JSON 对象，例如 {\"authorization\":\"...\"}")
+            unknown = [k for k in payload if k not in REQUIRED_KEYS + ("appName",)]
+            if unknown:
+                _err("不支持的字段: %s" % ", ".join(unknown))
+            changed = []
+            for key, value in payload.items():
+                if value is None:
+                    continue
+                existing[key] = str(value).strip()
+                changed.append(key)
+            if not changed:
+                _err("stdin 没有可写入的字段")
+
+        write_json(path, existing)
+        print("已更新 %s: %s" % (path, ", ".join(changed)))
+        print("（凭据值不回显；如需确认请运行 h3factory auth status）")
+        state = _config_state()
+        if state["ok"]:
+            print("凭据检查: OK（authorization 有效至 %s）" % state["jwt_expires_at"])
+        else:
+            print("凭据检查: 仍需处理（缺字段=%s, token过期=%s）"
+                  % (", ".join(state["missing"]) or "无", state["jwt_expired"]))
+            sys.exit(2)
+        return
+
+
+def cmd_doctor(args):
+    ok = True
+    print("h3factory doctor")
+    print("  版本      : %s" % VERSION)
+    print("  Python    : %s" % sys.version.split()[0])
+    print("  解释器    : %s" % sys.executable)
+    print("  代码目录  : %s" % ROOT)
+    print("  工作区    : %s" % settings.workspace_root())
+    pdir = settings.projects_dir()
+    print("  项目目录  : %s%s" % (pdir, "" if os.path.isdir(pdir)
+                                   else "（不存在，首次建项目时创建）"))
+    cfg_path = settings.resolve_config_path()
+    print("  配置文件  : %s" % (cfg_path or "未找到"))
+    cfg = {}
+    if not cfg_path:
+        print("  [FAIL] 缺配置：运行 h3factory init 后填写")
+        ok = False
+    else:
+        try:
+            cfg = settings.load_config()
+        except settings.ConfigError as e:
+            print("  [FAIL] %s" % e)
+            ok = False
+            cfg = {}
+        missing = [k for k in REQUIRED_KEYS if not cfg.get(k)]
+        if missing:
+            print("  [FAIL] 配置缺字段: %s" % ", ".join(missing))
+            ok = False
+        elif cfg:
+            print("  [PASS] 配置字段齐全（appCode=%s）" % cfg.get("appCode"))
+        info = _jwt_payload(cfg.get("authorization"))
+        exp = (info or {}).get("exp")
+        if exp:
+            expire_at = datetime.datetime.fromtimestamp(exp).astimezone()
+            if exp < time.time():
+                print("  [FAIL] authorization 已过期（%s），请去氚云后台重新生成"
+                      % expire_at.strftime("%Y-%m-%d %H:%M"))
+                ok = False
+            else:
+                days = max(0, int((exp - time.time()) // 86400))
+                print("  [PASS] authorization 有效至 %s（剩余 %d 天）"
+                      % (expire_at.strftime("%Y-%m-%d %H:%M"), days))
+        elif cfg.get("authorization"):
+            print("  [WARN] authorization 不是可解析的 JWT，无法判断是否过期")
+    home = os.path.expanduser("~")
+    for name in ("h3factory", "h3yun-dev-assistant"):
+        p = os.path.join(home, ".claude", "skills", name, "SKILL.md")
+        if os.path.isfile(p):
+            print("  [PASS] 技能 %s 已安装" % name)
+        else:
+            print("  [WARN] 技能 %s 未安装：运行 h3factory skill install" % name)
+    if not ok:
+        sys.exit(1)
+
+
+def cmd_docs(args):
+    d = os.path.join(ROOT, "docs")
+    if not args.name:
+        print("文档目录: %s" % d)
+        for fn in sorted(os.listdir(d)):
+            if fn.endswith(".md"):
+                print("  %s" % fn)
+        return
+    name = args.name if args.name.endswith(".md") else args.name + ".md"
+    p = os.path.join(d, name)
+    if not os.path.isfile(p):
+        names = ", ".join(sorted(f for f in os.listdir(d) if f.endswith(".md")))
+        _err("文档不存在: %s（可用: %s）" % (name, names))
+    with open(p, encoding="utf-8") as f:
+        sys.stdout.write(f.read())
+
+
+def _copy_dir(src, dst):
+    if os.path.isdir(dst):
+        shutil.rmtree(dst)
+    shutil.copytree(src, dst)
+
+
+def cmd_skill(args):
+    src_root = os.path.join(ROOT, "skills")
+    if not os.path.isdir(src_root):
+        _err("安装包缺 skills/ 目录")
+    skills = [d for d in sorted(os.listdir(src_root))
+              if os.path.isfile(os.path.join(src_root, d, "SKILL.md"))]
+    if not skills:
+        _err("skills/ 下没有可安装的技能")
+
+    if args.action == "list":
+        home = os.path.expanduser("~")
+        found = False
+        for dirname, tool in TOOL_SKILL_DIRS:
+            for name in skills:
+                p = os.path.join(home, dirname, "skills", name, "SKILL.md")
+                if os.path.isfile(p):
+                    print("[%s] %s" % (tool, p))
+                    found = True
+        if not found:
+            print("未发现已安装技能；运行 h3factory skill install --tool all")
+        return
+
+    home = os.path.expanduser("~")
+    targets = []
+    if args.scope == "project":
+        base = os.getcwd()
+        for dirname, tool in TOOL_SKILL_DIRS:
+            if args.tool in ("all", "auto", tool):
+                targets.append(os.path.join(base, dirname, "skills"))
+    else:
+        for dirname, tool in TOOL_SKILL_DIRS:
+            tool_dir = os.path.join(home, dirname)
+            if (args.tool == "all"
+                    or args.tool == tool
+                    or (args.tool == "auto"
+                        and (tool == "claude" or os.path.isdir(tool_dir)))):
+                targets.append(os.path.join(tool_dir, "skills"))
+    if not targets:
+        _err("没有匹配的安装目标（tool=%s, scope=%s）" % (args.tool, args.scope))
+    for dest_root in targets:
+        os.makedirs(dest_root, exist_ok=True)
+        for name in skills:
+            _copy_dir(os.path.join(src_root, name), os.path.join(dest_root, name))
+        print("已安装技能到 %s: %s" % (dest_root, ", ".join(skills)))
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="h3factory", description="h3factory —— 氚云表单工厂")
+    ap.add_argument("--version", action="version", version=VERSION)
+    sub = ap.add_subparsers(dest="cmd")
+    p = sub.add_parser("init", help="生成配置文件并写入 AGENTS.md")
+    p.add_argument("--no-input", action="store_true", help="不交互，只复制模板")
+    p.add_argument("--no-agent-md", action="store_true",
+                   help="不写入工作区 AGENTS.md")
+    p = sub.add_parser("agent", help="写入 AGENTS.md 指令（任意 Agent 通用）")
+    p.add_argument("action", choices=["init"])
+    p = sub.add_parser("prompt", help="打印通用提示语")
+    p.add_argument("--short", action="store_true", help="只输出一句话版本")
+    sub.add_parser("demo", help="把内置示例项目复制到工作区")
+    p = sub.add_parser("auth", help="凭据状态与录入（agent 第一步）")
+    p.add_argument("action", choices=["status", "set", "set-token"],
+                   help="status 检查；set 从 stdin 读 JSON；set-token 从 stdin 读 token")
+    p.add_argument("--json", action="store_true", help="status 输出 JSON")
+    sub.add_parser("doctor", help="检查 Python/配置/JWT/技能")
+    p = sub.add_parser("docs", help="列出或打印内置文档")
+    p.add_argument("name", nargs="?")
+    p = sub.add_parser("skill", help="安装/更新 AI 工具技能")
+    p.add_argument("action", choices=["install", "list"])
+    p.add_argument("--tool", default="all",
+                   choices=["auto", "all"] + [t for _, t in TOOL_SKILL_DIRS])
+    p.add_argument("--scope", default="user", choices=["user", "project"],
+                   help="user=各工具全局目录；project=当前目录")
+    helps = {"check": "本地校验表单定义（不联网）",
+             "list": "查看 registry 表编码与状态",
+             "build": "建表（已存在且结构一致则跳过）",
+             "verify": "LoadForm 只读回读比对",
+             "group": "建分组并把表归位（幂等）"}
+    for name in ("check", "list", "build", "verify", "group"):
+        p = sub.add_parser(name, help=helps[name])
+        p.add_argument("proj")
+        p.add_argument("targets", nargs="*")
+        if name == "build":
+            p.add_argument("--force", action="store_true", default=False,
+                           help="整表重存（会覆盖界面手工配置，慎用）")
+    p = sub.add_parser("import", help="批量导入表单数据")
+    p.add_argument("proj")
+    p.add_argument("sheet")
+    p.add_argument("data")
+    p.add_argument("--submit", action="store_true", default=False)
+    p = sub.add_parser("gen", help="生成 .cs 提交时代码骨架")
+    p.add_argument("proj")
+    p.add_argument("sheet")
+    args = ap.parse_args()
+    if not args.cmd:
+        state = _config_state()
+        print("h3factory %s —— 氚云表单工厂" % VERSION)
+        print("工作区: %s" % state["workspace"])
+        if state["ok"]:
+            print("凭据: OK（appCode=%s，token 有效至 %s）"
+                  % (state["app_code"], state["jwt_expires_at"]))
+            print("可用命令: h3factory --help")
+            sys.exit(0)
+        print("凭据: 需要录入")
+        print("  缺字段  : %s" % (", ".join(state["missing"]) or "无"))
+        print("  token过期: %s" % ("是" if state["jwt_expired"] else "否"))
+        print("agent 第一步: h3factory auth status --json")
+        print("录入 token: 客户在自己终端运行 h3factory auth set-token（输入不回显）")
+        print("或: h3factory init（交互式录入全部凭据）")
+        sys.exit(2)
+    {"init": cmd_init, "demo": cmd_demo, "auth": cmd_auth,
+     "agent": cmd_agent, "prompt": cmd_prompt,
+     "doctor": cmd_doctor, "docs": cmd_docs,
+     "skill": cmd_skill, "check": cmd_check, "list": cmd_list,
+     "build": cmd_build, "verify": cmd_verify, "group": cmd_group,
+     "import": cmd_import, "gen": cmd_gen}[args.cmd](args)
+
+
+if __name__ == "__main__":
+    main()