Refactor ECNU API skill for safe execution and reproducible validation

.github/workflows/validate.yml

@@ -0,0 +1,19 @@
+name: Validate skill
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Run repository validation
+        run: python scripts/validate_skill.py
+      - name: Run unit tests
+        run: python -m unittest discover -s tests -v

.gitignore

@@ -1,4 +1,9 @@
+.DS_Store
+.env
+.env.*
+!.env.example
 .venv/
-.pytest_cache/
 __pycache__/
 *.py[cod]
+smoke-results*.json
+smoke-results/

AGENTS.md

@@ -1,43 +1,85 @@
-# ecnu-api skill repo
+# ecnu-api repository guide
 
-Agent Skills package for the ECNU LLM Open Platform API. The repo content IS
-the skill; there is no runnable application code.
+This repository is an Agent Skills package for the ECNU LLM Open Platform API.
+The repository content is the skill; there is no production application.
 
-## Deploy
+## Scope
 
-Edit files in this repo, then copy the changed files to
-`C:\Users\Jason\.agents\skills\ecnu-api\` to take effect. That directory is a
-full mirror of this repo; verify file hashes match after every sync.
+- `SKILL.md` — concise activation and execution instructions
+- `references/api_reference.md` — documented endpoint contracts
+- `references/models.md` — models, aliases, credits, quotas, and deployment
+- `references/examples.md` — minimal, safe examples
+- `references/workflows.md` — implementation, debugging, retry, and test flows
+- `references/known_deviations.md` — dated live observations only
+- `scripts/smoke_test.py` — opt-in live structural checks
+- `scripts/validate_skill.py` — deterministic repository validation
+- `tests/` — offline tests for helper behavior
 
-## Layout
+Do not write outside the repository unless the user explicitly asks to install
+or synchronize the skill into a client-specific directory.
 
-- `SKILL.md` — skill entry: protocol roots, endpoint map, critical contracts
-- `references/api_reference.md` — exact request fields, limits, response shapes
-- `references/models.md` — models, aliases, credits, quotas, Recent Changes log
-- `references/examples.md` — Python and HTTP examples
-- `README.md` — human-facing overview for GitHub
+## Source precedence
 
-## Conventions
+When ECNU documentation pages disagree:
 
-- Official docs at developer.ecnu.edu.cn are the authority. Never invent
-  undocumented limits; write "not documented" instead.
-- `references/models.md` keeps a `Recent Changes` section; new entries go on
-  top, newest first.
-- Content is English; keep official Chinese terms (voice names, UI labels)
-  as-is.
-- Never commit real API keys.
+1. Use the current model page for model identity, context figures, aliases, and
+   capability labels.
+2. Use the endpoint page for JSON fields, types, and endpoint-specific limits.
+3. Use the quota page for current prices and quota periods.
+4. Use release notes to establish when a change occurred.
+5. Use `GET /models` for runtime visibility, not as the sole source of
+   capability truth.
+6. Keep live probes in `known_deviations.md`; never let a single observation
+   silently override a documented contract.
 
-## Current state (2026-08-22)
+## Change workflow
 
-- Synced with official docs through v3.2.1 (2026-08-10) and the doc
-  restructure of 2026-08-09 (security/tos pages published; vision page merged
-  into the completions multimodal section).
-- Responses-API `reasoning.effort` is documented from release notes; the
-  responses.html page itself still lags.
-- Live-verified against the service on 2026-08-21; deviations are recorded in
-  `references/api_reference.md` under Live Verification Notes.
+1. Work on a branch.
+2. Identify the exact official pages affected by the change.
+3. Update only the relevant focused reference.
+4. If live testing is needed, use `ECNU_API_KEY` from the environment.
+5. Never paste or persist a real key in a file, command example, report, issue,
+   commit, or pull request.
+6. Run:
 
-## Verifying changes
+```bash
+python scripts/validate_skill.py
+python -m unittest discover -s tests -v
+uvx --from skills-ref agentskills validate .
+```
 
-Fetch each page listed in Official Sources, diff against the reference files,
-patch stale statements, then sync to the `.agents` mirror and verify hashes.
+7. Review the diff for secrets, machine-specific paths, duplicated guidance,
+   undocumented request fields, and accidental billable calls.
+8. Summarize whether each changed claim is documented, observed, or unverified.
+
+## Live verification rules
+
+- The default smoke test performs model-list checks only.
+- Chat, embedding, and Anthropic probes require `--low-cost` or `--anthropic`.
+- Do not add image generation to an automatic or CI smoke test.
+- Do not blindly retry image, TTS, or any other billable request after an
+  ambiguous network failure.
+- Record SDK or Python version, account type, date, endpoint, status, content
+  type, and structural result.
+- Sanitize reports before sharing or committing them.
+- Update the date in `known_deviations.md` only when the behavior was actually
+  reproduced.
+
+## Content conventions
+
+- Write documentation in English; retain official Chinese UI labels where
+  needed.
+- Prefer imperative, stepwise instructions over broad prose.
+- Keep `SKILL.md` below the Agent Skills recommended size and route detail to
+  focused references.
+- Never describe `skills-ref` validation as an API correctness test.
+- Never claim undocumented limits.
+- Never describe an output dimension as a request parameter unless ECNU
+  documents it.
+- Use environment variables in every credential example.
+
+## Current state
+
+The reference content is aligned with the ECNU documentation and repository
+observations available on 2026-08-22. The live deviations remain dated
+2026-08-21 until a new authenticated run reproduces or supersedes them.

README.md

@@ -1,79 +1,134 @@
 # ECNU API Agent Skill
 
-Unofficial community [Agent Skill](https://agentskills.io/) for working with the
-ECNU / ChatECNU LLM Open Platform API.
-
-This skill helps compatible AI agents answer questions and write integrations
-for:
-
-- OpenAI-compatible chat completions
-- OpenAI-compatible Responses API
-- Vision / multimodal chat
-- Embeddings and rerank
-- Image generation
-- Text-to-speech
-- Structured output
+Unofficial community [Agent Skill](https://agentskills.io/) for implementing,
+reviewing, testing, and troubleshooting integrations with the ECNU / ChatECNU
+LLM Open Platform API.
+
+The skill covers:
+
+- OpenAI-compatible Chat Completions and Responses APIs
+- vision and multimodal messages
+- embeddings and rerank
+- image generation and text-to-speech
+- structured output
 - Anthropic-compatible API usage
-- Models, authentication, quotas, and error handling
+- model selection, authentication, quotas, errors, and known service deviations
 
 ## Install
 
-Install with the open Skills CLI:
-
 ```bash
 npx skills add JJasonSun/ecnu-api
 ```
 
-See the skill on [skills.sh](https://skills.sh/jjasonsun/ecnu-api/ecnu-api).
-
-Alternatively, clone or copy this repository into the skills directory used by
-your Agent Skills-compatible client. Keep the installed directory name as
-`ecnu-api`, because the Agent Skills specification requires it to match the
-`name` in `SKILL.md`.
+Or copy this repository into the skills directory used by an Agent
+Skills-compatible client. Keep the installed directory name as `ecnu-api` so it
+matches the `name` in `SKILL.md`.
 
-The exact skills directory depends on the client. For example:
+Example invocation:
 
 ```text
-<client-skills-directory>/ecnu-api/SKILL.md
+Use $ecnu-api to review this ECNU API integration.
 ```
 
-Once installed, ask the agent to work with the ECNU API. Clients that support
-explicit skill invocation may also accept prompts such as:
+## Repository layout
 
 ```text
-Use $ecnu-api to help me integrate with the ECNU LLM Open Platform API.
+ecnu-api/
+├── SKILL.md
+├── AGENTS.md
+├── references/
+│   ├── api_reference.md
+│   ├── models.md
+│   ├── examples.md
+│   ├── workflows.md
+│   └── known_deviations.md
+├── scripts/
+│   ├── smoke_test.py
+│   └── validate_skill.py
+├── tests/
+│   └── test_smoke_test.py
+└── .github/workflows/validate.yml
+```
+
+`SKILL.md` contains the core workflow and tells an agent when to load each
+focused reference. Live observations are isolated from documented contracts in
+`references/known_deviations.md`.
+
+## Configure a key safely
+
+Store the key in an environment variable. Do not put it in source files, shell
+scripts, screenshots, committed reports, or chat prompts.
+
+PowerShell:
+
+```powershell
+$env:ECNU_API_KEY = "your-api-key"
 ```
 
-## Files
+macOS or Linux:
+
+```bash
+export ECNU_API_KEY="your-api-key"
+```
 
-- `SKILL.md`: skill trigger metadata and quick navigation.
-- `AGENTS.md`: repo maintenance guide for AI agents (deploy flow,
-  conventions, verification workflow).
-- `references/api_reference.md`: endpoint summaries and request/response notes.
-- `references/models.md`: models, aliases, credits, quotas, and errors.
-- `references/examples.md`: short Python SDK and direct HTTP examples.
+A key pasted into a chat or public location should be revoked or rotated after
+testing.
 
-## Validate
+## Reproducible smoke tests
 
-Run the official
-[`skills-ref`](https://github.com/agentskills/agentskills/tree/main/skills-ref)
-reference validator with `uv`:
+The default profile performs model-list checks and does not send chat,
+embedding, Anthropic, image, or TTS POST requests:
 
 ```bash
-uvx --from skills-ref agentskills validate /path/to/ecnu-api
+python scripts/smoke_test.py
 ```
 
-On Windows PowerShell, force UTF-8 when the system locale is not UTF-8:
+Low-cost POST probes are explicit:
 
-```powershell
-$env:PYTHONUTF8 = "1"
-uvx --from skills-ref agentskills validate C:\path\to\ecnu-api
+```bash
+python scripts/smoke_test.py --low-cost --anthropic \
+  --account-type personal-token \
+  --output smoke-results.json
 ```
 
-## Official Documentation
+The report contains statuses and structural summaries. It does not print the
+API key or successful model content. Image generation is intentionally absent
+from the automated smoke test because it is comparatively expensive and a
+retry after an ambiguous failure could duplicate charges.
 
-API details can change. Treat this skill as a working summary and verify
-production-critical details against the official ECNU developer docs:
+## Validate the skill
+
+Run deterministic repository checks and unit tests:
+
+```bash
+python scripts/validate_skill.py
+python -m unittest discover -s tests -v
+```
+
+Run the Agent Skills reference validator separately:
+
+```bash
+uvx --from skills-ref agentskills validate .
+```
+
+The reference validator checks format and naming conventions; it does not
+verify that ECNU endpoints are currently available or that every documented
+contract matches live behavior.
+
+## Maintenance principles
+
+- Official ECNU documentation is the authority for documented contracts.
+- Runtime observations must include a date and must remain labeled as
+  observations.
+- Do not infer unsupported OpenAI or Anthropic fields.
+- Keep examples minimal and secrets environment-based.
+- Do not add local absolute paths or machine-specific deployment instructions.
+- Run repository validation before opening a pull request.
+
+## Official documentation
+
+API details can change. Verify production-critical behavior against the current
+ECNU developer documentation:
 
 - https://developer.ecnu.edu.cn/vitepress/llm/model.html
 - https://developer.ecnu.edu.cn/vitepress/llm/thinking.html
@@ -84,17 +139,16 @@ production-critical details against the official ECNU developer docs:
 - https://developer.ecnu.edu.cn/vitepress/llm/api/models.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/completions.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/responses.html
-- https://developer.ecnu.edu.cn/vitepress/llm/api/vision.html
-- https://developer.ecnu.edu.cn/vitepress/llm/api/imagegenerate.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/embedding.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/rerank.html
+- https://developer.ecnu.edu.cn/vitepress/llm/api/imagegenerate.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/audio.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/anthropic.html
 - https://developer.ecnu.edu.cn/vitepress/llm/api/structuredoutput.html
-- https://developer.ecnu.edu.cn/vitepress/llm/api/embediframe.html
+- https://developer.ecnu.edu.cn/vitepress/llm/tos.html
 
 ## Disclaimer
 
 This is an unofficial community skill. It is not endorsed by or affiliated with
-East China Normal University. Do not commit API keys, personal tokens, internal
-whitelist details, or screenshots containing credentials.
+East China Normal University. Never commit API keys, personal tokens, internal
+allowlist details, private prompts, or unsanitized live-test output.