@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f3f0e48

package/miaoda/data-analysis/references/python-analysis-reference.md

@@ -0,0 +1,272 @@
+# Python Code Standards & Templates
+
+## Recommended Libraries
+
+```python
+import pandas as pd        # Data processing
+import numpy as np         # Numerical computation
+from scipy import stats    # Statistical analysis
+from datetime import datetime
+import json
+import uuid
+```
+
+## Phase-Specific Code Templates
+
+### Phase 2: Data Understanding
+
+```python
+import pandas as pd
+
+df = pd.read_csv('data.csv')  # or pd.read_excel(), pd.read_json()
+
+print(f"Shape: {df.shape}")
+print(f"Columns: {df.columns.tolist()}")
+print(f"Dtypes:\n{df.dtypes}")
+print(f"Head:\n{df.head()}")
+```
+
+### Phase 3: Data Quality Assessment
+
+```python
+# Missing values
+missing = df.isnull().sum()
+missing_pct = (missing / len(df) * 100).round(2)
+print(f"Missing values:\n{missing[missing > 0]}")
+
+# Duplicate rows
+duplicates = df.duplicated().sum()
+print(f"Duplicate rows: {duplicates}")
+
+# Numeric outliers (IQR)
+def detect_outliers_iqr(series):
+    Q1, Q3 = series.quantile([0.25, 0.75])
+    IQR = Q3 - Q1
+    lower, upper = Q1 - 1.5 * IQR, Q3 + 1.5 * IQR
+    return ((series < lower) | (series > upper)).sum()
+
+for col in df.select_dtypes(include='number').columns:
+    outliers = detect_outliers_iqr(df[col])
+    if outliers > 0:
+        print(f"{col}: {outliers} outliers")
+```
+
+### Phase 4: Descriptive Analysis
+
+```python
+# 4.1 Numeric variables
+numeric_stats = df.describe(percentiles=[0.25, 0.5, 0.75]).T
+numeric_stats['skew'] = df.select_dtypes(include='number').skew()
+numeric_stats['kurtosis'] = df.select_dtypes(include='number').kurtosis()
+
+# 4.2 Categorical variables
+for col in df.select_dtypes(include='object').columns:
+    print(f"\n{col}:")
+    print(f"  Unique: {df[col].nunique()}")
+    print(f"  Top values:\n{df[col].value_counts().head()}")
+
+# 4.3 Correlation analysis (Pearson)
+import numpy as np
+correlation_matrix = df.select_dtypes(include='number').corr(method='pearson')
+corr_pairs = []
+for i in range(len(correlation_matrix.columns)):
+    for j in range(i+1, len(correlation_matrix.columns)):
+        r = correlation_matrix.iloc[i, j]
+        if abs(r) > 0.7:
+            corr_pairs.append({
+                'col1': correlation_matrix.columns[i],
+                'col2': correlation_matrix.columns[j],
+                'correlation': round(r, 3)
+            })
+
+# 4.4 Group aggregation
+grouped = df.groupby('category_column').agg({
+    'numeric_col1': ['mean', 'std', 'count'],
+    'numeric_col2': ['mean', 'std', 'count']
+})
+```
+
+## Complete Analysis Template
+
+```python
+import pandas as pd
+import numpy as np
+from scipy import stats
+import json
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+
+def setup_tmp_dirs(project_root: Path = None) -> dict:
+    """Initialize tmp directory structure for analysis artifacts."""
+    if project_root is None:
+        project_root = Path.cwd()
+
+    tmp_dir = project_root / "tmp"
+    paths = {
+        "root": tmp_dir,
+        "scripts": tmp_dir / "analysis_scripts",
+        "intermediate": tmp_dir / "intermediate",
+        "output": tmp_dir / "output",
+        "visualizations": tmp_dir / "output" / "visualizations",
+    }
+
+    for path in paths.values():
+        path.mkdir(parents=True, exist_ok=True)
+
+    return paths
+
+
+def analyze_data(file_path: str, analysis_type: str = "exploratory",
+                 project_root: Path = None) -> dict:
+    """
+    Execute complete data analysis workflow.
+
+    Args:
+        file_path: Data file path
+        analysis_type: exploratory/confirmatory/diagnostic/descriptive
+        project_root: Project root for tmp directory. Defaults to cwd.
+
+    Returns:
+        Analysis result JSON conforming to specification
+    """
+    # 0. Setup tmp directories
+    tmp_paths = setup_tmp_dirs(project_root)
+
+    # 1. Load data
+    if file_path.endswith('.csv'):
+        df = pd.read_csv(file_path)
+    elif file_path.endswith(('.xls', '.xlsx')):
+        df = pd.read_excel(file_path)
+    elif file_path.endswith('.json'):
+        df = pd.read_json(file_path)
+    else:
+        raise ValueError(f"Unsupported file format: {file_path}")
+
+    # 2. Initialize result structure
+    result = {
+        "analysis_id": str(uuid.uuid4()),
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "metadata": {
+            "data_source": file_path,
+            "row_count": len(df),
+            "column_count": len(df.columns),
+            "analysis_type": analysis_type
+        },
+        "data_quality": {},
+        "statistics": {},
+        "insights": [],
+        "recommendations": [],
+        "visualizations": []
+    }
+
+    # 3. Data quality assessment
+    missing = df.isnull().sum()
+    result["data_quality"] = {
+        "completeness": round(1 - df.isnull().sum().sum() / df.size, 4),
+        "missing_values": {k: int(v) for k, v in missing[missing > 0].items()},
+        "duplicates": int(df.duplicated().sum()),
+        "outliers": {},
+        "issues": []
+    }
+
+    for col in df.select_dtypes(include='number').columns:
+        Q1, Q3 = df[col].quantile([0.25, 0.75])
+        IQR = Q3 - Q1
+        outlier_count = int(((df[col] < Q1 - 1.5 * IQR) | (df[col] > Q3 + 1.5 * IQR)).sum())
+        if outlier_count > 0:
+            result["data_quality"]["outliers"][col] = outlier_count
+
+    # 4. Descriptive statistics - Numeric
+    numeric_cols = df.select_dtypes(include='number').columns
+    if len(numeric_cols) > 0:
+        result["statistics"]["numeric_summary"] = {}
+        for col in numeric_cols:
+            series = df[col].dropna()
+            result["statistics"]["numeric_summary"][col] = {
+                "count": int(series.count()),
+                "mean": round(float(series.mean()), 4),
+                "std": round(float(series.std()), 4),
+                "min": round(float(series.min()), 4),
+                "max": round(float(series.max()), 4),
+                "quartiles": [
+                    round(float(series.quantile(0.25)), 4),
+                    round(float(series.quantile(0.50)), 4),
+                    round(float(series.quantile(0.75)), 4)
+                ],
+                "skew": round(float(series.skew()), 4),
+                "kurtosis": round(float(series.kurtosis()), 4)
+            }
+
+    # Categorical
+    categorical_cols = df.select_dtypes(include=['object', 'category']).columns
+    if len(categorical_cols) > 0:
+        result["statistics"]["categorical_summary"] = {}
+        for col in categorical_cols:
+            value_counts = df[col].value_counts()
+            total = len(df[col].dropna())
+            result["statistics"]["categorical_summary"][col] = {
+                "unique_count": int(df[col].nunique()),
+                "top_values": [
+                    {
+                        "value": str(idx),
+                        "count": int(cnt),
+                        "percentage": round(cnt / total * 100, 2)
+                    }
+                    for idx, cnt in value_counts.head(5).items()
+                ],
+                "mode": str(value_counts.index[0]) if len(value_counts) > 0 else None
+            }
+
+    # 5. Correlation analysis
+    if len(numeric_cols) > 1:
+        corr_matrix = df[numeric_cols].corr()
+        correlations = []
+        for i in range(len(numeric_cols)):
+            for j in range(i + 1, len(numeric_cols)):
+                r = corr_matrix.iloc[i, j]
+                if abs(r) > 0.5:
+                    correlations.append({
+                        "column1": numeric_cols[i],
+                        "column2": numeric_cols[j],
+                        "coefficient": round(float(r), 4),
+                        "method": "pearson"
+                    })
+        if correlations:
+            result["statistics"]["correlations"] = correlations
+
+    # 6. Save output (MUST sanitize NaN/Infinity before dumping)
+    base_name = Path(file_path).stem
+    output_file = tmp_paths["output"] / f"{base_name}_{analysis_type}.json"
+
+    def sanitize_for_json(obj):
+        """Replace NaN/Infinity with None to produce valid JSON."""
+        if isinstance(obj, float) and (np.isnan(obj) or np.isinf(obj)):
+            return None
+        if isinstance(obj, dict):
+            return {k: sanitize_for_json(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [sanitize_for_json(v) for v in obj]
+        return obj
+
+    result = sanitize_for_json(result)
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(result, f, indent=2, ensure_ascii=False, allow_nan=False)
+    print(f"Analysis result saved to: {output_file}")
+
+    return result
+
+
+def save_visualization(fig, viz_id: str, tmp_paths: dict, format: str = "png"):
+    """Save matplotlib/seaborn figure to tmp/output/visualizations."""
+    output_path = tmp_paths["visualizations"] / f"{viz_id}.{format}"
+    fig.savefig(output_path, dpi=150, bbox_inches='tight')
+    print(f"Visualization saved to: {output_path}")
+    return output_path
+
+
+# Usage:
+# result = analyze_data("sales_2023.csv", "exploratory")
+# print(json.dumps(result, indent=2, ensure_ascii=False))
+```

package/miaoda/data-analysis/references/tmp-file-management-guide.md

@@ -0,0 +1,100 @@
+# Temporary File Management
+
+All temporary code and intermediate artifacts generated during analysis should be written to the project's `tmp/` directory.
+
+## Directory Structure
+
+```text
+<project_root>/
+├── tmp/                          # Analysis temp directory
+│   ├── analysis_scripts/         # Temporary analysis scripts
+│   │   └── sales_2023_analysis.py
+│   ├── intermediate/             # Intermediate artifacts
+│   │   ├── sales_2023_cleaned.csv
+│   │   └── sales_2023_correlation.csv
+│   └── output/                   # Final analysis output
+│       ├── sales_2023_analysis.json
+│       └── visualizations/
+│           ├── sales_2023_age_vs_amount.png
+│           └── sales_2023_amount_distribution.png
+```
+
+## Semantic File Naming
+
+| Pattern | Example | Description |
+| ------- | ------- | ----------- |
+| `{dataset}_{purpose}.py` | `sales_2023_analysis.py` | Analysis script |
+| `{dataset}_{stage}.csv` | `sales_2023_cleaned.csv` | Intermediate data |
+| `{dataset}_{analysis_type}.json` | `sales_2023_exploratory.json` | Analysis result |
+| `{dataset}_{chart_desc}.png` | `sales_2023_age_vs_amount.png` | Visualization |
+
+**Best practices**:
+- Derive base name from source file: `sales_2023.csv` → `sales_2023_*`
+- Include analysis focus: `sales_2023_correlation.json`, `sales_2023_outliers.json`
+- Use snake_case for consistency
+- Avoid UUIDs or timestamps in primary filenames (use for deduplication only if needed)
+
+## Usage Guidelines
+
+1. **Create directories on first use**:
+   ```python
+   from pathlib import Path
+
+   project_root = Path.cwd()
+   tmp_dir = project_root / "tmp"
+
+   (tmp_dir / "analysis_scripts").mkdir(parents=True, exist_ok=True)
+   (tmp_dir / "intermediate").mkdir(parents=True, exist_ok=True)
+   (tmp_dir / "output" / "visualizations").mkdir(parents=True, exist_ok=True)
+   ```
+
+2. **Script naming**: Use semantic names based on dataset and purpose
+   ```python
+   source_file = "sales_2023.csv"
+   base_name = Path(source_file).stem  # "sales_2023"
+   script_path = tmp_dir / "analysis_scripts" / f"{base_name}_analysis.py"
+   ```
+
+3. **Intermediate artifacts**: Write cleaned data, transformed results to `tmp/intermediate/`
+
+4. **Final output**: Write JSON results and visualizations to `tmp/output/`
+
+5. **gitignore**: Ensure `tmp/` is added to `.gitignore`
+
+## Why Use Project tmp/ Directory
+
+| Benefit | Description |
+| ------- | ----------- |
+| Traceable | Artifacts are associated with the project for easy review |
+| Reproducible | Intermediate scripts are retained for re-execution and verification |
+| Isolated | Does not pollute system temp directories |
+| Easy cleanup | Delete `tmp/` to remove all analysis artifacts at once |
+
+## Copying Output to shared/static/
+
+When the analysis JSON needs to be consumed by application code, copy it from `tmp/output/` to `shared/static/`:
+
+```python
+import shutil
+from pathlib import Path
+
+def export_to_shared(analysis_file: Path, dest_dir: Path = None, filename: str = None):
+    """Copy analysis result JSON to shared/static/ for downstream code consumption."""
+    if dest_dir is None:
+        dest_dir = Path("shared/static")
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_file = dest_dir / (filename or analysis_file.name)
+    shutil.copy2(analysis_file, dest_file)
+    print(f"Exported to: {dest_file}")
+    return dest_file
+
+# Example:
+# export_to_shared(Path("tmp/output/sales_2023_exploratory.json"))
+# → shared/static/sales_2023_exploratory.json
+# Import in code: import analysisData from '@shared/static/sales_2023_exploratory.json'
+```
+
+**Best practices**:
+- Only copy finalized, validated results to `shared/static/`
+- Keep `tmp/` for iterative work; export to `shared/` only when analysis is complete
+- Use descriptive filenames (e.g., `sales_q4_analysis.json` not `analysis_a1b2c3d4.json`)

package/miaoda/debug-investigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via read_file) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
+description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via the Skill tool) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
 available-agents:
   - Reviewer
 ---
@@ -15,45 +15,57 @@ Reviewer 的工具白名单已物理强制此规则：你无 Edit/Write 权限
 # Phase 1 — Root Cause Investigation (必做)
 
 1. 读 caller prompt 提取症状：What / When / Where / 触发条件，并判定症状
-   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。caller 出现
-   线上 / 发布后 / 线上用户反馈 / production / online 等表述 → 按线上处理
+   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。从 caller 转述的用户
+   原话判断：出现 线上 / 发布后 / 线上用户反馈 / production / online 等表述 →
+   按线上处理；用户描述的是应用使用者看到的现象，或判断不了 → 两条链路都查
+   （都是只读）
 2. 日志证据（按环境选链路，两条链路日志互不相通）：
    - **沙箱 dev 态** → ReadLogs browser / server-devserver / client-devserver /
      server，找对应错误栈、请求 / 响应、console error
-   - **线上（已发布）** → 见下方「Phase 1 子步骤：线上异常取证」，用
-     `miaoda observability` 拉线上日志。ReadLogs 读不到线上日志——
+   - **线上（已发布）** → 见下方「Phase 1 子步骤：线上异常取证」，按当前沙箱
+     的线上观测手册拉线上日志。ReadLogs 读不到线上日志——
      不要拿沙箱日志当线上症状的证据
+   - 一条链路查不到事件痕迹（没有对应请求、没有报错）时，不要下「无法考证」的
+     结论：事件多半发生在另一条链路，先查另一条。数据库查询、审计开关只反映
+     当前状态，说明不了是谁、何时改的
 3. 近期改动：`git log --oneline -20 <suspected_file>`，必要时看 `git show <sha>`
 4. 数据流反向追溯（见下方 5 步流程）
 5. 跨组件证据：即使没法 runtime 埋点，也要在报告里列清每层"当前行为 vs
    期望行为"，指出断点
 
-## Phase 1 子步骤：线上异常取证（caller 明确描述线上异常时必做）
+## Phase 1 子步骤：线上异常取证（第 1 步判定需要查线上时必做）
 
-当 caller 明确描述**线上（已发布）环境**的异常表现时，必须拉取线上日志作为
+当第 1 步判定需要查**线上（已发布应用）**时，必须拉取线上日志作为
 证据，禁止只凭静态代码阅读下结论。所有取证在 Phase 1 内完成（Reviewer 的
 Phase 3 禁止工具调用规则不变）。
 
-1. **加载命令手册**：Glob 定位 `**/miaoda-cli/references/observability.md`
-   并用 Read 加载——完整 flag / 默认值以该文档为准，不要凭记忆拼命令。
-   找不到该文件 → 当前栈不支持线上日志查询，在报告里注明
+1. **加载命令手册**：在 Available Skills 里找 `lark-apps-ops` 或 `miaoda-cli`，
+   按其 location 推出同目录下的 `references/lark-apps-observability.md` /
+   `references/observability.md`，用 Read 加载存在的那份（不要用 Glob / rg
+   在文件系统里搜：`.agent/` 被应用 .gitignore 忽略，会搜不到）。
+   完整命令 / flag / 默认值一律以该文档为准，不要凭记忆拼命令。
+   两份都找不到 → 当前栈不支持线上日志查询，在报告里注明
    「线上日志不可用」，回退沙箱日志 + 静态分析，不阻塞调查
-2. **错误日志**：`miaoda observability log --since <时间窗> --level ERROR`，
-   时间窗按 caller 描述的发生时间收敛（如 `--since 1h`）；有关键词时加
-   `--grep "<keyword>"`，接口类症状加 `--api <path>`
-3. **链路追溯**：从日志取 `trace_id` → `miaoda observability trace get <traceID>`
-   看完整调用链，定位慢点 / 失败环节
-4. **前端报错反解源码**：日志含前端错误时，
-   `miaoda observability source-stack --log-id <id>`（或 `--trace-id <id>`）
-   反解出 `file:line`，作为证据链入口
+2. **错误日志**：按手册的日志检索条目拉 ERROR 级日志，时间窗按 caller 描述
+   的发生时间收敛（如最近 1 小时）；有关键词或具体接口时，按手册支持的方式收窄
+   **请求追溯**：要找某个数据 / 资源被哪个请求改动时，不限 ERROR 级，按资源
+   id、标题、关键词或接口路径加时间窗检索；日志条目带时间戳、method、path、
+   user_id、trace_id，可直接回答「哪个请求、谁、何时」
+3. **链路追溯**：从日志取 `trace_id`，按手册的 trace 检索条目看完整调用链，
+   定位慢点 / 失败环节
+4. **前端报错反解源码**：日志含前端错误时，按手册的前端源码反解条目拿到
+   `file:line` 作为证据链入口。**手册没有这条能力就跳过并在报告里注明**——
+   部分通道没有独立的源码反解命令，源码位置只可能作为日志详情的附带字段出现，
+   不要臆造命令名或 flag
 5. **证据链标注来源**：报告中每条日志证据必须标注来源
-   （`线上 observability` / `沙箱 ReadLogs`）+ 日志时间戳，
-   线上症状必须有至少一条线上日志证据支撑。两个例外都不阻塞调查，
+   （`线上观测` / `沙箱 ReadLogs`）+ 日志时间戳，
+   线上症状必须有至少一条线上日志证据支撑。三个例外都不阻塞调查，
    在报告里注明即可：① 第 1 步已注明「线上日志不可用」；
-   ② 查询成功但结果为空（注明查询命令与时间窗，回到静态分析）
+   ② 第 4 步手册未提供源码反解能力；
+   ③ 查询成功但结果为空（注明查询条件与时间窗，回到静态分析）
 
-> `miaoda observability` 全部为只读查询。不要使用 `miaoda deploy` /
-> `miaoda app update` 等有副作用的命令——那不是 Reviewer 的职责。
+> 线上观测类查询全部为只读。不要使用触发发布 / 修改应用元数据等有副作用的
+> 命令——那不是 Reviewer 的职责。
 
 ## Phase 1 子步骤：5 步反向追溯
 

package/miaoda/extract-json-schema/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: extract-json-schema
+description: "Extract concise JSON schema with semantic field descriptions from JSON data. Use when: (1) analyzing JSON structure for documentation, (2) generating schema for API/data contracts, (3) creating field-level documentation for programmatic use, (4) understanding complex nested JSON data. Keywords: JSON schema, 提取schema, 字段说明, field description, data structure, 数据结构分析"
+---
+
+# Extract JSON Schema
+
+从 JSON 数据中提取精简的 schema 信息，包含语义化的字段解释，便于程序化处理和集成。
+
+---
+
+## Schema 输出规范
+
+输出必须符合 `extracted-json-schema/v1` 格式：
+
+```json
+{
+  "$schema": "extracted-json-schema/v1",
+  "title": "数据集名称",
+  "description": "数据集整体描述",
+  "source": "数据来源（可选）",
+  "extracted_at": "ISO 8601 时间",
+  "root_type": "object | array",
+  "fields": [
+    {
+      "path": "字段路径（如 order.items[].price）",
+      "type": "string | number | boolean | object | array | null | mixed",
+      "element_type": "数组元素类型（仅 array 需要）",
+      "nullable": false,
+      "description": "语义化中文描述（核心字段）",
+      "example": "示例值",
+      "enum": ["枚举值（如有）"],
+      "format": "date | datetime | currency | percentage | url | email | uuid 等",
+      "unit": "元 | % | 天 等",
+      "children": ["子字段路径列表（仅 object/array）"]
+    }
+  ],
+  "statistics": {
+    "total_fields": 0, "max_depth": 0, "object_count": 0, "array_count": 0
+  }
+}
+```
+
+### 类型与格式速查
+
+| JSON 值 | type | 常见 format | unit |
+|---------|------|------------|------|
+| `"text"` | `string` | date, datetime, period, email, url, uuid | — |
+| `123` / `1.5` | `number` | currency, percentage, ratio | 元, %, 天 |
+| `true` | `boolean` | — | — |
+| `{}` | `object` | — | — |
+| `[]` | `array` | — | — |
+| `null` | `null` | — | — |
+| 混合类型 | `mixed` | — | — |
+
+---
+
+## 语义化描述规范
+
+描述是 schema 的核心价值。每个字段的 description 必须说明**业务含义**，而非重复字段名。
+
+| 字段类型 | 描述模板 | 差的描述 ❌ | 好的描述 ✅ |
+|----------|----------|-----------|-----------|
+| 标识字段 | [实体]的[唯一标识] | "标题" | "财务报告的标题，标识报告类型和时间范围" |
+| 数值字段 | [指标名称]，单位为[单位] | "数量" | "该产品线的营收金额，单位为元" |
+| 百分比字段 | [指标]的百分比/增长率 | "百分比" | "该产品线营收占总营收的百分比" |
+| 日期字段 | [事件]的[日期/时间] | "时间" | "订单创建的时间戳，UTC 格式" |
+| 状态字段 | [实体]的[状态]，可选值包括... | "状态" | "订单状态，可选值：paid, pending, cancelled" |
+
+描述编写原则：结合数据集上下文理解字段含义 → 参考同级字段关联性 → 使用业务语言而非技术术语。
+
+---
+
+## 提取流程
+
+```
+1. 确认输入 JSON（用户提供或从文件读取）
+   ↓
+2. 识别根类型（object/array），递归遍历所有字段
+   ↓
+3. 推断 type、format、unit（优先根据字段名，结合值验证）
+   ↓
+4. 生成语义化 description（核心步骤，参考上方规范）
+   ↓
+5. 构建扁平化 fields 列表 + 计算 statistics
+   ↓
+6. 输出 Schema JSON，保存到 tmp/output/<source>_schema.json
+```
+
+### 类型推断规则
+
+- 数组元素类型以第一个元素为准
+- 遇到 `null` 值时标记 `nullable: true`
+- 同一字段存在多种类型时标记为 `mixed`
+- format 不确定时不标注
+
+---
+
+## 示例
+
+**输入**：
+```json
+{"order_id": "ORD-001", "total_amount": 598.00, "items": [{"name": "无线耳机", "price": 299.00}]}
+```
+
+**输出（关键字段）**：
+```json
+{
+  "$schema": "extracted-json-schema/v1",
+  "title": "电商订单",
+  "fields": [
+    {"path": "order_id", "type": "string", "nullable": false, "description": "订单的唯一标识编号", "example": "ORD-001"},
+    {"path": "total_amount", "type": "number", "nullable": false, "description": "订单总金额", "example": 598.00, "format": "currency", "unit": "元"},
+    {"path": "items", "type": "array", "element_type": "object", "nullable": false, "description": "订单包含的商品列表", "children": ["items[]"]},
+    {"path": "items[].name", "type": "string", "nullable": false, "description": "商品名称", "example": "无线耳机"},
+    {"path": "items[].price", "type": "number", "nullable": false, "description": "商品单价", "example": 299.00, "format": "currency", "unit": "元"}
+  ],
+  "statistics": {"total_fields": 5, "max_depth": 2, "object_count": 2, "array_count": 1}
+}
+```
+
+---
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| description 只写字段名翻译（如 "名称"） | 结合业务上下文写语义描述（如 "产品线名称"） |
+| 数值字段不标注 unit | 金额标 "元"，百分比标 "%"，时长标 "天/ms" |
+| 数组类型缺 element_type | array 类型必须标注元素类型 |
+| object/array 缺 children | 必须列出子字段路径 |
+| 忘记 statistics 段 | 每次输出必须包含 total_fields, max_depth 等统计 |
+| format 乱标 | 不确定时不标注，优先根据字段名推断 |
+| 输出标准 JSON Schema (draft-07) | 本 skill 输出 extracted-json-schema/v1 格式，非标准 JSON Schema |
+
+---
+
+## Checklist
+
+输出前逐项确认：
+
+- [ ] 所有字段都有 description 且语义化（非字段名翻译）
+- [ ] type 与实际值匹配
+- [ ] array 类型有 element_type，object/array 有 children
+- [ ] 金额/百分比等数值有 format 和 unit
+- [ ] statistics 与实际字段数一致
+- [ ] $schema 为 "extracted-json-schema/v1"

package/miaoda/feishu/SKILL.md

@@ -143,14 +143,14 @@ npm install @larksuiteoapi/node-sdk
 
 ### FeishuService 单例
 
-> ⚠️ **凭证写入源码**：全栈框架不支持自定义环境变量，因此 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须直接写在源码常量中，**不要改为 `process.env`**。
+> ⚠️ **凭证直接写入源码常量**：妙搭全栈当前不提供这类飞书自建应用凭证的运行时环境变量注入。用户提供真实的 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 后，直接写入 `FeishuService` 源码常量；不要把它们称为环境变量，也不要改成 `process.env`。在用户提供凭证前，不生成真实值或占位值。
 
 ```typescript
 import { Injectable } from '@nestjs/common';
 import * as lark from '@larksuiteoapi/node-sdk';
 
-const FEISHU_APP_ID = 'cli_xxxx';      // ← 用户提供的真实值
-const FEISHU_APP_SECRET = 'xxxx';      // ← 用户提供的真实值
+const FEISHU_APP_ID = '用户提供的真实 App ID';
+const FEISHU_APP_SECRET = '用户提供的真实 App Secret';
 
 @Injectable()
 export class FeishuService {
@@ -258,7 +258,7 @@ for await (const items of await client.contact.user.listWithIterator({
 
 | 错误 | 正确做法 |
 |------|----------|
-| 将凭证改为 process.env 读取 | 全栈框架不支持自定义环境变量，凭证必须写入源码常量 |
+| 把凭证称为环境变量或改用 `process.env` | 按当前全栈平台契约，在用户提供真实凭证后写入 `FeishuService` 源码常量；未提供前不要生成代码中的凭证值 |
 | `content` 传对象而非 JSON 字符串 | `content: JSON.stringify({ text: 'hello' })` |
 | 每次请求都新建 `lark.Client` | NestJS `@Injectable()` 单例模式复用 |
 | `receive_id_type` 与 ID 前缀不匹配 | `oc_` → `chat_id`, `ou_` → `open_id`, `on_` → `union_id` |