This is an automated email from the ASF dual-hosted git repository. psiace pushed a commit to branch feat/apache-opendal-oli-skill in repository https://gitbox.apache.org/repos/asf/opendal-oli.git
commit 1dbdbbd3ebe43377277f4bc99f38477e05f56f62 Author: Chojan Shang <[email protected]> AuthorDate: Sun Feb 22 15:56:00 2026 +0000 feat: add Apache OpenDAL Oli skill for direct data operations --- skills/apache-opendal-oli/SKILL.md | 106 ++++++++++++++++++ skills/apache-opendal-oli/agents/openai.yaml | 4 + skills/apache-opendal-oli/references/commands.md | 88 +++++++++++++++ .../references/safety-troubleshooting.md | 120 +++++++++++++++++++++ 4 files changed, 318 insertions(+) diff --git a/skills/apache-opendal-oli/SKILL.md b/skills/apache-opendal-oli/SKILL.md new file mode 100644 index 0000000..a5fd90c --- /dev/null +++ b/skills/apache-opendal-oli/SKILL.md @@ -0,0 +1,106 @@ +--- +name: apache-opendal-oli +description: Direct command playbooks for Apache OpenDAL Oli CLI data access and mutation. Use when Codex must run real `oli` commands to list, read, copy, move, delete, edit, stream, or benchmark data across local paths and `profile:/path` locations. +--- + +# Apache OpenDAL Oli + +## Command Principles + +- Prefer direct command execution over abstract planning. +- Run read-only checks before mutating data. +- Use explicit paths and explicit `--config` when environment consistency matters. + +## Direct Command Playbooks + +### Inspect Data Without Mutation + +```bash +oli ls 's3:/warehouse/' +oli ls -r 's3:/warehouse/2026/' +oli ls -T 's3:/warehouse/' +oli stat 's3:/warehouse/events.parquet' +oli cat 's3:/warehouse/schema.json' +``` + +### Copy Local File To Remote + +```bash +oli cp ./events.parquet 's3:/ingest/events.parquet' +oli stat 's3:/ingest/events.parquet' +``` + +### Copy Remote File To Local + +```bash +oli cp 's3:/ingest/events.parquet' ./events.parquet +``` + +### Copy Across Profiles + +```bash +oli cp 's3:/warehouse/events.parquet' 'r2:/backup/events.parquet' +oli stat 'r2:/backup/events.parquet' +``` + +### Recursive Directory Copy + +```bash +oli ls -r 's3:/warehouse/2026/' +oli cp -r 's3:/warehouse/2026/' 'r2:/backup/2026/' +oli ls -r 'r2:/backup/2026/' +``` + +### Move File Or Directory + +```bash +oli mv 's3:/staging/events.parquet' 's3:/warehouse/events.parquet' +oli mv -r 's3:/staging/old-batch/' 's3:/archive/old-batch/' +``` + +### Safe Recursive Delete + +```bash +oli ls -r 's3:/staging/to-delete/' +oli rm -r 's3:/staging/to-delete/' +oli ls 's3:/staging/' +``` + +### Stream Input To Object + +```bash +printf '%s\n' '{"status":"ok"}' | oli tee 's3:/logs/healthcheck.json' +``` + +### Edit Remote File + +```bash +EDITOR=vim oli edit 's3:/docs/README.md' +``` + +### Run Benchmark Suite + +```bash +oli bench --config ./config.toml s3 ./suite.toml +``` + +## Hard Rules + +- Always use `profile:/path` syntax and avoid `://`. +- Use `profile:/path` for remote targets and plain paths for local filesystem targets. +- For directory-level mutations, explicitly use `-r` and inspect scope first. +- For delete operations, list first, delete second, verify third. +- For cross-profile copy and move, verify source and destination with `stat` or `ls`. +- When non-default config is required, always pass `--config <path>` explicitly. + +## Failure Triage + +- `unknown profile`: check profile name and `config.toml`. +- `missing 'type' in profile`: add profile `type`. +- `Host part in a location is not supported`: replace `://` with `:/`. +- Recursive command errors: confirm `-r` and target kind (file vs directory). + +## Resource Navigation + +- Read `references/commands.md` for command semantics and flags. +- Read `references/safety-troubleshooting.md` for risk control and debugging. diff --git a/skills/apache-opendal-oli/agents/openai.yaml b/skills/apache-opendal-oli/agents/openai.yaml new file mode 100644 index 0000000..5e653a9 --- /dev/null +++ b/skills/apache-opendal-oli/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Apache OpenDAL Oli" + short_description: "Direct command playbooks for Apache OpenDAL Oli CLI" + default_prompt: "Use $apache-opendal-oli to execute real Apache OpenDAL Oli CLI commands for data access and mutation." diff --git a/skills/apache-opendal-oli/references/commands.md b/skills/apache-opendal-oli/references/commands.md new file mode 100644 index 0000000..38acd47 --- /dev/null +++ b/skills/apache-opendal-oli/references/commands.md @@ -0,0 +1,88 @@ +# OLI Command Reference + +## Location Semantics + +- Use local filesystem mode when the argument does not contain `:/`. +- Use remote profile mode when the argument is `<profile>:/<path>`. +- Avoid `://` in location strings. `oli` treats host parts as invalid. + +Examples: + +```bash +# local path +oli ls './data/' + +# remote path +oli ls 's3:/data/' + +# invalid syntax (do not use) +oli ls 's3://data/' +``` + +## Config Resolution + +- Default config path: + - Linux: `~/.config/oli/config.toml` + - macOS: `~/Library/Application Support/oli/config.toml` + - Windows: `%APPDATA%\oli\config.toml` +- Environment variables override file configuration. +- Environment key format: `OLI_PROFILE_<PROFILE>_<OPTION>` + +Examples: + +```bash +OLI_PROFILE_S3_TYPE=s3 +OLI_PROFILE_S3_BUCKET=my-bucket +OLI_PROFILE_S3_REGION=us-east-1 +``` + +## Global Parameter + +`--config <path>` is available through `ConfigParams` in command implementations. + +```bash +oli --config ./config.toml ls 's3:/' +oli cp --config ./config.toml './a.txt' 's3:/a.txt' +``` + +## Commands + +### Read-Only + +- `oli ls <target>` +- `oli ls -r <target>` +- `oli ls -T <target>` +- `oli cat <target>` +- `oli stat <target>` +- `oli config view` + +### Mutating + +- `oli cp <source> <destination>` +- `oli cp -r <source_dir> <destination_dir>` +- `oli cp --content-type application/json <source> <destination>` +- `oli mv <source> <destination>` +- `oli mv -r <source_dir> <destination_dir>` +- `oli rm <target>` +- `oli rm -r <target_dir>` +- `oli tee <destination>` +- `oli tee -a <destination>` +- `oli edit <target>` + +### Benchmark + +- `oli bench <profile> <suite.toml>` + +## Binary Aliases + +`oli` supports executable-name aliases: + +- `obench` -> `bench` +- `ocat` -> `cat` +- `ocp` -> `cp` +- `ols` -> `ls` +- `orm` -> `rm` +- `ostat` -> `stat` +- `omv` -> `mv` + +Prefer `oli <subcommand>` for clarity unless alias behavior is explicitly required. diff --git a/skills/apache-opendal-oli/references/safety-troubleshooting.md b/skills/apache-opendal-oli/references/safety-troubleshooting.md new file mode 100644 index 0000000..7a9b20b --- /dev/null +++ b/skills/apache-opendal-oli/references/safety-troubleshooting.md @@ -0,0 +1,120 @@ +# OLI Safety And Troubleshooting + +## Safe Execution Checklist + +1. Resolve intent: +- `read-only` for inspection +- `mutating` for data changes + +2. Validate source and destination paths with read-only checks: + +```bash +oli ls 's3:/path/' +oli stat 's3:/path/to/object' +``` + +3. Execute mutation only after verification: + +```bash +oli cp 's3:/path/to/object' 'r2:/backup/object' +``` + +4. Verify result: + +```bash +oli stat 'r2:/backup/object' +``` + +## High-Risk Operations + +### Recursive Delete + +- Always inspect scope before `rm -r`. + +```bash +oli ls -r 's3:/staging/prefix/' +oli rm -r 's3:/staging/prefix/' +oli ls 's3:/staging/' +``` + +### Recursive Move + +- `mv -r` moves data and deletes source entries afterward. +- Validate source and destination roots before running. + +### Recursive Copy + +- Use `cp -r` only for directory-level workflows. +- Confirm destination is a directory or a new path intended as directory root. + +## Common Errors And Fixes + +### `unknown profile: <name>` + +Cause: +- Profile name missing in config and environment. + +Fix: +- Add `[profiles.<name>]` in `config.toml`, or set `OLI_PROFILE_<NAME>_TYPE`. +- Use `oli config view` to inspect available profiles. + +### `missing 'type' in profile` + +Cause: +- Profile exists but has no `type` key. + +Fix: +- Add `type = "<service>"` in the profile table. + +### `Host part in a location is not supported` + +Cause: +- Used `://` instead of `:/`. + +Fix: +- Replace `s3://a/b` with `s3:/a/b`. + +### `can not move a directory in non-recursive mode` + +Cause: +- Tried to move directory with `mv` without `-r`. + +Fix: +- Use `mv -r`. + +### `Recursive copy destination '...' exists but is not a directory` + +Cause: +- `cp -r` destination points to an existing file. + +Fix: +- Use a directory destination path. + +### `No configuration profiles found in ...` + +Cause: +- Config file missing or empty at the selected `--config` path. + +Fix: +- Create config file with at least one profile. + +## Operational Patterns + +### Cross-Profile Transfer + +```bash +oli cp 's3:/dataset/part-0001.parquet' 'r2:/archive/part-0001.parquet' +oli stat 'r2:/archive/part-0001.parquet' +``` + +### Controlled Metadata Check + +```bash +oli stat 's3:/dataset/part-0001.parquet' +``` + +Use the output to validate: +- `size` +- `etag` (if available) +- `content-type` +- `last-modified`
