@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

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

@@ -20,8 +20,8 @@ Reviewer 的工具白名单已物理强制此规则：你无 Edit/Write 权限
 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 步流程）
@@ -34,26 +34,29 @@ Reviewer 的工具白名单已物理强制此规则：你无 Edit/Write 权限
 证据，禁止只凭静态代码阅读下结论。所有取证在 Phase 1 内完成（Reviewer 的
 Phase 3 禁止工具调用规则不变）。
 
-1. **加载命令手册**：Glob 定位 `**/miaoda-cli/references/observability.md`
-   并用 Read 加载——完整 flag / 默认值以该文档为准，不要凭记忆拼命令。
-   找不到该文件 → 当前栈不支持线上日志查询，在报告里注明
+1. **加载命令手册**：Glob 定位当前沙箱的线上观测手册，依次试
+   `**/lark-apps-ops/references/lark-apps-observability.md` 和
+   `**/miaoda-cli/references/observability.md`，命中哪份就用 Read 加载哪份。
+   完整命令 / 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 小时）；有关键词或具体接口时，按手册支持的方式收窄
+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/lark-apps/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: lark-apps
+description: "在妙搭沙箱里用 lark-cli 操作【当前这个已存在的】妙搭应用：开放 API Key。当用户要在沙箱里对当前应用做这些操作时使用（可用能力以本次打包的模块为准）。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +<cmd> --help"
+control-by-feature-ab: true
+---
+
+# 妙搭应用 (apps) · 沙箱版
+
+在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用。
+
+## 沙箱约定（先读）
+
+- **命令名**：一律 `lark-cli apps +<cmd>`；命令/flag 细节以 `--help` 为准。
+- **应用已存在、app_id 走环境变量**：应用 id 在环境变量 `app_id` 里，命令需要 `--app-id` 时用 `--app-id "$app_id"`。
+- **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
+
+## 意图路由
+
+| 用户意图 | 命令 | 详情 |
+|---|---|---|
+| 管理开放 API Key（列/查/建/改/启停/删/轮换） | `+openapi-key-list` / `+openapi-key-get` / `+openapi-key-create` / `+openapi-key-update` / `+openapi-key-enable` / `+openapi-key-disable` / `+openapi-key-delete` / `+openapi-key-reset` | [openapi-key](references/openapi-key.md) ⚠️ create/reset 密钥一次性可见；delete/reset 高风险 |
+
+
+## 失败处理
+命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。
+
+## 高风险写操作审批（exit 10）
+`risk: high-risk-write` 的命令不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
+1. 识别 exit code=10 且 `error.type=="confirmation_required"`；
+2. 把 `error.risk.action` + 关键参数给用户，明确"高风险"，等显式同意；
+3. 同意 → 原始 argv 末尾加 `--yes` 重试；拒绝 → 终止；
+4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）。
+**绝不**看到 exit 10 就默认补 `--yes` 静默重试。

package/miaoda/lark-apps/references/openapi-key.md

@@ -0,0 +1,80 @@
+# apps openapi-key 命令族（开放 API Key）
+
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
+
+## 命令路由
+
+| 命令 | 用途 |
+|---|---|
+| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
+| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
+| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
+| `+openapi-key-update` | 改名或改 config（不改 status） |
+| `+openapi-key-enable` | 启用 Key（status→1） |
+| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
+| `+openapi-key-delete` | 永久删除 Key（不可逆，高风险） |
+| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见**（高风险） |
+
+命令均带 `--app-id "$app_id"`（当前沙箱应用），如：
+
+```bash
+lark-cli apps +openapi-key-list --app-id "$app_id"
+```
+
+## 密钥红线（安全关键，务必遵守）
+
+- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 lark-cli 保存，请立即复制到你自己的密钥管理器）。
+- **绝不**把原始密钥写入 cache / config / recent / debug log / 错误信息，也不要在后续对话里回显完整密钥；只向用户转述一次并提示自行妥善保管。
+- **密钥丢失不能找回**：`list` / `get` 不回显原始密钥。唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
+
+## 脱敏口径
+
+- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
+- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次（见上「密钥红线」）。
+
+## scope 结构与 CLI 表达
+
+后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：
+
+```json
+{
+  "allow_all": true,
+  "http_infos": [
+    { "http_method": "GET", "http_path": "/openapi/some-path" }
+  ]
+}
+```
+
+- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
+- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。
+
+CLI 提供三种互斥的 scope 表达方式：
+
+| flag | 用途 | 备注 |
+|---|---|---|
+| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
+| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
+| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |
+
+### scope 值来源
+
+妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。
+
+## 高风险操作（delete / reset）
+
+`delete` 和 `reset` 是高风险写操作（`high-risk-write`）：缺 `--yes` 会 **exit 10**（`confirmation_required`），须按 SKILL.md 的 exit-10 审批协议先征得用户显式同意再补 `--yes`——**不要**自动补 `--yes`；不确定先 `--dry-run` 查看将执行的 HTTP 请求（不含密钥）。
+
+- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 `+openapi-key-enable` 恢复，delete 不可逆。
+
+## 典型决策场景
+
+| 用户意图 | 正确操作 |
+|---|---|
+| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
+| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
+| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
+| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |
+
+## 不在本 skill 范围
+
+- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。