{"id":"f3af8d6a-51a7-48a7-a739-8fde84814b81","entityType":"agent","slug":"clawhub-sdk-team-alibabacloud-pai-rec-diagnosis","name":"Alibabacloud Pai Rec Diagnosis","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis","canonicalPath":"/agent/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis","generatedAt":"2026-10-11T05:38:25.883Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":null},"description":"Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur... Skill: Alibabacloud Pai Rec Diagnosis Owner: sdk-team Summary: Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur... Tags: latest:0.0.3 Version history: v0.0.3 | 2026-06-17T07:23:50.720Z | auto alibabacloud-pai-rec-diagnosis 0.0.3 - Enforces that every aliyun API command must include a unique session-based --use","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-pai-rec-diagnosis","sourceUrl":"https://clawhub.ai/sdk-team/alibabacloud-pai-rec-diagnosis","homepage":"https://clawhub.ai/sdk-team/skills/alibabacloud-pai-rec-diagnosis","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sdk-team/alibabacloud-pai-rec-diagnosis","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sdk-team/skills/alibabacloud-pai-rec-diagnosis","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":null},"stars":null,"forks":null,"downloads":1182,"packageName":null,"latestVersion":"0.0.3","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T02:51:58.733Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T02:51:58.799Z","lastCrawledAt":"2026-10-11T02:51:58.733Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T02:51:58.733Z","lastVerifiedAt":null,"highlights":[{"version":"0.0.3","createdAt":"2026-06-17T07:23:50.720Z","changelog":"alibabacloud-pai-rec-diagnosis 0.0.3 - Enforces that every `aliyun` API command must include a unique session-based `--user-agent` for observability. - Removes SKILL.md requirements for enabling or disabling \"AI-Mode\" in the workflow. - Clarifies that only published workflows may be used (e.g., forbids ad-hoc instance resource checks). - Updates documentation and references to reflect new verification steps and compliance requirements. - Removes the deprecated file `skill-card.md`.","fileCount":14,"zipByteSize":64492},{"version":"0.0.2","createdAt":"2026-05-28T06:03:17.310Z","changelog":"alibabacloud-pai-rec-diagnosis 0.0.2 - Added a new config sanitization script (scripts/sanitize_config.py) to improve configuration safety and validation. - Updated validation logic and parameter handling in scripts/validate.py. - Documentation and references updated for improved accuracy and instruction clarity. - Enhanced schema definitions to support changes in configuration workflows.","fileCount":14,"zipByteSize":60935},{"version":"0.0.1","createdAt":"2026-05-08T10:06:35.432Z","changelog":"alibabacloud-pai-rec-diagnosis v0.0.1 - Initial Release - Introduces diagnosis and configuration validation for Alibaba Cloud PAI-Rec (Programmable Recommendation System) engines. - Enables tracing of engine API errors via EAS service logs and engine configuration analysis. - Ensures strict user confirmation of cloud credentials, permissions, and all operational parameters. - Provides clear installation, authentication, and RAM policy requirements. - Specifies mandatory AI-mode enable/disable at workflow start/exit for secure Agent Skill operation.","fileCount":12,"zipByteSize":54993}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-pai-rec-diagnosis","setupComplexity":"medium","setupSteps":["Setup complexity is MEDIUM. Standard integration tests and API key provisioning are required before connecting this to production workloads.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T05:38:25.880Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-pai-rec-diagnosis/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":null},"readme":"Skill: Alibabacloud Pai Rec Diagnosis\n\nOwner: sdk-team\n\nSummary: Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur...\n\nTags: latest:0.0.3\n\nVersion history:\n\nv0.0.3 | 2026-06-17T07:23:50.720Z | auto\n\nalibabacloud-pai-rec-diagnosis 0.0.3\n\n- Enforces that every `aliyun` API command must include a unique session-based `--user-agent` for observability.\n- Removes SKILL.md requirements for enabling or disabling \"AI-Mode\" in the workflow.\n- Clarifies that only published workflows may be used (e.g., forbids ad-hoc instance resource checks).\n- Updates documentation and references to reflect new verification steps and compliance requirements.\n- Removes the deprecated file `skill-card.md`.\n\nv0.0.2 | 2026-05-28T06:03:17.310Z | auto\n\nalibabacloud-pai-rec-diagnosis 0.0.2\n\n- Added a new config sanitization script (scripts/sanitize_config.py) to improve configuration safety and validation.\n- Updated validation logic and parameter handling in scripts/validate.py.\n- Documentation and references updated for improved accuracy and instruction clarity.\n- Enhanced schema definitions to support changes in configuration workflows.\n\nv0.0.1 | 2026-05-08T10:06:35.432Z | auto\n\nalibabacloud-pai-rec-diagnosis v0.0.1 - Initial Release\n\n- Introduces diagnosis and configuration validation for Alibaba Cloud PAI-Rec (Programmable Recommendation System) engines.\n- Enables tracing of engine API errors via EAS service logs and engine configuration analysis.\n- Ensures strict user confirmation of cloud credentials, permissions, and all operational parameters.\n- Provides clear installation, authentication, and RAM policy requirements.\n- Specifies mandatory AI-mode enable/disable at workflow start/exit for secure Agent Skill operation.\n\nArchive index:\n\nArchive v0.0.3: 14 files, 64492 bytes\n\nFiles: references/acceptance-criteria.md (18146b), references/cli-installation-guide.md (11625b), references/config-validation.md (13709b), references/configuration-examples.md (14921b), references/ram-policies.md (5489b), references/related-commands.md (11662b), references/schema.json (40311b), references/troubleshooting-guide.md (18787b), references/verification-method.md (13980b), scripts/sanitize_config.py (6168b), scripts/validate.py (48701b), skill-card.md (3186b), SKILL.md (24676b), _meta.json (149b)\n\nFile v0.0.3:SKILL.md\n\n---\nname: alibabacloud-pai-rec-diagnosis\ndescription: |\n Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill.\n Use for diagnosing PAI-Rec engine interface issues and validating engine configurations.\n Triggers: \"PAI-Rec\", \"engine diagnosis\", \"engine config validation\", \"pairec\", \"recommendation engine\".\n---\n\n# PAI-Rec Engine Diagnosis and Configuration Validation\n\nThis skill provides comprehensive diagnostic and validation capabilities for Alibaba Cloud PAI-Rec (Programmable Recommendation System) engines, including interface troubleshooting and configuration analysis.\n\n## Scenario Description\n\nPAI-Rec is Alibaba Cloud's programmable recommendation system that provides intelligent recommendation capabilities. This skill helps users:\n\n1. **Diagnose PAI-Rec Engine Interface Issues**: When engine API returns errors or unexpected results, trace the request through EAS service logs and engine configurations to identify root causes.\n\n2. **Validate Engine Configurations**: Analyze engine configuration files for potential issues, inconsistencies, or misconfigurations before deployment.\n\n**Architecture**: PAI-EAS Service + PAI-Rec Engine + Engine Configuration Management\n\n### Key Components\n- **PAI-EAS Service**: Elastic Algorithm Service hosting the recommendation engine\n- **PAI-Rec Engine**: The recommendation engine processing requests\n- **Engine Configuration**: Configuration files defining engine behavior\n- **Service Logs**: EAS service logs containing request traces\n\n---\n\n## Installation\n\n**Pre-check: Aliyun CLI >= 3.3.3 required**\n> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,\n> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update,\n> or see `references/cli-installation-guide.md` for installation instructions.\n\n**Pre-check: Aliyun CLI plugin update required**\n> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.\n> [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.\n\n---\n\n## Authentication\n\n> **Pre-check: Alibaba Cloud Credentials Required**\n>\n> **Security Rules:**\n> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)\n> - **NEVER** ask the user to input AK/SK directly in the conversation or command line\n> - **NEVER** use `aliyun configure set` with literal credential values\n> - **ONLY** use `aliyun configure list` to check credential status\n>\n> ```bash\n> aliyun configure list\n> ```\n> Check the output for a valid profile (AK, STS, or OAuth identity).\n>\n> **If no valid profile exists, STOP here.**\n> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)\n> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)\n> 3. Return and re-run after `aliyun configure list` shows a valid profile\n\n---\n\n## RAM Policy\n\n> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process:\n> 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL\n> 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions\n> 3. Pause and wait until the user confirms that the required permissions have been granted\n\nFor detailed RAM policies required by this skill, see [references/ram-policies.md](references/ram-policies.md).\n\n---\n\n## Parameter Confirmation\n\n> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,\n> ALL user-customizable parameters (e.g., RegionId, service names, instance IDs,\n> environment names, config names, etc.) MUST be confirmed with the user.\n> Do NOT assume or use default values without explicit user approval.\n\n### Required Parameters\n\n| Parameter Name | Required/Optional | Description | Default Value |\n|----------------|-------------------|-------------|---------------|\n| `service-name` | Required | PAI-EAS service name | N/A |\n| `cluster-id` | Required | EAS cluster/region ID | N/A |\n| `instance-id` | Required | PAI-Rec instance ID | N/A |\n| `request-id` | Required (for diagnosis) | Request ID from engine API response | N/A |\n| `config-name` | Optional | Engine configuration name | N/A |\n| `environment` | Optional | Engine environment (Prod/Pre) | N/A |\n| `engine-config-id` | Optional | Specific engine config version ID | N/A |\n| `region` | Optional | Alibaba Cloud region | N/A |\n\n---\n\n## Observability (MUST follow for every aliyun command)\n\nUpon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as `{session-id}` below.\n\n**Rule: Every `aliyun` CLI command that calls a cloud API MUST include the `--user-agent` flag.**\nLocal utility commands (e.g. `configure`, `plugin`, `version`) do not support this flag and should be excluded.\n\n```\n--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/{session-id}\n```\n\nExample (assuming session-id is `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`):\n```bash\naliyun eas describe-service --cluster-id cn-hangzhou --service-name my_service --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\nDo not skip, alter the format, or omit `--user-agent` on any `aliyun` API command invocation.\n\n---\n\n## Core Workflow\n\n> **[MUST] Allocate a per-session work directory** — All transient artifacts\n> (raw config dumps, log dumps, sanitized output) MUST be written under a unique\n> per-session directory to avoid concurrent overwrite between parallel skill\n> invocations. Run the following at the start of the workflow, before any\n> artifact-producing CLI invocation, and reuse `$WORKDIR` for the whole session.\n> Pass the full template as a positional arg (works on both BSD/macOS and\n> GNU/Linux `mktemp`); do NOT use `-t prefix`, which falls back to `$TMPDIR`\n> (e.g. `/var/folders` on macOS) and may even fail under sandboxed shells.\n> ```bash\n> export WORKDIR=$(mktemp -d /tmp/pairec-diag-XXXXXX)\n> ```\n> All file paths shown below (`$WORKDIR/engine_configs_list.json`, etc.) live\n> inside this directory and MUST NOT be replaced with hard-coded `/tmp/...` paths.\n\n> **[MUST] Use ONLY the workflows defined below.** Do NOT invent additional\n> steps (e.g. instance resource checks, network probes) or substitute manual\n> analysis for a defined workflow step.\n\n### Workflow 1: PAI-Rec Engine Interface Diagnosis\n\nThis workflow helps diagnose issues when a PAI-Rec engine API returns errors or unexpected results.\n\n**Input Example:**\n```\nService Name: embedding_recall\nAPI Response:\n{\n \"code\": 299,\n \"msg\": \"items size not enough\",\n \"request_id\": \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\",\n \"size\": 0,\n \"experiment_id\": \"\",\n \"items\": []\n}\n```\n\n#### Step 1: Retrieve EAS Service Information\n\nGet the service details to find the EAS service ID and configuration:\n\n```bash\naliyun eas describe-service \\\n --cluster-id \\\n --service-name \n```\n\n**What to extract:**\n- `Resource`: EAS service resource ID (e.g., `eas-r-1v4qb1yan3qmnjwxqe`)\n- `ServiceConfig.envs`: Environment variables containing:\n - `REGION`: The region\n - `INSTANCE_ID`: PAI-Rec instance ID\n - `CONFIG_NAME`: Engine configuration name\n - `PAIREC_ENVIRONMENT`: Environment (product/prepub)\n\n#### Step 2: Extract Request ID from API Response\n\nParse the API response JSON to get the `request_id` field. This will be used to search service logs.\n\n#### Step 3: Query EAS Service Logs\n\nUse the request ID as the **sole** filter to search service logs. Do NOT pass `--start-time` / `--end-time` when searching PAI-Rec business logs:\n\n```bash\naliyun eas describe-service-log \\\n --cluster-id \\\n --service-name \\\n --keyword \\\n --page-size 500\n```\n\n**[CRITICAL] `--keyword ` is MANDATORY — local post-processing is FORBIDDEN:**\n- You MUST pass `--keyword ` (server-side filter, exact case-sensitive match on the full `request_id`). The API returns only log lines matching the keyword.\n- You MUST NOT omit `--keyword` and then filter locally (e.g., piping through `head`, `grep`, `python3`, `jq`, or any script).\n- You MUST NOT make multiple `describe-service-log` calls without `--keyword` hoping to find relevant lines by scanning the full log stream.\n- If a call with `--keyword` returns empty results, report that no matching logs were found — do NOT fall back to fetching unfiltered logs.\n- `--page-size` 500 captures the entire trace in a single page; matched entries for one request are usually < 30.\n\n> **❌ WRONG** (fetches ALL logs, filters locally — FORBIDDEN):\n> ```bash\n> aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall | head -300\n> aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall | grep \"request_id\"\n> ```\n>\n> **✅ RIGHT** (server-side keyword filter — REQUIRED):\n> ```bash\n> aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall --keyword 0c6cbd91-5618-4705-8e08-9126bf4600f7 --page-size 500\n> ```\n\n**[CRITICAL] Time range silently drops business logs:**\n- With `--keyword` only (no time range), the CLI returns the full PAI-Rec application trace (`controller.go` / `feed.go` / `recall.go` / `rank_service.go` etc.) matching the request_id.\n- Adding `--start-time` / `--end-time` — even when the window covers the real timestamp — silently drops business logs and returns only infrastructure noise (`/bin/sh` heartbeats, `502 Bad Gateway` retries, `postgres.go dbstat`).\n- Use time ranges only for broad scans WITHOUT `--keyword`, in `yyyy-MM-dd HH:mm:ss` UTC format (no `T` / no `Z`); ISO-8601 forms like `2025-04-28T00:00:00Z` are rejected with `InvalidParameter`.\n\n#### Step 4: List Engine Configurations\n\nMap the environment and list matching configurations:\n\n**Environment Mapping:**\n- `product` → `Prod`\n- `prepub` → `Pre`\n\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id \\\n --environment \\\n --status Released \\\n --name > \"$WORKDIR/engine_configs_list.json\" 2>&1\n```\n\n**[MUST] Always pass `--name ` for server-side filtering:**\n`` is already known from Step 1 (`ServiceConfig.envs.CONFIG_NAME`); forward it as `--name`. Omitting it returns the entire instance's config inventory (often hundreds of unrelated entries), forces client-side filtering, wastes tokens, and risks hitting CLI default pagination so the target row is silently dropped. `--name` is an exact-match filter on the server; do NOT substitute with `grep` / `jq select` post-processing. The same rule applies to every `list-engine-configs` invocation in this skill (Workflow 2 Step 1 included).\n\n**What to extract:**\n- Find the configuration with `Status: Released`\n- Get `EngineConfigId` and `Version`\n\n#### Step 5: Get Engine Configuration Details\n\n```bash\naliyun pairecservice get-engine-config \\\n --instance-id \\\n --engine-config-id > \"$WORKDIR/raw_engine_config.json\" 2>&1\n```\n\n**[MUST] Sanitize before display** — Config may contain plaintext passwords or\naccess keys. Always pipe through the sanitizer before printing to terminal;\nonly sanitized output (with credentials replaced by `***REDACTED***`) should\nappear there. The raw file at `$WORKDIR/raw_engine_config.json` can be passed\ndirectly to `scripts/validate.py` (which does not print credential values).\n\n```bash\npython3 scripts/sanitize_config.py \"$WORKDIR/raw_engine_config.json\"\n```\n\n**What to extract:**\n- `ConfigValue`: The actual engine configuration (JSON/YAML)\n\n#### Step 5.5 (Optional): Static Config Sanity Check\n\nRun `scripts/validate.py` against the retrieved `ConfigValue` to rule out structural /\nreference errors. See [references/config-validation.md](references/config-validation.md).\n\n```bash\nprintf '%s' \"$CONFIG_VALUE\" | python3 scripts/validate.py --stdin\n```\n\n**When to run:** when logs point at a config element or when diagnosing the config for the first time.\n**When to skip:** when logs show a non-config root cause (missing `scene_id`, upstream 5xx).\n**[MUST NOT]** Do not replace or duplicate `validate.py` (same restriction as Workflow 2 § Step 3).\n**[MUST] Scoping rule:** findings enter the final diagnosis ONLY when tied to log evidence for the current `request_id`.\n\n#### Step 5a (Conditional): Retrieve Experiment Configuration\n\n**Condition:** `experiment_id` in the API response is non-empty (e.g., `\"ER14_L21_L26#EG21_L38#EG38#E44_GL36_GL37\"`).\n\n**Parse:** Extract `EG{id}` (experiment group) and `E{id}` (experiment) numeric IDs from the string. Ignore `ER`, `L`, `GL` prefixes — they carry no config.\n\n```bash\n# For each EG{id}:\naliyun pairecservice get-experiment-group \\\n --instance-id \\\n --experiment-group-id > \"$WORKDIR/experiment_group_.json\" 2>&1\n# For each E{id}:\naliyun pairecservice get-experiment \\\n --instance-id \\\n --experiment-id > \"$WORKDIR/experiment_.json\" 2>&1\n```\n\n**What to extract:** The `Config` field — contains override parameters (e.g., `default.RecallNames`, `rankconf`, `filterNames`, `default.SortNames`) that supersede the base engine config.\n\n**Override priority (low → high):** Base Engine Config < ExperimentGroup.Config < Experiment.Config. Apply in Step 6 to understand actual runtime behavior.\n\n**Validate experiment configs** against the base config (reference existence check):\n\n```bash\npython3 scripts/validate.py \"$WORKDIR/raw_engine_config.json\" \\\n --experiment-config \"$WORKDIR/experiment_group_.json\" \\\n --experiment-config \"$WORKDIR/experiment_.json\"\n```\n\n#### Step 6: Comprehensive Analysis\n\nAnalyze the following components together:\n1. **API Response**: Error code, message, and returned data\n2. **Service Logs**: Trace logs for the request_id showing processing flow\n3. **Engine Configuration**: Settings that may affect the behavior\n4. **Experiment Overrides** (if `experiment_id` non-empty): Effective config = base config with experiment parameters applied on top\n\n**Common Issues to Check:**\n- Configuration mismatches (e.g., recall settings, filtering rules)\n- Experiment overrides (e.g., experiment changed `RecallNames` / `rankconf` from base config)\n- Resource limitations (e.g., insufficient items, timeout settings)\n- Data source issues (e.g., table access, feature availability)\n- Environment inconsistencies (e.g., prod config in prepub environment)\n\n**[MUST] Evidence-only reporting rule:**\n\nThe final diagnosis delivered to the user MUST be grounded strictly in what the EAS service logs and the engine configuration directly show. Apply the following constraints:\n\n- **Report only what is observed.** Quote the exact log line (file:line, level, message) and the exact config fragment that proves each claim.\n- **State the direct causal chain** from log evidence to the API response, and stop there.\n- **Do NOT add** any of the following unless the user explicitly asks:\n - Speculative root causes not visible in logs/config (e.g., \"client probably sent wrong X\")\n - Fix recommendations or remediation steps\n - Conditional \"if X then Y\" scenarios\n - Tangential best-practice advice (security, fallback design, naming, etc.)\n - Guesses about upstream systems, client code, or data sources not covered by the logs/config\n- **If the evidence is insufficient** to reach a conclusion, state explicitly what additional data (specific log lines, other config versions, other environments) is needed, instead of guessing.\n- **Recommendations are opt-in only.** Provide fixes/suggestions only when the user explicitly requests them in a follow-up.\n\n---\n\n### Workflow 2: PAI-Rec Engine Configuration Validation\n\nThis workflow validates engine configurations for potential issues.\n\n**Input:** Configuration name and environment (Prod/Pre)\n\n#### Step 1: List Configuration Versions\n\nIf user doesn't provide `engine-config-id`, list available versions:\n\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id \\\n --environment \\\n --name \n```\n\n**Display to user:**\n- `Version`: Version number\n- `Status`: Configuration status (Released/Draft/Archived)\n- `GmtCreateTime`: Creation timestamp\n- `EngineConfigId`: Version ID\n\nAsk user to select a version or provide the `engine-config-id`.\n\n#### Step 2: Retrieve Configuration Details\n\n```bash\naliyun pairecservice get-engine-config \\\n --instance-id \\\n --engine-config-id > \"$WORKDIR/raw_engine_config.json\" 2>&1\n```\n\n**[MUST] Sanitize before display** — Always sanitize before printing to terminal:\n\n```bash\npython3 scripts/sanitize_config.py \"$WORKDIR/raw_engine_config.json\"\n```\n\n#### Step 3: Run Schema + Rule Validation\n\n**[MUST]** Feed the extracted `ConfigValue` JSON into `scripts/validate.py`. The script\nenforces JSON Schema (`references/schema.json`) + reference-consistency rules and exits\nwith status 0 on pass, 1 on failure.\n\n```bash\n# From a saved JSON file (recommended)\npython3 scripts/validate.py \"$WORKDIR/raw_engine_config.json\"\n# Or pipe ConfigValue directly via stdin\nprintf '%s' \"$CONFIG_VALUE\" | python3 scripts/validate.py --stdin\n```\n\nRequires `jsonschema` (`pip install jsonschema`); if missing the script falls back to\nrule-only validation without Schema checks.\n\n**[MUST NOT] Do not replace or duplicate `validate.py`:**\n- Do NOT skip it; do NOT hand-write equivalent checks in Python / jq / grep / any other tool — the script is the authoritative validator.\n- Do NOT re-implement, re-check, or \"double-confirm\" any rule after the script has run; trust its output verbatim, including a clean `0 error(s), 0 warning(s)` run.\n- If the script cannot run (missing Python, dependency issue, etc.), fix the environment and re-run — do NOT fall back to manual checking.\n- Inspections OUTSIDE the script's scope are still allowed (see Step 4).\n\n**What the script checks (summary):**\n\n1. **Structure** — JSON well-formedness, required fields, types (`RecallConfs`,\n `FilterConfs`, `SortConfs`, `AlgoConfs`, `SceneConfs`, `RankConf`,\n `FeatureConfs`, `UserFeatureConfs`, `DebugConfs`, `FeatureLogConfs`,\n `CallBackConfs`, `PipelineConfs`, etc.)\n2. **Enum values** — `RecallType` / `FilterType` / `SortType` /\n `DebugConfs.OutputType` / `GeneralRankConfs.ActionConfs[].ActionType`\n3. **Reference consistency** — `SceneConfs.RecallNames` → `RecallConfs`;\n `FilterNames` → `FilterConfs`; `SortNames` → `SortConfs`;\n `RankConf.RankAlgoList` → `AlgoConfs`; any `DaoConf.AdapterType` +\n `*Name` → the corresponding `*Confs` (Hologres / Redis / MySQL / TableStore /\n FeatureStore / …)\n4. **Business rules**\n - `User2ItemExposureFilter` with `WriteLog=true` + FeatureStore adapter: must set\n `TimeInterval > 0`\n - `PriorityAdjustCountFilter` in `accumulator` mode: `Count` must be strictly\n increasing (use `Type=\"fix\"` for independent per-recall caps)\n - `PipelineConfs.*.Name` must be globally unique\n - `DebugConfs.Rate` must be an integer in `[0, 100]`\n5. **Duplicate name detection** within `RecallConfs`, `FilterConfs`, `SortConfs`,\n `AlgoConfs`\n\nDetailed usage, exit codes, example outputs and the full rule list live in\n[references/config-validation.md](references/config-validation.md).\n\n#### Step 4: Evidence-Grounded Report\n\n**[MUST] Required first line of the report:** Quote `validate.py`'s stdout\nverbatim — either `Validation passed: configuration is well-formed` or\n`Validation finished: N error(s), M warning(s)`. A report missing this\nexact line is INVALID; restart from Step 3.\n\n**Manual inspection is allowed only** for concerns out of scope of\n`validate.py`: env / region / model-signature mismatches, cross-version diffs,\nnaming collisions between `RankScore` variables and model output fields, and\nroot-cause reading of any `[WARNING]` the script itself asks a human to judge.\nDo NOT add findings the script did not report unless you can tie them to one\nof these out-of-scope concerns.\n\n**Report structure:**\n\n- ✅ Checks passed — quote `validate.py`'s `0 error(s), 0 warning(s)` line\n- ⚠️ Warnings — copy each `[WARNING] : ` from the script,\n plus any out-of-scope inconsistency from manual inspection\n- ❌ Errors — copy each `[ERROR] : ` from the script\n- Missing-evidence notes — ONLY when ≥1 ⚠️ warning is listed: state what extra data would upgrade that warning into a confirmed error. With 0 warnings, OMIT this section; do NOT fill it with generic out-of-scope disclaimers (cross-version diff, remote connectivity, region/endpoint consistency) — those are volunteered best-practice advice forbidden by the evidence-only rule.\n\nDo not add speculative fixes or best-practice tangents; suggestions are provided\nonly when the user explicitly asks for them.\n\n---\n\n## Success Verification Method\n\nFor detailed verification steps, see [references/verification-method.md](references/verification-method.md).\n\n**Quick Verification:**\n\n1. **For Diagnosis Workflow:**\n - Service information retrieved successfully\n - Logs found containing the request_id\n - Configuration loaded correctly\n - Root cause identified\n\n2. **For Validation Workflow:**\n - Configuration retrieved successfully\n - All validation checks executed\n - Issues clearly reported\n - Recommendations provided (if applicable)\n\n---\n\n## Cleanup\n\nThis skill performs read-only Alibaba Cloud API calls (no remote resources are\ncreated). Transient artifacts go to a per-session local `$WORKDIR` under `/tmp`\n(see Core Workflow preamble). The skill does NOT delete `$WORKDIR` automatically\n— the OS-level temp policy reclaims it (macOS reaps `/tmp` periodically; most\nLinux distros reap on reboot or via `systemd-tmpfiles`). To free disk space\nsooner, manually run `rm -rf /tmp/pairec-diag-*` outside the workflow.\n\n---\n\n## Best Practices\n\n1. **Log queries — keyword only, no time range, no local filtering**: For request-level diagnosis, pass `--keyword ` to `aliyun eas describe-service-log` and leave `--start-time` / `--end-time` unset. NEVER omit `--keyword` and post-process locally (e.g., `| head`, `| grep`, `| python3`) — this defeats server-side filtering, wastes tokens, and may miss logs beyond the first page. Combining keyword with a time range filters out business logs due to a CLI quirk (see Workflow 1, Step 3). Only use time ranges for broad non-request scans, and only with the `yyyy-MM-dd HH:mm:ss` UTC format (no `T` / no `Z`).\n2. **Trust `validate.py`**: For Workflow 2, treat `scripts/validate.py` as the single source of truth for the rules in its catalogue. Do NOT skip it and hand-write checks, and do NOT re-validate its rules manually after a clean run. Manual inspection is reserved for concerns out of its scope (env / region / model signature, cross-version diffs, `RankScore` vs model output naming).\n3. **Environment awareness**: Always verify that configurations match the target environment (Prod vs Pre); compare against a known-good version when issues persist.\n4. **Log retention**: EAS service logs are retained for limited periods; diagnose issues promptly after occurrence.\n5. **Evidence-only conclusions**: Ground every statement on a specific log line or config fragment. Follow the systematic workflow rather than jumping to conclusions from error messages alone. Do not speculate, do not propose fixes, and do not volunteer best-practice advice unless the user explicitly asks. If the evidence is insufficient, say what is missing rather than inferring.\n\n---\n\n## Reference Links\n\n| Reference Document | Description |\n|--------------------|-------------|\n| [RAM Policies](references/ram-policies.md) | Required RAM permissions for PAI-Rec and EAS APIs |\n| [Related Commands](references/related-commands.md) | Complete CLI command reference |\n| [Verification Method](references/verification-method.md) | Detailed verification procedures |\n| [CLI Installation Guide](references/cli-installation-guide.md) | Alibaba Cloud CLI installation instructions |\n| [Configuration Examples](references/configuration-examples.md) | Sample engine configurations and common patterns |\n| [Config Validation](references/config-validation.md) | `scripts/validate.py` usage, exit codes, rule catalogue |\n| [Troubleshooting Guide](references/troubleshooting-guide.md) | Common issues and solutions |\n| [Config Sanitization](scripts/sanitize_config.py) | Credential redaction before LLM analysis |\n\nFile v0.0.3:_meta.json\n\n{\n \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n \"slug\": \"alibabacloud-pai-rec-diagnosis\",\n \"version\": \"0.0.3\",\n \"publishedAt\": 1781681030720\n}\n\nFile v0.0.3:references/acceptance-criteria.md\n\n# Acceptance Criteria: alibabacloud-pai-rec-diagnosis\n\n**Scenario**: PAI-Rec Engine Diagnosis and Configuration Validation\n**Purpose**: Skill testing acceptance criteria\n\nThis document defines correct and incorrect patterns for the PAI-Rec diagnosis skill to ensure proper implementation and usage.\n\n---\n\n## Correct CLI Command Patterns\n\n### 1. Product Names — Verify product name exists\n\n#### ✅ CORRECT\n\n```bash\n# EAS product commands\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test\naliyun eas describe-service-log --cluster-id cn-hangzhou --service-name test\n\n# PAI-RecService product commands\naliyun pairecservice list-engine-configs --instance-id pairec-cn-xxxxx\naliyun pairecservice get-engine-config --instance-id pairec-cn-xxxxx --engine-config-id config-123\n```\n\n**Why correct:** Uses valid product names `eas` and `pairecservice` that exist in Aliyun CLI.\n\n#### ❌ INCORRECT\n\n```bash\n# Wrong product names\naliyun pai-eas describe-service ... # Product is 'eas', not 'pai-eas'\naliyun rec describe-service ... # Product is 'pairecservice', not 'rec'\naliyun pairec list-engine-configs ... # Product is 'pairecservice', not 'pairec'\naliyun pai list-engine-configs ... # Product is 'pairecservice', not 'pai'\n```\n\n**Why incorrect:** These product names don't exist in the Aliyun CLI.\n\n---\n\n### 2. Command Names — Verify action exists under the product\n\n#### ✅ CORRECT\n\n```bash\n# EAS commands\naliyun eas describe-service\naliyun eas describe-service-log\n\n# PAI-RecService commands\naliyun pairecservice list-engine-configs\naliyun pairecservice get-engine-config\naliyun pairecservice apply-engine-config\naliyun pairecservice create-engine-config\naliyun pairecservice get-experiment-group\naliyun pairecservice get-experiment\n```\n\n**Why correct:** All commands use lowercase words connected with hyphens (plugin mode format).\n\n#### ❌ INCORRECT\n\n```bash\n# Traditional API format (not plugin mode)\naliyun eas DescribeService # Use describe-service\naliyun eas DescribeServiceLog # Use describe-service-log\naliyun pairecservice ListEngineConfigs # Use list-engine-configs\naliyun pairecservice GetEngineConfig # Use get-engine-config\n\n# Wrong command names\naliyun eas get-service # Command is describe-service\naliyun eas list-logs # Command is describe-service-log\naliyun pairecservice get-configs # Command is list-engine-configs\naliyun pairecservice describe-config # Command is get-engine-config\n```\n\n**Why incorrect:** Must use plugin mode format (lowercase with hyphens), and exact command names.\n\n---\n\n### 3. Parameter Names — Verify each parameter exists for the command\n\n#### ✅ CORRECT - EAS describe-service\n\n```bash\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --region cn-hangzhou\n```\n\n**Parameters:**\n- `--cluster-id`: Required, the cluster ID\n- `--service-name`: Required, the service name\n- `--region`: Optional, region override\n\n#### ✅ CORRECT - EAS describe-service-log\n\n```bash\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --keyword \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\" \\\n --start-time \"2025-04-28T08:00:00Z\" \\\n --end-time \"2025-04-28T09:00:00Z\" \\\n --page-num 1 \\\n --page-size 500\n```\n\n**Parameters:**\n- `--cluster-id`: Required\n- `--service-name`: Required\n- `--keyword`: Optional, filter keyword\n- `--start-time`: Optional, UTC format\n- `--end-time`: Optional, UTC format\n- `--page-num`: Optional, default 1\n- `--page-size`: Optional, default 500\n\n#### ✅ CORRECT - PAI-RecService list-engine-configs\n\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --name my_config \\\n --status Released \\\n --version v1.2.3 \\\n --page-number 1 \\\n --page-size 20\n```\n\n**Parameters:**\n- `--instance-id`: Required\n- `--environment`: Optional, valid values: `Prod` or `Pre`\n- `--name`: Optional, config name filter\n- `--status`: Optional, e.g., `Released`, `Draft`, `Archived`\n- `--version`: Optional\n- `--page-number`: Optional\n- `--page-size`: Optional\n\n#### ✅ CORRECT - PAI-RecService get-engine-config\n\n```bash\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-12345\n```\n\n**Parameters:**\n- `--instance-id`: Required\n- `--engine-config-id`: Required\n\n#### ✅ CORRECT - PAI-RecService get-experiment-group\n\n```bash\naliyun pairecservice get-experiment-group \\\n --instance-id pairec-cn-xxxxx \\\n --experiment-group-id 21\n```\n\n**Parameters:**\n- `--instance-id`: Required\n- `--experiment-group-id`: Required, numeric ID extracted from experiment_id string (EG{id} pattern)\n\n#### ✅ CORRECT - PAI-RecService get-experiment\n\n```bash\naliyun pairecservice get-experiment \\\n --instance-id pairec-cn-xxxxx \\\n --experiment-id 44\n```\n\n**Parameters:**\n- `--instance-id`: Required\n- `--experiment-id`: Required, numeric ID extracted from experiment_id string (E{id} pattern)\n\n#### ❌ INCORRECT - Wrong parameter names\n\n```bash\n# EAS describe-service - wrong parameters\naliyun eas describe-service \\\n --cluster cn-hangzhou \\ # Use --cluster-id\n --name embedding_recall # Use --service-name\n\n# EAS describe-service-log - wrong parameters\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name test \\\n --search-keyword \"test\" \\ # Use --keyword\n --from \"2025-04-28T08:00:00Z\" \\ # Use --start-time\n --to \"2025-04-28T09:00:00Z\" \\ # Use --end-time\n --page 1 \\ # Use --page-num\n --limit 500 # Use --page-size\n\n# PAI-RecService list-engine-configs - wrong parameters\naliyun pairecservice list-engine-configs \\\n --instance pairec-cn-xxxxx \\ # Use --instance-id\n --env Prod \\ # Use --environment\n --config-name my_config \\ # Use --name\n --page 1 # Use --page-number\n\n# PAI-RecService get-engine-config - wrong parameters\naliyun pairecservice get-engine-config \\\n --instance pairec-cn-xxxxx \\ # Use --instance-id\n --config-id config-12345 # Use --engine-config-id\n\n# PAI-RecService get-experiment-group - wrong parameters\naliyun pairecservice get-experiment-group \\\n --instance pairec-cn-xxxxx \\ # Use --instance-id\n --group-id 21 # Use --experiment-group-id\n\n# PAI-RecService get-experiment - wrong parameters\naliyun pairecservice get-experiment \\\n --instance pairec-cn-xxxxx \\ # Use --instance-id\n --exp-id 44 # Use --experiment-id\n```\n\n**Why incorrect:** Parameter names must match exactly as defined in `--help` output.\n\n---\n\n### 4. Parameter Values — Verify format and enum values\n\n#### ✅ CORRECT - Environment parameter values\n\n```bash\n# Environment must be \"Prod\" or \"Pre\" (case-sensitive)\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod\n\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Pre\n```\n\n**Valid values:** `Prod`, `Pre` (capitalized)\n\n#### ❌ INCORRECT - Wrong environment values\n\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment product # Use Prod\n\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment prepub # Use Pre\n\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment prod # Use Prod (capital P)\n\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment pre # Use Pre (capital P)\n```\n\n#### ✅ CORRECT - Time format (UTC)\n\n```bash\naliyun eas describe-service-log \\\n --start-time \"2025-04-28T08:00:00Z\" \\\n --end-time \"2025-04-28T09:00:00Z\"\n```\n\n**Format:** ISO 8601 UTC format with 'Z' suffix\n\n#### ❌ INCORRECT - Wrong time formats\n\n```bash\naliyun eas describe-service-log \\\n --start-time \"2025-04-28 08:00:00\" \\ # Missing 'T' and 'Z'\n --end-time \"04/28/2025 09:00:00\" # Wrong format\n\naliyun eas describe-service-log \\\n --start-time \"2025-04-28T16:00:00+08:00\" \\ # Use UTC, not local timezone\n --end-time \"2025-04-28T17:00:00+08:00\"\n```\n\n---\n\n### 5. Per-command --user-agent (Observability)\n\n#### ✅ CORRECT\n\n```bash\n# Session-id is a 32-char lowercase hex string generated once per session\n# Every aliyun API command includes --user-agent with session-id\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\n#### ❌ INCORRECT\n\n```bash\n# Missing --user-agent flag\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test\n\n# Wrong user-agent format (missing session-id)\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis\n\n# Using quoted user-agent value (should not be quoted)\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test \\\n --user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4\"\n```\n\n---\n\n### 6. Plugin Management Commands\n\n#### ✅ CORRECT\n\n```bash\n# Enable auto plugin install\naliyun configure set --auto-plugin-install true\n\n# Update plugins\naliyun plugin update\n```\n\n#### ❌ INCORRECT\n\n```bash\n# Wrong command\naliyun plugin install --auto # Use configure set\naliyun update-plugins # Use plugin update\n```\n\n---\n\n## Correct Workflow Patterns\n\n### 1. Diagnosis Workflow\n\n#### ✅ CORRECT - Complete workflow\n\n```bash\n# 1. Session-id is a 32-char lowercase hex string generated once per session\n# Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 2. Get service information\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 3. Query service logs by request_id\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --keyword \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\" \\\n --page-size 500 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 4. List engine configs\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --status Released \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 5. Get specific config\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-12345 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\n**Why correct:**\n- Session-id is a 32-char lowercase hex string generated once per session\n- Every API command includes --user-agent (without quotes) with session-id\n- Local utility commands (configure, plugin, version) excluded\n- Logical sequence of operations\n- Proper parameter usage\n\n#### ❌ INCORRECT - Missing steps or wrong order\n\n```bash\n# Missing --user-agent (no observability)\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test\n\n# Wrong environment mapping (using \"product\" instead of \"Prod\")\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment product\n```\n\n---\n\n### 2. Configuration Validation Workflow\n\n#### ✅ CORRECT\n\n```bash\n# 1. Session-id is a 32-char lowercase hex string generated once per session\n# Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 2. List config versions (if user didn't provide ID)\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --name my_config \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 3. Get specific config for validation\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-12345 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\n#### ❌ INCORRECT\n\n```bash\n# Skipping version listing when user didn't provide ID\n# (Should list versions for user to choose)\n\n# Using wrong status filter\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --status Active # Use Released, Draft, or Archived\n```\n\n---\n\n## Correct Environment Mapping\n\n#### ✅ CORRECT\n\n| Service Environment Variable | CLI Parameter Value |\n|------------------------------|---------------------|\n| `PAIREC_ENVIRONMENT=product` | `--environment Prod` |\n| `PAIREC_ENVIRONMENT=prepub` | `--environment Pre` |\n\n```bash\n# From service config: PAIREC_ENVIRONMENT=product\n# Map to CLI parameter:\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod\n\n# From service config: PAIREC_ENVIRONMENT=prepub\n# Map to CLI parameter:\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Pre\n```\n\n#### ❌ INCORRECT\n\n```bash\n# Using service env value directly (wrong)\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment product # Should be Prod\n\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment prepub # Should be Pre\n```\n\n---\n\n## Correct Parameter Confirmation Patterns\n\n#### ✅ CORRECT - Confirm before execution\n\n```\nBefore executing, please confirm the following parameters:\n- Cluster ID: cn-hangzhou\n- Service Name: embedding_recall\n- Instance ID: pairec-cn-xxxxx\n- Environment: Prod (mapped from \"product\")\n- Time Range: 2025-04-28 08:00:00 to 09:00:00 UTC\n\nProceed? (yes/no)\n```\n\n#### ❌ INCORRECT - Using hardcoded or assumed values\n\n```bash\n# Hardcoded region without confirmation\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\ # Never assume\n --service-name embedding_recall\n\n# Assumed time range without asking user\n--start-time \"2025-04-28T00:00:00Z\" \\ # Should confirm with user\n--end-time \"2025-04-28T23:59:59Z\"\n```\n\n---\n\n## Correct Error Handling Patterns\n\n#### ✅ CORRECT - Handle errors gracefully\n\n```bash\n# Check if command succeeded\nif ! SERVICE_INFO=$(aliyun eas describe-service --cluster-id cn-hangzhou --service-name test --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 2>&1); then\n echo \"Error: Failed to retrieve service information\"\n echo \"Details: $SERVICE_INFO\"\n exit 1\nfi\n```\n\n**Why correct:** Includes --user-agent for observability and handles errors gracefully.\n\n#### ❌ INCORRECT - No error handling\n\n```bash\n# No error checking\nSERVICE_INFO=$(aliyun eas describe-service --cluster-id cn-hangzhou --service-name test)\n\n# Process results without checking if command succeeded\n# (May fail silently or with confusing errors)\n```\n\n---\n\n## Correct Time Range Patterns\n\n#### ✅ CORRECT - Appropriate time windows\n\n```bash\n# For specific issue diagnosis (±30 min to ±1 hour)\n--start-time \"2025-04-28T08:00:00Z\" \\\n--end-time \"2025-04-28T09:00:00Z\"\n\n# For pattern analysis (last 1-24 hours)\n--start-time \"2025-04-27T08:00:00Z\" \\\n--end-time \"2025-04-28T08:00:00Z\"\n\n# For recent issues (last hour)\nSTART_TIME=$(date -u -d '1 hour ago' '+%Y-%m-%dT%H:%M:%SZ')\nEND_TIME=$(date -u '+%Y-%m-%dT%H:%M:%SZ')\n```\n\n#### ❌ INCORRECT - Inappropriate time windows\n\n```bash\n# Too broad (entire year - too many logs)\n--start-time \"2025-01-01T00:00:00Z\" \\\n--end-time \"2025-12-31T23:59:59Z\"\n\n# Too narrow (1 minute - may miss logs)\n--start-time \"2025-04-28T08:15:00Z\" \\\n--end-time \"2025-04-28T08:16:00Z\"\n\n# Wrong timezone (not UTC)\n--start-time \"2025-04-28T16:00:00+08:00\"\n```\n\n---\n\n## Verification Patterns\n\n#### ✅ CORRECT - Verify results\n\n```bash\n# Check if service info contains required fields\nif echo \"$SERVICE_INFO\" | jq -e '.Resource' > /dev/null; then\n echo \"✅ Service info retrieved successfully\"\nelse\n echo \"❌ Failed to get service resource ID\"\nfi\n\n# Check if logs found\nLOG_COUNT=$(echo \"$LOGS\" | jq -r '.TotalCount // 0')\nif [ \"$LOG_COUNT\" -gt 0 ]; then\n echo \"✅ Found $LOG_COUNT log entries\"\nelse\n echo \"❌ No logs found for request_id\"\nfi\n\n# Check if configs exist\nCONFIG_COUNT=$(echo \"$CONFIGS\" | jq -r '.EngineConfigs | length')\nif [ \"$CONFIG_COUNT\" -gt 0 ]; then\n echo \"✅ Found $CONFIG_COUNT configurations\"\nelse\n echo \"❌ No configurations found\"\nfi\n```\n\n#### ❌ INCORRECT - No verification\n\n```bash\n# Assume commands always succeed\nSERVICE_INFO=$(aliyun eas describe-service ...)\n# Process without checking if result is valid\n\n# No check if logs/configs found\n# May process empty results\n```\n\n---\n\n## Summary Checklist\n\n### CLI Commands\n- [ ] Use correct product names: `eas`, `pairecservice`\n- [ ] Use plugin mode format: lowercase with hyphens\n- [ ] Use exact parameter names from `--help`\n- [ ] Use correct enum values (e.g., `Prod`/`Pre`, not `product`/`prepub`)\n- [ ] Use UTC time format: `YYYY-MM-DDTHH:MM:SSZ`\n\n### Workflow\n- [ ] Generate session-id (32-char lowercase hex) at start\n- [ ] Include `--user-agent` on every `aliyun` API command\n- [ ] Exclude `--user-agent` from local utility commands (configure, plugin, version)\n- [ ] Confirm parameters with user before execution\n- [ ] Execute commands in logical order\n\n### Environment Mapping\n- [ ] Map `product` → `Prod`\n- [ ] Map `prepub` → `Pre`\n\n### Error Handling\n- [ ] Check command success\n- [ ] Handle errors gracefully\n\n### Verification\n- [ ] Verify command results\n- [ ] Check required fields present\n- [ ] Validate data formats\n- [ ] Confirm counts when listing\n\n---\n\n## Related Documentation\n\n- [Related Commands](related-commands.md) - Full CLI command reference\n- [Verification Method](verification-method.md) - Detailed verification steps\n- [Troubleshooting Guide](troubleshooting-guide.md) - Common issues and solutions\n\nFile v0.0.3:references/cli-installation-guide.md\n\n# Aliyun CLI Installation & Configuration Guide\n\nComplete guide for installing and configuring Aliyun CLI.\n\n> **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.\n\n## Installation\n\n### macOS\n\n**Using Homebrew (Recommended)**\n```bash\nbrew install aliyun-cli\n# Upgrade to latest\nbrew upgrade aliyun-cli\n\n# Verify version (>= 3.3.3)\naliyun version\n```\n\n**Using Binary**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz\n\n# Extract\ntar -xzf aliyun-cli-macosx-latest-amd64.tgz\n\n# Move to PATH\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n### Linux\n\n**Debian/Ubuntu**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-amd64.tgz\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n**CentOS/RHEL**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-amd64.tgz\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n**ARM64 Architecture**\n```bash\n# Download ARM64 version\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-arm64.tgz\nsudo mv aliyun /usr/local/bin/\n```\n\n### Windows\n\n**Using Binary**\n1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip\n2. Extract the ZIP file\n3. Add the directory to your PATH environment variable\n4. Open new Command Prompt or PowerShell\n5. Verify: `aliyun version`\n\n**Using PowerShell**\n```powershell\n# Download\nInvoke-WebRequest -Uri \"https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip\" -OutFile \"aliyun-cli.zip\"\n\n# Extract\nExpand-Archive -Path aliyun-cli.zip -DestinationPath C:\\aliyun-cli\n\n# Add to PATH (requires admin privileges)\n$env:Path += \";C:\\aliyun-cli\"\n[Environment]::SetEnvironmentVariable(\"Path\", $env:Path, [System.EnvironmentVariableTarget]::Machine)\n\n# Verify\naliyun version\n```\n\n## Configuration\n\n### Quick Start\n\n```bash\naliyun configure set \\\n --mode AK \\\n --access-key-id \\\n --access-key-secret \\\n --region cn-hangzhou\n```\n\nAll `aliyun configure` commands support non-interactive flags, which is the recommended approach —\nit works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.\n\n**Where to Get Access Keys**\n\n1. Log in to Aliyun Console: https://ram.console.aliyun.com/\n2. Navigate to: AccessKey Management\n3. Create a new AccessKey pair\n4. Save the secret immediately — it's only shown once\n\n### Configuration Modes\n\nAliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.\n\n#### 1. AK Mode (Access Key)\n\nMost common mode for personal accounts and scripts.\n\n```bash\naliyun configure set \\\n --mode AK \\\n --access-key-id LTAI5tXXXXXXXX \\\n --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \\\n --region cn-hangzhou\n```\n\nConfiguration is stored in `~/.aliyun/config.json`:\n\n```json\n{\n \"current\": \"default\",\n \"profiles\": [\n {\n \"name\": \"default\",\n \"mode\": \"AK\",\n \"access_key_id\": \"LTAI5tXXXXXXXX\",\n \"access_key_secret\": \"8dXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"region_id\": \"cn-hangzhou\",\n \"output_format\": \"json\",\n \"language\": \"en\"\n }\n ]\n}\n```\n\n#### 2. StsToken Mode (Temporary Credentials)\n\nFor short-lived access (tokens expire in 1-12 hours).\n\n```bash\naliyun configure set \\\n --mode StsToken \\\n --access-key-id LTAI5tXXXXXXXX \\\n --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \\\n --sts-token v1.0:XXXXXXXXXXXXXXXX \\\n --region cn-hangzhou\n```\n\nUse cases: CI/CD pipelines, temporary access for external contractors, cross-account access.\n\n#### 3. RamRoleArn Mode (Assume RAM Role)\n\nAssume a RAM role for elevated or cross-account access.\n\n```bash\naliyun configure set \\\n --mode RamRoleArn \\\n --access-key-id LTAI5tXXXXXXXX \\\n --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \\\n --ram-role-arn acs:ram::123456789012:role/AdminRole \\\n --role-session-name my-session \\\n --region cn-hangzhou\n```\n\nUse cases: cross-account resource access, temporary elevated privileges, role-based access control.\n\n#### 4. EcsRamRole Mode (ECS Instance RAM Role)\n\nUse the RAM role attached to an ECS instance — no credentials needed.\n\n```bash\naliyun configure set \\\n --mode EcsRamRole \\\n --ram-role-name MyEcsRole \\\n --region cn-hangzhou\n```\n\nRequirements: must be running on an ECS instance with a RAM role attached.\n\nUse cases: scripts and automation running on ECS instances.\n\n#### 5. RsaKeyPair Mode (RSA Key Pair)\n\nUse RSA key pair for authentication (generate key pair in Aliyun Console first).\n\n```bash\naliyun configure set \\\n --mode RsaKeyPair \\\n --private-key /path/to/private-key.pem \\\n --key-pair-name my-key-pair \\\n --region cn-hangzhou\n```\n\n#### 6. RamRoleArnWithEcs Mode (ECS + RAM Role)\n\nCombine ECS instance role with RAM role assumption for cross-account access from ECS.\n\n```bash\naliyun configure set \\\n --mode RamRoleArnWithEcs \\\n --ram-role-name MyEcsRole \\\n --ram-role-arn acs:ram::123456789012:role/TargetRole \\\n --role-session-name my-session \\\n --region cn-hangzhou\n```\n\n### Environment Variables\n\n**Highest priority** - overrides config file\n\n**Access Key Mode**\n```bash\nexport ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id\nexport ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret\nexport ALIBABA_CLOUD_REGION_ID=cn-hangzhou\n```\n\n**STS Token Mode**\n```bash\nexport ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id\nexport ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret\nexport ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token\nexport ALIBABA_CLOUD_REGION_ID=cn-hangzhou\n```\n\n**ECS RAM Role Mode**\n```bash\nexport ALIBABA_CLOUD_ECS_METADATA=role_name\n```\n\n**Use Case**:\n- CI/CD pipelines\n- Docker containers\n- Temporary credential override\n\n### Managing Multiple Profiles\n\n**Create Named Profiles**\n\n```bash\naliyun configure set --profile projectA \\\n --mode AK \\\n --access-key-id LTAI5tAAAAAAAA \\\n --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \\\n --region cn-hangzhou\n\naliyun configure set --profile projectB \\\n --mode AK \\\n --access-key-id LTAI5tBBBBBBBB \\\n --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \\\n --region cn-shanghai\n```\n\n**Use Specific Profile**\n\n```bash\naliyun ecs describe-instances --profile projectA\n\nexport ALIBABA_CLOUD_PROFILE=projectA\naliyun ecs describe-instances # Uses projectA\n```\n\n**List and Switch Profiles**\n\n```bash\naliyun configure list # List all profiles\naliyun configure set --current projectA # Switch default profile\n```\n\n### Credential Priority\n\nCredentials are loaded in this order (first found wins):\n\n1. **Command-line flag**: `--profile `\n2. **Environment variable**: `ALIBABA_CLOUD_PROFILE`\n3. **Environment credentials**: `ALIBABA_CLOUD_ACCESS_KEY_ID`, etc.\n4. **Configuration file**: `~/.aliyun/config.json` (current profile)\n5. **ECS Instance RAM Role**: If running on ECS with attached role\n\n## Verification\n\n### Test Authentication\n\n```bash\n# Basic test - list regions\naliyun ecs describe-regions\n\n# Expected output: JSON array of regions\n```\n\n**If successful**, you'll see:\n```json\n{\n \"Regions\": {\n \"Region\": [\n {\n \"RegionId\": \"cn-hangzhou\",\n \"RegionEndpoint\": \"ecs.cn-hangzhou.aliyuncs.com\",\n \"LocalName\": \"East China 1 (Hangzhou)\"\n },\n ...\n ]\n },\n \"RequestId\": \"...\"\n}\n```\n\n**If failed**, you'll see error messages:\n- `InvalidAccessKeyId.NotFound` - Wrong Access Key ID\n- `SignatureDoesNotMatch` - Wrong Access Key Secret\n- `InvalidSecurityToken.Expired` - STS token expired (for StsToken mode)\n- `Forbidden.RAM` - Insufficient permissions\n\n### Debug Configuration\n\n```bash\n# Show current configuration\naliyun configure get\n\n# Test with debug logging\naliyun ecs describe-regions --log-level=debug\n\n# Check credential provider\naliyun configure get mode\n```\n\n## Security Best Practices\n\n### 1. Use RAM Users (Not Root Account)\n\n❌ **Don't**: Use Aliyun root account credentials\n✅ **Do**: Create RAM users with specific permissions\n\n```bash\n# Create RAM user in console\n# Attach only necessary policies\n# Use RAM user's access keys\n```\n\n### 2. Principle of Least Privilege\n\nGrant only the minimum permissions needed:\n\n```bash\n# Example: Read-only ECS access\n# Attach policy: AliyunECSReadOnlyAccess\n```\n\n### 3. Rotate Access Keys Regularly\n\n```bash\n# Create new access key in RAM Console, then update configuration\naliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET\n# Delete old access key from console\n```\n\n### 4. Use STS Tokens for Temporary Access\n\n```bash\naliyun configure set --mode StsToken \\\n --access-key-id XXXX --access-key-secret XXXX \\\n --sts-token XXXX --region cn-hangzhou\n```\n\n### 5. Use ECS RAM Roles When Possible\n\n```bash\naliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou\n```\n\n### 6. Never Commit Credentials\n\n```bash\n# Add to .gitignore\necho \"~/.aliyun/config.json\" >> .gitignore\n\n# Use environment variables in CI/CD instead\n```\n\n### 7. Secure Config File\n\n```bash\n# Restrict permissions\nchmod 600 ~/.aliyun/config.json\n```\n\n## Troubleshooting\n\n### Issue: Command Not Found\n\n```bash\n# Check installation\nwhich aliyun\n\n# Check PATH\necho $PATH\n\n# Reinstall or add to PATH\n```\n\n### Issue: Authentication Failed\n\n```bash\n# Verify configuration\naliyun configure get\n\n# Test with debug\naliyun ecs describe-regions --log-level=debug\n\n# Check credentials in console\n# Verify access key is active\n```\n\n### Issue: Permission Denied\n\n```bash\n# Error: Forbidden.RAM\n\n# Check RAM user permissions\n# Attach necessary policies in RAM console\n# Example: AliyunECSFullAccess for ECS operations\n```\n\n### Issue: STS Token Expired\n\n```bash\n# Error: InvalidSecurityToken.Expired\n\n# Reconfigure with new token\naliyun configure set --mode StsToken \\\n --access-key-id XXXX --access-key-secret XXXX \\\n --sts-token NEW_TOKEN --region cn-hangzhou\n```\n\n### Issue: Wrong Region\n\n```bash\n# Some resources may not exist in the specified region\n\n# Check available regions\naliyun ecs describe-regions\n\n# Update default region\naliyun configure set region cn-shanghai\n```\n\n## Advanced Configuration\n\n### Custom Endpoint\n\n```bash\n# Use custom or private endpoint\nexport ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com\n```\n\n### Proxy Settings\n\n```bash\n# HTTP proxy\nexport HTTP_PROXY=http://proxy.example.com:8080\nexport HTTPS_PROXY=http://proxy.example.com:8080\n\n# No proxy for specific domains\nexport NO_PROXY=localhost,127.0.0.1,.aliyuncs.com\n```\n\n### Timeout Settings\n\n```bash\n# Connection timeout (default: 10s)\nexport ALIBABA_CLOUD_CONNECT_TIMEOUT=30\n\n# Read timeout (default: 10s)\nexport ALIBABA_CLOUD_READ_TIMEOUT=30\n```\n\n## Next Steps\n\nAfter installation and configuration:\n\n1. **Install plugins** for services you need (v3.3.3+ supports all published product plugins):\n ```bash\n aliyun plugin install --names ecs vpc rds\n\n # List all available plugins\n aliyun plugin list-remote\n ```\n\n2. **Explore commands**:\n ```bash\n aliyun ecs --help\n aliyun fc --help\n ```\n\n3. **Read documentation**:\n - [Command Syntax Guide](./command-syntax.md)\n - [Global Flags Reference](./global-flags.md)\n - [Common Scenarios](./common-scenarios.md)\n\n## References\n\n- Official Documentation: https://help.aliyun.com/zh/cli/\n- RAM Console: https://ram.console.aliyun.com/\n- Access Key Management: https://ram.console.aliyun.com/manage/ak\n- Plugin Repository: https://github.com/aliyun/aliyun-cli\n\nFile v0.0.3:references/config-validation.md\n\n# PAI-Rec Engine Configuration Validation\n\nReference for `scripts/validate.py` — the JSON Schema + rule-based validator used by\nWorkflow 2 (Engine Configuration Validation) in `SKILL.md`.\n\n---\n\n## 1. Files\n\n| Path | Purpose |\n|------|---------|\n| `scripts/validate.py` | Validator entry point (CLI + library). Loads a bundled JSON Schema (Draft-7) that describes the top-level engine-config structure. |\n\nAll files live inside this skill — no external skill dependency.\n\n---\n\n## 2. Dependencies\n\n- Python 3.8+\n- `jsonschema` >=4.0,<5.0 (optional but recommended):\n ```bash\n pip install \"jsonschema>=4.0,<5.0\"\n ```\n If `jsonschema` is not installed the script **still runs** but skips Schema checks\n and relies on the built-in rule validator only. A single warning-equivalent note\n is NOT emitted in this case, so install `jsonschema` for full coverage.\n\n---\n\n## 3. CLI Usage\n\n```bash\n# From a saved JSON file\npython3 scripts/validate.py /tmp/engine-config.json\n\n# Inline JSON string\npython3 scripts/validate.py '{\"RunMode\":\"product\",\"RecallConfs\":[...]}'\n\n# From stdin (recommended when ConfigValue is already in a shell variable)\nprintf '%s' \"$CONFIG_VALUE\" | python3 scripts/validate.py --stdin\n\n# Validate with experiment configs (reference-existence check)\npython3 scripts/validate.py /tmp/raw_engine_config.json \\\n --experiment-config /tmp/experiment_group_21.json \\\n --experiment-config /tmp/experiment_44.json\n```\n\n### Exit codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Validation passed (no errors; warnings may still be printed). |\n| `1` | Validation failed (at least one `error`-severity finding). |\n| `2` | Input error — argument is not a readable file, not valid JSON, or stdin decode failed. |\n\n### Output format\n\n```\nValidation finished: error(s), warning(s)\n\n [ERROR] : \n [WARNING] : \n ...\n```\n\n`` uses dotted / bracketed notation, e.g.\n`RecallConfs[3]`, `SceneConfs.default.default.RecallNames[1]`,\n`FilterConfs[0].DaoConf`.\n\n### Fragment auto-wrapping\n\nIf the input is a single fragment (object containing `RecallType`, `FilterType`, or\n`SortType` at the top level) and the corresponding `*Confs` array is missing, the\nscript automatically wraps it into `{ \"s\": [ ] }` before\nvalidation. This lets you validate one recall / filter / sort entry in isolation.\n\n---\n\n## 4. Library Usage\n\n```python\nfrom scripts.validate import validate_config, ValidationError\n\nerrors: list[ValidationError] = validate_config(config_dict, use_schema=True)\nfor e in errors:\n print(e.severity, e.path, e.message)\n```\n\n`ValidationError` fields: `path`, `message`, `severity` (`\"error\"` | `\"warning\"`).\n\n---\n\n## 5. Rule Catalogue\n\n### 5.1 Structural / Type checks (JSON Schema)\n\nEnforced by the bundled JSON Schema (Draft-7) via `jsonschema.Draft7Validator`. Covers:\n\n- Top-level keys: `RunMode`, `ListenConf`, `RecallConfs`, `FilterConfs`,\n `SortConfs`, `AlgoConfs`, `SceneConfs`, `FilterNames`, `SortNames`, `RankConf`,\n `GeneralRankConfs`, `FeatureConfs`, `UserFeatureConfs`, `DebugConfs`,\n `FeatureLogConfs`, `CallBackConfs`, `PipelineConfs`, `HologresConfs`,\n `RedisConfs`, `MysqlConfs`, `TableStoreConfs`, `FeatureStoreConfs`,\n `ClickHouseConfs`, `GraphConfs`, `LindormConfs`, `RecallEngineConfs`, …\n- Required fields and primitive types for every nested object.\n- Enumerations for `AdapterType`, operation modes, etc. where representable in\n JSON Schema.\n\n### 5.2 Enum validation (rule-based)\n\n| Field | Allowed values |\n|-------|----------------|\n| `RunMode` | `daily`, `prepub`, `product` |\n| `RecallConfs[*].RecallType` | `UserCollaborativeFilterRecall`, `UserTopicRecall`, `VectorRecall`, `UserCustomRecall`, `HologresVectorRecall`, `ItemCollaborativeFilterRecall`, `UserGroupHotRecall`, `UserGlobalHotRecall`, `I2IVectorRecall`, `ColdStartRecall`, `MilvusVectorRecall`, `RealTimeU2IRecall`, `OnlineHologresVectorRecall`, `OnlineVectorRecall`, `GraphRecall`, `MockRecall`, `RecallEngineRecall` |\n| `FilterConfs[*].FilterType` | `User2ItemExposureFilter`, `User2ItemCustomFilter`, `AdjustCountFilter`, `PriorityAdjustCountFilter`, `PriorityAdjustCountFilterV2`, `ItemStateFilter`, `ItemCustomFilter`, `CompletelyFairFilter`, `GroupWeightCountFilter`, `DimensionFieldUniqueFilter`, `User2ItemExposureWithConditionFilter`, `ConditionFilter`, `DiversityAdjustCountFilter`, `SnakeFilter`, `UniqueFilter` |\n| `SortConfs[*].SortType` | `ItemRankScore`, `BoostScoreSort`, `BoostScoreByWeight`, `DiversityRuleSort`, `DPPSort`, `SSDSort`, `AlgoScoreSort`, `TrafficControlSort`, `MultiRecallMixSort`, `DistinctIdSort`, `CustomFieldSort`, `ConditionSort` |\n| `AlgoConfs[*].EasConf.ResponseFuncName` | Must match one of the response funcs registered in `pairec/algorithm/eas/client.go` `SetResponseFunc()`: `pssmartResponseFunc`, `tfResponseFunc`, `alinkFMResponseFunc`, `tfMutValResponseFunc`, `easyrecResponseFunc`, `easyrecResponseFuncDebug`, `easyrecMutValResponseFunc`, `easyrecMutValResponseFuncDebug`, `easyrecMutClassificationResponseFunc`, `easyrecMutClassificationResponseFuncDebug`, `easyrecUserEmbResponseFunc`, `easyrecUserRealtimeEmbeddingResponseFunc`, `easyrecUserRealtimeEmbeddingMindResponseFunc`, `tfServingResponseFunc`, `torchrecMutValResponseFunc`, `torchrecMutValResponseFuncDebug`, `torchrecEmbeddingResponseFunc`, `torchrecEmbeddingItemsResponseFunc`, `torchrecEmbeddingItemsResponseFuncDebug`, `tfUseEmbResponseFunc`, `torchrecMutClassificationResponseFunc`, `torchrecMutClassificationResponseFuncDebug` |\n| `DebugConfs.OutputType` | Validated; `Rate` must be an integer in `[0, 100]`. |\n| `GeneralRankConfs.*.ActionConfs[*].ActionType` | Validated against supported action types. |\n\n### 5.2a Built-in recall instance names\n\n`SceneConfs...RecallNames[]` may reference the following\nbuilt-in recall instances that are implemented inside the engine and do NOT\nneed to appear in `RecallConfs`:\n\n| Name | Source |\n|------|--------|\n| `ContextItemRecall` | Engine built-in — reads item list from the request context. |\n\n### 5.2b Built-in sort (rerank) instance names\n\n`SceneConfs...SortNames[]` (and the top-level `SortNames[]`)\nmay reference the following built-in sort instances that are implemented\ninside the engine and do NOT need to appear in `SortConfs`. The validator\ntreats these names as pre-defined and will not emit an \"undefined sort name\"\nerror when they are referenced:\n\n| Name | Source |\n|------|--------|\n| `ItemRankScore` | Engine built-in rerank module — sorts items in descending order by the `RankScore` produced by `RankConf` (scoring algorithms listed in `RankAlgoList`). See the Aliyun PAI-Rec [Rerank Configuration](https://help.aliyun.com/zh/airec/what-is-pai-rec/user-guide/rearrange-configuration) docs. |\n\nNote: if a `SortConfs[*]` entry is defined with `SortType: ItemRankScore`, the\nenum check in §5.2 still applies; the built-in name above covers the case\nwhere `ItemRankScore` is referenced directly in `SortNames[]` without any\n`SortConfs` definition.\n\n### 5.3 Required-field checks\n\n- `RecallConfs[*]`: `Name`, `RecallType`, `RecallCount` (positive integer).\n- `FilterConfs[*]`: `Name`, `FilterType`.\n- `SortConfs[*]`: `Name`, `SortType`.\n- `AlgoConfs[*]`: `Name`, `Type`.\n- Data-source adapter blocks (`HologresConfs[*]`, `RedisConfs[*]`, …): connection\n identifiers required by Schema.\n\n### 5.4 Reference-consistency (cross-section)\n\nThe validator resolves every name reference and reports errors when a referenced\nentity is not defined:\n\n| Referencing location | Must resolve to |\n|----------------------|-----------------|\n| `SceneConfs...RecallNames[]` | `RecallConfs[*].Name` |\n| `SceneConfs...FilterNames[]` and top-level `FilterNames[]` | `FilterConfs[*].Name` |\n| `SceneConfs...SortNames[]` and top-level `SortNames[]` → each entry's `Name` | `SortConfs[*].Name` |\n| `RankConf..RankAlgoList[]` | `AlgoConfs[*].Name` |\n| `RankConf..ContextFeatures[*].FeatureName` | `FeatureConfs..FeatureLoadConfs[*]` outputs (when present) |\n| `FeatureConfs..FeatureLoadConfs[*].FeatureDaoConf.` + `*Name` | Matching `*Confs` block (see 5.5) |\n| `UserFeatureConfs..FeatureLoadConfs[*].FeatureDaoConf` | Same as above. |\n| `RecallConfs[*].DaoConf` / `FilterConfs[*].DaoConf` | Matching `*Confs` block. |\n| `FeatureLogConfs`, `CallBackConfs`, `PipelineConfs` `*.DaoConf` | Matching `*Confs` block. |\n\n### 5.5 Data-source adapter mapping\n\n`DaoConf.AdapterType` (case-insensitive) is mapped to the top-level confs key\nholding the connection definition; the `*Name` field inside `DaoConf` must match\nan entry there:\n\n| `AdapterType` | Top-level confs key |\n|---------------|---------------------|\n| `hologres` | `HologresConfs` |\n| `redis` | `RedisConfs` |\n| `mysql` | `MysqlConfs` |\n| `tablestore` | `TableStoreConfs` |\n| `featurestore`| `FeatureStoreConfs` |\n| `clickhouse` | `ClickHouseConfs` |\n| `graph` | `GraphConfs` |\n| `lindorm` | `LindormConfs` |\n| `recallengine`| `RecallEngineConfs` |\n\nAny other `AdapterType` is flagged as invalid.\n\n### 5.6 Business rules\n\n- **`User2ItemExposureFilter` + FeatureStore pseudo-exposure**\n When `WriteLog == true` and `DaoConf.AdapterType == \"featurestore\"`,\n `TimeInterval` is required and must be a **positive integer** (seconds).\n Missing or non-positive values are flagged as errors.\n\n- **`PriorityAdjustCountFilter` accumulator mode**\n Inside `AdjustCountConfs[*]`, for entries with `Type == \"accumulator\"`\n (the default), the sequence of `Count` values must be **strictly increasing**.\n A non-increasing pair emits a `warning` with a hint that\n `Type = \"fix\"` should be used for independent per-recall caps. Reported once\n per filter to avoid duplicates.\n\n- **`PipelineConfs[*].Name` uniqueness**\n All pipeline names must be globally unique across `PipelineConfs`.\n\n- **`DebugConfs.Rate`**\n Must be an integer in `[0, 100]` (inclusive). Values outside this range or of\n non-integer types are errors.\n\n### 5.7 Duplicate-name detection\n\nWithin each of `RecallConfs`, `FilterConfs`, `SortConfs`, `AlgoConfs` the `Name`\nfield must be unique; duplicates yield errors at the later occurrence.\n\n---\n\n## 6. How the Skill Uses the Validator\n\nWorkflow 2 (SKILL.md §\"Workflow 2\") runs the following sequence after fetching\nthe configuration from `pairecservice get-engine-config`:\n\n1. Extract the `ConfigValue` string from the API response.\n2. Pipe it to `python3 scripts/validate.py --stdin`.\n3. Capture stdout + exit code.\n4. Translate the output into the evidence-grounded ✅ / ⚠️ / ❌ report defined in\n SKILL.md §\"Workflow 2 / Step 4\". Every ⚠️ / ❌ line MUST quote the exact\n `[SEVERITY] path: message` produced by the script (or the exact JSON fragment\n of `ConfigValue` for findings that come from manual inspection outside the\n script's rule set).\n\n---\n\n## 7. Experiment Config Validation\n\nWhen `--experiment-config ` is passed, the script validates experiment\noverride parameters against the base engine config.\n\n### Recognized predefined keys\n\n| Key pattern | Override target | Value type |\n|------------|----------------|------------|\n| `{cat}.RecallNames` | Scene recall list | `string[]` |\n| `filterNames` | Filter chain | `string[]` |\n| `{cat}.SortNames` | Sort/rerank list | `string[]` |\n| `rankconf` | RankConf (fine-rank) | `object` |\n| `rankscore` | RankScore expression | `string` |\n| `sort.{SortName}` | Override specific sort config | (any) |\n| `recall.{RecallName}` | Override specific recall config | (any) |\n| `generalRankConf` | GeneralRankConf (coarse-rank) | `object` |\n| `features.scene.name` / `user_features.scene.name` | Feature scene | `string` |\n| `pid_task_params` / `pid_target_params` | Traffic control PID | `object` |\n\nKeys not matching any pattern above are treated as **user-defined custom\nparameters** and skipped without error.\n\n### Validation rules\n\n1. **Type check** — predefined keys must have the expected value type.\n2. **Reference existence** — names in list-type keys must exist in the\n corresponding base config section:\n - `{cat}.RecallNames` values → `RecallConfs[].Name` (exception: `ContextItemRecall`)\n - `filterNames` values → `FilterConfs[].Name` (exception: `UniqueFilter`)\n - `{cat}.SortNames` values → `SortConfs[].Name` (exception: `ItemRankScore`)\n - `rankconf.RankAlgoList` values → `AlgoConfs[].Name`\n - `sort.{X}` → X must exist in `SortConfs[].Name`\n - `recall.{X}` → X must exist in `RecallConfs[].Name`\n\n### Auto-detection\n\nThe script auto-detects the API response wrapper:\n- Base config file: if it contains a `ConfigValue` string field, that field is\n parsed as the actual engine config.\n- Experiment file: the `Config` string field is parsed as the experiment\n parameters JSON.\n\n---\n\n## 8. Extending the Validator\n\nWhen adding new rules:\n\n1. Prefer expressing structural constraints in the bundled JSON Schema (Draft-7).\n2. Put cross-section / business-logic rules in\n `PairecConfigValidator._validate_*` methods of `scripts/validate.py`.\n3. Keep `ValidationError.severity` aligned with real impact:\n - `error` — config will break at runtime or is definitely invalid.\n - `warning` — likely misconfiguration that has a legitimate alternative.\n4. Add/extend the enum sets (`VALID_RECALL_TYPES`, `VALID_FILTER_TYPES`,\n `VALID_SORT_TYPES`, `VALID_RESPONSE_FUNC_NAMES`, `BUILTIN_RECALL_NAMES`,\n `DATASOURCE_ADAPTER_MAP`) at the top of `validate.py` when new types are\n supported. For `VALID_RESPONSE_FUNC_NAMES`, keep in sync with upstream\n `pairec/algorithm/eas/client.go` `SetResponseFunc()`.\n\nFile v0.0.3:references/configuration-examples.md\n\n# PAI-Rec Engine Configuration Examples\n\nThis document provides sample PAI-Rec engine configurations and common patterns to help with validation and diagnosis.\n\n## Configuration Structure Overview\n\nA typical PAI-Rec engine configuration contains these main sections:\n\n```json\n{\n \"scene_id\": \"default\",\n \"recall\": {\n \"modules\": []\n },\n \"rank\": {\n \"modules\": []\n },\n \"filter\": {\n \"rules\": []\n },\n \"experiment\": {\n \"layers\": []\n }\n}\n```\n\n---\n\n## Basic Configuration Example\n\n### Minimal Working Configuration\n\n```json\n{\n \"scene_id\": \"embedding_recall_scene\",\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"embedding_recall\",\n \"type\": \"vector\",\n \"params\": {\n \"table\": \"user_item_embedding\",\n \"index_type\": \"hnsw\",\n \"topk\": 100,\n \"timeout_ms\": 200\n }\n }\n ]\n },\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"simple_scorer\",\n \"type\": \"feature_based\",\n \"params\": {\n \"features\": [\"user_age\", \"item_category\", \"click_rate\"],\n \"model_endpoint\": \"http://eas-service.cn-hangzhou.aliyuncs.com/scoring\"\n }\n }\n ]\n },\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"basic_filter\",\n \"type\": \"threshold\",\n \"params\": {\n \"min_score\": 0.1,\n \"max_results\": 50\n }\n }\n ]\n }\n}\n```\n\n---\n\n## Recall Module Examples\n\n### 1. Vector Similarity Recall\n\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"user_embedding_recall\",\n \"type\": \"vector\",\n \"params\": {\n \"table\": \"user_item_embeddings_v2\",\n \"index_type\": \"hnsw\",\n \"metric\": \"cosine\",\n \"topk\": 500,\n \"timeout_ms\": 300,\n \"filters\": {\n \"category\": \"electronics\",\n \"status\": \"active\"\n }\n }\n }\n ]\n }\n}\n```\n\n**Common Parameters:**\n- `table`: Source embedding table name\n- `index_type`: `hnsw`, `flat`, `ivf`\n- `metric`: `cosine`, `euclidean`, `inner_product`\n- `topk`: Number of results to retrieve\n- `timeout_ms`: Query timeout\n- `filters`: Pre-filter conditions\n\n**Validation Checks:**\n- ✅ Table exists and is accessible\n- ✅ Index type is supported\n- ✅ Metric matches index configuration\n- ✅ Timeout is reasonable (50-500ms)\n- ⚠️ topk too large (>1000) may impact performance\n\n---\n\n### 2. Collaborative Filtering Recall\n\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"cf_recall\",\n \"type\": \"collaborative_filtering\",\n \"params\": {\n \"table\": \"user_behavior_matrix\",\n \"algorithm\": \"item_cf\",\n \"topk\": 200,\n \"min_similarity\": 0.3,\n \"decay_days\": 30\n }\n }\n ]\n }\n}\n```\n\n**Common Parameters:**\n- `algorithm`: `user_cf`, `item_cf`, `swing`\n- `min_similarity`: Minimum similarity threshold\n- `decay_days`: Time decay for historical data\n\n---\n\n### 3. Hot Items Recall\n\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"hot_items\",\n \"type\": \"popular\",\n \"params\": {\n \"table\": \"item_popularity_stats\",\n \"time_window_hours\": 24,\n \"category_aware\": true,\n \"topk\": 100\n }\n }\n ]\n }\n}\n```\n\n---\n\n### 4. Multiple Recall Modules\n\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"embedding_recall\",\n \"type\": \"vector\",\n \"weight\": 0.5,\n \"params\": {\n \"table\": \"embeddings\",\n \"topk\": 300\n }\n },\n {\n \"name\": \"cf_recall\",\n \"type\": \"collaborative_filtering\",\n \"weight\": 0.3,\n \"params\": {\n \"table\": \"user_behavior\",\n \"topk\": 200\n }\n },\n {\n \"name\": \"hot_items\",\n \"type\": \"popular\",\n \"weight\": 0.2,\n \"params\": {\n \"topk\": 100\n }\n }\n ],\n \"merge_strategy\": \"weighted\",\n \"final_topk\": 500\n }\n}\n```\n\n**Validation Checks:**\n- ✅ Weights sum to 1.0 (if using weighted strategy)\n- ✅ No duplicate module names\n- ✅ final_topk >= max individual topk\n- ⚠️ Too many modules may slow processing\n\n---\n\n## Rank Module Examples\n\n### 1. Feature-Based Ranking\n\n```json\n{\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"feature_ranker\",\n \"type\": \"feature_based\",\n \"params\": {\n \"features\": [\n \"user_age\",\n \"user_gender\",\n \"item_category\",\n \"item_price\",\n \"ctr_7d\",\n \"cvr_7d\"\n ],\n \"feature_tables\": {\n \"user_features\": \"user_profile_v1\",\n \"item_features\": \"item_attributes_v1\",\n \"behavior_features\": \"user_item_stats_v1\"\n },\n \"model_endpoint\": \"http://eas.cn-hangzhou.aliyuncs.com/rank_model_v2\",\n \"timeout_ms\": 100,\n \"batch_size\": 50\n }\n }\n ]\n }\n}\n```\n\n**Validation Checks:**\n- ✅ All feature tables accessible\n- ✅ Model endpoint reachable\n- ✅ Batch size reasonable (20-100)\n- ✅ Timeout appropriate for batch size\n- ⚠️ Too many features (>50) may slow inference\n\n---\n\n### 2. Multi-Stage Ranking\n\n```json\n{\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"coarse_ranker\",\n \"type\": \"simple_scorer\",\n \"stage\": 1,\n \"params\": {\n \"features\": [\"ctr_7d\", \"cvr_7d\"],\n \"topk\": 200\n }\n },\n {\n \"name\": \"fine_ranker\",\n \"type\": \"deep_model\",\n \"stage\": 2,\n \"params\": {\n \"model_endpoint\": \"http://eas.cn-hangzhou.aliyuncs.com/dnn_ranker\",\n \"features\": [\"all\"],\n \"topk\": 50\n }\n }\n ]\n }\n}\n```\n\n---\n\n## Filter Module Examples\n\n### 1. Threshold Filters\n\n```json\n{\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"score_threshold\",\n \"type\": \"threshold\",\n \"params\": {\n \"field\": \"score\",\n \"min_value\": 0.1,\n \"max_value\": 1.0\n }\n },\n {\n \"name\": \"diversity_filter\",\n \"type\": \"diversity\",\n \"params\": {\n \"field\": \"category\",\n \"max_same_category\": 5\n }\n }\n ]\n }\n}\n```\n\n---\n\n### 2. Bloom Filter (Dedupe)\n\n```json\n{\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"dedupe_filter\",\n \"type\": \"bloom\",\n \"params\": {\n \"table\": \"user_exposure_history\",\n \"window_days\": 7,\n \"field\": \"item_id\"\n }\n }\n ]\n }\n}\n```\n\n---\n\n### 3. Business Rules Filter\n\n```json\n{\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"business_rules\",\n \"type\": \"custom\",\n \"params\": {\n \"rules\": [\n {\n \"condition\": \"item_status == 'active'\",\n \"action\": \"keep\"\n },\n {\n \"condition\": \"item_price > user_budget\",\n \"action\": \"remove\"\n },\n {\n \"condition\": \"item_stock < 1\",\n \"action\": \"remove\"\n }\n ]\n }\n }\n ]\n }\n}\n```\n\n**Validation Checks:**\n- ✅ Condition syntax is valid\n- ✅ Referenced fields exist\n- ✅ Actions are valid (keep/remove)\n- ⚠️ Complex rules may impact performance\n\n---\n\n## Experiment Configuration Examples\n\n### 1. A/B Testing\n\n```json\n{\n \"experiment\": {\n \"enabled\": true,\n \"layers\": [\n {\n \"layer_id\": \"rank_model_ab_test\",\n \"experiments\": [\n {\n \"exp_id\": \"exp_baseline\",\n \"traffic\": 0.5,\n \"config\": {\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"baseline_ranker\",\n \"model_endpoint\": \"http://eas/baseline_model\"\n }\n ]\n }\n }\n },\n {\n \"exp_id\": \"exp_new_model\",\n \"traffic\": 0.5,\n \"config\": {\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"new_ranker\",\n \"model_endpoint\": \"http://eas/new_model_v2\"\n }\n ]\n }\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n**Validation Checks:**\n- ✅ Traffic percentages sum to 1.0\n- ✅ Experiment IDs are unique\n- ✅ Config overrides are valid\n- ⚠️ Too many experiments may complicate analysis\n\n---\n\n## Common Configuration Patterns\n\n### Pattern 1: E-commerce Recommendation\n\n```json\n{\n \"scene_id\": \"product_recommendation\",\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"user_embedding\",\n \"type\": \"vector\",\n \"params\": {\n \"table\": \"user_item_embeddings\",\n \"topk\": 300\n }\n },\n {\n \"name\": \"browse_history_cf\",\n \"type\": \"collaborative_filtering\",\n \"params\": {\n \"table\": \"browse_behavior\",\n \"topk\": 200\n }\n },\n {\n \"name\": \"trending_products\",\n \"type\": \"popular\",\n \"params\": {\n \"time_window_hours\": 24,\n \"topk\": 100\n }\n }\n ],\n \"merge_strategy\": \"weighted\"\n },\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"ctr_cvr_ranker\",\n \"type\": \"feature_based\",\n \"params\": {\n \"features\": [\"user_profile\", \"item_attributes\", \"ctr_cvr_features\"],\n \"model_endpoint\": \"http://eas/rank_model\"\n }\n }\n ]\n },\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"in_stock_filter\",\n \"type\": \"custom\",\n \"params\": {\n \"condition\": \"item_stock > 0\"\n }\n },\n {\n \"name\": \"exposure_dedupe\",\n \"type\": \"bloom\",\n \"params\": {\n \"table\": \"user_exposure\",\n \"window_days\": 3\n }\n },\n {\n \"name\": \"diversity\",\n \"type\": \"diversity\",\n \"params\": {\n \"field\": \"category\",\n \"max_same_category\": 3\n }\n }\n ]\n }\n}\n```\n\n---\n\n### Pattern 2: Content Recommendation\n\n```json\n{\n \"scene_id\": \"news_feed\",\n \"recall\": {\n \"modules\": [\n {\n \"name\": \"content_embedding\",\n \"type\": \"vector\",\n \"params\": {\n \"table\": \"article_embeddings\",\n \"topk\": 500,\n \"filters\": {\n \"publish_time\": \"last_7_days\"\n }\n }\n },\n {\n \"name\": \"hot_news\",\n \"type\": \"popular\",\n \"params\": {\n \"time_window_hours\": 6,\n \"topk\": 100\n }\n }\n ]\n },\n \"rank\": {\n \"modules\": [\n {\n \"name\": \"engagement_ranker\",\n \"type\": \"feature_based\",\n \"params\": {\n \"features\": [\"read_time\", \"comment_count\", \"share_count\", \"user_interest_match\"],\n \"model_endpoint\": \"http://eas/news_ranker\"\n }\n }\n ]\n },\n \"filter\": {\n \"rules\": [\n {\n \"name\": \"freshness_filter\",\n \"type\": \"threshold\",\n \"params\": {\n \"field\": \"publish_time\",\n \"min_value\": \"now-7d\"\n }\n },\n {\n \"name\": \"read_history_dedupe\",\n \"type\": \"bloom\",\n \"params\": {\n \"table\": \"user_read_history\",\n \"window_days\": 30\n }\n }\n ]\n }\n}\n```\n\n---\n\n## Validation Checklists by Section\n\n### Recall Configuration Validation\n\n- [ ] All table references exist and are accessible\n- [ ] Index types match table configurations\n- [ ] topk values are reasonable (typically 50-1000)\n- [ ] Timeout values appropriate (50-500ms)\n- [ ] Filter conditions use valid fields\n- [ ] Multiple modules have consistent merge strategy\n- [ ] Weights sum to 1.0 (if weighted merge)\n\n### Rank Configuration Validation\n\n- [ ] Feature names match available features\n- [ ] Feature tables accessible in target environment\n- [ ] Model endpoints are reachable\n- [ ] Batch sizes appropriate (20-100)\n- [ ] Timeout accounts for batch processing\n- [ ] Multi-stage ranking has proper topk cascade\n- [ ] No circular dependencies\n\n### Filter Configuration Validation\n\n- [ ] Threshold values are reasonable\n- [ ] Referenced fields exist\n- [ ] Bloom filter tables accessible\n- [ ] Custom rule syntax is valid\n- [ ] Diversity constraints make sense\n- [ ] Filter order is optimal (cheap filters first)\n\n### Experiment Configuration Validation\n\n- [ ] Traffic splits sum to 1.0\n- [ ] Experiment IDs are unique\n- [ ] Config overrides are syntactically valid\n- [ ] Layer definitions don't conflict\n- [ ] Experiment is enabled/disabled appropriately\n\n---\n\n## Common Configuration Issues\n\n### Issue 1: Items Size Not Enough\n\n**Error:**\n```json\n{\n \"code\": 299,\n \"msg\": \"items size not enough\"\n}\n```\n\n**Possible Causes:**\n1. Recall topk too low\n2. Filters too aggressive\n3. No data in recall tables\n4. User has insufficient history\n\n**Configuration Fix:**\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"topk\": 500 // Increased from 100\n }\n ]\n },\n \"filter\": {\n \"rules\": [\n {\n \"min_score\": 0.05 // Lowered from 0.1\n }\n ]\n }\n}\n```\n\n---\n\n### Issue 2: Timeout Errors\n\n**Error:**\n```json\n{\n \"code\": 500,\n \"msg\": \"request timeout\"\n}\n```\n\n**Possible Causes:**\n1. Recall timeout too low\n2. Too many recall modules\n3. Large batch size in ranking\n4. Slow model endpoint\n\n**Configuration Fix:**\n```json\n{\n \"recall\": {\n \"modules\": [\n {\n \"params\": {\n \"timeout_ms\": 500 // Increased from 200\n }\n }\n ]\n },\n \"rank\": {\n \"modules\": [\n {\n \"params\": {\n \"batch_size\": 30, // Reduced from 100\n \"timeout_ms\": 200\n }\n }\n ]\n }\n}\n```\n\n---\n\n### Issue 3: Environment Mismatch\n\n**Error:**\n```\nResource 'prod_user_features' not found\n```\n\n**Cause:**\nUsing production table reference in Pre environment\n\n**Configuration Fix:**\n```json\n{\n \"rank\": {\n \"modules\": [\n {\n \"params\": {\n \"feature_tables\": {\n \"user_features\": \"pre_user_features_v1\" // Changed from prod_\n }\n }\n }\n ]\n }\n}\n```\n\n---\n\n## Best Practices\n\n### 1. Naming Conventions\n\n- Use descriptive module names: `user_embedding_recall`, not `recall1`\n- Include version in table names: `user_profile_v2`\n- Prefix tables by environment: `prod_`, `pre_`\n\n### 2. Performance Optimization\n\n- Set appropriate topk at each stage (cascade: 1000 → 200 → 50)\n- Use cheap filters before expensive ones\n- Batch model inference when possible\n- Set reasonable timeouts (recall: 200-500ms, rank: 100-200ms)\n\n### 3. Robustness\n\n- Always include fallback recall (e.g., hot items)\n- Set min/max constraints on values\n- Handle missing features gracefully\n- Use default values for optional parameters\n\n### 4. Experimentation\n\n- Start with small traffic splits (5%-10%)\n- Keep baseline configuration stable\n- Document experiment hypotheses\n- Monitor key metrics\n\n---\n\n## Related Documentation\n\n- [Verification Method](verification-method.md) - How to validate configurations\n- [Troubleshooting Guide](troubleshooting-guide.md) - Common issues and solutions\n- [Related Commands](related-commands.md) - CLI commands for config management\n\nFile v0.0.3:references/ram-policies.md\n\n# RAM Policies for PAI-Rec Diagnosis Skill\n\nThis document lists all RAM (Resource Access Management) permissions required by the PAI-Rec Engine Diagnosis and Configuration Validation skill.\n\n## Overview\n\nThis skill requires read-only permissions for:\n- PAI-EAS (Elastic Algorithm Service) - for service information and logs\n- PAI-RecService - for engine configuration management\n\n## Required Permissions\n\n### PAI-EAS Permissions\n\n| API Action | Permission | Purpose |\n|------------|-----------|---------|\n| `DescribeService` | `eas:DescribeService` | Retrieve EAS service details including configuration and resource IDs |\n| `DescribeServiceLog` | `eas:DescribeServiceLog` | Query service logs to trace request processing |\n\n### PAI-RecService Permissions\n\n| API Action | Permission | Purpose |\n|------------|-----------|----------|\n| `ListEngineConfigs` | `pairecservice:ListEngineConfigs` | List engine configuration versions |\n| `GetEngineConfig` | `pairecservice:GetEngineConfig` | Retrieve specific engine configuration details |\n| `GetExperimentGroup` | `pairecservice:GetExperimentGroup` | Retrieve experiment group details and override config |\n| `GetExperiment` | `pairecservice:GetExperiment` | Retrieve experiment details and override config |\n\n## Complete RAM Policy Document\n\n### Minimal Policy (Read-Only)\n\n```json\n{\n \"Version\": \"1\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"eas:DescribeService\",\n \"eas:DescribeServiceLog\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"pairecservice:ListEngineConfigs\",\n \"pairecservice:GetEngineConfig\",\n \"pairecservice:GetExperimentGroup\",\n \"pairecservice:GetExperiment\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n### Resource-Specific Policy (Recommended)\n\nFor better security, restrict access to specific resources:\n\n```json\n{\n \"Version\": \"1\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"eas:DescribeService\",\n \"eas:DescribeServiceLog\"\n ],\n \"Resource\": [\n \"acs:eas:*:*:service/\",\n \"acs:eas:*:*:cluster/\"\n ]\n },\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"pairecservice:ListEngineConfigs\",\n \"pairecservice:GetEngineConfig\",\n \"pairecservice:GetExperimentGroup\",\n \"pairecservice:GetExperiment\"\n ],\n \"Resource\": [\n \"acs:pairecservice:*:*:instance/\"\n ]\n }\n ]\n}\n```\n\n## Permission Scope\n\n### Service-Level Permissions\n\n- **EAS Service**: Read access to service configurations and logs\n- **PAI-Rec Instance**: Read access to engine configurations\n\n### Data-Level Permissions\n\n- No write permissions required\n- No resource creation/deletion permissions required\n- Read-only access to configurations and logs\n\n## Applying Permissions\n\n### Using RAM Console\n\n1. Log in to [RAM Console](https://ram.console.aliyun.com/)\n2. Navigate to **Users** or **Roles**\n3. Select the target principal\n4. Click **Add Permissions**\n5. Choose **Custom Policy** and paste the policy JSON above\n6. Click **OK** to apply\n\n### Using Aliyun CLI\n\nCreate a custom policy:\n\n```bash\naliyun ram create-policy \\\n --policy-name PAIRecDiagnosisReadOnly \\\n --policy-document '{\n \"Version\": \"1\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"eas:DescribeService\",\n \"eas:DescribeServiceLog\",\n \"pairecservice:ListEngineConfigs\",\n \"pairecservice:GetEngineConfig\",\n \"pairecservice:GetExperimentGroup\",\n \"pairecservice:GetExperiment\"\n ],\n \"Resource\": \"*\"\n }\n ]\n }'\n```\n\nAttach policy to user:\n\n```bash\naliyun ram attach-policy-to-user \\\n --policy-name PAIRecDiagnosisReadOnly \\\n --policy-type Custom \\\n --user-name \n```\n\n## Troubleshooting Permission Issues\n\n### Common Permission Errors\n\n1. **Forbidden.RAM**\n - Error: User not authorized to perform operation\n - Solution: Ensure all required permissions are granted\n - Check: Verify policy is attached and resources match\n\n2. **InvalidAccessKeyId.NotFound**\n - Error: Access key does not exist\n - Solution: Verify credentials are configured correctly\n - Check: Run `aliyun configure list`\n\n3. **Forbidden.SubUser**\n - Error: Sub-account lacks permissions\n - Solution: Contact account admin to grant permissions\n - Check: Verify you're using the correct account\n\n### Verification Steps\n\nAfter applying permissions, verify access:\n\n```bash\n# Test EAS service access\naliyun eas describe-service \\\n --cluster-id \\\n --service-name \n\n# Test PAI-Rec config access\naliyun pairecservice list-engine-configs \\\n --instance-id \n```\n\n## Security Best Practices\n\n1. **Principle of Least Privilege**: Grant only required permissions\n2. **Resource-Specific Policies**: Limit access to specific instances/services\n3. **Regular Audits**: Review and update permissions periodically\n4. **Separate Roles**: Use different roles for different environments (Prod/Pre)\n5. **Credential Rotation**: Rotate access keys regularly\n6. **Audit Logging**: Enable ActionTrail to track API calls\n\n## Related Documentation\n\n- [RAM Overview](https://www.alibabacloud.com/help/ram/product-overview/)\n- [EAS API Reference](https://www.alibabacloud.com/help/eas/developer-reference/)\n- [PAI-RecService API Reference](https://www.alibabacloud.com/help/pai/developer-reference/)\n\nFile v0.0.3:references/related-commands.md\n\n# Related CLI Commands\n\nThis document provides a comprehensive reference of all Alibaba Cloud CLI commands used in the PAI-Rec Engine Diagnosis and Configuration Validation skill.\n\n## PAI-EAS Commands\n\n### describe-service\n\nQueries the details about a PAI-EAS service.\n\n**Usage:**\n```bash\naliyun eas describe-service \\\n --cluster-id \\\n --service-name \n```\n\n**Parameters:**\n- `--cluster-id` (required): The ID of the region where the service is deployed\n- `--service-name` (required): The service name\n- `--region` (optional): Override region ID\n\n**Response Fields:**\n- `ServiceId`: Service identifier\n- `ServiceName`: Name of the service\n- `Resource`: EAS service resource ID (e.g., `eas-r-xxxxxxxxxxxx`)\n- `ServiceConfig`: Service configuration including environment variables\n- `Status`: Service status (Running/Stopped/etc.)\n- `CurrentVersion`: Current deployed version\n- `Metadata`: Additional service metadata\n\n**Example:**\n```bash\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall\n```\n\n**Common Use Cases:**\n- Get EAS service resource ID\n- Extract environment variables (INSTANCE_ID, CONFIG_NAME, REGION, PAIREC_ENVIRONMENT)\n- Check service status before diagnosis\n- Verify service configuration\n\n---\n\n### describe-service-log\n\nQueries the information about the logs of a PAI-EAS service.\n\n**Usage:**\n```bash\naliyun eas describe-service-log \\\n --cluster-id \\\n --service-name \\\n [--keyword ] \\\n [--start-time ] \\\n [--end-time ] \\\n [--page-num ] \\\n [--page-size ]\n```\n\n**Parameters:**\n- `--cluster-id` (required): The ID of the region where the service is deployed\n- `--service-name` (required): The service name\n- `--keyword` (optional, **strongly recommended for request-level diagnosis**): Keyword to filter logs, e.g., `request_id`. See pitfall note below.\n- `--start-time` (optional): Beginning of time range. Format MUST be `yyyy-MM-dd HH:mm:ss` in UTC (space separator, no `T` / no `Z`). ISO-8601 like `2025-04-28T00:00:00Z` will be rejected with `InvalidParameter`.\n- `--end-time` (optional): End of time range (same format as `--start-time`).\n- `--page-num` (optional): Page number (default: 1)\n- `--page-size` (optional): Entries per page (default: 500)\n- `--container-name` (optional): Container name\n- `--instance-name` (optional): Instance name\n- `--ip` (optional): Instance IP address\n- `--previous` (optional): Query logs before last restart\n\n**[CRITICAL] Pitfall — keyword + time range returns no business logs:**\nWhen `--keyword` is combined with `--start-time` / `--end-time`, PAI-Rec application logs (`controller.go`, `feed.go`, `recall.go`, `rank_service.go`, etc.) are silently dropped by the CLI, even if the time window covers the real log timestamp. Only `/bin/sh` wrapper heartbeats and `502 Bad Gateway` noise remain. For request-level diagnosis, always use `--keyword` **without** `--start-time` / `--end-time`.\n\n**Response Fields:**\n- `Logs`: Array of log entries\n- `PageNum`: Current page number\n- `TotalCount`: Total log count\n- `TotalPageNum`: Total pages\n\n**Example — recommended pattern for request-level diagnosis (keyword only):**\n```bash\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --keyword \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\" \\\n --page-size 500\n```\n\n**Example — broad time-window scan without keyword (infrastructure logs only):**\n```bash\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --start-time \"2025-04-28 08:00:00\" \\\n --end-time \"2025-04-28 09:00:00\" \\\n --page-size 500\n```\n\n**Common Use Cases:**\n- Trace request processing by `request_id` (use keyword-only pattern)\n- Debug error messages\n- Monitor service behavior\n- Analyze performance issues\n\n**Query Strategy Recommendations:**\n- Request-level diagnosis: `--keyword ` only, no time range\n- Service-level scan: omit `--keyword`, use time window in `yyyy-MM-dd HH:mm:ss` UTC\n- Log retention: EAS logs have a limited retention window; diagnose issues promptly\n\n---\n\n## PAI-RecService Commands\n\n### list-engine-configs\n\nLists engine configuration versions for a PAI-Rec instance.\n\n**Usage:**\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id \\\n [--environment ] \\\n [--name ] \\\n [--status ] \\\n [--version ] \\\n [--page-number ] \\\n [--page-size ]\n```\n\n**Parameters:**\n- `--instance-id` (required): The PAI-Rec instance ID\n- `--environment` (optional): Environment filter (`Prod` or `Pre`)\n- `--name` (optional but **strongly recommended** when the config name is known): Exact-match server-side filter on configuration name. Always pass this when you already know the target config (e.g. obtained from `ServiceConfig.envs.CONFIG_NAME`); omitting it returns the entire instance inventory and may exceed the default page size.\n- `--status` (optional): Status filter (e.g., `Released`, `Draft`, `Archived`)\n- `--version` (optional): Version filter\n- `--page-number` (optional): Page number for pagination\n- `--page-size` (optional): Number of results per page\n\n**Response Fields:**\n- `EngineConfigs`: Array of engine configurations\n - `EngineConfigId`: Configuration version ID\n - `Name`: Configuration name\n - `Version`: Version number\n - `Status`: Configuration status\n - `Environment`: Target environment\n - `GmtCreateTime`: Creation timestamp\n - `GmtModifiedTime`: Last modification timestamp\n\n**Example:**\n```bash\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --status Released \\\n --name my_engine_config\n```\n\n**Common Use Cases:**\n- Find released configurations\n- List all versions of a configuration\n- Filter by environment (Prod/Pre)\n- Select configuration for validation\n\n**Environment Mapping:**\n- Service environment `product` → CLI parameter `Prod`\n- Service environment `prepub` → CLI parameter `Pre`\n\n---\n\n### get-engine-config\n\nRetrieves detailed information about a specific engine configuration.\n\n**Usage:**\n```bash\naliyun pairecservice get-engine-config \\\n --instance-id \\\n --engine-config-id \n```\n\n**Parameters:**\n- `--instance-id` (required): The PAI-Rec instance ID\n- `--engine-config-id` (required): The specific configuration version ID\n\n**Response Fields:**\n- `EngineConfig`: Configuration object\n - `EngineConfigId`: Configuration ID\n - `Name`: Configuration name\n - `Version`: Version number\n - `Status`: Current status\n - `Environment`: Target environment\n - `ConfigValue`: The actual configuration content (JSON/YAML)\n - `Description`: Configuration description\n - `GmtCreateTime`: Creation time\n - `GmtModifiedTime`: Last modified time\n\n**Example:**\n```bash\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-12345\n```\n\n**Common Use Cases:**\n- Retrieve configuration for validation\n- Export configuration for backup\n- Compare different versions\n- Debug configuration issues\n\n**ConfigValue Structure:**\nThe `ConfigValue` field contains the engine configuration in JSON or YAML format, typically including:\n- Recall configurations\n- Ranking configurations\n- Filter rules\n- Scene definitions\n- Feature mappings\n- Model endpoints\n\n---\n\n## Utility Commands\n\n### aliyun configure list\n\nChecks current credential configuration status.\n\n**Usage:**\n```bash\naliyun configure list\n```\n\n**Output:**\nLists all configured profiles with their authentication method (AK, STS, OAuth).\n\n**Common Use Cases:**\n- Verify credentials before running commands\n- Check which profile is active\n- Troubleshoot authentication issues\n\n---\n\n### Per-command --user-agent (Observability)\n\nEvery `aliyun` CLI command that calls a cloud API MUST include `--user-agent` for request tracing.\nLocal utility commands (e.g. `configure`, `plugin`, `version`) do not support this flag and should be excluded.\n\n**Usage:**\n```bash\naliyun [options] \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/{session-id}\n```\n\n**Common Use Cases:**\n- Track skill invocations end-to-end via a unique session-id (32-char lowercase hex)\n- Correlate multiple CLI calls within a single skill session\n\n---\n\n### aliyun plugin update\n\nUpdates all installed CLI plugins to latest versions.\n\n**Usage:**\n```bash\naliyun plugin update\n```\n\n**Common Use Cases:**\n- Ensure latest plugin versions before execution\n- Required as part of skill prerequisites\n\n---\n\n## Command Chaining Examples\n\n### Full Diagnosis Flow\n\n```bash\n# 1. Session-id is a 32-char lowercase hex string generated once per session\n# Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 2. Get service info\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 3. Query logs by request_id (keyword-only pattern — do NOT add --start-time / --end-time)\naliyun eas describe-service-log \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --keyword \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\" \\\n --page-size 500 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 4. List engine configs (always pass --name when the config name is known)\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --status Released \\\n --name embedding_config \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 5. Get specific config\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-12345 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\n### Configuration Validation Flow\n\n```bash\n# 1. Session-id is a 32-char lowercase hex string generated once per session\n# Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 2. List available versions\naliyun pairecservice list-engine-configs \\\n --instance-id pairec-cn-xxxxx \\\n --environment Prod \\\n --name my_config \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n\n# 3. Get specific version for validation\naliyun pairecservice get-engine-config \\\n --instance-id pairec-cn-xxxxx \\\n --engine-config-id config-67890 \\\n --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\n```\n\n## Error Handling\n\n### Common Error Codes\n\n| Error Code | Description | Solution |\n|------------|-------------|----------|\n| `Forbidden.RAM` | Insufficient RAM permissions | Check RAM policies |\n| `InvalidParameter` | Invalid parameter value | Verify parameter format |\n| `ServiceNotFound` | Service does not exist | Check service name and cluster ID |\n| `ConfigNotFound` | Configuration not found | Verify instance ID and config ID |\n\n### Debugging Commands\n\nCheck command execution details:\n```bash\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name test \\\n --log-level DEBUG\n```\n\nDry-run mode (no actual execution):\n```bash\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name test \\\n --cli-dry-run\n```\n\n## Related Documentation\n\n- [EAS API Reference](https://www.alibabacloud.com/help/eas/developer-reference/)\n- [PAI-RecService API Reference](https://www.alibabacloud.com/help/pai/developer-reference/)\n- [Aliyun CLI User Guide](https://www.alibabacloud.com/help/cli/)\n\nFile v0.0.3:references/schema.json\n\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"title\": \"PAI-Rec Engine Configuration\",\n \"description\": \"JSON Schema for PAI-Rec recommendation engine configuration file\",\n \"type\": \"object\",\n \"properties\": {\n \"RunMode\": {\n \"type\": \"string\",\n \"description\": \"Run mode (informational only, not validated)\"\n },\n \"Region\": {\n \"type\": \"string\",\n \"description\": \"Region identifier\"\n },\n \"ListenConf\": {\n \"$ref\": \"#/definitions/ListenConfig\"\n },\n \"RecallConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/RecallConfig\" },\n \"description\": \"Recall configurations array\"\n },\n \"SceneConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"$ref\": \"#/definitions/CategoryConfig\"\n }\n },\n \"description\": \"Scene configurations\"\n },\n \"FilterConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/FilterConfig\" },\n \"description\": \"Filter configurations array\"\n },\n \"FilterNames\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"description\": \"Scene to filter names mapping\"\n },\n \"BeFilterConfs\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"object\" },\n \"description\": \"BE filter configurations\"\n },\n \"AlgoConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/AlgoConfig\" },\n \"description\": \"Algorithm/model configurations\"\n },\n \"GeneralRankConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/GeneralRankConfig\" },\n \"description\": \"General rank (coarse) configurations\"\n },\n \"RankConf\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/RankConfig\" },\n \"description\": \"Rank (fine) configurations\"\n },\n \"SortConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/SortConfig\" },\n \"description\": \"Sort (rerank) configurations array\"\n },\n \"DPPConf\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"object\" },\n \"description\": \"DPP diversity configurations\"\n },\n \"SortNames\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"description\": \"Scene to sort names mapping\"\n },\n \"FeatureConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/SceneFeatureConfig\" },\n \"description\": \"Feature loading configurations\"\n },\n \"UserFeatureConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/SceneFeatureConfig\" },\n \"description\": \"User feature preloading configurations\"\n },\n \"HologresConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/HologresConfig\" },\n \"description\": \"Hologres data sources\"\n },\n \"RedisConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/RedisConfig\" },\n \"description\": \"Redis data sources\"\n },\n \"MysqlConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/MysqlConfig\" },\n \"description\": \"MySQL data sources\"\n },\n \"ClickHouseConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/ClickHouseConfig\" },\n \"description\": \"ClickHouse data sources\"\n },\n \"GraphConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/GraphConfig\" },\n \"description\": \"Graph data sources\"\n },\n \"FeatureStoreConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/FeatureStoreConfig\" },\n \"description\": \"FeatureStore data sources\"\n },\n \"KafkaConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/KafkaConfig\" },\n \"description\": \"Kafka data sources\"\n },\n \"SlsConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/SlsConfig\" },\n \"description\": \"SLS data sources\"\n },\n \"DatahubConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/DatahubConfig\" },\n \"description\": \"Datahub data sources\"\n },\n \"BEConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"BE engine data sources\"\n },\n \"Ha3EngineConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"Ha3 engine data sources\"\n },\n \"OpenSearchConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/OpenSearchConfig\" },\n \"description\": \"OpenSearch data sources\"\n },\n \"HBaseConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"HBase data sources\"\n },\n \"HBaseThriftConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"HBase Thrift data sources\"\n },\n \"TableStoreConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/TableStoreConfig\" },\n \"description\": \"TableStore data sources\"\n },\n \"LindormConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"Lindorm data sources\"\n },\n \"RecallEngineConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/RecallEngineConfig\" },\n \"description\": \"Recall-engine service data sources\"\n },\n \"LogConf\": {\n \"type\": \"object\",\n \"description\": \"Logging configuration\"\n },\n \"ABTestConf\": {\n \"type\": \"object\",\n \"description\": \"A/B testing configuration\"\n },\n \"CallBackConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/CallBackConfig\" },\n \"description\": \"Callback configurations\"\n },\n \"EmbeddingConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"type\": \"object\" },\n \"description\": \"Embedding configurations\"\n },\n \"PipelineConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/PipelineConfig\" }\n },\n \"description\": \"Custom pipeline configurations\"\n },\n \"PrometheusConfig\": {\n \"$ref\": \"#/definitions/PrometheusConfig\"\n },\n \"DebugConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/DebugConfig\" },\n \"description\": \"Debug configurations\"\n },\n \"FeatureLogConfs\": {\n \"type\": \"object\",\n \"additionalProperties\": { \"$ref\": \"#/definitions/FeatureLogConfig\" },\n \"description\": \"Feature log configurations\"\n },\n \"UserDefineConfs\": {\n \"description\": \"User-defined configurations\"\n }\n },\n \"additionalProperties\": false,\n \"definitions\": {\n \"ListenConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"HttpAddr\": { \"type\": \"string\" },\n \"HttpPort\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"DaoConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"Adapter\": { \"type\": \"string\" },\n \"AdapterType\": { \"type\": \"string\" },\n \"RedisName\": { \"type\": \"string\" },\n \"RedisPrefix\": { \"type\": \"string\" },\n \"RedisDataType\": { \"type\": \"string\" },\n \"RedisFieldType\": { \"type\": \"string\" },\n \"RedisDefaultKey\": { \"type\": \"string\" },\n \"RedisValueDelimeter\": { \"type\": \"string\" },\n \"MysqlName\": { \"type\": \"string\" },\n \"MysqlTable\": { \"type\": \"string\" },\n \"Config\": { \"type\": \"string\" },\n \"TableStoreName\": { \"type\": \"string\" },\n \"TableStoreTableName\": { \"type\": \"string\" },\n \"HBasePrefix\": { \"type\": \"string\" },\n \"HBaseName\": { \"type\": \"string\" },\n \"HBaseTable\": { \"type\": \"string\" },\n \"ColumnFamily\": { \"type\": \"string\" },\n \"Qualifier\": { \"type\": \"string\" },\n \"ItemIdField\": { \"type\": \"string\" },\n \"ItemScoreField\": { \"type\": \"string\" },\n \"HologresName\": { \"type\": \"string\" },\n \"HologresTableName\": { \"type\": \"string\" },\n \"ClickHouseName\": { \"type\": \"string\" },\n \"ClickHouseTableName\": { \"type\": \"string\" },\n \"BeName\": { \"type\": \"string\" },\n \"BizName\": { \"type\": \"string\" },\n \"BeRecallName\": { \"type\": \"string\" },\n \"BeTableName\": { \"type\": \"string\" },\n \"BeExposureUserIdName\": { \"type\": \"string\" },\n \"BeExposureItemIdName\": { \"type\": \"string\" },\n \"FeatureStoreName\": { \"type\": \"string\" },\n \"FeatureStoreModelName\": { \"type\": \"string\" },\n \"FeatureStoreEntityName\": { \"type\": \"string\" },\n \"FeatureStoreViewName\": { \"type\": \"string\" },\n \"GraphName\": { \"type\": \"string\" },\n \"InstanceId\": { \"type\": \"string\" },\n \"TableName\": { \"type\": \"string\" },\n \"UserNode\": { \"type\": \"string\" },\n \"ItemNode\": { \"type\": \"string\" },\n \"Edge\": { \"type\": \"string\" },\n \"LindormTableName\": { \"type\": \"string\" },\n \"LindormName\": { \"type\": \"string\" },\n \"RecallEngineName\": { \"type\": \"string\" },\n \"RecallEngineTableName\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"RecallConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\", \"RecallType\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"RecallType\": {\n \"type\": \"string\",\n \"enum\": [\n \"UserCollaborativeFilterRecall\",\n \"UserTopicRecall\",\n \"VectorRecall\",\n \"UserCustomRecall\",\n \"HologresVectorRecall\",\n \"ItemCollaborativeFilterRecall\",\n \"UserGroupHotRecall\",\n \"UserGlobalHotRecall\",\n \"I2IVectorRecall\",\n \"ColdStartRecall\",\n \"MilvusVectorRecall\",\n \"RealTimeU2IRecall\",\n \"OnlineHologresVectorRecall\",\n \"OnlineVectorRecall\",\n \"GraphRecall\",\n \"MockRecall\",\n \"RecallEngineRecall\"\n ]\n },\n \"RecallCount\": { \"type\": \"integer\", \"minimum\": 1 },\n \"RecallAlgo\": { \"type\": \"string\" },\n \"VectorAlgoType\": { \"type\": \"string\" },\n \"ItemType\": { \"type\": \"string\" },\n \"CacheAdapter\": { \"type\": \"string\", \"enum\": [\"Redis\", \"localCache\"] },\n \"CacheConfig\": { \"type\": \"string\" },\n \"CachePrefix\": { \"type\": \"string\" },\n \"CacheTime\": { \"type\": \"integer\" },\n \"Triggers\": { \"type\": \"array\", \"items\": { \"type\": \"object\" } },\n \"HologresVectorConf\": { \"type\": \"object\" },\n \"BeVectorConf\": { \"type\": \"object\" },\n \"MilvusVectorConf\": { \"type\": \"object\" },\n \"UserCollaborativeDaoConf\": { \"type\": \"object\" },\n \"ItemCollaborativeDaoConf\": { \"type\": \"object\" },\n \"EnableMultipleItemId\": { \"type\": \"boolean\" },\n \"MultipleItemIdDelimiter\": { \"type\": \"string\" },\n \"User2ItemDaoConf\": { \"type\": \"object\" },\n \"UserTopicDaoConf\": { \"type\": \"object\" },\n \"DaoConf\": { \"$ref\": \"#/definitions/DaoConfig\" },\n \"VectorDaoConf\": { \"type\": \"object\" },\n \"ColdStartDaoConf\": {\n \"type\": \"object\",\n \"properties\": {\n \"AdapterType\": { \"type\": \"string\", \"description\": \"Adapter type: hologres or featurestore\" },\n \"HologresName\": { \"type\": \"string\", \"description\": \"Data source name defined in HologresConfs (required when Hologres)\" },\n \"HologresTableName\": { \"type\": \"string\", \"description\": \"Cold-start recall table name (required when Hologres)\" },\n \"WhereClause\": { \"type\": \"string\", \"description\": \"Filter clause; supports the $(time) variable and ${user.xxx}/${context.features.xxx} feature variables (Hologres)\" },\n \"PrimaryKey\": { \"type\": \"string\", \"description\": \"Table primary-key field name (required when Hologres)\" },\n \"TimeInterval\": { \"type\": \"integer\", \"description\": \"Time delta in seconds used to compute the $(time) variable (Hologres)\" },\n \"FeatureStoreName\": { \"type\": \"string\", \"description\": \"Data source name defined in FeatureStoreConfs (required when FeatureStore)\" },\n \"FeatureStoreViewName\": { \"type\": \"string\", \"description\": \"FeatureView name for cold-start recall (required when FeatureStore)\" }\n },\n \"required\": [\"AdapterType\"]\n },\n \"FilterParams\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"Type\": { \"type\": \"string\" },\n \"Operator\": { \"type\": \"string\" },\n \"Value\": {}\n }\n },\n \"description\": \"Cold-start recall filter clauses (FeatureStore mode)\"\n },\n \"RealTimeUser2ItemDaoConf\": { \"type\": \"object\" },\n \"UserFeatureConfs\": { \"type\": \"array\", \"items\": { \"type\": \"object\" } },\n \"BeConf\": { \"type\": \"object\" },\n \"GraphConf\": { \"type\": \"object\" },\n \"RecallEngineConf\": { \"$ref\": \"#/definitions/RecallEngineConf\" }\n },\n \"additionalProperties\": true\n },\n \"CategoryConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"RecallNames\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"AutoInvokeCallBack\": { \"type\": \"boolean\" },\n \"AutoInvokeCallBackRate\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 100 }\n },\n \"additionalProperties\": true\n },\n \"FilterConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\", \"FilterType\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"FilterType\": {\n \"type\": \"string\",\n \"enum\": [\n \"User2ItemExposureFilter\",\n \"User2ItemCustomFilter\",\n \"AdjustCountFilter\",\n \"PriorityAdjustCountFilter\",\n \"PriorityAdjustCountFilterV2\",\n \"ItemStateFilter\",\n \"ItemCustomFilter\",\n \"CompletelyFairFilter\",\n \"GroupWeightCountFilter\",\n \"DimensionFieldUniqueFilter\",\n \"User2ItemExposureWithConditionFilter\",\n \"ConditionFilter\",\n \"DiversityAdjustCountFilter\",\n \"SnakeFilter\",\n \"UniqueFilter\"\n ]\n },\n \"Dimension\": { \"type\": \"string\" },\n \"DaoConf\": { \"$ref\": \"#/definitions/DaoConfig\" },\n \"AdjustCountConfs\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"RecallName\": { \"type\": \"string\", \"description\": \"Recall source name (required for PriorityAdjustCountFilter/V2 and SnakeFilter)\" },\n \"Count\": { \"type\": \"integer\", \"description\": \"Count limit (required for PriorityAdjustCountFilter/V2 and DiversityAdjustCountFilter)\" },\n \"Type\": { \"type\": \"string\", \"enum\": [\"accumulator\", \"fix\"], \"description\": \"Limit type: accumulator (cumulative) or fix (fixed)\" },\n \"Expression\": { \"type\": \"string\", \"description\": \"Diversity expression (required for DiversityAdjustCountFilter)\" },\n \"Weight\": { \"type\": \"integer\", \"description\": \"Weight for proportional allocation (required for SnakeFilter)\" }\n }\n },\n \"description\": \"AdjustCount configs; required fields vary by FilterType: PriorityAdjustCountFilter/V2 require RecallName+Count, DiversityAdjustCountFilter requires Expression+Count, SnakeFilter requires RecallName+Weight\"\n },\n \"ItemStateDaoConf\": { \"type\": \"object\" },\n \"FilterParams\": { \"type\": \"array\" },\n \"DiversityDaoConf\": { \"type\": \"object\" },\n \"FilterVal\": { \"type\": \"object\" },\n \"MaxItems\": { \"type\": \"integer\" },\n \"TimeInterval\": { \"type\": \"integer\" },\n \"WriteLog\": { \"type\": \"boolean\" },\n \"OnlyLogUserExposeFlag\": { \"type\": \"boolean\" },\n \"GenerateItemDataFuncName\": { \"type\": \"string\" },\n \"WriteLogExcludeScenes\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"ClearLogIfNotEnoughScene\": { \"type\": \"string\" },\n \"ShuffleItem\": { \"type\": \"boolean\" },\n \"RetainNum\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": true\n },\n \"AlgoConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\", \"Type\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"Type\": { \"type\": \"string\" },\n \"EasConf\": { \"$ref\": \"#/definitions/EasConfig\" },\n \"VectorConf\": { \"$ref\": \"#/definitions/VectorConfig\" },\n \"MilvusConf\": { \"$ref\": \"#/definitions/MilvusConfig\" },\n \"LookupConf\": { \"type\": \"object\" },\n \"SeldonConf\": { \"type\": \"object\" },\n \"TFservingConf\": { \"type\": \"object\" }\n },\n \"additionalProperties\": false\n },\n \"EasConfig\": {\n \"type\": \"object\",\n \"required\": [\"Processor\", \"Url\", \"ResponseFuncName\"],\n \"properties\": {\n \"Processor\": {\n \"type\": \"string\",\n \"enum\": [\"EasyRec\", \"TensorFlow\", \"ALINK_FM\", \"PMML\", \"TFServing\"]\n },\n \"Url\": { \"type\": \"string\" },\n \"Auth\": { \"type\": \"string\" },\n \"EndpointType\": { \"type\": \"string\", \"enum\": [\"DOCKER\", \"DIRECT\"] },\n \"SignatureName\": { \"type\": \"string\" },\n \"Timeout\": { \"type\": \"integer\" },\n \"RetryTimes\": { \"type\": \"integer\" },\n \"ResponseFuncName\": {\n \"type\": \"string\",\n \"description\": \"Must match one of the response funcs registered in pairec algorithm/eas/client.go SetResponseFunc().\",\n \"enum\": [\n \"pssmartResponseFunc\",\n \"tfResponseFunc\",\n \"alinkFMResponseFunc\",\n \"tfMutValResponseFunc\",\n \"easyrecResponseFunc\",\n \"easyrecResponseFuncDebug\",\n \"easyrecMutValResponseFunc\",\n \"easyrecMutValResponseFuncDebug\",\n \"easyrecMutClassificationResponseFunc\",\n \"easyrecMutClassificationResponseFuncDebug\",\n \"easyrecUserEmbResponseFunc\",\n \"easyrecUserRealtimeEmbeddingResponseFunc\",\n \"easyrecUserRealtimeEmbeddingMindResponseFunc\",\n \"tfServingResponseFunc\",\n \"torchrecMutValResponseFunc\",\n \"torchrecMutValResponseFuncDebug\",\n \"torchrecEmbeddingResponseFunc\",\n \"torchrecEmbeddingItemsResponseFunc\",\n \"torchrecEmbeddingItemsResponseFuncDebug\",\n \"tfUseEmbResponseFunc\",\n \"torchrecMutClassificationResponseFunc\",\n \"torchrecMutClassificationResponseFuncDebug\"\n ]\n },\n \"Outputs\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"ModelName\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"VectorConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"ServerAddress\": { \"type\": \"string\" },\n \"Timeout\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"MilvusConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"ServerAddress\": { \"type\": \"string\" },\n \"Timeout\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"RankConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"RankAlgoList\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"RankScore\": { \"type\": \"string\" },\n \"Processor\": { \"type\": \"string\" },\n \"BatchCount\": { \"type\": \"integer\" },\n \"ContextFeatures\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"ItemFeatures\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } }\n },\n \"additionalProperties\": true\n },\n \"GeneralRankConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"FeatureLoadConfs\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/FeatureLoadConfig\" } },\n \"RankConf\": { \"$ref\": \"#/definitions/RankConfig\" },\n \"ActionConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/ActionConfig\" }\n }\n },\n \"additionalProperties\": true\n },\n \"ActionConfig\": {\n \"type\": \"object\",\n \"required\": [\"ActionType\", \"ActionName\"],\n \"properties\": {\n \"ActionType\": { \"type\": \"string\", \"enum\": [\"sort\", \"filter\"] },\n \"ActionName\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"SceneFeatureConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"AsynLoadFeature\": { \"type\": \"boolean\" },\n \"FeatureLoadConfs\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/FeatureLoadConfig\" }\n }\n },\n \"additionalProperties\": false\n },\n \"FeatureLoadConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"FeatureDaoConf\": { \"$ref\": \"#/definitions/FeatureDaoConfig\" },\n \"Features\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/FeatureConfig\" }\n }\n },\n \"additionalProperties\": false\n },\n \"FeatureDaoConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"Adapter\": { \"type\": \"string\" },\n \"AdapterType\": { \"type\": \"string\" },\n \"FeatureKey\": { \"type\": \"string\" },\n \"FeatureAppendKey\": { \"type\": \"string\" },\n \"FeatureStore\": { \"type\": \"string\", \"enum\": [\"user\", \"item\"] },\n \"UserFeatureKeyName\": { \"type\": \"string\" },\n \"ItemFeatureKeyName\": { \"type\": \"string\" },\n \"TimestampFeatureKeyName\": { \"type\": \"string\" },\n \"EventFeatureKeyName\": { \"type\": \"string\" },\n \"PlayTimeFeatureKeyName\": { \"type\": \"string\" },\n \"TsFeatureKeyName\": { \"type\": \"string\" },\n \"UserSelectFields\": { \"type\": \"string\" },\n \"ItemSelectFields\": { \"type\": \"string\" },\n \"FeatureAsyncLoad\": { \"type\": \"boolean\" },\n \"FeatureType\": { \"type\": \"string\" },\n \"SequenceLength\": { \"type\": \"integer\" },\n \"SequenceName\": { \"type\": \"string\" },\n \"SequenceEvent\": { \"type\": \"string\" },\n \"SequenceDelim\": { \"type\": \"string\" },\n \"SequencePlayTime\": { \"type\": \"string\" },\n \"SequenceOfflineTableName\": { \"type\": \"string\" },\n \"SequenceDimFields\": { \"type\": \"string\" },\n \"HologresName\": { \"type\": \"string\" },\n \"HologresTableName\": { \"type\": \"string\" },\n \"RedisName\": { \"type\": \"string\" },\n \"RedisPrefix\": { \"type\": \"string\" },\n \"RedisDataType\": { \"type\": \"string\" },\n \"RedisFieldType\": { \"type\": \"string\" },\n \"RedisDefaultKey\": { \"type\": \"string\" },\n \"RedisValueDelimeter\": { \"type\": \"string\" },\n \"MysqlName\": { \"type\": \"string\" },\n \"MysqlTable\": { \"type\": \"string\" },\n \"TableStoreName\": { \"type\": \"string\" },\n \"TableStoreTableName\": { \"type\": \"string\" },\n \"FeatureStoreName\": { \"type\": \"string\" },\n \"FeatureStoreModelName\": { \"type\": \"string\" },\n \"FeatureStoreEntityName\": { \"type\": \"string\" },\n \"FeatureStoreViewName\": { \"type\": \"string\" },\n \"CacheFeaturesName\": { \"type\": \"string\" },\n \"LoadFromCacheFeaturesName\": { \"type\": \"string\" },\n \"CacheSize\": { \"type\": \"integer\" },\n \"CacheTime\": { \"type\": \"integer\" },\n \"BeName\": { \"type\": \"string\" },\n \"BeItemFeatureKeyName\": { \"type\": \"string\" },\n \"BeTimestampFeatureKeyName\": { \"type\": \"string\" },\n \"BeEventFeatureKeyName\": { \"type\": \"string\" },\n \"BePlayTimeFeatureKeyName\": { \"type\": \"string\" },\n \"BeIsHomeField\": { \"type\": \"string\" },\n \"BeRTCntFields\": { \"type\": \"string\" },\n \"BeRTCntFieldInfo\": { \"type\": \"array\" },\n \"BeRTTable\": { \"type\": \"string\" },\n \"NoUsePlayTimeField\": { \"type\": \"boolean\" }\n },\n \"additionalProperties\": true\n },\n \"FeatureConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"FeatureType\": { \"type\": \"string\" },\n \"FeatureName\": { \"type\": \"string\" },\n \"FeatureSource\": { \"type\": \"string\" },\n \"FeatureValue\": { \"type\": \"string\" },\n \"FeatureStore\": { \"type\": \"string\", \"enum\": [\"user\", \"item\"] },\n \"RemoveFeatureSource\": { \"type\": \"boolean\" },\n \"Normalizer\": { \"type\": \"string\" },\n \"Expression\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"SortConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\", \"SortType\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"SortType\": {\n \"type\": \"string\",\n \"enum\": [\n \"ItemRankScore\",\n \"BoostScoreSort\",\n \"BoostScoreByWeight\",\n \"DiversityRuleSort\",\n \"DPPSort\",\n \"SSDSort\",\n \"AlgoScoreSort\",\n \"TrafficControlSort\",\n \"MultiRecallMixSort\",\n \"DistinctIdSort\",\n \"CustomFieldSort\",\n \"ConditionSort\"\n ]\n },\n \"Debug\": { \"type\": \"boolean\" },\n \"BoostScoreConditions\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/BoostScoreCondition\" } },\n \"DiversitySize\": { \"type\": \"integer\" },\n \"DiversityRules\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/DiversityRule\" } },\n \"ExcludeRecalls\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"Conditions\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/FilterParamConfig\" } },\n \"ExclusionRules\": { \"type\": \"array\", \"items\": { \"type\": \"object\" } },\n \"ExploreItemSize\": { \"type\": \"integer\" },\n \"TimeInterval\": { \"type\": \"integer\" },\n \"BoostScoreByWeightDao\": { \"type\": \"object\" }\n },\n \"additionalProperties\": true\n },\n \"BoostScoreCondition\": {\n \"type\": \"object\",\n \"required\": [\"Conditions\", \"Expression\"],\n \"properties\": {\n \"Conditions\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/FilterParamConfig\" } },\n \"Expression\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"FilterParamConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\", \"Domain\", \"Type\", \"Value\", \"Operator\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"Domain\": { \"type\": \"string\", \"enum\": [\"item\", \"user\"] },\n \"Type\": { \"type\": \"string\" },\n \"Value\": {},\n \"Operator\": {\n \"type\": \"string\",\n \"enum\": [\"equal\", \"not_equal\", \"in\", \"not_in\", \"greater\", \"greaterThan\", \"less\", \"lessThan\", \"contains\", \"not_contains\"]\n }\n },\n \"additionalProperties\": false\n },\n \"DiversityRule\": {\n \"type\": \"object\",\n \"required\": [\"Dimensions\"],\n \"properties\": {\n \"Dimensions\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"IntervalSize\": { \"type\": \"integer\" },\n \"WindowSize\": { \"type\": \"integer\" },\n \"FrequencySize\": { \"type\": \"integer\" },\n \"Weight\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"HologresConfig\": {\n \"type\": \"object\",\n \"required\": [\"DSN\"],\n \"properties\": {\n \"DSN\": { \"type\": \"string\" }\n },\n \"additionalProperties\": true\n },\n \"RedisConfig\": {\n \"type\": \"object\",\n \"required\": [\"Host\", \"Port\"],\n \"properties\": {\n \"Host\": { \"type\": \"string\" },\n \"Port\": { \"type\": \"integer\" },\n \"Password\": { \"type\": \"string\" },\n \"DbNum\": { \"type\": \"integer\" },\n \"MaxIdle\": { \"type\": \"integer\" },\n \"ConnectTimeout\": { \"type\": \"integer\" },\n \"ReadTimeout\": { \"type\": \"integer\" },\n \"WriteTimeout\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"MysqlConfig\": {\n \"type\": \"object\",\n \"required\": [\"DSN\"],\n \"properties\": {\n \"DSN\": { \"type\": \"string\" }\n },\n \"additionalProperties\": true\n },\n \"ClickHouseConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"DSN\": { \"type\": \"string\" }\n },\n \"additionalProperties\": true\n },\n \"GraphConfig\": {\n \"type\": \"object\",\n \"required\": [\"Host\", \"UserName\", \"Passwd\"],\n \"properties\": {\n \"Host\": { \"type\": \"string\" },\n \"UserName\": { \"type\": \"string\" },\n \"Passwd\": { \"type\": \"string\" }\n },\n \"additionalProperties\": true\n },\n \"FeatureStoreConfig\": {\n \"type\": \"object\",\n \"required\": [\"RegionId\", \"ProjectName\"],\n \"properties\": {\n \"RegionId\": { \"type\": \"string\" },\n \"ProjectName\": { \"type\": \"string\" },\n \"AccessId\": { \"type\": \"string\", \"description\": \"Alibaba Cloud Access Key ID (optional, can use env vars)\" },\n \"AccessKey\": { \"type\": \"string\", \"description\": \"Alibaba Cloud Access Key Secret (optional, can use env vars)\" },\n \"FeatureDBUsername\": { \"type\": \"string\" },\n \"FeatureDBPassword\": { \"type\": \"string\" },\n \"HologresPort\": { \"type\": \"integer\", \"description\": \"Hologres port (optional)\" },\n \"HologresUsername\": { \"type\": \"string\" },\n \"HologresPassword\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"KafkaConfig\": {\n \"type\": \"object\",\n \"required\": [\"BootstrapServers\", \"Topic\"],\n \"properties\": {\n \"BootstrapServers\": { \"type\": \"string\" },\n \"Topic\": { \"type\": \"string\" }\n },\n \"additionalProperties\": true\n },\n \"SlsConfig\": {\n \"type\": \"object\",\n \"required\": [\"EndPoint\", \"ProjectName\", \"LogstoreName\"],\n \"properties\": {\n \"EndPoint\": { \"type\": \"string\" },\n \"ProjectName\": { \"type\": \"string\" },\n \"LogstoreName\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"DatahubConfig\": {\n \"type\": \"object\",\n \"required\": [\"Endpoint\", \"ProjectName\", \"TopicName\"],\n \"properties\": {\n \"Endpoint\": { \"type\": \"string\" },\n \"ProjectName\": { \"type\": \"string\" },\n \"TopicName\": { \"type\": \"string\" },\n \"Schemas\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/DatahubTopicSchema\" }\n }\n },\n \"additionalProperties\": false\n },\n \"DatahubTopicSchema\": {\n \"type\": \"object\",\n \"required\": [\"Field\", \"Type\"],\n \"properties\": {\n \"Field\": { \"type\": \"string\" },\n \"Type\": {\n \"type\": \"string\",\n \"enum\": [\"string\", \"integer\", \"bigint\", \"double\", \"float\", \"timestamp\"]\n }\n },\n \"additionalProperties\": false\n },\n \"TableStoreConfig\": {\n \"type\": \"object\",\n \"required\": [\"EndPoint\", \"InstanceName\"],\n \"properties\": {\n \"EndPoint\": { \"type\": \"string\" },\n \"InstanceName\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"OpenSearchConfig\": {\n \"type\": \"object\",\n \"required\": [\"EndPoint\"],\n \"properties\": {\n \"EndPoint\": { \"type\": \"string\" }\n },\n \"additionalProperties\": false\n },\n \"CallBackConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"DataSource\": {\n \"type\": \"object\",\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"Type\": { \"type\": \"string\" }\n }\n },\n \"RankConf\": { \"$ref\": \"#/definitions/RankConfig\" },\n \"RawFeatures\": { \"type\": \"boolean\" },\n \"RawFeaturesRate\": { \"type\": \"integer\" },\n \"ItemSize\": { \"type\": \"integer\" },\n \"ItemSizeRate\": { \"type\": \"integer\" },\n \"UseUserFeatures\": { \"type\": \"boolean\" }\n },\n \"additionalProperties\": true\n },\n \"PipelineConfig\": {\n \"type\": \"object\",\n \"required\": [\"Name\"],\n \"properties\": {\n \"Name\": { \"type\": \"string\" },\n \"RecallNames\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"FilterNames\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"GeneralRankConf\": { \"$ref\": \"#/definitions/GeneralRankConfig\" },\n \"FeatureLoadConfs\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/definitions/FeatureLoadConfig\" } },\n \"RankConf\": { \"$ref\": \"#/definitions/RankConfig\" },\n \"SortNames\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } }\n },\n \"additionalProperties\": true\n },\n \"DebugConfig\": {\n \"type\": \"object\",\n \"required\": [\"OutputType\", \"Rate\"],\n \"properties\": {\n \"OutputType\": { \"type\": \"string\", \"enum\": [\"console\", \"datahub\", \"kafka\", \"file\"] },\n \"Rate\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 100 },\n \"DebugUsers\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } },\n \"DatahubName\": { \"type\": \"string\" },\n \"KafkaName\": { \"type\": \"string\" },\n \"FilePath\": { \"type\": \"string\" },\n \"MaxFileNum\": { \"type\": \"integer\" }\n },\n \"additionalProperties\": false\n },\n \"FeatureLogConfig\": {\n \"type\": \"object\",\n \"required\": [\"OutputType\"],\n \"properties\": {\n \"OutputType\": { \"type\": \"string\" },\n \"DatahubName\": { \"type\": \"string\" },\n \"Rate\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 100 },\n \"UserFeatures\": { \"type\": \"string\" },\n \"ItemFeatures\": { \"type\": \"string\" },\n \"SplitUserItemLogs\": { \"type\": \"boolean\" }\n },\n \"additionalProperties\": false\n },\n \"PrometheusConfig\": {\n \"type\": \"object\",\n \"properties\": {\n \"Enable\": { \"type\": \"boolean\" },\n \"Subsystem\": { \"type\": \"string\" },\n \"PushGatewayURL\": { \"type\": \"string\" },\n \"PushGatewayToken\": { \"type\": \"string\" },\n \"PushIntervalSecs\": { \"type\": \"integer\" },\n \"Job\": { \"type\": \"string\" },\n \"ReqDurBuckets\": { \"type\": \"array\", \"items\": { \"type\": \"number\" } },\n \"ReqSizeBuckets\": { \"type\": \"array\", \"items\": { \"type\": \"number\" } },\n \"RespSizeBuckets\": { \"type\": \"array\", \"items\": { \"type\": \"number\" } }\n },\n \"additionalProperties\": false\n },\n \"RecallEngineConfig\": {\n \"type\": \"object\",\n \"required\": [\"Username\", \"Password\"],\n \"properties\": {\n \"Username\": {\n \"type\": \"string\",\n \"description\": \"Recall-engine username\"\n },\n \"Password\": {\n \"type\": \"string\",\n \"description\": \"Recall-engine password\"\n },\n \"Endpoint\": {\n \"type\": \"string\",\n \"description\": \"Recall-engine service endpoint (optional; auto-detected in PAI-EAS)\"\n },\n \"Authorization\": {\n \"type\": \"string\",\n \"description\": \"Custom auth header (optional)\"\n },\n \"InstanceId\": {\n \"type\": \"string\",\n \"description\": \"Instance ID (optional; read from env vars in PAI-EAS)\"\n }\n },\n \"additionalProperties\": false\n },\n \"RecallEngineConf\": {\n \"type\": \"object\",\n \"required\": [\"RecallEngineName\", \"ServiceName\", \"RecallEngineParams\"],\n \"properties\": {\n \"RecallEngineName\": {\n \"type\": \"string\",\n \"description\": \"Recall data source name, defined in RecallEngineConfs\"\n },\n \"ServiceName\": {\n \"type\": \"string\",\n \"description\": \"Recall service name\"\n },\n \"VersionName\": {\n \"type\": \"string\",\n \"description\": \"Recall service version (optional; defaults to the active online version)\"\n },\n \"RecallEngineParams\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/RecallEngineParam\" },\n \"description\": \"Specific configuration for this recall\"\n },\n \"FilterNames\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"Filter name list (optional)\"\n },\n \"UserFeatures\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"User feature names to pass to recall engine (optional)\"\n }\n },\n \"additionalProperties\": false\n },\n \"RecallEngineParam\": {\n \"type\": \"object\",\n \"required\": [\"RecallType\", \"RecallName\", \"Count\"],\n \"properties\": {\n \"RecallType\": {\n \"type\": \"string\",\n \"enum\": [\"x2i\", \"vector\", \"random\"],\n \"description\": \"Recall type: x2i, vector, or random\"\n },\n \"RecallName\": {\n \"type\": \"string\",\n \"description\": \"Recall name configured in the recall-management service\"\n },\n \"Count\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": \"Recall count; if filters are configured, this is the post-filter count\"\n },\n \"TriggerType\": {\n \"type\": \"string\",\n \"enum\": [\"user\", \"item\", \"fixvalue\", \"u2i_realtime\"],\n \"description\": \"Trigger type: user, item, fixvalue, or u2i_realtime\"\n },\n \"TriggerValue\": {\n \"type\": \"string\",\n \"description\": \"Trigger fixed value (for fixvalue type, e.g. -1 for global hot)\"\n },\n \"UserTriggers\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/definitions/UserTrigger\" },\n \"description\": \"User trigger configuration (for user type)\"\n },\n \"UserTriggerDaoConf\": {\n \"$ref\": \"#/definitions/UserTriggerDaoConf\",\n \"description\": \"User trigger data configuration (for u2i_realtime type)\"\n }\n },\n \"additionalProperties\": false\n },\n \"UserTrigger\": {\n \"type\": \"object\",\n \"required\": [\"TriggerKey\"],\n \"properties\": {\n \"TriggerKey\": {\n \"type\": \"string\",\n \"description\": \"Trigger key, e.g. uid, gender, age\"\n },\n \"Boundaries\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"number\" },\n \"description\": \"Numeric bucketing boundaries (optional; used for numeric fields such as age)\"\n }\n },\n \"additionalProperties\": false\n },\n \"UserTriggerDaoConf\": {\n \"type\": \"object\",\n \"required\": [\"AdapterType\"],\n \"properties\": {\n \"AdapterType\": {\n \"type\": \"string\",\n \"enum\": [\"hologres\", \"featurestore\"],\n \"description\": \"Data source type\"\n },\n \"HologresName\": {\n \"type\": \"string\",\n \"description\": \"Data source name defined in HologresConfs (required for Hologres)\"\n },\n \"HologresTableName\": {\n \"type\": \"string\",\n \"description\": \"User-behavior table name (required for Hologres)\"\n },\n \"FeatureStoreName\": {\n \"type\": \"string\",\n \"description\": \"Data source name defined in FeatureStoreConfs (required for FeatureStore)\"\n },\n \"FeatureStoreViewName\": {\n \"type\": \"string\",\n \"description\": \"FeatureView name for user behavior (required for FeatureStore)\"\n },\n \"WhereClause\": {\n \"type\": \"string\",\n \"description\": \"SQL filter clause (optional)\"\n },\n \"Limit\": {\n \"type\": \"integer\",\n \"description\": \"Query result limit (optional)\"\n },\n \"TriggerCount\": {\n \"type\": \"integer\",\n \"description\": \"Trigger count (optional)\"\n },\n \"EventPlayTime\": {\n \"type\": \"string\",\n \"description\": \"Event play-time filter; format event1:time1;event2:time2 (optional)\"\n },\n \"EventWeight\": {\n \"type\": \"string\",\n \"description\": \"Event weight configuration; format event1:weight1;event2:weight2 (optional)\"\n },\n \"WeightExpression\": {\n \"type\": \"string\",\n \"description\": \"Weight expression; supports currentTime and eventTime variables (optional)\"\n },\n \"WeightMode\": {\n \"type\": \"string\",\n \"enum\": [\"sum\", \"max\"],\n \"description\": \"Weight aggregation mode: sum or max; defaults to sum (optional)\"\n },\n \"NoUsePlayTimeField\": {\n \"type\": \"boolean\",\n \"description\": \"Whether to ignore the play-duration field (optional)\"\n },\n \"ItemIdFieldName\": {\n \"type\": \"string\",\n \"description\": \"Item ID field name; defaults to item_id (optional)\"\n },\n \"EventFieldName\": {\n \"type\": \"string\",\n \"description\": \"Event field name; defaults to event (optional)\"\n }\n\nArchive v0.0.2: 14 files, 60935 bytes\n\nFiles: references/acceptance-criteria.md (16070b), references/cli-installation-guide.md (11625b), references/config-validation.md (11537b), references/configuration-examples.md (14921b), references/ram-policies.md (5015b), references/related-commands.md (11426b), references/schema.json (40071b), references/troubleshooting-guide.md (18571b), references/verification-method.md (13980b), scripts/sanitize_config.py (6168b), scripts/validate.py (37762b), skill-card.md (3321b), SKILL.md (23732b), _meta.json (149b)\n\nArchive v0.0.1: 12 files, 54993 bytes\n\nFiles: references/acceptance-criteria.md (16070b), references/cli-installation-guide.md (11625b), references/config-validation.md (11537b), references/configuration-examples.md (14921b), references/ram-policies.md (5015b), references/related-commands.md (11060b), references/schema.json (39340b), references/troubleshooting-guide.md (18571b), references/verification-method.md (13980b), scripts/validate.py (34779b), SKILL.md (19196b), _meta.json (149b)","readmeExcerpt":"Skill: Alibabacloud Pai Rec Diagnosis Owner: sdk-team Summary: Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur... Tags: latest:0.0.3 Version history: v0.0.3 | 2026-06-17T07:23:50.720Z | auto alibabacloud-pai-rec-diagnosis 0.0.3 - Enforces that every aliyun API command must include a unique session-based --use","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"> aliyun configure list\n>"},{"language":"text","snippet":"--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/{session-id}"},{"language":"bash","snippet":"aliyun eas describe-service --cluster-id cn-hangzhou --service-name my_service --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"},{"language":"bash","snippet":"> export WORKDIR=$(mktemp -d /tmp/pairec-diag-XXXXXX)\n>"},{"language":"text","snippet":"Service Name: embedding_recall\nAPI Response:\n{\n \"code\": 299,\n \"msg\": \"items size not enough\",\n \"request_id\": \"941b4e14-d1c5-489f-a184-b2b17f8b4fdb\",\n \"size\": 0,\n \"experiment_id\": \"\",\n \"items\": []\n}"},{"language":"bash","snippet":"aliyun eas describe-service \\\n --cluster-id \\\n --service-name "}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: alibabacloud-pai-rec-diagnosis\ndescription: |\n Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill.\n Use for diagnosing PAI-Rec engine interface issues and validating engine configurations.\n Triggers: \"PAI-Rec\", \"engine diagnosis\", \"engine config validation\", \"pairec\", \"recommendation engine\".\n---\n\n# PAI-Rec Engine Diagnosis and Configuration Validation\n\nThis skill provides comprehensive diagnostic and validation capabilities for Alibaba Cloud PAI-Rec (Programmable Recommendation System) engines, including interface troubleshooting and configuration analysis.\n\n## Scenario Description\n\nPAI-Rec is Alibaba Cloud's programmable recommendation system that provides intelligent recommendation capabilities. This skill helps users:\n\n1. **Diagnose PAI-Rec Engine Interface Issues**: When engine API returns errors or unexpected results, trace the request through EAS service logs and engine configurations to identify root causes.\n\n2. **Validate Engine Configurations**: Analyze engine configuration files for potential issues, inconsistencies, or misconfigurations before deployment.\n\n**Architecture**: PAI-EAS Service + PAI-Rec Engine + Engine Configuration Management\n\n### Key Components\n- **PAI-EAS Service**: Elastic Algorithm Service hosting the recommendation engine\n- **PAI-Rec Engine**: The recommendation engine processing requests\n- **Engine Configuration**: Configuration files defining engine behavior\n- **Service Logs**: EAS service logs containing request traces\n\n---\n\n## Installation\n\n**Pre-check: Aliyun CLI >= 3.3.3 required**\n> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,\n> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update,\n> or see `references/cli-installation-guide.md` for installation instructions.\n\n**Pre-check: Aliyun CLI plugin update required**\n> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.\n> [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.\n\n---\n\n## Authentication\n\n> **Pre-check: Alibaba Cloud Credentials Required**\n>\n> **Security Rules:**\n> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)\n> - **NEVER** ask the user to input AK/SK directly in the conversation or command line\n> - **NEVER** use `aliyun configure set` with literal credential values\n> - **ONLY** use `aliyun configure list` to check credential status\n>\n> ```bash\n> aliyun configure list\n> ```\n> Check the output for a valid profile (AK, STS, or OAuth identity).\n>\n> **If no valid profile exists, STOP here.**\n> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)\n> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)\n> 3. Return and re-run after `aliyun configure list` shows a valid profile\n\n---\n\n## RAM Policy\n\n> **[MUST] P"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n \"slug\": \"alibabacloud-pai-rec-diagnosis\",\n \"version\": \"0.0.3\",\n \"publishedAt\": 1781681030720\n}"},{"path":"references/acceptance-criteria.md","content":"# Acceptance Criteria: alibabacloud-pai-rec-diagnosis\n\n**Scenario**: PAI-Rec Engine Diagnosis and Configuration Validation\n**Purpose**: Skill testing acceptance criteria\n\nThis document defines correct and incorrect patterns for the PAI-Rec diagnosis skill to ensure proper implementation and usage.\n\n---\n\n## Correct CLI Command Patterns\n\n### 1. Product Names — Verify product name exists\n\n#### ✅ CORRECT\n\n```bash\n# EAS product commands\naliyun eas describe-service --cluster-id cn-hangzhou --service-name test\naliyun eas describe-service-log --cluster-id cn-hangzhou --service-name test\n\n# PAI-RecService product commands\naliyun pairecservice list-engine-configs --instance-id pairec-cn-xxxxx\naliyun pairecservice get-engine-config --instance-id pairec-cn-xxxxx --engine-config-id config-123\n```\n\n**Why correct:** Uses valid product names `eas` and `pairecservice` that exist in Aliyun CLI.\n\n#### ❌ INCORRECT\n\n```bash\n# Wrong product names\naliyun pai-eas describe-service ... # Product is 'eas', not 'pai-eas'\naliyun rec describe-service ... # Product is 'pairecservice', not 'rec'\naliyun pairec list-engine-configs ... # Product is 'pairecservice', not 'pairec'\naliyun pai list-engine-configs ... # Product is 'pairecservice', not 'pai'\n```\n\n**Why incorrect:** These product names don't exist in the Aliyun CLI.\n\n---\n\n### 2. Command Names — Verify action exists under the product\n\n#### ✅ CORRECT\n\n```bash\n# EAS commands\naliyun eas describe-service\naliyun eas describe-service-log\n\n# PAI-RecService commands\naliyun pairecservice list-engine-configs\naliyun pairecservice get-engine-config\naliyun pairecservice apply-engine-config\naliyun pairecservice create-engine-config\naliyun pairecservice get-experiment-group\naliyun pairecservice get-experiment\n```\n\n**Why correct:** All commands use lowercase words connected with hyphens (plugin mode format).\n\n#### ❌ INCORRECT\n\n```bash\n# Traditional API format (not plugin mode)\naliyun eas DescribeService # Use describe-service\naliyun eas DescribeServiceLog # Use describe-service-log\naliyun pairecservice ListEngineConfigs # Use list-engine-configs\naliyun pairecservice GetEngineConfig # Use get-engine-config\n\n# Wrong command names\naliyun eas get-service # Command is describe-service\naliyun eas list-logs # Command is describe-service-log\naliyun pairecservice get-configs # Command is list-engine-configs\naliyun pairecservice describe-config # Command is get-engine-config\n```\n\n**Why incorrect:** Must use plugin mode format (lowercase with hyphens), and exact command names.\n\n---\n\n### 3. Parameter Names — Verify each parameter exists for the command\n\n#### ✅ CORRECT - EAS describe-service\n\n```bash\naliyun eas describe-service \\\n --cluster-id cn-hangzhou \\\n --service-name embedding_recall \\\n --region cn-hangzhou\n```\n\n**Parameters:**\n- `--cluster-id`: Required, the cluster ID\n- `--service-name`: Required, the servi"},{"path":"references/cli-installation-guide.md","content":"# Aliyun CLI Installation & Configuration Guide\n\nComplete guide for installing and configuring Aliyun CLI.\n\n> **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.\n\n## Installation\n\n### macOS\n\n**Using Homebrew (Recommended)**\n```bash\nbrew install aliyun-cli\n# Upgrade to latest\nbrew upgrade aliyun-cli\n\n# Verify version (>= 3.3.3)\naliyun version\n```\n\n**Using Binary**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz\n\n# Extract\ntar -xzf aliyun-cli-macosx-latest-amd64.tgz\n\n# Move to PATH\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n### Linux\n\n**Debian/Ubuntu**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-amd64.tgz\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n**CentOS/RHEL**\n```bash\n# Download\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-amd64.tgz\nsudo mv aliyun /usr/local/bin/\n\n# Verify\naliyun version\n```\n\n**ARM64 Architecture**\n```bash\n# Download ARM64 version\nwget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz\n\n# Extract and install\ntar -xzf aliyun-cli-linux-latest-arm64.tgz\nsudo mv aliyun /usr/local/bin/\n```\n\n### Windows\n\n**Using Binary**\n1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip\n2. Extract the ZIP file\n3. Add the directory to your PATH environment variable\n4. Open new Command Prompt or PowerShell\n5. Verify: `aliyun version`\n\n**Using PowerShell**\n```powershell\n# Download\nInvoke-WebRequest -Uri \"https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip\" -OutFile \"aliyun-cli.zip\"\n\n# Extract\nExpand-Archive -Path aliyun-cli.zip -DestinationPath C:\\aliyun-cli\n\n# Add to PATH (requires admin privileges)\n$env:Path += \";C:\\aliyun-cli\"\n[Environment]::SetEnvironmentVariable(\"Path\", $env:Path, [System.EnvironmentVariableTarget]::Machine)\n\n# Verify\naliyun version\n```\n\n## Configuration\n\n### Quick Start\n\n```bash\naliyun configure set \\\n --mode AK \\\n --access-key-id \\\n --access-key-secret \\\n --region cn-hangzhou\n```\n\nAll `aliyun configure` commands support non-interactive flags, which is the recommended approach —\nit works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.\n\n**Where to Get Access Keys**\n\n1. Log in to Aliyun Console: https://ram.console.aliyun.com/\n2. Navigate to: AccessKey Management\n3. Create a new AccessKey pair\n4. Save the secret immediately — it's only shown once\n\n### Configuration Modes\n\nAliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.\n\n#### 1. AK Mode (Access Key)\n\nMost common mode for personal accounts and scripts.\n\n```bash\naliyun configure set \\\n --mode AK \\\n --access-key-id LTAI5tXXXXXXX"},{"path":"references/config-validation.md","content":"# PAI-Rec Engine Configuration Validation\n\nReference for `scripts/validate.py` — the JSON Schema + rule-based validator used by\nWorkflow 2 (Engine Configuration Validation) in `SKILL.md`.\n\n---\n\n## 1. Files\n\n| Path | Purpose |\n|------|---------|\n| `scripts/validate.py` | Validator entry point (CLI + library). Loads a bundled JSON Schema (Draft-7) that describes the top-level engine-config structure. |\n\nAll files live inside this skill — no external skill dependency.\n\n---\n\n## 2. Dependencies\n\n- Python 3.8+\n- `jsonschema` >=4.0,<5.0 (optional but recommended):\n ```bash\n pip install \"jsonschema>=4.0,<5.0\"\n ```\n If `jsonschema` is not installed the script **still runs** but skips Schema checks\n and relies on the built-in rule validator only. A single warning-equivalent note\n is NOT emitted in this case, so install `jsonschema` for full coverage.\n\n---\n\n## 3. CLI Usage\n\n```bash\n# From a saved JSON file\npython3 scripts/validate.py /tmp/engine-config.json\n\n# Inline JSON string\npython3 scripts/validate.py '{\"RunMode\":\"product\",\"RecallConfs\":[...]}'\n\n# From stdin (recommended when ConfigValue is already in a shell variable)\nprintf '%s' \"$CONFIG_VALUE\" | python3 scripts/validate.py --stdin\n\n# Validate with experiment configs (reference-existence check)\npython3 scripts/validate.py /tmp/raw_engine_config.json \\\n --experiment-config /tmp/experiment_group_21.json \\\n --experiment-config /tmp/experiment_44.json\n```\n\n### Exit codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Validation passed (no errors; warnings may still be printed). |\n| `1` | Validation failed (at least one `error`-severity finding). |\n| `2` | Input error — argument is not a readable file, not valid JSON, or stdin decode failed. |\n\n### Output format\n\n```\nValidation finished: error(s), warning(s)\n\n [ERROR] : \n [WARNING] : \n ...\n```\n\n`` uses dotted / bracketed notation, e.g.\n`RecallConfs[3]`, `SceneConfs.default.default.RecallNames[1]`,\n`FilterConfs[0].DaoConf`.\n\n### Fragment auto-wrapping\n\nIf the input is a single fragment (object containing `RecallType`, `FilterType`, or\n`SortType` at the top level) and the corresponding `*Confs` array is missing, the\nscript automatically wraps it into `{ \"s\": [ ] }` before\nvalidation. This lets you validate one recall / filter / sort entry in isolation.\n\n---\n\n## 4. Library Usage\n\n```python\nfrom scripts.validate import validate_config, ValidationError\n\nerrors: list[ValidationError] = validate_config(config_dict, use_schema=True)\nfor e in errors:\n print(e.severity, e.path, e.message)\n```\n\n`ValidationError` fields: `path`, `message`, `severity` (`\"error\"` | `\"warning\"`).\n\n---\n\n## 5. Rule Catalogue\n\n### 5.1 Structural / Type checks (JSON Schema)\n\nEnforced by the bundled JSON Schema (Draft-7) via `jsonschema.Draft7Validator`. Covers:\n\n- Top-level keys: `RunMode`, `ListenConf`, `RecallConfs`, `FilterConfs`,\n `SortConfs`, `AlgoConfs`, `SceneConfs`, `FilterNames`, `SortNa"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur... Skill: Alibabacloud Pai Rec Diagnosis Owner: sdk-team Summary: Alibaba Cloud PAI-Rec Engine Diagnostic and Configuration Validation Skill. Use for diagnosing PAI-Rec engine interface issues and validating engine configur... Tags: latest:0.0.3 Version history: v0.0.3 | 2026-06-17T07:23:50.720Z | auto alibabacloud-pai-rec-diagnosis 0.0.3 - Enforces that every aliyun API command must include a unique session-based --use","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1432,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T02:51:58.799Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:38:25.883Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}