@josephyan/qingflow-cli 1.1.4 → 1.1.6

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md → task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md}

@@ -2,7 +2,7 @@
 
 本文与 **MCP / 服务端公开工具命名**对齐，并给出已安装的 `**qingflow` CLI** 等价命令。编写前已在当前环境对 `**task list` / `task get` / `task log`** 实跑；`**task report`** 在抽样任务上遇到过后端 `**40038` Object not exist**（见文末「实测排障」），属数据/权限/报表生命周期问题，**不否定**标准编排顺序。
 
-**必须落盘**：`task` 的 `list`、`get`、`log`、`report` 以及 `**task action` 的响应**若体积大，均应 `> tmp/qingflow_*.json`，与主技能 [SKILL.md](../SKILL.md) 一致。
+**必须落盘**：`task` 的 `list`、`get`、`log`、`report` 以及 `**task action` 的响应**若体积大，均应 `> tmp/qingflow_*.json`，与主技能 [SKILL.md](../../SKILL.md) 一致。
 
 ---
 
@@ -106,7 +106,7 @@ qingflow --json task action \
   > tmp/qingflow_task_action.json
 ```
 
-`**--action` 允许字面量**（实现校验，大小写不敏感）：  
+`**--action` 允许字面量**（实现校验，大小写不敏感）：
 `approve`、`reject`、`rollback`、`transfer`、`urge`、`save_only`。
 
 **约束摘要**（与实现一致）：
@@ -126,7 +126,7 @@ qingflow --json task action \
 ## 4. 与「应用内 `record list`」的边界
 
 - **任务中心待办 / 已办 / 抄送**：用 `**task list --task-box …`**，**不要**再用过时的 `record list --view-id system:todo` 等当作任务箱。
-- **业务表读数**：仍在 `app get` 的 `**accessible_views`** 里选 `**custom:`* 等**，走 [QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
+- **业务表读数**：仍在 `app get` 的 `**accessible_views`** 里选 `**custom:`* 等**，走 [QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
 
 ---
 
@@ -147,5 +147,5 @@ qingflow --json task action \
 
 ## 6. 交叉引用
 
-- 主技能 [SKILL.md](../SKILL.md)：**落盘规则**、`**task-box` / `flow-status`** 枚举、与 `record` 混用雷区。
-- [QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)：成员侧最短路径。
+- 主技能 [SKILL.md](../../SKILL.md)：**落盘规则**、`**task-box` / `flow-status`** 枚举、与 `record` 混用雷区。
+- [QINGFLOW_CLI_MEMBER_CHEATSHEET.md](../core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)：成员侧最短路径。

package/skills/qingflow-cli/reference/task/ops/README.md

@@ -0,0 +1,131 @@
+# Qingflow CLI Task Ops
+
+## Overview
+
+This section is for task workflow operations only. Do not use it for record CRUD or final statistical analysis.
+
+## Default Paths
+
+Use exactly one of these default paths:
+
+1. Find target todos
+   `qingflow task list`
+
+2. Read one task context
+   `task list -> exact target -> task get`
+
+3. Read associated approval context
+   `task get -> task report` or `task log`
+
+4. Execute workflow action
+   `task list -> exact target -> task get -> task action`
+
+5. Execute a user-specified action on an already-clear target
+   `task list -> exact target -> (optional task get) -> task action`
+
+## Core Tools
+
+- `qingflow task list`
+- `qingflow task get`
+- `qingflow task action`
+- `qingflow task report`
+- `qingflow task log`
+
+## Supporting Tools
+
+- `app_list`
+- `app_search`
+
+## Standard Operating Order
+
+Use one of these two modes:
+
+1. Recommendation mode
+   1. Discover the exact target with `task list`
+   2. Read node context with `task get`
+   3. Before giving any approval recommendation, read `task log`
+   4. If `task get` returns any `associated_reports`, read every visible report through `task report`
+   5. Give a recommendation only after reviewing node context, workflow log, and associated reports
+   6. Wait for explicit user confirmation before `task action`
+
+2. User-directed execution mode
+   1. Discover the exact target with `task list`
+   2. If the target or action requirements are ambiguous, read `task get`; otherwise go straight to `task action`
+   3. Execute through `task action --task-id ...`
+   4. After actions, report the exact `task_id`, executed action, and any returned `app_key / record_id` plus warnings
+
+## Task-Center Rules
+
+- Use `task list` for flat browsing
+- `task_box` must be one of:
+  - `todo`
+  - `initiated`
+  - `cc`
+  - `done`
+- `flow_status` must be one of:
+  - `all`
+  - `in_progress`
+  - `approved`
+  - `rejected`
+  - `pending_fix`
+  - `urged`
+  - `overdue`
+  - `due_soon`
+  - `unread`
+  - `ended`
+- `task list` is the only public task discovery path
+- `task list --query` uses backend `searchKey` first; only when backend returns zero rows does CLI apply a local fallback match on normalized `app_name / workflow_node_name / app_key / record_id`
+- Treat `task_id` from `task list.data.items[]` as the public action locator. Do not reconstruct action identity from `app_key + record_id + workflow_node_id`.
+- Default box usage:
+  - `todo`: `task list -> task get -> task log / task report -> recommendation -> explicit user confirmation -> task action`
+  - `initiated`: `task list -> record get`
+  - `done`: `task list -> record get`
+  - `cc`: `task list -> record get`
+- Treat `initiated`, `done`, and `cc` primarily as list-plus-record-detail flows, not task action flows
+
+## Workflow Usage Actions
+
+- `task get.capabilities.available_actions` is the source of truth for executable actions
+- Current public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- Before any approve/reject/rollback/transfer recommendation, always review `task log` when `task get.visibility.audit_record_visible=true`
+- If `task get` returns visible `associated_reports`, review each one with `task report`; do not rely on report summary alone
+- Do not give an approval recommendation based only on `task get`
+- Do not execute `task action` until the user explicitly confirms the chosen action
+- Exception: if the user has already explicitly authorized a concrete action on exact targets, you may execute directly after exact target resolution
+- Avoid actions on ambiguous tasks or records
+- Summarize the final action and the exact `task_id`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields` and is only available when the backend exposes editable fields for the current node
+- `task action` distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
+- If `task action` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
+- If `task action` returns `TASK_CONTEXT_VISIBILITY_UNVERIFIED` after a `46001`-style context loss, do not claim the task was already processed unless the workflow log or record state proves it.
+- If `task_action_execute` returns `TASK_RUNTIME_CONSUMED_AFTER_ACTION`, treat that as a normal post-success state: the current node runtime was consumed, the workflow likely continued, and `46001` does not by itself mean the action failed
+
+## Feedback Escalation
+
+- If task capabilities, associated report detail, workflow log visibility, or action support still cannot satisfy the user's goal after reasonable use of this skill, summarize the exact gap in plain language.
+- Ask whether the user wants you to submit product feedback.
+- Only after explicit user confirmation, call `feedback_submit`.
+
+## Response Interpretation
+
+- `task_list` returns normalized todo rows and is the only default discovery path
+- `task_list` may return `TASK_LIST_QUERY_FALLBACK_APPLIED`; this means backend search missed the query and MCP recovered the result through local exact-field fallback
+- `task_get` returns node context summary, not full historical report data
+- `task_associated_report_detail_get` may return either:
+  - `result_type=view_list`
+  - `result_type=chart_data`
+- `task_workflow_log_get` returns workflow log detail only when the node grants log visibility
+- A successful approve/reject/rollback/transfer may still lose the current-node runtime immediately; treat `record_state_readable=false + backend 46001` as a post-action runtime loss unless continuation verification says otherwise
+- Treat `request_route` as the source of truth for live route debugging
+- If only part of the requested work is completed, explicitly disclose which parts are done and which are not
+
+## Resources
+
+- Workflow and task usage actions: [references/workflow-usage.md](./workflow-usage.md)

package/skills/qingflow-cli/reference/task/ops/environments.md

@@ -0,0 +1,43 @@
+# Environment Switching
+
+Use this reference before any workflow usage action, comment, or task-center operation that might affect live work.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational tasks, comments, and workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- workflow walkthroughs
+- user acceptance demos
+- comment or transfer rehearsals
+
+## Production Environment
+
+Use production for:
+
+- live task-center operations
+- live comments on real business records
+- approve / reject / rollback / transfer / urge on real work
+
+Production guardrails:
+
+- never assume a task id, record id, or workflow node id
+- find the exact target first
+- if the task can be answered read-only, do not act
+
+## Reporting Rule
+
+For task ops, always report:
+
+- active environment
+- target app or task box
+- operation type: read, comment, approve, reject, rollback, transfer, urge, or mark_read
+- affected task ids or record ids

package/skills/qingflow-cli/reference/task/ops/workflow-usage.md

@@ -0,0 +1,26 @@
+# Workflow and Task Usage Actions
+
+Use these when the user is operating inside an existing process, not redesigning it.
+
+Examples:
+
+- add a comment to a record
+- approve or reject a workflow task
+- transfer a task
+- roll back a task
+- list todo, initiated, done, or cc tasks
+- inspect workload by worksheet or workflow node
+- urge a pending task
+
+Rules:
+
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
+- use `task_summary` for headline counts
+- use `task_list` for flat browsing
+- use `task_facets` when worksheet or workflow-node buckets matter
+- treat task counts as task-center counts, not record counts
+- switch to `record_get` only after locating the exact business record behind a task
+- identify the exact target first
+- for approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
+- avoid usage-side workflow actions on ambiguous records
+- summarize the final action and target task ids or record ids

package/skills/qingflow-cli/scripts/validate_system_build_summary.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VALID_PORTAL_STATUSES = {"verified", "unverified", "not_created"}
+VALID_APP_VERIFY_STATUSES = {"verified", "unverified", "failed"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a Qingflow complete-system delivery summary JSON file.")
+    parser.add_argument("summary_file", nargs="?", default="tmp/qingflow_system_build_summary.json")
+    args = parser.parse_args(argv)
+    path = Path(args.summary_file)
+    issues = validate_summary_file(path)
+    if issues:
+        _emit({"status": "failed", "error_code": "SYSTEM_BUILD_SUMMARY_INVALID", "path": str(path), "issues": issues})
+        return 1
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    _emit(
+        {
+            "status": "success",
+            "path": str(path),
+            "summary": {
+                "package_id": payload.get("package_id"),
+                "package_name": payload.get("package_name"),
+                "portal_dash_key": payload.get("portal_dash_key"),
+                "portal_live_status": payload.get("portal_live_status"),
+                "app_count": len(payload.get("apps") or []),
+                "partial_count": len(payload.get("partial_items") or []),
+                "needs_followup_count": len(payload.get("needs_followup") or []),
+            },
+        }
+    )
+    return 0
+
+
+def validate_summary_file(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return [_issue("MISSING_FILE", "$", f"summary file does not exist: {path}")]
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        return [_issue("READ_FAILED", "$", str(exc))]
+    except json.JSONDecodeError as exc:
+        return [_issue("INVALID_JSON", "$", exc.msg)]
+    if not isinstance(payload, dict):
+        return [_issue("INVALID_ROOT", "$", "summary root must be a JSON object")]
+
+    issues: list[dict[str, Any]] = []
+    _require_positive_int(payload, "package_id", issues)
+    _require_nonempty_string(payload, "package_name", issues)
+    _require_bool(payload, "front_end_visible", issues)
+    _require_string_enum(payload, "portal_live_status", VALID_PORTAL_STATUSES, issues)
+    if payload.get("portal_live_status") == "verified":
+        _require_nonempty_string(payload, "portal_dash_key", issues)
+    elif "portal_dash_key" in payload and payload.get("portal_dash_key") is not None and not isinstance(payload.get("portal_dash_key"), str):
+        issues.append(_issue("INVALID_TYPE", "$.portal_dash_key", "portal_dash_key must be a string when present"))
+
+    apps = payload.get("apps")
+    if not isinstance(apps, list) or not apps:
+        issues.append(_issue("INVALID_APPS", "$.apps", "apps must be a non-empty array"))
+    else:
+        for index, app in enumerate(apps):
+            prefix = f"$.apps[{index}]"
+            if not isinstance(app, dict):
+                issues.append(_issue("INVALID_APP_ITEM", prefix, "app item must be an object"))
+                continue
+            _require_nonempty_string(app, "app_key", issues, prefix)
+            _require_nonempty_string(app, "app_name", issues, prefix)
+            for key in ("fields_count", "views_count", "flows_count", "charts_count"):
+                _require_nonnegative_int(app, key, issues, prefix)
+            _require_string_enum(app, "publish_verify_status", VALID_APP_VERIFY_STATUSES, issues, prefix)
+
+    for key in ("warnings", "partial_items", "needs_followup"):
+        if not isinstance(payload.get(key), list):
+            issues.append(_issue("INVALID_TYPE", f"$.{key}", f"{key} must be an array"))
+    return issues
+
+
+def _require_positive_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a positive integer"))
+
+
+def _require_nonnegative_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-negative integer"))
+
+
+def _require_nonempty_string(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-empty string"))
+
+
+def _require_bool(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    if not isinstance(payload.get(key), bool):
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a boolean"))
+
+
+def _require_string_enum(payload: dict[str, Any], key: str, allowed: set[str], issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if value not in allowed:
+        issues.append(_issue("INVALID_VALUE", f"{prefix}.{key}", f"{key} must be one of {sorted(allowed)}"))
+
+
+def _issue(code: str, path: str, message: str) -> dict[str, Any]:
+    return {"code": code, "path": path, "message": message}
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/qingflow-cli/scripts/workflow/diff_flow_spec.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""
+对比两个工作流 spec 的差异，输出新增/删除/修改的节点和边。
+用于更新模式下辅助 agent 判断是否遵循最小修改原则。
+
+用法:
+  python3 diff_flow_spec.py <old_spec.json> <new_spec.json>
+  python3 diff_flow_spec.py <old_spec.json> <new_spec.json> --json   # JSON 输出
+"""
+
+import json
+import sys
+
+
+def load_json(path):
+    with open(path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def extract_edges(spec):
+    """从 spec 中提取边列表，兼容 edges 在不同层级的情况"""
+    e = spec.get('edges', [])
+    if isinstance(e, dict) and 'edges' in e:
+        return e['edges']
+    if isinstance(e, list):
+        return e
+    return []
+
+
+def node_key(n):
+    """节点的唯一标识"""
+    return n.get('id', '')
+
+
+def edge_key(e):
+    """边的唯一标识：from→to"""
+    return (e.get('from', ''), e.get('to', ''))
+
+
+def node_identity(n):
+    """节点的完整内容（不含 id，用于判断是否修改）"""
+    return {
+        'type': n.get('type', ''),
+        'name': n.get('name', ''),
+        'attrs': n.get('attrs', {}),
+    }
+
+
+def edge_identity(e):
+    """边的完整内容（不含 from/to，用于判断是否修改）"""
+    return {
+        'label': e.get('label', ''),
+        'condition': e.get('condition', {}),
+    }
+
+
+def diff_nodes(old_nodes, new_nodes):
+    """对比节点差异"""
+    old_by_id = {node_key(n): n for n in old_nodes}
+    new_by_id = {node_key(n): n for n in new_nodes}
+
+    old_ids = set(old_by_id.keys())
+    new_ids = set(new_by_id.keys())
+
+    deleted_ids = sorted(old_ids - new_ids)
+    added_ids = sorted(new_ids - old_ids)
+    common_ids = sorted(old_ids & new_ids)
+
+    modified = []
+    id_changes = []
+    for nid in common_ids:
+        old_ident = node_identity(old_by_id[nid])
+        new_ident = node_identity(new_by_id[nid])
+        if old_ident != new_ident:
+            modified.append({
+                'id': nid,
+                'old': {'type': old_ident['type'], 'name': old_ident['name']},
+                'new': {'type': new_ident['type'], 'name': new_ident['name']},
+                'attrs_changed': old_ident['attrs'] != new_ident['attrs'],
+                'type_changed': old_ident['type'] != new_ident['type'],
+                'name_changed': old_ident['name'] != new_ident['name'],
+            })
+
+    # 检测可能的不必要 ID 变更（内容相同但 ID 不同）
+    old_by_identity = {}
+    for n in old_nodes:
+        ident = json.dumps(node_identity(n), sort_keys=True, ensure_ascii=False)
+        old_by_identity.setdefault(ident, []).append(n)
+
+    for n in new_nodes:
+        if node_key(n) in added_ids:
+            ident = json.dumps(node_identity(n), sort_keys=True, ensure_ascii=False)
+            if ident in old_by_identity and old_by_identity[ident]:
+                old_match = old_by_identity[ident][0]
+                if node_key(old_match) in deleted_ids:
+                    id_changes.append({
+                        'old_id': node_key(old_match),
+                        'new_id': node_key(n),
+                        'identity': node_identity(n),
+                        'warning': '节点内容未变但 ID 已变更，可能导致后端不支持配置丢失',
+                    })
+
+    return {
+        'deleted': [{'id': nid, 'name': old_by_id[nid].get('name', ''), 'type': old_by_id[nid].get('type', '')} for nid in deleted_ids],
+        'added': [{'id': nid, 'name': new_by_id[nid].get('name', ''), 'type': new_by_id[nid].get('type', '')} for nid in added_ids],
+        'modified': modified,
+        'id_changes': id_changes,
+        'unchanged': len(common_ids) - len(modified),
+    }
+
+
+def diff_edges(old_edges, new_edges):
+    """对比边差异"""
+    old_by_key = {edge_key(e): e for e in old_edges}
+    new_by_key = {edge_key(e): e for e in new_edges}
+
+    old_keys = set(old_by_key.keys())
+    new_keys = set(new_by_key.keys())
+
+    deleted_keys = sorted(old_keys - new_keys)
+    added_keys = sorted(new_keys - old_keys)
+    common_keys = sorted(old_keys & new_keys)
+
+    modified = []
+    for key in common_keys:
+        old_ident = edge_identity(old_by_key[key])
+        new_ident = edge_identity(new_by_key[key])
+        if old_ident != new_ident:
+            modified.append({
+                'from': key[0],
+                'to': key[1],
+                'old_condition': old_ident['condition'],
+                'new_condition': new_ident['condition'],
+                'label_changed': old_ident['label'] != new_ident['label'],
+                'condition_changed': old_ident['condition'] != new_ident['condition'],
+            })
+
+    return {
+        'deleted': [{'from': k[0], 'to': k[1]} for k in deleted_keys],
+        'added': [{'from': k[0], 'to': k[1]} for k in added_keys],
+        'modified': modified,
+        'unchanged': len(common_keys) - len(modified),
+    }
+
+
+def print_human(result):
+    """人类可读输出"""
+    nodes = result['nodes']
+    edges = result['edges']
+
+    print("=" * 60)
+    print("工作流 Spec 差异分析")
+    print("=" * 60)
+
+    # 节点汇总
+    print(f"\n📊 节点汇总:")
+    print(f"  删除: {len(nodes['deleted'])} | 新增: {len(nodes['added'])} | "
+          f"修改: {len(nodes['modified'])} | 未变: {nodes['unchanged']}")
+
+    if nodes['id_changes']:
+        print(f"\n⚠️  检测到 {len(nodes['id_changes'])} 个可能的 ID 变更（内容相同但 ID 不同）:")
+        for ic in nodes['id_changes']:
+            print(f"  {ic['old_id']} → {ic['new_id']} ({ic['identity']['name']})")
+            print(f"    ⚠ {ic['warning']}")
+
+    if nodes['deleted']:
+        print(f"\n🗑  删除的节点 ({len(nodes['deleted'])}):")
+        for d in nodes['deleted']:
+            print(f"  - [{d['type']}] {d['id']} ({d['name']})")
+
+    if nodes['added']:
+        print(f"\n➕ 新增的节点 ({len(nodes['added'])}):")
+        for a in nodes['added']:
+            print(f"  - [{a['type']}] {a['id']} ({a['name']})")
+
+    if nodes['modified']:
+        print(f"\n✏️  修改的节点 ({len(nodes['modified'])}):")
+        for m in nodes['modified']:
+            changes = []
+            if m['type_changed']:
+                changes.append(f"type: {m['old']['type']} → {m['new']['type']}")
+            if m['name_changed']:
+                changes.append(f"name: {m['old']['name']} → {m['new']['name']}")
+            if m['attrs_changed']:
+                changes.append("attrs 已变更")
+            print(f"  - {m['id']}: {', '.join(changes) if changes else '无实质变更'}")
+
+    # 边汇总
+    print(f"\n📊 边汇总:")
+    print(f"  删除: {len(edges['deleted'])} | 新增: {len(edges['added'])} | "
+          f"修改: {len(edges['modified'])} | 未变: {edges['unchanged']}")
+
+    if edges['deleted']:
+        print(f"\n🗑  删除的边 ({len(edges['deleted'])}):")
+        for d in edges['deleted']:
+            print(f"  - {d['from']} → {d['to']}")
+
+    if edges['added']:
+        print(f"\n➕ 新增的边 ({len(edges['added'])}):")
+        for a in edges['added']:
+            print(f"  - {a['from']} → {a['to']}")
+
+    if edges['modified']:
+        print(f"\n✏️  修改的边 ({len(edges['modified'])}):")
+        for m in edges['modified']:
+            changes = []
+            if m['label_changed']:
+                changes.append("label 已变更")
+            if m['condition_changed']:
+                changes.append("condition 已变更")
+            if changes:
+                print(f"  - {m['from']} → {m['to']}: {', '.join(changes)}")
+            else:
+                print(f"  - {m['from']} → {m['to']}: 无实质变更")
+
+    # 最小修改原则评估
+    print(f"\n📋 最小修改原则评估:")
+    issues = 0
+    if nodes['id_changes']:
+        print(f"  ❌ 存在 ID 变更（{len(nodes['id_changes'])} 个节点），可能导致后端不支持配置丢失")
+        issues += 1
+    if nodes['deleted']:
+        print(f"  ⚠️  删除了 {len(nodes['deleted'])} 个节点，请确认是否为业务需要")
+        issues += 1
+    if not nodes['deleted'] and not nodes['id_changes'] and nodes['modified']:
+        print(f"  ✅ 仅修改已有节点，未删除或变更 ID，符合最小修改原则")
+    if not nodes['deleted'] and not nodes['modified'] and not nodes['added'] and not nodes['id_changes']:
+        print(f"  ✅ 无任何变更")
+
+    print(f"\n总结: 错误 {issues} 项")
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("用法: python3 diff_flow_spec.py <old_spec.json> <new_spec.json> [--json]")
+        sys.exit(1)
+
+    old_file = sys.argv[1]
+    new_file = sys.argv[2]
+    output_json = '--json' in sys.argv
+
+    try:
+        old_spec = load_json(old_file)
+    except Exception as e:
+        print(f"FATAL: 无法读取旧 spec 文件 {old_file}: {e}")
+        sys.exit(1)
+
+    try:
+        new_spec = load_json(new_file)
+    except Exception as e:
+        print(f"FATAL: 无法读取新 spec 文件 {new_file}: {e}")
+        sys.exit(1)
+
+    old_nodes = old_spec.get('nodes', [])
+    new_nodes = new_spec.get('nodes', [])
+    old_edges = extract_edges(old_spec)
+    new_edges = extract_edges(new_spec)
+
+    result = {
+        'nodes': diff_nodes(old_nodes, new_nodes),
+        'edges': diff_edges(old_edges, new_edges),
+    }
+
+    if output_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print_human(result)
+
+    # 如果有 ID 变更，返回非零以便脚本判断
+    has_id_changes = len(result['nodes']['id_changes']) > 0
+    sys.exit(1 if has_id_changes else 0)
+
+
+if __name__ == '__main__':
+    main()