@josephyan/qingflow-cli 1.1.11 → 1.1.13

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.1.11
+npm install @josephyan/qingflow-cli@1.1.13
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.1.11 qingflow
+npx -y -p @josephyan/qingflow-cli@1.1.13 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.11"
+version = "1.1.13"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/reference/builder/70-portal.md

@@ -18,6 +18,7 @@ portal list/get if updating -> verify apps/views/charts -> portal apply -> porta
 
 - Use `--dash-key` for updates and do not send `package_id`.
 - Use `patch_sections[]` for targeted section changes when possible.
+- `patch_sections[]` selectors may use `order`, `chart_ref.chart_id`, `chart_ref.chart_key`, or `view_ref.view_key`; chart sections read back from portal often only include `chart_id`, so patching by `chart_id` is valid and does not require `app_key`.
 - If using a business-entry grid, include real `items`; do not submit an empty entry container.
 - Validate referenced `chart_key`, `chart_id`, `view_key`, or `app_key` before claiming the portal is complete.
 

package/skills/qingflow-cli/reference/builder/90-workflow.md

@@ -16,11 +16,13 @@ contract -> app get fields -> app get flow -> member/role lookup -> flow apply -
 
 ## Recommended write path
 
+- For normal agent-authored workflows, use the public path: `--nodes-file` + `--transitions-file`.
+- `--spec-file` is an advanced raw backend WorkflowSpec path. Do not put public node aliases such as `start` / `approve` / `end` into `--spec-file`.
 - Start from a preset when possible: `basic_approval` or `basic_fill_then_approve`.
 - Patch preset node ids instead of adding duplicate nodes:
   - `basic_approval` -> `approve_1`
   - `basic_fill_then_approve` -> `fill_1`, `approve_1`
-- Use `patch_nodes[]` for targeted updates to an existing flow.
+- Use `patch_nodes[]` for targeted updates to an existing flow. Node ids come from `builder flow get` readback, not from the original public `nodes-file` ids after the backend has assigned workflow node ids.
 - Do not mix `patch_nodes` and full `spec` in the same call.
 
 ## Supported public node types

package/skills/qingflow-cli/reference/builder/workflow/01-overview.md

@@ -19,7 +19,9 @@
 |------|------|
 | `qingflow builder flow schema --json` | 获取最新 WorkflowSpecDTO JSON Schema |
 | `qingflow builder flow get --app-key <KEY>` | 读取当前工作流 spec |
-| `qingflow builder flow apply --app-key <KEY> --spec-file <FILE>` | 部署/更新工作流 |
+| `qingflow --json builder flow apply --app-key <KEY> --nodes-file <NODES> --transitions-file <TRANSITIONS>` | 主链路：部署/更新 public 工作流 |
+| `qingflow --json builder flow apply --app-key <KEY> --patch-nodes-file <PATCH>` | 局部修改现有节点 |
+| `qingflow --json builder flow apply --app-key <KEY> --spec-file <FILE>` | 高级链路：部署 raw backend WorkflowSpec，不用于 public node aliases |
 | `qingflow builder member search --query <关键词>` | 搜索成员 |
 | `qingflow builder role search --keyword <关键词>` | 搜索角色 |
 | `qingflow --json app get --app-key <KEY>` | 获取应用信息（字段列表等） |
@@ -33,7 +35,7 @@
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| public nodes/transitions 生成与 apply | 操作复杂命令拼接 |
 | 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |

package/skills/qingflow-cli/reference/builder/workflow/02-update-mode.md

@@ -19,9 +19,19 @@
 | 修改条件 | 同一条边内改 condition | 删除边再新建 |
 | 调整流转 | 修改边的 from/to | 改节点 ID 来适配 |
 
-## 使用 diff 脚本辅助判断
+## 使用 patch_nodes 优先
 
-在构建新 spec 后、apply 前，使用 diff 脚本对比新旧 spec：
+如果只是改节点名称、负责人、局部 attrs，优先使用 `patch_nodes[]`，节点 id 从 `builder flow get` 的 `spec.nodes[]` 读取：
+
+```json
+[
+  {"id": "89160906", "set": {"name": "需求评审（局部改）"}}
+]
+```
+
+## raw spec 更新时使用 diff 脚本辅助判断
+
+只有在需要提交 raw backend `--spec-file` 时，才在 apply 前使用 diff 脚本对比新旧 spec：
 
 ```bash
 python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
@@ -29,7 +39,7 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 
 输出会显示删除的节点/边、新增的节点/边、修改的节点/边，并自动评估是否符合最小修改原则。
 
-验证脚本也支持在更新模式下进行最小修改原则校验：
+验证脚本也支持在 raw spec 更新模式下进行最小修改原则校验：
 
 ```bash
 python3 scripts/validate_flow_spec.py \

package/skills/qingflow-cli/reference/builder/workflow/06-stage3-build-spec.md

@@ -1,4 +1,4 @@
-# 阶段 3：获取 Schema + 构建 Spec
+# 阶段 3：获取 Schema + 构建流程输入
 
 ## 3.1 获取当前工作流 Schema
 
@@ -16,7 +16,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/current_flow.json
 
 从返回的 `spec` 中提取 `nodes` 和 `edges` 作为修改基础。
 
-**更新模式下**：构建新 spec 后，用 diff 脚本确认变更范围是否符合预期：
+**更新模式下**：如果走 `patch_nodes[]`，直接使用读回的 `spec.nodes[].id` 做局部修改；如果确实需要 raw backend `--spec-file`，再用 diff 脚本确认变更范围是否符合预期：
 
 ```bash
 python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
@@ -24,9 +24,45 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 
 新建场景可跳过此步。
 
-## 3.3 构建 WorkflowSpec
+## 3.3 推荐：构建 public nodes / transitions
 
-按照以下结构构建 `spec.json`：
+智能体主链路不要直接手写 raw backend `WorkflowSpec`。推荐写两个数组文件：
+
+`tmp/flow_nodes.json`
+
+```json
+[
+  {"id": "start", "type": "start", "name": "提交申请"},
+  {"id": "approve_1", "type": "approve", "name": "部门经理审批", "role_names": ["部门经理"]},
+  {"id": "end", "type": "end", "name": "结束"}
+]
+```
+
+`tmp/flow_transitions.json`
+
+```json
+[
+  {"from": "start", "to": "approve_1"},
+  {"from": "approve_1", "to": "end"}
+]
+```
+
+提交时使用：
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --nodes-file tmp/flow_nodes.json \
+  --transitions-file tmp/flow_transitions.json \
+  --publish \
+  > tmp/flow_apply.json
+```
+
+## 3.4 高级：raw backend WorkflowSpec
+
+`--spec-file` 只用于已经从 `builder flow get` 读回并理解的 raw backend spec。不要把 `start` / `approve` / `fill` / `end` 这类 public node alias 放进 `--spec-file`。
+
+raw backend spec 示例：
 
 ```json
 {
@@ -116,7 +152,7 @@ python3 scripts/diff_flow_spec.py tmp/current_flow.json tmp/flow_spec.json
 }
 ```
 
-## 节点类型速查
+## raw backend 节点类型速查
 
 | type | 说明 | 必要 attrs |
 |------|------|-----------|
@@ -154,9 +190,23 @@ OR-of-AND 二维数组：
 
 **judgeType 常用值**：`equals`, `not_equals`, `equals_any`, `includes`, `greater_than` 等（共21种，详见 schema）。
 
-## 3.4 保存 Spec 到文件
+## 3.5 局部修改 patch_nodes
+
+局部修改现有流程时，先 `builder flow get`，使用读回 `spec.nodes[].id`：
 
-将构建好的完整 Spec 以 JSON 格式保存到文件 `tmp/flow_spec.json`，确保使用 UTF-8 编码、缩进格式化，以便后续验证和 apply 使用。
+```json
+[
+  {"id": "89160906", "set": {"name": "需求评审（局部改）"}}
+]
+```
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
+```
 
 ---
 

package/skills/qingflow-cli/reference/builder/workflow/07-stage4-validate-spec.md

@@ -1,13 +1,20 @@
-# 阶段 4：验证 Spec
+# 阶段 4：验证流程输入
 
-使用本 Skill 自带的验证脚本：
+主链路 `--nodes-file + --transitions-file` 由 CLI 模型校验 public node type、边引用和角色/成员解析。提交前至少检查：
+
+- `nodes[].id` 唯一；
+- `transitions[].from/to` 都能在 nodes 中找到；
+- 节点类型只用 `start`、`approve`、`fill`、`copy`、`webhook`、`end`；
+- 审批/填写节点有明确 `member_names`、`member_ids`、`role_names` 或 `role_ids`。
+
+只有 raw backend `--spec-file` 才使用本 Skill 自带的 WorkflowSpec 验证脚本：
 
 ```bash
-# 新建模式
+# raw spec 新建模式
 python3 scripts/validate_flow_spec.py \
   tmp/flow_spec.json --schema tmp/flow_schema.json
 
-# 更新模式（同时校验最小修改原则）
+# raw spec 更新模式（同时校验最小修改原则）
 python3 scripts/validate_flow_spec.py \
   tmp/flow_spec.json --schema tmp/flow_schema.json --previous tmp/current_flow.json
 ```
@@ -24,7 +31,7 @@ python3 scripts/validate_flow_spec.py \
 
 ## 验证不通过时的处理
 
-根据错误信息修正 spec，重新验证，直到全部通过再进入 apply。
+public 输入根据 CLI 错误修正 nodes/transitions；raw spec 根据验证脚本错误修正 spec，重新验证，直到全部通过再进入 apply。
 
 ---
 

package/skills/qingflow-cli/reference/builder/workflow/08-stage5-apply-verify.md

@@ -2,11 +2,27 @@
 
 ## 5.1 部署工作流
 
+推荐主链路：
+
+```bash
+qingflow --json builder flow apply \
+  --app-key <APP_KEY> \
+  --nodes-file tmp/flow_nodes.json \
+  --transitions-file tmp/flow_transitions.json \
+  --publish \
+  > tmp/flow_apply.json
+```
+
+`--spec-file` 只用于 raw backend WorkflowSpec；普通智能体生成的 `start` / `approve` / `end` public nodes 必须走 `--nodes-file + --transitions-file`。
+
+局部修改已存在节点：
+
 ```bash
-qingflow builder flow apply \
+qingflow --json builder flow apply \
   --app-key <APP_KEY> \
-  --spec-file tmp/flow_spec.json \
-  --publish
+  --patch-nodes-file tmp/flow_patch_nodes.json \
+  --publish \
+  > tmp/flow_patch_apply.json
 ```
 
 ### 解读响应
@@ -14,6 +30,7 @@ qingflow builder flow apply \
 - `status: success` → 进入验证
 - `status: failed` → 查看 `error_code` / `message` / `blocking_issues`，修正后重试
 - `missing_input_node_ids` 警告（新建时常见）→ 可忽略，是正常现象
+- 成功写入应读取 `write_executed=true`、`write_succeeded=true`、`safe_to_retry=false`；不要因中间读回 pending 立刻重放。
 
 ## 5.2 验证部署结果
 
@@ -37,7 +54,7 @@ qingflow --json builder flow get --app-key <APP_KEY> > tmp/deployed_flow.json
 
 若验证发现不一致：
 1. 分析差异原因（条件格式错误、节点缺失、边遗漏等）
-2. 修正 `tmp/flow_spec.json`
+2. 修正 `tmp/flow_nodes.json` / `tmp/flow_transitions.json`；raw spec 高级路径才修正 `tmp/flow_spec.json`
 3. 重新验证 → apply → 对比
 4. **最多循环 3 次**；若 3 次后仍有不可修复的差异，告知用户并列出：
    - 已成功配置的部分

package/skills/qingflow-cli/reference/builder/workflow/README.md

@@ -48,7 +48,7 @@
 | 在范围内 | 超出范围 |
 |----------|----------|
 | 基于已有应用搭建工作流 | 从零创建应用 |
-| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| public nodes/transitions 生成与 apply；必要时 raw WorkflowSpec | 操作复杂命令拼接 |
 | 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
 | 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
 | 成员/角色搜索用于节点负责人 | 组织架构管理 |

package/src/qingflow_mcp/builder_facade/models.py

@@ -2137,7 +2137,7 @@ class PortalComponentPositionPatch(StrictModel):
 
 
 class PortalChartRefPatch(StrictModel):
-    app_key: str
+    app_key: str | None = None
     chart_id: str | None = None
     chart_name: str | None = None
 
@@ -2145,6 +2145,8 @@ class PortalChartRefPatch(StrictModel):
     def validate_target(self) -> "PortalChartRefPatch":
         if not (self.chart_id or self.chart_name):
             raise ValueError("chart_ref requires chart_id or chart_name")
+        if self.chart_name and not self.chart_id and not self.app_key:
+            raise ValueError("chart_ref.app_key is required when resolving by chart_name")
         return self
 
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -486,6 +486,9 @@ class AiBuilderFacade:
             "verified": verified,
             "app_key": app_key,
             "current_version_id": apply_result.get("currentVersionId"),
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -17345,6 +17348,8 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
     app_key = str(getattr(ref, "app_key", "") or "").strip()
     chart_id = str(getattr(ref, "chart_id", "") or "").strip()
     chart_name = str(getattr(ref, "chart_name", "") or "").strip()
+    if chart_id and not app_key:
+        return {"chart_id": chart_id, "chart_name": chart_name, "app_key": None, "chart_type": ""}
     items = charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
     if chart_id:
         for item in items: