hap-cli 0.5.0__py3-none-any.whl

hap_cli/README_CN.md

@@ -0,0 +1,601 @@
+# hap-cli
+
+**明道云 HAP** 命令行工具 —— 企业级无代码平台 (hap) 的 CLI 操控接口。
+
+通过命令行管理应用、工作表、数据记录、工作流、审批流程和角色权限，支持 JSON 输出以便自动化集成。
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+## 快速开始
+
+### 1. 登录认证
+
+**方式一：浏览器登录（推荐）**
+
+```bash
+# 明道云 SaaS（默认）
+hap config login
+
+# 指定服务器
+hap config login mingdao    # 明道云
+hap config login nocoly     # nocoly
+hap config login https://hap.example.com   # 私有部署
+```
+
+执行后会自动打开浏览器，在明道云页面完成登录后，token 会自动保存到本地配置。
+
+**方式二：手动配置 Token**
+
+```bash
+hap config set \
+  --server https://你的明道云服务器地址 \
+  --token 你的_MD_PSS_ID_令牌 \
+  --app-id 默认应用ID \
+  --project-id 组织ID
+```
+
+> `md_pss_id` 令牌可从浏览器登录明道云后的 Cookie 中获取。
+
+**查看当前用户**
+
+```bash
+hap config whoami
+```
+
+**退出登录**
+
+```bash
+hap config logout
+```
+
+### 2. 查看工作表列表
+
+```bash
+hap app worksheets
+```
+
+### 3. 查询数据记录
+
+```bash
+hap record list 工作表ID --page-size 10
+```
+
+### 4. JSON 输出（用于自动化）
+
+```bash
+hap --json record list 工作表ID
+```
+
+## 命令总览
+
+| 命令组 | 功能说明 |
+|--------|---------|
+| `config` | 服务器连接与认证配置 |
+| `app` | 应用管理（列表、详情、工作表） |
+| `worksheet` | 工作表操作（信息、字段、视图） |
+| `record` | 数据记录增删改查 |
+| `workflow` | 工作流生命周期（创建、编辑、发布、触发、回滚、配置） |
+| `node` | 流程节点管理（添加、删除、数据处理、查询记录、批量操作、测试代码/WebHook/AI） |
+| `instance` | 审批与待办（通过、否决、转审、加签、批量操作、执行历史） |
+| `role` | 角色与权限管理 |
+| `repl` | 交互式命令行模式 |
+
+## 工作流管理
+
+### 创建与编辑流程
+
+```bash
+# 创建工作流
+hap workflow create --company-id 组织ID --name "请假审批" --app-id 应用ID
+
+# 查看流程详情
+hap workflow get 流程ID
+
+# 修改流程信息
+hap workflow update 流程ID --name "新名称" --desc "流程说明"
+
+# 复制工作流
+hap workflow copy 流程ID --name "请假审批-副本"
+
+# 移动到其他应用
+hap workflow move 流程ID 目标应用ID
+
+# 删除工作流
+hap workflow delete 流程ID --yes
+```
+
+### 节点操作
+
+```bash
+# 查看所有节点类型和 Action ID
+hap node types
+
+# 查看所有节点
+hap node list 流程ID
+
+# 添加审批节点（type 4=审批）
+hap node add 流程ID --type 4 --name "主管审批" --after 起始节点ID
+
+# 添加填写节点（type 3=填写）
+hap node add 流程ID --type 3 --name "补充信息"
+
+# 添加数据处理节点（type 6=ACTION，action-id 指定操作类型）
+hap node add 流程ID --type 6 --name "新增记录" --action-id 1
+hap node add 流程ID --type 6 --name "更新记录" --action-id 2
+hap node add 流程ID --type 6 --name "删除记录" --action-id 3
+
+# 添加查询单条记录节点（type 7=SEARCH）
+hap node add 流程ID --type 7 --name "查询记录" --action-id 406
+
+# 添加获取多条记录节点（type 13=GET_MORE_RECORD）
+hap node add 流程ID --type 13 --name "获取多条" --action-id 400
+
+# 添加代码块节点（type 14=代码）
+hap node add 流程ID --type 14 --name "计算逻辑"
+
+# 添加 WebHook 节点（type 8=WebHook）
+hap node add 流程ID --type 8 --name "调用外部接口"
+
+# 添加 AI 节点（type 31=AIGC）
+hap node add 流程ID --type 31 --name "AI 摘要"
+
+# 添加延迟节点（type 12）
+hap node add 流程ID --type 12 --name "延迟1小时"
+
+# 添加子流程节点（type 16）
+hap node add 流程ID --type 16 --name "调用子流程"
+
+# 添加循环节点（type 29）
+hap node add 流程ID --type 29 --name "循环处理"
+
+# 查看节点详细配置
+hap node get 流程ID 节点ID
+
+# 获取工作表字段（用于配置数据处理节点）
+hap node controls 流程ID 节点ID --app-id 工作表ID
+
+# 重命名节点
+hap node rename 流程ID 节点ID --name "新节点名"
+
+# 修改节点描述
+hap node desc 流程ID 节点ID --desc "节点说明" --alias "别名"
+
+# 保存节点完整配置（通用 JSON 方式）
+hap node save 流程ID 节点ID --type 4 --config '{"accounts":[{"accountId":"用户ID"}]}'
+
+# 删除节点
+hap node delete 流程ID 节点ID --yes
+```
+
+### 数据处理节点
+
+#### 新增/编辑/删除记录（ACTION 节点，type=6）
+
+```bash
+# 新增记录（action-id=1）
+hap node save-action 流程ID 节点ID -a 1 --app-id 工作表ID \
+  -f '[{"fieldId":"字段ID","type":2,"fieldValue":"值"}]'
+
+# 编辑记录（action-id=2，需指定数据来源节点）
+hap node save-action 流程ID 节点ID -a 2 --app-id 工作表ID \
+  -s 来源节点ID \
+  -f '[{"fieldId":"字段ID","type":2,"fieldValue":"新值"}]'
+
+# 删除记录（action-id=3）
+hap node save-action 流程ID 节点ID -a 3 --app-id 工作表ID \
+  -s 来源节点ID
+
+# 获取关联记录（action-id=20）
+hap node save-action 流程ID 节点ID -a 20 --app-id 工作表ID \
+  -s 来源节点ID
+
+# 刷新单条数据（action-id=6）
+hap node save-action 流程ID 节点ID -a 6 --app-id 工作表ID \
+  -s 来源节点ID
+```
+
+#### 查询单条记录（SEARCH 节点，type=7）
+
+```bash
+# 从工作表查询一条记录（action-id=406）
+hap node save-search 流程ID 节点ID -a 406 --app-id 工作表ID \
+  --condition '[{"fieldId":"字段ID","conditionId":"1","value":["条件值"]}]'
+
+# 从多条数据中取一条（action-id=407）
+hap node save-search 流程ID 节点ID -a 407 -s 多条数据节点ID
+
+# 查询并更新（action-id=421）
+hap node save-search 流程ID 节点ID -a 421 --app-id 工作表ID \
+  --condition '[{"fieldId":"c001","conditionId":"1","value":["test"]}]' \
+  -f '[{"fieldId":"c002","type":2,"fieldValue":"更新值"}]'
+
+# 查询并删除（action-id=422）
+hap node save-search 流程ID 节点ID -a 422 --app-id 工作表ID \
+  --condition '[{"fieldId":"c001","conditionId":"1","value":["test"]}]'
+
+# 未找到时的处理方式
+hap node save-search 流程ID 节点ID -a 406 --app-id 工作表ID \
+  --not-found 2    # 0=中止流程, 1=新增记录, 2=继续执行
+
+# 随机取一条
+hap node save-search 流程ID 节点ID -a 406 --app-id 工作表ID --random
+```
+
+#### 获取多条记录 / 批量操作（GET_MORE_RECORD 节点，type=13）
+
+```bash
+# 从工作表获取多条记录（action-id=400）
+hap node save-get-more 流程ID 节点ID -a 400 --app-id 工作表ID \
+  --condition '[{"fieldId":"c001","conditionId":"12","value":["100"]}]' \
+  --sorts '[{"fieldId":"c002","isAsc":true}]' \
+  --limit '{"fieldValue":1000}'
+
+# 从记录的关联字段获取多条（action-id=401）
+hap node save-get-more 流程ID 节点ID -a 401 -s 来源节点ID
+
+# 批量更新多条记录（action-id=412）
+hap node save-get-more 流程ID 节点ID -a 412 --app-id 工作表ID \
+  -f '[{"fieldId":"c001","type":2,"fieldValue":"批量值"}]'
+
+# 批量删除多条记录（action-id=413）
+hap node save-get-more 流程ID 节点ID -a 413 --app-id 工作表ID
+
+# 刷新多条数据（action-id=415）
+hap node save-get-more 流程ID 节点ID -a 415 --app-id 工作表ID
+```
+
+### 测试节点
+
+```bash
+# 测试代码块
+hap node test-code 流程ID 节点ID --code "return 1 + 1"
+
+# 测试代码块（带输入参数）
+hap node test-code 流程ID 节点ID \
+  --code "return input.x * 2" \
+  --input '[{"name":"x","value":"5","type":"number"}]'
+
+# 测试 WebHook
+hap node test-webhook 流程ID 节点ID \
+  --url https://api.example.com/data \
+  --method GET
+
+# 测试 WebHook（带请求体）
+hap node test-webhook 流程ID 节点ID \
+  --url https://api.example.com/submit \
+  --method POST \
+  --body '{"key":"value"}' \
+  --headers '[{"name":"Authorization","value":"Bearer token"}]'
+
+# 测试 AI 文本生成
+hap node test-ai 流程ID 节点ID \
+  --prompt "请总结以下内容" \
+  --model gpt-4 \
+  --temperature 0.5
+```
+
+### 发布与版本
+
+```bash
+# 发布工作流（启用）
+hap workflow publish 流程ID
+
+# 停用工作流
+hap workflow publish 流程ID --disable
+
+# 查看版本历史
+hap workflow history 流程ID
+
+# 回滚到上一版本
+hap workflow rollback 流程ID --yes
+```
+
+### 流程配置
+
+```bash
+# 获取全局配置
+hap workflow config-get 流程ID
+
+# 修改全局配置
+hap workflow config-set 流程ID \
+  --config '{"allowRevoke":true,"allowUrge":true,"errorInterval":5}'
+```
+
+### 触发流程
+
+```bash
+# 按流程 ID 手动触发
+hap workflow trigger 流程ID --source-id 记录ID
+
+# 触发 PBP 流程
+hap workflow trigger-pbp 流程ID --app-id 应用ID
+
+# 查看流程分组
+hap workflow groups 应用ID
+
+# 查看使用统计
+hap workflow stats --company-id 组织ID
+```
+
+## 审批与待办
+
+```bash
+# 查看待处理数量
+hap instance todo-count
+
+# 查看待审批列表
+hap instance todo --type 4
+
+# 查看待填写列表
+hap instance todo --type 3
+
+# 查看我发起的
+hap instance todo --type 0
+
+# 查看实例详情
+hap instance get 实例ID
+
+# 查看可用操作
+hap instance operations 实例ID
+
+# 通过审批
+hap instance approve 实例ID --opinion "同意"
+
+# 否决审批
+hap instance reject 实例ID --opinion "信息不完整，请补充"
+
+# 否决并退回到指定节点
+hap instance reject 实例ID --opinion "请修改" --back-to 节点ID
+
+# 转审给其他人
+hap instance forward 实例ID --to 用户ID --opinion "请协助审批"
+
+# 加签（在当前审批人之前）
+hap instance sign 实例ID --to 用户ID --before
+
+# 加签（在当前审批人之后）
+hap instance sign 实例ID --to 用户ID --after
+
+# 提交填写任务
+hap instance submit 实例ID
+
+# 撤回（发起人撤回）
+hap instance revoke 实例ID
+
+# 催办
+hap instance urge 实例ID
+
+# 批量通过
+hap instance batch --action 4 -s 实例ID1 -s 实例ID2
+
+# 批量否决
+hap instance batch --action 5 -s 实例ID1 -s 实例ID2
+
+# 终止运行中的实例
+hap instance terminate 实例ID --yes
+
+# 重试失败的实例
+hap instance retry 实例ID
+
+# 重新发起
+hap instance restart 实例ID
+
+# 查看执行历史
+hap instance history --process-id 流程ID
+
+# 按状态筛选（1=运行中 2=完成 3=否决 4=失败）
+hap instance history --status 2
+
+# 查看执行历史详情
+hap instance history-detail 实例ID
+
+# 查看操作记录
+hap instance op-history 实例ID
+```
+
+## 数据记录操作
+
+```bash
+# 查询记录（支持分页、搜索、排序）
+hap record list 工作表ID --page-size 50 --keywords "关键词"
+
+# 获取单条记录
+hap record get 工作表ID 记录ID
+
+# 新建记录
+hap record create 工作表ID \
+  -f "字段ID1=值1" \
+  -f "字段ID2=值2"
+
+# 更新记录
+hap record update 工作表ID 记录ID \
+  -f "字段ID=新值"
+
+# 删除记录
+hap record delete 工作表ID 记录ID1 记录ID2 --yes
+```
+
+## 应用与工作表
+
+```bash
+# 列出组织下的应用
+hap app list --project-id 组织ID
+
+# 搜索应用
+hap app list --project-id 组织ID --keyword "人事"
+
+# 查看应用详情
+hap app info 应用ID
+
+# 列出工作表
+hap app worksheets 应用ID
+
+# 查看工作表信息
+hap worksheet info 工作表ID
+
+# 查看字段列表（获取字段ID用于记录操作）
+hap worksheet fields 工作表ID
+
+# 查看视图列表
+hap worksheet views 工作表ID
+```
+
+## 角色管理
+
+```bash
+# 列出应用角色
+hap role list 应用ID
+
+# 创建角色（权限: 0=自定义 10=只读 50=成员 100=管理员）
+hap role create 应用ID --name "审核员" --permission 10
+
+# 添加成员
+hap role add-member 应用ID 角色ID -u 用户ID1 -u 用户ID2
+
+# 添加部门
+hap role add-member 应用ID 角色ID -d 部门ID
+
+# 移除成员
+hap role remove-member 应用ID 角色ID -u 用户ID
+
+# 删除角色（并将成员移至其他角色）
+hap role delete 应用ID 角色ID --move-to 目标角色ID --yes
+```
+
+## 交互模式 (REPL)
+
+```bash
+hap repl
+hap> record list 工作表ID
+hap> --json workflow list 应用ID
+hap> instance todo-count
+hap> node list 流程ID
+hap> quit
+```
+
+## 节点类型参考
+
+> 运行 `hap node types` 可查看完整列表
+
+| 类型值 | 名称 | 说明 |
+|--------|------|------|
+| 0 | 开始 (START) | 流程起始节点 |
+| 1 | 分支 (BRANCH) | 条件分支/网关 |
+| 2 | 分支项 (BRANCH_ITEM) | 分支条件项 |
+| 3 | 填写 (FILL) | 表单填写任务 |
+| 4 | 审批 (APPROVAL) | 审批任务 |
+| 5 | 抄送 (CC) | 抄送通知 |
+| **6** | **数据处理 (ACTION)** | **新增/编辑/删除记录** |
+| **7** | **查询单条 (SEARCH)** | **获取单条记录** |
+| 8 | WebHook | HTTP 请求 |
+| 9 | 公式 (FORMULA) | 运算/公式计算 |
+| 10 | 短信 (MESSAGE) | 短信通知 |
+| 11 | 邮件 (EMAIL) | 邮件通知 |
+| 12 | 延迟 (DELAY) | 定时延迟 |
+| **13** | **获取多条 (GET_MORE_RECORD)** | **获取多条记录/批量操作** |
+| 14 | 代码块 (CODE) | JavaScript/Python 执行 |
+| 15 | 获取链接 (LINK) | 获取记录链接 |
+| 16 | 子流程 (SUB_PROCESS) | 调用子流程 |
+| 17 | 界面推送 (PUSH) | 界面推送通知 |
+| 18 | 文件 (FILE) | 打印/PDF 生成 |
+| 19 | 模板 (TEMPLATE) | 模板消息 |
+| 20 | 业务流程 (PBP) | 封装业务流程 |
+| 21 | JSON 解析 (JSON_PARSE) | JSON 数据解析 |
+| 22 | 认证 (AUTHENTICATION) | API 认证 |
+| 25 | API 调用 (API) | 已集成 API 调用 |
+| 26 | 发起审批 (APPROVAL_PROCESS) | 发起审批流程 |
+| 27 | 通知 (NOTICE) | 站内通知 |
+| 28 | 快照 (SNAPSHOT) | 数据快照 |
+| 29 | 循环 (LOOP) | 循环处理 |
+| 31 | AI (AIGC) | AI 文本/对象生成 |
+| 32 | 插件 (PLUGIN) | 插件调用 |
+| 33 | Agent | AI Agent |
+
+## Action ID 参考（数据处理节点）
+
+| Action ID | 节点类型 | 操作 | 说明 |
+|-----------|---------|------|------|
+| 1 | 6 (ACTION) | 新增记录 | 在指定工作表中新增一条记录 |
+| 2 | 6 (ACTION) | 编辑记录 | 更新工作表中的记录字段 |
+| 3 | 6 (ACTION) | 删除记录 | 删除指定记录 |
+| 5 | 6 (ACTION) | 创建记录 | 创建记录 |
+| 6 | 6 (ACTION) | 校准单条 | 刷新/更新单条记录字段 |
+| 20 | 6 (ACTION) | 关联记录 | 获取关联他表字段 |
+| 406 | 7 (SEARCH) | 从工作表查询 | 查询一条符合条件的记录 |
+| 407 | 7 (SEARCH) | 从多条中取一条 | 从多条数据节点中取一条 |
+| 420 | 7 (SEARCH) | 记录链接查询 | 通过记录链接查询 |
+| 421 | 7 (SEARCH) | 查询并更新 | 查询到记录后进行更新 |
+| 422 | 7 (SEARCH) | 查询并删除 | 查询到记录后进行删除 |
+| 400 | 13 (GET_MORE) | 从工作表获取 | 查询多条符合条件的记录 |
+| 401 | 13 (GET_MORE) | 从关联获取 | 从记录关联字段获取多条 |
+| 402 | 13 (GET_MORE) | 从新增节点获取 | 从新增记录节点获取多条 |
+| 412 | 13 (GET_MORE) | 批量更新 | 批量修改多条记录 |
+| 413 | 13 (GET_MORE) | 批量删除 | 批量删除多条记录 |
+| 415 | 13 (GET_MORE) | 校准多条 | 刷新/更新多条记录字段 |
+
+## 实例状态参考
+
+| 状态值 | 含义 |
+|--------|------|
+| 1 | 运行中 |
+| 2 | 已完成 |
+| 3 | 已否决 |
+| 4 | 已失败/已终止 |
+
+## 待办类型参考
+
+| 类型值 | 含义 |
+|--------|------|
+| -1 | 全部待处理 |
+| 0 | 我发起的 |
+| 3 | 待填写 |
+| 4 | 待审批 |
+| 5 | 待查看 |
+
+## 完整工作流示例：从创建到审批
+
+```bash
+# 第一步：创建工作流
+hap --json workflow create \
+  --company-id 组织ID --name "报销审批" --app-id 应用ID
+# 返回 processId
+
+# 第二步：查看初始节点
+hap --json node list 流程ID
+
+# 第三步：添加审批节点
+hap --json node add 流程ID --type 4 --name "部门主管审批" --after 起始节点ID
+# 返回 nodeId
+
+# 第四步：配置审批节点（指定审批人）
+hap node save 流程ID 节点ID --type 4 \
+  --config '{"accounts":[{"accountId":"主管用户ID"}]}'
+
+# 第五步：发布工作流
+hap workflow publish 流程ID
+
+# 第六步：触发工作流
+hap --json workflow trigger 流程ID --source-id 记录ID
+
+# 第七步：查看待审批
+hap --json instance todo --type 4
+
+# 第八步：审批通过
+hap instance approve 实例ID --opinion "费用合理，同意报销"
+
+# 查看执行结果
+hap --json instance history-detail 实例ID
+```
+
+## 认证说明
+
+本工具使用明道云的 `md_pss_id` 会话令牌进行认证。获取方式：
+
+1. 在浏览器中登录明道云
+2. 打开开发者工具 (F12)
+3. 在 Application > Cookies 中找到 `md_pss_id`
+4. 复制其值作为 `--token` 参数

hap_cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI harness for MingDAO HAP (hap-cli)."""
+
+__version__ = "0.3.0"

hap_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for hap-cli."""