@qingflow-tech/qingflow-cli 1.1.47-beta.1 → 1.1.47-beta.3

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.47-beta.1
+npm install @qingflow-tech/qingflow-cli@1.1.47-beta.3
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.1 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.3 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.1 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.3 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.47-beta.1",
+  "version": "1.1.47-beta.3",
   "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.47b1"
+version = "1.1.47b3"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -124,6 +124,24 @@ qingflow auth login \
 qingflow --json auth whoami
 ```
 
+### 交付网页资源链接
+
+创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。
+
+默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。
+
+部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明。纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。用户明确要求查看或打开页面时也使用已确认的路径。
+
+目标浏览器登录态未知时，临近交付取该 URI 的 pathname 执行：
+
+```bash
+qingflow auth login-link --redirect-path "/resources/ws/<WS_ID>/app/<APP_KEY>"
+```
+
+对每个实际展示的入口分别签发，使用本次返回的完整 URL，不额外追问登录态，不复用已消费链接。只有已有用户确认同一浏览器、网页域名、账号和工作区已登录、没有失效信号的事实，才直接交付稳定 `uri`。CLI 已登录、自动化浏览器已登录或曾经成功签发票据都不能证明目标浏览器已登录。
+
+用户未要求打开时不要提前打开或消费链接；签发失败时说明免登录链接未生成，并提供标注“需登录”的稳定 `uri` 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。
+
 常用参数：`--credential-stdin`、`--password-stdin`、`--persist` / `--forget-persisted`；详见 `qingflow auth --help`。
 
 ---
@@ -449,17 +467,17 @@ qingflow auth logout --forget-persisted
 
 ### 临时网页登录链接
 
-仅在用户需要进入网页查看或继续操作时生成，纯数据查询不自动调用：
+按上文“交付网页资源链接”规则，在创建、修改或安装完成后主动为主要结果提供查看入口；用户明确要求进入页面时也适用，纯数据问答不自动调用：
 
 ```bash
 qingflow --json auth login-link
-qingflow --profile default --json auth login-link --redirect-path "/index/app/123?view=abc"
+qingflow --profile default --json auth login-link --redirect-path "/resources/ws/<WS_ID>/app/<APP_KEY>"
 ```
 
 - 默认使用当前会话和已选工作区；缺失时按实际错误恢复，不额外预查或重新登录。
 - `--redirect-path` 可选，仅接受已确认的站内业务路径，可包含 query/hash；不接受外域或认证入口。示例 ID 仅作格式展示，不得照抄或编造实际目标；省略时进入工作区首页。
 - 将返回的 `url` 作为可点击链接交付，不修改或拼造。链接短时有效且仅可使用一次，失效后重新获取，不写入公共文档或日志。
-- 命令不会自动打开浏览器；用户仅索取链接时不提前打开，明确要求打开时才调用浏览器。
+- 命令不会自动打开浏览器；用户未要求打开时不提前打开或消费链接，明确要求打开时才调用浏览器。
 
 **高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。
 

package/skills/qingflow-common/SKILL.md

@@ -45,7 +45,12 @@ Each package includes this common Skill. The CLI package installs its CLI guidan
 
 ## 从 AI 对话进入轻流页面
 
-用户需要查看结果、继续编辑、处理业务或进入工作区页面时，MCP 调用 `get_login_link`，CLI 调用 `qingflow --json auth login-link`。纯数据查询无需页面，不自动生成链接。
+创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。用户明确要求查看或打开页面时也适用以下规则。
+
+- 默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。
+- 主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明，不把链接当作整个任务成功的证明。
+- 纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。
+- MCP 调用 `get_login_link`；CLI 调用 `qingflow --json auth login-link --redirect-path <资源 pathname>`。
 
 - 目标路径使用用户提供或业务工具确认的站内路径，不根据应用、记录标识猜测地址。
 - 用户明确指定页面但路径未知时继续定位或说明限制，不猜测，也不静默替换成首页。搜索未命中时继续搜索 `login` 或查看服务工具列表，不擅自打开固定正式站点；失败时如实说明。
@@ -53,10 +58,14 @@ Each package includes this common Skill. The CLI package installs its CLI guidan
 - 默认使用当前会话及已选工作区；需要指定会话时使用 MCP 的 `profile` 或 CLI 的 `--profile`。
 - `redirect_path` 可选，默认空：省略时进入工作区首页；传入时仅支持以单个 `/` 开头的站内业务路径，可带 query/hash。不得传完整 URL、外部地址、认证入口或多层编码路径。
 - 示例：`get_login_link({})`；指定目标示例：`get_login_link({"redirect_path":"/index/app/123?view=abc"})`。示例标识仅作格式展示，实际目标必须来自用户提供或已经确认的页面信息，不得编造应用、记录标识。
-- 临近交付时再生成，使用返回的 `url`，文案贴合“查看记录”“继续编辑”等上下文，不展示工作区数字 ID 或原始 JSON。
+- 成功响应仅有 `url` 和毫秒整数 `expires_at`。临近交付时再签发，使用本次返回的完整链接作为主要点击入口，不展示工作区数字 ID 或原始 JSON。
 - CLI 示例：`qingflow --json auth login-link`；指定目标使用 `qingflow --profile default --json auth login-link --redirect-path "/index/app/123?view=abc"`，同样不得编造实际路径。
-- 链接短时有效且仅可使用一次，失效后重新获取，不修改或拼造链接；只交付给请求用户，不写入公共文档或日志。
-- 用户要求“给我链接”时仅交付，不提前消费；要求“打开”时才使用可用浏览器打开。浏览器不可用时提供可点击链接，不假称已经打开。
+- 目标浏览器状态未知时，默认按每个待交付资源分别签发新链接，不额外追问登录态。只有已有用户确认目标是同一浏览器、网页域名、账号和工作区且已登录、没有失效信号的事实，才直接交付稳定 `uri`。调用过票据工具、自动化浏览器已登录或之前签发过票据都不是该事实；已消费链接不可复用。
+- 链接约 5 分钟内只能兑换一次，不作为长期书签；过期或使用后重新调用，不修改票据或拼造链接；只交付给请求用户，不写入公共文档或日志。
+- 用户未要求打开时仅交付，不提前消费；要求“打开”时才使用可用浏览器打开。浏览器不可用时提供可点击链接，不假称已经打开。
+- 签发失败时说明免登录链接未生成，并提供标注“需登录”的稳定 `uri` 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。
+- 必要的 MFA、密码安全验证仍执行，完成后先切换当前 MCP 工作区，再进入目标页面；业务权限仍由目标页面校验，不因链接而扩大。
+- 工具拒绝非法跳转参数；浏览器收到被篡改的非法目标时忽略目标并进入首页。网页域名由 MCP 配置 `QINGFLOW_MCP_WEB_BASE_URL` 决定，不从目标路径选择其他环境。
 
 ## Route Next
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -19,6 +19,7 @@ from ..backend_client import BackendRequestContext
 from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error
 from ..json_types import JSONObject
 from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_TYPE
+from ..resource_uri import validate_positive_resource_id, validate_resource_identity
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
@@ -1491,6 +1492,74 @@ class AiBuilderFacade:
                 details={"solution_key": requested_solution_key},
                 suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
             )
+        raw_result = created.get("result") if isinstance(created.get("result"), dict) else {}
+        raw_tag_ids = raw_result.get("tagIds")
+        raw_app_keys = raw_result.get("appKeys")
+        tag_ids, tag_ids_complete = _unique_resource_tag_ids(raw_tag_ids)
+        app_keys, app_keys_complete = _unique_resource_app_keys(raw_app_keys)
+        resource_list_complete = tag_ids_complete and app_keys_complete
+        resources: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+
+        for tag_id in tag_ids:
+            name = None
+            try:
+                detail = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=False)
+                package = detail.get("result") if isinstance(detail.get("result"), dict) else {}
+                name = str(package.get("tagName") or package.get("tag_name") or "").strip() or None
+            except (QingflowApiError, RuntimeError):
+                pass
+            if not name:
+                warnings.append(_warning("RESOURCE_NAME_UNAVAILABLE", "installed package name could not be read", package_id=tag_id))
+            resources.append(
+                _compact_dict(
+                    {
+                        "resource_type": "package",
+                        "operation": "installed",
+                        "status": "success",
+                        "id": tag_id,
+                        "key": str(tag_id),
+                        "name": name,
+                        "ids": {"package_id": tag_id},
+                    }
+                )
+            )
+
+        for app_key in app_keys:
+            name = None
+            parent = None
+            try:
+                detail = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=False)
+                app = detail.get("result") if isinstance(detail.get("result"), dict) else {}
+                name = str(app.get("formTitle") or app.get("appName") or "").strip() or None
+                matching_tag_ids = [tag_id for tag_id in _unique_positive_ints(app.get("tagIds")) if tag_id in tag_ids]
+                if len(matching_tag_ids) == 1:
+                    parent = {"resource_type": "package", "id": matching_tag_ids[0], "key": str(matching_tag_ids[0])}
+            except (QingflowApiError, RuntimeError):
+                pass
+            if not name:
+                warnings.append(_warning("RESOURCE_NAME_UNAVAILABLE", "installed application name could not be read", app_key=app_key))
+            resources.append(
+                _compact_dict(
+                    {
+                        "resource_type": "app",
+                        "operation": "installed",
+                        "status": "success",
+                        "key": app_key,
+                        "name": name,
+                        "ids": {"app_key": app_key},
+                        "parent": parent,
+                    }
+                )
+            )
+
+        if not resource_list_complete:
+            warnings.append(
+                _warning(
+                    "RESOURCE_LIST_INCOMPLETE",
+                    "solution installation succeeded, but its returned package/application identity list was incomplete",
+                )
+            )
         return {
             "status": "success",
             "error_code": None,
@@ -1503,9 +1572,15 @@ class AiBuilderFacade:
             "request_id": created.get("request_id"),
             "suggested_next_call": None,
             "noop": False,
-            "verification": {},
+            "warnings": warnings,
+            "verified": False,
+            "verification": {
+                "resource_list_complete": resource_list_complete,
+                "business_verified": False,
+            },
             "write_executed": True,
             "safe_to_retry": False,
+            "resources": resources,
         }
 
     def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
@@ -17148,6 +17223,49 @@ def _coerce_positive_int(value: Any) -> int | None:
     return None
 
 
+def _unique_positive_ints(value: Any) -> list[int]:
+    if not isinstance(value, list):
+        return []
+    result: list[int] = []
+    for item in value:
+        number = _coerce_positive_int(item)
+        if number is not None and number not in result:
+            result.append(number)
+    return result
+
+
+def _unique_resource_tag_ids(value: Any) -> tuple[list[int], bool]:
+    if not isinstance(value, list):
+        return [], False
+    result: list[int] = []
+    complete = True
+    for item in value:
+        try:
+            tag_id = validate_positive_resource_id(item, "package_id")
+        except (ValueError, UnicodeError):
+            complete = False
+            continue
+        if tag_id not in result:
+            result.append(tag_id)
+    return result, complete
+
+
+def _unique_resource_app_keys(value: Any) -> tuple[list[str], bool]:
+    if not isinstance(value, list):
+        return [], False
+    result: list[str] = []
+    complete = True
+    for item in value:
+        try:
+            app_key = validate_resource_identity(item, "app_key")
+        except (ValueError, UnicodeError):
+            complete = False
+            continue
+        if app_key not in result:
+            result.append(app_key)
+    return result, complete
+
+
 def _coerce_nonnegative_int(value: Any) -> int | None:
     if isinstance(value, bool) or value is None:
         return None

package/src/qingflow_mcp/cli/commands/auth.py

@@ -41,7 +41,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     whoami.set_defaults(handler=_handle_whoami, format_hint="auth_whoami")
 
     login_link = auth_subparsers.add_parser("login-link", help="生成当前工作区的临时一次性登录链接（不自动打开）")
-    login_link.add_argument("--redirect-path", default="", help="登录后跳转的站内路径，可包含查询参数和锚点")
+    login_link.add_argument("--redirect-path", default="", help="登录后跳转的站内路径；资源路径必须属于当前工作区，其他业务路径可包含查询参数和锚点")
     login_link.set_defaults(handler=_handle_login_link, format_hint="login_link")
 
     logout = auth_subparsers.add_parser("logout", help="退出登录")

package/src/qingflow_mcp/cli/context.py

@@ -10,12 +10,12 @@ from ..session_store import SessionStore
 from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
 from ..tools.auth_tools import AuthTools
-from ..tools.login_link_tools import LoginLinkTools
 from ..tools.code_block_tools import CodeBlockTools
 from ..tools.export_tools import ExportTools
 from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
 from ..tools.import_tools import ImportTools
+from ..tools.login_link_tools import LoginLinkTools
 from ..tools.record_tools import RecordTools
 from ..tools.resource_read_tools import ResourceReadTools
 from ..tools.task_context_tools import TaskContextTools

package/src/qingflow_mcp/cli/formatters.py

@@ -191,9 +191,10 @@ def _format_app_items(result: dict[str, Any]) -> str:
                 str(item.get("app_key") or item.get("appKey") or ""),
                 str(item.get("app_name") or item.get("name") or item.get("title") or ""),
                 str(item.get("package_name") or item.get("tag_name") or ""),
+                str(item.get("uri") or ""),
             ]
         )
-    return _render_titled_table("Apps", ["app_key", "app_name", "package"], rows)
+    return _render_titled_table("Apps", ["app_key", "app_name", "package", "uri"], rows)
 
 
 def _format_app_get(result: dict[str, Any]) -> str:
@@ -201,6 +202,7 @@ def _format_app_get(result: dict[str, Any]) -> str:
     lines = [
         f"App: {data.get('app_name') or '-'}",
         f"App Key: {data.get('app_key') or '-'}",
+        f"URI: {data.get('uri') or '-'}",
         f"Can Create: {data.get('can_create')}",
     ]
     import_capability = data.get("import_capability")
@@ -224,7 +226,7 @@ def _format_app_get(result: dict[str, Any]) -> str:
     lines.append(f"Accessible Views: {len(views)}")
     for item in views[:10]:
         if isinstance(item, dict):
-            lines.append(f"- {item.get('view_id')}: {item.get('name')}")
+            lines.append(f"- {item.get('view_id')}: {item.get('name')} / {item.get('uri') or '-'}")
     _append_warnings(lines, result.get("warnings"))
     return "\n".join(lines) + "\n"
 
@@ -296,6 +298,7 @@ def _format_view_get(result: dict[str, Any]) -> str:
         f"View Key: {data.get('view_key') or '-'}",
         f"App Key: {data.get('app_key') or '-'}",
         f"View Type: {data.get('view_type') or '-'}",
+        f"URI: {data.get('uri') or '-'}",
         f"Analysis Supported: {data.get('analysis_supported')}",
     ]
     if export_capability:
@@ -1184,6 +1187,7 @@ def _format_builder_summary(result: dict[str, Any]) -> str:
         ("view_key", "View Key"),
         ("chart_id", "Chart ID"),
         ("package_id", "Package ID"),
+        ("uri", "URI"),
         ("verified", "Verified"),
         ("write_executed", "Write Executed"),
         ("delete_executed", "Delete Executed"),
@@ -1216,6 +1220,7 @@ def _format_builder_summary(result: dict[str, Any]) -> str:
         "associations",
         "package_ids",
         "app_keys",
+        "resources",
     ):
         value = result.get(key)
         if not isinstance(value, list) and isinstance(data, dict):
@@ -1226,6 +1231,15 @@ def _format_builder_summary(result: dict[str, Any]) -> str:
                 lines.append("- " + _builder_item_summary(item))
             if len(value) > 8:
                 lines.append(f"... {len(value) - 8} more")
+            if key == "apps":
+                uri_lines = [
+                    line
+                    for item in value
+                    for line in _builder_batch_item_uri_lines(item)
+                ]
+                if uri_lines:
+                    lines.append("Resource URIs:")
+                    lines.extend(f"- {line}" for line in uri_lines)
     components = result.get("components") if isinstance(result.get("components"), list) else []
     if components:
         lines.append("Component Refs:")
@@ -1294,6 +1308,7 @@ def _builder_item_summary(item: Any) -> str:
         "uid",
         "userId",
         "email",
+        "uri",
     )
     parts = [
         f"{key}={item.get(key)}"
@@ -1305,6 +1320,50 @@ def _builder_item_summary(item: Any) -> str:
     return " / ".join(parts) if parts else json.dumps(item, ensure_ascii=False)
 
 
+def _builder_batch_item_uri_lines(item: Any) -> list[str]:
+    if not isinstance(item, dict):
+        return []
+    item_status = str(item.get("status") or "").lower()
+    if item_status not in {"success", "partial_success"}:
+        return []
+    data = item.get("data") if isinstance(item.get("data"), dict) else item.get("result")
+    if not isinstance(data, dict) or not _builder_uri_is_confirmed(data, fallback_status=item_status):
+        return []
+    lines: list[str] = []
+    if data.get("uri"):
+        lines.append(f"URI: {data['uri']}")
+    views = data.get("views") if isinstance(data.get("views"), list) else []
+    for view in views:
+        if (
+            isinstance(view, dict)
+            and view.get("uri")
+            and _builder_uri_is_confirmed(view, fallback_status=item_status)
+        ):
+            lines.append(f"View URI: {view['uri']}")
+    return lines
+
+
+def _builder_uri_is_confirmed(value: dict[str, Any], *, fallback_status: str) -> bool:
+    status = str(value.get("status") or fallback_status).lower()
+    operation = str(value.get("operation") or "").lower()
+    return (
+        status in {"success", "partial_success", "unchanged", "verified"}
+        and operation
+        not in {
+            "failed",
+            "pending",
+            "planned",
+            "readback_pending",
+            "pending_readback",
+            "unknown",
+            "remove",
+            "removed",
+            "delete",
+            "deleted",
+        }
+    )
+
+
 def _format_file_upload_local(result: dict[str, Any]) -> str:
     lines = [
         f"Upload Kind: {result.get('upload_kind') or result.get('requested_upload_kind') or '-'}",
@@ -1567,7 +1626,7 @@ def _task_action_debug_lines(result: dict[str, Any]) -> list[str]:
 
 
 def _format_login_link(result: dict[str, Any]) -> str:
-    return f"登录链接：{result['url']}\n过期时间（Unix 毫秒）：{result['expires_at']}\n链接仅可使用一次，请勿泄露。\n"
+    return f"登录链接：{result['url']}\n过期时间（Unix 毫秒）：{result['expires_at']}\n链接只能使用一次，请勿泄露；仅在用户要求打开时才打开。\n"
 
 
 _FORMATTERS = {

package/src/qingflow_mcp/public_surface.py

@@ -128,6 +128,7 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("builder", "auth", "use-credential"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), ("builder", "auth", "whoami"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), ("builder", "auth", "logout"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "get_login_link", ("get_login_link",), mcp_public=True, cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), ("builder", "workspace", "list"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "workspace_get", ("workspace_get",), ("builder", "workspace", "get"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/resource_uri.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, unquote, urlsplit, urlunsplit
+
+from .config import get_web_base_url
+from .errors import QingflowApiError
+from .json_types import JSONObject
+
+
+SYSTEM_VIEW_NAMES = frozenset({"all", "initiated", "todo", "done", "cc"})
+_ENCODED_OCTET = re.compile(r"%[0-9A-Fa-f]{2}")
+
+
+@dataclass(frozen=True, slots=True)
+class ResourcePath:
+    resource_type: str
+    ws_id: int
+    package_id: int | None = None
+    app_key: str | None = None
+    view_kind: str | None = None
+    view_key: str | None = None
+
+
+def validate_resource_identity(value: object, field: str = "resource_id") -> str:
+    """按资源 URI 单路径段合同校验并返回规范身份，不读取网页域名配置。"""
+    return _validate_identity(value, field)
+
+
+def validate_positive_resource_id(value: object, field: str = "resource_id") -> int:
+    """按资源 URI 数字路径段合同校验正整数，不接受布尔值或浮点截断。"""
+    return int(_positive_int_segment(value, field))
+
+
+def build_resource_uri(
+    *,
+    ws_id: object,
+    resource_type: str,
+    package_id: object = None,
+    app_key: object = None,
+    view_kind: str | None = None,
+    view_key: object = None,
+    web_origin: str | None = None,
+) -> str:
+    """按固定公共合同构造资源 URI，不接受通用目标路由。"""
+    workspace = _positive_int_segment(ws_id, "ws_id")
+    if resource_type == "package":
+        path = f"/resources/ws/{workspace}/package/{_positive_int_segment(package_id, 'package_id')}"
+    elif resource_type == "app":
+        path = f"/resources/ws/{workspace}/app/{_identity_segment(app_key, 'app_key')}"
+    elif resource_type == "view":
+        app_segment = _identity_segment(app_key, "app_key")
+        if view_kind == "custom":
+            view_segment = _identity_segment(view_key, "view_key")
+        elif view_kind == "system":
+            name = str(view_key or "").strip()
+            if name not in SYSTEM_VIEW_NAMES:
+                raise ValueError("system view name is not supported")
+            view_segment = name
+        else:
+            raise ValueError("view_kind must be custom or system")
+        path = f"/resources/ws/{workspace}/app/{app_segment}/view/{view_kind}/{view_segment}"
+    else:
+        raise ValueError("resource_type is not supported")
+    return f"{_normalize_web_origin(web_origin) if web_origin is not None else get_web_base_url()}{path}"
+
+
+def parse_resource_path(value: str) -> ResourcePath:
+    """严格解析资源 pathname，供免登录签发前校验工作区。"""
+    try:
+        parsed = urlsplit(value)
+        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment or parsed.path != value:
+            raise ValueError
+        parts = parsed.path.split("/")
+        if len(parts) < 6 or parts[:3] != ["", "resources", "ws"]:
+            raise ValueError
+        ws_id = int(_decode_segment(parts[3], "ws_id"))
+        if ws_id <= 0:
+            raise ValueError
+        if len(parts) == 6 and parts[4] == "package":
+            package_id = int(_decode_segment(parts[5], "package_id"))
+            if package_id <= 0:
+                raise ValueError
+            return ResourcePath("package", ws_id, package_id=package_id)
+        if len(parts) == 6 and parts[4] == "app":
+            return ResourcePath("app", ws_id, app_key=_decode_segment(parts[5], "app_key"))
+        if len(parts) == 9 and parts[4] == "app" and parts[6] == "view":
+            app_key = _decode_segment(parts[5], "app_key")
+            view_kind = parts[7]
+            view_key = _decode_segment(parts[8], "view_key")
+            if view_kind == "system" and view_key not in SYSTEM_VIEW_NAMES:
+                raise ValueError
+            if view_kind not in {"custom", "system"}:
+                raise ValueError
+            return ResourcePath("view", ws_id, app_key=app_key, view_kind=view_kind, view_key=view_key)
+    except (TypeError, ValueError, UnicodeError):
+        pass
+    raise ValueError("resource path is invalid")
+
+
+def try_build_resource_uri(**kwargs: Any) -> tuple[str | None, JSONObject | None]:
+    try:
+        return build_resource_uri(**kwargs), None
+    except (QingflowApiError, ValueError, UnicodeError) as error:
+        return None, {
+            "code": "RESOURCE_URI_UNAVAILABLE",
+            "message": f"resource URI was omitted because its identity or web origin is invalid: {error}",
+        }
+
+
+def _positive_int_segment(value: object, field: str) -> str:
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be a positive integer")
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        raise ValueError(f"{field} must be a positive integer") from None
+    if parsed <= 0 or str(value).strip() != str(parsed):
+        raise ValueError(f"{field} must be a positive integer")
+    return str(parsed)
+
+
+def _normalize_web_origin(value: str) -> str:
+    try:
+        parsed = urlsplit(value.strip())
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path not in {"", "/"}
+            or parsed.query
+            or parsed.fragment
+            or any(character.isspace() or ord(character) < 32 for character in value)
+        ):
+            raise ValueError
+        _ = parsed.port
+    except (AttributeError, ValueError):
+        raise ValueError("web_origin must be an absolute HTTP(S) origin") from None
+    return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+
+
+def _identity_segment(value: object, field: str) -> str:
+    raw = _validate_identity(value, field)
+    return quote(raw, safe="")
+
+
+def _decode_segment(value: str, field: str) -> str:
+    decoded = _validate_identity(unquote(value, errors="strict"), field)
+    if quote(decoded, safe="") != value:
+        raise ValueError(f"{field} must use canonical path encoding")
+    return decoded
+
+
+def _validate_identity(value: object, field: str) -> str:
+    source = str(value or "")
+    if any(ord(character) < 32 or ord(character) == 127 for character in source):
+        raise ValueError(f"{field} must be one safe path segment")
+    raw = source.strip()
+    if not raw:
+        raise ValueError(f"{field} is required")
+    current = raw
+    for _ in range(8):
+        if (
+            current in {".", ".."}
+            or any(character in current for character in "/\\?#")
+            or any(ord(character) < 32 or ord(character) == 127 for character in current)
+        ):
+            raise ValueError(f"{field} must be one safe path segment")
+        decoded = unquote(current, errors="strict")
+        if decoded == current:
+            return raw
+        current = decoded
+    if (
+        current in {".", ".."}
+        or any(character in current for character in "/\\?#")
+        or any(ord(character) < 32 or ord(character) == 127 for character in current)
+    ):
+        raise ValueError(f"{field} must be one safe path segment")
+    if _ENCODED_OCTET.search(current):
+        raise ValueError(f"{field} has excessive encoding")
+    return raw