shield_lock
JinDaGe
← Back to skills
extension
Category: Content & MediaAPI key requirement unconfirmed

lingjing-cover-image

灵境工坊外部封面图生成技能。面向 Claude、Codex、OpenCode 等外部 Agent，使用 LINGJING_API_KEY 调用灵境工坊平台 API 生成文章封面，保留 5 维设计定制能力。Use when user asks to generate/create/make an article cover image.

personAuthor: stormflyhubgithub
open_in_newRepositorydownloadDownload package

灵境工坊封面图生成

通过灵境工坊对外 API 生成文章封面。本技能只调用平台 API，不依赖本地生图后端、内部 Token、沙箱目录或 localhost。

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

  1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent.
  2. Fallback: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
  3. Batching: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.

Platform API Requirements

生成图片前先阅读 references/platform-api.md，其中包含完整请求示例、响应处理和错误处理。所有模型调用只能走灵境工坊 /api/v1 对外接口，不能直接调用 DashScope、火山方舟、OpenAI、V-API 或其他上游服务。

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | LINGJING_API_KEY | Yes | none | 平台 API Key，格式 lk_... | | LINGJING_API_BASE | No | https://www.lingjing-ai.work | 平台 Base URL，不带末尾 / | | LINGJING_COVER_MODEL | No | qwen-image-3.0 | 默认封面模型，支持文生图和图生图 | | LINGJING_COVER_FALLBACK_MODEL | No | qwen-image-2.0-pro | 502/超时失败时最多切换一次 | | LINGJING_VISION_MODEL | No | qwen3.7-flash | 参考图视觉分析辅助模型 |

请求头统一使用 X-API-Key: <LINGJING_API_KEY>。

API Key Gate ⛔ BLOCKING

在任何内容分析、偏好确认或图片生成前，先检查 LINGJING_API_KEY。Key 缺失、为空或不是 lk_... 时不要猜测、不要尝试自行注册，停止当前任务并向用户显示以下指引：

请先完成灵境工坊外部 API 开通：
1. 打开 https://www.lingjing-ai.work 注册账号。
2. 登录后进入“设置”页面，申请平台 API Key（格式 lk_...）。
3. 将 Key 配置为环境变量 LINGJING_API_KEY，也可以把 Key 粘贴给当前 Agent，请 Agent 代为设置为环境变量：如果用户提供了 `lk_...`，并要求保存到当前项目 `.env`，使用 dotenv 的`set_key` 或等效方式更新当前`.env`；不要手工覆盖整个文件。
  - 保留 `.env` 中其他内容不变。
  - 如果已有 `LINGJING_API_KEY=...`，只替换该行。
  - 如果没有该行，则在末尾追加。
  - 写入前校验值以 `lk_` 开头。
  - 不打印完整 Key，不把 Key 写入技能文件或日志。
  实际执行方式可以是：
  from dotenv import set_key
  set_key(
      ".env",
      "LINGJING_API_KEY",
      user_provided_key,
      quote_mode="never",
  )
  同时建议把加载 .env 放到读取环境变量之前，例如脚本顶部先执行：
  dotenv.load_dotenv()
4. 确认账号积分大于 0；不足时请先充值。
配置完成后重新发起请求即可。

如果用户把 Key 粘贴给 Agent，只允许将其写入当前 Agent 支持的环境变量配置；不得写入技能文件、日志、会话摘要或输出文件。需要展示 Key 时只显示 lk_ 开头的前几个字符。

⛔ Never substitute SVG, HTML, canvas, or other code-based rendering for raster image generation. 封面必须由平台图片模型生成；无法调用平台时向用户说明并停止，不静默输出 SVG、HTML 或代码绘制图像。

⛔ Never repair rendered text by painting over a generated bitmap. 如果标题/副标题错误、乱码或可读性差，不得用代码覆盖、擦除或改写位图文字；应修正 prompt 后重新生成，必要时保留旧候选以便比较。

Prompt file requirement (hard): 每次生成前，把完整最终 prompt 写入 prompts/cover.md。该文件是复现记录，也是平台 API 的 prompt 来源。

Confirmation Policy

Default behavior: confirm before generation.

  • Treat explicit skill invocation, a file path, matched keywords/presets, EXTEND.md defaults, and any documented auto-selection as recommendation inputs only. None of them authorizes skipping confirmation.
  • Do not start Step 3 or Step 4 until the user confirms the dimensions / aspect / language choices.
  • Skip confirmation only when the current request explicitly says to do so, for example: --quick, "直接生成", "不用确认", "跳过确认", "按默认出图", or equivalent wording. quick_mode: true in EXTEND.md counts as a standing explicit opt-out — set it only when you want every run to skip Step 2.
  • If confirmation is skipped explicitly, state the assumed dimensions / aspect / language / model in the next user-facing update before generating.

Options

| Option | Description | |--------|-------------| | --type <name> | hero, conceptual, typography, metaphor, scene, minimal | | --palette <name> | warm, elegant, cool, dark, earth, vivid, pastel, mono, retro, duotone, macaron | | --rendering <name> | flat-vector, hand-drawn, painterly, digital, pixel, chalk, screen-print | | --style <name> | Preset shorthand (see Style Presets) | | --text <level> | none, title-only, title-subtitle, text-rich | | --mood <level> | subtle, balanced, bold | | --font <name> | clean, handwritten, serif, display | | --aspect <ratio> | 16:9 (default), 2.35:1, 4:3, 3:2, 1:1, 3:4 | | --lang <code> | Title language (en, zh, ja, etc.) | | --no-title | Alias for --text none | | --quick | Skip confirmation, use auto-selection | | --ref <files...> | Reference image(s); the first direct reference becomes the /images/edits input when needed |

Five Dimensions

| Dimension | Values | Default | |-----------|--------|---------| | Type | hero, conceptual, typography, metaphor, scene, minimal | auto | | Palette | warm, elegant, cool, dark, earth, vivid, pastel, mono, retro, duotone, macaron | auto | | Rendering | flat-vector, hand-drawn, painterly, digital, pixel, chalk, screen-print | auto | | Text | none, title-only, title-subtitle, text-rich | title-only | | Mood | subtle, balanced, bold | balanced | | Font | clean, handwritten, serif, display | clean |

Auto-selection rules: references/auto-selection.md

Galleries

Types: hero, conceptual, typography, metaphor, scene, minimal → Details: references/types.md

Palettes: warm, elegant, cool, dark, earth, vivid, pastel, mono, retro, duotone, macaron → Details: references/palettes/

Renderings: flat-vector, hand-drawn, painterly, digital, pixel, chalk, screen-print → Details: references/renderings/

Text Levels: none (pure visual) | title-only (default) | title-subtitle | text-rich (with tags) → Details: references/dimensions/text.md

Mood Levels: subtle (low contrast) | balanced (default) | bold (high contrast) → Details: references/dimensions/mood.md

Fonts: clean (sans-serif) | handwritten | serif | display (bold decorative) → Details: references/dimensions/font.md

File Structure

Output directory per default_output_dir preference:

  • same-dir: {article-dir}/
  • imgs-subdir: {article-dir}/imgs/
  • independent (default): cover-image/{topic-slug}/
<output-dir>/
├── source-{slug}.{ext}    # Source files
├── refs/                  # Reference images (if provided)
│   ├── ref-01-{slug}.{ext}
│   └── ref-01-{slug}.md   # Description file
├── prompts/cover.md       # Generation prompt
└── cover.png              # Output image

Slug: 2-4 words, kebab-case. Conflict: append -YYYYMMDD-HHMMSS

Workflow

Progress Checklist

Cover Image Progress:
- [ ] Step 0: Check LINGJING_API_KEY ⛔ BLOCKING
- [ ] Step 0b: Check preferences (EXTEND.md) ⛔ BLOCKING
- [ ] Step 1: Analyze content + save refs + determine output dir
- [ ] Step 2: Confirm options (6 dimensions) ⚠️ unless --quick
- [ ] Step 3: Create prompt
- [ ] Step 4: Generate image
- [ ] Step 5: Completion report

Flow

Input → [Step 0: API Key gate] ─┬─ Missing/invalid → Show onboarding → STOP
                                └─ Valid → [Step 0b: Preferences] → Found → Continue
                                                                └─ Not found → First-Time Setup → Save EXTEND.md → Continue
        ↓
Analyze + Save Refs → [Output Dir] → [Confirm: 6 Dimensions] → Prompt → Platform API Generate → Complete
                                              ↓
                                     (skip if --quick or all specified)

Step 0: Check Platform API Key ⛔ BLOCKING

按“API Key Gate”规则检查环境变量。Key 缺失、为空或格式错误时停止，不询问封面选项，不分析文章内容，不调用模型 API。

Step 0b: Load Preferences ⛔ BLOCKING

Check EXTEND.md in priority order — the first one found wins:

| Priority | Path | Scope | |----------|------|-------| | 1 | .lingjing-skills/lingjing-cover-image/EXTEND.md | Project | | 2 | ${XDG_CONFIG_HOME:-$HOME/.config}/lingjing-skills/lingjing-cover-image/EXTEND.md | XDG | | 3 | $HOME/.lingjing-skills/lingjing-cover-image/EXTEND.md | User home |

| Result | Action | |--------|--------| | Found | Load, display summary → Continue | | Not found | ⛔ Run first-time setup (references/config/first-time-setup.md) → Save → Continue |

CRITICAL: If not found, complete setup BEFORE any other steps or questions.

Step 1: Analyze Content

  1. Save reference images (if provided) → references/workflow/reference-images.md
  2. Save source content (if pasted, save to source.md)
  3. Analyze content: topic, tone, keywords, visual metaphors
  4. Deep analyze references ⚠️: Extract specific, concrete elements (see reference-images.md)
  5. Detect language: Compare source, user input, EXTEND.md preference
  6. Determine output directory: Per File Structure rules

⚠️ People in Reference Images:

If reference images contain people who should appear in the cover:

  • Primary direct reference: Copy image to refs/, upload it as image via /api/v1/images/edits. The platform edit model sees the reference directly.
  • Additional references: Analyze them with LINGJING_VISION_MODEL (default qwen3.7-flash) and embed extracted hair, glasses, skin tone, clothing, style, palette and layout as MUST/REQUIRED textual instructions.

See reference-images.md for full decision table.

Step 2: Confirm Options ⚠️

Hard gate: this step is mandatory per the Confirmation Policy — Steps 3–4 cannot start until the user confirms here (or explicitly opts out with --quick / quick_mode: true / equivalent wording in the current request).

MUST use AskUserQuestion tool to present options as interactive selection — NOT plain text tables. Present up to 4 questions in a single AskUserQuestion call (Type, Palette, Rendering, Font + Settings). Each question shows the recommended option first with reason, followed by alternatives.

Full confirmation flow and question format: references/workflow/confirm-options.md

| Condition | Skipped | Still Asked | |-----------|---------|-------------| | --quick or quick_mode: true | 6 dimensions | Aspect ratio (unless --aspect) | | All 6 + --aspect specified | All | None |

Step 3: Create Prompt

Save to prompts/cover.md. Template: references/workflow/prompt-template.md

CRITICAL - References in Frontmatter:

  • Files saved to refs/ → Add to frontmatter references list; mark the uploaded primary as usage: direct
  • Style extracted verbally (no file) → Omit references, describe in body
  • Before writing → Verify: test -f refs/ref-NN-{slug}.{ext}

Reference elements in body MUST be detailed, prefixed with "MUST"/"REQUIRED", with integration approach.

Step 4: Generate Image

  1. Backup existing cover.png if regenerating.
  2. Write the full final prompt to prompts/cover.md (hard requirement) BEFORE invoking the API.
  3. Choose endpoint:
    • No reference image that must be preserved: call POST /api/v1/images/generations with model, prompt, size, n.
    • Direct reference image: choose one primary image, call POST /api/v1/images/edits with multipart model, prompt, image, size, n.
    • Multiple direct references: ask once which image is primary; if the user does not specify, use the first --ref file. Analyze remaining references with LINGJING_VISION_MODEL and append their constraints to the prompt.
  4. See references/platform-api.md for exact request and response handling.
  5. Failure handling: follow the error table in references/platform-api.md; for 502/timeout retry once, then switch once to LINGJING_COVER_FALLBACK_MODEL.

Step 5: Completion Report

Cover Generated!

Topic: [topic]
Type: [type] | Palette: [palette] | Rendering: [rendering]
Text: [text] | Mood: [mood] | Font: [font] | Aspect: [ratio]
Title: [title or "visual only"]
Language: [lang] | Watermark: [enabled/disabled]
References: [N images or "extracted style" or "none"]
Location: [directory path]

Files:
✓ source-{slug}.{ext}
✓ prompts/cover.md
✓ cover.png

Image Modification

| Action | Steps | |--------|-------| | Regenerate | Backup → Update prompt file FIRST → Regenerate | | Change dimension | Backup → Confirm new value → Update prompt → Regenerate |

Text correction policy:

  • If the title/subtitle is misspelled, garbled, hard to read, or visually weak, do not patch the bitmap with code.
  • For text-correction regenerations, write a new prompt file and a new output path so the flawed candidate is preserved for comparison.
  • Post-processing is limited to crop, resize, compression, or format conversion that does not alter text or the main composition.

Composition Principles

  • Whitespace: 40-60% breathing room
  • Visual anchor: Main element centered or offset left
  • Characters: Simplified silhouettes; NO realistic humans
  • Title: Use exact title from user/source; never invent

Changing Preferences

EXTEND.md lives at the path noted in Step 0b. Three ways to change it:

  • Edit directly — open EXTEND.md and change fields. Full schema: references/config/preferences-schema.md.
  • Reconfigure interactively — delete EXTEND.md (or ask "reconfigure lingjing-cover-image preferences" / "重新配置"). The next run re-triggers first-time setup.
  • Common one-line edits:
    • watermark.enabled: true, preferred_type, preferred_palette, preferred_rendering, default_aspect, quick_mode: true, language — shift the auto-selection defaults and confirmation flow.

References

Dimensions: text.md | mood.md | font.md Palettes: references/palettes/ Renderings: references/renderings/ Types: references/types.md Auto-Selection: references/auto-selection.md Style Presets: references/style-presets.md Compatibility: references/compatibility.md Visual Elements: references/visual-elements.md Platform API: references/platform-api.md Workflow: confirm-options.md | prompt-template.md | reference-images.md Config: preferences-schema.md | first-time-setup.md | watermark-guide.md