@qingflow-tech/qingflow-cli 1.1.48 → 1.1.50

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md

@@ -1,7 +1,8 @@
 # Qingflow CLI：更新记录工作流（详情后直接写入）
 
+> **兼容范围**：本文仅限用户明确要求旧 CLI `record` 兼容入口时使用。默认更新必须切换到 [data 操作说明](../data/README.md) 的 `data get` → `data update`；禁止在 data update 失败后自动回退本文链路。
 > **用途**：使用当前 CLI 会话读取目标记录详情后，用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`；字段范围不清、候选歧义或失败排查时，才追加 **`record schema update`**。
-> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `record access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
+> **关联**：直接数据操作统一使用 [data 操作说明](../data/README.md)；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 

package/skills/qingflow-cli/reference/record/analysis/README.md

@@ -1,130 +1,38 @@
-# Qingflow CLI Record Analysis
+# 轻流记录数据分析
 
-Use this section for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
-
-Default path, every time:
+最终统计结论、分析报告、趋势、排名、比例和分布统一使用以下路径：
 
 ```text
-app get -> record schema browse(view_id=...) -> record access -> Python/pandas -> final answer
-```
-
-Use the CLI entry:
-
-```bash
-qingflow record --help
-qingflow record access --help
-qingflow record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json --json
-```
-
-The CLI command is under the `record` command group, so the discovery path is: first inspect `qingflow record --help`, then inspect `qingflow record access --help`.
-
-## Hard Rules
-
-- Never start analysis from `record_list`, export, QingBI, or guessed field ids.
-- Never conclude `record_access` is unavailable just because it is not visible as a top-level MCP tool; check the CLI path `qingflow record access`.
-- Never call `record access` before `record schema browse`.
-- Use only field ids returned by `record schema browse`.
-- If `app_get.accessible_views[].analysis_supported=false`, do not use that view for `record_access`.
-- Prefer an explicit time range or business filter. If the user gives none and the table may be large, ask for scope or use a clearly provided month/quarter/year.
-- Read every CSV shard in `record_access.files[].local_path` with Python. Do not print raw CSV or load raw rows into model context.
-- Before final analysis, run a field-quality profile in pandas: row count, null rate, distinct count, and period coverage for candidate grouping fields.
-- Do not use a high-missing field as the main conclusion dimension. If a candidate dimension is sparse, downgrade it to an `已填写样本观察` and choose a cleaner semantic fallback when available.
-- Full final conclusions require `record_access.complete=true` and `record_access.safe_for_final_conclusion=true`.
-- `record_list` is only for sample inspection after the aggregate result is understood.
-- `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
-- `record_export_direct` is only for explicit export/download/Excel requests.
-- `chart_get` / QingBI is only for user-provided report URLs or chart ids.
-
-## Tool Selection
-
-| Need | Tool |
-|---|---|
-| Batch analysis, statistics, comparison, report | `record access -> Python` |
-| Browse a few example rows | `record_list` |
-| Inspect one record, logs, references, images, attachments | `record_get` |
-| User asks to export/download/Excel | `record_export_direct` |
-| User gives report URL or chart id | `chart_get` |
-| Todo/workflow task actions | `reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md` |
-
-## Standard Procedure
-
-1. Run `app get` and choose a table-style `view_id` from `accessible_views`.
-2. Run `record schema browse --app-key APP_KEY --view-id VIEW_ID`.
-3. Decide metric intent before fetching data: `count`, `sum`, `avg`, `distinct_count`, ratio, ranking, trend, or comparison.
-4. Choose minimal `record_access.columns`, plus `where` and `order_by`.
-5. Run `qingflow record access`.
-6. Read all returned CSV files in Python; use `fields[]` only when field-id metadata is needed.
-7. Run field-quality checks for all candidate dimensions.
-8. Compute results in pandas.
-9. Report numbers with scope, field choices, field-quality caveats, completeness, and business assumptions.
-
-Use field-id DSLs only:
-
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
-  "order_by": [{ "field_id": 2, "direction": "asc" }]
-}
+qingflow data query --all --output csv -> 读取全部 CSV 分片 -> Python/pandas
 ```
 
-Never pass `page`, `page_size`, `limit`, `max_rows`, `timeout`, or `profile` to `record_access`.
-
-CSV columns are already readable and field-id anchored, for example `项目状态__field_343283094`. Do not expect separate `schema.json` or `README.md` files.
-
-For CLI use, write JSON argument files instead of embedding large JSON in shell text:
+先用当前 CLI 帮助确认参数：
 
 ```bash
-qingflow record access \
+qingflow data --help
+qingflow data query --help
+qingflow --json data query \
   --app-key APP_KEY \
-  --view-id system:all \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --sort-file sort.json \
+  --all --output csv
 ```
 
-## Status Handling
-
-Read `record_access.status` before reading files or writing conclusions.
-
-- `status=success`, `complete=true`, `safe_for_final_conclusion=true`: full-scope answer is allowed.
-- `status=needs_scope`: no CSV was written. Ask for a time/business range or retry with a user-provided period using `scope.suggested_time_fields`.
-- `status=partial`: read returned files only as a subset. Do not give a full-population conclusion.
-- `complete=false`, `truncated=true`, or `safe_for_final_conclusion=false`: answer as `初步观察` or ask for a narrower scope.
-
-## Business Context
-
-If the question mentions department, team, region, owner group, stage, product line, or a named business scope, check whether aliases or child scopes matter before concluding. Use explicit mappings provided by the user or local context; otherwise ask a short clarification.
-
-Example: if `烈焰组` and `飓风组` are sub-departments of `北斗部门`, apply that mapping in Python and state it in the answer.
-
-## Output Shape
-
-Default to:
-
-1. `结论`
-2. `关键数据`
-3. `口径与范围`
-4. `可信度 / 限制`
-
-Concrete numbers are mandatory. Ratios require both numerator and denominator. Trends require a time field and explicit date range. Rankings must come from a sorted pandas result.
-If a requested dimension has poor quality, say so explicitly and provide the nearest reliable fallback dimension, for example platform or product instead of a mostly empty module field.
+`--all` 与 `--output csv` 必须同时使用。columns 使用字段 id 数组；where 与 sort 使用包含 `field_id` 的对象数组。字段 id 来自当前 data schema 或已确认上下文，不得猜测。
 
-## References
+## 分析门禁
 
-Load only what is needed:
+- 读取返回摘要的 `status`、`row_count`、`complete`、`truncated`、`safe_for_final_conclusion`、`files` 和 `stopped_reason`。
+- 用 Python/pandas 读取全部 `files[].local_path`，不要把原始 CSV 行打印到模型上下文。
+- 完整总体结论必须同时满足 `complete=true`、`truncated=false`、`safe_for_final_conclusion=true`。
+- `status=needs_scope` 时 `files` 为空；读取 `scope.reported_total` 与 `scope.row_threshold`，请求时间或业务范围后重试。
+- `status=partial` 或任一完整性条件不满足时，只能给出局部观察，或收窄范围后重试。
+- 最终分组前检查行数、空值率、唯一值数量与时间覆盖；高缺失维度只能作为“已填写样本观察”。
+- `record list` 仅用于样本核查，不能代替全量 CSV；导出工具只用于用户明确要求下载文件的场景。
 
-- Data access status machine: [references/data-access-playbook.md](./data-access-playbook.md)
-- Python/pandas templates: [references/pandas-recipes.md](./pandas-recipes.md)
-- Analysis patterns: [references/analysis-patterns.md](./analysis-patterns.md)
-- Business mappings and scope: [references/business-context.md](./business-context.md)
-- Confidence and final wording: [references/confidence-reporting.md](./confidence-reporting.md)
-- Common mistakes: [references/analysis-gotchas.md](./analysis-gotchas.md)
-- Report templates: [references/report-format.md](./report-format.md)
+## 输出要求
 
-## Feedback Escalation
+默认输出结论、关键数据、口径与范围、可信度／限制。比例必须包含分子与分母，趋势必须说明时间字段与日期范围，排名必须来自 pandas 显式排序。
 
-If the desired analysis cannot be completed because of missing capability, unsupported data shape, or an awkward workflow after reasonable attempts, summarize the exact gap and ask whether to submit product feedback. Only after explicit user confirmation, call `feedback_submit`.
+进一步细节见同目录的取数状态机、pandas 模板、分析模式、业务上下文、可信度和报告模板。

package/skills/qingflow-cli/reference/record/analysis/analysis-gotchas.md

@@ -1,19 +1,19 @@
 # Analysis Gotchas
 
-## Do Not Skip Schema
+## 不要猜字段 schema
 
-Correct path:
+正确路径：
 
-1. `app_get`
-2. `record_browse_schema_get`
-3. `record_access`
-4. Python
+1. 从当前 data schema 或已确认上下文选择字段 id
+2. `data query --all --output csv`
+3. 读取全部 `files[].local_path`
+4. Python/pandas
 
-`record_browse_schema_get` returns readable fields for the selected view. Missing fields are permission or view-scope boundaries, not invitations to guess hidden ids.
+data 工具返回的 schema、字段错误与访问范围是事实源；缺失字段不是猜测隐藏 id 的理由。
 
 ## Do Not Use Export For Analysis
 
-Export tools are for user-requested files. Analysis uses `record_access` because it returns structured completeness and compact field metadata.
+导出工具只用于用户明确要求下载文件。分析使用 `data query --all --output csv`，因为它返回本地 CSV 分片与结构化完整性字段。
 
 ## Do Not Treat `record_list` As Full Data
 
@@ -28,7 +28,7 @@ Export tools are for user-requested files. Analysis uses `record_access` because
 
 ## Do Not Control Paging
 
-`record_access` owns paging internally.
+`data query --all --output csv` 内部处理分页。
 
 Do not invent:
 
@@ -84,7 +84,7 @@ For penetration, conversion, or share:
 
 ## Normalize Relative Dates
 
-Convert relative phrases into exact ranges before `record_access`.
+在 data query 前把相对日期转换为精确范围。
 
 - `今年5月` -> exact May 1 to May 31 in the current year
 - `去年同期` -> same date range in previous year

package/skills/qingflow-cli/reference/record/analysis/analysis-patterns.md

@@ -2,12 +2,12 @@
 
 ## Canonical Sequence
 
-1. `app_get`
-2. `record_browse_schema_get`
-3. decide metric intent
-4. choose `record_access.columns / where / order_by`
-5. `record_access`
-6. Python over every returned CSV shard
+1. 明确 `app_key`
+2. 从当前 data schema 或已确认上下文选择字段 id
+3. 决定指标意图
+4. 选择 data query 的 columns / where / sort
+5. `data query --all --output csv`
+6. Python 读取每个 `files[].local_path`
 7. optional `record_list` or `record_get` only for sample/detail verification
 
 Metric intent must be one of:
@@ -74,7 +74,7 @@ If denominator is missing or scope differs, do not call the result a rate.
 
 ## Trend
 
-1. Choose a date/time field from `suggested_time_fields`.
+1. 从 data schema 或查询响应的 `fields` 中选择日期／时间字段，并核对其 id、标题与类型。
 2. Convert relative phrases into exact date ranges.
 3. Fetch the date field and metrics.
 4. Bucket in pandas by day/week/month/quarter/year.
@@ -104,8 +104,8 @@ Never use `record_list` alone for final averages, shares, rankings, trends, or d
 
 If the exact field is unclear:
 
-1. inspect `record_browse_schema_get.fields`
-2. use titles and suggested fields
+1. 检查 data schema 或返回的 `fields`
+2. 按 `fields` 中的标题、字段 id 与类型筛选候选字段
 3. if one candidate is clearly dominant, proceed
 4. otherwise ask the user to confirm
 

package/skills/qingflow-cli/reference/record/analysis/business-context.md

@@ -54,7 +54,7 @@ If any part is ambiguous, ask. Do not rename a count as a rate.
 
 ## Time Scope
 
-Normalize relative dates to exact dates before calling `record_access`.
+调用 data query 前把相对日期转换为精确日期。
 
 Examples:
 

package/skills/qingflow-cli/reference/record/analysis/confidence-reporting.md

@@ -4,12 +4,12 @@
 
 Use `全量可信结论` only when:
 
-- `record_browse_schema_get` was used
-- data came from `record_access`
+- 字段 id 来自当前 data schema 或已确认上下文
+- 数据来自 `data query --all --output csv`
 - all returned CSV shards were read in Python
-- `record_access.complete=true`
-- `record_access.truncated=false`
-- `record_access.safe_for_final_conclusion=true`
+- `complete=true`
+- `truncated=false`
+- `safe_for_final_conclusion=true`
 - metric definitions are complete
 - denominator exists for every ratio
 - time fields and date ranges are explicit
@@ -19,11 +19,11 @@ Use `全量可信结论` only when:
 
 Use `初步观察` when:
 
-- `record_access.status=needs_scope`
-- `record_access.status=partial`
-- `record_access.complete=false`
-- `record_access.truncated=true`
-- `record_access.safe_for_final_conclusion=false`
+- `status=needs_scope`
+- `status=partial`
+- `complete=false`
+- `truncated=true`
+- `safe_for_final_conclusion=false`
 - evidence came from `record_list`
 - scope or saved view filter is unverified
 

package/skills/qingflow-cli/reference/record/analysis/data-access-playbook.md

@@ -1,106 +1,78 @@
-# Data Access Playbook
+# data CSV 取数状态机
 
-This file is the operational state machine for `record_access`.
+## 必须路径
 
-## Required Sequence
+1. 明确 `app_key` 与指标意图。
+2. 从当前 data schema 或已确认上下文选择字段 id。
+3. 构造 columns、where、sort JSON 文件。
+4. 执行 `data query --all --output csv`。
+5. 读取全部 `files[].local_path` 并在 Python/pandas 中合并。
 
-1. `app_get`
-2. choose `view_id` from `accessible_views`
-3. `record_browse_schema_get(app_key, view_id)`
-4. build `record_access.columns / where / order_by` from field ids
-5. run `record_access`
-6. read every CSV shard with Python
-
-Do not call `record_access` with field titles, guessed ids, page controls, row limits, or profile.
-CSV columns are readable and field-id anchored, for example `项目状态__field_343283094`; do not look for extra `schema.json` or README files.
-
-## Finding `record_access`
-
-`record_access` can be available as an MCP tool or as a CLI subcommand. If the MCP surface does not show a top-level `record_access` tool, look under the Qingflow CLI record group before choosing any other path:
-
-```bash
-qingflow record --help
-qingflow record access --help
-```
-
-The CLI call is:
+CLI 发现与调用：
 
 ```bash
-qingflow record access \
+qingflow data --help
+qingflow data query --help
+qingflow --json data query \
   --app-key APP_KEY \
-  --view-id VIEW_ID \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --sort-file sort.json \
+  --all --output csv
 ```
 
-This is the same analysis path: it writes CSV shards and metadata for Python. Do not replace it with list browsing, export, QingBI, or aggregate helpers just because the MCP tool is not visible.
-
-## Request Patterns
+columns 是字段 id 数组，例如 `[2, 18]`；where 和 sort 是带 `field_id` 的对象数组。`--all` 与 `--output csv` 必须同时出现。
 
-### Count or distribution
+## 真实输出字段
 
-Fetch the grouping field and any time/business filter field.
+分析前先读取：
 
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
-  "order_by": []
-}
-```
+- `status`
+- `files[].local_path`、`files[].row_count`、`files[].part`
+- `row_count`
+- `complete`
+- `truncated`
+- `safe_for_final_conclusion`
+- `fetched_pages`
+- `stopped_reason`
+- `fields`
 
-### Trend
+输出还可能包含 `local_dir`、访问上下文和动态提示；这些内容保持原样解释，不在本地补造。
 
-Fetch the date/time field plus metric fields.
+## 状态决策
 
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-01-01", "2026-12-31"] }],
-  "order_by": [{ "field_id": 2, "direction": "asc" }]
-}
-```
-
-### Ratio
-
-If numerator and denominator use different filters, run separate `record_access` calls. Only compute the ratio after both source datasets are complete and compatible.
-
-## Status Decisions
-
-| Status | Meaning | Agent action |
+| 状态 | 含义 | 动作 |
 |---|---|---|
-| `success` + `safe_for_final_conclusion=true` | Full retrieved scope is reliable | Give final conclusion |
-| `needs_scope` | Tool refused large unbounded scan, no CSV | Ask for scope or retry with explicit period/business filter |
-| `partial` | Some CSV files written, but not full data | Give only subset observation |
-| `complete=false` | Not all requested data is available | Do not present full-population conclusion |
-| `truncated=true` | Tool had to stop before full scope | Disclose and narrow scope |
-
-## `needs_scope` Recovery
+| `success` 且完整性三项满足 | 请求范围完整可用 | 读取所有分片后形成总体结论 |
+| `needs_scope` | 无范围大查询被拒绝，未写 CSV | 读取 `scope.reported_total` 与 `scope.row_threshold`，请求时间或业务范围 |
+| `partial` | 已写部分 CSV，但未完成 | 只给局部观察，说明 `row_count` 与 `stopped_reason` |
+| `complete=false` | 未取完请求范围 | 不给总体结论 |
+| `truncated=true` | 提前停止 | 收窄范围后重试 |
+| `safe_for_final_conclusion=false` | 不适合最终总体结论 | 降级或重试 |
 
-Use the returned `scope` object:
+`needs_scope` 时 `files=[]`、`row_count=0`；不要寻找不存在的 CSV。partial 时保留的文件可用于局部观察，但不能使用“全部”“整体”“全量”等措辞。
 
-- `reported_total`: explain why scope is needed
-- `suggested_time_fields`: choose likely date fields
-- `recommended_where_examples`: reuse if they match the user request
+## 请求示例
 
-If the user already provided a concrete month/quarter/year, retry with that period. If no business boundary is available, ask one short clarification.
+`columns.json`：
 
-## `partial` Recovery
+```json
+[2, 18]
+```
 
-You may read the files, but must label output as partial:
+`where.json`（同一字段的范围使用两个公开操作符并按 AND 组合）：
 
-- say which files/rows were analyzed
-- do not use `全部`, `所有`, `整体`, or `全量`
-- suggest narrowing time or business scope before final conclusion
+```json
+[
+  {"field_id": 2, "op": "gte", "value": "2026-05-01"},
+  {"field_id": 2, "op": "lte", "value": "2026-05-31"}
+]
+```
 
-## View Scope
+`sort.json`：
 
-For custom views, the result is scoped to that saved view. If `verification.view_filter_verified=false`, disclose that the saved-filter scope could not be fully verified.
+```json
+[{"field_id": 2, "direction": "asc"}]
+```
 
-For board/gantt views, switch to a table-style view or `system:all` plus explicit filters.
+若分子和分母使用不同筛选，分别执行兼容范围的 data query；两侧都满足完整性门禁后再计算比例。

package/skills/qingflow-cli/reference/record/analysis/pandas-recipes.md

@@ -9,14 +9,14 @@ import pandas as pd
 
 files = [
     "/absolute/path/records-0001.csv",
-    # include every record_access.files[].local_path
+    # 包含 data query 返回的每个 files[].local_path
 ]
 
 frames = [pd.read_csv(path, dtype=str, keep_default_na=False) for path in files]
 df = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
 
 # Columns are readable and field-id anchored, e.g. 项目状态__field_343283094.
-fields = []  # optionally paste record_access.fields here if you need field-id metadata
+fields = []  # 需要字段 id 元数据时使用 data query 返回的 fields
 field_by_id = {int(item["field_id"]): item for item in fields if "field_id" in item}
 title_by_col = {item["column_name"]: item["title"] for item in fields if item.get("column_name")}
 ```

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

@@ -1,18 +1,22 @@
 #!/usr/bin/env python3
 """
 验证工作流 spec JSON 是否符合 WorkflowSpecDTO JSON Schema，
-并执行自定义约束检查（DAG、单 applicant、gateway 条件等）。
+并执行自定义约束检查（边端点/自环、单 applicant、gateway 条件等）。
+
+环判定口径与后端 LegacyEngineFlowValidator（G 规则）镜像：
+- 自环（A→A）拒绝；无根纯环（A→B→A，无 gateway）拒绝；
+- 经 gateway 回指的驳回环（approval→gateway→approval）合法，不做通用 DAG 无环检查；
+- 单节点流程（仅 applicant，空边）合法，提交即结束。
 
 用法:
   python3 validate_flow_spec.py <spec_file.json> --schema <schema_file.json>
-
+  
 schema 文件应在运行时通过 qingflow builder flow schema --json 动态获取。
 """
 
 import json
 import sys
 import os
-from collections import deque
 
 try:
     import jsonschema
@@ -48,35 +52,23 @@ def validate_schema(spec, schema):
 
 
 def check_dag(nodes, edges):
-    """检查边是否构成 DAG（无环）"""
+    """检查边端点存在性与自环（与后端 G2/G4 口径镜像）。
+
+    注意：不做通用 DAG 无环检查——轻流流程存在合法驳回环
+    （approval -> gateway -> approval，经 gateway 回指的回退边），
+    后端同样只拒绝自环与无根纯环；通用 Kahn 环检测曾造成 409 例合法流程误报。
+    """
     node_ids = {n['id'] for n in nodes}
-    adj = {nid: [] for nid in node_ids}
+    errors = []
     for e in edges:
-        f, t = e['from'], e['to']
+        f, t = e.get('from'), e.get('to')
         if f not in node_ids:
-            return [f"edge from={f} to={t}: from 节点不存在于 nodes 中"]
+            errors.append(f"edge from={f} to={t}: from 节点不存在于 nodes 中")
         if t not in node_ids:
-            return [f"edge from={f} to={t}: to 节点不存在于 nodes 中"]
-        adj[f].append(t)
-
-    # Kahn's algorithm for topological sort
-    indeg = {nid: 0 for nid in node_ids}
-    for e in edges:
-        indeg[e['to']] += 1
-
-    q = deque([nid for nid, d in indeg.items() if d == 0])
-    visited = 0
-    while q:
-        u = q.popleft()
-        visited += 1
-        for v in adj[u]:
-            indeg[v] -= 1
-            if indeg[v] == 0:
-                q.append(v)
-
-    if visited != len(node_ids):
-        return ["检测到环路：工作流边中存在环，不符合 DAG 要求"]
-    return []
+            errors.append(f"edge from={f} to={t}: to 节点不存在于 nodes 中")
+        if f == t:
+            errors.append(f"自环边 from={f} to={t}：节点指向自身（自环被后端 G2 拒绝）")
+    return errors
 
 
 def check_applicant(nodes):
@@ -301,22 +293,31 @@ def check_orphan_nodes(nodes, edges):
 
 
 def check_routing_entry_and_sync(nodes, edges):
-    """检查入口出边和需要继续流转节点的 sync 标记。"""
+    """检查入口出边和需要继续流转节点的 sync 标记。
+
+    返回 (errors, warnings)：单节点流程（仅 applicant、无出边）合法，降为警告
+    （提交即结束，后端 apply 同样放行）。
+    """
     errors = []
+    warn = []
     outgoing = {}
     for edge in edges:
         outgoing.setdefault(edge.get('from'), []).append(edge.get('to'))
 
+    single_node = len(nodes) == 1
     for node in nodes:
         node_id = node.get('id')
         node_type = node.get('type')
         node_label = f"节点 {node_id} ({node.get('name','')})"
         has_outgoing = bool(outgoing.get(node_id))
         if node_type == 'applicant' and not has_outgoing:
-            errors.append(f"申请人入口节点 {node_id} 没有出边，提交后流程不会进入下一节点")
+            if single_node:
+                warn.append(f"单节点流程：入口节点 {node_id} 无出边，提交即结束（合法形态）")
+            else:
+                errors.append(f"申请人入口节点 {node_id} 没有出边，提交后流程不会进入下一节点")
         if has_outgoing and node.get('sync') is not True:
             errors.append(f"{node_label} 存在出边但未显式 sync=true，后端可能停止继续路由")
-    return errors
+    return errors, warn
 
 
 def check_minimal_modification(old_spec, new_spec):
@@ -545,25 +546,17 @@ def main():
     nodes, edges = normalize_spec(spec)
     if not nodes:
         all_errors.append("[结构] spec 中未找到 nodes 数组")
-    if not edges:
-        all_errors.append("[结构] spec 中未找到 edges 数组")
+    # edges 可为空列表：单节点流程（仅 applicant）合法（提交即结束）；多节点必须有边
+    if not edges and len(nodes) > 1:
+        all_errors.append("[结构] 多节点流程要求 edges 非空（单节点流程可为空数组）")
 
-    if nodes and edges:
+    if nodes:
         # 3. 必要字段检查
         all_errors.extend(check_required_fields(nodes, edges))
 
-        # 4. DAG 检查（回退边/驳回边可能导致环，降级为警告）
-        dag_errors = check_dag(nodes, edges)
-        if dag_errors:
-            warnings.extend(dag_errors)
-            warnings.append("DAG 环通常由回退边（如审批驳回、gateway 回退）引起，可能是合法的业务需求")
-
         # 5. 单 applicant 检查
         all_errors.extend(check_applicant(nodes))
 
-        # 6. Gateway 条件检查
-        all_errors.extend(check_gateway_conditions(nodes, edges))
-
         # 7. 审批节点检查
         all_errors.extend(check_approval_nodes(nodes))
 
@@ -576,12 +569,21 @@ def main():
         # 10. 抄送节点检查
         all_errors.extend(check_cc_nodes(nodes))
 
+        # 12. 入口出边与 sync 检查（单节点流程降为警告；空边时 outgoing 为空也需检查）
+        entry_errors, entry_warnings = check_routing_entry_and_sync(nodes, edges)
+        all_errors.extend(entry_errors)
+        warnings.extend(entry_warnings)
+
+    if edges:
+        # 4. 边结构检查（端点存在 + 自环；与后端 G2/G4 口径镜像，合法驳回环放行）
+        all_errors.extend(check_dag(nodes, edges))
+
+        # 6. Gateway 条件检查
+        all_errors.extend(check_gateway_conditions(nodes, edges))
+
         # 11. 孤立节点检查
         all_errors.extend(check_orphan_nodes(nodes, edges))
 
-        # 12. 入口出边与 sync 检查
-        all_errors.extend(check_routing_entry_and_sync(nodes, edges))
-
     # 13. 更新模式：最小修改原则检查
     if previous_file:
         try: