A local-first multi-agent app development platform, built on PenguinHarness
fix(skills): ollama, vllm and penguin-sdk teach openai-chat, not the alias (#417)
Myriad-Dreamin2a3f253bee3c
diff --git a/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.md b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.mdnew file mode 100644index 00000000..4edaf2c6--- /dev/null+++ b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.md@@ -0,0 +1,22 @@+# Library skills spell the OpenAI client type `openai-chat`++- **Date:** 2026-08-23+- **Type:** process+- **Scope:** `skills`+- **PR:** [#417](https://github.com/Prism-Shadow/penguin-harness/pull/417)++[中文版](2026-08-23-skills-teach-openai-chat-client-type.zh.md)++The `ollama`, `vllm` and `penguin-sdk` skills registered OpenAI-compatible endpoints with+`--client-type openai`, the pre-AgentHub-0.4.2 spelling that `agenthub-models` documents as a+deprecated alias. All five occurrences now read `openai-chat` (`ollama` and `vllm` at `v2`,+`penguin-sdk` at `v22`).++## Details++- Both the prose step and the full command example were updated in `ollama` and `vllm`; the+ `penguin-sdk` setup recipe was updated in the optional flag and in the recommendation that+ follows it.+- The alias keeps working — `canonicalClientType` normalizes it on read and on write, and the+ CLI already writes `openai-chat` for a new OpenAI-routed entry — so this changes what the+ library teaches, not what an existing config does.diff --git a/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.md b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.mdnew file mode 100644index 00000000..069e9776--- /dev/null+++ b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.md@@ -0,0 +1,19 @@+# 库内 skill 统一使用 `openai-chat` 作为 OpenAI 客户端类型++- **Date:** 2026-08-23+- **Type:** process+- **Scope:** `skills`+- **PR:** [#417](https://github.com/Prism-Shadow/penguin-harness/pull/417)++[English](2026-08-23-skills-teach-openai-chat-client-type.md)++`ollama`、`vllm`、`penguin-sdk` 三个 skill 在注册 OpenAI 兼容端点时写的是 `--client-type openai`,+即 AgentHub 0.4.2 之前的拼法,而 `agenthub-models` 早已把它记作废弃别名。五处全部改为 `openai-chat`+(`ollama`、`vllm` 升到 `v2`,`penguin-sdk` 升到 `v22`)。++## 细节++- `ollama` 与 `vllm` 的说明步骤和完整命令示例都做了改动;`penguin-sdk` 改的是配置流程里的可选参数+ 及紧随其后的推荐写法。+- 该别名仍然可用——`canonicalClientType` 在读和写两侧都会归一化,CLI 为新的 OpenAI 路由条目本来就+ 写入 `openai-chat`——所以变的是库教什么,不是既有配置的行为。diff --git a/packages/skills/skills/ollama/SKILL.md b/packages/skills/skills/ollama/SKILL.mdindex e4dac8ef..d3b76560 100644--- a/packages/skills/skills/ollama/SKILL.md+++ b/packages/skills/skills/ollama/SKILL.md@@ -3,8 +3,8 @@ name: ollamadescription: Deploy and serve local models with Ollama — pull and run them, then expose the OpenAI-compatible endpoint to apps and agents.short_description: Run local models with Ollama.short_description_zh: 用 Ollama 运行本地模型。-version: 1-updated: 2026-07-22T00:00:00Z+version: 2+updated: 2026-08-23T15:42:44Z---# Ollama Serving@@ -32,7 +32,7 @@ If port 11434 is already serving, reuse that instance — never kill an existing2. Pick the engine the user prefers: Ollama is the default; vLLM covers high-throughput GPU serving.3. Install Ollama if missing, then `ollama pull qwen3.5:0.8b`.4. Verify with `curl http://localhost:11434/v1/models`.-5. Register the endpoint: `penguin config model add ... --client-type openai --base-url http://localhost:11434/v1` — a pulled Ollama model is not visible to Penguin until added.+5. Register the endpoint: `penguin config model add ... --client-type openai-chat --base-url http://localhost:11434/v1` — a pulled Ollama model is not visible to Penguin until added.6. Confirm the new entry with `penguin config model list`.## Install@@ -85,7 +85,7 @@ ollama create qwen3.5-32k -f ModelfileModel configuration is the penguin CLI's job — `penguin config model add` registers an endpoint and `penguin config model list` shows what has been registered. A pulled Ollama model is not visible to Penguin until you add it:```bash-penguin config model add --provider custom --client-type openai \+penguin config model add --provider custom --client-type openai-chat \--base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollamapenguin config model list # the new entry should now be listed```diff --git a/packages/skills/skills/penguin-sdk/SKILL.md b/packages/skills/skills/penguin-sdk/SKILL.mdindex 1941c6ae..14901a12 100644--- a/packages/skills/skills/penguin-sdk/SKILL.md+++ b/packages/skills/skills/penguin-sdk/SKILL.md@@ -3,8 +3,8 @@ name: penguin-sdkdescription: Use whenever the user wants to build an agent application — their own program with an embedded agent, such as an AI app, an agentic app or a RAG app. This is writing application code on the Penguin Harness SDK, not configuring an Agent State inside PenguinHarness. Covers self-contained projects, the createSession/run streaming loop with thinking and image messages, wiring the user's existing tools in as CLI commands, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.short_description: Build agent, AI and RAG applications on the Penguin Harness SDK.short_description_zh: 基于 Penguin SDK 构建智能体应用、AI 与 RAG 应用。-version: 21-updated: 2026-08-21T00:00:00Z+version: 22+updated: 2026-08-23T15:42:44Z---# Penguin Harness SDK@@ -55,7 +55,7 @@ If the package is not on your npm registry (it is developed in the PenguinHarnesConfigure a model for the app's data root, in this order — stop at the first that works:-1. `penguin config model add --root <data_dir> --provider <group> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai] --set-default` — prefer `--client-type openai --base-url <endpoint>` (works with any OpenAI-compatible endpoint; exact ids in the agenthub-models skill). `--provider` is required: a model is always the `(provider, model_id)` pair and the group is never inferred from the id (`custom` for an endpoint outside the built-in groups).+1. `penguin config model add --root <data_dir> --provider <group> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai-chat] --set-default` — prefer `--client-type openai-chat --base-url <endpoint>` (works with any OpenAI Chat Completions compatible endpoint; exact ids in the agenthub-models skill). `--provider` is required: a model is always the `(provider, model_id)` pair and the group is never inferred from the id (`custom` for an endpoint outside the built-in groups).2. Environment variables cover the **credential only** (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) — model selection still comes from the project config, whose preset default is `deepseek-v4-flash`. Env-only setup therefore works out of the box only with `DEEPSEEK_API_KEY`; for another vendor either run the CLI command above or pass a configured `{ provider, modelId }` pair to `createSession`.Keep model API keys **project-local**: configure them with the penguin CLI into the app's own data root under the working directory, so the project stays self-contained and movable. When building an AI app, **always pass `--root <data_dir>` pointing at the app's data directory inside the current working directory** (the same path you give `createAgent({ root })`, e.g. `./penguin_data`) — never run `penguin config ...` without `--root`, or it writes to the global `~/.penguin/data` instead of the project. Never read, copy or fall back to model keys stored in the user's global `~/.penguin` directory — that config belongs to the person running Penguin, not to the app you are building.diff --git a/packages/skills/skills/vllm/SKILL.md b/packages/skills/skills/vllm/SKILL.mdindex cbd36796..a2efe368 100644--- a/packages/skills/skills/vllm/SKILL.md+++ b/packages/skills/skills/vllm/SKILL.md@@ -3,8 +3,8 @@ name: vllmdescription: Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint, with tool calling enabled for agent workloads.short_description: Serve models locally with vLLM.short_description_zh: 用 vLLM 部署本地模型服务。-version: 1-updated: 2026-07-22T00:00:00Z+version: 2+updated: 2026-08-23T15:42:44Z---# vLLM Serving@@ -32,7 +32,7 @@ The model must fit the available VRAM — model size and context length drive th2. Pick the engine the user prefers: vLLM for high-throughput GPU serving; Ollama is the simple default and the choice on macOS or CPU-only machines.3. Serve on a free port, with the tool-calling flags whenever agents will call it (see below).4. Verify with `curl http://localhost:8000/v1/models`.-5. Register the endpoint: `penguin config model add ... --client-type openai --base-url http://localhost:8000/v1` — a served model is not visible to Penguin until added.+5. Register the endpoint: `penguin config model add ... --client-type openai-chat --base-url http://localhost:8000/v1` — a served model is not visible to Penguin until added.6. Confirm the new entry with `penguin config model list`.## Install@@ -82,7 +82,7 @@ curl http://localhost:8000/v1/modelsModel configuration is the penguin CLI's job — `penguin config model add` registers an endpoint and `penguin config model list` shows what has been registered. A served model is not visible to Penguin until you add it:```bash-penguin config model add --provider custom --client-type openai \+penguin config model add --provider custom --client-type openai-chat \--base-url http://localhost:8000/v1 --model-id <served-model-name> --api-key <key>penguin config model list # the new entry should now be listed```