@evatick/skill 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EVA Tick CLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# EVA Skill for Codex
+
+This package installs the EVA Codex Skill, which teaches Codex how to select and
+use the locally installed `eva` CLI safely and predictably.
+
+The Skill package depends on the matching EVA CLI version, so one npm command
+installs both the `eva` command and the Skill installer:
+
+```shell
+npm install --global @evatick/skill
+eva-skill install
+eva-skill status
+```
+
+Restart Codex after installing or updating a Skill so it can rediscover the
+instructions. To update an existing installation while preserving a recoverable
+backup:
+
+```shell
+npm update --global @evatick/skill
+eva-skill update
+```
+
+`eva-skill` installs into `$CODEX_HOME/skills/eva`, or `~/.codex/skills/eva`
+when `CODEX_HOME` is unset. It does not use npm lifecycle scripts and never
+silently overwrites an existing Skill.

package/bin/eva-skill.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const source = path.join(packageRoot, "skill", "eva");
+const codexRoot = path.resolve(
+  process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+);
+const skillsRoot = path.join(codexRoot, "skills");
+const target = path.join(skillsRoot, "eva");
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function stageSkill() {
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  const temporary = path.join(
+    skillsRoot,
+    `.eva.install-${process.pid}-${Date.now()}`,
+  );
+  fs.cpSync(source, temporary, { recursive: true, errorOnExist: true });
+  return temporary;
+}
+
+function install() {
+  if (fs.existsSync(target)) {
+    fail(
+      `EVA Skill already exists at ${target}. Run "eva-skill update" to replace it safely.`,
+    );
+  }
+  const temporary = stageSkill();
+  fs.renameSync(temporary, target);
+  console.log(JSON.stringify({ installed: true, path: target }));
+}
+
+function update() {
+  if (!fs.existsSync(target)) {
+    fail(
+      `EVA Skill is not installed at ${target}. Run "eva-skill install" first.`,
+    );
+  }
+  const temporary = stageSkill();
+  const backup = path.join(
+    skillsRoot,
+    `eva.backup-${Date.now()}-${process.pid}`,
+  );
+  fs.renameSync(target, backup);
+  try {
+    fs.renameSync(temporary, target);
+  } catch (error) {
+    fs.renameSync(backup, target);
+    throw error;
+  }
+  console.log(JSON.stringify({ updated: true, path: target, backup }));
+}
+
+function status() {
+  console.log(
+    JSON.stringify({
+      installed: fs.existsSync(path.join(target, "SKILL.md")),
+      path: target,
+    }),
+  );
+}
+
+const command = process.argv[2];
+if (command === "install") install();
+else if (command === "update") update();
+else if (command === "status") status();
+else {
+  fail("Usage: eva-skill install|update|status");
+}

package/bin/eva.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+"use strict";
+
+require("@evatick/cli/bin/eva.js");

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@evatick/skill",
+  "version": "0.3.0",
+  "description": "Codex Skill for using the EVA market data CLI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiaochaohit/evatick-cli.git"
+  },
+  "homepage": "https://github.com/xiaochaohit/evatick-cli#readme",
+  "bugs": "https://github.com/xiaochaohit/evatick-cli/issues",
+  "bin": {
+    "eva": "bin/eva.js",
+    "eva-skill": "bin/eva-skill.js"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@evatick/cli": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/eva/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: eva
+description: Query and export mainland A-share and Chinese index data through the locally installed EVA CLI and EVA service. Use for instrument listing, search, resolution and inspection; stock and index quotes or bars; index constituents; EVA service health checks; and EVA CLI HTTP or authentication troubleshooting.
+---
+
+# Use EVA
+
+Treat `eva` as a thin HTTP client. Let the EVA service own data-source selection,
+fallback, retries, normalization, and catalog persistence.
+
+## Workflow
+
+1. Verify the CLI with `command -v eva`.
+2. Verify the service with `eva health`. The default URL is `https://api.evatick.com`; use `--server-url URL` or `EVA_SERVER_URL` when needed.
+3. If authentication fails, check `eva config show`, `EVA_CONFIG`, and `EVA_API_KEY` without printing or exposing the key.
+4. Resolve uncertain user input with `eva instrument search` or `eva instrument resolve`.
+5. Run leaf help before unfamiliar calls.
+6. Parse stdout as one strict JSON value. Treat a nonzero status and the single stderr JSON object as failure.
+7. Report the canonical instrument, requested period, and data limitations. Do not present results as investment advice.
+
+Read [references/command-guide.md](references/command-guide.md) for the complete
+v1 command tree, output options, configuration, and error handling.
+
+## Guardrails
+
+- Use named options only.
+- Prefer canonical instrument IDs when a symbol or name is ambiguous.
+- Use ISO dates such as `2026-08-15` for `--start`, `--end`, and `--as-of`.
+- Use `--output PATH` for large results. Add `--format` only to select `json`, `jsonl`, `csv`, or `parquet`.
+- Do not add `--overwrite` without user authorization.
+- Never expose API keys from environment variables or configuration files.
+- Let the EVA service handle provider routing. Report retryable service failures instead of calling providers directly.
+- Do not invent unsupported commands for funds, futures, options, bonds, FX, macro data, calendars, or alternative data.
+
+## Quick sequence
+
+```shell
+eva health
+eva instrument search --query 平安银行 --type equity
+eva stock bars --help
+eva stock bars --symbol 000001 --start 2026-08-01 --end 2026-08-15 --limit 20
+```

package/skill/eva/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EVA"
+  short_description: "通过 EVA CLI 查询、解析并导出中国股票和指数数据"
+  default_prompt: "Use $eva to find and run the right EVA market data command."

package/skill/eva/references/command-guide.md

@@ -0,0 +1,80 @@
+# EVA v1 command guide
+
+## Connection and configuration
+
+The default service URL is `https://api.evatick.com`. Persist connection settings with:
+
+```shell
+eva config set --base-url https://api.example.com --api-key 'eva_...'
+eva config show
+```
+
+The default configuration path on macOS and Linux is
+`~/.config/eva/config.json`. Overrides are:
+
+- `EVA_CONFIG`: configuration path
+- `EVA_SERVER_URL`: service URL
+- `EVA_API_KEY`: API key
+
+Explicit command options take precedence over environment variables, which take
+precedence over the configuration file. Never display the raw API key.
+
+## Command tree
+
+```shell
+eva health
+eva version
+eva config set|show
+
+eva instrument list [--type equity|index] [--venue VENUE] [--publisher PUBLISHER]
+eva instrument search --query TEXT [--type equity|index]
+eva instrument resolve --query TEXT [--type equity|index]
+eva instrument show --id CANONICAL_ID
+
+eva stock quotes --symbol SYMBOL_OR_ID
+eva stock bars --symbol SYMBOL_OR_ID [--interval INTERVAL] [--start DATE] [--end DATE]
+
+eva index quotes --symbol SYMBOL_OR_ID
+eva index bars --symbol SYMBOL_OR_ID [--interval INTERVAL] [--start DATE] [--end DATE]
+eva index constituents --symbol SYMBOL_OR_ID [--as-of DATE]
+```
+
+Supported bar intervals are `1m`, `5m`, `15m`, `30m`, `60m`, `1d`, `1w`, and
+`1mo`. Inspect leaf help for context and adjustment options.
+
+## Results and files
+
+Successful data commands unwrap the service envelope and write one strict JSON
+value to stdout.
+
+- `--limit N`: retain the first N returned records.
+- `--output PATH`: atomically write data and return a JSON path/record summary.
+- `--format json|jsonl|csv|parquet`: explicitly select the file format.
+- `--overwrite`: replace an existing regular file only when authorized.
+- CSV requires consistent flat records. JSONL and Parquet require record lists.
+- Parquet requires the optional Python dependency `evatick[parquet]`; native npm CLI installations support JSON, JSONL, and CSV.
+
+Example:
+
+```shell
+eva stock bars --symbol 000001 \
+  --start 2026-08-01 --end 2026-08-15 \
+  --output /absolute/path/bars.csv --format csv
+```
+
+## Errors
+
+stderr contains one JSON object, for example:
+
+```json
+{"code":"SERVER_UNAVAILABLE","message":"EVA service is unavailable","retryable":true}
+```
+
+- `INVALID_ARGUMENT`: correct the command or options; do not retry unchanged input.
+- `API_KEY_REQUIRED`: configure a valid EVA API key without exposing it.
+- `SERVER_UNAVAILABLE` or `TIMEOUT`: check `eva health` and the configured service URL; for a self-hosted service, also check its process.
+- `AMBIGUOUS_INSTRUMENT`: search first or pass a canonical instrument ID.
+- `INSTRUMENT_NOT_FOUND`: verify the catalog and instrument type.
+- `OUTPUT_EXISTS`: choose another path or obtain authorization for `--overwrite`.
+- `PARQUET_UNAVAILABLE`: use the Python distribution with its optional extra or choose another format.
+- Provider errors are service responsibilities; do not call a data source directly.