h3factory —— 氚云表单工厂

把「需求文档 → 设计 → 建表 → 数据 → 代码」固化成流水线。确定性部分（建表/导入/校验/骨架代码）全部脚本化，零 LLM 依赖；智能部分（需求→设计、业务规则代码）由 Claude Code 现场完成。 两者靠一份表单 JSON 定义接起来。

📖 完整使用手册：HTML 版（可离线打开/打印 PDF） · Markdown 版

需求文档
   ↓  [AI 层] 按 docs/requirement_checklist.md 澄清 → 产出设计稿 + 表单 JSON → 人工过目
projects/<名>/sheets/*.json + dicts.json
   ↓  [工厂层] h3factory build <名>
氚云线上表单（编码自动注册 registry.json）
   ↓  h3factory verify <名>   ← 只读回读核对（字段/隐藏规则/一行多列/子表/布局项/位置设置/NameSchema）
   ↓  h3factory gen <名> <表> ← .cs 提交时代码骨架（TODO 由 AI/人补业务规则）
交付：代码 +「界面手工配置清单」（必填/审批流等 UI-only 项平台 API 配不了）

安装

要求：Node.js ≥ 16、Python ≥ 3.10（只用标准库，无需 pip 安装依赖）。

从 npm 安装（推荐）

npm install -g h3factory

# 国内镜像（npmmirror 会同步公共 npm 包）
npm install -g h3factory --registry https://registry.npmmirror.com

任何支持技能目录的 Agent 装完即用，无需额外配置。

从 GitHub 私有仓库安装（内部/源码）

私有仓库不要用 github:账号/仓库 简写——npm 会匿名请求 codeload，私有仓会返回 404。用完整 git 地址：

# SSH（需本机已配置 GitHub SSH key）
npm install -g git+ssh://[email protected]/xiangduo10146814/h3factory.git

# 若 22 端口不通，改用 SSH 443（GitHub 官方支持）
git config --global url."ssh://[email protected]:443/".insteadOf "ssh://[email protected]/"
npm install -g git+ssh://[email protected]/xiangduo10146814/h3factory.git

# HTTPS + PAT（token 会留在 shell 历史，注意保密）
npm install -g git+https://<TOKEN>@github.com/xiangduo10146814/h3factory.git

从本地 tarball 安装

npm pack                       # 生成 h3factory-0.2.3.tgz
npm install -g ./h3factory-0.2.3.tgz

安装时 postinstall 会把 skills/h3factory 和 skills/h3yun-dev-assistant 复制到 Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun / CodeBuddy / WorkBuddy 的用户技能目录（不存在会创建）。技能更新由安装包管理，会覆盖本地修改。

快速开始

mkdir D:\h3work && cd /d D:\h3work   # 任意工作区目录，别用 System32

h3factory auth status --json   # Agent 第一步：检查凭据，ok=false 就先录 token
h3factory init                 # 交互录入 + 写入 AGENTS.md（任何 Agent 都能读到）
h3factory prompt               # 打印通用提示语，直接贴给任意 Agent
h3factory doctor               # 检查 Python / 配置 / JWT 是否过期 / 技能
h3factory demo                 # 复制内置示例项目到 ./projects/demo
h3factory check demo           # 离线校验，不联网

凭据字段：baseUrl、engineCode、engineSecret、authorization（JWT，会过期）、appCode。 authorization 可以只填 JWT 本身，不带 Bearer ；CLI 会自动补全（也兼容小写 bearer 和引号）。 Agent 写凭据用 stdin，避免出现在命令行参数里：

h3factory auth set --json <<'JSON'
{"authorization": "<JWT>"}
JSON

authorization 过期后去氚云后台重新生成粘回，再跑 h3factory auth status 确认。

工作区模型

命令在当前目录执行，当前目录就是工作区：

<工作区>/
├─ config.json              # 凭据（勿提交/分享）
└─ projects/<项目名>/
   ├─ config.json           # 可选，覆盖工作区凭据
   ├─ dicts.json            # 枚举字典
   ├─ groups.json           # 可选，表单分组与顺序
   ├─ sheets/*.json         # 每张表单一个定义文件
   ├─ registry.json         # 平台编码注册表，勿手改
   ├─ logs/                 # verify/group 报告
   └─ generated/            # .cs 代码骨架

配置查找顺序：H3FACTORY_CONFIG → ./config.json → ~/.h3factory/config.json。 工作区也可用环境变量指定：H3FACTORY_HOME=D:\h3work h3factory check demo。

命令

| 命令 | 作用 | 联网 | |---|---|---| | h3factory auth status [--json] | 凭据门禁：检查配置与 JWT 是否可用 | 否 | | h3factory auth set --json | 从 stdin 读 JSON 写入凭据（值不回显） | 否 | | h3factory auth set-token | 从 stdin 读 token 写入 | 否 | | h3factory init [--no-input] [--no-agent-md] | 生成 config.json 并写入 AGENTS.md | 否 | | h3factory agent init | 只写 AGENTS.md 指令块 | 否 | | h3factory prompt [--short] | 打印任意 Agent 可用的提示语 | 否 | | h3factory demo | 复制内置示例项目 | 否 | | h3factory doctor | 检查运行时、配置、JWT、技能 | 否 | | h3factory check <项目> [表..] | 本地加载并校验表单定义 | 否 | | h3factory list <项目> | registry 各表编码与状态 | 否 | | h3factory build <项目> [表..] [--force] | 建表；已存在且结构一致则跳过 | 是 | | h3factory verify <项目> [表..] | LoadForm 只读回读比对 | 是 | | h3factory group <项目> [表..] | 建分组并归位（幂等） | 是 | | h3factory import <项目> <表> <data.json> [--submit] | 批量导数据 | 是 | | h3factory gen <项目> <表> | 生成 .cs 提交时代码骨架 | 否 | | h3factory docs [名称] | 列出/打印内置文档 | 否 | | h3factory skill install [--tool all\|auto\|<工具>] [--scope user\|project] | 安装/更新技能 | 否 | | h3factory skill list | 查看各工具已安装位置 | 否 | | h3factory --version | 版本 | 否 |

源码目录内仍可用旧方式：python -X utf8 cli.py <命令>（Windows GBK 控制台必须带 -X utf8）。

与各种 Agent 配合

npm 安装后会把技能自动复制到以下用户级技能目录（目录不存在也会创建）：

| Agent | 技能目录 | |---|---| | Claude Code | ~/.claude/skills/ | | Codex | ~/.codex/skills/ | | Cursor | ~/.cursor/skills/ | | OpenCode | ~/.opencode/skills/ | | QwenWork | ~/.qwenworkcn/skills/ | | Qoder / QoderWork | ~/.qoder/skills/、~/.qoderwork/skills/ | | Mulerun | ~/.mulerun/skills/ | | CodeBuddy | ~/.codebuddy/skills/ | | WorkBuddy | ~/.workbuddy/skills/ |

随包安装两个技能：

• h3factory —— 工厂总入口：凭据门禁、澄清需求、产出 sheets JSON、调用 CLI、交付清单。
• h3yun-dev-assistant —— 氚云二开规范：C# 后端、ES5 前端、SQL、控件编码、平台限制。

Agent 会话第一步：录入 token

技能里已写成硬门禁。Agent 每次会话先执行：

h3factory auth status --json     # 看 ok / missing / jwt_expired

ok=false 时向客户要 token，并通过 stdin 写入（不放进命令行参数、不回显）：

h3factory auth set --json <<'JSON'
{"authorization": "<客户提供的 JWT>"}
JSON

再次运行 h3factory auth status --json，ok=true 后才允许 build/verify/group/import。 CLI 自身也会在 build/verify/group/import 启动时做同样的检查，token 缺失或过期会直接拒绝执行。

首选方式：让客户在自己的终端运行 h3factory auth set-token（输入隐藏，token 不进入对话记录）； 还缺其他字段就运行 h3factory init。只有客户主动在对话里贴 token 时，才用上面的 auth set --json。

通用提示语（不依赖技能加载）

任何 Agent（包括 WorkBuddy / CodeBuddy，或不会自动加载技能的模型）都可以这样用：

h3factory prompt          # 打印通用提示语，复制给 Agent
h3factory prompt --short  # 只要一句话版本

或者在项目目录运行一次 h3factory init：它会在工作区写入 AGENTS.md， Codex 等会读取项目指令的 Agent 下次会话就能自动看到 h3factory 的流程和 token 门禁。 不读 AGENTS.md 的 Agent，直接把 h3factory prompt 的输出贴进去即可。

新需求直接对 Agent 说：

用 h3factory 帮我做这个需求：<需求文档/链接/文本>

技能会按 docs/requirement_checklist.md 澄清，产出 projects/<新项目>/ 设计并停下来等你过目；确认后才建表。

关键规则（血泪教训，详见 docs/platform_gotchas.md）

• verify 只读、可重复跑；build --force 才整表重存 —— 重存 = 整体替换，会抹掉界面上手工配的必填/联动，慎用。
• 界面手工活（必填、审批流、字段联动、只读）API 配不了，每次交付附「界面配置清单」。
• 表单下拉存储「名称」，代码位另用字典表转换 —— 设计时就想清「存名称还是代码」。
• 代码类、schema code 注册在 projects/<名>/registry.json，删了会发新编码、断关联。
• config.json 含凭据：不提交、不分享、不让 AI 打印。

源码结构

h3factory/
├─ bin/h3factory.js          # npm 入口：探测 Python 3.10+ 并转调 cli.py
├─ cli.py                    # init/demo/doctor/check/list/build/verify/group/import/gen
├─ h3platform/               # 连接层：Console SaveForm/LoadForm + OpenAPI + 配置解析
├─ h3design/                 # 设计层：控件工厂 / SaveForm 载荷 / JSON DSL
├─ h3verify/verify.py        # LoadForm 只读回读比对
├─ skills/                   # 随包安装到各 Agent 的技能
├─ templates/controller.cs.tpl
├─ docs/                     # workflow / schema_doc / requirement_checklist / platform_gotchas
├─ scripts/postinstall.js    # 技能安装
└─ projects/demo/            # 内置示例（打包时带上）

开发与发布

npm pack --dry-run     # 检查包内容：不得出现 config.json / 业务 projects / logs
npm pack               # 生成 tarball
npm install -g ./h3factory-0.2.3.tgz
h3factory check demo   # 冒烟

发布到公共 npm（维护者）：

npm login --registry https://registry.npmjs.org
npm publish                 # package.json 的 publishConfig 已指向 npmjs

代码仓库（私有）：https://github.com/xiangduo10146814/h3factory

日常更新：

git add .
git commit -m "feat: ..."
git push origin main        # 本机 github.com:443 不通时，用 gh api / 代理推送

仓库默认不跟踪业务项目（projects/* 已忽略，仅保留 projects/demo），凭据文件也不会入库。