weaver-e10-builder 1.5.11 → 1.5.13

package/README.md

@@ -1,189 +1,212 @@
-# e10-cli — 泛微 OA 命令行工具
-
-> 面向开发者和自动化场景的 Eteams/Ebuilder 命令行工具。一行命令完成应用创建、表单管理、代码部署，无需打开浏览器。
-
-## 1. 产品定位
-
-泛微 OA 的日常操作（建应用、建表单、导代码、搜员工）原本只能在 Web 后台点选完成。`e10-cli` 把这些操作封装为标准命令行，支持：
-
-- **人工使用**：终端里快速执行，比网页点击快 10 倍
-- **AI Agent 调用**：Claude Code Agent 通过 CLI 自动完成复杂任务
-- **CI/CD 集成**：脚本化批量操作
-
-```
-# 创建应用 + 表单 + 流程，一条龙
-e10-cli app create 会议室管理
-e10-cli form create <appId> 会议室表单 ./project
-e10-cli workflow create <appId> <formObjId> 会议室审批
-```
-
-## 2. 命令全景
-
-### 2.1 代码相关（Ecode 自定义页面）
-
-| 命令 | 说明 |
-|------|------|
-| `e10-cli project create <name> [desc]` | 新建 Ecode 项目 |
-| `e10-cli project import <projectId> <zip> --main-url <url>` | 导入代码包 |
-| `e10-cli project tree <parentId>` | 查看目录结构 |
-| `e10-cli project read <fileId>` | 读取代码文件 |
-| `e10-cli project update <fileId> <content>` | 更新代码文件 |
-| `e10-cli project create-file <name> <parentId>` | 新建文件 |
-| `e10-cli project create-folder <name> <parentId>` | 新建文件夹 |
-| `e10-cli project delete-file <fileId>` | 删除文件 |
-| `e10-cli project delete-folder <folderId>` | 删除文件夹 |
-| `e10-cli check [dir]` | 代码质量自检 |
-
-### 2.2 Ebuilder 相关（应用 / 表单 / 流程 / 菜单）
-
-| 命令 | 说明 |
-|------|------|
-| `e10-cli app create <name> [desc]` | 新建 Ebuilder 应用 |
-| `e10-cli form read <objId> [dir]` | 读取表单字段 |
-| `e10-cli form list <appId>` | 列出应用表单 |
-| `e10-cli form create <appId> <name> <dir>` | 创建表单 |
-| `e10-cli form add-field <objId> <appId> <name> <type>` | 添加字段 |
-| `e10-cli form delete <objId> <appId>` | 删除表单 |
-| `e10-cli menu list <appId>` | 列出菜单 |
-| `e10-cli menu add <name> <path> <appId>` | 添加菜单 |
-| `e10-cli menu delete <menuId> <appId>` | 删除菜单 |
-| `e10-cli workflow create <appId> <formObjId> <name>` | 创建流程 |
-| `e10-cli form data add <objId> <json>` | 写入一条表单数据 |
-| `e10-cli form data list <objId>` | 查询表单数据 |
-| `e10-cli form data delete <objId> <dataId>` | 删除一条表单数据 |
-
-### 2.3 其他（人员 / 图标）
-
-| 命令 | 说明 |
-|------|------|
-| `e10-cli user search <keyword> [count]` | 模糊搜索员工 |
-| `e10-cli icon search <keyword...>` | 搜索 Ebuilder 图标 |
-
-## 3. 架构设计
-
-```
-┌─────────────────────────────────────────────┐
-│                    e10-cli                    │
-│                                               │
-│  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
-│  │ commands │  │   core   │  │   types     │ │
-│  │          │  │          │  │             │ │
-│  │ form     │  │ auth  ←──┼──┤ AuthData    │ │
-│  │ project  │  │ client   │  │ Employee    │ │
-│  │ app      │  │ crypto   │  │ MenuItem    │ │
-│  │ menu     │  │          │  │ ...         │ │
-│  │ workflow │  └────┬─────┘  └────────────┘ │
-│  │ user     │       │                         │
-│  │ icon     │       │ fetch + ETEAMSID        │
-│  │ check    │       │                         │
-│  └──────────┘       ▼                         │
-│               ┌──────────┐                    │
-│               │ 泛微 API │                    │
-│               │ (HTTPS)  │                    │
-│               └──────────┘                    │
-└─────────────────────────────────────────────┘
-```
-
-- **TypeScript 实现**，Node.js 18+ 运行，零外部运行时依赖
-- **Commander.js** 做命令行路由（npm 周下载量第一的 CLI 框架）
-- 每条命令对应一个函数，调用泛微 REST API，返回结构化结果
-- 支持 `--json` 输出机器可读格式，方便脚本管道
-
-## 4. 认证与安全
-
-### 4.1 设计原则
-
-> **命令行参数中永不出现凭证。**
-
-凭证加密存储在操作系统密钥链中，CLI 参数只传 `--profile`（环境名）或 `--auth <文件路径>`，实际 token 在进程内存中解密后通过 HTTPS Header 发送。
-
-| 层面 | 实现 |
-|------|------|
-| **静态存储** | `.eteams-auth.json` 文件内容使用 AES-256-GCM 加密 |
-| **密钥来源** | 32 字节随机密钥存操作系统密钥链，**每台机器一把，源码与仓库中不含任何密钥材料** |
-| **无密钥链时** | 回退到本地密钥文件（文件权限 `0600`），密钥仍是随机生成、非源码内置 |
-| **CLI 参数** | 只接受 `--profile` / `--auth <文件路径>`，不接受任何形式的 token/密码 |
-| **内存中** | 运行时解密到进程内存，通过 HTTPS Header 发送 |
-| **传输** | 全程 HTTPS，ETEAMSID 作为 HTTP Header 发送 |
-
-### 4.2 加密文件格式
-
-`.eteams-auth.json` 实际存储内容（加密后）：
-
-```json
-{
-  "enc": true,
-  "v": 1,
-  "data": "<base64(iv 12字节 + AES-256-GCM密文 + 认证标签 16字节)>"
-}
-```
-
-解密后得到真实的认证数据：
-
-```json
-{
-  "cookies": { "ETEAMSID": "PCACCOUNT_xxx..." },
-  "userId": "your_account",
-  "tenantKey": "your_tenant_key",
-  "baseUrl": "https://weapp.example.com",
-  "passportUrl": "https://passport.example.com",
-  "cookieSavedAt": 1783424987112
-}
-```
-
-### 4.3 威胁模型
-
-```
-攻击者能做什么              →  防护措施
-─────────────────────────────────────────────
-读取磁盘上的 auth 文件     →  AES-256-GCM 加密，密钥不在文件里
-查看进程命令行 (ps aux)    →  命令行从不出现任何凭证
-拦截网络传输               →  全程 HTTPS
-拿到源码或整个仓库         →  密钥在本机密钥链里，源码中没有任何密钥材料
-获取内存 dump              →  ETEAMSID 有时效性，过期自动失效
-```
-
-### 4.4 凭证生命周期
-
-```
-Web 登录 (SSO / 账号密码)
-  │
-  ├─→ 泛微 passport 返回 ETEAMSID
-  │
-  ├─→ AES-256-GCM 加密写入 .eteams-auth.json
-  │
-  ├─→ CLI 运行时解密到内存
-  │     │
-  │     ├─→ 每次 API 调用注入 eteamsid header → HTTPS → 泛微服务端
-  │     │
-  │     └─→ cookie 过期检测（302 重定向）→ 可选自动续签
-  │           │
-  │           └─→ 通过环境变量 E10_ACCOUNT / E10_PASSWORD RSA 重新登录
-  │                 （未设置则提示用户通过 Web 页面重新登录）
-```
-
-## 5. 安装使用
-
-```bash
-# 安装
-npm i -g weaver-e10-builder
-
-# 认证（通过 Web 登录一次，自动生成加密的 .eteams-auth.json）
-# 访问 http://localhost:7981 → SSO 登录 → 自动保存
-
-# 使用
-e10-cli user search 王晶
-e10-cli menu list 1289012843518550017 --json
-```
-
-## 6. 技术栈
-
-| 层 | 技术 |
-|----|------|
-| 语言 | TypeScript |
-| 运行时 | Node.js 18+ |
-| CLI 框架 | Commander.js |
-| HTTP | Node 内置 fetch |
-| 加密 | Node 内置 crypto (AES-256-GCM) |
-| 图标数据库 | sql.js (SQLite WASM) |
-| 打包 | tsc → 纯 JS，零依赖编译 |
+# e10-cli — 泛微 OA 命令行工具
+
+> 面向开发者和自动化场景的 Eteams/Ebuilder 命令行工具。一行命令完成应用创建、表单管理、代码部署，无需打开浏览器。
+
+## 1. 产品定位
+
+泛微 OA 的日常操作（建应用、建表单、导代码、搜员工）原本只能在 Web 后台点选完成。`e10-cli` 把这些操作封装为标准命令行，支持：
+
+- **人工使用**：终端里快速执行，比网页点击快 10 倍
+- **AI Agent 调用**：Claude Code Agent 通过 CLI 自动完成复杂任务
+- **CI/CD 集成**：脚本化批量操作
+
+```
+# 创建应用 + 表单 + 流程，一条龙
+e10-cli app create 会议室管理
+e10-cli form create <appId> 会议室表单 ./project
+e10-cli workflow create <appId> <formObjId> 会议室审批
+```
+
+## 2. 命令全景
+
+### 2.1 代码相关（Ecode 自定义页面）
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli project create <name> [desc]` | 新建 Ecode 项目 |
+| `e10-cli project import <projectId> <zip> --main-url <url>` | 导入代码包 |
+| `e10-cli project tree <parentId>` | 查看目录结构 |
+| `e10-cli project read <fileId>` | 读取代码文件 |
+| `e10-cli project update <fileId> <content>` | 更新代码文件 |
+| `e10-cli project create-file <name> <parentId>` | 新建文件 |
+| `e10-cli project create-folder <name> <parentId>` | 新建文件夹 |
+| `e10-cli project delete-file <fileId>` | 删除文件 |
+| `e10-cli project delete-folder <folderId>` | 删除文件夹 |
+| `e10-cli check [dir]` | 代码质量自检 |
+
+### 2.2 Ebuilder 相关（应用 / 表单 / 流程 / 菜单）
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli app create <name> [desc]` | 新建 Ebuilder 应用 |
+| `e10-cli form read <objId> [dir]` | 读取表单字段 |
+| `e10-cli form list <appId>` | 列出应用表单 |
+| `e10-cli form create <appId> <name> <dir>` | 创建表单 |
+| `e10-cli form add-field <objId> <appId> <name> <type>` | 添加字段 |
+| `e10-cli form delete <objId> <appId>` | 删除表单 |
+| `e10-cli menu list <appId>` | 列出菜单 |
+| `e10-cli menu add <name> <path> <appId>` | 添加菜单 |
+| `e10-cli menu delete <menuId> <appId>` | 删除菜单 |
+| `e10-cli workflow create <appId> <formObjId> <name>` | 创建流程 |
+| `e10-cli form data add <objId> <json>` | 写入一条表单数据 |
+| `e10-cli form data list <objId>` | 查询表单数据 |
+| `e10-cli form data delete <objId> <dataId>` | 删除一条表单数据 |
+
+### 2.3 其他（人员 / 图标）
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli user search <keyword> [count]` | 模糊搜索员工 |
+| `e10-cli icon search <keyword...>` | 搜索 Ebuilder 图标 |
+
+## 3. 架构设计
+
+```
+┌─────────────────────────────────────────────┐
+│                    e10-cli                    │
+│                                               │
+│  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
+│  │ commands │  │   core   │  │   types     │ │
+│  │          │  │          │  │             │ │
+│  │ form     │  │ auth  ←──┼──┤ AuthData    │ │
+│  │ project  │  │ client   │  │ Employee    │ │
+│  │ app      │  │ crypto   │  │ MenuItem    │ │
+│  │ menu     │  │          │  │ ...         │ │
+│  │ workflow │  └────┬─────┘  └────────────┘ │
+│  │ user     │       │                         │
+│  │ icon     │       │ fetch + ETEAMSID        │
+│  │ check    │       │                         │
+│  └──────────┘       ▼                         │
+│               ┌──────────┐                    │
+│               │ 泛微 API │                    │
+│               │ (HTTPS)  │                    │
+│               └──────────┘                    │
+└─────────────────────────────────────────────┘
+```
+
+- **TypeScript 实现**，Node.js 18+ 运行，零外部运行时依赖
+- **Commander.js** 做命令行路由（npm 周下载量第一的 CLI 框架）
+- 每条命令对应一个函数，调用泛微 REST API，返回结构化结果
+- 支持 `--json` 输出机器可读格式，方便脚本管道
+
+## 4. 认证与安全
+
+### 4.1 设计原则
+
+> **命令行参数中永不出现凭证。**
+
+凭证加密存储在操作系统密钥链中，CLI 参数只传 `--profile`（环境名）或 `--auth <文件路径>`，实际 token 在进程内存中解密后通过 HTTPS Header 发送。
+
+| 层面 | 实现 |
+|------|------|
+| **静态存储** | `.eteams-auth.json` 文件内容使用 AES-256-GCM 加密 |
+| **密钥来源** | 32 字节随机密钥存操作系统密钥链，**每台机器一把，源码与仓库中不含任何密钥材料** |
+| **无密钥链时** | 回退到本地密钥文件（文件权限 `0600`），密钥仍是随机生成、非源码内置 |
+| **CLI 参数** | 只接受 `--profile` / `--auth <文件路径>`，不接受任何形式的 token/密码 |
+| **内存中** | 运行时解密到进程内存，通过 HTTPS Header 发送 |
+| **传输** | 全程 HTTPS，ETEAMSID 作为 HTTP Header 发送 |
+
+### 4.2 加密文件格式
+
+`.eteams-auth.json` 实际存储内容（加密后）：
+
+```json
+{
+  "enc": true,
+  "v": 1,
+  "data": "<base64(iv 12字节 + AES-256-GCM密文 + 认证标签 16字节)>"
+}
+```
+
+解密后得到真实的认证数据：
+
+```json
+{
+  "cookies": { "ETEAMSID": "PCACCOUNT_xxx..." },
+  "userId": "your_account",
+  "tenantKey": "your_tenant_key",
+  "baseUrl": "https://weapp.example.com",
+  "passportUrl": "https://passport.example.com",
+  "cookieSavedAt": 1783424987112
+}
+```
+
+### 4.3 威胁模型
+
+```
+攻击者能做什么              →  防护措施
+─────────────────────────────────────────────
+读取磁盘上的 auth 文件     →  AES-256-GCM 加密，密钥不在文件里
+查看进程命令行 (ps aux)    →  命令行从不出现任何凭证
+拦截网络传输               →  全程 HTTPS
+拿到源码或整个仓库         →  密钥在本机密钥链里，源码中没有任何密钥材料
+获取内存 dump              →  ETEAMSID 有时效性，过期自动失效
+```
+
+### 4.4 凭证生命周期
+
+```
+Web 登录 (SSO / 账号密码)
+  │
+  ├─→ 泛微 passport 返回 ETEAMSID
+  │
+  ├─→ AES-256-GCM 加密写入 .eteams-auth.json
+  │
+  ├─→ CLI 运行时解密到内存
+  │     │
+  │     ├─→ 每次 API 调用注入 eteamsid header → HTTPS → 泛微服务端
+  │     │
+  │     └─→ cookie 过期检测（302 重定向）→ 可选自动续签
+  │           │
+  │           └─→ 通过环境变量 E10_ACCOUNT / E10_PASSWORD RSA 重新登录
+  │                 （未设置则提示用户通过 Web 页面重新登录）
+```
+
+## 5. 安装使用
+
+```bash
+# 安装
+npm i -g weaver-e10-builder
+
+# 认证（通过 Web 登录一次，自动生成加密的 .eteams-auth.json）
+# 访问 http://localhost:7981 → SSO 登录 → 自动保存
+
+# 使用
+e10-cli user search 王晶
+e10-cli menu list 1289012843518550017 --json
+```
+
+## 6. 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 语言 | TypeScript |
+| 运行时 | Node.js 18+ |
+| CLI 框架 | Commander.js |
+| HTTP | Node 内置 fetch |
+| 加密 | Node 内置 crypto (AES-256-GCM) |
+| 图标数据库 | sql.js (SQLite WASM) |
+| 打包 | tsc → 纯 JS，零依赖编译 |
+
+## 7. 图片和 XLSX 源样式还原
+
+现有表单和字段创建行为保持原样。新增布局命令把源样表绑定到已创建字段，生成 pageLayouts 和原生 workbook，通过 saveFormAndLayout 单次保存并独立回读。实现全部位于 CLI 内，不依赖 Form Engine 或 Python。
+
+```bash
+e10-cli form layout extract sample.xlsx --out layout-source.json
+e10-cli form layout compile <objId> --source @layout-source.json --spec @layout-spec.json --out layout-artifact.json
+e10-cli form layout apply <objId> --artifact @layout-artifact.json --out layout-result.json
+e10-cli form layout verify <objId> --artifact @layout-artifact.json
+```
+
+图片先用 `form layout image-context <file> --out image-context.json` 获取真实哈希，由 Agent 查看图片后按文档产出结构化观察，再通过 `extract --observation` 接入同一编译链。`inspect` 导出完整原生上下文，`compile --context` 支持无登录的离线编译。
+
+图片样式在保存前需经用户二次确认：`form layout style-review --source @json --spec @json --out <file>` 展示字体、字号、颜色及对齐；用户自然语言修改由 Agent 定位，`--overrides` 逐项转换，未知单项保留图片识别值。收到用户确认或明确修改后才使用 `--confirm`，再重新 compile。v4 同步几何区域的标题对齐到组件样式，并在图片保存前检查确认状态，Excel 和旧产物保持原行为。
+
+`form create` 可加 `--layout-source`、`--layout-spec` 和 `--layout-artifact-out`，在字段补写与归组结束后衔接还原。布局失败保留已有表单并返回具体部分状态，不重新建表。
+
+当前范围为已有单个 PC EXCEL 页面、普通主表和完整原生普通明细。保留业务配置；未匹配字段、标题冲突、跨界合并、嵌套容器及不支持源样式会明确报告。独立回读证明结构和支持样式，图片像素一致性需另行渲染验收。详见 [源样式指南](skill/references/form/guide-form-layout-source.md) 和 [LayoutSpec Schema](assets/layout-spec.schema.json)。
+
+图片观察新增可选 `imageStyles`，支持颜色、字体粗细/字号、对齐、边框、页面背景及已有原生分类支持的组件外观。图片 extract 规范化 `align/bold` 别名，bold 不再被错误替换为下划线；compile 同步 workbook 与组件自定义样式，并输出 imageStyleReport。使用 `form layout style-audit <id> --artifact @json [--context @json]` 定位 cell/component/page 层的样式漂移。未观察到样式或分类不闭合默认阻断，不切换基础模板，也不修改字段业务属性。Schema 见 [图片样式观察](assets/image-style-observation.schema.json)。
+
+v5 图片布局增加表格外框观察与回读检查：`imageStyles.tableBorders` 明确正文范围及四侧边线，区分有线、none 和 unknown；未观察不能保存。几何投影保留已声明的外围边线，外框落在正文边缘。`style-review` 展示表格线粗细清单，`gridBorderStyle` 支持对已声明表格的外框及内部线统一调整粗细/颜色/线型；控件输入框和标题区保持独立。新旧编译产物按各自版本校验。