@josephyan/qingflow-app-user-mcp 0.2.0-beta.25 → 0.2.0-beta.27

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.25
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.27
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.25 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.27 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.25",
+  "version": "0.2.0-beta.27",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b25"
+version = "0.2.0b27"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -9,19 +9,8 @@ metadata:
 
 ## Overview
 
-This skill is a **router skill** for operational usage inside existing Qingflow apps.
-
-Use it when the request is operational, but you first need to decide which specialized skill should own it.
-
-This skill does **not** try to teach every detailed workflow itself.  
-It routes to:
-
-- [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md) for record browsing, detail lookup, create, update, and delete
-- [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md) for task-center usage, comments, approvals, rollback, transfer, urge, and directory lookup
-- [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) for grouped analysis, ratios, rankings, trends, and final statistical conclusions
-
-Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md).  
-If the user did not specify one, default to `prod`.
+This skill is a lightweight router for operational Qingflow work.
+Assumes MCP is connected, authenticated, and on the correct workspace.
 
 ## Default Paths
 
@@ -42,23 +31,19 @@ Route to exactly one of these specialized paths:
 ## Routing Rules
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
-- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, or subtable writes, switch to `$qingflow-record-crud`
+- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
 - If the task is about inbox, todo, cc, task-center workload, comments, approval, reject, rollback, transfer, urge, or directory lookup, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
 - If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
 
 ## Shared Preconditions
 
-- confirm environment first
-- ensure auth exists
-- ensure workspace is selected
 - prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
 - if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
 - if the task can stay read-only, do not write or act
 
 ## Resources
 
-- Environment switching: [references/environments.md](references/environments.md)
 - Record CRUD: [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
 - Task center and workflow usage: [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
 - Dedicated analysis workflow: [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)

package/skills/qingflow-record-analysis/SKILL.md

@@ -7,15 +7,15 @@ metadata:
 
 # Qingflow Record Analysis
 
-Analysis tasks must start with `record_schema_get`.
-Use field_id-based DSLs only.
+This skill is for final statistical conclusions only.
+Assumes MCP is connected, authenticated, and on the correct workspace.
+Analysis tasks must start with `record_schema_get`. Use field_id-based DSLs only.
 
 ## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
 
 This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
 
-Tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for sample rows AFTER analysis, and treat those read paths as belonging to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md).
-Comments, approvals, rollback, transfer, urge, and directory lookup stay in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md), not in this analysis skill.
+Core tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
 
 ---
 
@@ -74,56 +74,32 @@ Comments, approvals, rollback, transfer, urge, and directory lookup stay in [$qi
 
 ---
 
-## COMPLETE DSL TEMPLATE — copy, replace field_id, done
+See [references/dsl-templates.md](references/dsl-templates.md) for complete copy-paste templates.
 
+**Typical summary / distribution:**
 ```json
 {
-  "app_key": "YOUR_APP_KEY",
-  "dimensions": [
-    { "field_id": FIELD_ID_FROM_SCHEMA, "alias": "维度名" }
-  ],
-  "metrics": [
-    { "op": "count", "alias": "记录数" }
-  ],
-  "filters": [
-    { "field_id": TIME_FIELD_ID, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
-  ],
-  "sort": [
-    { "by": "记录数", "order": "desc" }
-  ],
+  "dimensions": [{ "field_id": FIELD_ID_FROM_SCHEMA, "alias": "维度名" }],
+  "metrics": [{ "op": "count", "alias": "记录数" }],
+  "sort": [{ "by": "记录数", "order": "desc" }],
   "limit": 50,
   "strict_full": true
 }
 ```
 
-More templates:
-
-**Whole-table count (no grouping):**
-```json
-{ "dimensions": [], "metrics": [{"op":"count","alias":"记录数"}], "strict_full": true }
-```
-
-**Monthly trend:**
-```json
-{
-  "dimensions": [{"field_id": 3, "alias": "月份", "bucket":"month"}],
-  "metrics": [{"op":"count","alias":"记录数"}],
-  "sort": [{"by":"月份","order":"asc"}],
-  "limit": 24, "strict_full": true
-}
-```
-
-**Cross analysis with sum:**
+**Typical time-filter / trend:**
 ```json
 {
-  "dimensions": [{"field_id": 2, "alias": "状态"}, {"field_id": 5, "alias": "负责人"}],
-  "metrics": [{"op":"count","alias":"记录数"}, {"op":"sum","field_id": 7, "alias":"总金额"}],
-  "sort": [{"by":"记录数","order":"desc"}],
-  "limit": 100, "strict_full": true
+  "dimensions": [{ "field_id": TIME_FIELD_ID, "alias": "月份", "bucket": "month" }],
+  "metrics": [{ "op": "count", "alias": "记录数" }],
+  "filters": [{ "field_id": TIME_FIELD_ID, "op": "between", "value": ["2024-03-01", "2024-03-31"] }],
+  "sort": [{ "by": "月份", "order": "asc" }],
+  "limit": 24,
+  "strict_full": true
 }
 ```
 
-### Top-level arguments
+Top-level arguments:
 
 - `app_key`: required.
 - `dimensions`: `[]` = whole-table summary; `[{...}]` = grouped.
@@ -136,12 +112,10 @@ More templates:
 
 ## RULES
 
-- Normalize relative time phrases into explicit legal date ranges.
 - 渗透率 / 转化率 / 占比类结论必须先定义分子和分母。
 - Do not claim a metric you did not query.
 - Derived ratios must be computed outside the DSL.
 - Before choosing a DSL shape, first decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`.
-- If a field is still ambiguous after `record_schema_get`, do not guess; ask the user to confirm from a short candidate list.
 - Rankings must come from structured sorted results.
 - For partial answers, explicitly disclose which parts are complete and which parts remain unresolved.
 - Complex answers should default to `先结构、后解读`.
@@ -150,33 +124,25 @@ More templates:
 - Final wording should stay as close as possible to schema titles.
 - Do not pass field titles, aliases, or guessed ids.
 - If `completeness.statement_scope=returned_groups_only` or `completeness.rows_truncated=true`, downgrade wording to returned groups only.
-- All `field_id` MUST come from `record_schema_get`. Never guess or use field titles.
 - One DSL per question. Multiple small DSLs > one overloaded request.
-- Normalize relative dates to concrete ranges BEFORE building DSL. Never send impossible dates (e.g. `2026-02-29`).
-- If schema has ambiguous fields, ask user to pick from a short list. Do not guess.
 - `record_list` is NEVER the basis for final statistics.
-- Derived ratios: run numerator and denominator as separate DSLs, compute ratio in your reasoning.
 - Set `alias` for any metric you will sort by, compare, or quote.
 
 ---
 
-## OUTPUT (CRITICAL — final answer must show concrete numbers)
-
-### 必须逐行列出数据（硬性要求）
-
-final_answer MUST include a table with every row from `result.rows`:
-
-| {维度别名} | {指标别名} | 占比 |
-|------------|-----------|------|
-| {row.dimensions.X} | {row.metrics.Y} | {Y / total * 100}% |
-
-- 占比 = 行指标值 / `result.totals.metric_totals` 总值, 保留一位小数
-- 如 `metric_totals` 不存在, 用各行之和作分母
-- 超过 20 行展示 Top 20 并注明
-- 不得只写"共 N 种类型"而省略明细
-
-### 结论分级
+## OUTPUT
 
+- Final answer must show concrete numbers.
+- If `result.rows` exists, list each returned row; if there are more than 20 rows, show Top 20 and say so.
+- 占比 = 行指标值 / `result.totals.metric_totals` 总值；如 `metric_totals` 缺失，用各行之和作分母。
+- Prefer the structured `ranking` block when it exists.
 - `safe_for_final_conclusion=true` → `全量可信结论`
-- 不完整 → `初步观察`
+- Otherwise → `初步观察`
 - `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`
+
+## Resources
+
+- DSL templates: [references/dsl-templates.md](references/dsl-templates.md)
+- Analysis patterns: [references/analysis-patterns.md](references/analysis-patterns.md)
+- Confidence reporting: [references/confidence-reporting.md](references/confidence-reporting.md)
+- Analysis gotchas: [references/analysis-gotchas.md](references/analysis-gotchas.md)

package/skills/qingflow-record-analysis/references/dsl-templates.md

@@ -0,0 +1,93 @@
+# DSL Templates
+
+Use these copy-paste templates after `record_schema_get`.
+
+## Whole-table summary
+
+```json
+{
+  "dimensions": [],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "strict_full": true
+}
+```
+
+## Distribution / ranking
+
+```json
+{
+  "dimensions": [
+    { "field_id": 9500572, "alias": "报价类型" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "sort": [
+    { "by": "记录数", "order": "desc" }
+  ],
+  "limit": 50,
+  "strict_full": true
+}
+```
+
+## Time-filtered distribution
+
+```json
+{
+  "app_key": "YOUR_APP_KEY",
+  "dimensions": [
+    { "field_id": 9500572, "alias": "维度名" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "filters": [
+    { "field_id": 3, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
+  ],
+  "sort": [
+    { "by": "记录数", "order": "desc" }
+  ],
+  "limit": 50,
+  "strict_full": true
+}
+```
+
+## Monthly trend
+
+```json
+{
+  "dimensions": [
+    { "field_id": 3, "alias": "月份", "bucket": "month" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "sort": [
+    { "by": "月份", "order": "asc" }
+  ],
+  "limit": 24,
+  "strict_full": true
+}
+```
+
+## Cross analysis with sum
+
+```json
+{
+  "dimensions": [
+    { "field_id": 2, "alias": "状态" },
+    { "field_id": 5, "alias": "负责人" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" },
+    { "op": "sum", "field_id": 7, "alias": "总金额" }
+  ],
+  "sort": [
+    { "by": "记录数", "order": "desc" }
+  ],
+  "limit": 100,
+  "strict_full": true
+}
+```

package/skills/qingflow-record-crud/SKILL.md

@@ -9,44 +9,16 @@ metadata:
 
 ## Overview
 
-This skill is for **record CRUD only** inside existing Qingflow apps.
-
-Use it for:
-
-- record browsing
-- record detail lookup
-- record create / update / delete
-- attachment preflight before a write
-- relation/member/department lookup that directly supports a write
-
-Do **not** use this skill for:
-
-- grouped analysis, ratios, rankings, trends, or final statistical conclusions  
-  Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
-- task-center workflow actions, comments, or directory-driven operational workflows  
-  Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
-
-This skill assumes the MCP is already connected, authenticated, and bound to the correct workspace.  
-If not, switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md) first.
-
-Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md).  
-If the user did not specify one, default to `prod`.
+This skill is for record CRUD only inside existing Qingflow apps.
+Assumes MCP is connected, authenticated, and on the correct workspace.
 
 ## Default Paths
 
 Use exactly one of these default paths:
 
-1. Browse records  
-   `record_schema_get -> record_list`
-
-2. Read one record  
-   `record_schema_get -> record_get`
-
-3. Write records  
-   `record_schema_get -> record_write`
-
-4. Analysis  
-   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+1. Browse records: `record_schema_get -> record_list`
+2. Read one record: `record_schema_get -> record_get`
+3. Write records: `record_schema_get -> record_write`
 
 ## Core Tools
 
@@ -55,16 +27,14 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
-`record_schema_get` now returns the **current user's applicant-node schema only**:
-
-- only fields visible to the current user at the applicant node are returned
-- hidden fields are omitted entirely
-- missing fields should be treated as `当前用户在申请人节点下不可见/不可用`, not as a reason to guess a different field
+`record_schema_get` only exposes the current user's applicant-node visible fields; if a field is missing, treat it as unavailable in the current permission scope.
 
 ## Supporting Tools
 
 - `app_list`
 - `app_search`
+- `record_member_candidates`
+- `record_department_candidates`
 - `directory_search`
 - `directory_list_internal_users`
 - `directory_list_internal_departments`
@@ -90,15 +60,7 @@ Use exactly one of these default paths:
 - Use `record_list` for browse/export/sample inspection only
 - Use `record_get` when `record_id` is known
 - `record_get` without explicit `columns` still returns only applicant-node visible fields; do not assume it exposes the full builder-side record
-- `record_list` accepts:
-  - `columns`
-  - `where`
-  - `order_by`
-  - `limit`
-  - `page`
 - `record_list` and `record_get` may reject hidden-field `field_id`s because record tools now validate against the applicant-node visible schema only
-- `record_list` is **not** an analysis tool
-- If a request turns into grouped distributions, ratios, rankings, trends, or final statistical conclusions, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 
 ## Record Write Rules
 
@@ -108,51 +70,24 @@ Use `record_write` as the only default write tool.
 
 1. Run `record_schema_get`
 2. Decide whether the task is `insert`, `update`, or `delete`
-3. Build SQL-like JSON clauses
-4. Run `record_write`
-5. If `ok=false`, explain `field_errors` first, then summarize blockers; do not report a write as executed
-6. If `ok=true`, report the affected `record_id` or created resource
-7. For important writes, keep `verify_write=true`
+3. For relation fields, read `target_app_key / target_app_name` from schema first
+4. For member fields with unknown ids, run `record_member_candidates`
+5. For department fields with unknown ids, run `record_department_candidates`
+6. Build SQL-like JSON clauses
+7. Run `record_write`
+8. If `ok=false`, explain `field_errors` first, then summarize blockers; do not report a write as executed
+9. If `ok=true`, report the affected `record_id` or created resource
+10. For important writes, keep `verify_write=true`
 
 ### SQL-like JSON DSL
 
 The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 
-#### Insert
-
-```json
-{
-  "operation": "insert",
-  "values": [
-    { "field_id": 12, "value": "测试客户" },
-    { "field_id": 18, "value": 1000 }
-  ],
-  "submit_type": "submit",
-  "verify_write": true
-}
-```
-
-#### Update
-
-```json
-{
-  "operation": "update",
-  "record_id": 123,
-  "set": [
-    { "field_id": 18, "value": 2000 }
-  ],
-  "verify_write": true
-}
-```
-
-#### Delete
-
-```json
-{
-  "operation": "delete",
-  "record_ids": [123, 124]
-}
-```
+| operation | required shape | compact example |
+|-----------|----------------|-----------------|
+| `insert` | `values` | `{"operation":"insert","values":[{"field_id":12,"value":"测试客户"}]}` |
+| `update` | `record_id + set` | `{"operation":"update","record_id":123,"set":[{"field_id":18,"value":2000}]}` |
+| `delete` | `record_id` or `record_ids` | `{"operation":"delete","record_ids":[123,124]}` |
 
 ### Write discipline
 
@@ -164,7 +99,9 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Do not use free-form `WHERE` updates or deletes
 - Do not auto-fill missing fields
 - Do not auto-resolve relation targets without first querying them
-- Do not assume `record_schema_get` is a builder/full-field schema. It is the current user's applicant-node visible schema only.
+- Do not assume member display names resolve automatically; `record_member_candidates` returns ids, but direct name-to-id write is not automatic
+- Do not assume department names resolve automatically; `record_department_candidates` returns ids, but direct name-to-id write is not automatic
+- Do not assume `record_schema_get` is a builder/full-field schema.
 
 ## Response Interpretation
 
@@ -173,12 +110,10 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - If `record_write` returns `ok=false`, the write was blocked and not executed
 - Prefer explaining `field_errors` before summarizing top-level blockers
 - If `record_write` returns `ok=true`, still check `verification` and `warnings` before claiming success
-- Treat `request_route` as the source of truth for live route debugging
 - Prefer canonical schema titles and aliases in your final wording
 - If only part of the requested work is completed, explicitly disclose which parts are done and which are not
 
 ## Resources
 
-- Environment switching: [references/environments.md](references/environments.md)
 - Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
 - Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)

package/skills/qingflow-task-ops/SKILL.md

@@ -9,29 +9,8 @@ metadata:
 
 ## Overview
 
-This skill is for **task-center and workflow usage operations** inside existing Qingflow apps.
-
-Use it for:
-
-- task-center browsing
-- headline task counts
-- grouped worksheet or workflow-node workload views
-- approve / reject / rollback / transfer / urge
-- record comments
-- directory lookup that supports task or comment actions
-
-Do **not** use this skill for:
-
-- record create / update / delete  
-  Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
-- grouped analysis, ratios, rankings, trends, or final statistical conclusions  
-  Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
-
-This skill assumes the MCP is already connected, authenticated, and bound to the correct workspace.  
-If not, switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md) first.
-
-Before operating on live work, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md).  
-If the user did not specify one, default to `prod`.
+This skill is for task-center and workflow usage operations only.
+Assumes MCP is connected, authenticated, and on the correct workspace.
 
 ## Default Paths
 
@@ -143,6 +122,4 @@ Use exactly one of these default paths:
 
 ## Resources
 
-- Environment switching: [references/environments.md](references/environments.md)
 - Workflow and task usage actions: [references/workflow-usage.md](references/workflow-usage.md)
-

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b25"
+__version__ = "0.2.0b27"

package/src/qingflow_mcp/server.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
@@ -23,25 +25,88 @@ from .tools.workspace_tools import WorkspaceTools
 
 
 def build_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow MCP",
-        instructions=(
-            "Use auth_login first, then workspace_list and workspace_select. "
-            "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
-            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
-            "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
-            "then call record_analyze. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
-            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
-            "For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply and refuses fields outside the applicant-node writable schema.\n\n"
-            "Task Center (待办/已办) handling:\n"
-            "- Use task_summary to get headline counts.\n"
-            "- Use task_list for flat task browsing with task_box and flow_status.\n"
-            "- Use task_facets when worksheet or workflow-node buckets matter.\n"
-            "- Use task_mark_read to mark a specific task as read.\n"
-            "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- After identifying the exact task node and record, use task_approve, task_reject, task_rollback, or task_transfer as needed."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## Authentication
+
+Use `auth_login` first, then `workspace_list` and `workspace_select`.
+All resource tools operate with the logged-in user's Qingflow permissions.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+
+## Schema-First Rule
+
+Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_schema_get` returns the current user's applicant-node visible fields only.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+
+## Analytics Path
+
+`record_schema_get -> record_analyze`
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`record_schema_get -> record_list / record_get / record_write`
+
+`record_write` uses SQL-like JSON clauses:
+
+- `insert` -> `values`
+- `update` -> `record_id + set`
+- `delete` -> `record_id` or `record_ids`
+
+- Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
+- If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
+
+## Task Center Path
+
+`task_summary -> task_list / task_facets -> task action`
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.""",
     )
     sessions = SessionStore()
     backend = BackendClient()