# Agent Guide — Qwen provider

This file adds package-specific rules for `packages/qwen-token-plan-cn-responses`.
The monorepo root `AGENTS.md` still applies and takes precedence.

## Mission

Expose Qwen Token Plan CN Personal models to DeepSeek Harness through Responses by default and an isolated GLM Chat route, while deriving the advertised model and server-side tool catalog from official Qianwen documentation instead of a manually maintained list.

## Repository map

| Module | Responsibility |
| --- | --- |
| `lib/catalog.js` | Runtime-only immutable catalog interface; imports the release-bundled JSON and never performs network I/O. |
| `lib/catalog-source.js` | Maintainer-side pure parsers that compile official documents into a candidate catalog. |
| `lib/catalog.snapshot.json` | Generated, reviewed catalog shipped with the npm release. |
| `catalog/reasoning-probes.json` | Reviewed first-party Responses compatibility evidence and semantic effort policy. |
| `scripts/sync-catalog.mjs` | Explicit maintainer/CI fetch-and-compile command. Never called by plugin runtime. |
| `lib/harness.js` | Server-side Harness tool vocabulary, policy intersection and user-visible activity rendering. |
| `lib/content.js` | Adapter from DSH provider-neutral messages/tools/images to Responses request items. |
| `lib/chat.js` | GLM-only Chat request/SSE codec; no other model may use this route without reviewed probe evidence. |
| `lib/sse.js` | Adapter from Qwen Responses SSE events to DSH `StreamChunk` values. |
| `lib/adapter.js` | DSH `LlmAdapter` implementation and credential/network boundary. |
| `lib/index.js` | Cordis composition root. Keep it shallow. |
| `test/` | Network-free contract tests using representative official-document and SSE fixtures. |
| `docs/` | Architecture, catalog-sync and security rationale. |

## Required commands

From the monorepo root:

```bash
npm ci
npm run check --workspace dsh-qwen-token-plan-cn-responses
npm run catalog:sync --workspace dsh-qwen-token-plan-cn-responses  # explicit maintainer network action
npm run pack:check
```

## Non-negotiable invariants

1. Never commit, log, snapshot or cache an API key. Configuration stores only the credential reference name.
2. Resolve the key once per model call through `ctx.credentials`; environment lookup is only the service-less fallback.
3. Runtime must never fetch documentation or mutate the model catalog. Catalog changes arrive only in reviewed, versioned npm releases.
4. Model membership is `Personal text-capable models ∩ Responses-supported models`.
5. Server-side Harness tools and DSH local function tools are different capabilities. Do not describe one as the other.
6. `web_extractor` must be accompanied by `web_search`.
7. In Responses semantics, `web_search_image` is text-to-image search (文搜图), while `image_search` uses an input image/bbox (以图搜图).
8. Do not add a new public content-block type merely to display server-side activity; UI, compaction and replay would all need support. Render the concise activity appendix instead.
9. Every provider request must include DSH `attributionHeaders()`.
10. Changes to wire conversion or SSE lifecycle require fixture tests before a live call.
11. `glm-5.2` alone uses Chat because its Responses effort mapping is broken; every other catalog model stays on Responses.

## Official source endpoints

The daily repository workflow uses the machine-readable `.md` endpoints documented in `docs/CATALOG-SYNC.md`. HTML scraping is a fallback, not the primary interface. A documentation format change must fail the workflow without changing the bundled snapshot or publishing.

## Change workflow

- Keep seams narrow: source fetching belongs to maintainer scripts, parsing functions remain pure, runtime sees only `CatalogSnapshot.snapshot()`, and the Cordis composition root only wires dependencies.
- Update README's current matrix when publishing a release; `lib/catalog.snapshot.json`, not README or live documentation, is runtime authority.
- When a new model appears without OpenClaw metadata, advertise it without invented context/output capacities rather than guessing.
- Run `npm run security:scan` and the tarball audit before publishing.