AGENTS.md@nook-qwen-image git:20260616.5e1f9ccA

Immutable. This exact content never changes and is served at /api/v1/blob/f68f6981b3418bb6.

# AGENTS.md — Deployment Guide for AI Agents

> Auto-loaded by Claude Code, Codex CLI, Trae IDE, Cursor, Continue, Windsurf, and other MCP-aware agents.
> When a user gives you this repository URL and says "deploy this", "set it up", "install", or similar, follow the steps below.

## What this skill is

This is a **ModelScope text-to-image MCP server** for AI agents.

- **Provider**: ModelScope (`api-inference.modelscope.cn`) via `MS_API_KEY`
- **Tools exposed**: `submit_<name>_task`, `get_<name>_result`
- **Output**: Local image files written to the configured `output/` directory

Read `SKILL.md` for capability details, `references/integration-contract.md` for how upper-layer skills should call this provider, and `references/agent-deployment.md` for full deployment and troubleshooting.

## One-time deployment procedure

When the user says "deploy" / "install" / "set up" this project, do **in order**:

### 1. Clone the repository to a stable path

```bash
git clone https://github.com/captain-nook/nook_skills.git
cd nook_skills/<this-folder>
```

> ⚠️ Clone to a stable location (e.g. `~/nook-skills/<folder>`), **not** a temp folder. The MCP config records the absolute path, so if the folder moves, every agent will break.

### 2. Run `setup.js` and collect the API key

```bash
node setup.js
```

`setup.js` will:
1. Ask the user for `MS_API_KEY` (their ModelScope SDK token)
2. Write the key to `<project>/.env` (kept local, not committed)
3. Run `npm install` inside `server/`
4. Auto-detect the user's AI client and register the MCP server

If you are running non-interactively (e.g. you are an agent that cannot read user input), accept the key from env or argv:

```bash
MS_API_KEY=<key> node setup.js
# or
node setup.js <key>
```

### 3. Restart the user's AI client

| Client | Restart |
|---|---|
| Trae IDE | Close window and reopen |
| Codex CLI | Re-run `codex` |
| Claude Code | Restart terminal session |
| Cursor / Windsurf | Cmd/Ctrl+Shift+P → "Reload Window" |
| Continue (VS Code) | Reload VS Code |

### 4. Verify by listing MCP tools

Tell the user to send a probe prompt:

> "Use this skill to generate a tiny test image (size 512x512)."

If the agent can see `submit_<name>_task` and `get_<name>_result`, deployment is successful.

If the tools are not visible, see `references/agent-deployment.md` § Troubleshooting.

### 5. Report back to the user

Reply with:

> ✓ Deployment complete. Registered to: **\<agent name\>**.
> Your ModelScope key is stored locally in `.env` (not shared).
> Try: "给我生一个美女" / "出一张小红书封面" / "生成一张背景图".

## Provider selection rule

When the user gives a natural-language image request, route based on intent:

| User says | Use | Why |
|---|---|---|
| "生一个美女" / "出图" / "测试" / "草图" / "draft" / "背景" / "explore" / "mood" / "cheap" | `nook-zimage` | Cheap/fast Z-Image-Turbo |
| "小红书封面" / "公众号头图" / "海报" / "标题图" / "中文" / "高质量" / "印刷" / "typography" / "editorial" | `nook-qwen-image` | High-quality Qwen-Image with strong Chinese typography |
| "改图" / "换背景" / "image to image" / "edit" | `nook-image2-gpt` (separate project) | Image-to-image editing |

**Default if unclear** → `nook-zimage` (cheaper, faster). The user can always re-render with the other model.

## Output handling

The MCP tools return JSON like:

```json
{
  "task_id": "qwen_img_20260615_142301_a1b2c3d4",
  "status": "succeeded",
  "image_path": "C:\\nook-skills\\nook-qwen-image\\output\\qwen_img_...jpg",
  "image_paths": ["..."]
}
```

**Always display the generated image** to the user using Markdown so they can see it inline:

```markdown
![generated image](file:///C:/nook-skills/nook-qwen-image/output/qwen_img_20260615_142301_a1b2c3d4.jpg)
```

(Use `file:///` absolute URL on Windows; on macOS/Linux use plain absolute path.)

**If the user named a path** (e.g. "存到 D:\\images\\cat.jpg", "save to my Desktop"), pass it as `output_path` to the submit tool so the file lands there:

```python
submit_qwen_image_task(
    prompt="...",
    size="1024x1024",
    output_path="D:\\images\\cat.jpg"
)
```

**If the user did not specify a path**, use the default `output/` directory and present the result inline.

## Error recovery

If `setup.js` does not detect the user's agent:

1. Identify the agent manually (ask if needed).
2. Use the path table in `references/agent-deployment.md` to write the MCP config directly.
3. Restart the agent.

If MCP tools are not visible after restart:

- Confirm the config file is valid JSON (or valid TOML for Codex).
- Confirm the `args` path is **absolute** and points to `server/index.js`.
- Run `node server/index.js` manually to check for startup errors.
- See `references/agent-deployment.md` § Troubleshooting for the full list.

If `MS_API_KEY` is wrong, the user will see HTTP 401 from ModelScope. Tell them to re-run `node setup.js`.

## Security note

`MS_API_KEY` is the user's **personal** ModelScope SDK token. Never log it, never echo it, never commit the `.env` file. The MCP server keeps it server-side only.