Skip to content

refactor: 让 ECNU Skill 聚焦接入与排障，减轻默认使用流程 #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JJasonSun merged 4 commits into from
Sep 12, 2026
Merged

refactor: 让 ECNU Skill 聚焦接入与排障，减轻默认使用流程 #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7259dc2
Refactor ECNU skill around practical integration and targeted diagnosis
JJasonSun Sep 12, 2026
6ae9311
fix: make ECNU recipes directly usable and verify SDK history
JJasonSun Sep 12, 2026
d6e38a4
docs: record live validation of ECNU integration recipes
JJasonSun Sep 12, 2026
27cb514
docs: close refactor handoff and align maintenance guidance
JJasonSun Sep 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 24 additions & 30 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,49 +2,43 @@

## Purpose

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.
This is an Agent Skills package, not a production application.
Optimize for less repeated setup, lookup, and troubleshooting work.
These instructions apply to maintaining this repository, not consuming apps.

## File routing

- `SKILL.md` is the concise task entry point.
- `references/api_reference.md` contains documented endpoint contracts.
- Model selection and Agent design: `references/models.md` and `references/agent_development.md`.
- `references/examples.md` contains minimal safe examples.
- `references/workflows.md` contains executable integration and test flows.
- `references/known_deviations.md` contains dated live observations only.
- `scripts/smoke_test.py` performs opt-in live structural checks.
- `scripts/validate_skill.py` and `tests/` provide offline validation.
- `SKILL.md`: small integration entry point and task routing.
- `references/api_reference.md`: official endpoint links, not copied field tables.
- `references/models.md`: selection defaults and current account-source pointers.
- `references/examples.md`: ECNU-specific integration recipes.
- `references/workflows.md`: symptom-driven, opt-in diagnostics.
- `references/known_deviations.md`: dated live evidence; preserve dates and scope.
- `references/agent_development.md`: historical guidance cited by old observations.
- `scripts/` and `tests/`: existing diagnostics and offline validation.
- `docs/skill-refactor-plan.md`: refactor scope and acceptance evidence.

## Editing rules

- Treat current official ECNU documentation as the documented contract.
- Keep documented facts, live observations, application policy, and unverified
claims distinct.
- Do not invent undocumented fields, limits, model capabilities, or prices.
- Put point-in-time behavior only in `known_deviations.md` with dated evidence.
- Keep examples sequential, timeout-bounded, and environment-key based.
- Maintain this repository with Git; update the deployed skill via `npx skills update -g ecnu-api`, never by manually copying it.
- Prefer current official contracts; keep observed differences separately dated.
- Add content only when it saves a concrete lookup, decision, mistake, or repeated action.
- Keep everyday integration separate from platform audits and repository maintenance.
- Do not invent API limits or copy upstream model defaults into ECNU requests.
- Do not refresh a test date or label a snippet live-verified without a real test.
- Update installed copies via `npx skills update -g ecnu-api`, not manual copying.

## Validation

Run before committing:

```bash
python3 scripts/validate_skill.py
python3 -m unittest discover -s tests -v
python3 -m compileall scripts tests
uvx --from skills-ref agentskills validate "$PWD"
git diff --check
```

Review `git diff --check` and scan tracked content for secrets and personal paths.

## Safety

- Read live credentials only from `ECNU_API_KEY`; never accept a CLI key.
- Never commit keys, Authorization values, private inputs, raw responses,
generated media, one-time URLs, or full reasoning content.
- Keep API calls serial and enforce the declared credit ceiling.
- Do not automatically retry POST requests after ambiguous transport failures.
- Record only sanitized response structure and allowlisted diagnostic headers.
- Do not update an observation date unless the behavior was reproduced.
Report unavailable checks as not run. Review tracked changes for secrets.
Live checks use only `ECNU_API_KEY`, serial requests, no ambiguous POST retry,
and an approved cumulative budget. Never commit private inputs, reasoning,
credentials, generated media, one-time URLs, or raw responses. Keep sanitized
live artifacts under the ignored `.live-artifacts/` directory.
230 changes: 44 additions & 186 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,209 +1,67 @@
# ECNU API Agent Skill

Unofficial community [Agent Skill](https://agentskills.io/) for implementing,
reviewing, testing, and troubleshooting integrations with the ECNU / ChatECNU
LLM Open Platform API.
An unofficial skill that helps an Agent connect to the ECNU / ChatECNU LLM
Open Platform without repeatedly finding the same docs or rediscovering the
same integration differences.

The skill covers:
The default path is small: a working connection example, task-specific official
documentation, and a few ECNU-specific recipes. Full live diagnostics are opt-in.
This is not another API manual, a generic Agent course, or a required test harness.

- 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
- URL-parameter ChatECNU links
- model selection, authentication, quotas, errors, and known service deviations
- upstream Qwen3.8, DeepSeek, and DSpark context, distinct from ECNU guarantees
- Agent prompt templates, tool continuation, context management, and evaluation

## Install
## Install and use

```bash
npx skills add JJasonSun/ecnu-api
```

Use the skills CLI to manage installed copies. For an existing global
installation, update from its upstream source with:

```bash
npx skills update -g ecnu-api
```

Maintain this source repository with Git; do not deploy edits by manually
copying files into an installed skill directory.

Example invocation:

```text
Use $ecnu-api to review this ECNU API integration.
```

## Repository layout
Example request:

```text
ecnu-api/
├── SKILL.md
├── AGENTS.md
├── references/
│ ├── api_reference.md
│ ├── models.md
│ ├── agent_development.md
│ ├── examples.md
│ ├── workflows.md
│ └── known_deviations.md
├── scripts/
│ ├── smoke_test.py
│ └── validate_skill.py
├── tests/
│ ├── test_repository_contracts.py
│ └── test_smoke_test.py
└── .github/workflows/validate.yml
Use $ecnu-api to adapt this application to ECNU. Keep the current framework.
Only change the integration and its relevant checks; do not make live requests.
```

`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`.

For Agent development, start with
[model-specific prompt and tool guidance](references/agent_development.md).
It covers ECNU's differences from upstream DeepSeek-V4.1 and Qwen3.8,
reusable task prompts, thinking/tool history, and checks for actual task success.

## 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"
```

macOS or Linux:
For an existing global installation:

```bash
export ECNU_API_KEY="your-api-key"
npx skills update -g ecnu-api
```

A key pasted into a chat or public location should be revoked or rotated after
testing.
Configure `ECNU_API_KEY` through the local environment or secret manager when
execution is needed. Never paste a real key into chat or commit it. Missing
credentials should not prevent the Agent from writing or reviewing code.

## Reproducible live validation
## Where to go

The runner reads only `ECNU_API_KEY`, sends requests serially, and does not
retry POST requests. Select the smallest profile that answers the question:

| Profile | Scope |
| Need | Resource |
|---|---|
| `auth` | Service status plus valid, invalid, and missing-token model discovery; no billable POST requests. This is the default. |
| `core` | Low-cost Chat Completions, Responses, embeddings, rerank, vision, structured output, error-shape, OpenAI SDK, and LangChain probes. |
| `compatibility` | Responses vision and Anthropic-compatible models, aliases, effort controls, long-context suffix behavior, vision, and SDK probes. |
| `billable` | Fixed-price TTS and one documented image-generation probe, subject to the credit ceiling. |
| `all` | The union of all four profiles; later billable cases are skipped when the ceiling is reached. |

Examples:

```bash
python3 scripts/smoke_test.py --profile auth --max-credits 0 --output .live-artifacts/auth.json
python3 scripts/smoke_test.py --profile core --max-credits 50 --output .live-artifacts/core.json
python3 scripts/smoke_test.py --profile compatibility --max-credits 50 --output .live-artifacts/compatibility.json
python3 scripts/smoke_test.py --profile billable --max-credits 50 --output .live-artifacts/billable.json
python3 scripts/smoke_test.py --profile all --max-credits 50 --output .live-artifacts/all.json
```

`--max-credits` is a conservative planned-cost gate, defaulting to 50. The
runner reserves each case's estimate before sending it and skips a case that
would exceed the ceiling. The estimate is not proof of the service's actual
debit. Recheck the official quota and pricing page before a live run.

Use `--case` to rerun only named cases within the selected profile; repeat the
flag to select more than one:

```bash
python3 scripts/smoke_test.py --profile core --case openai_sdk_chat \
--max-credits 1 --output .live-artifacts/openai-sdk-chat.json
```

Keep reports under `.live-artifacts/`, which is Git-ignored. Reports contain
statuses and structural summaries, not the API key, generated content,
reasoning text, media, or one-time URLs.

Selected SDK probes on 2026-08-23 passed with OpenAI Python SDK 2.48.0,
Anthropic Python SDK 0.125.0, `langchain-openai` 0.3.35, and `httpx` 0.28.1.
This is dated, point-in-time evidence, not a blanket compatibility guarantee;
see `references/known_deviations.md` for the observed scope and divergences.

## Validate the skill

Run deterministic repository checks and unit tests:

```bash
python3 scripts/validate_skill.py
python3 -m unittest discover -s tests -v
```

Run the Agent Skills reference validator separately:

```bash
uvx --from skills-ref agentskills validate "$PWD"
```

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.
- Upstream model cards and papers provide background, not ECNU API guarantees.
- 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.

## Revalidate after ECNU platform updates

An ECNU release, model rollout, endpoint change, quota change, or announced fix
is a reason to consider a new targeted validation; it is not evidence that an
active deviation has been resolved. Review the updated official contract,
recalculate the credit allowance, and run only the affected `--case` probes
serially with fresh sanitized evidence. Billable TTS or image probes require
new account-owner authorization and must never run automatically.

Update an observation date or mark a deviation `resolved` only after the same
behavior has been exercised again with the current runner. Preserve the prior
entry when the new run is inconclusive, and record both the changed contract
and the new observed result when the platform update changes expectations.

## 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
- https://developer.ecnu.edu.cn/vitepress/llm/authorization.html
- https://developer.ecnu.edu.cn/vitepress/llm/limit.html
- https://developer.ecnu.edu.cn/vitepress/llm/error.html
- https://developer.ecnu.edu.cn/vitepress/llm/release.html
- 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/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/urlchat.html
- https://developer.ecnu.edu.cn/vitepress/llm/tos.html
| Start a normal integration | [SKILL.md](SKILL.md) |
| Find the relevant official endpoint contract | [Endpoint map](references/api_reference.md) |
| LangChain embeddings, thinking/tool history, Anthropic SDK | [Integration recipes](references/examples.md) |
| Model choice or current account facts | [Model/account pointers](references/models.md) |
| Diagnose a failure or select a live probe | [Targeted diagnosis](references/workflows.md) |
| Inspect dated evidence | [Known deviations](references/known_deviations.md) |
| Maintain this repository | [AGENTS.md](AGENTS.md) |
| Inspect the refactor's acceptance evidence | [Acceptance record](docs/skill-refactor-plan.md) |

The older [Agent-development notes](references/agent_development.md) remain to
preserve historical prompt-fixture references in the observation log. They are
not part of the default integration reading path or a current model benchmark.

## Validation and evidence

The existing runner and unit tests are retained. Maintainer commands are in
`AGENTS.md`; they are not steps for an Agent editing someone else's application.
Live checks require appropriate authorization and a cumulative credit budget.
A documentation edit is not a new live test: observation dates and statuses must
not be refreshed without reproducing the relevant behavior.

Use current official pages for changing contracts, models, prices, and quotas.
Use local recipes to save integration work and dated observations to diagnose
specific discrepancies. Do not assume compatibility with every upstream feature.

## Disclaimer

This is an unofficial community skill. It is not endorsed by or affiliated with
East China Normal University. Never commit API keys, personal tokens, internal
allowlist details, private prompts, or unsanitized live-test output.
This community skill is not endorsed by or affiliated with East China Normal
University. Never commit credentials, private prompts, personal data, raw live
responses, generated media, or one-time access URLs.
Loading
Loading