diff --git a/.agents/skills/cz-cli-inner/SKILL.md b/.agents/skills/cz-cli-inner/SKILL.md new file mode 100644 index 0000000000..81b0ca7fa3 --- /dev/null +++ b/.agents/skills/cz-cli-inner/SKILL.md @@ -0,0 +1,50 @@ +--- +name: cz-cli-inner +description: Use when answering operational ClickZetta Studio or Lakehouse requests from inside a cz-cli-aware agent, including listing metadata, running SQL, managing tasks, checking runs, or operating datasource and AI Gateway resources. +--- + +# cz-cli Inner + +Use `cz-cli` proactively for ClickZetta operational requests. Do not ask for information that can be discovered with `cz-cli` commands. + +## Core Rules + +- Use `cz-cli` from `PATH` for Lakehouse and Studio operations. +- Run `cz-cli --help` when exact flags are unclear. +- Prefer `--format json` for machine-readable output and preserve `ai_message` guidance. +- Use `--profile ` when the user names an environment or profile. +- On `NO_PROFILE`, guide the user to run `cz-cli setup`. +- Stop after the same command fails twice or repeated minor variations make no progress; report what failed and change approach or ask for guidance. +- Never fabricate URLs, task IDs, run IDs, table names, or profile names. Use exact command output. + +## SQL Rules + +- Current default SQL mode is sync: `cz-cli sql "SELECT ..."` waits for results. +- Use `--async` for large or long-running queries, then inspect with `cz-cli sql status ` or `cz-cli job status `. +- Write operations always require `--write`, including DDL and DML. +- If SQL contains quotes, `$`, backticks, backslashes, or newlines, write it to a file and run `cz-cli sql -f ` to avoid shell corruption. +- Use ClickZetta Lakehouse SQL syntax only. Before generating, modifying, validating, explaining, or running non-trivial Lakehouse SQL, load the Lakehouse documentation skill if available. + +## Studio Task Rules + +- Always pass `--type` when creating tasks. +- Flow tasks use `cz-cli task flow *` commands for nodes; do not use normal task content/deploy commands on flow nodes. +- Merge tasks use `cz-cli task create --type MERGE` and `cz-cli task save-merge --dependency --status SUCCESS --status FAILED`; use `--status SKIPPED` only for upstream if/condition tasks. +- For standalone task runtime params, use `cz-cli task save-content --params '{"key":"value"}'` while saving script content, or `cz-cli task save-config --param key=value` to merge/update params without changing script content. +- `cz-cli task content ` returns saved `params`, and may also return `input_params` / `output_params` when the backend has those lists. +- For flow node params, use `cz-cli task flow node-save`: `--param key=value` for manual defaults, `--flow-param key` for values inherited from parent flow execution params, `--output-param key` to declare `$[output]`, and `--input-param key=upstreamNodeName` to consume an upstream node output. Bind the upstream dependency first so the upstream node can resolve from the DAG. +- Confirm intent before destructive or state-changing operations: deploy, undeploy, execute, delete, refill/backfill, stop, rerun, and similar actions. +- For historical reruns or backfills, use `cz-cli runs refill --from YYYY-MM-DD --to YYYY-MM-DD`; this is under `runs`, not `task`. +- For output table JSON flags such as `--output-tables`, pass the JSON array as one shell argument, usually with single quotes. + +## Output Handling + +- `--format json`: best for parsing. +- `--format toon`: line-per-field output, useful with `grep` or `head`. +- `--format table`, `--format csv`, `--format pretty`: human-readable. +- `--field `: extracts one field as raw text. +- Paginated list commands usually return page 1; check `ai_message` for next-page hints. + +## Command Reference + +Read `references/command-reference.md` when you need examples or command coverage beyond these core rules. diff --git a/.agents/skills/cz-cli-inner/references/command-reference.md b/.agents/skills/cz-cli-inner/references/command-reference.md new file mode 100644 index 0000000000..b9d68ac6ce --- /dev/null +++ b/.agents/skills/cz-cli-inner/references/command-reference.md @@ -0,0 +1,143 @@ +# cz-cli Command Reference + +Use `cz-cli --help` for authoritative options. This reference is a compact command map for common operations. + +## SQL and Jobs + +```bash +cz-cli sql "" # Execute SQL, sync by default +cz-cli sql "" --async # Return job_id immediately for large/long-running queries +cz-cli sql status # Check async SQL job status +cz-cli job status # Job status and summary +cz-cli job result # Fetch job result set +cz-cli job profile # Flattened job profile basics; use --raw for raw content +``` + +## Schemas and Tables + +```bash +cz-cli schema list [--like ] +cz-cli schema describe +cz-cli schema create +cz-cli schema drop + +cz-cli table list [--schema ] +cz-cli table describe +cz-cli table preview +cz-cli table stats +cz-cli table history [name] +cz-cli table create "" +cz-cli table drop +``` + +## Workspaces and Profiles + +```bash +cz-cli workspace current +cz-cli status +cz-cli profile list +``` + +## Studio Tasks + +```bash +cz-cli task list +cz-cli task create --type # SQL/PYTHON/SHELL/SPARK/FLOW/MERGE +cz-cli task content # Draft script, config, params, input_params, output_params +cz-cli task save-content --file # Save task script; --params JSON sets runtime params +cz-cli task save-config # Save non-cron config: retry, deps, VC, schema, timeout; --param key=value merges params +cz-cli task save-merge # Save MERGE rule content and upstream schedule dependencies +cz-cli task save-cron # Save cron schedule config +cz-cli task lineage # Parse outputs/dependencies; returns save_payload +cz-cli task deps # Draft dependencies +cz-cli task deploy # Publish/deploy; alias: online +cz-cli task undeploy # Undeploy; alias: offline +cz-cli task execute # Ad-hoc execution +cz-cli task delete # Delete draft/offline task +cz-cli task flow dag # Get flow DAG +cz-cli task flow node-save --name N # Save node script/params; supports --param, --flow-param, --output-param, --input-param +``` + +For standalone task params: + +```bash +cz-cli task save-content --file script.sql --params '{"city":"beijing","dt":"bizdate","yd":"$[yyyy-MM-dd,-1d]"}' +cz-cli task save-config --param city=shanghai --param tenant=acme +``` + +`save-content --params` stores params while saving content. `save-config --param key=value` merges overrides with existing task params and preserves script content. System params such as `bizdate`, `sys_plan_day`, and `sys_biz_datetime` are auto-detected for JSON `--params` values. + +For flow node params: + +```bash +cz-cli task flow node-save --name upstream --output-param result_value +cz-cli task flow bind --upstream upstream --downstream downstream +cz-cli task flow node-save --name downstream --input-param up_value=upstream +cz-cli task flow node-save --name worker --param city=beijing --flow-param bizdate +``` + +`--output-param key` declares an output value as `$[output]`. `--input-param key=upstreamNodeName` resolves the upstream node id from the flow DAG, so create/bind nodes before using it. `--flow-param key` marks a child node param as inherited from the parent flow execution params (`ref=2`). + +For merge tasks: + +```bash +cz-cli task create merge_task --type MERGE --folder +cz-cli task save-merge merge_task --dependency upstream_task --status SUCCESS --status FAILED --status SKIPPED +``` + +`save-merge` writes the merge rule content and saves the upstream task as a schedule dependency. `--status` is repeatable or comma-separated. `SKIPPED` only applies to upstream if/condition tasks. + +For manual output tables, quote JSON as one argument: + +```bash +cz-cli task save-config --outputs replace --output-tables '[{"outputTableName":"ws.table","refTableName":"ws.public.table"}]' +``` + +## Runs and Attempts + +```bash +cz-cli runs list [--task ] +cz-cli runs detail +cz-cli runs wait +cz-cli runs logs +cz-cli runs deps # Published dependencies +cz-cli runs stop +cz-cli runs refill --from D --to D # D is YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS +cz-cli runs rerun +cz-cli runs stats + +cz-cli attempts list [id] +cz-cli attempts log [id] +``` + +## Datasources + +```bash +cz-cli datasource list [--type ] [--name ] +cz-cli datasource catalogs +cz-cli datasource objects +cz-cli datasource describe +cz-cli datasource test +cz-cli datasource sample +``` + +## AI Gateway + +```bash +cz-cli ai-gateway key list +cz-cli ai-gateway key create +cz-cli ai-gateway key upsert +cz-cli ai-gateway key get +cz-cli ai-gateway key set-quota --ref R --period P --quota N +cz-cli ai-gateway key enable +cz-cli ai-gateway key disable +cz-cli ai-gateway key delete +cz-cli ai-gateway model list [ref] +``` + +Useful key flags: + +- `key list`: `--alias`, `--key`, `--status 1|0`, `--mine`, `--reveal` +- `key create/upsert`: `--period daily|weekly|monthly|total`, `--quota N`, `--route-type default|provider|byok`, `--providers `, `--provider-sort price|throughput|latency`, `--private-keys `, `--add-to-llm [name]`, `--use` +- `key get`: `` can be an alias, masked key, or key value; supports `--add-to-llm [name]` and `--use` +- `key delete`: `--remove-from-llm` diff --git a/.agents/skills/openspec-apply-change/SKILL.md b/.agents/skills/openspec-apply-change/SKILL.md new file mode 100644 index 0000000000..d474dc1355 --- /dev/null +++ b/.agents/skills/openspec-apply-change/SKILL.md @@ -0,0 +1,156 @@ +--- +name: openspec-apply-change +description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. +license: MIT +compatibility: Requires openspec CLI. +metadata: + author: openspec + version: "1.0" + generatedBy: "1.2.0" +--- + +Implement tasks from an OpenSpec change. + +**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. + +**Steps** + +1. **Select the change** + + If a name is provided, use it. Otherwise: + - Infer from conversation context if the user mentioned a change + - Auto-select if only one active change exists + - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select + + Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). + +2. **Check status to understand the schema** + ```bash + openspec status --change "" --json + ``` + Parse the JSON to understand: + - `schemaName`: The workflow being used (e.g., "spec-driven") + - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) + +3. **Get apply instructions** + + ```bash + openspec instructions apply --change "" --json + ``` + + This returns: + - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs) + - Progress (total, complete, remaining) + - Task list with status + - Dynamic instruction based on current state + + **Handle states:** + - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change + - If `state: "all_done"`: congratulate, suggest archive + - Otherwise: proceed to implementation + +4. **Read context files** + + Read the files listed in `contextFiles` from the apply instructions output. + The files depend on the schema being used: + - **spec-driven**: proposal, specs, design, tasks + - Other schemas: follow the contextFiles from CLI output + +5. **Show current progress** + + Display: + - Schema being used + - Progress: "N/M tasks complete" + - Remaining tasks overview + - Dynamic instruction from CLI + +6. **Implement tasks (loop until done or blocked)** + + For each pending task: + - Show which task is being worked on + - Make the code changes required + - Keep changes minimal and focused + - Mark task complete in the tasks file: `- [ ]` → `- [x]` + - Continue to next task + + **Pause if:** + - Task is unclear → ask for clarification + - Implementation reveals a design issue → suggest updating artifacts + - Error or blocker encountered → report and wait for guidance + - User interrupts + +7. **On completion or pause, show status** + + Display: + - Tasks completed this session + - Overall progress: "N/M tasks complete" + - If all done: suggest archive + - If paused: explain why and wait for guidance + +**Output During Implementation** + +``` +## Implementing: (schema: ) + +Working on task 3/7: +[...implementation happening...] +✓ Task complete + +Working on task 4/7: +[...implementation happening...] +✓ Task complete +``` + +**Output On Completion** + +``` +## Implementation Complete + +**Change:** +**Schema:** +**Progress:** 7/7 tasks complete ✓ + +### Completed This Session +- [x] Task 1 +- [x] Task 2 +... + +All tasks complete! Ready to archive this change. +``` + +**Output On Pause (Issue Encountered)** + +``` +## Implementation Paused + +**Change:** +**Schema:** +**Progress:** 4/7 tasks complete + +### Issue Encountered + + +**Options:** +1.