@qingflow-tech/qingflow-cli 1.1.43-beta.5 → 1.1.44-beta.1

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.43-beta.5
+npm install @qingflow-tech/qingflow-cli@1.1.44-beta.1
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.5 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.1 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.43-beta.5 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.1 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.43-beta.5",
+  "version": "1.1.44-beta.1",
   "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.43b5"
+version = "1.1.44b1"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -246,6 +246,10 @@ current CLI payload.
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
 | `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
 
+部门字段的 `defaultDepartments` 也遵循同一约束：`custom` 模式必须包含至少一个部门。读取历史后端数据时，如果默认部门值存在但部门列表为空，AppForm 归一化会将其视为“未配置默认部门”并省略 `defaultDepartments`；不要在新声明中写 `departments: []`。
+
+读取历史数据时，空的应用/段落/字段标题会按稳定 ID 生成兼容名称，空行和空筛选组会被忽略；选择项、子表列、序列号组件、Q-Linker 输出和代码源码等语义必需值无法安全推断时，读取会返回结构化 `UNSUPPORTED_FIELD_CONFIG`，不会伪造声明值。`validate/apply` 对新声明仍保持严格 Schema 约束。
+
 别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
 
 ### 2.1 `relation` 选择器形态

package/src/qingflow_mcp/auth_provider.py

@@ -0,0 +1,522 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Callable
+
+from .errors import QingflowApiError
+from .oauth_profile_store import OAuthProfileState, OAuthProfileStore
+from .oauth_token_store import OAuthTokenBundle, OAuthTokenStore
+from .session_store import BackendSession, SessionProfile, SessionStore
+from .cli.oauth_client import CLI_OAUTH_CLIENT_ID, CLI_OAUTH_SOURCE_CODE, OAuthClient
+
+
+OAUTH_REFRESH_SKEW = timedelta(seconds=90)
+
+
+class OAuthSessionProvider:
+    def __init__(
+        self,
+        profile_store: OAuthProfileStore,
+        token_store: OAuthTokenStore,
+        oauth_client: OAuthClient,
+    ) -> None:
+        self.profile_store = profile_store
+        self.token_store = token_store
+        self.oauth_client = oauth_client
+
+    def get_state(self, profile: str) -> OAuthProfileState | None:
+        return self.profile_store.get(profile)
+
+    def get_profile(self, profile: str, *, refresh: bool = True) -> SessionProfile:
+        state, bundle = self._resolve(profile, refresh=refresh)
+        return self._session_profile(state, token=bundle.access_token if refresh else None)
+
+    def get_backend_session(self, profile: str) -> BackendSession:
+        state, bundle = self._resolve(profile, refresh=True)
+        return BackendSession(
+            token=bundle.access_token,
+            login_token=None,
+            credential=None,
+            profile=profile,
+            base_url=state.base_url or "",
+            qf_version=state.qf_version,
+            qf_version_source=state.qf_version_source,
+        )
+
+    def activate(
+        self,
+        *,
+        profile: str,
+        base_url: str,
+        qf_version: str | None,
+        qf_version_source: str | None,
+        uid: int,
+        email: str | None,
+        nick_name: str | None,
+        selected_ws_id: int | None,
+        selected_ws_name: str | None,
+        issuer: str,
+        resource: str,
+        bundle: OAuthTokenBundle,
+    ) -> OAuthProfileState:
+        with self.profile_store.lock(profile):
+            previous_state = self.profile_store.get(profile)
+            previous_bundle = self.token_store.load(profile)
+            previous_storage = (
+                previous_state.secret_storage
+                if previous_state is not None and previous_state.active_auth_type == "oauth"
+                else None
+            )
+            storage = self.token_store.save(profile, bundle, storage=previous_storage, locked=True)
+            now = datetime.now(timezone.utc).isoformat()
+            state = OAuthProfileState(
+                active_auth_type="oauth",
+                profile=profile,
+                base_url=base_url,
+                qf_version=qf_version,
+                qf_version_source=qf_version_source,
+                uid=uid,
+                email=email,
+                nick_name=nick_name,
+                selected_ws_id=selected_ws_id,
+                selected_ws_name=selected_ws_name,
+                persisted=True,
+                secret_storage=storage,
+                issuer=issuer,
+                client_id=CLI_OAUTH_CLIENT_ID,
+                resource=resource,
+                source_code=CLI_OAUTH_SOURCE_CODE,
+                access_expires_at=bundle.access_expires_at,
+                created_at=previous_state.created_at if previous_state is not None else now,
+                updated_at=now,
+            )
+            try:
+                self.profile_store.save(state, locked=True)
+            except Exception:
+                if previous_bundle is None:
+                    self.token_store.delete(profile, locked=True)
+                else:
+                    self.token_store.save(
+                        profile,
+                        previous_bundle,
+                        storage=previous_storage,
+                        locked=True,
+                    )
+                if previous_state is None:
+                    self.profile_store.delete(profile, locked=True)
+                else:
+                    self.profile_store.save(previous_state, locked=True)
+                raise
+            return state
+
+    def refresh(self, profile: str, *, force: bool, observed_generation: int | None = None) -> bool:
+        with self.profile_store.lock(profile):
+            state = self._require_oauth_state(profile)
+            bundle = self._require_bundle(profile)
+            if observed_generation is not None and bundle.generation > observed_generation:
+                return True
+            if not force and not self._needs_refresh(bundle):
+                return True
+            metadata = self.oauth_client.discover(state.base_url or "")
+            try:
+                refreshed = self.oauth_client.refresh(
+                    metadata,
+                    refresh_token=bundle.refresh_token,
+                    generation=bundle.generation,
+                )
+            except QingflowApiError as error:
+                oauth_error = (error.details or {}).get("oauth_error")
+                failure = "invalid_grant" if oauth_error == "invalid_grant" else "uncertain_result"
+                self._invalidate_refresh_bundle(profile)
+                details = {"reason": "oauth_relogin_required", "refresh_failure": failure}
+                if oauth_error:
+                    details["oauth_error"] = oauth_error
+                raise QingflowApiError(
+                    category="auth",
+                    message=(
+                        f"OAuth session for profile '{profile}' could not be safely refreshed. "
+                        "Run auth login --method oauth again."
+                    ),
+                    backend_code=error.backend_code,
+                    request_id=error.request_id,
+                    http_status=error.http_status,
+                    details=details,
+                ) from error
+            try:
+                storage = self.token_store.save(
+                    profile,
+                    refreshed,
+                    storage=state.secret_storage,
+                    locked=True,
+                )
+                state.secret_storage = storage
+                state.access_expires_at = refreshed.access_expires_at
+                self.profile_store.save(state, locked=True)
+            except Exception as error:
+                self._invalidate_refresh_bundle(profile)
+                raise QingflowApiError(
+                    category="auth",
+                    message=(
+                        f"OAuth session for profile '{profile}' could not persist its refreshed token. "
+                        "Run auth login --method oauth again."
+                    ),
+                    details={
+                        "reason": "oauth_relogin_required",
+                        "refresh_failure": "local_persistence_failed",
+                    },
+                ) from error
+            return True
+
+    def _invalidate_refresh_bundle(self, profile: str) -> None:
+        try:
+            self.token_store.delete(profile, locked=True)
+        except QingflowApiError:
+            pass
+        self.profile_store.set_none(profile, locked=True)
+
+    def update_workspace(self, profile: str, ws_id: int, ws_name: str | None) -> SessionProfile:
+        with self.profile_store.lock(profile):
+            state = self._require_oauth_state(profile)
+            state.selected_ws_id = ws_id
+            state.selected_ws_name = ws_name
+            self.profile_store.save(state, locked=True)
+        return self.get_profile(profile, refresh=False)
+
+    def update_route(
+        self,
+        profile: str,
+        *,
+        qf_version: str | None,
+        qf_version_source: str | None,
+    ) -> SessionProfile:
+        with self.profile_store.lock(profile):
+            state = self._require_oauth_state(profile)
+            state.qf_version = _text(qf_version)
+            state.qf_version_source = _text(qf_version_source)
+            self.profile_store.save(state, locked=True)
+        return self.get_profile(profile, refresh=False)
+
+    def update_metadata(
+        self,
+        profile: str,
+        *,
+        uid: int | object,
+        email: str | None | object,
+        nick_name: str | None | object,
+        selected_ws_id: int | None | object,
+        selected_ws_name: str | None | object,
+        unset: object,
+    ) -> SessionProfile:
+        with self.profile_store.lock(profile):
+            state = self._require_oauth_state(profile)
+            if uid is not unset:
+                state.uid = int(uid)
+            if email is not unset:
+                state.email = email if isinstance(email, str) or email is None else state.email
+            if nick_name is not unset:
+                state.nick_name = nick_name if isinstance(nick_name, str) or nick_name is None else state.nick_name
+            if selected_ws_id is not unset:
+                state.selected_ws_id = (
+                    int(selected_ws_id)
+                    if isinstance(selected_ws_id, int) and not isinstance(selected_ws_id, bool)
+                    else None
+                )
+            if selected_ws_name is not unset:
+                state.selected_ws_name = (
+                    selected_ws_name
+                    if isinstance(selected_ws_name, str) or selected_ws_name is None
+                    else state.selected_ws_name
+                )
+            self.profile_store.save(state, locked=True)
+        return self.get_profile(profile, refresh=False)
+
+    def logout(self, profile: str) -> list[dict[str, str]]:
+        with self.profile_store.lock(profile):
+            state = self._require_oauth_state(profile)
+            warnings: list[dict[str, str]] = []
+            bundle = self.token_store.load(profile)
+            if bundle is not None:
+                try:
+                    self.oauth_client.revoke(state.base_url or "", bundle.refresh_token)
+                except QingflowApiError as error:
+                    warnings.append(
+                        {
+                            "code": "OAUTH_REMOTE_REVOCATION_FAILED",
+                            "message": error.message,
+                        }
+                    )
+            self.token_store.delete(profile, locked=True)
+            self.profile_store.set_none(profile, locked=True)
+        return warnings
+
+    def deactivate_for_legacy(self, profile: str) -> list[dict[str, str]]:
+        with self.profile_store.lock(profile):
+            state = self.get_state(profile)
+            if state is None:
+                return []
+            warnings: list[dict[str, str]] = []
+            if state.active_auth_type == "oauth":
+                bundle = self.token_store.load(profile)
+                if bundle is not None:
+                    try:
+                        self.oauth_client.revoke(state.base_url or "", bundle.refresh_token)
+                    except QingflowApiError as error:
+                        warnings.append(
+                            {
+                                "code": "OAUTH_REMOTE_REVOCATION_FAILED",
+                                "message": error.message,
+                            }
+                        )
+            self.token_store.delete(profile, locked=True)
+            self.profile_store.delete(profile, locked=True)
+        return warnings
+
+    def _resolve(self, profile: str, *, refresh: bool) -> tuple[OAuthProfileState, OAuthTokenBundle]:
+        state = self._require_oauth_state(profile)
+        bundle = self._require_bundle(profile)
+        if refresh and self._needs_refresh(bundle):
+            try:
+                self.refresh(profile, force=False, observed_generation=bundle.generation)
+                state = self._require_oauth_state(profile)
+                bundle = self._require_bundle(profile)
+            except QingflowApiError as error:
+                if error.category != "network" or self._is_expired(bundle):
+                    raise
+        return state, bundle
+
+    def _require_oauth_state(self, profile: str) -> OAuthProfileState:
+        state = self.get_state(profile)
+        if state is None or state.active_auth_type != "oauth":
+            raise QingflowApiError.auth_required(profile)
+        return state
+
+    def _require_bundle(self, profile: str) -> OAuthTokenBundle:
+        bundle = self.token_store.load(profile)
+        if bundle is None:
+            raise QingflowApiError(
+                category="auth",
+                message=(
+                    f"OAuth session for profile '{profile}' is missing its token bundle. "
+                    "Run auth login --method oauth again."
+                ),
+                details={"reason": "oauth_relogin_required"},
+            )
+        return bundle
+
+    def _session_profile(self, state: OAuthProfileState, *, token: str | None) -> SessionProfile:
+        return SessionProfile(
+            profile=state.profile,
+            base_url=state.base_url or "",
+            qf_version=state.qf_version,
+            qf_version_source=state.qf_version_source,
+            token=token,
+            login_token=None,
+            credential=None,
+            uid=int(state.uid or 0),
+            email=state.email,
+            nick_name=state.nick_name,
+            selected_ws_id=state.selected_ws_id,
+            selected_ws_name=state.selected_ws_name,
+            persisted=True,
+            created_at=state.created_at,
+            updated_at=state.updated_at,
+        )
+
+    def _needs_refresh(self, bundle: OAuthTokenBundle) -> bool:
+        return self._expires_at(bundle) <= datetime.now(timezone.utc) + OAUTH_REFRESH_SKEW
+
+    def _is_expired(self, bundle: OAuthTokenBundle) -> bool:
+        return self._expires_at(bundle) <= datetime.now(timezone.utc)
+
+    def _expires_at(self, bundle: OAuthTokenBundle) -> datetime:
+        try:
+            value = datetime.fromisoformat(bundle.access_expires_at)
+        except ValueError as exc:
+            raise QingflowApiError.config_error("OAuth access_expires_at is invalid.") from exc
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+
+class CliSessionFacade:
+    def __init__(self, legacy: SessionStore, oauth: OAuthSessionProvider) -> None:
+        self.legacy = legacy
+        self.oauth = oauth
+        self._pending_legacy_profiles: set[str] = set()
+
+    def set_profile_refresher(self, refresher: Callable[[str, SessionProfile | None], bool] | None) -> None:
+        self.legacy.set_profile_refresher(refresher)
+
+    def oauth_state(self, profile: str) -> str | None:
+        state = self.oauth.get_state(profile)
+        return state.active_auth_type if state is not None else None
+
+    def uses_oauth(self, profile: str) -> bool:
+        return profile not in self._pending_legacy_profiles and self.oauth_state(profile) == "oauth"
+
+    def blocks_legacy(self, profile: str) -> bool:
+        return profile not in self._pending_legacy_profiles and self.oauth_state(profile) in {"oauth", "none"}
+
+    def save_session(self, **kwargs) -> SessionProfile:  # type: ignore[no-untyped-def]
+        profile = str(kwargs.get("profile") or "")
+        oauth_state = self.oauth_state(profile)
+        saved = self.legacy.save_session(**kwargs)
+        if oauth_state in {"oauth", "none"}:
+            self._pending_legacy_profiles.add(profile)
+        return saved
+
+    def get_profile(self, profile: str) -> SessionProfile | None:
+        if profile in self._pending_legacy_profiles:
+            return self.legacy.get_profile(profile)
+        state = self.oauth_state(profile)
+        if state == "oauth":
+            return self.oauth.get_profile(profile)
+        if state == "none":
+            return None
+        return self.legacy.get_profile(profile)
+
+    def peek_profile(self, profile: str) -> SessionProfile | None:
+        if profile in self._pending_legacy_profiles:
+            return self.legacy.peek_profile(profile)
+        state = self.oauth_state(profile)
+        if state == "oauth":
+            return self.oauth.get_profile(profile, refresh=False)
+        if state == "none":
+            return None
+        return self.legacy.peek_profile(profile)
+
+    def get_backend_session(self, profile: str) -> BackendSession | None:
+        if profile in self._pending_legacy_profiles:
+            return self.legacy.get_backend_session(profile)
+        state = self.oauth_state(profile)
+        if state == "oauth":
+            return self.oauth.get_backend_session(profile)
+        if state == "none":
+            return None
+        return self.legacy.get_backend_session(profile)
+
+    def select_workspace(self, profile: str, ws_id: int, ws_name: str | None) -> SessionProfile:
+        if self.uses_oauth(profile):
+            return self.oauth.update_workspace(profile, ws_id, ws_name)
+        if self.blocks_legacy(profile):
+            raise KeyError(profile)
+        return self.legacy.select_workspace(profile, ws_id, ws_name)
+
+    def update_route(
+        self,
+        profile: str,
+        *,
+        qf_version: str | None,
+        qf_version_source: str | None,
+    ) -> SessionProfile:
+        if self.uses_oauth(profile):
+            return self.oauth.update_route(
+                profile,
+                qf_version=qf_version,
+                qf_version_source=qf_version_source,
+            )
+        if self.blocks_legacy(profile):
+            raise KeyError(profile)
+        return self.legacy.update_route(
+            profile,
+            qf_version=qf_version,
+            qf_version_source=qf_version_source,
+        )
+
+    def update_profile_metadata(self, profile: str, **kwargs) -> SessionProfile:  # type: ignore[no-untyped-def]
+        if self.uses_oauth(profile):
+            unset = object()
+            return self.oauth.update_metadata(
+                profile,
+                uid=kwargs.get("uid", unset),
+                email=kwargs.get("email", unset),
+                nick_name=kwargs.get("nick_name", unset),
+                selected_ws_id=kwargs.get("selected_ws_id", unset),
+                selected_ws_name=kwargs.get("selected_ws_name", unset),
+                unset=unset,
+            )
+        if self.blocks_legacy(profile):
+            raise KeyError(profile)
+        return self.legacy.update_profile_metadata(profile, **kwargs)
+
+    def logout(self, profile: str, forget_persisted: bool = False) -> None:
+        if self.uses_oauth(profile):
+            self.oauth.logout(profile)
+            return
+        if self.oauth_state(profile) == "none":
+            return
+        self.legacy.logout(profile, forget_persisted=forget_persisted)
+
+    def invalidate(self, profile: str) -> None:
+        if self.uses_oauth(profile):
+            self.oauth.token_store.delete(profile)
+            return
+        if self.oauth_state(profile) == "none":
+            return
+        self.legacy.invalidate(profile)
+
+    def has_profile(self, profile: str) -> bool:
+        if self.uses_oauth(profile):
+            return True
+        if self.oauth_state(profile) == "none":
+            return False
+        return self.legacy.has_profile(profile)
+
+    def activate_oauth(self, **kwargs) -> OAuthProfileState:  # type: ignore[no-untyped-def]
+        profile = str(kwargs.get("profile") or "")
+        state = self.oauth.activate(**kwargs)
+        self._pending_legacy_profiles.discard(profile)
+        return state
+
+    def complete_legacy_login(self, profile: str) -> list[dict[str, str]]:
+        warnings = self.oauth.deactivate_for_legacy(profile)
+        self._pending_legacy_profiles.discard(profile)
+        return warnings
+
+    def begin_legacy_login(self, profile: str) -> None:
+        self._pending_legacy_profiles.add(profile)
+
+    def cancel_legacy_login(self, profile: str) -> None:
+        self._pending_legacy_profiles.discard(profile)
+
+    def oauth_logout(self, profile: str) -> list[dict[str, str]]:
+        self._pending_legacy_profiles.discard(profile)
+        return self.oauth.logout(profile)
+
+    def refresh_oauth_session(self, profile: str, *, force: bool = True) -> bool:
+        if not self.uses_oauth(profile):
+            return False
+        backend = self.oauth.token_store.load(profile)
+        generation = backend.generation if backend is not None else None
+        return self.oauth.refresh(profile, force=force, observed_generation=generation)
+
+    def active_auth_type(self, profile: str) -> str:
+        if self.uses_oauth(profile):
+            return "oauth"
+        if self.oauth_state(profile) == "none":
+            return "none"
+        session_profile = self.legacy.peek_profile(profile)
+        if session_profile is None:
+            return "none"
+        return "credential" if _text(session_profile.credential) else "legacy_token"
+
+    def oauth_details(self, profile: str) -> dict[str, object]:
+        state = self.oauth.get_state(profile)
+        if state is None or state.active_auth_type != "oauth":
+            return {}
+        return {
+            "active_auth_type": "oauth",
+            "auth_source": "oauth_pkce",
+            "source_code": state.source_code,
+            "access_expires_at": state.access_expires_at,
+        }
+
+    def close(self) -> None:
+        self.oauth.oauth_client.close()
+
+
+def _text(value: object) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None