Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

docs(landing): rewrite every blog post for readability (#757)

Yaowei Zhengde6567cbf79e
diff --git a/changelog/unreleased/2026-09-16-blog-rewrite.md b/changelog/unreleased/2026-09-16-blog-rewrite.md
new file mode 100644
index 00000000..d336970c
--- /dev/null
+++ b/changelog/unreleased/2026-09-16-blog-rewrite.md
@@ -0,0 +1,40 @@
+# Every blog post rewritten for readability
+
+- **Date:** 2026-09-16
+- **Type:** process
+- **Scope:** `landing`
+- **PR:** [#757](https://github.com/Prism-Shadow/penguin-harness/pull/757)
+
+[中文版](2026-09-16-blog-rewrite.zh.md)
+
+All 21 blog posts were rewritten in both languages. The English version of each post was
+rewritten first and the Chinese version translated from it, and every draft was checked against
+the old post, the product's UI strings and the code before it replaced the old text.
+
+## Details
+
+- Release posts (0.1.4 through 0.2.13), the launch post, the model posts and the July roundup now
+ open with a short summary and give each change its own section: what users can now do, how to
+ use it, and any limit worth knowing. Internal implementation detail that does not change what a
+ user sees was dropped.
+- The three practice posts became step-by-step tutorials with prerequisites, numbered steps and
+ expected results. `natural-language-training-loop` was restructured from an argument into steps
+ built on the prompts the post already used.
+- The three perspectives essays state their question and thesis up front and give each step of the
+ argument its own section. Their dated claims were kept as of their publication date.
+- Stale or wrong statements were corrected against the code at each post's release, among them:
+ the 0.2.13 post now says that the CEO-proposes, board-decides rule is guidance in the company
+ Skills and handbook rather than something the server enforces; the 0.2.4 post names the default
+ command-policy rules that block commands such as `rm -rf`; the self-improvement tutorial creates
+ `meeting_summary_agent`, because agent ids do not allow hyphens. UI labels are the ones the app
+ showed on each post's date (for example **Set API key for group**, **Costs**, **Trajectory**),
+ and claims that no longer hold today are tied to the version they describe.
+- In-page anchor links were replaced by plain references to the section they pointed at.
+- Posts whose title names no release open with a note saying which version they were written for
+ (0.0.1, 0.1.0, 0.1.1 or 0.1.2).
+- The Chinese posts use the Chinese UI's own labels and the product's term 插话 for steering, keep
+ their China-specific material (the China ADP route in the Fireworks guide, localized prompts
+ and screenshots), and render every bold span next to CJK punctuation.
+- The landing package now checks the blog directory itself: every post ships both languages, the
+ two halves agree on `date`, `category` and `pinned`, and every `penguin.ooo/docs/<slug>` a post
+ links to is a page the docs site navigates.
diff --git a/changelog/unreleased/2026-09-16-blog-rewrite.zh.md b/changelog/unreleased/2026-09-16-blog-rewrite.zh.md
new file mode 100644
index 00000000..30de5140
--- /dev/null
+++ b/changelog/unreleased/2026-09-16-blog-rewrite.zh.md
@@ -0,0 +1,21 @@
+# 全部博客文章按可读性重写
+
+- **Date:** 2026-09-16
+- **Type:** process
+- **Scope:** `landing`
+- **PR:** [#757](https://github.com/Prism-Shadow/penguin-harness/pull/757)
+
+[English](2026-09-16-blog-rewrite.md)
+
+21 篇博客文章的中英文版本全部重写。每篇先重写英文,再由英文翻译出中文;每份草稿在替换旧文之前,都对照了旧文、产品界面文案和代码逐项核对。
+
+## 细节
+
+- 发布文章(0.1.4 到 0.2.13)、首发文章、模型文章和七月汇总,开头改为简短概述,每项改动单独成节:用户现在能做什么、怎么用、有哪些值得知道的限制。与用户所见无关的内部实现细节已删去。
+- 三篇实践文章改成分步教程,包含前提条件、编号步骤和预期结果。`natural-language-training-loop` 从论述改为分步结构,步骤沿用文章原有的提示词。
+- 三篇观点文章在开头点明问题和论点,论证的每一步单独成节;带有时间属性的说法保持发布当时的口径。
+- 对照每篇文章发布时的代码,修正了过时或错误的说法,例如:0.2.13 文章改为说明「CEO 提议、董事会拍板」是公司 Skill 和手册里的约定,服务端并不强制;0.2.4 文章写明了默认命令策略规则会拦截 `rm -rf` 这类命令;自我进化教程创建的 Agent 改为 `meeting_summary_agent`,因为 Agent id 不允许连字符。界面文字采用文章发布当天应用里的写法(例如 **Set API key for group**、**Costs**、**Trajectory**,中文为「统一配置 API key」「成本中心」「模型仓库」),如今已不成立的说法注明了所指的版本。
+- 页内锚点链接改为直接写明所指的小节。
+- 标题里没有版本号的文章,开头加了一行说明,写明文章基于哪个版本撰写(0.0.1、0.1.0、0.1.1 或 0.1.2)。
+- 中文文章使用中文界面的原文和产品中表示 steering 的术语「插话」,保留面向中文读者的内容(Fireworks 指南中的 AMD 中国站申请路径、本地化的提示词与截图),并确保紧挨中文标点的加粗都能正常渲染。
+- landing 包新增对博客目录本身的校验:每篇文章都有中英两个版本,两份 frontmatter 的 `date`、`category`、`pinned` 一致,文章里指向 `penguin.ooo/docs/<slug>` 的链接都能对上文档站实际存在的页面。
diff --git a/packages/landing/content/blog/ai-infrastructure-past-present-future.en.md b/packages/landing/content/blog/ai-infrastructure-past-present-future.en.md
index 81f7be87..bfcf6bbe 100644
--- a/packages/landing/content/blog/ai-infrastructure-past-present-future.en.md
+++ b/packages/landing/content/blog/ai-infrastructure-past-present-future.en.md
@@ -2,44 +2,48 @@
title: "AI Infrastructure: Past, Present, and Future"
date: 2026-07-22
category: perspectives
-excerpt: PyTorch, vLLM, Ollama and LlamaFactory were all designed for a human who reads the docs, watches the logs and remembers what is already running. Increasingly the thing driving them is an agent. Here is what changes — and what PenguinHarness ships today to make it work.
+excerpt: AI infrastructure was built for human operators, and agents increasingly drive it. The stack already suits agents; what they lack is an engineer's operating knowledge, which PenguinHarness ships as Skills.
---
-The infrastructure we use to build AI was designed for people. PyTorch assumes someone reading a tutorial. vLLM assumes an engineer who knows how much VRAM the card has. LlamaFactory assumes a researcher who will read the training curve and decide whether it is going well. Ollama assumes you remember whether the service is already running.
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
-Every one of those assumptions is about a human operator. And increasingly, the operator is an agent.
+The infrastructure we use to build AI was designed for people. PyTorch assumes someone reading a tutorial. vLLM assumes an engineer who knows how much VRAM the GPU has. LlamaFactory assumes a researcher who reads the training curve and decides whether training is going well. Ollama assumes you remember whether the service is already running.
-This is a short post about what that changes, and what we already ship for it.
+Every one of these assumptions is about a human operator, and the operator is increasingly an agent: a model that does its work by calling tools. This post asks what changes when a program drives the stack. Our answer is that the stack itself needs little change, because it is already text and commands that an agent can run through a shell.
-## 1. Past: three assumptions about a human operator
+What agents lack is the operating knowledge a competent engineer carries. That knowledge can be written down, and PenguinHarness ships it today as Skills, together with runtime support for long jobs and readable failures. Three problems remain that nobody has solved yet.
-Three assumptions run through nearly all AI tooling, and all three quietly break when the user is a program.
+## Past: the stack assumes a human operator
-### 1.1 That the user carries state in their head
+Three assumptions about the operator run through nearly all AI tooling, and all three quietly break when the operator is a program.
-You know you started an Ollama server this morning. You know the training job from last night is still holding the GPU. None of that is in any command's output, because a human did not need it written down.
+### The operator keeps state in their head
-### 1.2 That errors are a starting point for investigation
+The first assumption is that the user remembers what is running. You know you started an Ollama server this morning. You know last night's training job still holds the GPU. No command prints either fact, because a human never needed it written down. An agent that sees only command output knows neither.
-`CUDA out of memory` is a perfectly good message for a person — you read it, you halve the batch size, you move on. It tells an agent almost nothing about what to do next, and the ML stack is full of errors like it: shape mismatches thrown eight frames deep, NCCL timeouts, a silent fallback to CPU that only shows up as everything being forty times slower.
+### Errors start an investigation
-### 1.3 That documentation is read once, by someone who will remember it
+The second assumption is that an error message is where a person starts investigating. `CUDA out of memory` is a good message for a person: you read it, halve the batch size, and move on. It tells an agent almost nothing about what to do next. The ML stack is full of errors like it: shape mismatches thrown eight frames deep, NCCL timeouts, and a silent fallback to CPU whose only symptom is that everything runs forty times slower.
-Tutorials are written as prose, front to back, with the important constraint — the model has to fit in VRAM — in a sentence somewhere in the middle.
+Stripe measured what this costs when it benchmarked whether agents could build real integrations against its API. The failure mode it found generalizes well beyond Stripe: agents "would pass in nonexistent Stripe data, observe 400s, and consider the task complete." The error was correct. It still failed to communicate failure.
-Stripe measured what this costs when they benchmarked whether agents could build real integrations against their API. The failure mode they found generalizes uncomfortably well: agents "would pass in nonexistent Stripe data, observe 400s, and consider the task complete." The error was correct. It still failed to communicate failure.
+### Documentation is read once
-## 2. Present: the stack is already agent-shaped
+The third assumption is that documentation is read once, by someone who will remember it. Tutorials are prose, written to be read front to back. The most important constraint, for example that the model has to fit in VRAM, sits in a sentence somewhere in the middle.
-### 2.1 The shell is the integration
+## Present: the stack is already agent-shaped
-The good news is that AI infrastructure is, by accident, better suited to agents than most software. It is already command-line tools, YAML configs and Python files — text in, text out, composable. There is no need to wrap `nvidia-smi` in anything. An agent with a shell can already drive the entire stack.
+The stack needs no new interfaces for agents. It needs operating knowledge and a runtime built for AI work, which is shaped differently from web work.
-That is why PenguinHarness exposes the shell as its universal interface — `exec_command` is the whole filesystem and process interface, and there are no separate file tools. Driving vLLM is not an integration; it is a command.
+### The shell is the integration layer
-### 2.2 What actually needs building: the operating knowledge
+AI infrastructure is, by accident, better suited to agents than most software. It already consists of command-line tools, YAML configs, and Python files: text in, text out, and composable. A tool like `nvidia-smi` needs no wrapper, because an agent with a shell can already drive the entire stack.
-What is missing is not connectivity. It is the operating knowledge a competent engineer has and a model does not. We ship that as **Skills** — instruction packages an agent reads on demand. Three of them cover this stack directly, in the AI App Development group:
+That is why PenguinHarness uses the shell as its universal interface. In 0.1.1, `exec_command` was the whole filesystem and process interface, and there were no separate file tools. Driving vLLM is not an integration; it is a command.
+
+### What is missing is operating knowledge
+
+What is missing is not connectivity. It is the operating knowledge a competent engineer has and a model does not. PenguinHarness ships that knowledge as **Skills**, instruction packages an agent reads on demand. Three of them, in the AI App Development group, cover this stack directly:
| Skill | What it lets an agent do |
| --- | --- |
@@ -47,41 +51,43 @@ What is missing is not connectivity. It is the operating knowledge a competent e
| `vllm` | Serve on GPU for high throughput, with tool-calling flags enabled for agent workloads |
| `llamafactory` | Fine-tune with LoRA/QLoRA, SFT or DPO through YAML configs |
-What is in them is more interesting than that they exist, because each one encodes a rule a human would never have needed:
+What these Skills contain matters more than the fact that they exist. They encode rules that a human operator never needed to be told:
+
+1. **Check the world before changing it.** The `ollama` Skill has the agent run `ollama --version` and `ollama ps` first. Then it states the rule plainly: if port 11434 is already serving, reuse that instance, and *never kill an existing Ollama process*. A human knows not to kill a colleague's server. An agent has to be told.
+2. **Check the real constraint first.** The `vllm` Skill confirms the hardware with `nvidia-smi` (or `rocm-smi` on AMD) before it serves anything, because VRAM limits both model size and context length. The sentence buried in the tutorial becomes step zero.
+3. **Verify instead of assuming.** Both serving Skills end with a real check before the job counts as done, such as `curl http://localhost:8000/v1/models` for vLLM. This is the direct answer to the Stripe failure mode: success is defined by an observation, not by the absence of a crash.
+4. **Finish the job.** PenguinHarness cannot see a served model until it is registered. The Skills therefore close the loop with `penguin config model add --client-type openai --base-url ...` and confirm the result with `penguin config model list`. Starting a server is not the task. Having a usable model is.
+5. **Ask instead of guessing.** All three Skills open the same way: if the request names the Skill but gives no concrete goal, the agent asks first and runs nothing. The choice of engine also follows the user's preference rather than a hardcoded default. vLLM is for high-throughput GPU serving, while Ollama is the simple default and the only one of the two that runs on macOS or CPU-only machines.
-1. **Check the world before changing it.** The `ollama` skill has the agent run `ollama --version` and `ollama ps` first, and then states the rule plainly: if port 11434 is already serving, reuse that instance — *never kill an existing Ollama process*. A human knows not to kill their colleague's server. An agent has to be told.
-2. **Preflight the constraint that actually binds.** The `vllm` skill confirms hardware with `nvidia-smi` (or `rocm-smi` on AMD) before anything else, because model size and context length are bounded by VRAM. The buried sentence in the tutorial becomes step zero.
-3. **Verify, do not assume.** Both serving skills end with a real check — `curl http://localhost:8000/v1/models` — before the job counts as done. This is the direct answer to the Stripe failure mode: the definition of success is an observation, not the absence of a crash.
-4. **Finish the job.** A served model is invisible to PenguinHarness until it is registered, so the skills close the loop with `penguin config model add --client-type openai --base-url ...` and then confirm with `penguin config model list`. Starting a server is not the task. Having a usable model is.
-5. **Ask instead of guessing.** Every skill opens the same way: if the request names a skill but no concrete goal, ask first and run nothing. Engine choice, for instance, follows the user's preference rather than a hardcoded default — vLLM for high-throughput GPU serving, Ollama as the simple default and the only option on macOS or CPU-only machines.
+### Long jobs are first-class
-### 2.3 Two runtime pieces, because AI work is not shaped like web work
+Training and serving do not finish in thirty seconds, so the runtime treats long jobs as the normal case. `exec_command` waits in the foreground. Once a command outruns its wait window, it keeps running in the background and the tool returns a `process_id`. `input_command` then polls that process, writes to its stdin, or sends Ctrl-C. An agent can start a fine-tune, do something else, and come back to check on it, without a special training tool.
-**Long jobs are first-class.** Training and serving do not complete in thirty seconds. `exec_command` waits in the foreground, and once a command outruns its window it keeps running in the background and hands back a `process_id`; `input_command` then polls it, writes to stdin, or sends Ctrl-C. An agent can start a fine-tune, go do something else, and come back to check on it — without a special "training tool."
+### Failures come back as text
-**Failures come back as text, not exceptions.** Tools never throw into the loop. A non-zero exit, a timeout, an OOM — all of it converges into tool output the model reads and reacts to, with the exit code appended outside the truncation window so it survives even when a long log gets cut. That last detail matters more than it sounds: the one line telling you the run actually failed is usually the last one.
+Tools never throw exceptions into the agent loop. A non-zero exit, a timeout, or an out-of-memory (OOM) error becomes tool output that the model reads and reacts to. The exit code is appended outside the truncation window, so it survives even when a long log is cut. That detail matters more than it seems, because the line that says a run failed is usually the last one.
-## 3. Future: what is still hard
+## Future: three unsolved problems
-Three problems are not solved, by us or anyone.
+Three problems remain unsolved, by us or by anyone else.
-### 3.1 ML-stack errors are still written for humans
+### ML-stack errors are still written for humans
-Nothing in an agent harness can fix a traceback that does not say what to change. The fix has to happen upstream, in the frameworks — and the guidance already exists: good tool errors are specific and actionable rather than opaque codes and tracebacks. Very little of the training stack meets that bar today.
+Nothing in an agent harness, the software that runs an agent's loop and its tools, can fix a traceback that does not say what to change. The fix has to happen upstream, in the frameworks. The guidance already exists: [Anthropic's advice on writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) says good tool errors are specific and actionable, not opaque codes and tracebacks. Very little of the training stack meets that bar today.
-### 3.2 GPUs are a shared resource with no protocol
+### GPUs are shared without a protocol
-An agent can read `nvidia-smi`, but there is no standard way to reserve VRAM, queue behind another job, or find out that the memory it just saw is about to be taken. Today the answer is a written rule — do not kill what you did not start — which is a convention, not a guarantee.
+An agent can read `nvidia-smi`, but there is no standard way to reserve VRAM, to queue behind another job, or to learn that the memory it just saw is about to be taken. Today the answer is a written rule: do not kill what you did not start. That is a convention, not a guarantee.
-### 3.3 Reproducibility is unresolved
+### Reproducibility is unresolved
-A fine-tune is a long, expensive, stochastic action. Agents make those cheap to launch, which makes it much easier to end up with a model nobody can reproduce. Snapshots and traces help; they are not a full answer.
+A fine-tune is long, expensive, and stochastic. Agents make such runs cheap to launch, which makes it much easier to end up with a model nobody can reproduce. Snapshots and Traces help, but they are not a full answer.
-## 4. The short version
+## Conclusion
-AI infrastructure did not need to be reinvented for agents — it was already text and commands. What was missing is the operating knowledge around it: check before you change, preflight the real constraint, verify with an observation, and finish the job rather than starting it.
+AI infrastructure did not need to be reinvented for agents, because it was already text and commands. What was missing is the operating knowledge around it: check before you change anything, check the real constraint first, verify with an observation, and finish the job instead of only starting it.
-That is what our skills encode, on top of a shell, a two-phase process model for long jobs, and errors that come back as readable text.
+PenguinHarness encodes that knowledge in Skills. Underneath them are a shell, a two-phase process model for long jobs, and errors that come back as readable text. The commands below install PenguinHarness and ask an agent to serve a local model and register it:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
@@ -90,7 +96,7 @@ penguin run -m "Serve Qwen3.5-0.8B with Ollama and register it with Penguin"
---
-- **Docs**: [Skills](https://penguin.ooo/docs/skills) · [Tools & Approval](https://penguin.ooo/docs/tools) · [Models & Providers](https://penguin.ooo/docs/models)
+- **Docs**: [Skills & Plugins](https://penguin.ooo/docs/skills) · [Tools & Approval](https://penguin.ooo/docs/tools) · [Models & Providers](https://penguin.ooo/docs/models)
- **Community**: [GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**Sources**: [vLLM](https://docs.vllm.ai/) · [Ollama](https://ollama.com/) · [LlamaFactory](https://github.com/hiyouga/LlamaFactory) · [Stripe, Can AI agents build real Stripe integrations?](https://stripe.com/blog/can-ai-agents-build-real-stripe-integrations) · [Anthropic, Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
diff --git a/packages/landing/content/blog/ai-infrastructure-past-present-future.zh.md b/packages/landing/content/blog/ai-infrastructure-past-present-future.zh.md
index b3c0ceb3..ad59fc78 100644
--- a/packages/landing/content/blog/ai-infrastructure-past-present-future.zh.md
+++ b/packages/landing/content/blog/ai-infrastructure-past-present-future.zh.md
@@ -2,86 +2,92 @@
title: "AI 基础设施:过去、现在与未来"
date: 2026-07-22
category: perspectives
-excerpt: PyTorch、vLLM、Ollama、LlamaFactory,都是照着"一个会读文档、会看日志、记得自己启过什么服务的人"来设计的。可现在,越来越多地在驱动它们的是 Agent。这个变化意味着什么,PenguinHarness 今天又为它准备了什么。
+excerpt: AI 基础设施是为人类操作者打造的,如今驱动它的越来越多是 Agent。这套技术栈本身就适合 Agent,Agent 缺的是工程师的操作经验,PenguinHarness 把这些经验做成了 Skill。
---
-我们用来构建 AI 的这套基础设施,是照着人来设计的。PyTorch 默认有人在读教程;vLLM 默认工程师清楚自己显卡有多少显存;LlamaFactory 默认研究者会盯着 loss 曲线判断训练正不正常;Ollama 则默认你记得服务是不是已经起来了。
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-**这些默认无一例外都指向一个人类操作者。而现在,操作者越来越多地是 Agent。**
+我们用来构建 AI 的这套基础设施,是照着人来设计的。PyTorch 默认有人在读教程;vLLM 默认工程师清楚 GPU 有多少显存;LlamaFactory 默认研究者会看训练曲线,判断训练是否正常;Ollama 则默认你记得服务是不是已经在运行。
-这篇文章不长,只讲两件事:这个变化带来了什么,以及我们现在为它准备了什么。
+这些默认针对的都是人类操作者,而现在,操作者越来越多地换成了 Agent,也就是靠调用工具干活的模型。本文要回答的问题是:驱动这套技术栈的一方换成程序之后,会发生什么变化。我们的回答是,技术栈本身几乎不用改,它本来就是文本和命令,Agent 通过 shell 就能跑起来。
-## 一、过去:关于"人类操作者"的三个默认
+Agent 缺的是称职工程师身上的操作经验。这些经验可以写下来,PenguinHarness 现在就把它们做成了 Skill,运行时也支持长任务,失败会以可读文本返回。另外还有三个问题,目前谁都没有解决。
-几乎所有 AI 工具链里都埋着三个默认。使用者一旦换成程序,这三个默认全都会悄无声息地失效。
+## 过去:技术栈默认操作者是人
-### 1.1 默认使用者把状态记在脑子里
+几乎所有 AI 工具都默认了关于操作者的三件事。操作者一旦换成程序,这三条默认会悄无声息地全部失效。
-你知道今天早上启过一个 Ollama 服务,也知道昨晚那个训练任务还占着显卡。这些信息不会出现在任何一条命令的输出里,因为人本来就不需要它被写下来。
+### 操作者把状态记在脑子里
-### 1.2 默认错误信息是排查的起点,而不是行动指令
+第一个默认是,用户记得有哪些东西在运行。你知道今天早上启动过一个 Ollama 服务,也知道昨晚的训练任务还占着 GPU。这两件事不会出现在任何命令的输出里,因为人从来不需要把它们写下来。只看得到命令输出的 Agent,两件事都无从知道。
-`CUDA out of memory` 对人来说是条相当好的消息:看一眼,把 batch size 减半,接着干。可它几乎没告诉 Agent 下一步该做什么。而 ML 技术栈里满是这类错误——从八层调用栈深处抛出来的 shape mismatch、NCCL 超时,还有悄悄回落到 CPU,唯一的症状是所有东西慢了四十倍。
+### 报错是排查的起点
-### 1.3 默认文档只读一次,而且读的人记得住
+第二个默认是,报错是人开始排查的起点。`CUDA out of memory` 对人来说是条挺好的报错:看一眼,把 batch size 减半,接着干。可它几乎没告诉 Agent 下一步该做什么。ML 技术栈里满是这类报错:从八层调用栈深处抛出来的 shape 不匹配,NCCL 超时,还有悄悄回退到 CPU 运行,唯一的症状是一切都慢了四十倍。
-教程是按文章写的,讲究从头读到尾,而真正会卡住你的那条约束——模型得放得进显存——躲在中间某一句话里。
+Stripe 评测 Agent 能不能基于自家 API 做出真实集成时,算过这笔账。他们发现的失败模式放到别处同样成立:Agent「会传入根本不存在的 Stripe 数据,收到 400,然后认为任务已经完成」。报错本身没有错,却没能把「失败」传达出去。
-Stripe 评测 Agent 能不能基于他们的 API 做出真实集成时,把这笔账算了出来。他们发现的失败模式放到别处同样成立,而且让人不太舒服:Agent 传入了根本不存在的数据,收到 400,然后认为任务已经完成。**错误本身是对的,但它没能把"失败"这件事传达出去。**
+### 文档只读一遍
-## 二、现在:这套技术栈本来就对 Agent 友好
+第三个默认是,文档只读一遍,而且读的人记得住。教程写成文章,要从头读到尾。最重要的约束,比如模型必须放得进显存,只是埋在中间某处的一句话。
-### 2.1 Shell 就是集成层
+## 现在:技术栈天然适合 Agent
-好消息是,AI 基础设施其实比大多数软件都更适合 Agent,而且属于无心插柳:它本来就是命令行工具、YAML 配置和 Python 文件,文本进、文本出,天然可组合。没必要给 `nvidia-smi` 再包一层什么,**一个拿着 shell 的 Agent 已经能把整个栈跑通了。**
+这套技术栈不需要为 Agent 新增接口。它需要的是操作经验,以及一个贴合 AI 工作的运行时,因为 AI 的活和 Web 的活形态不同。
-这正是 PenguinHarness 把 shell 当作通用接口的理由:`exec_command` 就是全部的文件与进程接口,没有另外的文件工具。**驱动 vLLM 不算一次"集成",它就是一条命令。**
+### Shell 就是集成层
-### 2.2 真正需要补的,是操作经验
+AI 基础设施比大多数软件更适合 Agent,而且纯属无心插柳。它本来就是命令行工具、YAML 配置和 Python 文件:文本进,文本出,可以自由组合。`nvidia-smi` 这类工具用不着再包一层,一个拿着 shell 的 Agent 已经能驱动整个技术栈。
-缺的从来不是连通性,而是一个称职工程师有、模型没有的那点**操作经验**。我们把它做成 **Skills**,也就是 Agent 按需读取的指令包。其中三个直接覆盖这套技术栈,归在 AI 应用开发技能组里:
+所以 PenguinHarness 把 shell 当作通用接口:在 0.1.1 版本里,`exec_command` 就是全部的文件系统与进程接口,还没有单独的文件工具。驱动 vLLM 算不上一次集成,它就是一条命令。
-| Skill | 让 Agent 能做什么 |
+### 缺的是操作经验
+
+缺的不是连通性,而是称职工程师有、模型没有的操作经验。PenguinHarness 把这些经验做成 **Skill**,也就是 Agent 按需读取的指令包。其中三个归在「AI 应用开发」分组,直接覆盖这套技术栈:
+
+| Skill | Agent 能用它做什么 |
| --- | --- |
| `ollama` | 拉取并启动本地模型,对外暴露 OpenAI 兼容端点 |
-| `vllm` | 在 GPU 上做高吞吐服务,并为 Agent 负载打开工具调用相关参数 |
+| `vllm` | 在 GPU 上做高吞吐服务,并为 Agent 负载打开工具调用参数 |
| `llamafactory` | 用 YAML 配置做 LoRA/QLoRA、SFT 或 DPO 微调 |
-比"有这三个技能"更值得说的,是它们里面到底写了什么——每一条都写下了一件人类根本不需要被叮嘱的事:
+比起「有这几个 Skill」,更值得说的是它们里面写了什么。它们写下的规则,人类操作者从来不需要别人叮嘱:
+
+1. **动手之前,先看清现场。** `ollama` Skill 让 Agent 先运行 `ollama --version` 和 `ollama ps`,然后把规矩挑明:如果 11434 端口上已经有服务,就复用这个实例,绝不杀掉已经在运行的 Ollama 进程。人知道不该动同事的服务,Agent 却得有人明确告诉它。
+2. **先确认真正的约束。** `vllm` Skill 在启动服务之前,先用 `nvidia-smi`(AMD 上是 `rocm-smi`)确认硬件,因为模型大小和上下文长度都受显存限制。教程里埋在中间的那句话,在这里成了第 0 步。
+3. **要验证,别想当然。** 两个服务类 Skill 都以一次真实检查收尾,比如 vLLM 的 `curl http://localhost:8000/v1/models`,检查通过才算完成任务。这正是对 Stripe 那个失败模式的直接回应:「成功」由一次观测来定义,而不是「没崩溃就算成功」。
+4. **把活干完。** 模型启动后不注册,PenguinHarness 就看不见它。所以这些 Skill 会用 `penguin config model add --client-type openai --base-url ...` 把这一步闭环,再用 `penguin config model list` 确认结果。启动一个服务不算完成任务,拿到一个能用的模型才算。
+5. **拿不准就问,别猜。** 三个 Skill 的开头都一样:如果请求只点了 Skill 的名字、没给具体目标,Agent 会先问清楚,一条命令都不跑。选哪个引擎也听用户的,而不是写死一个默认值:vLLM 用于高吞吐的 GPU 服务,Ollama 是省事的默认选项,也是两者中唯一能在 macOS 或纯 CPU 机器上运行的。
-1. **动手之前,先看清楚现场。** `ollama` 技能会让 Agent 先跑 `ollama --version` 和 `ollama ps`,然后把规矩挑明:如果 11434 端口上已经有服务,就复用它,**绝不去杀已经存在的 Ollama 进程**。人当然知道不该动同事的服务,Agent 却必须被明确告知。
-2. **先确认真正卡住你的那条约束。** `vllm` 技能在做任何事之前,先用 `nvidia-smi`(AMD 上是 `rocm-smi`)确认硬件,因为模型规模和上下文长度都被显存卡着。**教程里那句被埋起来的话,在这里被提到了第 0 步。**
-3. **要验证,别想当然。** 两个服务类技能都以一次真实检查收尾——`curl http://localhost:8000/v1/models`——过了才算完成。这正好回答了 Stripe 那个失败模式:**"成功"得由一次观测来定义,而不是"没崩就算成了"。**
-4. **把活干完,别只起个头。** 模型启动之后,不注册进来 PenguinHarness 是看不见它的,所以技能会用 `penguin config model add --client-type openai --base-url ...` 把这一步闭上,再用 `penguin config model list` 确认一遍。**起一个服务不叫完成任务,拿到一个能用的模型才叫。**
-5. **拿不准就问,别猜。** 每个技能开头都是同一句话:如果对方只点了技能名却没说具体要干什么,先问清楚,一条命令都别跑。比如引擎选哪个就听用户的,而不是写死一个默认值——vLLM 用于高吞吐 GPU 服务,Ollama 更省事,也是 macOS 和纯 CPU 机器上的唯一选择。
+### 长任务是一等公民
-### 2.3 还有两块运行时能力,因为 AI 的活跟 Web 不是一个形状
+训练和服务不可能三十秒跑完,所以运行时把长任务当作常态。`exec_command` 先在前台等待;命令一旦超出等待窗口,就转到后台继续运行,工具返回一个 `process_id`。之后由 `input_command` 轮询这个进程、向它的 stdin 写入内容,或者发送 Ctrl-C。Agent 可以先把微调跑起来,转头去做别的事,过一阵再回来看进度,不需要专门的训练工具。
-**长任务是一等公民。** 训练和服务不可能三十秒跑完。`exec_command` 先在前台等着,一旦命令超出等待窗口,它就转到后台继续跑并返回一个 `process_id`,之后由 `input_command` 去轮询、写 stdin 或者发 Ctrl-C。**Agent 可以先把微调发起来,转头去干别的,过一阵再回来看进度,不需要什么"训练专用工具"。**
+### 失败以文本返回
-**失败以文本返回,而不是抛异常。** 工具永远不会把异常抛进循环里。非零退出、超时、OOM,最后都收敛成模型读得懂、也能据此反应的工具输出;退出码还会被追加在截断窗口**之外**,哪怕长日志被砍掉也还在。这个细节比它听上去更要紧:**告诉你这次真的跑挂了的那一行,通常正好是最后一行。**
+工具永远不会把异常抛进 Agent 循环。非零退出、超时、内存耗尽(OOM),最后都会变成工具输出,交给模型读取和应对。退出码追加在截断窗口之外,哪怕长日志截断了,退出码也还在。这个细节比听上去更要紧:表明运行失败的那一行,通常就是最后一行。
-## 三、未来:仍然难啃的部分
+## 未来:三个尚未解决的问题
有三个问题至今没有解决,我们没有,别人也没有。
-### 3.1 ML 技术栈的错误信息,还是写给人看的
+### ML 技术栈的报错仍是写给人看的
-一段不说明"该改什么"的 traceback,任何 Agent harness 都救不回来。这事得在上游框架里修,而原则其实早就摆在那儿了:好的工具错误应该具体、可执行,而不是甩出一串晦涩的错误码和调用栈。**今天的训练栈里,达到这个标准的部分非常少。**
+Agent Harness 是运行 Agent 循环和工具的软件。一条不说明该改什么的 traceback,任何 Agent Harness 都救不回来。这件事得在上游的框架里解决。指导原则其实早就有了:[Anthropic 关于为 Agent 编写工具的建议](https://www.anthropic.com/engineering/writing-tools-for-agents)指出,好的工具报错应当具体、可执行,而不是一串晦涩的错误码和 traceback。今天的训练技术栈里,达到这个标准的部分非常少。
-### 3.2 GPU 是共享资源,却没有一套协议
+### GPU 是共享资源,却没有协议
-Agent 能读 `nvidia-smi`,但没有标准办法去预留显存、排队等另一个任务结束,或者提前知道它刚看到的那块空闲显存马上就要被人占走。今天的答案是一条写下来的规矩:别去动不是你启的东西。**那是约定,不是保证。**
+Agent 能读 `nvidia-smi`,但预留显存、排队等其他任务结束、提前知道刚看到的显存马上就有别的任务要用,这些都没有标准做法。今天的答案是一条写下来的规矩:不是你启动的进程,就别去杀。这是约定,不是保证。
-### 3.3 可复现性还没有着落
+### 可复现性还没有着落
-一次微调是耗时、烧钱、还带随机性的动作。Agent 让"发起"这件事变得极其便宜,也就更容易攒出一个谁都复现不出来的模型。快照和 Trace 能帮上忙,但算不上完整答案。
+一次微调耗时长、成本高,还带随机性。Agent 让发起这类运行变得很便宜,也就更容易攒出一个谁都复现不了的模型。快照和 Trace 能帮上忙,但算不上完整的答案。
-## 四、小结
+## 结语
-**AI 基础设施并不需要为 Agent 重新发明一遍,它本来就是文本和命令。** 缺的是围着它的那点操作经验:动手前先看现场,先确认真正的约束,用观测来确认结果,以及把活干完而不是起个头。
+AI 基础设施不需要为 Agent 重新发明一遍,因为它本来就是文本和命令。缺的是围绕它的操作经验:动手之前先看现场,先确认真正的约束,用观测来验证,把活干完而不是只起个头。
-这就是我们的 Skills 写下来的东西。底下垫着的,是一个 shell、一套面向长任务的两阶段进程模型,以及以可读文本返回的错误。
+PenguinHarness 把这些经验写进了 Skill,底下垫着的是 shell、面向长任务的两阶段进程模型,以及以可读文本返回的错误。下面的命令先安装 PenguinHarness,再让 Agent 启动一个本地模型服务并完成注册:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
@@ -90,7 +96,7 @@ penguin run -m "用 Ollama 启动 Qwen3.5-0.8B 并注册到 Penguin"
---
-- **文档**:[Skills](https://penguin.ooo/docs/skills) · [工具与审批](https://penguin.ooo/docs/tools) · [模型与供应商](https://penguin.ooo/docs/models)
+- **文档**:[技能与插件](https://penguin.ooo/docs/skills) · [工具与审批](https://penguin.ooo/docs/tools) · [模型与供应商](https://penguin.ooo/docs/models)
- **社区**:[GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**参考来源**:[vLLM](https://docs.vllm.ai/) · [Ollama](https://ollama.com/) · [LlamaFactory](https://github.com/hiyouga/LlamaFactory) · [Stripe, Can AI agents build real Stripe integrations?](https://stripe.com/blog/can-ai-agents-build-real-stripe-integrations) · [Anthropic, Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
diff --git a/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.en.md b/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.en.md
index a9228112..28d5eb64 100644
--- a/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.en.md
+++ b/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.en.md
@@ -2,38 +2,38 @@
title: "The Easiest Way to Build AI Agents in 2026"
date: 2026-07-22
category: perspectives
-excerpt: Writing an agent takes ten lines now. The cost has moved somewhere else — into the stack you must assemble around it, where building, observability and evaluation are three separate products from two or three vendors. This is a comparison of what that actually costs to learn, and the case for automating it away instead.
+excerpt: Writing an agent now takes about ten lines of code. The cost has moved into the stack around it, where building, observability and evaluation are separate products to learn; this essay compares that cost and argues for automating it away.
---
-Ask "what is the easiest way to build an AI agent" and you will get answers about lines of code. Those answers are now mostly obsolete: the leading toolkits all reach a working agent in four to fifteen lines.
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
-The cost did not disappear. It moved. It now sits in everything *around* the agent — the orchestration layer, the observability platform, the evaluation harness — each a separate product, with separate concepts, separate documentation, and often a separate vendor. Writing the agent is an afternoon. Learning the stack is a quarter.
+The usual way to measure how hard it is to build an AI agent is to count the lines in a quickstart. By that measure the problem is solved: the leading toolkits reach a working agent in as few as four to fifteen lines.
-This post is about that cost, and about removing it rather than paying it.
+This essay asks what building an agent actually costs in 2026. Our answer is that the cost did not disappear; it moved into the stack around the agent. The better response is to remove that assembly cost rather than pay it. We show what the cost looks like on the most popular stack, how PenguinHarness removes it, and when you should choose something else.
-## 1. What "building an agent with LangChain" actually costs
+The stack around the agent has distinct layers: orchestration, which manages the agent's control flow; observability, which records what the agent did; and evaluation, which scores the results. Each is a separate product, with its own concepts, its own documentation, and often its own vendor. Writing the agent takes an afternoon. Learning the stack takes a quarter.
-LangChain is the reasonable default and the most-used option in the space, so it makes the fairest example. To take an agent from prototype to something you would run in production, here is what you assemble:
+## What a production agent stack costs
+
+On the most popular stack, a production agent means five separate products to learn and run. LangChain is the reasonable default and the most-used option in the space, so it makes the fairest example. To take an agent from prototype to something you would run in production, you assemble the following:
| Layer | What you use | Who makes it | What you have to learn |
| --- | --- | --- | --- |
-| Build | **LangChain** | LangChain Inc. | Tools, models, `create_agent` |
-| Orchestrate | **LangGraph** | LangChain Inc. | Nodes, edges, state, checkpoints, interrupts |
-| Observe | **LangSmith** or **Langfuse** | LangChain Inc. / Langfuse | SDK wiring and a hosted platform — or OpenTelemetry plus self-hosting |
+| Build | LangChain | LangChain Inc. | Tools, models, `create_agent` |
+| Orchestrate | LangGraph | LangChain Inc. | Nodes, edges, state, checkpoints, interrupts |
+| Observe | LangSmith or Langfuse | LangChain Inc. / Langfuse | SDK wiring and a hosted platform, or OpenTelemetry plus self-hosting |
| Evaluate | LangSmith evals or Langfuse evals | same | Datasets, judges, experiment configuration |
-| Deploy | **LangGraph Platform** | LangChain Inc. | Yet another deployment model |
+| Deploy | LangGraph Platform | LangChain Inc. | Yet another deployment model |
Every one of these is a good product. That is not the problem. The problem is that they are five products.
-The observability row is where it bites hardest, because it is a fork in the road rather than a step. LangSmith is LangChain's own commercial platform with native integration — easiest if you are already on the stack, and a managed SaaS you are now dependent on. [Langfuse](https://github.com/langfuse/langfuse) is the open-source alternative: MIT-licensed apart from its enterprise folders, framework-agnostic, self-hostable via Docker or Kubernetes, and maintained by a team that joined ClickHouse in January 2026. It is genuinely excellent. It is also a second vendor, a second data model, and a service you now operate.
-
-So before your agent does anything useful in production, someone on your team has learned two libraries, wired a tracing SDK, stood up or subscribed to an observability platform, and built an evaluation dataset by hand. Then, when the agent underperforms, that same person reads the traces and tunes the prompts — because there is nothing in this stack that does that part for you.
+The observability row costs the most, because it is a fork in the road rather than a step. LangSmith is LangChain's own commercial platform with native integration. It is the easiest choice if you already use the stack, and it leaves you dependent on a managed SaaS. [Langfuse](https://github.com/langfuse/langfuse) is the open-source alternative: MIT-licensed apart from its enterprise folders, framework-agnostic, self-hostable with Docker or Kubernetes, and maintained by a team that joined ClickHouse in January 2026. In our judgment it is genuinely excellent. It is also a second vendor, a second data model, and a service you now operate.
-**That is the real answer to "how hard is it to build an agent in 2026." Not the ten lines. The quarter.**
+So before your agent does anything useful in production, someone on your team has learned two libraries, wired up a tracing SDK, stood up or subscribed to an observability platform, and built an evaluation dataset by hand. When the agent underperforms, the same person reads the traces and tunes the prompts, because nothing in this stack does that part for you.
-## 2. The field, as of July 2026
+## The field as of July 2026
-Five representative options, spanning the design space. All figures checked 2026-07-22.
+The table compares five representative options that span the design space, with PenguinHarness in the last row. All figures were checked on 2026-07-22.
| Tool | License | ★ | Min. code | UI / CLI / server | Observability | Evaluation |
| --- | --- | ---: | --- | --- | --- | --- |
@@ -41,90 +41,92 @@ Five representative options, spanning the design space. All figures checked 2026
| CrewAI | MIT | 56k | ~55 lines, 5 files | — / scaffold / — | `verbose` logging | — |
| OpenAI Agents SDK | MIT | 28k | ~27 lines | — / — / — | OpenAI Dashboard | — |
| Google ADK | Apache-2.0 | 21k | ~8 lines | `adk web` / `adk run` / `adk api_server` | — | Built in, and deep |
-| Dify | Modified Apache-2.0 | 150k | **0** | Yes / Yes / REST | — | — |
-| **PenguinHarness** | Apache-2.0 | — | **0** | **Yes / Yes / Yes** | **Built in (Trace)** | **Built in** |
+| Dify | Modified Apache-2.0 | 150k | 0 | Yes / Yes / REST | — | — |
+| PenguinHarness | Apache-2.0 | — | 0 | Yes / Yes / Yes | Built in (Trace) | Built in |
-Line counts come from each project's official quickstart and are not perfectly comparable. Blank cells mean *not documented in the sources we checked*, not *impossible*.
+Line counts come from each project's official quickstart and are not perfectly comparable. A dash (—) means *not documented in the sources we checked*, not *impossible*.
-One licensing note, since "open source" is doing heavy lifting in this market: Dify ships under a **modified** Apache 2.0 that forbids multi-tenant SaaS resale and forbids removing its branding. n8n, the most-starred project in the space at 197k, uses the Sustainable Use License and is not open source at all. PenguinHarness is plain Apache-2.0.
+Licensing needs a note, because "open source" is doing heavy lifting in this market. Dify ships under a *modified* Apache 2.0 license that forbids multi-tenant SaaS resale and forbids removing its branding from the frontend. n8n, the most-starred project in the space at 197k stars, uses the Sustainable Use License and is not open source at all. PenguinHarness is plain Apache-2.0.
-## 3. The field already agrees that thin won
+## The field is moving toward thin harnesses
The strongest arguments against heavy agent frameworks now come from the vendors themselves.
-Anthropic's engineering guidance, still their canonical reference:
+Anthropic's engineering guidance, still its canonical reference, says:
> "the most successful implementations weren't using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns."
+The same guide warns that frameworks often add layers of abstraction that obscure the underlying prompts and responses, which makes agents harder to debug.
+
Microsoft's own Agent Framework documentation opens with a line most vendors would not print:
> "If you can write a function to handle the task, do that instead of using an AI agent."
-And AutoGen — still the highest-starred multi-agent framework at 60k — now begins its README with:
+AutoGen, still the most-starred multi-agent framework at 60k stars, now begins its README with:
> "AutoGen is now in maintenance mode. It will not receive new features or enhancements and is community managed going forward."
-LangChain itself moved its legacy chains, retrievers and hub module into a separate `langchain-classic` package to keep the core "lean and focused." Meanwhile "harness" became the industry's word: within roughly two months, AWS renamed its agent repo to `harness-sdk`, Microsoft shipped a Harness tier in Agent Framework, and Anthropic published *"A harness for every task."*
+LangChain itself moved its legacy chains, retrievers, and hub module into a separate `langchain-classic` package, to keep the core "lean and focused." Meanwhile, "harness" became the industry's word. Within roughly two months, AWS renamed its agent repo to `harness-sdk`, Microsoft shipped a Harness tier in Agent Framework, and Anthropic published *"A harness for every task."*
-The category is not dying. It is admitting the abstractions were never the valuable part — which makes the assembly cost in section 1 even harder to justify.
+The category is not dying. It is admitting that the abstractions were never the valuable part, which makes the assembly cost described above even harder to justify.
-## 4. PenguinHarness: one install, and nothing to learn
+## What PenguinHarness removes and automates
-Our answer is not a thinner framework. It is removing the assembly step and then automating the tuning loop.
+PenguinHarness does not answer with a thinner framework. It removes the assembly step, and then it automates the tuning loop.
-### 4.1 The layers are already one product
+### One install covers the five layers
-One install gives you all five rows of that first table, sharing one data directory and one message protocol:
+One install gives you all five rows of the first table, sharing one data directory and one message protocol:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # http://127.0.0.1:7364 — first login: admin, initial password printed on first start
+penguin web # http://127.0.0.1:7364 — first login: admin / penguin-2026, shown on the login page
```
-Multi-session chat, agent and skill management, model configuration, usage and cost statistics, **Trace observability**, and an **evaluation center** — in the box, wired together, nothing to subscribe to and nothing to self-host separately. Every request, tool call and approval decision is already recorded; a session restores completely from its trace. There is no tracing SDK to install because there is no seam to instrument across.
+The install includes chat with multiple Sessions, agent and Skill management, model configuration, usage and cost statistics, Trace observability, and an **Evaluation Center**, all wired together. There is nothing to subscribe to and nothing to self-host separately. Every request, tool call, and approval decision is already recorded, and a Session restores completely from its Trace. There is no tracing SDK to install, because there is no seam between products to instrument.
-### 4.2 Zero lines, not fewer lines
+### Zero lines, not fewer lines
+
+Running an agent needs no project, no imports, and no framework:
```bash
penguin run -m "Analyze data.csv and summarize quarterly sales"
```
-No project, no imports, no framework. The same engine drives the REPL (`penguin chat`), a headless server (`penguin server`) and the Web App.
-
-### 4.3 An agent builds your agent
+The same engine drives the REPL (`penguin chat`), a headless server (`penguin server`), and the Web App.
-You describe what you want; an agent writes its `AGENTS.md`, installs the skills it needs, and hands you something that runs. One sentence produced a complete RAG application — ingestion, retrieval, cited sources, web UI — for **$0.02** of tokens on DeepSeek V4 Pro. The [runnable example](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent) is an 82-line script that builds a new agent from a plain-language requirement and then runs it.
+### An agent builds the agent
-This works because **agents are editable data, not hardcoded constants** — prompts, skills and configuration are plain files on disk.
+You describe what you want. An agent writes the new agent's `AGENTS.md`, installs the Skills it needs, and hands you something that runs. One sentence produced a complete RAG application, with ingestion, retrieval, cited sources, and a web UI, for $0.02 of Tokens on DeepSeek V4 Pro. The [runnable example](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent) is an 82-line script that builds a new agent from a plain-language requirement and then runs it.
-### 4.4 The tuning loop is automated too
+This works because **agents are editable data, not hardcoded constants**: prompts, Skills, and configuration are plain files on disk.
-This is the part that answers section 1's last paragraph. Built-in skills for benchmark design, evaluation and optimization let the agent score its own output, locate where it lost points, and ship version N+1 — with a snapshot before every round and every request replayable in the trace view.
+### The tuning loop is automated too
-On other stacks, *you* are the optimizer: you read the traces, you tune the prompts, you rerun the evals. Here that loop is the agent's job. **You do not have to learn to be good at it.**
+This answers the last step of the LangChain example, where a person reads the traces and tunes the prompts. Built-in Skills for Benchmark design, evaluation, and optimization let the agent score its own output, find where it lost points, and ship version N+1. No round starts until a snapshot of the current version exists, and every request can be replayed in the Trace view.
-### 4.5 The controls are still there
+On other stacks, *you* are the optimizer: you read the traces, tune the prompts, and rerun the evals. Here that loop is the agent's job, so you do not have to learn to be good at it.
-Every tool call gets exactly one approval decision in one of four modes — allow-all, deny-all, read-only, always-ask — and each decision is audited to the trace. It runs fully locally on as little as a single CPU, and reaches 1000+ models through any OpenAI-protocol endpoint.
+### The controls are still there
-## 5. When not to use PenguinHarness
+Removing the assembly step does not remove oversight. Every tool call gets exactly one approval decision, in one of four modes: `allow-all`, `deny-all`, `read-only`, or `always-ask`. Each decision is audited in the Trace. PenguinHarness runs fully locally on as little as a single CPU, and reaches 1000+ models through any OpenAI-protocol endpoint.
-A comparison where one option wins every row is an advertisement, not an analysis. Two cases where you should pick something else:
+## When not to use PenguinHarness
-- **Python shops.** Our SDK is TypeScript. The CLI and server are language-agnostic, but if your team works in Python and wants to subclass and extend these classes, most of the options above will fit better.
-- **Deep cloud integration.** If you are already all-in on Azure, Microsoft Agent Framework is the path of least resistance; on Vertex, ADK is.
+A comparison in which one option wins every row is an advertisement, not an analysis. In two cases, you should pick something else:
-## 6. The short version
+- **Python shops.** The PenguinHarness SDK is TypeScript. The CLI and server are language-agnostic, but if your team works in Python and wants to extend agents by subclassing framework classes, most of the options above will fit better.
+- **Deep cloud integration.** If you are already all-in on Azure, Microsoft Agent Framework is the path of least resistance. On Vertex, ADK is.
-Building an agent stopped being the hard part. Assembling and learning the stack around it did not — and on the most popular option that means two libraries, an observability platform from a first or third party, an evaluation harness, and a human who becomes the optimization loop.
+## Conclusion
-PenguinHarness collapses those into one install, then hands the optimization loop to the agent.
+Building an agent is no longer the hard part; assembling and learning the stack around it still is. On the most popular option, that stack means two libraries, an observability platform from a first or third party, an evaluation harness, and a person who becomes the optimization loop. When you compare toolkits, count that whole stack, not the quickstart's line count.
-Not the smallest framework — **no framework, an agent to write the agent, and nothing left for you to learn.**
+PenguinHarness collapses those layers into one install and hands the optimization loop to the agent. It is not a smaller framework: there is no framework to learn, and an agent writes the agent. For Python-first teams and deep cloud integrations, the alternatives above remain the better choice.
---
-- **Docs**: [Quickstart](https://penguin.ooo/docs/quickstart) · [Skills](https://penguin.ooo/docs/skills) · [Sessions & Traces](https://penguin.ooo/docs/sessions-and-traces)
+- **Docs**: [Quickstart](https://penguin.ooo/docs/quickstart) · [Skills & Plugins](https://penguin.ooo/docs/skills) · [Sessions & Traces](https://penguin.ooo/docs/sessions-and-traces)
- **Community**: [GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**Sources** — figures checked 2026-07-22: [LangChain v1 release notes](https://docs.langchain.com/oss/python/releases/langchain-v1) · [Langfuse](https://github.com/langfuse/langfuse) · [AutoGen README](https://github.com/microsoft/autogen) · [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/) · [Google ADK](https://adk.dev/) · [CrewAI](https://docs.crewai.com/en/quickstart) · [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/quickstart/) · [Dify LICENSE](https://github.com/langgenius/dify/blob/main/LICENSE) · [n8n LICENSE](https://github.com/n8n-io/n8n/blob/master/LICENSE.md) · [Anthropic, Building Effective AI Agents](https://www.anthropic.com/engineering/building-effective-agents)
diff --git a/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.zh.md b/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.zh.md
index fa058f08..93fb4bff 100644
--- a/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.zh.md
+++ b/packages/landing/content/blog/easiest-way-to-build-ai-agents-2026.zh.md
@@ -2,123 +2,131 @@
title: "2026 年构建 AI Agent 最简单的方式"
date: 2026-07-22
category: perspectives
-excerpt: 今天写一个 Agent 只要十几行。成本没有消失,只是换了地方——挪到了它外面那一圈:构建、观测、评估分属两三家厂商的独立产品。本文算一算这笔学习成本,再说说另一条路:把它自动化掉,而不是老老实实付掉。
+excerpt: 如今写一个 Agent 只要十行左右代码。成本挪到了它周边的技术栈,构建、观测、评估分属几个要各自学习的产品;本文比较这笔成本,并主张把它自动化掉。
---
-问"构建 AI Agent 最简单的方式是什么",多数答案都在比代码行数。这个比法今天已经没什么意义了:主流工具包写十几行就能跑起一个可用的 Agent。
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-**成本没有消失,只是换了地方。** 它挪到了 Agent 外面那一圈:编排层、观测平台、评估体系。每一样都是独立的产品,各有各的概念、各有各的文档,甚至各有各的厂商。**写一个 Agent 是一下午的事,把这套栈学明白是一个季度的事。**
+衡量构建一个 AI Agent 有多难,通常的办法是数 quickstart 里的代码行数。按这个标准,问题已经解决了:主流工具包最少只要四到十五行代码,就能跑起一个可用的 Agent。
-这篇文章就来算这笔账,再说说怎么把它去掉,而不是老老实实付掉。
+本文要回答的问题是,2026 年构建一个 Agent 的真实成本在哪里。我们的回答是,成本没有消失,只是挪到了 Agent 周边的技术栈里。更好的做法是把这笔组装成本去掉,而不是老老实实付掉。下文会讲清楚这笔成本在最流行的技术栈上是什么样子,PenguinHarness 怎样去掉它,以及什么情况下你该选别的方案。
-## 一、用 LangChain 做一个 Agent,代价到底是什么
+Agent 周边的技术栈分成几个清晰的层次:编排,管理 Agent 的控制流;可观测,记录 Agent 做过什么;评估,给结果打分。每一层都是独立的产品,有自己的概念、自己的文档,往往还有自己的厂商。写 Agent 只要一个下午,学这套技术栈却要一个季度。
-LangChain 是这个领域用得最多的方案,也是多数团队的默认选项,拿它举例最公道。要把一个 Agent 从原型推到能上生产,你得拼出这么一套:
+## 生产级 Agent 技术栈要付出什么
-| 层次 | 你要用的东西 | 出品方 | 你必须学会的东西 |
+在最流行的技术栈上,一个生产级 Agent 意味着要学习、运行五个独立的产品。LangChain 是这个领域合理的默认选项,用的人也最多,拿它举例最公道。要把 Agent 从原型推到能上生产,你得拼出下面这一套:
+
+| 层次 | 用什么 | 出品方 | 要学什么 |
| --- | --- | --- | --- |
-| 构建 | **LangChain** | LangChain Inc. | 工具、模型、`create_agent` |
-| 编排 | **LangGraph** | LangChain Inc. | 节点、边、状态、检查点、interrupt |
-| 观测 | **LangSmith** 或 **Langfuse** | LangChain Inc. / Langfuse | 接追踪 SDK 加托管平台,或者上 OpenTelemetry 加自建部署 |
+| 构建 | LangChain | LangChain Inc. | 工具、模型、`create_agent` |
+| 编排 | LangGraph | LangChain Inc. | 节点、边、状态、检查点、中断 |
+| 观测 | LangSmith 或 Langfuse | LangChain Inc. / Langfuse | 接入追踪 SDK 加托管平台,或者 OpenTelemetry 加自建部署 |
| 评估 | LangSmith 评估或 Langfuse 评估 | 同上 | 数据集、评判器、实验配置 |
-| 部署 | **LangGraph Platform** | LangChain Inc. | 又一套部署模型 |
-
-这五样单拿出来都是好东西,问题不在这儿。**问题在于它们是五样东西。**
+| 部署 | LangGraph Platform | LangChain Inc. | 又一套部署模式 |
-最难受的是"观测"这一行。它不是一个步骤,而是一道岔路。LangSmith 是 LangChain 自家的商业平台,原生集成,接入最省事,代价是你从此绑在一个托管 SaaS 上。[Langfuse](https://github.com/langfuse/langfuse) 是开源的那条路:除企业版目录外采用 MIT 协议,不绑定框架,可以用 Docker 或 Kubernetes 自建,团队已在 2026 年 1 月加入 ClickHouse。它确实做得很好,但它同时也意味着**多一家厂商、多一套数据模型,以及一个从此要你自己运维的服务**。
+这五样单拿出来都是好产品,问题不在这儿。问题在于它们是五个产品。
-于是,在这个 Agent 于生产环境里做成第一件有用的事之前,团队里已经有人学完了两个库、接好了追踪 SDK、订阅或自建了一个观测平台,还手工攒出了一套评估数据集。等到 Agent 表现不好,还是这个人去读 trace、改提示词。**因为这套栈里没有任何一环会替你做这件事。**
+观测这一行的代价最高,因为它不是一个步骤,而是一道岔路。LangSmith 是 LangChain 自家的商业平台,原生集成。如果你已经在用这套技术栈,它是最省事的选择,代价是从此依赖一个托管 SaaS。[Langfuse](https://github.com/langfuse/langfuse) 是开源的那条路:除企业版目录外采用 MIT 许可证,不绑定框架,可以用 Docker 或 Kubernetes 自建部署,团队已在 2026 年 1 月加入 ClickHouse。在我们看来,它确实做得很好。但它也意味着多一家厂商、多一套数据模型,以及一个从此要你自己运维的服务。
-**这才是"2026 年构建 Agent 有多难"的真实答案。不是那十几行,是那一个季度。**
+所以,Agent 还没在生产环境里做成任何有用的事,团队里就已经有人学完了两个库,接好了追踪 SDK,自建或订阅了一个观测平台,还手工攒了一套评估数据集。等 Agent 表现不好,去读 trace、调提示词的还是这个人,因为这套技术栈里没有任何一环会替你做这件事。
-## 二、2026 年 7 月的战场实况
+## 2026 年 7 月的格局
-五个覆盖设计空间的代表。数据均于 2026-07-22 核对。
+下表对比了五个覆盖整个设计空间的代表性方案,PenguinHarness 列在最后一行。所有数据均于 2026-07-22 核对。
-| 工具 | 协议 | ★ | 最少代码 | UI / CLI / 服务 | 观测 | 评估 |
+| 工具 | 许可证 | ★ | 最少代码 | UI / CLI / 服务 | 观测 | 评估 |
| --- | --- | ---: | --- | --- | --- | --- |
-| LangChain + LangGraph | MIT | 142k / 38k | 约 15 行 | — / — / Platform | LangSmith 或 Langfuse | LangSmith 或 Langfuse |
-| CrewAI | MIT | 56k | 5 个文件约 55 行 | — / 脚手架 / — | `verbose` 日志 | — |
-| OpenAI Agents SDK | MIT | 28k | 约 27 行 | — / — / — | 官方 Dashboard | — |
+| LangChain + LangGraph | MIT | 142k / 38k | 约 15 行 | — / — / Platform | LangSmith(SaaS)或 Langfuse | LangSmith 或 Langfuse |
+| CrewAI | MIT | 56k | 约 55 行,5 个文件 | — / 脚手架 / — | `verbose` 日志 | — |
+| OpenAI Agents SDK | MIT | 28k | 约 27 行 | — / — / — | OpenAI Dashboard | — |
| Google ADK | Apache-2.0 | 21k | 约 8 行 | `adk web` / `adk run` / `adk api_server` | — | 内置,且做得很深 |
-| Dify | 修改版 Apache-2.0 | 150k | **0** | 有 / 有 / REST | — | — |
-| **PenguinHarness** | Apache-2.0 | — | **0** | **有 / 有 / 有** | **内置(Trace)** | **内置** |
+| Dify | 修改版 Apache-2.0 | 150k | 0 | 有 / 有 / REST | — | — |
+| PenguinHarness | Apache-2.0 | — | 0 | 有 / 有 / 有 | 内置(Trace) | 内置 |
+
+代码行数取自各项目官方的 quickstart,彼此并不完全可比。破折号(—)表示「我们查到的资料里没有写」,不是「做不到」。
+
+关于许可证还得补一句,因为「开源」这个词在这个市场里用得太宽。Dify 用的是**修改版** Apache 2.0 许可证,禁止多租户 SaaS 转售,也禁止把前端的品牌标识去掉。n8n 是这个领域星标最多的项目,有 197k,但它用的是 Sustainable Use License,根本算不上开源。PenguinHarness 是标准的 Apache-2.0。
-代码行数取自各项目官方 quickstart,彼此并不完全可比。空白格的意思是**我们查到的资料里没有写**,不是"做不到"。
+## 行业正在转向轻量 Harness
-关于协议还得补一句,因为"开源"这个词在这个市场里被用得太宽。Dify 用的是**修改版** Apache 2.0,禁止多租户 SaaS 转售,也禁止把前端的品牌标识去掉;n8n 是这个领域星标最高的项目,197k,但它用的是 Sustainable Use License,**根本算不上开源**。PenguinHarness 是标准 Apache-2.0。
+反对重型 Agent 框架最有力的说法,如今恰恰来自厂商自己。
-## 三、这个领域自己已经承认:薄的那一方赢了
+Anthropic 的工程指南至今仍是他们的权威参考,里面写道:
-今天反对重型 Agent 框架最有力的说法,恰恰来自厂商自己。
+> 「最成功的落地案例都没有用复杂框架或专用库,而是用简单、可组合的模式搭起来的。」
-Anthropic 的工程指南至今仍是他们的权威参考,其中写道:**最成功的落地案例都没有用复杂框架或专用库,而是用简单、可组合的模式搭起来的**;这类框架往往多加一层抽象,把底层的提示词和响应挡在后面,反而更难调试。
+同一份指南还提醒,框架往往多加一层抽象,把底层的提示词和响应挡在后面,让 Agent 更难调试。
-微软自家 Agent Framework 文档的开篇,摆着一句多数厂商不会印出来的话:**一个函数能搞定的事,就写函数,别上 AI Agent。**
+微软自家 Agent Framework 文档的开篇,摆着一句多数厂商不会印出来的话:
-而 AutoGen,多智能体框架里星标依然最高的那个(60k),现在 README 第一段就写着:**本项目已进入维护模式,不再接受新特性或增强,后续由社区管理。**
+> 「如果能写一个函数来完成这个任务,那就写函数,不要用 AI Agent。」
-LangChain 自己也把遗留的 chain、retriever 和 hub 模块挪进了独立的 `langchain-classic` 包,好让核心"精简、专注"。与此同时,"harness"成了行业通用词:两个月左右的时间里,AWS 把 Agent 仓库改名叫 `harness-sdk`,微软在 Agent Framework 里加了一层 Harness,Anthropic 发了一篇《A harness for every task》。
+AutoGen 以 60k 星标仍是星标最多的多 Agent 框架,它的 README 现在第一段就写着:
-这个品类没有死,它只是承认了一件事:**真正有价值的从来不是那些抽象**。而这也让第一节那笔拼装成本更难自圆其说。
+> 「AutoGen 已进入维护模式,不再添加新功能或增强,今后由社区管理。」
-## 四、PenguinHarness:装一次,然后不用再学
+LangChain 自己也把遗留的 chain、retriever 和 hub 模块挪进了独立的 `langchain-classic` 包,好让核心「精简、专注」。与此同时,「Harness」成了行业通用词。大约两个月里,AWS 把 Agent 仓库改名为 `harness-sdk`,微软在 Agent Framework 里推出了 Harness 一档,Anthropic 发表了《A harness for every task》。
-我们的答案不是"做一个更薄的框架",而是**把拼装这一步取消掉,再把调优那个循环也自动化掉**。
+这个品类没有死,它只是承认了一件事:真正有价值的从来不是那些抽象。这样一来,上文那笔组装成本就更说不过去了。
-### 4.1 那几层,本来就该是同一个产品
+## PenguinHarness 去掉了什么,又自动化了什么
-装一次,第一张表里的五行就都有了,而且共用同一份数据目录、同一套消息协议:
+PenguinHarness 给出的答案不是一个更薄的框架。它先去掉组装这一步,再把调优循环自动化。
+
+### 一次安装覆盖全部五层
+
+装一次,就有了第一张表里的全部五行,它们共用同一个数据目录、同一套消息协议:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # http://127.0.0.1:7364 — 首次登录:admin,初始密码见首次启动输出
+penguin web # http://127.0.0.1:7364 — 首次登录:admin / penguin-2026,登录页上也有提示
```
-多会话对话、Agent 与技能管理、模型配置、用量与成本统计、**Trace 可观测**、**评测中心**,开箱即有,彼此已经打通,**不用订阅什么,也不用另外自建什么**。每个请求、每次工具调用、每个审批决策都已经记下来了,会话可以从 Trace 完整恢复。**这里没有追踪 SDK 要接,因为根本不存在需要跨越的接缝。**
+安装后就有多会话对话、Agent 与 Skill 管理、模型配置、用量与成本统计、Trace 可观测,以及**评估中心**,彼此已经打通。不用订阅什么,也不用另外自建什么。每个请求、每次工具调用、每个审批决策都已经记录下来,会话可以从 Trace 完整恢复。这里没有追踪 SDK 要接,因为产品之间根本不存在需要埋点的接缝。
-### 4.2 是零行,不是"更少的行"
+### 是零行,不是「更少的行」
+
+运行一个 Agent,不用建工程,不用写 import,也不用框架:
```bash
penguin run -m "分析 data.csv 并总结季度销售情况"
```
-不用建工程,不用写 import,也没有框架要学。同一套引擎还驱动着 REPL(`penguin chat`)、无头服务(`penguin server`)和 Web App。
+同一套引擎还驱动着 REPL(`penguin chat`)、无头服务(`penguin server`)和 Web App。
-### 4.3 让 Agent 来写你的 Agent
+### 让 Agent 来写 Agent
-你把想要的东西描述出来,剩下的交给一个 Agent:它来写目标 Agent 的 `AGENTS.md`,装好需要的技能,最后把一个能跑的成品交给你。我们用一句话生成过一个完整的 RAG 应用——文档摄取、检索、带出处的引用、Web 界面一应俱全,在 DeepSeek V4 Pro 上的 token 成本是 **$0.02**。[可运行示例](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent)是一个 82 行的脚本:从一句自然语言需求造出新 Agent,然后跑起来验证它。
+你把想要的东西描述出来,剩下的交给一个 Agent:它写好新 Agent 的 `AGENTS.md`,装上需要的 Skill,把一个能跑的成品交给你。我们用一句话生成过一个完整的 RAG 应用,文档摄取、检索、带出处的引用、Web 界面一应俱全,在 DeepSeek V4 Pro 上只花了 $0.02 的 Token。[可运行示例](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent)是一个 82 行的脚本:根据一句自然语言需求构建新 Agent,然后运行它。
-这件事能成立,靠的是一条设计原则:**Agent 是可编辑的数据,不是硬编码的常量**。提示词、技能、配置,全都是磁盘上的普通文件。
+这件事能成立,是因为 **Agent 是可编辑的数据,不是写死的常量**:提示词、Skill 和配置都是磁盘上的普通文件。
-### 4.4 连调优的循环也自动化了
+### 调优循环也自动化了
-这一节正面回应第一节结尾那个问题。内置的基准设计、评测与优化技能,让 Agent 自己给输出打分、找出失分在哪,然后发布第 N+1 版。每一轮开始前留快照,每个请求都能在 Trace 视图里回放。
+这正好回应了 LangChain 那个例子的最后一步:由人去读 trace、调提示词。内置的 Benchmark 设计、评估与优化 Skill,让 Agent 自己给输出打分,找出丢分的地方,然后发布第 N+1 版。当前版本的快照不存在,下一轮就不会开始;每个请求都能在 Trace 视图里回放。
-在别的技术栈上,**那个优化器就是你本人**:你读 trace,你改提示词,你重跑评估。**在这里,这个循环归 Agent 管,你不必再把自己练成这方面的老手。**
+在别的技术栈上,优化器就是**你**自己:你读 trace,你调提示词,你重跑评估。在这里,这个循环归 Agent 管,你不必把自己练成这方面的行家。
-### 4.5 管控并没有因此消失
+### 管控依然都在
-每次工具调用恰好触发一次审批决策,四种模式可选:全部允许、全部拒绝、只读放行、每次询问,每个决策都写进 Trace 留档。整套东西完全本地运行,单核 CPU 也带得动;通过任意 OpenAI 协议端点接得上 1000+ 模型。
+去掉组装这一步,不等于去掉监管。每次工具调用恰好触发一次审批决策,审批模式有四种:`allow-all`、`deny-all`、`read-only` 和 `always-ask`,每个决策都写入 Trace 留作审计。PenguinHarness 可以完全在本地运行,单个 CPU 也带得动,并能通过任意 OpenAI 协议端点接入 1000+ 模型。
-## 五、什么时候**不该**用 PenguinHarness
+## 什么时候不该用 PenguinHarness
-一份每一行都自己赢的对比是广告,不是分析。有两种情况,你该选别的:
+一份每一行都是同一个选项获胜的对比是广告,不是分析。有两种情况,你该选别的:
-- **团队写 Python。** 我们的 SDK 是 TypeScript。CLI 和服务端与语言无关,但如果你的团队习惯在 Python 里继承、扩展这些类,上表里的多数选项都会更顺手。
+- **团队写 Python。** PenguinHarness 的 SDK 是 TypeScript。CLI 和服务端与语言无关,但如果你的团队用 Python,还想通过继承框架里的类来扩展 Agent,上面的多数方案会更顺手。
- **深度绑定某一家云。** 已经全面押注 Azure 的话,Microsoft Agent Framework 阻力最小;如果是 Vertex,那就是 ADK。
-## 六、小结
-
-**难的早就不是构建 Agent 本身,而是把它周围那套栈拼起来、学明白。** 在最流行的那个选项上,这意味着两个库、一个自家或第三方的观测平台、一套评估体系,外加一个人肉充当的优化循环。
+## 结论
-PenguinHarness 把这些收进一次安装,然后**把优化循环交给 Agent 自己**。
+难的早就不是构建 Agent 本身,而是把它周边那套技术栈拼起来、学明白。在最流行的方案上,这意味着两个库、一个自家或第三方的观测平台、一套评估体系,外加一个人肉充当的优化循环。比较工具包时,要把这一整套栈都算进去,别只数 quickstart 的代码行数。
-我们做的不是最小的框架。**是没有框架,有一个替你写 Agent 的 Agent,以及一份不再需要你去学的清单。**
+PenguinHarness 把这些层收进一次安装,再把优化循环交给 Agent。它不是一个更小的框架:根本没有框架要学,写 Agent 的也是 Agent。对以 Python 为主的团队和深度绑定云平台的场景,上面提到的替代方案仍然更合适。
---
-- **文档**:[快速开始](https://penguin.ooo/docs/quickstart) · [Skills](https://penguin.ooo/docs/skills) · [会话与 Trace](https://penguin.ooo/docs/sessions-and-traces)
+- **文档**:[快速开始](https://penguin.ooo/docs/quickstart) · [技能与插件](https://penguin.ooo/docs/skills) · [Session 与 Trace](https://penguin.ooo/docs/sessions-and-traces)
- **社区**:[GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**参考来源**(数据均于 2026-07-22 核对):[LangChain v1 发布说明](https://docs.langchain.com/oss/python/releases/langchain-v1) · [Langfuse](https://github.com/langfuse/langfuse) · [AutoGen README](https://github.com/microsoft/autogen) · [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/) · [Google ADK](https://adk.dev/) · [CrewAI](https://docs.crewai.com/en/quickstart) · [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/quickstart/) · [Dify LICENSE](https://github.com/langgenius/dify/blob/main/LICENSE) · [n8n LICENSE](https://github.com/n8n-io/n8n/blob/master/LICENSE.md) · [Anthropic, Building Effective AI Agents](https://www.anthropic.com/engineering/building-effective-agents)
diff --git a/packages/landing/content/blog/fireworks-credits-amd.en.md b/packages/landing/content/blog/fireworks-credits-amd.en.md
index f8732f2b..a4875520 100644
--- a/packages/landing/content/blog/fireworks-credits-amd.en.md
+++ b/packages/landing/content/blog/fireworks-credits-amd.en.md
@@ -1,84 +1,84 @@
---
-title: "Partnering with the AMD Developer Program: $50 in free Fireworks credits, wired into PenguinHarness"
+title: "Partnering with the AMD AI Developer Program: $50 in free Fireworks credits, ready to use in PenguinHarness"
date: 2026-07-20
category: news
-excerpt: We are delighted to partner with the AMD AI Developer Program to bring you free Fireworks coupon codes — apply for the $50 credits with this guide, then set them up in PenguinHarness in three steps.
+excerpt: We have partnered with the AMD AI Developer Program to offer free Fireworks coupon codes. This guide shows how to apply for $50 in credits on AMD's global or China site, then set them up in PenguinHarness in three steps.
---
-We are delighted to partner with the **AMD AI Developer Program** to bring you free Fireworks redemption codes: join the program, pass the review, and you receive a Coupon Code redeemable for **$50 in Fireworks AI Credits**. PenguinHarness ships a built-in Fireworks AI gateway group — OpenAI protocol, preset base URL, five preset models — so the credits are usable the moment they land.
+> Written for PenguinHarness 0.1.0. Later releases may differ in some details.
-> Page content, credit amounts, and expiration dates are subject to change. Please refer to the application page and approval email for the latest information.
+We have partnered with the **AMD AI Developer Program** to bring you free Fireworks redemption codes. Join the program and pass its review, and you receive a coupon code worth **$50 in Fireworks AI Credits**. PenguinHarness has a built-in Fireworks AI gateway group, with the OpenAI protocol, the base URL and five models preset, so you can use the credits as soon as they arrive.
-## Step 1: Join the AMD AI Developer Program
+The program has a global site and a China site. The first two steps differ between them; from the application form onward, the steps are the same.
-Visit the official page: <https://developer.amd.com/ai-developer-program/>. In the **Join the AMD AI Developer Program** section:
+> Page content, credit amounts and expiration dates may change. Check the application page and the approval email for the latest details.
-- No AMD ADP account yet: click **Create Account** and enter your personal information;
-- Already have one: click **Log In** and follow the on-screen instructions.
+## Step 1: Create an account or sign in
-![The AMD AI Developer Program join page](https://github.com/user-attachments/assets/47a3055b-9a95-40a1-80c6-e3bac7a9ac49)
+- **Global site:** open <https://developer.amd.com/ai-developer-program/>. In the **Join the AMD AI Developer Program** section, click **Create Account** and enter your personal information. If you already have an AMD ADP account, click **Log In** and follow the on-screen instructions.
+- **China site:** open <https://developer.amd.com.cn/login?source=2a6CMBw3K>. Click **注册账号** (Register) and enter your personal information to create an ADP account. If you already have one, click **登录** (Log in) and follow the prompts.
-## Step 2: Request Cloud Credits under Member Perks
+![The Join the AMD AI Developer Program section on the global site, with the Create Account and Log In buttons](https://github.com/user-attachments/assets/47a3055b-9a95-40a1-80c6-e3bac7a9ac49)
-After registering and signing in:
+## Step 2: Open the application
-1. Click **Member Perks** in the top navigation bar;
-2. Find **Cloud Credit Options**;
-3. Click **Request Cloud Credits** at the bottom of the page.
+After you sign in:
-![Cloud Credit Options under Member Perks](https://github.com/user-attachments/assets/773f8cf1-d72f-4aa3-83b8-f31fc7c9ed9e)
+- **Global site:**
+ 1. Click **Member Perks** in the top navigation bar.
+ 2. Find **Cloud Credit Options**.
+ 3. Click **Request Cloud Credits** at the bottom of the page.
+- **China site:** open the campaign from **新闻/公告** (News/Announcements) on the home page, or open the campaign page in **活动中心** (Events Center). Then click **去申请** (Apply).
-## Step 3: Complete the application form
+![Cloud Credit Options under Member Perks on the global site](https://github.com/user-attachments/assets/773f8cf1-d72f-4aa3-83b8-f31fc7c9ed9e)
-Fill in the requested personal information:
+## Step 3: Fill in the application form
-- Under **Product Needed**, select **Fireworks AI**;
-- In the **Profile** section, provide at least one public profile for account verification: LinkedIn, GitHub, a portfolio, a company or school profile, WeChat, WeCom, and similar all work.
+Fill in the personal information the form asks for:
-![Application form: select Fireworks AI under Product Needed](https://github.com/user-attachments/assets/12a49136-0956-4f29-9d47-f0e473615075)
+- Under **Product Needed**, select **Fireworks AI**.
+- In the **Profile** section, give at least one public profile for account verification. LinkedIn, GitHub, a portfolio, a company or school profile, WeChat, WeCom and similar profiles all work. Reviewers look at these profiles to decide whether you are eligible.
-Complete the other required fields marked with `*`, double-check your email, identity, product selection, and profile link, then submit.
+![The application form, with Fireworks AI selected under Product Needed](https://github.com/user-attachments/assets/12a49136-0956-4f29-9d47-f0e473615075)
+
+Complete the other required fields, marked with `*`. Check your email address, identity, product choice and profile links, then submit.
## Step 4: Wait for the review
-AMD verifies your account and application, usually within **2–3 business days** — actual time varies with application volume, information completeness, and holidays.
+AMD verifies your account and application. This usually takes 2–3 business days; the actual time depends on the number of applications, how complete your information is, and holidays.
-## Step 5: Receive and redeem the coupon code
+## Step 5: Receive the coupon code
-Once approved, AMD emails a unique **Coupon Code** redeemable for **$50 in Fireworks AI Credits** to your application address. Keep it secure — do not share it publicly, forward it, or commit it to a repository.
+When your application is approved, AMD emails the address you applied with. The email contains a unique coupon code worth $50 in Fireworks AI Credits. Keep it safe: do not post it publicly, forward it, or commit it to a repository.
-![The Coupon Code in the approval email](https://github.com/user-attachments/assets/c53129c7-2c87-4510-a4e3-31f52598dc24)
+![The coupon code in the approval email](https://github.com/user-attachments/assets/c53129c7-2c87-4510-a4e3-31f52598dc24)
-Redeem it and create an API key:
+## Step 6: Redeem the credits and create an API key
-1. Open <https://fireworks.ai/> and sign in;
-2. Click **Redeem Promo** and enter the Coupon Code from the email to redeem the $50 credits;
+1. Open <https://fireworks.ai/> and sign in.
+2. Click **Redeem Promo** and enter the coupon code from the email to redeem the $50 credits.
3. Click **Create API Key** to generate your Fireworks API key.
-![Redeeming and creating an API key in the Fireworks console](https://github.com/user-attachments/assets/051a1e69-db7f-4867-b899-89981df15142)
+![The Fireworks console, with the Redeem Promo and Create API Key buttons](https://github.com/user-attachments/assets/051a1e69-db7f-4867-b899-89981df15142)
## Set it up in PenguinHarness
-With the API key in hand, three steps:
-
-**1. Install and launch**
-
-```bash
-curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # opens http://127.0.0.1:7364 (first login: admin, initial password printed on first start)
-```
-
-**2. Configure a Fireworks model**
+With the API key in hand, setup takes three steps:
-Open the Models page and find the **Fireworks AI** group, then use its bulk key button to paste the API key you just created. The group presets five models — GLM 5.2, Kimi K2.7 Code, DeepSeek V4 Pro, MiniMax M3, and DeepSeek V4 Flash — with base URLs and pricing pre-filled; set any of them as the default. You can also hit the group's speed-test button to measure real TTFT and TPS before choosing.
+1. Install PenguinHarness and start the Web App:
-**3. Start working**
+ ```bash
+ curl -fsSL https://penguin.ooo/install.sh | sh
+ penguin web # opens http://127.0.0.1:7364 (first login: admin / penguin-2026, shown on the login page)
+ ```
-Head back to Chat and hand the Agent its first task — e.g. "Analyze data.csv and summarize quarterly sales".
+2. Open the **Models** page and find the **Fireworks AI** group. Click **Set API key for group** and paste the API key you just created. The group has five preset models, with base URLs and pricing filled in: GLM 5.2, Kimi K2.7 Code, DeepSeek V4 Pro, MiniMax M3 and DeepSeek V4 Flash. Set any of them as the default. To compare real TTFT and TPS before you choose, click the group's **Speed test** button.
+3. Go back to **Chat** and give the agent its first task, for example "Analyze data.csv and summarize quarterly sales".
## References
- [AMD AI Developer Program](https://developer.amd.com/ai-developer-program/)
-- [Official AMD Cloud Credits application video tutorial](https://www.youtube.com/watch?v=masSW53JkTY)
-- Application steps and screenshots are adapted from WhatGhost's guides ([中文](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_%E7%94%B3%E8%AF%B7%E6%8C%87%E5%8D%97.md) / [English](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_Application_Guide_EN.md)) — thanks to the original author
+- [AMD AI Developer Program China site](https://developer.amd.com.cn/login?source=2a6CMBw3K)
+- [Official AMD video tutorial on applying for Cloud Credits](https://www.youtube.com/watch?v=masSW53JkTY)
+- The global-site steps and screenshots are adapted from WhatGhost's guides ([中文](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_%E7%94%B3%E8%AF%B7%E6%8C%87%E5%8D%97.md) / [English](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_Application_Guide_EN.md)), and the China-site steps and screenshots from the [official AMD AI Developer Program application guide](https://acn658bi9o7j.feishu.cn/docx/T8VIdjkZXoqyDwxwNjacbcsYngd) (in Chinese). Thanks to the original authors.
- [PenguinHarness model configuration docs](https://penguin.ooo/docs/models)
diff --git a/packages/landing/content/blog/fireworks-credits-amd.zh.md b/packages/landing/content/blog/fireworks-credits-amd.zh.md
index 4f8b46e1..0b8bbce4 100644
--- a/packages/landing/content/blog/fireworks-credits-amd.zh.md
+++ b/packages/landing/content/blog/fireworks-credits-amd.zh.md
@@ -1,99 +1,80 @@
---
-title: 携手 AMD 开发者计划:免费领取 $50 Fireworks 额度,直连 PenguinHarness
+title: 携手 AMD 开发者计划:免费领取 $50 Fireworks 额度,PenguinHarness 直接可用
date: 2026-07-20
category: news
-excerpt: 我们很高兴与 AMD AI Developer Program 合作,为大家带来 Fireworks 的免费兑换码——按本文申请 $50 Credits,再在 PenguinHarness 里三步用起来。
+excerpt: 我们与 AMD AI Developer Program 合作,为大家提供免费的 Fireworks 兑换码。本文介绍如何在 AMD 国际站或中国站申请 $50 Credits,再在 PenguinHarness 里三步用起来。
---
-我们很高兴与 **AMD AI Developer Program**(AMD 开发者计划)合作,为大家带来 Fireworks 的免费兑换码:加入计划并通过审核,即可获得可兑换 **$50 Fireworks AI Credits** 的 Coupon Code。PenguinHarness 内置 Fireworks AI 网关分组——OpenAI 协议、预置 base URL 与五个模型,额度到手即刻可用。
+> 本文基于 PenguinHarness 0.1.0 撰写,之后的版本在部分细节上可能有所不同。
-> 页面内容、Credits 金额与有效期可能调整,请以申请时的页面及审批邮件为准。
+我们与 **AMD AI Developer Program**(AMD 开发者计划)合作,为大家带来免费的 Fireworks 兑换码。加入计划并通过审核,就能拿到一个兑换码,可兑换 **$50 Fireworks AI Credits**。PenguinHarness 内置 Fireworks AI 网关分组,OpenAI 协议、base URL 和五个模型都已预置,额度到手就能用。
-## 第一步:打开 AMD AI Developer Program 页面
+这个计划有国际站和中国站两个站点。两边的前两步不同,从填写申请表开始,步骤完全相同。
-访问 AMD AI Developer Program 中国站官方入口:
+> 页面内容、Credits 金额与有效期可能调整,请以申请页面和审批邮件为准。
-点击此链接 [AMD AI Developer Program 中国站](https://developer.amd.com.cn/login?source=2a6CMBw3K)
+## 第一步:注册或登录
-或在浏览器中输入下面的网址
-
-https://developer.amd.com.cn/login?source=2a6CMBw3K
-
-- 没有 AMD ADP账户:点击 “注册账号”。输入个人信息,创建ADP账户。
-
-- 已有 AMD ADP 账户:点击“登录”,然后按页面提示登录。
+- **国际站**:打开 <https://developer.amd.com/ai-developer-program/>,在 **Join the AMD AI Developer Program** 区域点击 **Create Account**,填写个人信息。已有 AMD ADP 账号的,点击 **Log In**,按页面提示登录。
+- **中国站**:打开 <https://developer.amd.com.cn/login?source=2a6CMBw3K>,点击**注册账号**,填写个人信息,创建 ADP 账号。已有账号的,点击**登录**,按页面提示登录。
<img width="327" height="690" alt="image 2" src="https://github.com/user-attachments/assets/e904e4aa-28e4-424e-98e1-373275000623" />
+## 第二步:进入申请页
-## 第二步:进入活动页
+登录后:
-点击首页“新闻/公告”或进入“活动中心”相关活动页,点击“去申请”。
+- **国际站**:
+ 1. 点击顶部导航栏中的 **Member Perks**。
+ 2. 找到 **Cloud Credit Options**。
+ 3. 点击页面底部的 **Request Cloud Credits**。
+- **中国站**:从首页的**新闻/公告**进入活动,或者在**活动中心**打开相关活动页,然后点击**去申请**。
<img width="1533" height="904" alt="image" src="https://github.com/user-attachments/assets/650ad0a8-6f27-4fea-b157-381d24fb3d15" />
+## 第三步:填写申请表
+按表单要求填写个人信息:
-## 第三步:填写 Credits 申请表
-
-进入申请表后,填写对应的个人信息。
-
-在Product Needed 处默认选择Fireworks AI。
-
-在Profile从处至少一个公开资料用于账户验证。审核人员将查看您的相关账号用于评估您的申请资格。
-
-
-
-填写页面中其他带 `*` 的必填项,检查邮箱、身份、产品选项和公开资料链接无误后提交申请。
-
+- 在 **Product Needed** 处选择 **Fireworks AI**。
+- 在 **Profile** 处至少填写一个公开资料,用于账号验证。LinkedIn、GitHub、作品集、公司或学校主页、微信、企业微信等都可以。审核人员会查看这些资料,评估你的申请资格。
+填好其他带 `*` 的必填项,核对邮箱、身份、产品选项和公开资料链接,确认无误后提交。
## 第四步:等待审核
-提交后,AMD 会验证账户及申请资料。通常需要 2–3 个工作日,实际时间可能因申请量、资料完整度或节假日而变化。
-
+AMD 会验证你的账号和申请资料,通常需要 2–3 个工作日。实际时间会受申请量、资料完整度和节假日影响。
+## 第五步:接收兑换码
-## 第五步:收到邮件并激活 Credits
+审核通过后,AMD 会向申请邮箱发送邮件,邮件里有一个唯一的兑换码(Coupon Code),可兑换 $50 Fireworks AI Credits。请妥善保存,不要公开、转发,也不要提交到代码仓库。
-审核通过后,AMD 会向申请邮箱发送附带兑换码的邮件
+## 第六步:兑换 Credits 并创建 API key
-审批邮件包含一个唯一 Coupon Code,用于兑换 $50 Fireworks AI Credits,请妥善保存,请勿公开、转发或提交到代码仓库中。
-
-
-## 第六步:兑换 Fireworks AI Credits 并创建 API Key
-
-1. 打开 [https://fireworks\.ai/](https://fireworks.ai/) 并登录 Fireworks AI 账户。
-
-2. 点击 Redeem Promo,输入邮件中的 Coupon Code,兑换 $50 Credits。
-
-3. 兑换成功后,点击 Create API Key,即可生成 Fireworks API Key。
+1. 打开 <https://fireworks.ai/> 并登录。
+2. 点击 **Redeem Promo**,输入邮件里的兑换码,兑换 $50 Credits。
+3. 点击 **Create API Key**,生成 Fireworks API key。
<img width="1462" height="733" alt="image 1" src="https://github.com/user-attachments/assets/179c8f11-18f2-4e80-b0b0-4d48fd81db80" />
-
-
## 在 PenguinHarness 中用起来
拿到 API key 后,三步接入:
-**1. 安装并启动**
-
-```bash
-curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # 打开 http://127.0.0.1:7364(首次登录:admin,初始密码见首次启动输出)
-```
-
-**2. 配置 Fireworks 模型**
-
-进入「模型仓库」页,找到 **Fireworks AI** 分组,点击「统一配置 key」粘贴刚创建的 API key。分组预置了五个模型——GLM 5.2、Kimi K2.7 Code、DeepSeek V4 Pro、MiniMax M3、DeepSeek V4 Flash——base URL 与价格已填好,任选一个设为默认即可;也可以点组头的「测速」,实测各模型的 TTFT 与 TPS 再决定。
+1. 安装 PenguinHarness 并启动 Web App:
-**3. 开始使用**
+ ```bash
+ curl -fsSL https://penguin.ooo/install.sh | sh
+ penguin web # 打开 http://127.0.0.1:7364(首次登录:admin / penguin-2026,登录页上也有提示)
+ ```
-回到对话页,把第一个任务交给 Agent——例如「分析 data.csv,输出各季度销售额汇总」。
+2. 打开**模型仓库**页面,找到 **Fireworks AI** 分组,点击**统一配置 API key**,粘贴刚创建的 API key。分组预置了五个模型:GLM 5.2、Kimi K2.7 Code、DeepSeek V4 Pro、MiniMax M3 和 DeepSeek V4 Flash,base URL 与价格都已填好,任选一个设为默认即可。想先比较各模型的实测 TTFT 与 TPS,可以点击分组上的**测速**。
+3. 回到**对话**页面,把第一个任务交给 Agent,例如「分析 data.csv,输出各季度销售额汇总」。
## 参考链接
+- [AMD AI Developer Program](https://developer.amd.com/ai-developer-program/)
- [AMD AI Developer Program 中国站](https://developer.amd.com.cn/login?source=2a6CMBw3K)
-- 申请步骤与截图整理自[AMD AI Developer Program 官方申请指南](https://acn658bi9o7j.feishu.cn/docx/T8VIdjkZXoqyDwxwNjacbcsYngd),感谢原作者
+- [AMD 官方 Cloud Credits 申请视频教程](https://www.youtube.com/watch?v=masSW53JkTY)
+- 国际站的申请步骤与截图整理自 WhatGhost 的申请指南([中文](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_%E7%94%B3%E8%AF%B7%E6%8C%87%E5%8D%97.md) / [English](https://github.com/WhatGhost/whatghost_Notebooks/blob/main/other/AMD_AI_Developer_Program_Credits_Application_Guide_EN.md)),中国站的申请步骤与截图整理自 [AMD AI Developer Program 官方申请指南](https://acn658bi9o7j.feishu.cn/docx/T8VIdjkZXoqyDwxwNjacbcsYngd)。感谢各位原作者。
- [PenguinHarness 模型配置文档](https://penguin.ooo/docs/models)
diff --git a/packages/landing/content/blog/free-models-in-penguin-harness.en.md b/packages/landing/content/blog/free-models-in-penguin-harness.en.md
index ee54fc6c..da8f6193 100644
--- a/packages/landing/content/blog/free-models-in-penguin-harness.en.md
+++ b/packages/landing/content/blog/free-models-in-penguin-harness.en.md
@@ -2,63 +2,74 @@
title: Introducing the free models in PenguinHarness
date: 2026-07-24
category: news
-excerpt: The preset catalog now carries four zero-cost OpenRouter entries — Nemotron 3 Ultra (free), the new Ling 3.0 Flash (free) and Laguna M.1 (free), and the new Free Models Router. One OpenRouter API key and an agent is running, no balance required. Here is the lineup, how to switch it on, and an honest account of what the free tier does and does not buy you.
+excerpt: The preset catalog now has four free OpenRouter entries, three of them new, so one free OpenRouter API key is all an agent needs. Here is the lineup, how to switch it on, and what the free tier does and does not give you.
---
-Trying an agent harness should not start with a top-up. PenguinHarness ships free models in its preset catalog: rows priced at $0 per million tokens, wired up like every other preset — protocol, base URL, pricing and context window pre-filled — so the only thing between you and a running agent is an OpenRouter API key, which is itself free to create.
+> Written for PenguinHarness 0.1.2. Later releases may differ in some details.
-As of today the free lineup is four entries, all in the OpenRouter group:
+PenguinHarness now ships free models in its preset catalog: rows priced at $0 per million Tokens, set up like every other preset with the protocol, base URL, pricing and context window filled in. The only thing between you and a running agent is an OpenRouter API key, which is itself free to create, and no balance is required.
-| Provider group | Model id | Context | Price |
-| -------------- | ---------------------------------------- | -------------: | ----- |
-| OpenRouter | `nvidia/nemotron-3-ultra-550b-a55b:free` | 1,000,000 | $0 |
-| OpenRouter | `inclusionai/ling-3.0-flash:free` | 262,144 | $0 |
-| OpenRouter | `poolside/laguna-m.1:free` | 262,144 | $0 |
+As of today, the free lineup has four entries, all in the OpenRouter group. Nemotron 3 Ultra was already in the catalog. Ling 3.0 Flash, Laguna M.1 and the Free Models Router are new.
+
+## The lineup
+
+| Provider group | Model id | Context | Price |
+| -------------- | ---------------------------------------- | ---------------------: | ----- |
+| OpenRouter | `nvidia/nemotron-3-ultra-550b-a55b:free` | 1,000,000 | $0 |
+| OpenRouter | `inclusionai/ling-3.0-flash:free` | 262,144 | $0 |
+| OpenRouter | `poolside/laguna-m.1:free` | 262,144 | $0 |
| OpenRouter | `openrouter/free` | 128,000 (conservative) | $0 |
-![The Models page's OpenRouter group: Ling 3.0 Flash (free), Nemotron 3 Ultra (free), Laguna M.1 (free) and the Free Models Router all carry the light-yellow Free badge, with Claude Opus 5 in the first card row](/blog-assets/free-models-page-en-light.webp)
+![The OpenRouter group on the Models page: Ling 3.0 Flash (free), Nemotron 3 Ultra (free), Laguna M.1 (free) and the Free Models Router each carry the light-yellow Free badge](/blog-assets/free-models-page-en-light.webp)
## Nemotron 3 Ultra (free)
-The catalog's first free row, and still its largest: NVIDIA's open frontier-reasoning and orchestration model, a Mixture-of-Experts with 55B active parameters out of 550B total on a hybrid Transformer–Mamba architecture, with a 1M-token context window. If you want to see what the harness's planning-heavy loops look like on a big reasoning model — without paying big-reasoning-model prices — this is the row.
+Nemotron 3 Ultra was the catalog's first free row, and it is still the largest. It is NVIDIA's open frontier model for reasoning and orchestration: a Mixture-of-Experts model with 55B active parameters out of 550B total, on a hybrid Transformer–Mamba architecture, with a context window of 1M Tokens. Pick this row to see how the harness's planning-heavy loops run on a large reasoning model without paying large-reasoning-model prices.
-## New: Ling 3.0 Flash (free)
+## Ling 3.0 Flash (free)
-Released by inclusionAI on July 23, in the catalog the next day. Ling-3.0-flash is a 124B-parameter MoE that activates only ~5.1B parameters per token, and inclusionAI's stated design priorities are token efficiency and production-scale agentic inference, tool calling included. That reads like a description of what an agent harness does all day: dozens of short round trips, each carrying a tool schema and a growing transcript, where efficiency per step is the whole cost model. A sparse, tool-tuned model at $0 is a very good default for exactly that traffic. Context is 262K; text only.
+inclusionAI released Ling 3.0 Flash on July 23, and it joined the catalog the next day. It is a 124B-parameter Mixture-of-Experts model that activates only about 5.1B parameters per Token. inclusionAI names Token efficiency and production-scale agent inference, tool calling included, as its design priorities.
-## New: Laguna M.1 (free)
+That is close to what an agent harness does all day: dozens of short round trips, each carrying a tool schema and a growing transcript, where the efficiency of each step decides the cost. A sparse, tool-tuned model at $0 is a good default for that kind of traffic. Context is 262K; text only.
-Alongside Ling comes the free tier of Poolside's flagship coding-agent model. Laguna M.1 is optimized for complex software-engineering work — agentic coding workflows with tool calling and reasoning, which is precisely the traffic a harness generates. Context is 262K; text only.
+## Laguna M.1 (free)
-## New: Free Models Router
+Laguna M.1 joined the catalog alongside Ling. This row is the free tier of Poolside's flagship coding-agent model, which is optimized for complex software-engineering work: agent coding workflows with tool calling and reasoning, the same traffic a harness generates. Context is 262K; text only.
-`openrouter/free` is not a model but OpenRouter's unified free-tier endpoint: each request is routed to a random free model currently available on OpenRouter, filtered so the target supports what the request actually needs — tool calling, structured outputs, and so on. Free models come and go upstream; the router keeps answering, and you never chase the current list yourself.
+## Free Models Router
-Two catalog decisions are worth knowing. The routed target's real context window varies per request, so the row records a deliberately conservative 128,000 rather than any single target's real figure — long Sessions compact early instead of growing toward a window the routed model may not have. And it is marked text-only on purpose: the router itself accepts images, but the model behind any given request may not, so PenguinHarness keeps images off this route and falls back to its usual text-only hand-off (file path plus `describe_image`).
+`openrouter/free` is not a model. It is OpenRouter's unified free-tier endpoint: each request goes to a random free model that is currently available on OpenRouter, chosen from the ones that support what the request needs, such as tool calling or structured outputs. Free models come and go upstream, but the router keeps answering, so you never have to track the current list yourself.
-## Switching it on
+Two decisions in the catalog are worth knowing:
-1. Create an API key at [openrouter.ai](https://openrouter.ai/) — the free tier needs no payment method.
-2. A new Project carries the presets already: open the **Models** page and paste the key on the OpenRouter group's bulk key button. An existing Project picks the new rows up with one click on **Sync presets** next to the Models page's search box — locally added models and stored credentials are untouched.
-3. Or from the terminal:
+- **Context window.** The routed model's real context window changes from request to request, so the row records a deliberately conservative 128,000 instead of any one model's real figure. Long Sessions compact early instead of growing toward a window the routed model may not have.
+- **Text only.** The router itself accepts images, but the model behind a given request may not. The row is marked text-only on purpose, so PenguinHarness does not send images on this route and falls back to its usual text-only hand-off (file path plus `describe_image`).
-```bash
-penguin config model add --provider openrouter --model-id inclusionai/ling-3.0-flash:free --api-key <your-key> --set-default
-penguin config model list
-```
+## Switch it on
+
+1. Create an API key at [openrouter.ai](https://openrouter.ai/). The free tier needs no payment method.
+2. Open the **Models** page:
+ - A new Project already has the presets. Click **Set API key for group** on the OpenRouter group and paste the key once for the whole group.
+ - An existing Project picks up the new rows with one click on **Sync presets**, next to the search box. Locally added models and stored API keys stay as they are.
+3. Or add a model from the terminal:
+
+ ```bash
+ penguin config model add --provider openrouter --model-id inclusionai/ling-3.0-flash:free --api-key <your-key> --set-default
+ penguin config model list
+ ```
-Set a free row as the Project default, or leave the default alone and pick one in the model selector when starting a Session — models are chosen per Session, not bound to an Agent. Free rows carry a light-yellow "Free" badge on the Models page and in the model picker, so they are easy to spot.
+Set a free row as the Project default, or keep your default and pick a free row in the model picker when you start a Session. Models are chosen per Session, not tied to an agent. Free rows carry a light-yellow **Free** badge on the **Models** page and in the model picker, so they are easy to spot.
-## What free buys you, and what it does not
+## What free gives you, and what it does not
-The caveats, plainly:
+Free models let you try the full harness: Workspaces, tools, Skills, subagents, and a **Costs** page that reads $0. They also handle light automation. The limits:
-- **Rate limits.** OpenRouter's free tier caps requests per minute and per day; a long Session or a benchmark run can hit them.
-- **Data policy.** Free models run under OpenRouter's free-model terms, and prompts may be used by the upstream provider as its terms allow. Send nothing you would not share.
-- **Availability and quality vary.** Free capacity is whatever providers choose to offer; models get busy, get slower, and get withdrawn.
-- **The router's target changes per request.** Its real context window varies with it — hence the conservative recorded window, which makes long Sessions compact early — and consistency is not what `openrouter/free` is for; a fixed free row gives you more of it, a paid row the most.
+- **Rate limits.** OpenRouter's free tier caps requests per minute and per day. A long Session or a Benchmark run can hit those caps.
+- **Data policy.** Free models run under OpenRouter's free-model terms, and the upstream provider may use your prompts as its terms allow. Send nothing you would not share.
+- **Availability and quality vary.** Free capacity is whatever providers choose to offer. Models get busy, slow down, and get withdrawn.
+- **The router's target changes per request.** Its real context window changes with it, which is why the catalog records a conservative window and long Sessions compact early. Consistency is not what `openrouter/free` is for: a fixed free row gives you more of it, and a paid row the most.
-Free models are a genuine way to experience the full harness — Workspaces, tools, Skills, subagents, the Cost center reading a clean $0 — and to run light automation. For serious work, pick a paid model; the same catalog carries plenty.
+For serious work, pick a paid model. The same catalog has plenty.
## Get it
@@ -67,4 +78,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Then open the Models page, drop in an OpenRouter key, and pick a free row.
+Then open the **Models** page, add an OpenRouter key, and pick a free row.
diff --git a/packages/landing/content/blog/free-models-in-penguin-harness.zh.md b/packages/landing/content/blog/free-models-in-penguin-harness.zh.md
index ceab9c1f..f17555ff 100644
--- a/packages/landing/content/blog/free-models-in-penguin-harness.zh.md
+++ b/packages/landing/content/blog/free-models-in-penguin-harness.zh.md
@@ -1,64 +1,75 @@
---
-title: 介绍 PenguinHarness 里的免费模型
+title: PenguinHarness 免费模型介绍
date: 2026-07-24
category: news
-excerpt: 预置目录现有四条 $0 价格的 OpenRouter 条目——已有的 Nemotron 3 Ultra (free),以及新增的 Ling 3.0 Flash (free)、Laguna M.1 (free) 与 Free Models Router。一个免费注册的 OpenRouter API Key 就能把 Agent 跑起来,无需充值。本文介绍这套免费阵容、开启方式,以及免费档能换来什么、换不来什么。
+excerpt: 预置目录现有四个免费的 OpenRouter 条目,其中三个是新加入的,一个免费的 OpenRouter API key 就能让 Agent 跑起来。本文介绍这套免费阵容、开启方法,以及免费档能提供什么、不能提供什么。
---
-试用一个 Agent Harness,不应该从充值开始。PenguinHarness 的预置目录里带着免费模型:每百万 Token 价格为 $0 的模型行,和其他预置条目一样填好了协议、base URL、价格与上下文窗口——你与一个跑起来的 Agent 之间,只隔着一个 OpenRouter API Key,而注册它本身也是免费的。
+> 本文基于 PenguinHarness 0.1.2 撰写,之后的版本在部分细节上可能有所不同。
-截至今天,免费阵容共四条,全部在 OpenRouter 分组下:
+PenguinHarness 的预置目录现在带有免费模型:这些条目每百万 Token 价格为 $0,和其他预置条目一样,协议、base URL、价格和上下文窗口都已填好。要跑起一个 Agent,只需要一个 OpenRouter API key。创建 API key 本身免费,也不需要账户余额。
-| 提供方分组 | 模型 ID | 上下文 | 价格 |
-| ---------- | ---------------------------------------- | ---------------: | ---- |
-| OpenRouter | `nvidia/nemotron-3-ultra-550b-a55b:free` | 1,000,000 | $0 |
-| OpenRouter | `inclusionai/ling-3.0-flash:free` | 262,144 | $0 |
-| OpenRouter | `poolside/laguna-m.1:free` | 262,144 | $0 |
-| OpenRouter | `openrouter/free` | 128,000(保守值) | $0 |
+截至今天,免费阵容共四个条目,全部在 OpenRouter 分组下。Nemotron 3 Ultra 之前就在目录里,Ling 3.0 Flash、Laguna M.1 和 Free Models Router 是新加入的。
-![模型仓库的 OpenRouter 分组:Ling 3.0 Flash (free)、Nemotron 3 Ultra (free)、Laguna M.1 (free) 与 Free Models Router 均带淡黄色「免费」标签,首行还能看到 Claude Opus 5](/blog-assets/free-models-page-zh-light.webp)
+## 免费阵容
+
+| 供应商分组 | 模型 ID | 上下文 | 价格 |
+| ---------- | ---------------------------------------- | ----------------: | ---- |
+| OpenRouter | `nvidia/nemotron-3-ultra-550b-a55b:free` | 1,000,000 | $0 |
+| OpenRouter | `inclusionai/ling-3.0-flash:free` | 262,144 | $0 |
+| OpenRouter | `poolside/laguna-m.1:free` | 262,144 | $0 |
+| OpenRouter | `openrouter/free` | 128,000(保守值) | $0 |
+
+![模型仓库页面的 OpenRouter 分组:Ling 3.0 Flash (free)、Nemotron 3 Ultra (free)、Laguna M.1 (free) 和 Free Models Router 都带淡黄色的「免费」标签](/blog-assets/free-models-page-zh-light.webp)
## Nemotron 3 Ultra (free)
-目录里的第一条免费行,也仍是最大的一条:NVIDIA 的开放前沿推理与编排模型,MoE 架构,总参数 550B、每 Token 激活 55B,混合 Transformer–Mamba,上下文窗口 1M Token。想看看 Harness 的重规划循环跑在大推理模型上是什么样、又不想付大推理模型的价格,就选这一行。
+Nemotron 3 Ultra 是目录里的第一个免费条目,至今仍是最大的一个。它是 NVIDIA 面向推理与编排的开放前沿模型:MoE 架构,总参数 550B、激活参数 55B,采用 Transformer–Mamba 混合架构,上下文窗口 1M Token。想看看 Harness 里以规划为主的循环跑在大型推理模型上是什么样子,又不想付大型推理模型的价钱,就选这一条。
-## 新增:Ling 3.0 Flash (free)
+## Ling 3.0 Flash (free)
-inclusionAI 于 7 月 23 日发布,次日进入目录。Ling-3.0-flash 是一个 124B 参数的 MoE 模型,每个 Token 只激活约 5.1B 参数;inclusionAI 给它的设计目标是 Token 效率与生产规模的 Agent 推理,含工具调用。这几乎就是在描述一个 Agent Harness 每天做的事:几十次短往返,每一次都带着工具 Schema 和不断增长的对话记录,单步效率就是全部的成本模型。一个稀疏、面向工具调用调优、价格为 $0 的模型,正适合承接这类流量。上下文 262K,仅文本。
+inclusionAI 在 7 月 23 日发布 Ling 3.0 Flash,第二天就进了目录。这是一个 124B 参数的 MoE 模型,每个 Token 只激活约 5.1B 参数。inclusionAI 给它定的设计重点是 Token 效率和生产规模的 Agent 推理,工具调用也包括在内。
-## 新增:Laguna M.1 (free)
+这几乎就是 Agent Harness 每天在做的事:几十次短往返,每次都带着工具 Schema 和不断变长的对话记录,每一步的效率决定了成本。一个稀疏、针对工具调用调优、价格为 $0 的模型,很适合默认承接这类流量。上下文 262K,仅支持文本。
-与 Ling 一同进入目录的,还有 Poolside 旗舰编码 Agent 模型的免费档。Laguna M.1 面向复杂软件工程任务优化——支持工具调用与推理的 Agent 编码工作流,而这正是 Harness 产生的流量形态。上下文 262K,仅文本。
+## Laguna M.1 (free)
-## 新增:Free Models Router
+Laguna M.1 和 Ling 同时进入目录。这一条是 Poolside 旗舰编码 Agent 模型的免费档。这个模型针对复杂的软件工程任务优化,擅长带工具调用和推理的 Agent 编码工作流,正是 Harness 产生的那类流量。上下文 262K,仅支持文本。
-`openrouter/free` 不是一个模型,而是 OpenRouter 的统一免费端点:每个请求被随机路由到 OpenRouter 上当前可用的某个免费模型,并按请求真正需要的能力过滤——工具调用、结构化输出等。上游的免费模型来来去去,这个路由始终有答案,你不必自己盯着最新清单。
+## Free Models Router
-有两个目录层面的决定值得说明。被路由到的目标随请求变化,其真实上下文窗口也随之变化,所以这一行刻意记录一个保守值 128,000,而非任何单一目标的真实窗口——长会话会提前压缩,而不是向被路由模型未必拥有的窗口继续膨胀。它也被刻意标记为仅文本:路由本身接受图片,但任一请求背后的模型未必支持,所以 PenguinHarness 不向这条路由发送图片,改走常规的纯文本交接(文件路径加 `describe_image`)。
+`openrouter/free` 不是一个模型,而是 OpenRouter 的统一免费端点:每个请求会随机发给 OpenRouter 上当前可用的某个免费模型,候选模型都支持这个请求需要的能力,比如工具调用或结构化输出。上游的免费模型来来去去,这个路由始终能响应,你不用自己盯着最新的模型清单。
-## 开启方式
+目录为这一条做了两个决定,值得了解:
-1. 在 [openrouter.ai](https://openrouter.ai/) 注册并创建 API Key——免费档不需要绑定支付方式。
-2. 新建 Project 自带这些预置条目:打开 **Models** 页面,用 OpenRouter 分组的批量填 Key 按钮贴上 Key 即可。已有 Project 点一下搜索框旁的**同步预置**就能拿到新行——本地添加的模型与已存凭证都不会被动到。
-3. 也可以走终端:
+- **上下文窗口。** 实际接收请求的模型每次都可能不同,真实上下文窗口也随之变化,所以这一条刻意记录了保守值 128,000,而不是某个模型的真实窗口。这样长会话会提前压缩,不会一直增长到目标模型未必撑得住的长度。
+- **仅支持文本。** 路由本身接受图片,但某次请求背后的模型未必支持。这一条特意标记为仅支持文本,所以 PenguinHarness 不会在这条路由上发送图片,而是改走平常的纯文本交接(文件路径加 `describe_image`)。
-```bash
-penguin config model add --provider openrouter --model-id inclusionai/ling-3.0-flash:free --api-key <your-key> --set-default
-penguin config model list
-```
+## 开启免费模型
+
+1. 在 [openrouter.ai](https://openrouter.ai/) 创建 API key。免费档不需要绑定支付方式。
+2. 打开**模型仓库**页面:
+ - 新建的 Project 已经带有这些预置条目。在 OpenRouter 分组上点击**统一配置 API key**,粘贴一次 API key,整个分组都会生效。
+ - 已有的 Project 点一下搜索框旁的**同步预置**,就能拿到新条目。本地添加的模型和已保存的 API key 都不受影响。
+3. 也可以在终端里添加模型:
+
+ ```bash
+ penguin config model add --provider openrouter --model-id inclusionai/ling-3.0-flash:free --api-key <your-key> --set-default
+ penguin config model list
+ ```
-把某条免费行设为 Project 默认,或者不动默认、在创建会话时于模型选择器里现选一条——模型按 Session 选择,不绑定 Agent。免费行在 Models 页面与模型选择器中都带淡黄色「免费」标签,一眼可辨。
+可以把某个免费条目设为 Project 的默认模型;也可以不动默认模型,开始会话时在模型选择器里选一个免费条目。模型按会话选择,不绑定 Agent。免费条目在**模型仓库**页面和模型选择器里都带淡黄色的**免费**标签,很容易认出来。
-## 免费换来什么,换不来什么
+## 免费能提供什么,不能提供什么
-把话说在前面:
+免费模型足以完整体验 Harness:Workspace、工具、Skill、子 Agent,还有显示 $0 的**成本中心**。轻量的自动化任务也可以交给它们。需要注意的限制如下:
-- **速率限制。** OpenRouter 免费档限制每分钟与每天的请求数;一段长会话或一轮评测就可能碰到上限。
-- **数据政策。** 免费模型按 OpenRouter 的免费模型条款运行,Prompt 可能在上游条款允许的范围内被其使用。不要发送任何你不愿意公开的内容。
-- **可用性与质量会波动。** 免费容量取决于提供方的意愿;模型会变忙、变慢,也会下线。
-- **路由目标逐请求变化。** 目标的真实上下文窗口也随之变化——因此目录记录的是上面那个保守值,让长会话尽早压缩;一致性本就不是 `openrouter/free` 的目标,固定选一条免费行会更一致,付费行最一致。
+- **速率限制。** OpenRouter 免费档限制每分钟和每天的请求数。一次长会话或一轮 Benchmark 运行就可能碰到上限。
+- **数据政策。** 免费模型按 OpenRouter 的免费模型条款运行,上游供应商可能在自家条款允许的范围内使用你发送的提示词。不愿公开的内容不要发送。
+- **可用性和质量有波动。** 免费容量取决于供应商愿意提供多少。模型会变忙、变慢,也会下线。
+- **路由目标每次请求都在变。** 真实上下文窗口也随之变化,所以目录记录的是保守窗口,长会话会提前压缩。`openrouter/free` 本来就不追求一致性:固定使用一个免费条目会更稳定,付费条目最稳定。
-免费模型足以真实地体验完整的 Harness——Workspace、工具、Skill、子 Agent,以及费用中心里干干净净的 $0——也能承担轻量自动化。正经的工作请换付费模型,同一份目录里有的是。
+正式的工作请选付费模型,同一份目录里有很多。
## 获取方式
@@ -67,4 +78,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-然后打开 Models 页面,填入 OpenRouter Key,选一条免费行。
+然后打开**模型仓库**页面,填入 OpenRouter API key,选一个免费条目。
diff --git a/packages/landing/content/blog/gemini-3-6-in-penguinharness.en.md b/packages/landing/content/blog/gemini-3-6-in-penguinharness.en.md
index 086ee58a..67df295d 100644
--- a/packages/landing/content/blog/gemini-3-6-in-penguinharness.en.md
+++ b/packages/landing/content/blog/gemini-3-6-in-penguinharness.en.md
@@ -1,19 +1,21 @@
---
-title: "PenguinHarness 0.1.1: Gemini 3.6 Flash support, for building agents faster and better"
+title: "PenguinHarness 0.1.1: Gemini 3.6 Flash and 3.5 Flash-Lite support"
date: 2026-07-22
category: news
-excerpt: Google reports Gemini 3.6 Flash at 63.9% on MLE-Bench, against 49.7% for 3.5 Flash. MLE-Bench scores machine-learning engineering — an agent doing the work of building and tuning ML systems, which is exactly what PenguinHarness exists to do. The model is in the catalog today, at a lower price than the Flash it replaces. Here is the case, and the rest of the 0.1.1 release.
+excerpt: Google reports Gemini 3.6 Flash at 63.9% on MLE-Bench, up from 49.7% for 3.5 Flash, at a lower price. PenguinHarness 0.1.1 adds it to the catalog along with 3.5 Flash-Lite. Here is why it matters, and the rest of the release.
---
-Google announced [Gemini 3.6 Flash, 3.5 Flash-Lite, and 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/) on July 21, 2026. One number in that announcement matters more to PenguinHarness than everything else in it: **MLE-Bench, 63.9% against 3.5 Flash's 49.7%**.
+PenguinHarness 0.1.1 adds Gemini 3.6 Flash and 3.5 Flash-Lite to the model catalog, one day after Google announced them. By Google's numbers, 3.6 Flash scores 63.9% on MLE-Bench against 49.7% for 3.5 Flash, and it costs less. The release also makes max output tokens a per-model setting, corrects Gemini cache pricing, and adds `penguin update` for in-place upgrades.
-## Why that one number
+## Why Gemini 3.6 Flash matters for PenguinHarness
-MLE-Bench scores machine-learning *engineering* — an agent doing the work of building, training and tuning an ML system, not answering questions about one. Google's own phrasing for the result is a "significant improvement in ML Research, as seen in MLE Bench (63.9% vs. 49.7%)". That is a 14.2-point gain, the largest move of the three percentage-scored panels in Google's chart below, and it lands well above the 42.6% the same chart records for the previous Pro-generation model, 3.1 Pro.
+Google announced [Gemini 3.6 Flash, 3.5 Flash-Lite, and 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/) on July 21, 2026. For PenguinHarness, one number in that announcement matters more than the rest: **MLE-Bench, 63.9% against 3.5 Flash's 49.7%**.
-PenguinHarness exists so that **agents build agents — faster, better, cheaper**. Every loop the product runs is machine-learning engineering in miniature: stand a model up, hand an agent a task, score it against a private rubric, read the failures, tune, redeploy, measure again. A model that is markedly better at precisely that work, priced in the Flash tier, is the strongest model yet for what this harness does all day. That is the argument; the rest of this post is the evidence, and then the rest of the release.
+MLE-Bench measures machine-learning *engineering*: an agent doing the work of building, training and tuning an ML system, not answering questions about one. Google describes the result as a "significant improvement in ML Research, as seen in MLE Bench (63.9% vs. 49.7%)". That is a 14.2-point gain, the largest of the three percentage-scored panels in Google's chart below, and well above the 42.6% the same chart records for the previous Pro-generation model, 3.1 Pro.
-One caveat up front, and it holds for every figure below: these are **Google's numbers, from Google's evaluation methodology**. We have not independently reproduced any of them.
+PenguinHarness exists so that agents build agents, faster, better and cheaper. Every loop the product runs is machine-learning engineering in miniature: stand a model up, hand an agent a task, score it against a private rubric, read the failures, tune, redeploy, and measure again. A model that is markedly better at exactly that work, priced in the Flash tier, is the strongest model yet for what this harness does all day.
+
+One caveat applies to every figure below: these are **Google's numbers, from Google's evaluation methodology**. We have not independently reproduced any of them.
## The rest of the scoreboard
@@ -30,19 +32,21 @@ MLE-Bench does not stand alone. Against 3.5 Flash, Google reports:
| GDPval-AA v2 | Knowledge work | 1349 | 1421 |
| OSWorld-Verified | Computer use | 78.4% | 83.0% |
-The three supporting rows are the ones an ML-engineering loop actually leans on. Long-horizon software engineering is how the agent edits the training config, the dataset builder and the serving flags without thrashing — Google attributes the DeepSWE jump to "higher precision with fewer unwanted code edits and reduced execution loops", the failure mode anyone who has watched an agent churn through a repository will recognize. Computer use is now a built-in client-side tool in the Gemini API and Gemini Enterprise. And the model ships with enhanced Frontier Safety safeguards for CBRN and cyber-offense misuse that Google says make it "substantially more resistant to jailbreaks" while minimizing refusals for beneficial uses.
+The other three rows are abilities an ML-engineering loop relies on. Long-horizon software engineering lets the agent edit the training config, the dataset builder and the serving flags without thrashing. Google attributes the DeepSWE jump to "higher precision with fewer unwanted code edits and reduced execution loops". Computer use is now a built-in client-side tool in the Gemini API and Gemini Enterprise.
+
+The model also ships with enhanced Frontier Safety safeguards against CBRN and cyber-offense misuse. Google says these make it "substantially more resistant to jailbreaks" while minimizing refusals for beneficial uses.
-## The cheaper leg: fewer tokens, fewer steps, lower price
+## Fewer Tokens, fewer steps, lower price
-Google's framing of the release lands squarely on what a harness like this one does all day: "Developers and customers building production AI agents need higher token efficiency, lower latency, and more reliable performance." An agent loop is not one long completion — it is dozens of short round trips, each carrying a tool schema, a growing transcript and a reasoning budget. Efficiency per step is the whole cost model.
+Google frames the release around what a harness like this one does all day: "Developers and customers building production AI agents need higher token efficiency, lower latency, and more reliable performance." An agent loop is not one long completion. It is dozens of short round trips, each carrying a tool schema, a growing transcript and a reasoning budget, so the efficiency of each step decides the cost.
-Google reports 3.6 Flash consuming **17% fewer output tokens than 3.5 Flash** on the Artificial Analysis Index, with "up to 65%" observed on some benchmarks such as DeepSWE by Datacurve, and says it "takes fewer reasoning steps and tool calls to accomplish multi-step workflows." That efficiency "is also combined with a lower price than 3.5 Flash": **$1.50 per million input tokens and $7.50 per million output tokens**. Google's own conclusion is the one that matters here — the combination "reduces the overall cost per agentic task, making agents more cost-effective to build and run."
+Google reports that 3.6 Flash uses **17% fewer output Tokens than 3.5 Flash** on the Artificial Analysis Index, with "up to 65%" observed on some benchmarks such as DeepSWE by Datacurve. It also "takes fewer reasoning steps and tool calls to accomplish multi-step workflows."
-Fewer tokens, fewer steps, lower unit price. For a self-improving loop that re-runs a whole benchmark suite on every round, the three compound.
+That efficiency "is also combined with a lower price than 3.5 Flash": **$1.50 per million input Tokens and $7.50 per million output Tokens**. In Google's words, the combination "reduces the overall cost per agentic task, making agents more cost-effective to build and run." For a self-improving loop that re-runs a whole Benchmark suite every round, fewer Tokens, fewer steps and a lower unit price compound.
-## What ships in PenguinHarness today
+## The models in PenguinHarness today
-One day after the announcement, the catalog carries both generally available models, on two routes each:
+One day after the announcement, the catalog carries both generally available models, each on two routes:
| Provider group | Model id | Context | Vision |
| -------------- | ------------------------------ | --------: | ------ |
@@ -51,64 +55,99 @@ One day after the announcement, the catalog carries both generally available mod
| OpenRouter | `google/gemini-3.6-flash` | 1,048,576 | yes |
| OpenRouter | `google/gemini-3.5-flash-lite` | 1,048,576 | yes |
-The Google-endpoint rows are auto-routed by model id, so a `GEMINI_API_KEY` is all they need. The OpenRouter rows carry the OpenAI client type and the gateway's base URL inline, so they need nothing but an OpenRouter key. Either way, the fastest path is the **Models** page in the Web App: find the row, add the key, done. From the CLI it is one command:
+The Google endpoint rows are routed automatically by model id, so a `GEMINI_API_KEY` is all they need. The OpenRouter rows carry the OpenAI client type and the gateway's base URL inline, so they need only an OpenRouter key.
+
+Either way, the fastest path is the **Models** page in the Web App: find the row and add the key. From the CLI, it is one command:
```bash
penguin config model add --provider google --model-id gemini-3.6-flash --api-key <your-key>
penguin config model list
```
-Two related corrections landed with them. Gemini pricing is now recorded with the vendor's real cache-hit rate rather than the input price repeated into the cache bucket — $0.15 per million cached input tokens for 3.6 Flash, $0.03 for 3.5 Flash-Lite — so the Cost center no longer overstates cache-heavy spend by an order of magnitude. And `google/gemini-3.5-flash` had its context window recorded as 1,000,000; the real figure, on both the gateway and the direct endpoint, is 1,048,576.
+Two related corrections landed with the new rows:
+
+- Gemini pricing now records the vendor's real cache-hit rate instead of repeating the input price in the cache bucket: $0.15 per million cached input Tokens for 3.6 Flash, and $0.03 for 3.5 Flash-Lite. The **Costs** page no longer overstates cache-heavy spend by an order of magnitude.
+- `google/gemini-3.5-flash` had its context window recorded as 1,000,000. The real figure, on both the gateway and the direct endpoint, is 1,048,576.
-### 3.5 Flash-Lite, the fan-out half
+### 3.5 Flash-Lite for fan-out work
-The second model in the catalog is aimed at volume rather than depth. Gemini 3.5 Flash-Lite is the fastest model in the 3.5 series as measured by Artificial Analysis, running at **350 output tokens per second**, priced at **$0.30 per million input tokens and $2.50 per million output tokens**. Google positions it for high-throughput work like agentic search and document processing, with configurable thinking levels so the same model can be driven cheap-and-shallow for bulk tasks or pushed higher for multi-step subagent workloads. Computer use is a built-in tool here too.
+The second new model is built for volume rather than depth. As measured by Artificial Analysis, Gemini 3.5 Flash-Lite is the fastest model in the 3.5 series, at **350 output Tokens per second**. It is priced at **$0.30 per million input Tokens and $2.50 per million output Tokens**.
-Against the previous Flash-Lite generation, Google reports Terminal-Bench 2.1 at **54% vs 31%**, long context on GDM-MRCR v2 at **72.2% vs 60.1%**, and GDPval-AA v2 at **1140 vs 642**. On several agentic and coding evals it even passes 3 Flash — SWE-Bench Pro **54.2% vs 49.6%**, OSWorld-Verified **74.0% vs 65.1%**.
+Google positions it for high-throughput work such as agentic search and document processing. Its thinking level is configurable, so the same model can run cheap and shallow for bulk tasks, or higher for multi-step subagent workloads. Computer use is a built-in tool here too.
-That is a very good fit for the subagent pattern PenguinHarness runs on: a capable parent model planning, a cheap fast model fanning out. Google's own post shows the same shape — 3.5 Flash-Lite generating design concepts "alongside 3.6 Flash as the master agent."
+Against the previous Flash-Lite generation, Google reports Terminal-Bench 2.1 at **54% vs 31%**, long context on GDM-MRCR v2 at **72.2% vs 60.1%**, and GDPval-AA v2 at **1140 vs 642**. On several agentic and coding evals it even passes 3 Flash: SWE-Bench Pro at **54.2% vs 49.6%**, and OSWorld-Verified at **74.0% vs 65.1%**.
-The third model in Google's announcement, 3.5 Flash Cyber, is deliberately out of reach: Google says it will be available exclusively to governments and trusted partners through CodeMender, as part of a limited-access pilot program. It is not something PenguinHarness — or anyone else — will be pointing a base URL at.
+That fits the subagent pattern PenguinHarness runs on: a capable parent model plans, and a cheap, fast model fans out. Google's own post shows the same shape, with 3.5 Flash-Lite generating design concepts "alongside 3.6 Flash as the master agent."
+
+The third model in Google's announcement, 3.5 Flash Cyber, is out of reach on purpose. Google says it will be available only to governments and trusted partners through CodeMender, as part of a limited-access pilot program, so it is not in the PenguinHarness catalog.
## The rest of 0.1.1
-The Gemini rows are one line of a much larger catalog refresh, and the catalog is one surface of a release that touched most of them.
+The Gemini rows are one part of a much larger catalog refresh, and the catalog is one of many areas this release touched.
### Models and core
-The SDK moved to **AgentHub 0.4.1**, a type-compatible upgrade whose new supported-model registry — model, base URL and client triples with modalities, context windows and per-million pricing — became the authoritative source for a catalog diff. The catalog grew from 59 to 70 entries: the two Gemini rows above on both routes, Claude Fable 5 and Claude Sonnet 5 on Anthropic, Kimi K3 on Moonshot, Kimi K2.6, Qwen3.6 35B A3B and GLM 5.1 on OpenRouter, and the same three on SiliconFlow. The last three ship unpriced on purpose: no source publishes their rates, and a guessed number is worse than none. Every context window, vision flag and price came from the registry rather than a vendor marketing page.
+The SDK moved to **AgentHub 0.4.1**, a type-compatible upgrade. Its new supported-model registry lists model, base URL and client triples with modalities, context windows and per-million pricing, and it became the authoritative source for refreshing the catalog. Every context window, vision flag and price came from the registry rather than a vendor marketing page. The catalog grew from 57 to 70 entries. The new rows are:
+
+- Gemini 3.6 Flash and 3.5 Flash-Lite, on both routes above
+- Claude Fable 5 and Claude Sonnet 5 on Anthropic
+- Kimi K3 on Moonshot
+- Kimi K2.6, Qwen3.6 35B A3B and GLM 5.1 on OpenRouter
+- The same three on SiliconFlow
+
+The three SiliconFlow rows have no price on purpose: no source publishes their rates, and a guessed number is worse than none.
Three fixes matter if you run agents against local or strict endpoints:
-- **Empty tool lists no longer go on the wire.** Strict OpenAI-compatible servers reject `tools: []` outright — vLLM answers `400 … tools must not be an empty array`. Every tool-less request the harness makes (the connectivity probe, session-title generation, the vision describer) used to hit that. The field is now omitted entirely when the list is empty.
-- **Max output tokens is a per-model setting.** A 32k-context model served locally would refuse requests because the agent-level default asked for 32,000 output tokens. The Models page and `penguin config model add --max-tokens` now take a per-model cap that applies ahead of the agent default, and out-of-band requests take the smaller of the two.
-- **The default system prompt gained guardrails.** Agents that freed a busy port by killing its listener sometimes killed the harness's own services; the prompt now says never kill a process you did not start, and pick another free port instead. On a 401/403 or invalid-key error the agent retries once, then stops and asks you to update the key outside the conversation — secret values do not belong in a chat transcript. Existing agents keep their current prompt; new ones get the rules.
+- **Empty tool lists are no longer sent.** Strict OpenAI-compatible servers reject `tools: []` outright; vLLM answers `400 … tools must not be an empty array`. Every request the harness makes without tools used to hit this: the connectivity probe, Session title generation and the vision describer. The field is now left out entirely when the list is empty.
+- **Max output tokens is a per-model setting.** A 32k-context model served locally would refuse requests, because the agent-level default asked for 32,000 output Tokens. The **Models** page and `penguin config model add --max-tokens` now take a per-model cap that applies ahead of the agent default. Out-of-band requests use the smaller of the two.
+- **The default system prompt has new guardrails.** Agents that freed a busy port by killing its listener sometimes killed the harness's own services. The prompt now says never to kill a process you did not start, and to pick another free port instead. On a 401, a 403 or an invalid-key error, the agent retries once, then stops and asks you to update the key outside the conversation, because secret values do not belong in a chat transcript. Existing agents keep their current prompt; new agents get the rules.
-Two runtime settings changed shape. The thinking level moved out of the Models page and into a compact picker next to the model selector in the chat draft (`low` / `medium` / `high` / `xhigh`), writing through to Agent settings so the session created on send uses it. And subagents now inherit the parent session's resolved `(provider, model_id)` pair and effective thinking level instead of falling back to the project default — an explicit pair in the tool call still wins.
+Two runtime settings changed shape:
+
+- **Thinking level** moved out of the **Models** page into a compact picker next to the model selector in the chat draft (`low` / `medium` / `high` / `xhigh`). It writes through to the agent's settings, so the Session created when you send uses it.
+- Subagents now inherit the parent Session's resolved `(provider, model_id)` pair and effective thinking level instead of falling back to the Project default. An explicit pair in the tool call still wins.
### Web App
-The chat sidebar now groups conversations **by Workspace** by default, labeled by directory basename, ordered by newest session, with auto-created temp workspaces collapsed into a single group instead of one per session. Groups can be pinned to the top, collapse state persists per Project, sessions created by subagents and scheduled tasks file into their own folders, and each group pages in more sessions on demand rather than fetching an unbounded list. Agent grouping is still one toggle away.
+The chat sidebar now groups conversations by Workspace by default. Each group is labeled with its directory name and ordered by newest Session, and auto-created temporary Workspaces share a single group instead of getting one each. You can pin groups to the top, and collapse state is saved per Project. Sessions created by subagents and scheduled tasks go into their own folders, and each group loads more Sessions on demand instead of fetching an unbounded list. Grouping by agent is still one toggle away.
+
+The model dropdown now lists models that have a configured key first, with the rest one click below. The collapsed sidebar is now a full eight-entry navigation rail with bilingual tooltips; before, it had no Benchmark entry at all. Custom provider groups and agents show initial-letter avatars on a background tinted by their id, with WCAG AA contrast in both themes, so same-named models in different groups are no longer indistinguishable.
-The model dropdown now lists models that actually have a configured key first, with the rest one click below. The collapsed sidebar became a full eight-entry navigation rail with bilingual tooltips (Benchmark was previously missing entirely). Custom provider groups and Agents render initial-letter avatars on a tinted background derived from the name, holding WCAG AA contrast in both themes, so same-named models across groups stop being indistinguishable.
+Chat rendering got a pass:
-Chat rendering got a pass: links open in a new tab, long URLs and inline code wrap at the container edge without splitting Latin words inside CJK prose, wide tables scroll inside the message instead of widening the page, expanded subagent conversations render below the tool call's own output, and three mobile dropdowns that used to overflow the viewport by up to 143px now stay inside it. The Cost center's daily-token tooltip follows the pointer and shows the cache hit rate; the copy-message task-stats line, previously hardcoded Chinese, now goes through the dictionaries like everything else.
+- Links open in a new tab.
+- Long URLs and inline code wrap at the container edge, without splitting Latin words inside CJK text.
+- Wide tables scroll inside the message instead of widening the page.
+- Expanded subagent conversations render below the tool call's own output.
+- Three mobile dropdowns that overflowed the viewport by up to 143px now stay inside it.
+
+The daily Token tooltip on the **Costs** page follows the pointer and shows the cache hit rate. The task-stats line added when you copy a message was hardcoded in Chinese; it now goes through the dictionaries like everything else.
### Skills
-Three new skills join the AI App Development group — **vllm**, **ollama** and **llamafactory** — so an agent can stand up and tune the models it builds on, not just call them. Both serving skills share a guided workflow: ask which model to serve, ask which engine the user prefers, serve, verify, then register the endpoint with the CLI. The `penguin-cli` skill (now v5) and `penguin-sdk` carry the hard rule they lean on: configuring Penguin's own model uses the default data root, but models configured for an app under development must go into the app's own project directory. There is a whole [practice post](/blog/natural-language-training-loop) on what changes once an agent holds all three — you stop typing the commands and start describing the outcome.
+Three new Skills join the AI App Development group: `vllm`, `ollama` and `llamafactory`. With them, an agent can stand up and tune the models it builds on, not just call them. The two serving Skills share a guided workflow: ask which model to serve, ask which engine you prefer, serve it, verify it, then register the endpoint with the CLI.
+
+The `penguin-cli` Skill (now v5) and `penguin-sdk` carry the hard rule the serving Skills rely on: configuring Penguin's own model uses the default data root, but models configured for an app under development must go into that app's own project directory. A separate [practice post](/blog/natural-language-training-loop) covers what changes once an agent holds all three: you stop typing the commands and start describing the outcome.
-A fourth skill, **bento-slides**, joins the Office Productivity group: ask for a presentation and the agent authors a real Bento deck — one self-contained `.bento.html` whose document is JSON — mapping your material onto charts, morph transitions and state slides instead of a wall of bullets. It is adapted, with attribution, from the Bento project's own MIT-licensed skill.
+A fourth Skill, `bento-slides`, joins the Office Productivity group. Ask for a presentation, and the agent authors a real Bento deck: one self-contained `.bento.html` file whose document is JSON, mapping your material onto charts, morph transitions and state slides instead of a wall of bullets. It is adapted, with attribution, from the Bento project's own MIT-licensed skill.
-`agenthub-models` tracks the 0.4.1 upgrade: the new supported-model registry, the config parameters a client may now reject outright, and the Gemini 3.6 / Kimi K3 / GLM-5.2 families with their reasoning-effort knobs.
+`agenthub-models` tracks the 0.4.1 upgrade: the new supported-model registry, the config parameters a client may now reject outright, and the Gemini 3.6, Kimi K3 and GLM-5.2 families with their reasoning-effort settings.
### Sites, docs and tooling
-The docs and landing navbars are now literally the same layout — same container width, same logo block, same right cluster — after drifting apart into two near-identical implementations. The blog gained the **Tech practice** category, pinned posts, and per-post metadata (locale-formatted date, author line, copy-link button). Both READMEs and the landing page now list the built-in Skills where people actually look for them.
+The docs site and the landing page now share one navbar layout, with the same container width, logo block and right-hand cluster, after drifting apart into two near-identical implementations. The blog gained the **Tech practice** category, pinned posts, and per-post metadata: a date formatted for your language, an author line and a copy-link button. Both READMEs and the landing page now list the built-in Skills where people look for them.
+
+The README roadmap gained two items: agent company and templates, and company-level self evolving. The self-improvement example under `examples/` is now two runnable scripts in which a local open-weight model scores itself, edits its own files and re-runs, replacing a fixed illustrative transcript. The server now validates paging and date query parameters instead of trusting them.
+
+## Upgrading
+
+Upgrading is now one command. `penguin update` resolves the newest release, tells you exactly what it is about to do, and upgrades in place with the same mechanism you installed with:
-The README roadmap gained two items — Agent company and templates, and company-level self evolving — and the self-improvement example under `examples/` was reworked into two runnable scripts that let a local open-weight model score itself, edit its own files and re-run, instead of a fixed illustrative transcript. On the hardening side, the server now validates paging and date query parameters instead of trusting them, and two previously uncovered core modules picked up unit tests.
+- For a tarball install, it re-runs the official installer, keeping your install directory and your choice of bundled runtime.
+- For an npm, pnpm, yarn or bun global install, it runs the matching global install.
-Upgrading is now one command. `penguin update` resolves the newest release, tells you exactly what it is about to do, and upgrades in place using the mechanism your install actually came from — re-running the official installer for a tarball install (keeping your install dir and your choice of bundled runtime), or the right global install for an npm/pnpm/yarn/bun one. It refuses to touch a source checkout, and it never touches your data dir. `penguin update --check` reports the versions and changes nothing.
+It refuses to touch a source checkout, and it never touches your data directory. `penguin update --check` reports the versions and changes nothing.
## Get it
@@ -117,4 +156,4 @@ curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/downl
penguin web
```
-Then open the Models page, drop in a Gemini or OpenRouter key, and pick `gemini-3.6-flash`. The full release notes live in [`changelog/0.1.1/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.1).
+Then open the **Models** page, add a Gemini or OpenRouter key, and pick `gemini-3.6-flash`. The full release notes are in [`changelog/0.1.1/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.1).
diff --git a/packages/landing/content/blog/gemini-3-6-in-penguinharness.zh.md b/packages/landing/content/blog/gemini-3-6-in-penguinharness.zh.md
index 6e5281c8..8586cd6a 100644
--- a/packages/landing/content/blog/gemini-3-6-in-penguinharness.zh.md
+++ b/packages/landing/content/blog/gemini-3-6-in-penguinharness.zh.md
@@ -1,25 +1,27 @@
---
-title: PenguinHarness 0.1.1 更新:支持 Gemini 3.6 Flash,更快更好地构建 Agent
+title: PenguinHarness 0.1.1:支持 Gemini 3.6 Flash 与 3.5 Flash-Lite
date: 2026-07-22
category: news
-excerpt: Google 给出的 Gemini 3.6 Flash MLE-Bench 成绩是 63.9%,3.5 Flash 是 49.7%。MLE-Bench 衡量的是机器学习工程能力——Agent 亲手构建、训练、调优一套 ML 系统,而这正是 PenguinHarness 要做的事。该模型今天已在模型目录中,价格还低于它取代的那一代 Flash。本文讲清这个判断,以及 0.1.1 版本的其余更新。
+excerpt: 按 Google 公布的数据,Gemini 3.6 Flash 在 MLE-Bench 上得分 63.9%,3.5 Flash 为 49.7%,价格却更低。PenguinHarness 0.1.1 已把它和 3.5 Flash-Lite 加入模型目录。本文讲清它为什么重要,以及这个版本的其余更新。
---
-Google 在 2026 年 7 月 21 日发布了 [Gemini 3.6 Flash、3.5 Flash-Lite 与 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/)。这次发布里有一个数字,对 PenguinHarness 的意义超过其余全部:**MLE-Bench 63.9%,而 3.5 Flash 是 49.7%**。
+Google 发布 Gemini 3.6 Flash 和 3.5 Flash-Lite 的第二天,PenguinHarness 0.1.1 就把它们加入了模型目录。按 Google 的数据,3.6 Flash 的 MLE-Bench 成绩是 63.9%,3.5 Flash 是 49.7%,而且价格更低。这个版本还把最大输出长度改成按模型设置,修正了 Gemini 的缓存价格,并新增 `penguin update` 命令用于原地升级。
-## 为什么是这个数字
+## Gemini 3.6 Flash 为什么对 PenguinHarness 重要
-MLE-Bench 衡量的是机器学习*工程*能力——Agent 亲手构建、训练、调优一套 ML 系统,而不是回答关于它的问题。Google 自己的说法是,这体现了「ML Research 上的显著提升,见 MLE Bench(63.9% vs. 49.7%)」。这是 14.2 个百分点的提升,是下面那张图中三项百分制基准里幅度最大的一项,并且明显高于同一张图给出的上一代 Pro 级模型 3.1 Pro 的 42.6%。
+Google 在 2026 年 7 月 21 日发布了 [Gemini 3.6 Flash、3.5 Flash-Lite 与 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/)。对 PenguinHarness 来说,这次发布里最重要的是一个数字:**MLE-Bench 63.9%,而 3.5 Flash 是 49.7%**。
-PenguinHarness 存在的意义,就是**让 Agent 构建 Agent——更快、更好、更便宜**。这个产品跑的每一个循环,本质上都是一次小型的机器学习工程:把模型部署起来,交给 Agent 一个任务,用私有 Rubric 打分,读失败原因,调优,重新部署,再测一次。一个在这件事上明显更强、又落在 Flash 价格档的模型,就是迄今最适合这套 Harness 的模型。这是本文的论点;后面是证据,再后面是这个版本的其余更新。
+MLE-Bench 衡量的是机器学习的工程能力:Agent 亲手构建、训练、调优一套 ML 系统,而不是回答关于它的问题。Google 自己的说法是,这体现了「ML Research 上的显著提升,见 MLE Bench(63.9% vs. 49.7%)」。这是 14.2 个百分点的提升,在下面那张图的三项百分制基准里幅度最大,也明显高于同一张图给出的上一代 Pro 级模型 3.1 Pro 的 42.6%。
-有一点先说清楚,且对下文每一个数字都成立:这些都是 **Google 自己的数据、按 Google 自己的评测方法得出**,我们没有独立复现其中任何一项。
+PenguinHarness 存在的意义,就是让 Agent 构建 Agent,更快、更好、更便宜。这个产品跑的每一个循环,本质上都是一次小型的机器学习工程:把模型部署起来,交给 Agent 一个任务,用私有 Rubric 打分,读失败原因,调优,重新部署,再测一次。一个恰好在这件事上明显更强、又落在 Flash 价格档的模型,就是迄今最适合这套 Harness 日常工作的模型。
+
+下文的每个数字都有同一个前提:它们都是 **Google 自己的数据,按 Google 自己的评测方法得出**,我们没有独立复现过其中任何一项。
## 其余的成绩单
![Gemini 3.6 Flash 评测图:DeepSWE v1.1、MLE-Bench、GDPval-AA v2 与 OSWorld-Verified 四项,逐项对比 Gemini 3.1 Pro、3.5 Flash 与 3.6 Flash](/blog-assets/gemini-3-6-flash-evals.webp)
-*图片版权归 Google 所有,转载自其发布博客 [Introducing Gemini 3.6 Flash, 3.5 Flash-Lite, and 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/)(2026 年 7 月 21 日)。图中全部数据与评测方法均出自 Google,而非我们自测。*
+图表出自 Google,转载自 Google 的发布博客 [Introducing Gemini 3.6 Flash, 3.5 Flash-Lite, and 3.5 Flash Cyber](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-6-flash-3-5-flash-lite-3-5-flash-cyber/)(2026 年 7 月 21 日)。图中全部数据与评测方法均出自 Google,而非我们自测。
MLE-Bench 不是孤证。对比 3.5 Flash,Google 给出的数据是:
@@ -30,85 +32,122 @@ MLE-Bench 不是孤证。对比 3.5 Flash,Google 给出的数据是:
| GDPval-AA v2 | 知识工作 | 1349 | 1421 |
| OSWorld-Verified | 计算机操作 | 78.4% | 83.0% |
-另外三行恰好是一个机器学习工程循环真正依赖的能力。长程软件工程决定了 Agent 能不能不反复折腾地改好训练配置、数据集脚本与部署参数——Google 把 DeepSWE 的提升归因于「更高的精确度、更少的多余代码改动和更少的执行循环」,任何看过 Agent 在代码仓库里来回折腾的人都认得这个失败模式。计算机操作现在是 Gemini API 与 Gemini Enterprise 中的内置客户端工具。模型还带上了针对 CBRN 与网络攻击滥用的 Frontier Safety 加固,Google 称其「明显更难被越狱」,同时减少了对正当用途的拒答。
+另外三行恰好是机器学习工程循环所依赖的能力。长程软件工程能力决定了 Agent 修改训练配置、数据集脚本和部署参数时会不会反复折腾。Google 把 DeepSWE 的提升归因于「更高的精确度、更少的多余代码改动和更少的执行循环」。计算机操作现在是 Gemini API 与 Gemini Enterprise 中的内置客户端工具。
+
+模型还带上了增强的 Frontier Safety 防护,针对 CBRN 与网络攻击类滥用。Google 表示,这让它「明显更难被越狱」,同时尽量减少对正当用途的拒答。
-## 「更便宜」这一条:更少 Token、更少步数、更低单价
+## 更少 Token、更少步数、更低单价
-Google 对这次发布的定位,恰好就是 Harness 每天在做的事:「构建生产级 AI Agent 的开发者与客户,需要更高的 Token 效率、更低的延迟和更可靠的表现。」Agent 循环不是一次长补全,而是几十次短往返,每一次都带着工具 Schema、不断增长的对话记录和一份推理预算。单步效率就是全部的成本模型。
+Google 对这次发布的定位,恰好就是这类 Harness 每天在做的事:「构建生产级 AI Agent 的开发者与客户,需要更高的 Token 效率、更低的延迟和更可靠的表现。」Agent 循环不是一次长补全,而是几十次短往返,每一次都带着工具 Schema、不断增长的对话记录和一份推理预算,每一步的效率决定了成本。
-按 Google 的说法,在 Artificial Analysis Index 上 3.6 Flash 比 3.5 Flash **少消耗 17% 的输出 Token**,在 Datacurve 的 DeepSWE 等部分基准上观察到「最高 65%」,并且「完成多步工作流所需的推理步数与工具调用更少」。这种效率提升「同时还配上了低于 3.5 Flash 的价格」:**输入 $1.50 / 百万 Token,输出 $7.50 / 百万 Token**。Google 自己的结论正是这里最要紧的一句——这套组合「降低了每个 Agent 任务的总体成本,让 Agent 的构建与运行更划算」。
+按 Google 的说法,在 Artificial Analysis Index 上,3.6 Flash 比 3.5 Flash **少消耗 17% 的输出 Token**,在 Datacurve 的 DeepSWE 等部分基准上观察到「最高 65%」。它还「完成多步工作流所需的推理步数与工具调用更少」。
-更少的 Token、更少的步数、更低的单价。对于每一轮都要重跑一整套评测集的自我进化循环来说,这三者是叠乘关系。
+这种效率提升「同时还配上了低于 3.5 Flash 的价格」:**输入 $1.50 / 百万 Token,输出 $7.50 / 百万 Token**。用 Google 的话说,这套组合「降低了每个 Agent 任务的总体成本,让 Agent 的构建与运行更划算」。自我进化循环每一轮都要重跑一整套 Benchmark,更少的 Token、更少的步数和更低的单价会叠加起作用。
-## PenguinHarness 里现在能用到什么
+## PenguinHarness 现已支持的模型
-发布一天之后,目录里已经收录了两个公开可用的模型,各有两条接入路径:
+发布一天之后,目录里已经收录了这两个公开可用的模型,各有两条接入路径:
-| 提供方分组 | 模型 ID | 上下文 | 视觉 |
+| 供应商分组 | 模型 ID | 上下文 | 视觉 |
| ------------- | ------------------------------ | --------: | ---- |
| Google Gemini | `gemini-3.6-flash` | 1,048,576 | 支持 |
| Google Gemini | `gemini-3.5-flash-lite` | 1,048,576 | 支持 |
| OpenRouter | `google/gemini-3.6-flash` | 1,048,576 | 支持 |
| OpenRouter | `google/gemini-3.5-flash-lite` | 1,048,576 | 支持 |
-Google 直连的两行由模型 ID 自动路由,只需要一个 `GEMINI_API_KEY`;OpenRouter 的两行已经内联了 OpenAI 客户端类型与网关 base URL,只需要一个 OpenRouter Key。最快的路径是 Web App 的 **Models** 页面:找到那一行,填 Key,结束。命令行则是一条命令:
+Google 直连的两行按模型 ID 自动路由,只需要一个 `GEMINI_API_KEY`。OpenRouter 的两行已经内联了 OpenAI 客户端类型和网关的 base URL,只需要一个 OpenRouter API key。
+
+无论走哪条路径,最快的方式都是 Web App 的**模型仓库**页面:找到那一行,填入 API key 即可。命令行也只要一条命令:
```bash
penguin config model add --provider google --model-id gemini-3.6-flash --api-key <your-key>
penguin config model list
```
-随之落地的还有两处修正。Gemini 的价格现在按厂商真实的缓存命中价记录,而不是把输入价重复填进缓存桶——3.6 Flash 每百万缓存输入 Token $0.15,3.5 Flash-Lite $0.03——费用中心因此不再把缓存密集型开销高估一个数量级。另外 `google/gemini-3.5-flash` 的上下文窗口此前记为 1,000,000,网关与直连端点的真实值都是 1,048,576,现已更正。
+随新模型一起落地的还有两处修正:
+
+- Gemini 的价格现在按厂商真实的缓存命中价记录,不再把输入价重复填进缓存价:3.6 Flash 每百万缓存输入 Token $0.15,3.5 Flash-Lite $0.03。**成本中心**因此不再把缓存密集型开销高估一个数量级。
+- `google/gemini-3.5-flash` 的上下文窗口此前记为 1,000,000,网关与直连端点的真实值都是 1,048,576。
-### 3.5 Flash-Lite:负责扇出的那一半
+### 3.5 Flash-Lite:负责扇出
-目录里的第二个模型,目标是吞吐而不是深度。按 Artificial Analysis 的测量,Gemini 3.5 Flash-Lite 是 3.5 系列中最快的模型,达到 **350 输出 Token/秒**,定价 **输入 $0.30 / 百万 Token、输出 $2.50 / 百万 Token**。Google 把它定位在 Agent 检索、文档处理这类高吞吐场景,并支持配置思考等级——同一个模型既可以压到低延迟低成本跑批量任务,也可以调高思考等级承担多步子 Agent 负载。计算机操作在这里同样是内置工具。
+第二个新模型的目标是吞吐,而不是深度。按 Artificial Analysis 的测量,Gemini 3.5 Flash-Lite 是 3.5 系列中最快的模型,达到 **350 输出 Token/秒**。定价为**输入 $0.30 / 百万 Token,输出 $2.50 / 百万 Token**。
-与上一代 Flash-Lite 相比,Google 给出的数据是:Terminal-Bench 2.1 **54% 对 31%**,长上下文 GDM-MRCR v2 **72.2% 对 60.1%**,GDPval-AA v2 **1140 对 642**。在若干 Agent 与编码评测上它甚至超过 3 Flash——SWE-Bench Pro **54.2% 对 49.6%**,OSWorld-Verified **74.0% 对 65.1%**。
+Google 把它定位在 Agent 检索、文档处理这类高吞吐场景。它的思考等级可以配置,同一个模型既能调低,便宜地跑批量任务,也能调高,承担多步的子 Agent 负载。计算机操作在这里同样是内置工具。
-这非常契合 PenguinHarness 依赖的子 Agent 模式:能力更强的父模型负责规划,便宜且快的模型负责扇出执行。Google 自己的博客展示的也是同一形态——3.5 Flash-Lite「与作为主控 Agent 的 3.6 Flash 协同」批量生成设计方案。
+与上一代 Flash-Lite 相比,Google 给出的数据是:Terminal-Bench 2.1 **54% 对 31%**,长上下文 GDM-MRCR v2 **72.2% 对 60.1%**,GDPval-AA v2 **1140 对 642**。在若干 Agent 与编码评测上,它甚至超过了 3 Flash:SWE-Bench Pro **54.2% 对 49.6%**,OSWorld-Verified **74.0% 对 65.1%**。
-发布中的第三个模型 3.5 Flash Cyber 则刻意不对外开放:Google 表示它将仅通过 CodeMender、以限量试点计划的形式提供给政府与可信合作伙伴。PenguinHarness——以及任何其他工具——都不会有机会把 base URL 指过去。
+这很契合 PenguinHarness 所依赖的子 Agent 模式:能力更强的父模型负责规划,便宜且快的模型负责扇出执行。Google 自己的博客展示的也是这种形态:3.5 Flash-Lite「与担任主控 Agent 的 3.6 Flash 协同」,批量生成设计方案。
+
+发布中的第三个模型 3.5 Flash Cyber 刻意不对外开放。Google 表示,它将仅通过 CodeMender、以限量试点计划的形式提供给政府与可信合作伙伴,所以 PenguinHarness 的目录里没有它。
## 0.1.1 的其余更新
-Gemini 这两行只是一次更大规模目录刷新中的一条,而目录也只是这个版本触及的诸多面之一。
+Gemini 这几行只是一次更大规模目录刷新的一部分,而目录也只是这个版本改动的诸多方面之一。
### 模型与内核
-SDK 升级到 **AgentHub 0.4.1**。这是一次类型兼容的升级,它新增的受支持模型注册表——模型、base URL 与 client 三元组,附带模态、上下文窗口和每百万 Token 价格——成了这次目录比对的权威来源。目录条目从 59 条增加到 70 条:上文两个 Gemini 模型的两条路径,Anthropic 的 Claude Fable 5 与 Claude Sonnet 5,Moonshot 的 Kimi K3,OpenRouter 的 Kimi K2.6、Qwen3.6 35B A3B 与 GLM 5.1,以及 SiliconFlow 上的同样三个。最后三个刻意不带价格:没有任何来源公布它们的费率,而猜一个数字比留空更糟。所有上下文窗口、视觉标记与价格都来自注册表,而不是厂商的宣传页。
+SDK 升级到 **AgentHub 0.4.1**,这是一次类型兼容的升级。它新增的受支持模型注册表列出模型、base URL 与 client 三元组,附带模态、上下文窗口和每百万 Token 价格,成了这次目录刷新的权威来源。所有上下文窗口、视觉标记与价格都取自注册表,而不是厂商的宣传页。目录条目从 57 条增加到 70 条,新增的条目有:
+
+- Gemini 3.6 Flash 与 3.5 Flash-Lite,覆盖上文的两条路径
+- Anthropic 的 Claude Fable 5 与 Claude Sonnet 5
+- Moonshot 的 Kimi K3
+- OpenRouter 的 Kimi K2.6、Qwen3.6 35B A3B 与 GLM 5.1
+- SiliconFlow 上的同样三个
+
+SiliconFlow 的三行刻意不带价格:没有任何来源公布它们的费率,而猜一个数字比留空更糟。
-如果你把 Agent 跑在本地或严格的端点上,有三处修复值得注意:
+如果你把 Agent 跑在本地或严格的端点上,有三处修复与你直接相关:
-- **空工具列表不再发到线上。** 严格的 OpenAI 兼容服务会直接拒绝 `tools: []`——vLLM 会回 `400 … tools must not be an empty array`。Harness 所有不带工具的请求(连通性探测、会话标题生成、视觉描述)此前都会撞上它。现在列表为空时该字段被整个省略。
-- **最大输出 Token 成为模型级设置。** 本地部署的 32k 上下文模型会直接拒绝请求,因为 Agent 级默认值要求 32,000 个输出 Token。Models 页面与 `penguin config model add --max-tokens` 现在支持按模型设置上限,其优先级高于 Agent 默认值,带外请求则取两者中较小的一个。
-- **默认系统提示词加了护栏。** Agent 为了腾出被占端口而杀掉监听进程时,有时杀掉的是 Harness 自己的服务;提示词现在要求:绝不杀死不是自己启动的进程,端口被占就另选一个空闲端口。遇到 401/403 或无效 Key 时,Agent 最多重试一次,随后停止并请用户在对话之外更新 Key——密钥不该出现在聊天记录里。已有 Agent 保留当前提示词,新建的 Agent 才带上这些规则。
+- **空工具列表不再发出。** 严格的 OpenAI 兼容服务会直接拒绝 `tools: []`,vLLM 会返回 `400 … tools must not be an empty array`。Harness 所有不带工具的请求此前都会撞上它:连通性探测、会话标题生成和视觉描述。现在列表为空时,整个字段直接省略。
+- **最大输出长度改为按模型设置。** 本地部署的 32k 上下文模型会直接拒绝请求,因为 Agent 级默认值要求 32,000 个输出 Token。**模型仓库**页面和 `penguin config model add --max-tokens` 现在支持按模型设置上限,优先级高于 Agent 默认值。带外请求取两者中较小的一个。
+- **默认系统提示词加了护栏。** Agent 为了腾出被占用的端口而杀掉监听进程时,有时杀掉的是 Harness 自己的服务。提示词现在要求:绝不杀死不是自己启动的进程,端口被占就另选一个空闲端口。遇到 401、403 或无效 key 错误时,Agent 只重试一次,随后停下,请你在对话之外更新 key,因为密钥不该出现在聊天记录里。已有 Agent 保留当前的提示词,新建的 Agent 才带上这些规则。
-还有两项运行时设置换了形态。思考等级从 Models 页面挪到了对话草稿区、模型选择器旁的紧凑选择器(`low` / `medium` / `high` / `xhigh`),并即时写回 Agent 设置,使发送时创建的会话就用新值。子 Agent 现在继承父会话已解析的 `(provider, model_id)` 二元组与生效的思考等级,不再回落到 Project 默认模型;工具调用里显式给出的完整二元组仍然优先。
+还有两项运行时设置换了形态:
+
+- **思考等级**从**模型仓库**页面挪到了对话草稿区模型选择器旁的紧凑选择器(`low` / `medium` / `high` / `xhigh`),并写回 Agent 设置,发送时创建的会话就会使用它。
+- 子 Agent 现在继承父会话已解析的 `(provider, model_id)` 二元组和生效的思考等级,不再回落到 Project 默认模型。工具调用里显式给出的二元组仍然优先。
### Web App
-聊天侧边栏默认**按 Workspace 分组**:以目录名作为标签、按最新会话排序,自动创建的临时 Workspace 收敛成单个分组而不是一个会话一个分组。分组可以置顶,折叠状态按 Project 持久化,子 Agent 与定时任务创建的会话进入各自的文件夹,每个分组按页加载而不再一次拉取全部列表。按 Agent 分组仍然只差一次切换。
+侧栏里的会话列表现在默认按 Workspace 分组。分组以目录名为标签,按最新会话排序,自动创建的临时 Workspace 合并为一个分组,不再一个会话一个分组。分组可以置顶,折叠状态按 Project 保存。子 Agent 和定时任务创建的会话会进入各自的文件夹,每个分组按需加载更多会话,不再一次拉取不限数量的列表。按 Agent 分组仍然只差一次切换。
+
+模型下拉框现在优先列出已配置 key 的模型,其余的点一下就能展开。收起后的侧栏变成完整的八项导航栏,带中英双语悬浮提示,此前它完全没有 Benchmark 入口。自定义供应商分组与 Agent 改用首字母头像,底色由 id 派生,深浅两种主题下都满足 WCAG AA 对比度,不同分组里的同名模型也就能分辨了。
+
+聊天渲染也做了一轮打磨:
+
+- 链接在新标签页打开。
+- 长 URL 与行内代码在容器边缘换行,同时不会把中文段落里的英文单词拦腰截断。
+- 宽表格在消息内部横向滚动,不再把页面撑宽。
+- 展开的子 Agent 对话渲染在工具调用自身输出的下方。
+- 三个此前在移动端最多溢出视口 143px 的下拉面板,现在留在视口内。
+
+**成本中心**的每日 Token 提示气泡会跟随指针,并显示缓存命中率。复制消息时生成的任务统计行此前是硬编码的中文,现在同样走词典。
+
+### Skill
+
+AI 应用开发分组新增三个 Skill:`vllm`、`ollama` 与 `llamafactory`。有了它们,Agent 不只是调用模型,还能把自己依赖的模型部署起来、调优出来。两个部署 Skill 共用同一套引导流程:先问要部署哪个模型,再问你偏好哪个引擎,然后部署、验证,最后用 CLI 注册端点。
-模型下拉框现在优先列出真正配置了 Key 的模型,其余的收在下面一行。折叠后的侧边栏变成了完整的八项导航栏,带中英双语悬浮提示(Benchmark 此前完全缺失)。自建模型分组与 Agent 改用首字母头像——底色由名称派生,深浅色模式下都满足 WCAG AA 对比度——同名模型跨分组终于能分辨了。
+`penguin-cli` Skill(现为 v5)与 `penguin-sdk` 承载了部署 Skill 所依赖的硬性规则:给 Penguin 自身配置模型用默认数据根目录,而为开发中的应用配置模型,必须写进那个应用自己的项目目录。我们另有一篇[实践文章](/blog/natural-language-training-loop),讲 Agent 同时握有这三个 Skill 之后会发生什么变化:你不再敲命令,只描述你要的结果。
-聊天渲染也做了一轮:链接在新标签页打开;长 URL 与行内代码在容器边缘换行,同时不会把中文段落里的英文单词拦腰截断;宽表格在消息内部横向滚动而不是把页面撑宽;展开的子 Agent 对话渲染在工具调用自身输出的下方;三个此前在移动端最多溢出 143px 的下拉面板现在留在视口内。费用中心的每日 Token 提示气泡跟随指针并显示缓存命中率;复制消息时生成的任务统计行此前是硬编码中文,现在同样走词典。
+第四个 Skill `bento-slides` 进入办公效率分组。让 Agent 做演示文稿,它会产出一份真正的 Bento 幻灯片:一个自包含的 `.bento.html` 文件,文档本身就是 JSON。它把你的素材映射到图表、morph 转场和状态页,而不是堆一屏要点。这个 Skill 改编自 Bento 项目自己的 MIT 许可 Skill,并标注了出处。
-### 技能
+`agenthub-models` 同步了 0.4.1 的变化:新的受支持模型注册表、客户端现在可能直接拒绝的配置参数,以及 Gemini 3.6、Kimi K3 和 GLM-5.2 系列和它们的推理强度设置。
-AI 应用开发分组新增三个技能——**vllm**、**ollama** 与 **llamafactory**——让 Agent 不只是调用模型,还能把自己依赖的模型部署起来、调优出来。两个部署技能共享同一套引导流程:先问要部署哪个模型、再问用户偏好哪个引擎,然后部署、验证,最后用 CLI 注册端点。`penguin-cli`(现为 v5)与 `penguin-sdk` 承载了它们所依赖的硬性规则:给 Penguin 自身配置模型用默认数据根目录,而为在开发的 AI 应用配置模型必须写进该应用自己的项目目录。我们另有一篇[实践文章](/blog/natural-language-training-loop)讲当 Agent 同时握有这三个技能之后会发生什么——你不再敲命令,只描述你要的结果。
+### 站点、文档与工具
-第四个技能 **bento-slides** 进入办公效率分组:让 Agent 做演示文稿,它会真正产出一份 Bento 幻灯片——一个自包含的 `.bento.html`,文档本身就是 JSON——并把你的素材映射到图表、morph 转场与状态页,而不是堆一屏要点。它改编自 Bento 项目自己的 MIT 许可技能,并在正文中标注了出处。
+文档站和官网的导航栏此前逐渐分化成两份几乎相同的实现,现在共用同一套布局:同样的容器宽度、同样的 Logo 区块、同样的右侧按钮组。博客新增了**技术实践**分类、置顶文章,以及文章元信息:按语言格式化的日期、作者行和复制链接按钮。两份 README 与官网首页也在读者真正会去找的位置列出了内置 Skill。
-`agenthub-models` 同步了 0.4.1:新的受支持模型注册表、客户端现在可能直接拒绝的配置参数,以及 Gemini 3.6 / Kimi K3 / GLM-5.2 系列及其推理强度旋钮。
+README 路线图新增两项:Agent company and templates,以及 company-level self evolving。`examples/` 下的自我进化示例重写成两个可运行脚本,让本地开放权重模型给自己打分、修改自己的文件并重跑,而不再是一段固定的示意记录。服务端现在会校验分页与日期查询参数,不再照单全收。
-### 站点、文档与工程
+## 升级
-文档站与官网的导航栏现在是同一套布局——同样的容器宽度、同样的 Logo 区块、同样的右侧集群——此前它们已经漂移成两份近乎相同的实现。博客新增 **Tech practice** 分类、置顶文章,以及文章元信息(按语言格式化的日期、作者行、复制链接按钮)。两份 README 与官网首页也在人们真正会去找的位置列出了内置技能。
+升级现在只需一条命令。`penguin update` 会查出最新版本,先说明接下来要做什么,再按你当初的安装方式原地升级:
-README 路线图新增两项——Agent company and templates,以及 company-level self evolving;`examples/` 下的自我进化示例重写成两个可运行脚本,让本地开源权重模型真正给自己打分、改自己的文件并重跑,而不再是一段固定的示意记录。加固方面,服务端现在校验分页与日期查询参数而不是照单全收,两个此前没有直接测试覆盖的内核模块补上了单元测试。
+- tarball 安装:重新执行官方安装脚本,保留原安装目录以及是否内置运行时的选择。
+- npm、pnpm、yarn 或 bun 全局安装:用对应的包管理器重新全局安装。
-升级现在只需一条命令。`penguin update` 会解析最新版本,先把将要做的事讲清楚,再按你当初的安装方式原地升级——tarball 安装就重新执行官方安装脚本(保留原安装目录与是否内置运行时),npm/pnpm/yarn/bun 全局安装就用对应的包管理器。它拒绝改动源码检出,也从不碰你的数据目录。`penguin update --check` 只报告版本,不做任何修改。
+源码检出的安装它会直接拒绝,你的数据目录它也从不触碰。`penguin update --check` 只报告版本,不做任何修改。
## 获取方式
@@ -117,4 +156,4 @@ curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/downl
penguin web
```
-然后打开 Models 页面,填入 Gemini 或 OpenRouter 的 Key,选择 `gemini-3.6-flash` 即可。完整的发布说明见 [`changelog/0.1.1/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.1)。
+然后打开**模型仓库**页面,填入 Gemini 或 OpenRouter 的 API key,选择 `gemini-3.6-flash` 即可。完整的发布说明见 [`changelog/0.1.1/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.1)。
diff --git a/packages/landing/content/blog/introducing-penguinharness.en.md b/packages/landing/content/blog/introducing-penguinharness.en.md
index da6acb46..68417e82 100644
--- a/packages/landing/content/blog/introducing-penguinharness.en.md
+++ b/packages/landing/content/blog/introducing-penguinharness.en.md
@@ -3,30 +3,32 @@ title: "Introducing PenguinHarness: agents that build agents"
date: 2026-07-17
category: news
pinned: true
-excerpt: We proved agents can self-evolve in our GDPevo Benchmark — now we are bringing that capability to everyone. The first open-source harness with recursive self-improvement covers everything from one-sentence agent construction to continuous self-evolution.
+excerpt: Our GDPevo Benchmark showed that agents can evolve themselves. PenguinHarness brings that to everyone as an open-source harness with recursive self-improvement, covering everything from building an agent in one sentence to improving it continuously.
---
-Today we are releasing **PenguinHarness** — an open-source harness built for constructing and evolving agents: a zero-code Harness CLI and Web UI, connected to 1000+ models. The story it tells fits in one line:
+> Written for PenguinHarness 0.1.0. Later releases may differ in some details.
+
+Today we are releasing **PenguinHarness**, an open-source harness for building and evolving agents. It gives you a zero-code CLI and Web App, connected to 1000+ models. The idea behind it fits in one line:
> With LangChain, you build agents by hand — at 1× speed. With PenguinHarness, agents build agents — at 100×.
-## From GDPevo to PenguinHarness: why we built this
+## Why we built PenguinHarness
-Before PenguinHarness, our team published the [GDPevo Benchmark](https://prism-shadow.github.io/GDPevo/). In GDPevo we systematically verified one thing: **agents can self-evolve** — an Agent can score its own performance, find where the points were lost, rewrite its own prompts and Skills, and climb version after version.
+Before PenguinHarness, our team published the [GDPevo Benchmark](https://prism-shadow.github.io/GDPevo/). In GDPevo we systematically verified one thing: **agents can self-evolve**. An agent can score its own performance, find where it lost points, rewrite its own prompts and Skills, and score higher with each version.
-With the capability proven, the question became: how does everyone get to use it? Self-evolution should not stay a curve in a paper — it should be infrastructure that works out of the box on every developer's desk. **Bringing an efficient self-improving harness to everyone is why we built PenguinHarness** — and it is right there in the name: Efficient Self-Improving Harness for Everyone.
+With that proven, the question became how everyone gets to use it. Self-evolution should not stay a curve in a paper; it should be infrastructure that works out of the box for every developer. Bringing an efficient self-improving harness to everyone is why we built PenguinHarness, and the goal is in the name: Efficient Self-Improving Harness for Everyone.
-## Why PenguinHarness
+## Better on complex tasks, at lower cost
-Three reasons, in deliberate order — from task quality, to how agents get built, to how they keep improving.
+PenguinHarness uses a deliberately minimal toolset over clean low-level interfaces, so it makes fewer tool calls and spends fewer Tokens. It is tuned in depth for open models such as DeepSeek.
-### 1. Better on complex tasks, at lower cost
+We compared it head to head with Claude Code and OpenAI Codex on two suites. Each harness runs the model it is normally paired with, so the comparison shows the products as people actually use them.
-A deliberately minimal toolset over clean low-level interfaces: fewer tool calls, fewer Tokens, deeply tuned for open models like DeepSeek. Each harness runs the model it is normally paired with — the comparison is between the products as people actually use them — head-to-head on two suites:
+![Benchmark results: PenguinHarness leads the data-analysis suite and ties OpenAI Codex on coding, at a small fraction of either rival's cost](/blog-assets/benchmark-light.svg)
-![Benchmark: PenguinHarness leads the data-analysis suite and ties OpenAI Codex on coding, at a small fraction of both rivals' cost](/blog-assets/benchmark-light.svg)
+### Complex data analysis
-Complex data analysis (15 tasks, single run; PenguinHarness and Codex at thinking xhigh, Claude Code at max):
+15 tasks, one run each. PenguinHarness and OpenAI Codex ran at thinking level `xhigh`, Claude Code at `max`.
| Framework | Model | Accuracy (%) | Tokens (M) | Cost ($) |
| -------------- | --------------- | -----------: | ---------: | -------: |
@@ -34,7 +36,9 @@ Complex data analysis (15 tasks, single run; PenguinHarness and Codex at thinkin
| Claude Code | Claude Opus 4.8 | 53.33 | 22.20 | 38.48 |
| OpenAI Codex | GPT-5.5 | 53.33 | 13.72 | 19.41 |
-Coding tasks (40 tasks × 2 runs; accuracy is over all 80 outcomes):
+### Coding
+
+40 tasks × 2 runs; accuracy is over all 80 outcomes.
| Framework | Model | Accuracy (%) | Tokens (M) | Cost ($) |
| -------------- | --------------- | -----------: | ---------: | -------: |
@@ -42,37 +46,45 @@ Coding tasks (40 tasks × 2 runs; accuracy is over all 80 outcomes):
| Claude Code | Claude Opus 4.8 | 86.25 | 151.61 | 146.97 |
| OpenAI Codex | GPT-5.5 | 71.25 | 251.20 | 220.08 |
-Tokens and cost are suite totals, not per-run means. On data analysis we take the highest accuracy of the three — 66.67% against 53.33% for both — while spending 1/35 of what Codex spent and 1/70 of Claude Code's. On coding we tie Codex at 71.25% and trail Claude Code's 86.25%, but the whole suite cost us $3.81 against their $220.08 and $146.97: comparable work, one to two orders of magnitude apart on the bill.
+Tokens and cost are totals for the whole suite, not per-run means. On data analysis, PenguinHarness has the highest accuracy of the three, 66.67% against 53.33% for both others, while spending 1/35 of what Codex spent and 1/70 of what Claude Code spent. On coding, it ties Codex at 71.25% and trails Claude Code's 86.25%, but the whole suite cost $3.81, against $220.08 for Codex and $146.97 for Claude Code. The work is comparable, and the bills are one to two orders of magnitude apart.
-### 2. One sentence, and an Agent builds your Agent app
+## Build an agent app from one sentence
-Type one sentence, and an Agent builds the complete Agent application for you — scaffold, code, and run instructions, end to end:
+Type one sentence, and an agent builds the complete agent application for you, end to end: scaffold, code and run instructions. For example:
```text
Collect the docs from https://github.com/ericbuess/claude-code-docs and build a RAG app that answers Claude Code questions as a configuration expert, citing its sources.
```
-And this is the finished product — a docs expert with retrieval, cited sources that link to the original files, and example questions built in:
+The finished product is a docs expert with retrieval, cited sources that link to the original files, and built-in example questions:
![The generated RAG app: a Claude Code docs expert answering with cited, clickable sources and example questions](/blog-assets/rag-app-en-light.webp)
-**And generating this entire RAG app burned just $0.02 (¥0.2) of tokens — on DeepSeek V4 Pro.**
+Generating the entire RAG app used $0.02 (¥0.2) of Tokens on DeepSeek V4 Pro.
+
+## Self-evolution: better with use
-### 3. Self-evolution: it gets stronger with use
+With the PenguinHarness Skills, an agent evaluates and optimizes itself. In each round:
-With PenguinHarness Skills, an Agent evaluates and optimizes itself: the Optimizer orchestrates multiple Evaluators to score in parallel, uses the scores and run traces to find where points were lost, and upgrades the Agent from version N to N+1 — with a snapshot before every round, and every request replayable in the Trace view. A self-evolution demo video is coming soon.
+1. The Optimizer runs several Evaluators in parallel to score the agent.
+2. It uses the scores and the run Traces to find where points were lost.
+3. It upgrades the agent from version N to N+1.
+
+A snapshot is taken before every round, and every request can be replayed on the **Trajectory** page. A demo video of self-evolution is coming soon.
## Evolution within bounds, security first
-The biggest worry about self-evolution is losing control. PenguinHarness answers with a contract (CONTRACT.md):
+The biggest worry about self-evolution is losing control. PenguinHarness answers it with a contract, CONTRACT.md:
-- Evolution is strictly confined to Workspace and Skills — the harness core security boundary is never modified;
-- Tool calls require approval first, and every approval leaves an audit record;
-- Risky changes are preceded by version snapshots, so any round of evolution can be rolled back;
-- Fully open source and locally deployed — data never leaves your machine, meeting enterprise data-security requirements.
+- Evolution is strictly confined to the Workspace and Skills. The harness core, which is the security boundary, is never modified.
+- Tool calls require approval first, and every approval leaves an audit record.
+- A version snapshot is taken before any risky change, so any round of evolution can be rolled back.
+- PenguinHarness is fully open source and deployed locally, so your data stays on your machine, apart from the requests sent to the model provider you configure. This meets enterprise data-security requirements.
## Supported models
+PenguinHarness ships with presets for these models:
+
| Model | Providers |
| ---------------- | -------------------------------------------------------------------------------- |
| DeepSeek V4 | DeepSeek, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan |
@@ -84,33 +96,31 @@ The biggest worry about self-evolution is losing control. PenguinHarness answers
| Gemini 3.5 Flash | Google Gemini, OpenRouter |
| Claude Opus 4.8 | Anthropic, OpenRouter |
-Any OpenAI-protocol endpoint is supported: pick a preset above, or point a custom endpoint at any of the 1000+ online and local models.
+Any OpenAI-protocol endpoint works too: pick a preset above, or point a custom endpoint at any of the 1000+ online and local models.
-## How to use it
-
-Install with one command (Linux / macOS, x64 / arm64, bundled Node runtime), then launch the Web UI:
+## What's next
-```bash
-curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # opens http://127.0.0.1:7364 (first login: admin, initial password printed on first start)
-```
+- Public release of the benchmark suite
+- A desktop app
+- Windows support
-Open the Models page, paste an API key under the DeepSeek or OpenRouter group and set it as default; then head back to Chat and hand the Agent its first task — e.g. "Analyze data.csv and summarize quarterly sales".
+## Join the community
-## What's next
+A self-improving harness needs a community that improves with it. Come discuss, request features and contribute; opening your first issue is a good way to start.
-- Public release of the benchmark suite;
-- A desktop app;
-- Windows support;
-- More to come.
+- [Discord](https://discord.gg/eFHKqqcU3D): chat with us and other developers in real time.
+- [X (Twitter)](https://x.com/code_hiyouga): follow the latest updates.
+- [WeChat group](https://github.com/Prism-Shadow/penguin-harness-community/blob/main/wechat/group.jpg): discussions in the Chinese community.
+- [GitHub](https://github.com/Prism-Shadow/penguin-harness): stars, issues and pull requests are all welcome.
-## Join the community and build with us
+## Get started
-A self-improving harness needs a community that improves with it. Come discuss, request, and contribute — your first Issue is the best way to start:
+1. Install PenguinHarness with one command, then start the Web App. The installer supports Linux and macOS on x64 and arm64, and bundles its own Node runtime.
-- [Discord](https://discord.gg/eFHKqqcU3D): chat with us and other developers in real time;
-- [X (Twitter)](https://x.com/code_hiyouga): follow the latest updates;
-- [WeChat group](https://github.com/Prism-Shadow/penguin-harness-community/blob/main/wechat/group.jpg): Chinese community discussions;
-- [GitHub](https://github.com/Prism-Shadow/penguin-harness): stars, Issues, and PRs all welcome.
+ ```bash
+ curl -fsSL https://penguin.ooo/install.sh | sh
+ penguin web # opens http://127.0.0.1:7364 (first login: admin / penguin-2026, shown on the login page)
+ ```
-Self-evolving agent infrastructure, for everyone — starting today.
+2. Open the **Models** page, add an API key to the DeepSeek or OpenRouter group, and set one of its models as the default.
+3. Go back to **Chat** and give the agent its first task, for example "Analyze data.csv and summarize quarterly sales".
diff --git a/packages/landing/content/blog/introducing-penguinharness.zh.md b/packages/landing/content/blog/introducing-penguinharness.zh.md
index edf27d52..d3ff20a1 100644
--- a/packages/landing/content/blog/introducing-penguinharness.zh.md
+++ b/packages/landing/content/blog/introducing-penguinharness.zh.md
@@ -3,30 +3,32 @@ title: PenguinHarness 正式发布:让 Agent 为你构建 Agent
date: 2026-07-17
category: news
pinned: true
-excerpt: 我们在 GDPevo Benchmark 中验证了 Agent 自我进化的能力,现在把它带给所有人——首个支持递归自我进化的开源 Harness 正式发布,从一句话构建 Agent 到持续自我进化,一套基础设施全部覆盖。
+excerpt: 我们在 GDPevo Benchmark 中验证了 Agent 可以自我进化,现在把这项能力带给所有人:一个支持递归自我进化的开源 Harness,从一句话构建 Agent,到持续自我进化,全部覆盖。
---
-今天,我们正式发布 **PenguinHarness**——一个为构建与进化 Agent 而生的开源 Harness:零代码的 Harness CLI 与 Web UI,连接 1000+ 模型。它要讲的故事只有一句话:
+> 本文基于 PenguinHarness 0.1.0 撰写,之后的版本在部分细节上可能有所不同。
+
+今天,我们正式发布 **PenguinHarness**,一个用于构建和进化 Agent 的开源 Harness,提供零代码的 CLI 与 Web App,可以连接 1000+ 模型。背后的理念一句话就能说清:
> 使用 LangChain,以 1 倍速度人工构建 Agent;使用 PenguinHarness,以 100 倍速度用 Agent 构建 Agent。
-## 从 GDPevo 到 PenguinHarness:我们的初心
+## 我们为什么做 PenguinHarness
-在 PenguinHarness 之前,我们团队发布了 [GDPevo Benchmark](https://prism-shadow.github.io/GDPevo/)。在 GDPevo 中,我们系统性地验证了一件事:**Agent 可以自我进化**——让 Agent 评估自己的表现、定位失分原因、改写自己的提示词与技能,分数随版本一路上升。
+在 PenguinHarness 之前,我们团队发布了 [GDPevo Benchmark](https://prism-shadow.github.io/GDPevo/)。在 GDPevo 中,我们系统地验证了一件事:**Agent 可以自我进化**。Agent 能给自己的表现打分,找出失分的地方,改写自己的提示词和 Skill,分数随版本一路上升。
-能力验证了,问题就变成了:怎么让每个人都用上它?自我进化不该只是论文里的曲线,而应该是每个开发者桌面上开箱即用的基础设施。**让每个人都能使用 Efficient Self-Improving Harness,这就是我们构建 PenguinHarness 的初心**——它也因此得名:Efficient Self-Improving Harness for Everyone.
+能力验证了,问题就变成怎么让每个人都用上它。自我进化不该只是论文里的一条曲线,而应该是每个开发者开箱即用的基础设施。让每个人都用上高效的自我进化 Harness,就是我们做 PenguinHarness 的原因,这个目标也写在名字里:Efficient Self-Improving Harness for Everyone。
-## 为什么是 PenguinHarness
+## 复杂任务表现更好,成本更低
-三个递进的理由——从任务效果,到构建方式,再到进化能力。
+PenguinHarness 在干净的底层接口上刻意只提供一套精简的工具集,所以工具调用更少,Token 消耗也更少。它还针对 DeepSeek 等开放模型做了深度适配。
-### 1. 复杂任务表现更好,成本更低
+我们在两套题库上把它和 Claude Code、OpenAI Codex 正面对比。每个 Harness 都搭配它平时常用的模型,比的是大家实际会怎么用。
-刻意精简的工具集配合干净的底层接口:更少的工具调用、更少的 Token,对 DeepSeek 等开放模型深度适配。每个产品搭配它常用的模型——比的是大家实际会怎么用——在两套题库上正面对比:
+![Benchmark 结果:PenguinHarness 在数据分析题库上准确率最高,编程题库与 OpenAI Codex 持平,成本只是两个对手的零头](/blog-assets/benchmark-light.svg)
-![Benchmark:PenguinHarness 在数据分析题库准确率最高、编程题库与 OpenAI Codex 持平,成本仅为两者的零头](/blog-assets/benchmark-light.svg)
+### 复杂数据分析
-复杂数据分析(15 题,单次运行;PenguinHarness 与 Codex 为 thinking xhigh,Claude Code 为 max):
+15 题,每题运行一次。PenguinHarness 与 OpenAI Codex 的思考等级为 `xhigh`,Claude Code 为 `max`。
| 实验框架 | 模型名称 | 准确率(%) | Token 用量(M) | 成本($) |
| -------------- | --------------- | ----------: | --------------: | --------: |
@@ -34,7 +36,9 @@ excerpt: 我们在 GDPevo Benchmark 中验证了 Agent 自我进化的能力,
| Claude Code | Claude Opus 4.8 | 53.33 | 22.20 | 38.48 |
| OpenAI Codex | GPT-5.5 | 53.33 | 13.72 | 19.41 |
-代码任务(40 题 × 2 次运行,准确率取全部 80 次结果):
+### 编程
+
+40 题 × 2 次运行,准确率按全部 80 次结果计算。
| 实验框架 | 模型名称 | 准确率(%) | Token 用量(M) | 成本($) |
| -------------- | --------------- | ----------: | --------------: | --------: |
@@ -42,75 +46,81 @@ excerpt: 我们在 GDPevo Benchmark 中验证了 Agent 自我进化的能力,
| Claude Code | Claude Opus 4.8 | 86.25 | 151.61 | 146.97 |
| OpenAI Codex | GPT-5.5 | 71.25 | 251.20 | 220.08 |
-Token 与成本均为全套题目合计,不是单次均值。数据分析套件我们准确率最高——66.67% 对另两者的 53.33%——花的钱是 Codex 的 1/35、Claude Code 的 1/70;代码套件与 Codex 同为 71.25%、低于 Claude Code 的 86.25%,但整套题目只花了 $3.81,对方分别是 $220.08 与 $146.97:活干得差不多,账单差出一到两个数量级。
+Token 与成本都是整套题库的合计,不是单次运行的均值。数据分析题库上,PenguinHarness 的准确率在三者中最高,为 66.67%,另外两家都是 53.33%,花的钱却只有 Codex 的 1/35、Claude Code 的 1/70。编程题库上,它与 Codex 同为 71.25%,低于 Claude Code 的 86.25%,但整套题只花了 $3.81,Codex 和 Claude Code 分别花了 $220.08 和 $146.97。活干得差不多,账单差出一到两个数量级。
-### 2. 一句话,让 Agent 构建 Agent 应用
+## 一句话构建 Agent 应用
-输入一句话,Agent 为你构建完整的 Agent 应用——脚手架、代码、运行说明,一步到位:
+输入一句话,Agent 就能为你从头到尾构建一个完整的 Agent 应用,包括脚手架、代码和运行说明。例如:
```text
收集 https://github.com/ericbuess/claude-code-docs 的文档,做一个化身 Claude Code 配置专家、回答带来源引用的 RAG 问答应用。
```
-这是做出来的成品——一个文档专家:检索增强、引用可点击直达原文、内置示例问题:
+做出来的成品是一个文档专家:检索增强,引用可点击直达原文,还内置了示例问题。
+
+![生成的 RAG 应用:Claude Code 配置专家,回答带可点击的来源引用与示例问题](/blog-assets/rag-app-zh-light.webp)
-![生成的 RAG 应用成品:Claude Code 配置专家,回答带可点击的来源引用与示例问题](/blog-assets/rag-app-zh-light.webp)
+生成整个 RAG 应用消耗了 0.2 元($0.02)的 Token,使用的模型是 DeepSeek V4 Pro。
-**而生成整个 RAG 应用,仅消耗了 0.2 元($0.02)的 token——使用 DeepSeek V4 Pro 模型。**
+## 自我进化:越用越强
-### 3. 自进化,越用越强
+借助 PenguinHarness 的 Skill,Agent 自己评估、自己优化。每一轮:
-借助 PenguinHarness 技能库,Agent 自己评估、自己优化:Optimizer 组织多个 Evaluator 并行打分,依据分数与运行轨迹定位失分原因,把 Agent 从版本 N 优化到版本 N+1——每轮之前自动快照,每个请求都可在轨迹观测中回放。自进化演示视频即将上线。
+1. Optimizer 并行调度多个 Evaluator,给 Agent 打分。
+2. Optimizer 根据分数和运行 Trace,定位失分原因。
+3. Optimizer 把 Agent 从版本 N 优化到版本 N+1。
+
+每轮开始前都会自动快照,每个请求都能在**轨迹观测**页面回放。自我进化的演示视频即将上线。
## 进化有界,安全先行
-自我进化最大的疑虑是失控。PenguinHarness 用一份契约(CONTRACT.md)回答这个问题:
+自我进化最大的顾虑是失控。PenguinHarness 用一份契约(CONTRACT.md)回答这个问题:
-- 进化严格限制在 Workspace 与 Skill 之内,不修改 Harness 核心安全边界;
-- 工具调用先经批准,每次批准皆留审计;
-- 风险修改之前先留版本快照,任何一次进化都可回退;
-- 完全开源、本地部署,数据不出域,满足企业级数据安全。
+- 进化严格限制在 Workspace 与 Skill 之内。Harness 核心是安全边界,从不修改。
+- 工具调用先经审批,每次审批都留有审计记录。
+- 有风险的修改之前先留版本快照,任何一轮进化都可以回滚。
+- PenguinHarness 完全开源、本地部署。除了发往你配置的模型供应商的请求,数据都留在你的机器上,满足企业级数据安全要求。
## 支持的模型
+PenguinHarness 为以下模型提供了预置配置:
+
| 模型 | 可用供应商 |
| ---------------- | -------------------------------------------------------------------------------- |
-| DeepSeek V4 | DeepSeek, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan |
-| Kimi K3 | Moonshot AI, OpenRouter, Qwen Pay-As-You-Go |
-| GLM 5.2 | Z.AI, OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go |
+| DeepSeek V4 | DeepSeek、OpenRouter、Fireworks AI、SiliconFlow、Qwen Token Plan |
+| Kimi K3 | Moonshot AI、OpenRouter、Qwen Pay-As-You-Go |
+| GLM 5.2 | Z.AI、OpenRouter、Fireworks AI、SiliconFlow、Qwen Token Plan、Qwen Pay-As-You-Go |
| Hunyuan 3 | OpenRouter |
| Qwen 3.8 Max | Qwen Token Plan(预览) |
-| GPT 5.5 | OpenAI, OpenRouter |
-| Gemini 3.5 Flash | Google Gemini, OpenRouter |
-| Claude Opus 4.8 | Anthropic, OpenRouter |
+| GPT 5.5 | OpenAI、OpenRouter |
+| Gemini 3.5 Flash | Google Gemini、OpenRouter |
+| Claude Opus 4.8 | Anthropic、OpenRouter |
-只要是 OpenAI 协议的端点都可以接入:从上表选择预置,或用自定义端点连接 1000+ 在线与本地模型。
+任何 OpenAI 协议的端点都能接入:从上表选择预置,或者用自定义端点连接 1000+ 在线与本地模型中的任意一个。
-## 如何使用
-
-一行命令安装(Linux / macOS,x64 / arm64,内嵌 Node 运行时),然后启动 Web 界面:
+## 发展计划
-```bash
-curl -fsSL https://penguin.ooo/install.sh | sh
-penguin web # 打开 http://127.0.0.1:7364(首次登录:admin,初始密码见首次启动输出)
-```
+- Benchmark 套件正式公开
+- 推出桌面应用
+- 支持 Windows
-进入「模型仓库」页,在 DeepSeek 或 OpenRouter 分组里粘贴 API key 并设为默认;回到对话页,把第一个任务交给 Agent——例如「分析 data.csv,输出各季度销售额汇总」。
+## 加入社区
-## 发展计划
+会自我进化的 Harness,也需要一个一起进化的社区。欢迎加入讨论、提出需求、贡献代码,提交你的第一个 Issue 就是很好的开始。
-- Benchmark 套件正式发布;
-- 推出桌面端(Desktop)应用;
-- 支持 Windows 系统;
-- 更多规划,敬请期待。
+- [Discord](https://discord.gg/eFHKqqcU3D):与我们和其他开发者实时交流。
+- [X(Twitter)](https://x.com/code_hiyouga):关注最新动态。
+- [微信群](https://github.com/Prism-Shadow/penguin-harness-community/blob/main/wechat/group.jpg):中文社区讨论。
+- [GitHub](https://github.com/Prism-Shadow/penguin-harness):Star、Issue 和 PR 都欢迎。
-## 加入社区,一起共建
+## 快速开始
-自我进化的 Harness,也需要一个不断进化的社区。欢迎加入讨论、提出需求、贡献代码——你的第一个 Issue 就是最好的开始:
+1. 用一条命令安装 PenguinHarness,然后启动 Web App。安装脚本支持 Linux 与 macOS(x64 / arm64),内嵌 Node 运行时。
-- [Discord](https://discord.gg/eFHKqqcU3D):与我们和其他开发者实时交流;
-- [X(Twitter)](https://x.com/code_hiyouga):关注最新动态;
-- [微信群](https://github.com/Prism-Shadow/penguin-harness-community/blob/main/wechat/group.jpg):中文社区讨论;
-- [GitHub](https://github.com/Prism-Shadow/penguin-harness):Star、Issue 与 PR 都欢迎。
+ ```bash
+ curl -fsSL https://penguin.ooo/install.sh | sh
+ penguin web # 打开 http://127.0.0.1:7364(首次登录:admin / penguin-2026,登录页上也有提示)
+ ```
-让每个人都用上会自我进化的 Agent 基础设施——从今天开始。
+2. 打开**模型仓库**页面,在 DeepSeek 或 OpenRouter 分组里填入 API key,把组里的一个模型设为默认。
+3. 回到**对话**页面,把第一个任务交给 Agent,例如「分析 data.csv,输出各季度销售额汇总」。
diff --git a/packages/landing/content/blog/july-2026-updates.en.md b/packages/landing/content/blog/july-2026-updates.en.md
index 10053dcd..59ced707 100644
--- a/packages/landing/content/blog/july-2026-updates.en.md
+++ b/packages/landing/content/blog/july-2026-updates.en.md
@@ -1,30 +1,32 @@
---
-title: "July 2026 updates: scheduled tasks, Agent snapshots and a stronger evaluation center"
+title: "July 2026 updates: scheduled tasks, Agent State snapshots and Benchmark scoreboards"
date: 2026-07-17
category: changelog
-excerpt: Scheduled tasks, Agent State snapshots with export/import, benchmark scoreboards, the model identity principle and one-line install have all landed on main.
+excerpt: Scheduled tasks, Agent State snapshots with export and import, Benchmark scoreboards, the model identity principle and a one-line install have landed on main.
---
-This month a batch of updates directly serving "stable evolution" landed on main. Highlights below.
+> Written for PenguinHarness 0.0.1. Later releases may differ in some details.
-## Scheduled tasks & Agent State snapshots
+This month, a batch of updates aimed at stable self-evolution landed on main. Agents can now run on a schedule, Agent State is snapshotted before risky changes, and the Evaluation Center charts Benchmark results per model. The highlights are below.
-- **Scheduled tasks**: one TOML file per task under `agent_state/schedule/` — cron-style scheduling keeps Agents working autonomously around the clock.
-- **Agent State snapshots with export/import**: `system_config.yaml` carries a `version`; risky changes (optimization passes, import overwrite) snapshot to `snapshots/v<version>.tar.gz` first, restore any time, with the live vault preserved.
+## Scheduled tasks and Agent State snapshots
-## Evaluation center
+- **Scheduled tasks.** Each task is one TOML file under `agent_state/schedule/`. Cron-style schedules keep agents working on their own around the clock.
+- **Agent State snapshots, with export and import.** `system_config.yaml` records a `version`. Before a risky change, such as an optimization pass or an import that overwrites the current state, the Agent State is saved to `snapshots/v<version>.tar.gz`. You can restore a snapshot at any time, and restoring one keeps the live Vault.
-- **Benchmark scoreboards**: bundled suites, per-case scoring and trend curves; evaluations are charted per model, and each run deep-links to its Session's trace view.
-- **Evaluations carry the model**: the model reference moved from benchmark_config onto each evaluation (`provider` / `model_id` as a pair), making cross-model comparison direct.
+## Evaluation Center
+
+- **Benchmark scoreboards.** The Evaluation Center gains bundled suites, per-case scores and trend curves. Evaluations are charted per model, and each run links straight to its Session's Trace.
+- **Evaluations record the model.** The model reference moved from `benchmark_config` onto each evaluation, stored as a `provider` / `model_id` pair, so comparing models is direct.
## Model system
-- **Model identity principle**: a model is uniquely identified by the `(provider, model_id)` pair; connection details live inline on the Project config entry, with client-resolved environment-variable fallback when the credential is left empty.
-- **Custom provider groups**: beyond built-in vendors and custom, users can create their own groups (OpenAI protocol by default, base URL required).
-- **Runtime baseline raised to Node ≥ 24**: bundled runtime, CI and the release pipeline all migrated.
+- **Model identity principle.** A model is uniquely identified by its `(provider, model_id)` pair. Connection details are stored inline on the model's entry in the Project config. When the credential is left empty, the client falls back to environment variables.
+- **Custom provider groups.** Besides the built-in vendor groups and the Custom group, you can create your own groups. They use the OpenAI protocol by default and require a base URL.
+- **Node 24 or later.** The runtime baseline is now Node ≥ 24. The bundled runtime, CI and the release pipeline have all moved to it.
-## Install & experience
+## Install and experience
-- **One-line install**: a repo-root `install.sh` — `curl | sh` detects Linux / macOS and x64 / arm64; artifacts bundle the Node runtime, unpack and run.
-- **Skill library revamp**: Skills now use files as the runtime source of truth, with redesigned cards and quick invocation; built-in Agents converge to a single default_agent, with agent creation/optimization fully carried by the Skill library.
-- **Stability fixes**: Gemini tool_call_id collisions on consecutive same-name calls, stream-view scroll jitter on short containers, and WorkGroup parallel tool timing are all fixed.
+- **One-line install.** A new `install.sh` at the repository root runs as `curl | sh` and detects Linux / macOS and x64 / arm64. The release artifacts bundle the Node runtime, so you unpack them and run.
+- **Skill library redesign.** Skills now use their files as the runtime source of truth, the Skill cards are redesigned, and Skills can be invoked quickly. The built-in agents are merged into a single `default_agent`, and building and optimizing agents is handled entirely by the Skill library.
+- **Stability fixes.** Fixed colliding `tool_call_id` values when Gemini calls the same tool several times in a row, jitter when scrolling up through streaming output in a short scroll area, and the elapsed time shown for parallel tool calls in a WorkGroup.
diff --git a/packages/landing/content/blog/july-2026-updates.zh.md b/packages/landing/content/blog/july-2026-updates.zh.md
index 8d124154..8ad873d9 100644
--- a/packages/landing/content/blog/july-2026-updates.zh.md
+++ b/packages/landing/content/blog/july-2026-updates.zh.md
@@ -1,30 +1,32 @@
---
-title: 2026 年 7 月更新:定时任务、Agent 快照与评估中心增强
+title: 2026 年 7 月更新:定时任务、Agent State 快照与 Benchmark 记分板
date: 2026-07-17
category: changelog
-excerpt: 定时任务调度、Agent State 版本快照与导出导入、Benchmark 记分展示、模型确定原则与一键安装等一批更新已合入主干。
+excerpt: 定时任务、支持导出导入的 Agent State 快照、Benchmark 记分板、模型确定原则与一键安装已合入 main。
---
-本月主干合入了一批与「稳定进化」直接相关的更新,摘要如下。
+> 本文基于 PenguinHarness 0.0.1 撰写,之后的版本在部分细节上可能有所不同。
+
+本月有一批面向「稳定进化」的更新合入了 main。Agent 现在可以按计划定时运行,Agent State 会在有风险的修改之前自动快照,评估中心按模型绘制 Benchmark 结果。要点如下。
## 定时任务与 Agent State 快照
-- **定时任务调度**:`agent_state/schedule/` 下每个任务一个 TOML 文件,计划调度让 Agent 全天候自主执行。
-- **Agent State 版本快照与导出导入**:`system_config.yaml` 以 `version` 标识当前版本,风险修改(优化类修改、导入覆盖)前自动快照到 `snapshots/v<version>.tar.gz`,可随时回退,且恢复时保留现行 vault。
+- **定时任务。** 每个任务是 `agent_state/schedule/` 下的一个 TOML 文件。按 cron 风格调度,Agent 可以全天候自主工作。
+- **Agent State 快照,支持导出导入。** `system_config.yaml` 记录当前的 `version`。在有风险的修改之前,比如一轮优化或一次覆盖当前状态的导入,Agent State 会先保存到 `snapshots/v<version>.tar.gz`。快照随时可以恢复,恢复时保留当前的密钥保险柜。
-## 评估中心增强
+## 评估中心
-- **Benchmark 记分展示**:内建题库、逐题评分与趋势曲线,评估记录按模型分系列展示,run 可直达对应 Session 的轨迹观测。
-- **评估携带模型**:模型引用从 benchmark_config 移到每条 evaluation(`provider` / `model_id` 成对记录),跨模型对比更直观。
+- **Benchmark 记分板。** 评估中心新增内置题库、逐题评分和趋势曲线。评估记录按模型分别绘制,每次运行都能直接跳到对应会话的轨迹观测页面。
+- **每条评估记下所用模型。** 模型引用从 `benchmark_config` 移到了每条评估上,以 `provider` / `model_id` 成对记录,跨模型对比更直接。
## 模型体系
-- **模型确定原则**:模型由 `(provider, model_id)` 二元组唯一确定,连接信息内联在 Project 配置的模型条目上;credential 留空时按 client 解析结果回退环境变量。
-- **模型页自建分组**:内置厂商分组与 custom 之外,支持用户自建分组(OpenAI 协议缺省、base URL 必填)。
-- **运行基线升级 Node ≥ 24**:内嵌运行时同步更新,CI 与发布链路完成迁移。
+- **模型确定原则。** 模型由 `(provider, model_id)` 二元组唯一确定。连接信息内联在 Project 配置里对应的模型条目上。凭证留空时,客户端回退到环境变量。
+- **自建供应商分组。** 除了内置的厂商分组和 Custom 分组,还可以自建分组。自建分组默认使用 OpenAI 协议,base URL 必填。
+- **Node 24 及以上。** 运行时基线提升到 Node ≥ 24。内嵌运行时、CI 和发布流水线都已迁移。
## 安装与体验
-- **一键安装**:仓库根新增 `install.sh`,`curl | sh` 识别 Linux / macOS 与 x64 / arm64,产物内嵌 Node 运行时,解压即用。
-- **技能库改版**:Skill 以文件为运行时真源,技能卡片改版并支持快捷调用;内置 Agent 收敛为 default_agent,Agent 构建与优化能力全部由技能库承载。
-- **稳定性修复**:Gemini 连续同名工具调用 tool_call_id 冲突、流式输出短滚动区上滑抖动、WorkGroup 并行工具用时统计等问题已修复。
+- **一键安装。** 仓库根目录新增 `install.sh`,用 `curl | sh` 运行,自动识别 Linux / macOS 与 x64 / arm64。发布产物内嵌 Node 运行时,解压即可运行。
+- **技能库改版。** Skill 在运行时以文件为准,Skill 卡片重新设计,并支持快捷调用。内置 Agent 合并为一个 `default_agent`,Agent 的构建与优化完全交给技能库。
+- **稳定性修复。** 修复了三个问题:Gemini 连续调用同一个工具时 `tool_call_id` 冲突;滚动区域较矮时,向上滚动流式输出会抖动;WorkGroup 中并行工具调用的耗时显示不准。
diff --git a/packages/landing/content/blog/local-agents-on-amd-gpus.en.md b/packages/landing/content/blog/local-agents-on-amd-gpus.en.md
index 0c82d375..ff8fbd18 100644
--- a/packages/landing/content/blog/local-agents-on-amd-gpus.en.md
+++ b/packages/landing/content/blog/local-agents-on-amd-gpus.en.md
@@ -1,32 +1,52 @@
---
-title: "A closer look at PenguinHarness — and running a self-improving agent locally on an AMD GPU"
+title: "Run a self-improving agent locally on an AMD GPU with PenguinHarness"
date: 2026-07-20
category: practice
author: Ning Zhang (AMD), Yuyang Gao (AMD), Yaowei Zheng (PrismShadow)
-excerpt: What PenguinHarness actually is, the ideas behind its architecture, and a real end-to-end run — a local open-weight model on an AMD GPU that fails a scored task, then recursively improves itself from a middling score to near the ceiling by diagnosing and rewriting its own files, entirely on-device.
+excerpt: "Learn how PenguinHarness is built, then run it on an AMD GPU with a local open-weight model: have an agent build another agent, and watch an agent raise its own score from about 4.6 to 9.8 out of 10, entirely on-device."
---
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
+
*AMD × PrismShadow — by Ning Zhang, Yuyang Gao (AMD) and Yaowei Zheng (PrismShadow).*
-If you are new to PenguinHarness, this post is a guided tour: what the project is, the ideas that shape its architecture, and — to make it concrete — a real run where a fully local open-weight model on an AMD GPU fails a scored task and then recursively improves itself from a middling score to near the ceiling by diagnosing and rewriting its own files, without a single byte leaving the machine.
+In this tutorial you run PenguinHarness on fully local, open-weight infrastructure with an AMD GPU. Every Token is generated on the machine, and nothing is sent to a cloud API.
+
+You start with a short tour of how PenguinHarness is built. Then you serve a local model on the GPU, have an agent build a new agent from a one-sentence requirement, and watch an agent fail a scored task and improve itself by diagnosing the failure and rewriting its own files.
+
+By the end you will have:
+
+- `qwen3.6:35b` served by Ollama on your AMD GPU and registered as the default model in PenguinHarness,
+- a `commit-helper` agent that another agent built for you,
+- a self-improvement run that moves the score from about 4.6 to about 9.8 out of 10 in two rounds.
+
+The tutorial is for developers who are new to PenguinHarness. If you have no AMD GPU, the section after Step 5 shows how to use Fireworks credits instead.
+
+## Prerequisites
+
+- An AMD GPU supported by ROCm, with ROCm installed and enough GPU memory for `qwen3.6:35b`, a model of about 24 GB.
+- Ollama on the same machine.
+- A clone of the [PenguinHarness repository](https://github.com/Prism-Shadow/penguin-harness), with Node.js 24 or later and pnpm, to run the two examples in Steps 3 to 5.
-## What PenguinHarness is
+You do not need a cloud account or an API key.
-PenguinHarness is an open-source AI Agent harness — a complete TypeScript stack for *building* and *evolving* agents, not a single app. It deploys fully locally, can run on as little as a single CPU, and reaches 1000+ online and local models through one unified gateway. Its purpose fits in one line:
+## How PenguinHarness is built
+
+PenguinHarness is an open-source AI agent harness: a complete TypeScript stack for *building* and *evolving* agents, not a single app. It deploys fully locally, can run on as little as a single CPU, and reaches 1000+ online and local models through one unified gateway. Its purpose fits in one line:
> Efficient Self-Improving Harness for Everyone.
-The word "harness" is deliberate. This is not a heavyweight framework you build *on top of*; it is a thin, reliable, observable substrate that an agent can *stand inside* — and, crucially, one that an agent can reach back into and improve. Three pillars carry that idea:
+The word "harness" is deliberate. PenguinHarness is not a heavyweight framework you build on top of. It is a thin, reliable, observable substrate that an agent stands inside, and one that an agent can reach back into and improve. Three pillars carry that idea:
| Pillar | Meaning |
| --- | --- |
-| **Simplest Is the Best** | A deliberately minimal toolset over clean low-level interfaces: fewer tool calls, fewer tokens, complex tasks done efficiently. |
-| **Harness for Building Agents** | Either build one programmatically with the SDK (`createAgent` → `createSession` → `run`), or have an Agent build a whole new Agent for you from a plain-language requirement. |
-| **Harness for Recursive Self-Improvement** | With Skills, an Agent evaluates and optimizes *itself*, improving recursively over time. |
+| **Simplest Is the Best** | A deliberately minimal toolset over clean low-level interfaces: fewer tool calls, fewer Tokens, complex tasks done efficiently. |
+| **Harness for building agents** | Either build one programmatically with the SDK (`createAgent` → `createSession` → `run`), or have an agent build a whole new agent for you from a plain-language requirement. |
+| **Harness for Recursive Self-Improvement** | With Skills, an agent evaluates and optimizes *itself*, improving recursively over time. |
For the latter two, PenguinHarness is the first open-source implementation of its kind.
-## The architecture, and why it is shaped this way
+### One kernel, many front-ends
One install gives you four layers that share one data directory and one message protocol:
@@ -46,57 +66,57 @@ One install gives you four layers that share one data directory and one message
└──────────────────────────────────────────────┘
```
-The center is the execution engine in `@prismshadow/penguin-core`. The CLI, the Server, and the Web App are simply different "Human implementations" of that same engine. This single decision — one kernel, many front-ends — is what keeps the whole system coherent, and it comes from a small set of design tenets worth understanding on their own.
+The center is the execution engine in `@prismshadow/penguin-core`. The CLI, the Server and the Web App are different "Human implementations" of that same engine. This one decision, a single kernel with many front-ends, keeps the whole system coherent. It follows from a few design tenets, described below.
-### One protocol, three jobs — OmniMessage
+### OmniMessage: one protocol, three jobs
-Everything the system does is expressed as one message type, OmniMessage. It is simultaneously:
+Everything the system does is expressed as one message type, OmniMessage. It is at the same time:
- the SDK's external interface (what you send in and stream back out),
- the on-disk Trace format, and
- the engine's internal currency.
-In other words, *what streams live, what is stored on disk, and what the model sees are literally the same object*. There is no translation layer silently reshaping your data between "what happened" and "what was recorded." That identity is the foundation for the observability and recoverability everything else relies on.
+What streams live, what is stored on disk and what the model sees are literally the same object. No translation layer silently reshapes your data between "what happened" and "what was recorded". That identity is the foundation for the observability and recoverability that everything else relies on.
### The three-interface boundary
The engine speaks only OmniMessage and orchestrates the flow between exactly three boundaries:
-- **Human** — the user side. Notably *not* a class: the SDK's single entry point `session.run(newMessages, { approve, signal })` *is* the Human boundary. Input is a list of messages plus an approval callback; output is a stream of messages. The CLI and the Server are its two shipped implementations.
-- **LLM** — the model side (`LLMInterface`). All provider-specific protocol adaptation lives in the AgentHub gateway; the core never imports a vendor SDK. This is exactly why any OpenAI-compatible endpoint — including a local one — just works.
-- **Environment** — the tool side (`EnvironmentInterface`). Runs approved tool calls and streams results back.
+- **Human**: the user side. It is not a class: the SDK's single entry point, `session.run(newMessages, { approve, signal })`, *is* the Human boundary. Its input is a list of messages plus an approval callback, and its output is a stream of messages. The CLI and the Server are its two shipped implementations.
+- **LLM**: the model side (`LLMInterface`). All provider-specific protocol adaptation lives in the AgentHub gateway, and the core never imports a vendor SDK. That is why any OpenAI-compatible endpoint, including a local one, just works.
+- **Environment**: the tool side (`EnvironmentInterface`). It runs approved tool calls and streams the results back.
-Because the kernel contains no provider, tool, or UI specifics, each side swaps by configuration alone. Today's local shell can become tomorrow's sandbox; a CLI caller can become a web caller — the core never changes.
+Because the kernel contains no provider, tool or UI specifics, each side swaps by configuration alone. Today's local shell can become tomorrow's sandbox, and a CLI caller can become a web caller, while the core never changes.
### Agents are editable data, not code
-An Agent's entire behavior — its prompt, its Skills, its runtime config — lives as editable files on disk (`agent_state/`), not as hardcoded constants. This is the quiet key to the whole project: *what you can see, an Agent can improve*. Self-improvement is not a special engine feature; it is an agent editing the same files you would edit by hand, then re-evaluating itself.
+An agent's entire behavior (its prompt, its Skills and its runtime config) lives as editable files on disk in `agent_state/`, not as hardcoded constants. This is the key to the whole project: what you can see, an agent can improve. Self-improvement is not a special engine feature. It is an agent editing the same files you would edit by hand, then evaluating itself again. Step 5 shows this in action.
-### A few more tenets that run through everything
+### Tenets that run through everything
-- **Errors converge into messages.** Model and tool failures never throw into the engine; they become messages the model can react to. Robustness is a property of the protocol, not of scattered try/catch.
-- **Everything is observable.** Every request, tool call, and approval decision is appended to the Trace; a Session restores fully from it.
-- **Streaming first.** Text streams token by token; tool calls and results appear live.
-- **Model ↔ Agent decoupling.** An Agent never binds to a model — you choose one per Session. The same Agent can run different sessions on different models.
+- Errors converge into messages. Model and tool failures never throw into the engine; they become messages the model can react to. Robustness is a property of the protocol, not of scattered try/catch.
+- Everything is observable. Every request, tool call and approval decision is appended to the Trace, and a Session restores fully from it.
+- Streaming comes first. Text streams Token by Token, and tool calls and results appear live.
+- Models and agents are decoupled. An agent never binds to a model: you choose one per Session, so the same agent can run different Sessions on different models.
-The one-line summary of the layering: *what is editable or recorded lives in files; what makes messages flow lives in the SDK; what needs a resident process and multiple users lives in the Server; the rest is rendering.*
+The layering in one sentence: *what is editable or recorded lives in files; what makes messages flow lives in the SDK; what needs a resident process and multiple users lives in the Server; the rest is rendering.*
-## Simplest is the best — six tools, and why that matters
+### Six built-in tools
-The first pillar is the easiest to overlook and the one you feel most in practice: the toolset is deliberately tiny. PenguinHarness ships exactly six built-in tools:
+The first pillar is the easiest to overlook and the one you feel most in practice: the toolset is deliberately tiny. When this post was written, PenguinHarness shipped exactly six built-in tools:
| Tool | Purpose |
| --- | --- |
-| `exec_command` | Run a shell command in the workspace (streams stdout/stderr) |
-| `input_command` | Drive a running command — write stdin, send Ctrl-C, poll output |
+| `exec_command` | Run a shell command in the Workspace (streams stdout/stderr) |
+| `input_command` | Drive a running command: write stdin, send Ctrl-C, poll output |
| `run_subagent` | Delegate a self-contained subtask to a child agent |
| `input_subagent` | Poll or follow up with a background subagent |
| `read_image` | Read an image as image content (vision models) |
| `describe_image` | Have a vision model describe an image for text-only models |
-Notice what is *not* there: no `read_file`, no `write_file`, no `edit_file`, no `list_dir`, no `grep` tool. That is intentional — the shell is the universal interface, so reading, writing, and editing files all go through `exec_command` (`cat`, `>`, `sed`, and so on). The principle is "the simplest is the best": every extra tool is more schema in the prompt, more tokens on every call, and one more thing the model can pick wrong. Fewer tools means fewer wrong calls and less token overhead — complex tasks done with less ceremony.
+There was no `read_file`, `write_file`, `edit_file`, `list_dir` or `grep` tool, on purpose. The shell was the universal interface, so reading, writing and editing files all went through `exec_command` (`cat`, `>`, `sed` and so on). Every extra tool adds schema to the prompt, Tokens to every call, and one more thing the model can pick wrong. Fewer tools mean fewer wrong calls and less Token overhead.
-This is not just theory — you can read it straight out of the Trace. Here are the only three tool calls the agent made to complete the entire CSV-cleanup case, all of them `exec_command`:
+You can read this straight out of a Trace. These are the only three tool calls an agent made to complete a CSV-cleanup case, all of them `exec_command`:
```bash
# 1. read the input — no read_file tool, just cat
@@ -118,19 +138,64 @@ for r in cleaned:
cat users_clean.csv
```
-Read the file, transform it, check the result — three calls, one tool, no special file machinery. And notice the second step: because the interface is a shell, the model naturally reached for Python to express the dedup logic, something no fixed `edit_file` tool could have done. A minimal toolset is not a limitation the model works around; it is *why* a capable model can finish a real task in so few steps.
+Read the file, transform it, check the result: three calls, one tool, no special file machinery. In the second call, because the interface is a shell, the model reached for Python to express the dedup logic, which no fixed `edit_file` tool could have done. A minimal toolset is not a limitation the model works around. It is why a capable model can finish a real task in so few steps.
+
+## Step 1: Install PenguinHarness
+
+Install PenguinHarness with the one-line installer:
+
+```bash
+curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
+```
-## Agents that build agents — a worked example
+The installer gives you the `penguin` CLI, which you use in the next step to register the local model.
-This is the second pillar — *the harness for building agents* — made concrete. It has two faces. The first is the SDK: you embed an agent in your own program with a few lines — `createAgent()` → `createSession()` → `session.run(...)` (see the snippet at the end). The second is the more striking one, and the flip side of "agents are editable data": if an Agent is just files, then *an Agent can write those files for you*. That is what the built-in `agent-creation` skill does — given a plain-language requirement, an agent scaffolds a new agent: its directory layout, its `system_config.yaml` (name and description), and above all its `AGENTS.md`, the file that turns the requirement into behavior. To show that second face end-to-end, we did exactly this on the local AMD GPU stack.
+## Step 2: Serve qwen3.6:35b on the AMD GPU
-**The request.** We asked the local `qwen3.6:35b` agent, using the `agent-creation` skill:
+In this step you serve a local model through Ollama and register it with PenguinHarness.
+
+The model is `qwen3.6:35b`, a capable local open-weight model: a ~24 GB MoE with 36B total parameters, quantized to Q4_K_M. Under ROCm, Ollama detects the AMD GPU natively, with no architecture override, and loads the model into GPU memory. The same path spans AMD's ROCm-supported lineup, from Radeon PRO workstation cards such as the W7900 (48 GB, RDNA3) up to datacenter Instinct accelerators.
+
+Start Ollama and pull the model:
+
+```bash
+ollama serve & # if not already running as a service
+ollama pull qwen3.6:35b
+```
+
+Then register the model with PenguinHarness and make it the default:
+
+```bash
+penguin config model add \
+ --model-id qwen3.6:35b \
+ --provider custom --client-type openai \
+ --base-url http://localhost:11434/v1 \
+ --api-key ollama --set-default
+```
+
+A single command is enough because the core treats any OpenAI-compatible endpoint the same way, and Ollama serves one at `http://localhost:11434/v1`.
+
+## Step 3: Have an agent build an agent
+
+In this step an agent builds a new agent for you. This is the second pillar, the harness for building agents, made concrete.
+
+The pillar has two faces. The first is the SDK: you embed an agent in your own program with a few lines, `createAgent()` → `createSession()` → `session.run(...)` (see Next steps at the end). The second follows from agents being editable data: if an agent is just files, *an agent can write those files for you*. That is what the built-in `agent-creation` Skill does (renamed `agent-initialization` in PenguinHarness 0.2.4). Given a plain-language requirement, an agent scaffolds a new agent: its directory layout, its `system_config.yaml` (name and description), and above all its `AGENTS.md`, the file that turns the requirement into behavior.
+
+The repository example [`examples/build-agent-with-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent) runs the whole flow as a self-contained, SDK-driven script on the local Ollama + qwen3.6:35b setup, with no cloud API. Its `README.md` covers the one-time Ollama configuration. Run it from the repository root:
+
+```bash
+pnpm install
+pnpm build
+pnpm --dir examples/build-agent-with-agent start
+```
+
+In phase 1, the script uses `createAgent`/`createSession`/`run` to drive `default_agent` into building `commit-helper`. The local `qwen3.6:35b` agent receives this request, using the `agent-creation` Skill:
> Create a new agent called `commit-helper` that writes Conventional Commits messages — a `type(scope): subject` header (type from feat/fix/docs/…), imperative subject under ~50 chars, a blank line, then a body explaining the *why*.
-**What it produced.** Working on its own, the agent created the new agent's directory, copied a base config, set its name and description, and wrote a genuinely good `AGENTS.md` — encoding the header format, a type enum, a subject-length rule, "explain the *why*, not the *what*" for the body, an optional `BREAKING CHANGE`/`Closes #` footer, and even a heuristic for inferring the type from a diff (e.g. "renames → refactor, not chore"). No hand-holding on the content.
+Working on its own, the agent creates the new agent's directory, copies a base config, sets its name and description, and writes a genuinely good `AGENTS.md`. The file encodes the header format, a type enum, a subject-length rule, "explain the *why*, not the *what*" for the body, an optional `BREAKING CHANGE`/`Closes #` footer, and even a heuristic for inferring the type from a diff (for example, "renames → refactor, not chore"). The content needs no hand-holding.
-**Then we ran the agent it built.** Pointed at a change description ("added retry-with-backoff to the payment client because transient 503s broke checkout"), the freshly-created `commit-helper` — following only the `AGENTS.md` written for it — produced:
+In phase 2, the script loads the new agent and runs it on a change description: "added retry-with-backoff to the payment client because transient 503s broke checkout". Following only the `AGENTS.md` written for it, the freshly created `commit-helper` produces:
```text
fix(payment): add retry-with-backoff for transient gateway 503 errors
@@ -141,79 +206,71 @@ exponential backoff gives the gateway time to recover, preventing
spurious user-facing errors without requiring manual retries.
```
-It even reasoned out loud about whether the change was a `fix` or a `feat` before committing to `fix` — behavior that came entirely from the AGENTS.md its parent agent had written.
+It even reasons out loud about whether the change is a `fix` or a `feat` before settling on `fix`. That behavior comes entirely from the `AGENTS.md` its parent agent wrote.
-**Run it yourself.** The whole flow above is a self-contained, SDK-driven script in the repo:
-[`examples/build-agent-with-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent).
-Phase 1 uses `createAgent`/`createSession`/`run` to drive `default_agent` into building
-`commit-helper`; phase 2 loads the new agent and runs it — all on the local Ollama + qwen3.6:35b
-setup, no cloud API. See its `README.md` for the one-time Ollama configuration.
+## Step 4: Measure the baseline
-## Self-improvement, in one line
+In this step you score an agent with a blank `AGENTS.md` on a task whose rules it cannot see.
-The third pillar builds on the same idea. Because agents are editable data and everything is traced, an agent can *measure itself and get better* — a loop of benchmark → evaluate → find where points were lost → edit the agent's own files → keep the change only if the score improves. There is no special engine code behind it; it is ordinary agent machinery orchestrated by Skills, and every number on the scoreboard links back to the exact Session that produced it. We walk through the full loop — with a real before/after — after the run below.
+The task looks trivial: read a project notes file and produce a summary with a 2-sentence overview and exactly 3 key facts, *and follow the team's standard report format*. That last clause is the whole point. The "team format" is an arbitrary house convention: a specific marker line, a `# Report: <subject>` title, a `Classification: INTERNAL` line and a `Reviewed-by: Aurora Team` footer. It lives *only in the agent's `AGENTS.md`* and cannot be inferred from the task.
-## A real local run on an AMD GPU
+The task carries a private rubric, a checklist the agent never sees, worth 10 points:
-Design tenets are easy to claim. Here is an end-to-end run that exercises them, entirely on fully local, open-weight infrastructure with an AMD GPU — every token generated on-device, nothing sent to a cloud API.
+- 5 points for content, which any capable model earns from the task alone;
+- 5 points for the convention, which is knowable only from `AGENTS.md`.
-**The setup.** An AMD GPU running ROCm, serving `qwen3.6:35b` — a capable local open-weight model (a ~24 GB MoE, 36B total parameters, Q4_K_M) — through Ollama's OpenAI-compatible endpoint. Ollama detected the AMD GPU natively (no architecture override needed) and loaded the model into GPU memory. This same path spans AMD's ROCm-supported lineup — from Radeon PRO workstation cards such as the W7900 (48 GB, RDNA3) up to datacenter Instinct accelerators. Wiring it into PenguinHarness took a single command, precisely because the core treats any OpenAI-compatible endpoint the same way:
+The repository example [`examples/self-improving-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/self-improving-agent) runs this task, and then the improvement loop, as a self-contained, SDK-driven script. It uses a deterministic, readable rubric with the same 10 points, runs on the same local Ollama + qwen3.6:35b setup, and uses a dedicated agent id, so your own agents are untouched. Start it from the repository root:
```bash
-penguin config model add \
- --model-id qwen3.6:35b \
- --provider custom --client-type openai \
- --base-url http://localhost:11434/v1 \
- --api-key ollama --set-default
+pnpm --dir examples/self-improving-agent start
```
-**The task, and how it's scored.** We gave it a task that looks trivial: read a project notes file and produce a summary with a 2-sentence overview and exactly 3 key facts — *and follow the team's standard report format.* That last clause is the whole point. The "team format" is an arbitrary house convention — a specific marker line, a `# Report: <subject>` title, a `Classification: INTERNAL` line, a `Reviewed-by: Aurora Team` footer — that lives *only in the agent's `AGENTS.md`* and cannot be inferred from the task. The task carries a private rubric — a checklist the agent never sees — with 10 points: 5 for content any capable model earns from the task alone, and 5 for the convention, which is knowable only from `AGENTS.md`.
+The first score the script reports is the baseline. With a blank `AGENTS.md`, the model writes a perfectly reasonable summary but stably loses all 5 convention points, landing around 4.6 / 10. Exact numbers vary run to run. A local model is nondeterministic, so the script averages several runs per version, which is exactly why real Benchmarks use a `runs` count.
+
+The model could not have done otherwise. Nothing in the task reveals the house convention, so this is an *information gap, not a capability gap*, and it is why a stronger model cannot just "figure it out". Because every step is in the Trace, you can open the run and see precisely which points were missed.
+
+This is the honest starting point: on local hardware, an out-of-the-box agent does not ace a task whose rules live in files it has not learned yet. A measured, auditable, reproducible failure is something the agent can fix systematically by teaching itself, which is what the next step shows.
-**The baseline — and why it isn't perfect.** Running locally on the AMD GPU with a blank `AGENTS.md`, the model wrote a perfectly reasonable summary — and stably lost all 5 convention points, landing around **4.6 / 10** (exact numbers vary run to run). It could not have done otherwise: nothing in the task reveals the house convention, so this is an *information gap, not a capability gap* — which is exactly why a stronger model can't just "figure it out." And because every step is in the Trace, this is not guesswork — you can open the run and see precisely which points were missed.
+## Step 5: Let the agent improve itself
-That is the honest starting point: on local hardware, an out-of-the-box agent does *not* ace a task whose rules live in files it hasn't learned yet. Which is exactly what makes the next section interesting — a measured, auditable, *reproducible* failure is something the agent can systematically fix by teaching itself.
+In this step the same run continues into the self-improvement loop. The agent does the diagnosing and the editing; nobody hands it the answer.
-## How self-improvement actually works — and a real before/after
+The loop has five stages. There is no special engine code behind it: it is ordinary agent machinery, orchestrated by Skills.
-The 4.6 / 10 above is an *evaluation* — a snapshot of the agent as it stands. The more interesting question is how PenguinHarness turns that snapshot into progress. This is the recursive self-improvement loop, and it is worth understanding as a mechanism, because there is no magic engine code behind it — it is ordinary agent machinery, orchestrated by Skills:
+1. Benchmark: define capability cases, each with a private rubric, as in Step 4.
+2. Evaluate: run the agent over the cases and score them against the rubrics. Each run is an ordinary, fully traced Session.
+3. Read the Trace to find where points were lost: every score links back to the exact run, so you can see *why* a point was missed, not just that it was.
+4. Edit the agent's state: the agent's behavior lives in editable files (`AGENTS.md`, Skills, config). You, or an Optimizer agent, change those files to address the failure, producing version N+1.
+5. Snapshot, then keep or roll back: take a snapshot before each round, and keep N+1 only if the score strictly improves. Otherwise, roll back.
-1. **Benchmark** — define capability cases, each with a private rubric (as above).
-2. **Evaluate** — run the agent over the cases and score against the rubrics. Each run is an ordinary, fully-traced Session.
-3. **Read the Trace to find where points were lost** — because every score links back to the exact run, you can see *why* a point was missed, not just that it was.
-4. **Edit the Agent's state** — the agent's behavior lives in editable files (`AGENTS.md`, Skills, config). You (or an Optimizer agent) change those to address the failure, producing version N+1.
-5. **Snapshot & keep-or-roll-back** — snapshot before each round; keep N+1 only if the score strictly improves, otherwise roll back.
+In the example, the script supplies only the failure signal and the accepted example reports, then reports whether each round raised the score. It never writes the convention itself.
-Let's improve the exact agent from the previous section — the same `qwen3.6:35b` on the same AMD GPU, the same task that just scored **4.6 / 10**. And here is the crucial part: the *agent* does the diagnosing and the editing — we do not hand it the answer.
+### Round 1: learn the structure
-- **The diagnosis (by the agent).** We give the agent two files and nothing else: the report it just got rejected, and a *different* project's report that passed review. Nobody tells it the rules. It compares the two, and infers the reusable house convention — the marker, the title shape, the metadata line, the sign-off. This is the "read the Trace to find where points were lost" step, performed by the agent itself.
-- **The edit (N → N+1), authored by the agent.** The agent writes the convention it just inferred into its own `AGENTS.md`. From a single example it correctly recovers the *structure*, but can't yet tell which tokens are fixed constants vs per-report fields — a single example is ambiguous — so it generalizes the marker to a placeholder. Re-evaluated, the score climbs to about **6.6 / 10**. No retraining, no code — the agent edited a text file it reads on every run.
-- **The recursion (N+1 → N+2).** Now we show it *several* accepted reports from different projects that share the same marker and sign-off. The agent reasons that whatever is identical across all of them must be a fixed constant, reads its *own* N+1 `AGENTS.md`, and refines it — locking `<!-- ACME-DATA-PLATFORM -->` and `Reviewed-by: Aurora Team` to literals. Re-evaluated again: about **9.8 / 10**. That is recursion in the true sense: `state_{n+1} = agent.reflect(state_n, new_evidence)`.
+The agent gets two files and nothing else: the report that was just rejected, and a passing report from a *different* project. Nobody tells it the rules. It compares the two and infers the reusable house convention: the marker, the title shape, the metadata line and the sign-off. This is the "read the Trace to find where points were lost" stage, performed by the agent itself.
-That is a **4.6 → 6.6 → 9.8** climb on the same model and task (numbers vary run to run), achieved purely by the agent editing a text file it reads — with the harness keeping each round only because the score strictly improved. That is the loop, self-driven: *what the agent can see, the agent can improve* — measured against a rubric, linked to a Trace, not vibes.
+The agent then writes the convention into its own `AGENTS.md`, producing version N+1. From a single example it correctly recovers the *structure*, but it cannot yet tell which tokens are fixed constants and which are per-report fields, because one example is ambiguous. So it generalizes the marker to a placeholder. Evaluated again, the score climbs to about 6.6 / 10. There is no retraining and no code change: the agent edited a text file it reads on every run.
-**Run it yourself.** This whole loop is a self-contained, SDK-driven script in the repo:
-[`examples/self-improving-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/self-improving-agent).
-It uses a deterministic, readable rubric (10 points: 5 for content, 5 for the house convention that
-lives only in `AGENTS.md`) and — because a local model is nondeterministic — averages several runs
-per version, which is exactly why real benchmarks use a `runs` count. Crucially, the script never
-writes the convention itself: the *agent* diagnoses the gap from a passing example and edits its own
-`AGENTS.md`. In our runs the averaged score moved **4.6 → 6.6 → 9.8** across two self-authored
-rounds (structure learned, then constants locked), and the harness keeps each round only because the
-score strictly improved. It runs on the same local Ollama + qwen3.6:35b setup and uses a dedicated
-agent id, so your own agents are untouched.
+### Round 2: lock the constants
-## No AMD GPU yet? Free cloud compute from AMD + Fireworks
+Next, the agent sees *several* accepted reports from different projects that share the same marker and sign-off. It reasons that whatever is identical across all of them must be a fixed constant, reads its *own* N+1 `AGENTS.md`, and refines it, locking `<!-- ACME-DATA-PLATFORM -->` and `Reviewed-by: Aurora Team` to literals. Evaluated again, the score reaches about 9.8 / 10. That is recursion in the true sense: `state_{n+1} = agent.reflect(state_n, new_evidence)`.
-Not everyone has an AMD GPU under their desk — and you do not need one to try this. Through the AMD AI Developer Program, AMD partners with Fireworks AI to hand eligible developers **$50 in free Fireworks credits**. Fireworks serves open-weight models over an OpenAI-compatible endpoint, so — just like the local Ollama setup above — it is a single-line change to point PenguinHarness at it.
+Each round strictly raised the score, which is the condition stage 5 sets for keeping an edit.
-Getting the credits (approval typically takes 2–3 business days):
+## No AMD GPU? Use Fireworks credits
+
+You do not need an AMD GPU to try this. Through the AMD AI Developer Program, AMD partners with Fireworks AI to give eligible developers $50 in free Fireworks credits. Fireworks serves open-weight models over an OpenAI-compatible endpoint, so, just like the local Ollama setup, pointing PenguinHarness at it is a single-line change.
+
+Approval typically takes 2–3 business days. To get the credits:
1. Sign up at the [AMD AI Developer Program](https://developer.amd.com/ai-developer-program/).
2. Open **Member Perks → Cloud Credit Options → Request Cloud Credits**.
3. In the form, choose **Fireworks AI** as the product needed, add at least one public profile link (GitHub, LinkedIn, etc.), and submit.
4. AMD emails you a coupon code. Redeem it at [fireworks.ai](https://fireworks.ai/) via **Redeem Promo**, then generate an API key.
-Then wire it into PenguinHarness exactly like any other endpoint:
+[Getting Fireworks API Access](https://penguin.ooo/blog/fireworks-credits-amd) walks through redeeming the credits and creating the API key in detail.
+
+Then register Fireworks in PenguinHarness like any other endpoint:
```bash
penguin config model add --model-id <fireworks-model-id> \
@@ -222,15 +279,29 @@ penguin config model add --model-id <fireworks-model-id> \
--api-key <your-fireworks-key> --set-default
```
-Same harness, same one-line swap — whether the tokens are generated on your own AMD GPU or on AMD-backed cloud credits. (Keep your coupon code and key private; program terms may change, so check the official page and approval email for current details.)
+The harness and the one-line swap stay the same, whether the Tokens are generated on your own AMD GPU or on AMD-backed cloud credits. Keep your coupon code and key private. Program terms may change, so check the official page and the approval email for current details.
-## Why this matters
+## Results
-- **Local-first is not a slogan.** A complete build → run → self-evaluate loop ran on-device, on an AMD GPU, with no data leaving the machine — a real answer for privacy-sensitive and enterprise settings. And because it rides on ROCm + Ollama, the same setup runs across AMD's GPU range: a single Radeon PRO workstation card (e.g. the 48 GB W7900) comfortably runs models from 8B up to 30B-plus, while Instinct accelerators scale it further.
-- **The thin model layer pays off.** Because provider adaptation lives entirely in the gateway, "a local Ollama model" and "a frontier cloud API" are the same one-line change. You are never locked to a vendor — or to a GPU vendor. We ran this on an AMD GPU (ROCm), but nothing here is AMD-specific: the very same steps work on an NVIDIA GPU (Ollama's CUDA backend) or on Apple Silicon — only the Ollama runtime underneath changes, while the harness, the commands, and the examples stay identical.
-- **Observability is built in, everywhere.** The local run produced the same append-only Trace and scoreboard linkage as any cloud run. Evaluation is auditable by construction.
+In our runs, the same model and task produced this climb. The numbers vary run to run.
-## Get started
+| Version | What the agent had written into its `AGENTS.md` | Score |
+| --- | --- | --- |
+| N (baseline) | Nothing: the file is blank | about 4.6 / 10 |
+| N+1 | The convention's structure, with the marker as a placeholder | about 6.6 / 10 |
+| N+2 | The same convention, with its constants locked to literals | about 9.8 / 10 |
+
+The score rose purely because the agent edited a text file it reads. The run shows three things:
+
+- Local-first works on AMD hardware. A complete build → run → self-evaluate loop ran on-device, on an AMD GPU, with no data leaving the machine. That is a real answer for privacy-sensitive and enterprise settings. Because it rides on ROCm + Ollama, the same setup runs across AMD's GPU range: a single Radeon PRO workstation card (such as the 48 GB W7900) comfortably runs models from 8B up to 30B-plus, while Instinct accelerators scale it further.
+- The thin model layer pays off. Provider adaptation lives entirely in the gateway, so "a local Ollama model" and "a frontier cloud API" are the same one-line change. You are never locked to a vendor, or to a GPU vendor. We ran this on an AMD GPU (ROCm), but nothing here is AMD-specific: the same steps work on an NVIDIA GPU (Ollama's CUDA backend) or on Apple Silicon. Only the Ollama runtime underneath changes; the harness, the commands and the examples stay identical.
+- Observability is built in everywhere. The local run produced the same append-only Trace and scoreboard linkage as any cloud run, and every number on the scoreboard links back to the exact Session that produced it. Evaluation is auditable by construction.
+
+## Next steps
+
+You served a local model on an AMD GPU, had an agent build `commit-helper`, and watched an agent raise its own score by editing its own `AGENTS.md`.
+
+The whole setup takes three commands, for any OpenAI-compatible endpoint, a local Ollama model included:
```bash
curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
@@ -243,7 +314,7 @@ penguin config model add --model-id <your-model> \
penguin web # or: penguin run --approve allow-all --message "..."
```
-Prefer to embed it in your own program? That is the SDK face of the "building agents" pillar — the core loop is three calls:
+To embed an agent in your own program, use the SDK face of the "building agents" pillar. The core loop is three calls:
```ts
const agent = await createAgent({ agentId: "default_agent" });
@@ -251,6 +322,4 @@ const session = await agent.createSession({ workspaceDir: process.cwd() });
for await (const out of session.run([userText("...")], { approve: async () => "allow" })) { /* stream */ }
```
-Complete, runnable versions live in [`examples/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples) — including an agent that builds another agent and an agent that improves itself, both on local Ollama.
-
-Whether you run frontier cloud models or open weights on your own AMD GPU, PenguinHarness gives you the same minimal, observable, self-improving substrate. Follow us on [GitHub](https://github.com/Prism-Shadow/penguin-harness) and open your first issue.
+Complete, runnable versions live in [`examples/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples), including an agent that builds another agent and an agent that improves itself, both on local Ollama. Follow us on [GitHub](https://github.com/Prism-Shadow/penguin-harness) and open your first issue.
diff --git a/packages/landing/content/blog/local-agents-on-amd-gpus.zh.md b/packages/landing/content/blog/local-agents-on-amd-gpus.zh.md
index 6b5a7e47..2852e510 100644
--- a/packages/landing/content/blog/local-agents-on-amd-gpus.zh.md
+++ b/packages/landing/content/blog/local-agents-on-amd-gpus.zh.md
@@ -1,34 +1,54 @@
---
-title: 深入了解 PenguinHarness——并在 AMD GPU 上本地跑通一个自我进化的 Agent
+title: "在 AMD GPU 上用 PenguinHarness 本地运行自我进化的 Agent"
date: 2026-07-20
category: practice
author: 张宁(AMD)、高钰洋(AMD)、郑耀威(PrismShadow)
-excerpt: PenguinHarness 到底是什么、它的架构背后有哪些理念,以及一次真实的端到端运行——一个完全本地、运行在 AMD GPU 上的开源权重模型,先在一个打分任务上失败,再通过自己诊断并改写自身文件,把分数从大约半数递归自我提升到接近满分,全程数据不出本机。
+excerpt: "先了解 PenguinHarness 的架构,再在 AMD GPU 上用本地开源权重模型运行它:让一个 Agent 构建另一个 Agent,再看 Agent 把自己的分数从约 4.6 提升到 9.8(满分 10),全程在本机完成。"
---
-*AMD × PrismShadow——张宁、高钰洋(AMD),郑耀威(PrismShadow)。*
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-如果你是第一次接触 PenguinHarness,这篇文章是一次完整的导览:这个项目是什么、它的架构背后有哪些设计理念,以及——为了让一切足够具体——一次真实的运行:一个完全本地、跑在 AMD GPU 上的开源权重模型,先在一个打分任务上失败,再由它自己诊断失分、改写自身文件,把分数从大约半数递归自我提升到接近满分,全程没有一个字节离开本机。
+AMD × PrismShadow——张宁、高钰洋(AMD),郑耀威(PrismShadow)。
-## PenguinHarness 是什么
+在这篇教程里,你将在 AMD GPU 上,用完全本地、开源权重的环境运行 PenguinHarness。每个 Token 都在本机生成,不向任何云端 API 发送内容。
-PenguinHarness 是一个开源的 AI Agent Harness——一套用于*构建*和*进化* Agent 的完整 TypeScript 技术栈,而不是某一个具体应用。它可以完全本地部署,最低单 CPU 即可运行,并通过一个统一网关触达 1000+ 在线与本地模型。它的主旨只有一句话:
+你会先简要了解 PenguinHarness 的架构,然后在 GPU 上部署一个本地模型,让一个 Agent 根据一句话需求构建新 Agent,再看一个 Agent 在打分任务上失败之后,如何通过诊断失分原因、改写自己的文件实现自我进化。
+
+完成本教程后,你将拥有:
+
+- 在你的 AMD GPU 上由 Ollama 部署、并注册为 PenguinHarness 默认模型的 `qwen3.6:35b`;
+- 一个由另一个 Agent 替你构建的 `commit-helper` Agent;
+- 一次自我进化运行:两轮之内,分数从约 4.6 提升到约 9.8(满分 10)。
+
+本教程面向初次接触 PenguinHarness 的开发者。如果没有 AMD GPU,第五步之后的一节介绍了如何改用 Fireworks 额度。
+
+## 准备工作
+
+- 一块受 ROCm 支持的 AMD GPU,已安装 ROCm,显存足以装下约 24 GB 的 `qwen3.6:35b`。
+- 同一台机器上装有 Ollama。
+- 克隆好的 [PenguinHarness 仓库](https://github.com/Prism-Shadow/penguin-harness),以及 Node.js 24 或更高版本和 pnpm,用来运行第三步到第五步的两个示例。
+
+不需要云端账号,也不需要 API Key。
+
+## PenguinHarness 的架构
+
+PenguinHarness 是一个开源的 AI Agent Harness:一套用于构建和进化 Agent 的完整 TypeScript 技术栈,而不是某一个具体应用。它可以完全本地部署,最低单个 CPU 即可运行,并通过一个统一网关接入 1000 多个在线和本地模型。它的宗旨可以用一句话概括:
> Efficient Self-Improving Harness for Everyone.(为每个人打造的、高效的自我进化 Harness。)
-"Harness"(挽具 / 骨架)这个词是刻意选择的。它不是一个让你*在其之上*层层搭建的重型框架,而是一层轻薄、可靠、可观测的底座——Agent 可以*站在其中*运行,更关键的是,Agent 可以反过来触及并改进它自己。三大支柱承载了这一理念:
+「Harness」这个词是刻意选的。PenguinHarness 不是一个让你在其上层层搭建的重型框架,而是一层轻薄、可靠、可观测的底座:Agent 在其中运行,也能反过来触及并改进它。三大支柱承载了这一理念:
| 支柱 | 含义 |
| --- | --- |
-| **Simplest Is the Best(大道至简)** | 在干净的底层接口之上,提供刻意精简的工具集:更少的工具调用、更少的 Token、复杂任务高效完成。 |
-| **构建 Agent 的 Harness** | 既可用 SDK 编程构建(`createAgent` → `createSession` → `run`),也可由一个 Agent 根据一句需求描述,自动造出一个全新 Agent。 |
-| **递归自我进化的 Harness** | 借助 Skills,一个 Agent 能评估并优化*它自己*,随时间递归改进。 |
+| **Simplest Is the Best(大道至简)** | 在干净的底层接口之上,提供刻意精简的工具集:更少的工具调用、更少的 Token,高效完成复杂任务。 |
+| **构建 Agent 的 Harness** | 既可以用 SDK 编程构建(`createAgent` → `createSession` → `run`),也可以让一个 Agent 根据一句自然语言需求,替你构建一个全新的 Agent。 |
+| **递归自我进化的 Harness** | 借助 Skill,Agent 评估并优化自己,随时间递归改进。 |
-后两点,PenguinHarness 是业界首个开源实现。
+在后两根支柱上,PenguinHarness 是同类项目中第一个开源实现。
-## 架构,以及它为何长成这样
+### 一个内核,多个前端
-一次安装即可获得共享同一个数据目录和同一套消息协议的四层:
+一次安装即可得到四层结构,它们共享同一个数据目录和同一套消息协议:
```text
┌─────────────┐ ┌─────────────────────────────┐
@@ -46,57 +66,57 @@ PenguinHarness 是一个开源的 AI Agent Harness——一套用于*构建*和*
└──────────────────────────────────────────────┘
```
-系统的中心是 `@prismshadow/penguin-core` 里的执行引擎。CLI、Server、Web App 只是同一个引擎的不同"Human 实现"。这一个决定——单一内核、多前端——正是让整个系统保持自洽的关键,而它源自一组值得单独理解的设计信条。
+系统的中心是 `@prismshadow/penguin-core` 里的执行引擎。CLI、Server 和 Web App 只是同一个引擎的不同「Human 实现」。「单一内核、多个前端」这一个决定,让整个系统保持自洽。它源自几条设计原则,下面逐一介绍。
-### 一套协议,三重身份——OmniMessage
+### OmniMessage:一套协议,三种职责
-系统所做的一切都用同一种消息类型 OmniMessage 表达。它同时是:
+系统所做的一切,都用同一种消息类型 OmniMessage 表达。它同时是:
-- SDK 的对外接口(你输入的、以及流式返回的),
-- 磁盘上的 Trace 格式,
-- 引擎内部流转的"通货"。
+- SDK 的对外接口(你传入的消息和流式返回的消息);
+- 磁盘上的 Trace 格式;
+- 引擎内部流转的通用数据。
-换句话说,*实时流式的内容、落盘存储的内容、模型看到的内容,是字面意义上的同一个对象*。中间没有一个隐形的转换层在"实际发生了什么"和"被记录了什么"之间悄悄改写数据。正是这种"三位一体",构成了其余一切可观测性与可恢复性的根基。
+实时流出的内容、落盘存储的内容、模型看到的内容,是字面意义上的同一个对象。在「发生了什么」和「记录了什么」之间,没有一个隐形的转换层在悄悄改写数据。正是这种同一性,构成了系统其余部分所依赖的可观测性和可恢复性的基础。
### 三接口边界
-引擎只讲 OmniMessage,并在恰好三个边界之间编排信息流:
+引擎只认 OmniMessage,并在恰好三个边界之间编排信息流:
-- **Human**——用户侧。值得注意的是它*不是*一个类:SDK 唯一的入口 `session.run(newMessages, { approve, signal })` *就是* Human 边界。输入是一组新消息加一个审批回调,输出是一串流式消息。CLI 和 Server 是它的两个官方实现。
-- **LLM**——模型侧(`LLMInterface`)。所有与厂商相关的协议适配都活在 AgentHub 网关里;core 从不导入任何厂商 SDK。这正是为什么任何 OpenAI 兼容端点——包括本地端点——都能开箱即用。
-- **Environment**——工具侧(`EnvironmentInterface`)。执行已审批的工具调用并把结果流式返回。
+- **Human**:用户侧。它不是一个类:SDK 唯一的入口 `session.run(newMessages, { approve, signal })` 就是 Human 边界。输入是一组消息加一个审批回调,输出是一串流式消息。CLI 和 Server 是它的两个官方实现。
+- **LLM**:模型侧(`LLMInterface`)。所有与供应商相关的协议适配都放在 AgentHub 网关里,core 从不引入任何厂商 SDK。正因如此,任何 OpenAI 兼容端点(包括本地端点)都能直接使用。
+- **Environment**:工具侧(`EnvironmentInterface`)。它执行通过审批的工具调用,并把结果流式返回。
-因为内核不含任何 provider、工具或 UI 的具体细节,每一侧都仅靠配置即可替换。今天的本地 shell 可以变成明天的沙箱;一个 CLI 调用方可以换成 Web 调用方——core 始终不变。
+内核不包含任何供应商、工具或 UI 的具体细节,所以每一侧都只靠配置就能替换。今天的本地 shell 明天可以换成沙箱,CLI 调用方也可以换成 Web 调用方,core 始终不变。
### Agent 是可编辑的数据,不是代码
-一个 Agent 的全部行为——它的提示词、Skills、运行参数——都以磁盘上的可编辑文件形式存在(`agent_state/`),而非硬编码常量。这是整个项目安静而关键的一点:*你能看到的,Agent 就能改进*。自我进化不是引擎的某个特殊功能,而是一个 Agent 去编辑那些你本可以手动编辑的同一批文件,然后重新评估自己。
+Agent 的全部行为(提示词、Skill 和运行参数)都以可编辑文件的形式保存在磁盘上的 `agent_state/` 里,而不是写死的常量。这是整个项目的关键:你能看到的,Agent 就能改进。自我进化不是引擎的某个特殊功能,而是 Agent 去编辑那些你本来也可以手动编辑的文件,然后重新评估自己。第五步会展示这一点。
-### 贯穿始终的其余信条
+### 贯穿始终的设计原则
-- **错误收敛为消息。** 模型与工具的失败从不向引擎抛异常;它们会变成模型可以据此反应的消息。健壮性是协议的属性,而非散落各处的 try/catch。
-- **一切皆可观测。** 每一次请求、工具调用、审批决策都会追加进 Trace;一个 Session 可完整从中恢复。
-- **流式优先。** 文本逐 Token 流出;工具调用与结果实时呈现。
-- **模型与 Agent 解耦。** Agent 从不绑定模型——在创建每个 Session 时选择。同一个 Agent 可以在不同 Session 上跑不同模型。
+- 错误收敛为消息。模型和工具的失败从不向引擎抛出异常,而是变成模型可以据此应对的消息。健壮性是协议本身的属性,不靠散落各处的 try/catch。
+- 一切皆可观测。每一次请求、工具调用和审批决定都会追加进 Trace,Session 可以据此完整恢复。
+- 流式优先。文本逐 Token 流出,工具调用和结果实时呈现。
+- 模型与 Agent 解耦。Agent 从不绑定模型:模型在每个 Session 里单独选择,同一个 Agent 可以在不同的 Session 上跑不同的模型。
-分层的一句话总结:*可编辑或需记录的活在文件里;让消息流动的活在 SDK 里;需要常驻进程与多用户的活在 Server 里;其余的都是渲染。*
+这套分层可以用一句话总结:可编辑或需要记录的放在文件里;让消息流动的放在 SDK 里;需要常驻进程和多用户的放在 Server 里;其余都是渲染。
-## 大道至简——只有 6 个工具,以及这为何重要
+### 六个内置工具
-第一根支柱最容易被忽略,却是你在实际使用中感受最深的:工具集刻意做得极小。PenguinHarness 只内置恰好 6 个工具:
+第一根支柱最容易被忽略,实际使用中的感受却最深:工具集刻意做得极小。本文写作时,PenguinHarness 恰好只内置六个工具:
| 工具 | 用途 |
| --- | --- |
-| `exec_command` | 在工作区里执行 shell 命令(流式返回 stdout/stderr) |
-| `input_command` | 驱动一个运行中的命令——写 stdin、发 Ctrl-C、轮询输出 |
+| `exec_command` | 在 Workspace 里执行 shell 命令(流式返回 stdout/stderr) |
+| `input_command` | 操作运行中的命令:写入 stdin、发送 Ctrl-C、轮询输出 |
| `run_subagent` | 把一个自包含的子任务委派给子 Agent |
-| `input_subagent` | 轮询后台子 Agent,或在其空闲后追加提示 |
+| `input_subagent` | 轮询后台子 Agent,或向它追加提示 |
| `read_image` | 把图片作为图像内容读入(视觉模型) |
-| `describe_image` | 让视觉模型把图片描述成文本(供纯文本模型使用) |
+| `describe_image` | 让视觉模型把图片描述成文字(供纯文本模型使用) |
-注意这里*没有*什么:没有 `read_file`、没有 `write_file`、没有 `edit_file`、没有 `list_dir`、没有 `grep` 工具。这是刻意的——shell 就是通用接口,所以文件的读、写、改全部通过 `exec_command` 走(`cat`、`>`、`sed` 等等)。它遵循的原则就是"大道至简":每多一个工具,就是提示词里多一段 schema、每次调用多一些 token、模型多一个可能选错的选项。工具越少,选错越少、token 开销越小——复杂任务反而做得更利落。
+当时没有 `read_file`、`write_file`、`edit_file`、`list_dir` 或 `grep` 工具,这是有意为之。shell 就是通用接口,读、写、改文件全部通过 `exec_command` 完成(`cat`、`>`、`sed` 等)。每多一个工具,提示词里就多一段 schema,每次调用都多花一些 Token,模型也多一个可能选错的选项。工具越少,选错的调用越少,Token 开销也越小。
-这不只是理论——你可以直接从 Trace 里读出来。下面就是那个 CSV 清洗 Case,Agent 完成整个任务所做的全部 3 次工具调用,全都是 `exec_command`:
+这一点可以直接从 Trace 里读出来。下面是一个 Agent 完成一道 CSV 清洗题目时的全部三次工具调用,全都是 `exec_command`:
```bash
# 1. 读输入——没有 read_file 工具,直接 cat
@@ -118,19 +138,64 @@ for r in cleaned:
cat users_clean.csv
```
-读文件、做转换、核对结果——3 次调用、1 个工具、没有任何专用文件机制。再留意第二步:正因为接口是一个 shell,模型很自然地用起了 Python 来表达去重逻辑——这是任何固定的 `edit_file` 工具都做不到的。精简的工具集不是模型需要绕过的限制;它恰恰*正是*一个有能力的模型能用极少步骤完成真实任务的原因。
+读文件、做转换、核对结果:三次调用、一个工具,没有任何专用的文件机制。再看第二次调用:正因为接口是 shell,模型很自然地用 Python 写出了去重逻辑,这是任何固定的 `edit_file` 工具都做不到的。精简的工具集不是模型需要绕过的限制;有能力的模型之所以能用这么少的步骤完成真实任务,靠的正是它。
+
+## 第一步:安装 PenguinHarness
+
+用一行安装命令安装 PenguinHarness:
+
+```bash
+curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
+```
+
+安装完成后就有了 `penguin` CLI,下一步用它注册本地模型。
-## 用 Agent 造 Agent——一个完整的例子
+## 第二步:在 AMD GPU 上部署 qwen3.6:35b
-这就是第二根支柱——构建 Agent 的 Harness——的具体呈现。它有两面。第一面是 SDK:你用几行代码就能把一个 Agent 嵌进自己的程序——`createAgent()` → `createSession()` → `session.run(...)`(文末有代码片段)。第二面更惊艳,也正是"Agent 是可编辑的数据"的另一面:如果一个 Agent 不过是一堆文件,那么*一个 Agent 就能替你把这些文件写出来*。这正是内置 `agent-creation` skill 所做的事——给它一句大白话需求,一个 Agent 就能搭建出一个全新的 Agent:它的目录布局、它的 `system_config.yaml`(名称与描述),以及最关键的 `AGENTS.md`——那个把需求变成行为的文件。为了把这第二面端到端地展示出来,我们就在本地 AMD GPU 这套技术栈上真跑了一次。
+这一步用 Ollama 部署一个本地模型,并在 PenguinHarness 中注册它。
-**需求。** 我们让本地的 `qwen3.6:35b`,通过 `agent-creation` skill:
+模型是 `qwen3.6:35b`,一个能力不俗的本地开源权重模型:约 24 GB 的 MoE,总参数量 36B,Q4_K_M 量化。在 ROCm 下,Ollama 能原生识别 AMD GPU,无需设置任何架构 override,就能把模型加载进显存。这条路径覆盖 AMD 受 ROCm 支持的整个产品线,从 Radeon PRO 工作站显卡(如 W7900,48 GB,RDNA3)一直到数据中心的 Instinct 加速卡。
-> 创建一个叫 `commit-helper` 的新 Agent,专门写 Conventional Commits 提交信息——`type(scope): subject` 的标题(type 取自 feat/fix/docs/…)、祈使句、subject 控制在约 50 字符内,空一行,然后是一段解释"为什么"的正文。
+启动 Ollama 并拉取模型:
-**它产出了什么。** 这个 Agent 自主完成了:创建新 Agent 的目录、复制一份 base config、设置名称与描述,并写出了一份质量相当高的 `AGENTS.md`——涵盖了标题格式、type 枚举、subject 长度规则、正文"解释 why 而非 what"、可选的 `BREAKING CHANGE`/`Closes #` 脚注,甚至还有一条"从 diff 推断 type"的启发式(例如"重命名 → refactor 而非 chore")。内容层面完全没有需要人工提点。
+```bash
+ollama serve & # 若尚未作为服务运行
+ollama pull qwen3.6:35b
+```
+
+然后在 PenguinHarness 中注册这个模型,并设为默认模型:
+
+```bash
+penguin config model add \
+ --model-id qwen3.6:35b \
+ --provider custom --client-type openai \
+ --base-url http://localhost:11434/v1 \
+ --api-key ollama --set-default
+```
-**然后我们运行了它造出来的这个 Agent。** 给刚创建的 `commit-helper` 一段改动描述("给支付客户端加了带退避的重试,因为网关偶发的 503 导致下单失败"),它——只依据为它写的那份 `AGENTS.md`——产出了:
+一条命令就够了,因为 core 对任何 OpenAI 兼容端点一视同仁,而 Ollama 正好在 `http://localhost:11434/v1` 提供这样一个端点。
+
+## 第三步:让 Agent 构建新 Agent
+
+这一步由一个 Agent 替你构建新 Agent,第二根支柱「构建 Agent 的 Harness」在这里落到实处。
+
+这根支柱有两面。第一面是 SDK:几行代码就能把 Agent 嵌进你自己的程序,即 `createAgent()` → `createSession()` → `session.run(...)`(见文末的「后续步骤」)。第二面源于「Agent 是可编辑的数据」:既然 Agent 不过是一组文件,Agent 就能替你把这些文件写出来。内置的 `agent-creation` Skill(0.2.4 起更名为 `agent-initialization`)做的正是这件事。给它一句自然语言需求,Agent 就能搭建出一个新 Agent:目录结构、`system_config.yaml`(名称和描述),以及最关键的 `AGENTS.md`,也就是把需求变成行为的那个文件。
+
+仓库里的示例 [`examples/build-agent-with-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent) 把整个流程做成了一个自包含、由 SDK 驱动的脚本,跑在本地 Ollama + qwen3.6:35b 上,不调用任何云端 API。一次性的 Ollama 配置见其 `README.md`。在仓库根目录运行:
+
+```bash
+pnpm install
+pnpm build
+pnpm --dir examples/build-agent-with-agent start
+```
+
+第一阶段,脚本通过 `createAgent`/`createSession`/`run` 驱动 `default_agent` 构建 `commit-helper`。本地的 `qwen3.6:35b` Agent 借助 `agent-creation` Skill,收到的请求是:
+
+> 创建一个叫 `commit-helper` 的新 Agent,专门写 Conventional Commits 提交信息:`type(scope): subject` 格式的标题(type 取自 feat/fix/docs/…),subject 用祈使句并控制在约 50 个字符以内,空一行,然后是一段解释为什么要改的正文。
+
+Agent 会自主创建新 Agent 的目录、复制一份基础配置、设置名称和描述,并写出一份质量相当高的 `AGENTS.md`。文件里写明了标题格式、type 枚举、subject 长度规则、正文要「解释为什么改,而不是改了什么」、可选的 `BREAKING CHANGE`/`Closes #` 脚注,甚至还有一条从 diff 推断 type 的经验规则(例如「重命名 → refactor,而不是 chore」)。内容上完全不需要人工提点。
+
+第二阶段,脚本加载这个新 Agent,让它处理一段改动描述:「给支付客户端加了带退避的重试,因为网关偶发的 503 导致下单失败」。刚创建好的 `commit-helper` 只依据为它写的 `AGENTS.md`,产出了:
```text
fix(payment): add retry-with-backoff for transient gateway 503 errors
@@ -141,66 +206,64 @@ exponential backoff gives the gateway time to recover, preventing
spurious user-facing errors without requiring manual retries.
```
-它甚至先"出声"权衡了这个改动到底算 `fix` 还是 `feat`,才最终定为 `fix`——这个行为完全来自它的父 Agent 为它写的 AGENTS.md。
+它甚至会先出声权衡这个改动算 `fix` 还是 `feat`,最后才定为 `fix`。这一行为完全来自父 Agent 为它写的 `AGENTS.md`。
-**你可以自己跑一遍。** 上面整个流程在仓库里有一个自包含、纯 SDK 驱动的脚本:
-[`examples/build-agent-with-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/build-agent-with-agent)。
-第一阶段用 `createAgent`/`createSession`/`run` 驱动 `default_agent` 造出 `commit-helper`;第二阶段加载这个新 Agent 并运行它——全部跑在本地 Ollama + qwen3.6:35b 上,不用任何云端 API。一次性的 Ollama 配置见其 `README.md`。
+## 第四步:测量基线
-## 自我进化,一句话概括
+这一步给一个 `AGENTS.md` 为空的 Agent 打分,而任务的规则它看不到。
-第三根支柱建立在同一个理念之上。因为 Agent 是可编辑的数据、且一切皆被追踪,一个 Agent 可以*度量自己并变得更好*——这是一个"定基准 → 评估 → 找到失分点 → 编辑 Agent 自己的文件 → 只有分数提升才保留"的循环。它背后没有任何专用引擎代码,就是由 Skills 编排的普通 Agent 机制,而 scoreboard 上的每一个数字都能追回到产生它的那次具体 Session。我们会在下面这次运行之后,用一次真实的前后对比,把整个循环走一遍。
+任务看起来平平无奇:读一个项目笔记文件,写一份摘要,包含 2 句概述和恰好 3 条要点,并遵守团队的标准报告格式。关键全在最后这个要求。所谓「团队格式」是一套随意定下的内部约定:一行特定的标记、一个 `# Report: <subject>` 标题、一行 `Classification: INTERNAL`,以及一行 `Reviewed-by: Aurora Team` 页脚。它只写在 Agent 的 `AGENTS.md` 里,从任务本身推断不出来。
-## 在 AMD GPU 上的一次真实本地运行
+任务附带一份私有评分细则,也就是 Agent 永远看不到的一份检查清单,满分 10 分:
-设计信条说起来容易。下面是一次真正践行了这些信条的端到端运行,全程在完全本地、开源权重、AMD GPU 的环境上进行——每一个 Token 都在本机生成,不向任何云端 API 发送。
+- 5 分给内容,任何有能力的模型仅凭任务本身就能拿到;
+- 5 分给约定,只有从 `AGENTS.md` 里才能得知。
-**环境。** 一块 AMD GPU 运行 ROCm,通过 Ollama 的 OpenAI 兼容端点提供 `qwen3.6:35b`——一个能力不俗的本地开源权重模型(约 24 GB 的 MoE,36B 总参数,Q4_K_M 量化)。Ollama 原生识别到该 AMD GPU(无需任何架构 override),并把模型加载进显存。这条路径覆盖 AMD 受 ROCm 支持的整个产品线——从 Radeon PRO 工作站显卡(如 W7900,48 GB,RDNA3)一直到数据中心的 Instinct 加速卡。把它接入 PenguinHarness 只需一条命令,正因为 core 对任何 OpenAI 兼容端点一视同仁:
+仓库里的示例 [`examples/self-improving-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/self-improving-agent) 把这个任务和随后的改进闭环做成了一个自包含、由 SDK 驱动的脚本。它使用一份确定性的、可读的评分细则,同样是这 10 分;跑在同一套本地 Ollama + qwen3.6:35b 环境上;并使用一个专用的 Agent id,不会动到你自己的 Agent。在仓库根目录启动:
```bash
-penguin config model add \
- --model-id qwen3.6:35b \
- --provider custom --client-type openai \
- --base-url http://localhost:11434/v1 \
- --api-key ollama --set-default
+pnpm --dir examples/self-improving-agent start
```
-**任务,以及如何评分。** 我们给它一个看似平平无奇的任务:读一个项目 notes 文件,写一份含 2 句概述和恰好 3 条要点的摘要——*并遵守团队的标准报告格式。* 玄机全在最后这句:这个“团队格式”是一套任意的内部约定——一行特定 marker、一个 `# Report: <subject>` 标题、一行 `Classification: INTERNAL`、一行 `Reviewed-by: Aurora Team` 页脚——它*只存在于 Agent 的 `AGENTS.md` 里*,无法从任务本身推断。任务附带一份私有 rubric——一份 Agent 永远看不到的清单——共 10 分:5 分是任何有能力的模型仅凭任务就能拿到的内容分,另外 5 分是只能从 `AGENTS.md` 得知的约定分。
+脚本报告的第一个分数就是基线。`AGENTS.md` 为空时,模型写出的摘要相当合理,却稳定地丢掉全部 5 个约定分,落在 4.6 / 10 左右。具体数字每次运行会有波动。本地模型的输出有随机性,所以脚本对每个版本取多次运行的平均分,这也正是真实的 Benchmark 要设置 `runs` 次数的原因。
+
+模型别无选择。任务里没有任何信息透露这套内部约定,所以这是**信息缺口,而不是能力缺口**,这也是更强的模型同样无法「自己想出来」的原因。每一步都记录在 Trace 里,打开这次运行,就能准确看到丢了哪几分。
+
+这就是诚实的起点:在本地硬件上,一个开箱即用的 Agent,面对规则写在它尚未学过的文件里的任务,并不能拿到满分。而一个可测量、可审计、可复现的失败,Agent 可以通过自学系统地修复,下一步就会展示。
+
+## 第五步:让 Agent 自我进化
-**基线——以及它为何不是满分。** 跑在本地 AMD GPU 上、`AGENTS.md` 为空时,这个模型写出了一份相当合理的摘要——却稳定丢掉全部 5 个约定分,落在 **4.6 / 10** 左右(具体数字每次运行会有波动)。它别无选择:任务里没有任何东西透露那套内部约定,所以这是*信息缺口,不是能力缺口*——也正是为什么更强的模型也没法“自己想出来”。而因为每一步都在 Trace 里,这不是靠猜——你可以打开这次运行,精确看到哪些分被丢了。
+这一步,同一次运行会继续进入自我进化闭环。诊断和修改都由 Agent 自己完成,没有人把答案交给它。
-这就是诚实的起点:在本地硬件上,一个开箱即用的 Agent,面对规则藏在它尚未学过的文件里的任务,并不能一次拿满分。而这恰恰让下一节变得有意思——一个可度量、可审计、*可复现*的失败,Agent 可以通过自学来系统性修复。
+这个闭环有五个阶段。背后没有任何特殊的引擎代码,只是由 Skill 编排的普通 Agent 机制:
-## 自我进化到底是怎么运作的——附一次真实的前后对比
+1. Benchmark:定义能力题目,每道题配一份私有评分细则,和第四步一样。
+2. 评估:让 Agent 跑这些题目,并按评分细则打分。每一次运行都是一个普通的、全程留有 Trace 的 Session。
+3. 读 Trace,找出丢分点:每个分数都能追溯到具体的那次运行,所以你不只知道丢了分,还能看到为什么丢分。
+4. 编辑 Agent State:Agent 的行为保存在可编辑的文件里(`AGENTS.md`、Skill、配置)。由你或一个 Optimizer Agent 针对失败修改这些文件,产出版本 N+1。
+5. 打快照,然后保留或回滚:每轮开始前先打快照;只有分数严格提升才保留 N+1,否则回滚。
-上面那个 4.6 / 10 是一次*评估*——是这个 Agent 当前状态的一张快照。更有意思的问题是:PenguinHarness 如何把这张快照变成进步。这就是递归自我进化循环,值得作为一种"机制"来理解,因为它背后没有任何魔法引擎代码——它就是由 Skills 编排的普通 Agent 机制:
+在这个示例里,脚本只提供失败信号和通过审核的示例报告,并报告每一轮分数有没有提升,从不自己写入那套约定。
-1. **Benchmark(定基准)**——定义能力 Case,每个都配一份私有 rubric(如上)。
-2. **Evaluate(评估)**——让 Agent 跑这些 Case 并按 rubric 打分。每一次运行都是一个普通的、被完整追踪的 Session。
-3. **读 Trace 定位失分点**——因为每个分数都能追回到那次具体运行,你能看到某一分*为什么*被扣,而不只是"被扣了"。
-4. **编辑 Agent 的状态**——Agent 的行为活在可编辑文件里(`AGENTS.md`、Skills、config)。你(或一个 Optimizer Agent)针对失分点去改这些文件,产出版本 N+1。
-5. **快照 & 保留或回滚**——每轮前先打快照;只有当分数*严格提升*时才保留 N+1,否则回滚。
+### 第一轮:学会结构
-我们就来改进上一节里那个 Agent——同一个 `qwen3.6:35b`、同一块 AMD GPU、同一个刚拿了 4.6 / 10 的任务。关键之处在于:诊断和编辑都是 *Agent* 自己做的——我们并不把答案递给它。
+Agent 只拿到两个文件,别无其他:它刚被退回的那份报告,以及另一个项目里一份通过审核的报告。没有人告诉它规则。它对比两份报告,推断出可复用的内部约定:标记、标题形式、元数据行和署名页脚。这正是「读 Trace,找出丢分点」这个阶段,只不过由 Agent 亲自完成。
-- **诊断(由 Agent 完成)。** 我们只给 Agent 两个文件,别无其他:它刚被拒的那份报告,以及*另一个*项目里一份通过了评审的报告。没有人告诉它规则。它对比两者,自己推断出可复用的内部约定——marker、标题形态、元数据行、签名页脚。这就是"读 Trace 定位失分点"那一步,只不过由 Agent 亲自完成。
-- **编辑(N → N+1),由 Agent 撰写。** Agent 把刚推断出的约定写进它自己的 `AGENTS.md`。从单一范例里它能正确还原出*结构*,但还分不清哪些 token 是固定常量、哪些是每份报告要替换的字段(单个范例本就有歧义),于是把 marker 泛化成了占位符。重新评估,分数升到约 **6.6 / 10**。没有重新训练、没有改代码——Agent 编辑的是一份它每次运行都会读的文本文件。
-- **递归(N+1 → N+2)。** 现在我们再给它*多份*来自不同项目、却共享同一 marker 和签名的通过报告。Agent 推断出:凡是在所有样本里都完全相同的,必是固定常量;于是它读取自己*上一轮*写的 N+1 `AGENTS.md` 并精炼它——把 `<!-- ACME-DATA-PLATFORM -->` 和 `Reviewed-by: Aurora Team` 锁定为字面量。再评估一次:约 **9.8 / 10**。这才是真正意义上的递归:`state_{n+1} = agent.reflect(state_n, 新证据)`。
+随后,Agent 把推断出的约定写进自己的 `AGENTS.md`,得到版本 N+1。从单个示例里,它能正确还原出结构,但还分不清哪些词是固定常量、哪些是每份报告各不相同的字段,因为单个示例本身就有歧义。于是它把标记泛化成了占位符。再次评估,分数升到约 6.6 / 10。没有重新训练,也没有改代码:Agent 改的只是一份它每次运行都会读取的文本文件。
-在同一个模型、同一个任务上,仅仅由 Agent 自己编辑一份它会读取的文本文件,分数就走出了 **4.6 → 6.6 → 9.8** 的轨迹(数字每次运行会有波动)——而且 harness 每一轮都只因分数严格提升才保留。这就是自驱动的循环:*Agent 能看到的,Agent 就能改进*——用一份 rubric 度量、关联着 Trace,不是拍脑袋。
+### 第二轮:锁定常量
-**你可以自己跑一遍。** 整个循环在仓库里有一个自包含、纯 SDK 驱动的脚本:
-[`examples/self-improving-agent/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples/self-improving-agent)。
-它用一份确定性的、可读的 rubric(10 分:5 分内容分、5 分只存在于 `AGENTS.md` 的内部约定分),并且——因为本地模型有随机性——对每个版本跑多次取平均分,这正是真实 benchmark 里 `runs`(多次运行)的意义所在。关键在于:脚本从不自己写那套约定;是 *Agent* 从一份通过范例里诊断出缺口,并编辑自己的 `AGENTS.md`。在我们的运行中,平均分沿着 **4.6 → 6.6 → 9.8** 走过两轮自撰改进(先学到结构、再锁定常量),harness 每一轮都只因分数严格提升才保留。它跑在同一套本地 Ollama + qwen3.6:35b 环境上,并使用一个专用 agent id,所以你自己的 Agent 不会被动到。
+接下来,Agent 看到多份来自不同项目、共用同一个标记和署名页脚的合格报告。它推理出:凡是在所有报告里都完全相同的部分,必然是固定常量。于是它读取自己上一轮写的 N+1 版 `AGENTS.md` 并加以完善,把 `<!-- ACME-DATA-PLATFORM -->` 和 `Reviewed-by: Aurora Team` 锁定为字面量。再次评估,分数达到约 9.8 / 10。这才是真正意义上的递归:`state_{n+1} = agent.reflect(state_n, new_evidence)`。
-## 还没有 AMD GPU?来自 AMD + Fireworks 的免费云端算力
+两轮都让分数严格提升,这正是第 5 阶段保留修改的条件。
-不是每个人桌下都有一块 AMD GPU——而要试用这一切,你并不需要它。通过 AMD AI Developer Program,AMD 与 Fireworks AI 合作,向符合条件的开发者提供**价值 50 美元的免费 Fireworks 额度**。Fireworks 通过 OpenAI 兼容端点提供开源权重模型,因此——和上面的本地 Ollama 一样——把 PenguinHarness 指向它也只是一行配置的事。
+## 没有 AMD GPU?改用 Fireworks 额度
-领取额度(审核通常需要 2–3 个工作日)可参阅 [Fireworks API 获取指南](https://penguin.ooo/blog/fireworks-credits-amd),了解额度兑换和 API Key 获取步骤。
+想动手试试,不一定需要 AMD GPU。通过 AMD AI Developer Program,AMD 与 Fireworks AI 合作,向符合条件的开发者提供价值 50 美元的免费 Fireworks 额度。Fireworks 通过 OpenAI 兼容端点提供开源权重模型,所以和本地 Ollama 一样,把 PenguinHarness 指向它也只需改一行配置。
+领取额度(审核通常需要 2–3 个工作日)的步骤,请参阅 [Fireworks API 获取指南](https://penguin.ooo/blog/fireworks-credits-amd),里面详细介绍了额度兑换和 API Key 的获取方法。
-之后像接入任何其他端点一样把它接进 PenguinHarness:
+然后像接入其他端点一样,在 PenguinHarness 中注册 Fireworks:
```bash
penguin config model add --model-id <fireworks-模型-id> \
@@ -209,15 +272,29 @@ penguin config model add --model-id <fireworks-模型-id> \
--api-key <你的-fireworks-key> --set-default
```
-同一套 Harness、同样的一行切换——无论 Token 是在你自己的 AMD GPU 上生成,还是用 AMD 支持的云端额度生成。(请妥善保管优惠码与 Key;项目条款可能变动,具体以官方页面和审核邮件为准。)
+无论 Token 是在你自己的 AMD GPU 上生成,还是用 AMD 支持的云端额度生成,Harness 都不变,一行配置的切换方式也不变。请妥善保管优惠码和 API Key。计划条款可能变动,具体以官方页面和审核邮件为准。
-## 这为什么重要
+## 结果
-- **本地优先不是口号。** 一个完整的"构建 → 运行 → 自我评估"闭环在本机、在一块 AMD GPU 上跑通,没有数据离开机器——这是对隐私敏感与企业场景的真实回答。而且因为它跑在 ROCm + Ollama 之上,同一套配置可覆盖 AMD 的整个 GPU 阵容:单块 Radeon PRO 工作站显卡(如 48 GB 的 W7900)从 8B 到 30B 以上的模型都能从容运行,而 Instinct 加速卡则可进一步向上扩展。
-- **薄模型层带来实际收益。** 因为 provider 适配完全活在网关里,"一个本地 Ollama 模型"和"一个前沿云端 API"只是同一处一行配置的差别。你不会被某个厂商锁定——也不会被某个 GPU 厂商锁定。我们这次跑在 AMD GPU(ROCm)上,但这里没有任何 AMD 专属的东西:同样的步骤在 NVIDIA GPU(Ollama 的 CUDA 后端)或 Apple Silicon 上一样成立——底层变的只是 Ollama 运行时,而 Harness、命令、example 全都保持不变。
-- **可观测性内建于每一处。** 这次本地运行产生了与任何云端运行相同的只追加 Trace 与 scoreboard 关联。评估在设计上就是可审计的。
+在我们的运行中,同一个模型、同一个任务的分数是这样爬升的,具体数字每次运行都会有波动:
-## 立即开始
+| 版本 | Agent 写进 `AGENTS.md` 的内容 | 分数 |
+| --- | --- | --- |
+| N(基线) | 无,文件为空 | 约 4.6 / 10 |
+| N+1 | 约定的结构,标记仍是占位符 | 约 6.6 / 10 |
+| N+2 | 同一套约定,常量已锁定为字面量 | 约 9.8 / 10 |
+
+分数的提升,完全来自 Agent 编辑了一份它每次都会读取的文本文件。这次运行说明了三点:
+
+- 本地优先在 AMD 硬件上切实可行。完整的「构建 → 运行 → 自我评估」闭环在本机的一块 AMD GPU 上跑通,没有数据离开机器,这对隐私敏感的场景和企业环境是一个实实在在的答案。由于它建立在 ROCm + Ollama 之上,同一套配置适用于 AMD 的整个 GPU 产品线:单块 Radeon PRO 工作站显卡(如 48 GB 的 W7900)就能从容运行 8B 到 30B 以上的模型,Instinct 加速卡还能进一步向上扩展。
+- 薄模型层带来实际收益。供应商适配全部放在网关里,所以「本地 Ollama 模型」和「前沿云端 API」之间只差一行配置。你不会被某个厂商锁定,也不会被某个 GPU 厂商锁定。我们这次跑在 AMD GPU(ROCm)上,但这里没有任何 AMD 专属的东西:同样的步骤在 NVIDIA GPU(Ollama 的 CUDA 后端)或 Apple Silicon 上一样可行。变的只是底层的 Ollama 运行时,Harness、命令和示例都保持不变。
+- 可观测性处处内建。本地运行产生的只追加 Trace 和记分板关联,与任何云端运行完全相同,记分板上的每个数字都能追溯到产生它的那个 Session。评估从设计上就是可审计的。
+
+## 后续步骤
+
+这一路下来,你在 AMD GPU 上部署了本地模型,让一个 Agent 构建了 `commit-helper`,还看到一个 Agent 通过编辑自己的 `AGENTS.md` 提高了分数。
+
+整套配置只需三条命令,适用于任何 OpenAI 兼容端点,包括本地 Ollama 模型:
```bash
curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
@@ -230,7 +307,7 @@ penguin config model add --model-id <你的模型> \
penguin web # 或:penguin run --approve allow-all --message "..."
```
-想把它嵌进自己的程序?这就是"构建 Agent"支柱的 SDK 那一面——核心循环就是三次调用:
+想把 Agent 嵌进自己的程序,就用「构建 Agent」这根支柱的 SDK 那一面。核心循环只有三次调用:
```ts
const agent = await createAgent({ agentId: "default_agent" });
@@ -238,6 +315,4 @@ const session = await agent.createSession({ workspaceDir: process.cwd() });
for await (const out of session.run([userText("...")], { approve: async () => "allow" })) { /* 流式处理 */ }
```
-完整、可运行的版本见 [`examples/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples)——包括一个"用 Agent 造 Agent"和一个"自我改进的 Agent",都跑在本地 Ollama 上。
-
-无论你跑的是前沿云端模型,还是自己 AMD GPU 上的开源权重模型,PenguinHarness 都为你提供同一套精简、可观测、可自我进化的底座。在 [GitHub](https://github.com/Prism-Shadow/penguin-harness) 关注我们,并提交你的第一个 issue。
+完整、可运行的版本见 [`examples/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/examples),其中包括一个构建其他 Agent 的 Agent 和一个自我进化的 Agent,都跑在本地 Ollama 上。在 [GitHub](https://github.com/Prism-Shadow/penguin-harness) 关注我们,提交你的第一个 issue。
diff --git a/packages/landing/content/blog/natural-language-training-loop.en.md b/packages/landing/content/blog/natural-language-training-loop.en.md
index e6040990..1d06757c 100644
--- a/packages/landing/content/blog/natural-language-training-loop.en.md
+++ b/packages/landing/content/blog/natural-language-training-loop.en.md
@@ -1,143 +1,185 @@
---
-title: "Let the agent drive Ollama, vLLM and LlamaFactory: a data-safe self-closing training loop"
+title: "Ask the agent to serve, evaluate and fine-tune a local model with Ollama, vLLM and LlamaFactory"
date: 2026-07-22
category: practice
-excerpt: PenguinHarness 0.1.1 ships the ollama, vllm and llamafactory skills. They are not three more command-line tools for you to learn — they are what the agent already knows, so "serve a model here, then fine-tune it until it passes my evaluation" becomes something you say rather than something you type. This post is mostly about why this harness drives those three tools well: what ships in the box, what it costs per request, and why the loop closes at all. The data in it never leaves your environment.
+excerpt: "Ask a PenguinHarness agent to serve a model with Ollama or vLLM, measure it with a Benchmark, fine-tune it with LlamaFactory and measure it again. You write two requests, approve tool calls and provide the training data, and with a local model driving the agent, your data never leaves your environment."
---
-Three skills landed in 0.1.1: `ollama`, `vllm`, `llamafactory`. The easy misreading is that PenguinHarness now expects you to learn three more command-line tools.
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
-It is the opposite. The skills are not written for you — they are written for the agent, and the entire reason they exist is that you stop running the commands. You say what you want in a sentence; the agent picks the tool, asks the questions it is required to ask, runs the thing, checks that it worked, and tells you what happened.
+PenguinHarness 0.1.1 ships three Skills for working with models on your own hardware: `ollama`, `vllm` and `llamafactory`. They are not three more command-line tools for you to learn. They are written for the agent, so that you stop running the commands. You say what you want in a sentence, and the agent picks the tool, asks the questions it is required to ask, runs the commands, checks that they worked and tells you what happened.
-This post is about what that changes, in three parts:
+In this tutorial you use them to close a training loop on your own hardware. You send the agent two messages: the first asks it to serve a model, the second to fine-tune that model until it passes an evaluation. The agent serves the model, builds a Benchmark and measures a baseline, fine-tunes the model on the training data you point it to, redeploys it and measures again. You answer its questions, approve its tool calls, provide the training data and read the scoreboard. The commands shown along the way are what the agent ran, not a checklist for you.
-1. **The interface is a sentence.** What you type, and what the agent then does on its own.
-2. **Why *this* harness drives these three tools well.** Six things that are in the box rather than in your head, each one a file you can open.
-3. **The loop closes, and nothing you care about goes out.** Serve → evaluate → fine-tune → redeploy → measure again, on your hardware, with your weights.
+The tutorial is for anyone who wants to serve, evaluate and fine-tune models on their own hardware and keep their data where they put it. At the end, the base model and its fine-tuned successor are both registered and compared on one scoreboard. If a local model also drives the agent (Step 3), your data never leaves your environment.
-Everything attributed to the agent here is behavior a shipped skill actually specifies. The skills are plain Markdown and you can read them yourself under `packages/skills/skills/`. Where a skill stops and you take over, this post says so rather than pretending.
+Every agent behavior described here is specified by a Skill that ships with PenguinHarness. Skills are plain Markdown files, under `packages/skills/skills/` in 0.1.1, so you can read what the agent will do before you ask. Where a Skill stops and you take over, this tutorial says so.
-## 1. "Run a local model on this machine — I don't want the data going anywhere"
+This is the loop you are about to run:
-That sentence is the whole input. Here is what happens on the other side of it.
+```text
+ ┌──────────────────────────────────────────────┐
+ │ │
+serve the model → run the benchmark → read the failing traces
+ (vllm/ollama) (benchmark-design + (session ids from
+ agent-evaluation) the scoreboard)
+ ↑ │
+ │ ↓
+ redeploy ← merge and export ← fine-tune on what it got wrong
+ (vllm) (llamafactory) (llamafactory)
+```
-**The agent loads the `ollama` skill and asks two questions before touching anything.** Not out of politeness: the skill forbids running any command until the goal is clear. It asks which model you want to run — and if you have no preference it proposes a small default, Qwen3.5-0.8B, with the reminder that the model has to fit the machine's RAM or VRAM. It asks which engine you prefer, because that choice is genuinely yours: Ollama is the simple default and the only option on macOS or a CPU-only box, while vLLM is for high-throughput GPU serving.
+## Prerequisites
-**Then it looks before it leaps.** The skill's first rule is to check the current state — is Ollama installed, is something already serving — and if port 11434 already has an instance, to reuse it and never kill it. That is the same instinct 0.1.1 baked into the default system prompt: never kill a process you did not start; when a port is busy, take another one.
+- PenguinHarness. This tutorial follows 0.1.1, the release that added the `ollama`, `vllm` and `llamafactory` Skills. Later releases moved the Skills into plugins and changed some names and flag values, so newer versions differ in the details; the agent follows the Skills of the version you install.
+- A model configured for the agent itself to run on. It can be a hosted API or a local model; Step 3 explains the difference.
+- A machine to serve the model. Ollama is the simple default and the only option on macOS or a CPU-only machine; vLLM is for high-throughput serving on a GPU.
+- A GPU for fine-tuning with LlamaFactory. LoRA needs far less GPU memory than full fine-tuning.
+- Network access to download installs and model weights. Serving, training and evaluation upload none of your data; the one exception is the model that drives the agent, covered in Step 3.
-**Then it does the boring parts you would have gotten wrong.** It installs Ollama if missing, pulls the model, and raises the context window — the step people skip and then spend an afternoon debugging, because Ollama's default window is small and agent sessions are not. The skill gives it both ways to do that: `OLLAMA_CONTEXT_LENGTH` in the server environment, or `num_ctx` baked into a model variant with a Modelfile.
+## Step 1: Install PenguinHarness and open the Web App
-**Then it verifies, and only then registers.** A pulled model is invisible to PenguinHarness until it is added, and model configuration is the CLI's job:
+Install PenguinHarness and start the Web App:
```bash
-# what the agent ran — not a checklist for you
-curl http://localhost:11434/v1/models
-
-penguin config model add --provider custom --client-type openai \
- --base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollama
-penguin config model list
+curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
+penguin web
```
-The details in that command are decisions, not boilerplate, and the `penguin-cli` skill is where the agent learned them. A model in PenguinHarness is the `(provider, model_id)` pair and the group is **never** inferred from the id — gateways resell vendor models under their upstream ids, so a guess could send your key to somebody else's endpoint; `custom` is the group for any endpoint outside the built-in ones. `--client-type openai --base-url <endpoint>` is the shape for any OpenAI chat-completion compatible server. And `--api-key ollama` is not decoration: Ollama accepts any key, but the field must be non-empty.
+`penguin web` opens the Web App in your browser. The first time, sign in as the built-in admin: in 0.1.1 the login page shows the initial password, while later releases print a one-time sign-in link in the terminal instead. If the model the agent runs on is not configured yet, add it on the Models page and set it as the default model.
-If the local model has a small context window, the agent also has a reason to cap its output — `--max-tokens` is a per-model cap, new in 0.1.1, that overrides the Agent default of 32,000, which on its own does not fit in a 32k window alongside any prompt at all.
+Click **New chat**, then set the chat's approval mode to **Ask every time**. A new chat approves every tool call automatically by default; with **Ask every time**, each call waits for your **Allow** or **Deny**, which is how this tutorial keeps you in the loop. You send the next request from this chat.
-You did not run any of that. You approved it — each tool call, as it came. That is the first of the three places a human is still genuinely in the loop, and it is there on purpose.
+## Step 2: Ask the agent to serve a local model
-## 2. Why this harness drives these three tools well
+Send this message:
-Any capable agent with a shell can, in principle, run `vllm serve`. The interesting question is what it takes to get from *in principle* to a session that works the first time, and how much of that you had to supply. Six answers, each one a file in this repo rather than an adjective.
+> Run a local model on this machine — I don't want the data going anywhere
-**One: the knowledge ships in the box.** `packages/skills/skills/vllm/SKILL.md`, `.../ollama/SKILL.md` and `.../llamafactory/SKILL.md` are part of the Skill library, and a project's `default_agent` is created with the whole library installed — not fetched, not configured, not pasted in by you. So on a fresh install the agent already knows that vLLM has to be started with `--enable-auto-tool-choice` and a `--tool-call-parser` matched to the model family or every tool call comes back a `400`; that Ollama's default context window is too small for agent sessions, and both ways to raise it; that a LoRA adapter must never be merged into a quantized base. None of that is exotic — it is exactly the set of things you find out by losing an afternoon to them.
+That sentence is the whole input. The agent loads the `ollama` Skill and works through the rest:
-<details>
-<summary><strong>Expand: some of what the three skills already know</strong></summary>
+1. It asks two questions before touching anything, because the Skill forbids running any command until the goal is clear. First, which model to run: if you have no preference, it proposes a small default, Qwen3.5-0.8B, and reminds you that the model has to fit the machine's RAM or VRAM. Second, which engine: Ollama is the simple default and the only option on macOS or a CPU-only machine, while vLLM is for high-throughput GPU serving. That choice is yours.
+2. It checks the current state. Is Ollama installed, and is something already serving? If port 11434 already has an instance, the agent reuses it and never kills it. The 0.1.1 default system prompt carries the same rule: never kill a process you did not start, and when a port is busy, take another one.
+3. It installs Ollama if it is missing, pulls the model, and raises the context window, the step people skip and then spend an afternoon debugging: Ollama's default window is small, and agent Sessions are not. The Skill gives two ways to raise it: `OLLAMA_CONTEXT_LENGTH` in the server environment, or `num_ctx` baked into a model variant with a Modelfile.
+4. It verifies the endpoint, and only then registers the model. A pulled model is invisible to PenguinHarness until it is added, and model configuration is the CLI's job:
-Straight from the shipped `SKILL.md` files — this is the class of detail that is already in the agent's reach before you say anything:
+ ```bash
+ # what the agent ran — not a checklist for you
+ curl http://localhost:11434/v1/models
-- **vLLM, tool calling.** `vllm serve <model> --enable-auto-tool-choice --tool-call-parser hermes`, with the parser chosen for the model family (`hermes` for Qwen, `llama3_json` for Llama). Without it: `400 "auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set` on every agent request.
-- **vLLM, out of memory at startup.** Lower `--gpu-memory-utilization` or `--max-model-len`, or serve a quantized model.
-- **Ollama, context.** `OLLAMA_CONTEXT_LENGTH=32768 ollama serve`, or `PARAMETER num_ctx 32768` in a Modelfile plus `ollama create`.
-- **Ollama, an instance already running.** Port 11434 in use means reuse it — never kill a serving process you did not start.
-- **LlamaFactory, merging.** Merge the adapter into the base weights for standalone serving, never into a quantized base.
-- **Registering the result.** `--provider custom --client-type openai --base-url <endpoint>`; a served model is invisible to Penguin until it is added.
+ penguin config model add --provider custom --client-type openai \
+ --base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollama
+ penguin config model list
+ ```
-</details>
+You do not run any of these commands. You answer the two questions and approve each tool call as it comes, with **Allow** or **Deny**; the approval mode you set in Step 1 is what makes each call wait for you. In the SDK, the same approval gate is a callback, and an app that supplies none has every tool call denied.
-**Two: knowing many tools costs almost nothing per request.** Skills have no dedicated tool and are not concatenated into the prompt. The system prompt template carries a `{{SKILL_METADATA}}` placeholder, and assembly replaces it with one line per installed skill — `` - `vllm` — Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint… `` — while the body is read from disk with a shell command only when a task matches. In 0.1.1 that is fifteen skills whose metadata lines total about 2.5 KB, against skill bodies totalling over 100 KB that never enter a context window until they are needed. Deep knowledge of a tool you are not using this turn is not a tax you pay every request.
+### What the registration command means
-**Three: it operates the real CLIs, because that is all it has.** A session's built-in tools are `exec_command`, `input_command`, `run_subagent`, `input_subagent` and one image tool. There is no read-file tool, no write-file tool, and no per-vendor integration: `exec_command`'s own description tells the model to read, write and edit files and run programs with the shell. That constraint is the feature here. `vllm serve`, `ollama pull` and `llamafactory-cli train` need no adapter written for them, the flags in the skills are the tools' real flags rather than whatever subset a wrapper exposed, and when vLLM adds a flag next month the fix is a Markdown edit, not a release of this harness.
+The details in that command are decisions, and the `penguin-cli` Skill is where the agent learned them:
-**Four: the loop closes because registration is part of the job.** Serving a model and *being able to use* it are two different facts, and the gap between them is where most "the agent set it up for me" demos quietly end. The `penguin-cli` skill closes it: it teaches the agent that an endpoint is invisible until `penguin config model add` registers it, and — the part that actually matters — *which* data root to register it into. `--root` must point at the app's own data directory (`--root ./penguin_data`, the same path the app hands `createAgent({ root })`) when the agent is building an app; the default root is for Penguin's own model. So the model the agent just served becomes a model it can then run on, deliberately, in the right place. That is the difference between a loop and a demo.
+- A model in PenguinHarness is the `(provider, model_id)` pair, and the group is never inferred from the id. Gateways resell vendor models under their upstream ids, so a guess could send your key to somebody else's endpoint. `custom` is the group for any endpoint outside the built-in ones.
+- `--client-type openai --base-url <endpoint>` is the shape for any OpenAI chat-completion compatible server.
+- `--api-key ollama` is not decoration: Ollama accepts any key, but the field must be non-empty.
-**Five: measuring is a shipped capability, not an exercise for the reader.** `benchmark-design`, `agent-evaluation` and `agent-optimization` are in the same library, installed the same way. Executing is not improving; "fine-tune it until it passes" needs something that can say *passes*. Part 3 is what those three do.
+The Skill also covers two flags that this command does not use:
-**Six: the two stories are one story.** The reason the agent can drive these tools at all is that it drives them by running commands on the machine that holds the data. There is no hosted control plane in the middle that would need to see your dataset in order to orchestrate the run. "Local" is not a feature bolted onto this design; it is the same fact as "it can use the real CLI".
+- `--max-tokens` is a per-model output cap, new in 0.1.1, that overrides the agent default of 32,000. That default does not fit in a 32k window alongside any prompt, so with a small local context window the agent has a reason to set it.
+- `--root` chooses the data root. When the agent builds an app, `--root` must point at the app's own data directory (`--root ./penguin_data`, the same path the app hands `createAgent({ root })`). The default root is for the model PenguinHarness itself runs on, and it is where this tutorial registers the model. Registering in the right place is what closes the loop: the model the agent just served becomes a model the agent itself can run on.
-**And the honest version of all six.** None of this says another agent cannot do these things. Give any competent shell-using agent the same instructions and it will serve the model too. The difference is smaller and checkable than a superlative: with PenguinHarness those instructions are already installed, cost about 2.5 KB of prompt to have available, and include the registration step that makes the served model usable afterwards. Elsewhere, you are the one who has to know it — and know it again next session.
+## Step 3 (optional): Keep the whole loop local
-## 3. "Now fine-tune it until it passes my evaluation"
+From the next step on, the agent works with your data: it reads evaluation Cases, Traces and your training set. One choice decides whether any of that leaves your machine: the model that drives the agent. If the agent runs on a hosted API, the conversation itself goes to that vendor, even though the model it tunes is local. That includes your instructions, the file contents the agent reads and the tool output it summarizes.
-This is the sentence that makes the loop close, and it only works because of the word *evaluation*. There is no self-improving anything without a number, and a single run is not a number.
+To keep everything on your machine, make the endpoint the agent just served PenguinHarness's own default model too, with the same `penguin config model add ...` command plus `--set-default`. Ask the agent to run it, or run it yourself. In 0.1.1 a chat keeps the model it started with, so send the Step 4 request from a new chat, and name the model you served, because the new chat does not know what happened in Step 2. The loop then runs end to end without a third party in it.
-```text
- ┌──────────────────────────────────────────────┐
- │ │
-serve the model → run the benchmark → read the failing traces
- (vllm/ollama) (benchmark-design + (session ids from
- agent-evaluation) the scoreboard)
- ↑ │
- │ ↓
- redeploy ← merge and export ← fine-tune on what it got wrong
- (vllm) (llamafactory) (llamafactory)
-```
+This is a real trade-off: a small local model driving the whole loop is not the same proposition as a frontier model driving it. Make it a decision, not an assumption.
-**The agent builds the measurement first.** `benchmark-design` has it lay out a Benchmark: a set of Cases, each with a public statement the tested agent sees and a private rubric it must never see, plus the scoreboard the results land in. Each Case runs more than once by default, because one sample from a nondeterministic local model is not a measurement. `agent-evaluation` runs each of those Case runs in isolation and returns nothing but protocol metadata — a score, a cost, a duration, a session id — which is how the rubric stays out of the tested agent's context.
+## Step 4: Ask for a fine-tune that must pass your evaluation
-**Which gives the agent something to read, not just a number.** Every evaluation records the `(provider, model_id)` pair that produced it, so the base model and its tuned successor land on the same scoreboard and compare directly. And every run carries its session id, so the agent can open the exact trace and see which step lost the point. That is the whole reason "fine-tune on what it got wrong" is a sentence with a referent.
+Send the second message:
-**Then it fine-tunes.** The `llamafactory` skill has it confirm four things before training — available GPU memory (LoRA needs far less than full fine-tuning), the base model, the dataset and its format, and the goal, with LoRA SFT as the usual starting point. It registers the dataset in `data/dataset_info.json` in alpaca or sharegpt form, writes a training config derived from the shipped `examples/train_lora/qwen3_lora_sft.yaml`, runs `llamafactory-cli train`, and tries the result interactively before trusting it.
+> Now fine-tune it until it passes my evaluation
-**Then it redeploys and measures again.** The adapter gets merged into the base weights and exported. vLLM serves the export directory directly; Ollama needs an import first. When the agent serves it, the `vllm` skill has already told it the flag that everyone forgets — the tool-calling pair from part 2. The tuned endpoint gets registered as its **own** model id rather than overwriting the base one, precisely so both stay on the scoreboard, and then the same Benchmark runs again.
+This sentence closes the loop, and it works because of the word *evaluation*. Nothing improves itself without a number, and a single run is not a number. So the agent builds the measurement first, with the `benchmark-design` Skill:
-That is the loop, and none of the steps between "serve" and "measure again" required you to name a command.
+- It lays out a Benchmark: a set of Cases, each with a public statement that the tested agent sees and a private rubric that it must never see, plus the scoreboard the results land in.
+- It needs the agent under test and the capability being measured, and asks you for either one that is missing.
+- Each Case runs more than once by default, because one sample from a nondeterministic local model is not a measurement.
+- The `agent-evaluation` Skill runs each Case run in isolation and returns only protocol metadata: a score, a cost, a duration and a Session id. That is how the rubric stays out of the tested agent's context.
-**One seam, stated plainly.** Turning failing traces into training examples is the step the skills do *not* prescribe. `llamafactory` asks where your dataset lives and what format it is in; it does not teach an agent to mine a trace into an SFT file. The agent can read the traces, and it can write the conversion script if you ask it to — but that is you directing it, not a skill driving it. Anyone telling you this part is already automatic is selling something.
+The result gives the agent more to read than a number. Every evaluation records the `(provider, model_id)` pair that produced it, so the base model and its tuned successor land on the same scoreboard and compare directly. Every run carries its Session id, so the agent can open the exact Trace and see which step lost the point. That is what gives "fine-tune on what it got wrong" something concrete to refer to.
-## 4. Where the human still stands
+## Step 5: Provide the training data and fine-tune with LlamaFactory
-Three places, and they are not accidents:
+Before training, the `llamafactory` Skill has the agent confirm four things with you:
-- **Approving tool calls.** Every tool call is gated. In the SDK that gate is literally a callback, and omitting it denies everything — the default is refusal, not permission.
-- **The judgment calls.** Which base model. Which engine. What "good enough" means. All three serving and tuning skills are written to *ask* rather than assume, and `benchmark-design` requires you to name the agent under test and the capability being measured before it will start. If you also want the agent itself improved rather than the weights, `agent-optimization` works from the same scoreboard — and it refuses to touch Agent State until a snapshot exists to roll back to.
-- **The dataset seam** from the end of part 3.
+- the available GPU memory (LoRA needs far less than full fine-tuning),
+- the base model,
+- the dataset and its format,
+- the goal, with LoRA SFT as the usual starting point.
-Everything else — which flags, which port, which parser, whether to reuse the running server, what to do about `400 … tools must not be an empty array` (upgrade to 0.1.1, which stopped sending an empty tool list) or an out-of-memory at vLLM startup — is in the skills, which means it is in the agent.
+The dataset is yours to provide. Turning failing Traces into training examples is the one step the Skills do not prescribe: the `llamafactory` Skill asks where your dataset lives and what format it is in, but it does not teach the agent to mine a Trace into an SFT file. Point the agent at your dataset. If you want the failing Traces turned into training data, ask the agent to write the conversion script: it can read the Traces and write the script, but that is you directing it, not a Skill driving it.
-## 5. Data never leaves your environment
+Then the agent registers the dataset in `data/dataset_info.json` in alpaca or sharegpt form, writes a training config derived from LlamaFactory's bundled `examples/train_lora/qwen3_lora_sft.yaml`, runs `llamafactory-cli train`, and tries the result interactively before trusting it.
-This is the reason the whole arrangement is worth the trouble, so it deserves precision rather than a slogan.
+## Step 6: Redeploy and measure again
-**Local, in this setup:**
+The agent merges the adapter into the base weights and exports the result. vLLM serves the export directory directly; Ollama needs an import first. When the agent serves the export with vLLM, the `vllm` Skill has already told it the flags everyone forgets: `--enable-auto-tool-choice` and a `--tool-call-parser` matched to the model family.
-- **The served model.** Ollama exposes its OpenAI-compatible API on `http://localhost:11434/v1`; vLLM on `http://localhost:8000/v1`. Both are on the machine. Every prompt, tool schema, tool result and completion in an agent session against them stays on the loopback interface.
-- **The training.** LlamaFactory runs on your GPU. Your dataset sits under `data/` next to `data/dataset_info.json`; the adapter and the merged export land under `saves/`. No stage of `llamafactory-cli train` ships your examples anywhere.
-- **The evaluation.** Cases, statements and rubrics are files in your project — a rubric lives at a path like `~/.penguin/data/default_project/agents/tool-router/benchmarks/tool-routing-v1/CASE-003-pick-the-cheaper-endpoint/rubric/README.md` — and the evaluator reads them from disk. The scoreboard is a YAML file next to them.
-- **The configuration.** `penguin config model add` writes into a single hidden project config file. It is CLI-managed, never hand-edited, and it stays where you point it.
+The agent registers the tuned endpoint as its own model id rather than overwriting the base one, so both stay on the scoreboard. Then the same Benchmark runs again, and you compare the two results on the scoreboard. None of the steps between serving and measuring again required you to name a command.
-**What does cross the network:** installs and weights, coming *in*. `ollama pull`, `pip install vllm`, cloning LlamaFactory, resolving a Hugging Face base model id — all of them download. None of them upload your data. It is worth being clear about the direction, because "local" is often quietly claimed for setups that phone home.
+If you want to improve the agent itself rather than the weights, the `agent-optimization` Skill works from the same scoreboard. It refuses to touch Agent State until a snapshot exists to roll back to.
-**And the one thing that decides everything else:** the model that drives the agent. If the agent is running on a hosted API, then the conversation itself — your instructions, the file contents it reads, the tool output it summarizes — goes to that vendor, no matter how local the model it is tuning. The fully-local configuration is a deliberate choice you make: point the harness's own default model at the local endpoint too, with the same `penguin config model add ... --set-default`, and the loop runs end to end without a third party in it. It is a real trade-off — a small local model driving the whole loop is not the same proposition as a frontier model driving it — and it should be a decision, not an assumption.
+## How the pieces fit
-## What actually changed
+Three facts explain why the agent can run this loop, and each one is backed by a file you can open.
-Before this release, PenguinHarness could talk to any OpenAI-compatible endpoint but had nothing to say about where that endpoint came from. Standing one up, measuring what it could do, and fixing what it could not were three different tools with three sets of conventions, and a human in between translating.
+### The knowledge ships with the agent
-Now they are one system, and the human's job moved. You describe the outcome. The agent serves the model, runs its own benchmark, reads its own failures, tunes, redeploys, and measures again — choosing each next step from the last result. You approve the calls, make the judgment calls, and read the scoreboard.
+In 0.1.1, `packages/skills/skills/vllm/SKILL.md`, `.../ollama/SKILL.md` and `.../llamafactory/SKILL.md` are part of the Skill library, and a Project's `default_agent` is created with the whole library installed. You do not fetch, configure or paste anything. The Skills that measure and improve, `benchmark-design`, `agent-evaluation` and `agent-optimization`, are in the same library and installed the same way. On a fresh install the agent already knows that vLLM must start with `--enable-auto-tool-choice` and a `--tool-call-parser` matched to the model family, or every tool call comes back a `400`; that Ollama's default context window is too small for agent Sessions, and both ways to raise it; and that a LoRA adapter must never be merged into a quantized base. These are the details people otherwise lose an afternoon to.
-On your hardware. On your weights. With your data staying where you put it.
+### Knowing many tools costs almost nothing per request
-```bash
-curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
-penguin web
-```
+Skills have no dedicated tool and are not pasted into the prompt. The system prompt template carries a `{{SKILL_METADATA}}` placeholder, which assembly replaces with one line per installed Skill, such as `` - `vllm` — Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint… ``. The agent reads a Skill's body from disk with a shell command only when a task matches. In 0.1.1 that is fifteen Skills whose metadata lines total about 2.5 KB, while their bodies total over 100 KB and stay out of the context window until they are needed.
+
+### The agent operates the real CLIs
+
+In 0.1.1, a Session's built-in tools are `exec_command`, `input_command`, `run_subagent`, `input_subagent` and one image tool. There is no read-file tool, no write-file tool and no per-vendor integration: `exec_command`'s own description tells the model to read, write and edit files and run programs with the shell. So `vllm serve`, `ollama pull` and `llamafactory-cli train` need no adapter, the flags in the Skills are the tools' real flags, and when vLLM adds a flag, the fix is a Markdown edit, not a release of the harness. This is also why the loop can stay local: the agent runs commands on the machine that holds the data, with no hosted control plane in between that would need to see your dataset.
+
+Another capable agent with a shell could do these things too, given the same instructions. The difference is that in PenguinHarness the instructions are already installed, cost about 2.5 KB of prompt, and include the registration step that makes a served model usable afterwards. Elsewhere you have to know all of it yourself, again in every Session.
+
+## Troubleshooting
+
+The failures below are already written into the Skills, so the agent knows how to handle them. They are listed here so you recognize them when they appear in a Session:
+
+- vLLM rejects every tool call: the server was started without the tool-calling flags. Restart it with `vllm serve <model> --enable-auto-tool-choice --tool-call-parser hermes`, choosing the parser for the model family (`hermes` for Qwen, `llama3_json` for Llama). Without it, every agent request fails with `400 "auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set`.
+- vLLM runs out of memory at startup: lower `--gpu-memory-utilization` or `--max-model-len`, or serve a quantized model.
+- Ollama's context window is too small: start the server with `OLLAMA_CONTEXT_LENGTH=32768 ollama serve`, or put `PARAMETER num_ctx 32768` in a Modelfile and run `ollama create`.
+- Ollama is already running: port 11434 in use means reuse the instance, and never kill a serving process you did not start.
+- Merging a LoRA adapter: merge the adapter into the base weights for standalone serving, but never into a quantized base.
+- A served model does not show up in PenguinHarness: it stays invisible until it is added, so register it with `--provider custom --client-type openai --base-url <endpoint>`.
+
+One more error comes from the harness rather than from a Skill. Before 0.1.1, requests that carried no tools still sent an empty tool list, which vLLM rejects with `400 … tools must not be an empty array`; 0.1.1 stopped sending it, so upgrading fixes the error.
+
+## What stays on your machine
+
+In this setup, these stay local:
+
+- The served model. Ollama exposes its OpenAI-compatible API on `http://localhost:11434/v1`, and vLLM on `http://localhost:8000/v1`. Every prompt, tool schema, tool result and completion in an agent Session against them stays on the loopback interface.
+- The training. LlamaFactory runs on your GPU. Your dataset sits under `data/` next to `data/dataset_info.json`, and the adapter and the merged export land under `saves/`. No stage of `llamafactory-cli train` ships your examples anywhere.
+- The evaluation. Cases, statements and rubrics are files in your Project, and the evaluator reads them from disk. A rubric lives at a path like `~/.penguin/data/default_project/agents/tool_router/benchmarks/tool-routing-v1/CASE-003-pick-the-cheaper-endpoint/rubric/README.md`, and the scoreboard is a YAML file next to them.
+- The configuration. `penguin config model add` writes into a single hidden Project config file. The CLI manages it, it is never edited by hand, and it stays where you point it.
+
+If a local model drives the agent, only installs and weights cross the network, and they come in. `ollama pull`, `pip install vllm`, cloning LlamaFactory and resolving a Hugging Face base model id all download; none of them upload your data. If a hosted model drives the agent, the conversation also goes to that vendor, as Step 3 describes.
+
+## Wrap-up
+
+Before 0.1.1, PenguinHarness could talk to any OpenAI-compatible endpoint but had nothing to say about where that endpoint came from. Standing one up, measuring what it could do and fixing what it could not were three tools with three sets of conventions, and a person in between translating.
+
+In this tutorial you described two outcomes. The agent served a model, ran its own Benchmark, read its own failures, fine-tuned, redeployed and measured again, choosing each next step from the last result. You stayed in the loop in three places: approving tool calls, making the judgment calls (which base model, which engine, what counts as good enough), and providing the training data. Everything else, from flags and ports to parsers and whether to reuse a running server, is in the Skills, which means it is in the agent.
+
+Where to go next:
+
+- Read the Skills the agent had available, as they shipped in 0.1.1, under [`packages/skills/skills/`](https://github.com/Prism-Shadow/penguin-harness/tree/v0.1.1/packages/skills/skills).
+- If a hosted model drove the agent this time, run the loop again with a local model driving it, as described in Step 3.
diff --git a/packages/landing/content/blog/natural-language-training-loop.zh.md b/packages/landing/content/blog/natural-language-training-loop.zh.md
index 01e3b305..6044c286 100644
--- a/packages/landing/content/blog/natural-language-training-loop.zh.md
+++ b/packages/landing/content/blog/natural-language-training-loop.zh.md
@@ -1,143 +1,185 @@
---
-title: 让 Agent 来操作 Ollama、vLLM、LlamaFactory,做数据安全的模型训练自闭环
+title: "让 Agent 用 Ollama、vLLM 和 LlamaFactory 部署、评估并微调本地模型"
date: 2026-07-22
category: practice
-excerpt: PenguinHarness 0.1.1 新增了 ollama、vllm、llamafactory 三个技能。它们不是三个要你去学的命令行工具,而是 Agent 本来就会的东西——于是「在这里部署一个模型,再把它微调到能过我的评测」变成了你说的一句话,而不是你敲的一串命令。本文主要讲的是:为什么这套 Harness 能把这三个工具用好——什么是开箱就有的、每次请求要付多少代价、以及闭环凭什么合得上。而整个过程中的数据不出你自己的环境。
+excerpt: "让 PenguinHarness 的 Agent 用 Ollama 或 vLLM 部署模型,用 Benchmark 衡量效果,再用 LlamaFactory 微调,然后重新衡量。你只需写两条请求、审批工具调用、提供训练数据;如果驱动 Agent 的也是本地模型,数据就始终不离开你的环境。"
---
-0.1.1 带来了三个技能:`ollama`、`vllm`、`llamafactory`。最容易的误读是:PenguinHarness 现在要你再学三个命令行工具。
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-恰恰相反。这些技能不是写给你的,是写给 Agent 的;它们存在的全部理由,就是让你不再敲这些命令。你用一句话说清楚要什么,Agent 自己选工具、问该问的问题、执行、验证,然后把结果讲给你听。
+PenguinHarness 0.1.1 新增了三个 Skill:`ollama`、`vllm` 和 `llamafactory`,用来在你自己的硬件上部署和微调模型。它们并不意味着你又要多学三个命令行工具。这三个 Skill 是写给 Agent 的,目的正是让你不必再亲手敲这些命令。你用一句话说出想要什么,Agent 就会选好工具,把该问的问题问清楚,执行命令,确认命令生效,再告诉你结果。
-本文分三部分:
+在这篇教程里,你会用它们在自己的硬件上跑通一个训练闭环。你给 Agent 发两条消息:第一条让它部署模型,第二条让它把模型微调到能通过评估为止。Agent 会部署模型,创建 Benchmark 并测出基线,用你指定的训练数据微调模型,重新部署,再测一次。你只需回答它的问题、审批它的工具调用、提供训练数据、查看记分板。文中出现的命令都是 Agent 执行过的,不是留给你照做的清单。
-1. **接口是一句话。** 你输入什么,Agent 随后自己做了什么。
-2. **为什么这套 Harness 能把这三个工具用得更好。** 六件写在仓库文件里、而不是留在你脑子里的事。
-3. **闭环合得上,而且数据不出域。** 部署 → 评测 → 微调 → 重新部署 → 再测一次,跑在你自己的硬件与权重上。
+本教程适合想在自己的硬件上部署、评估和微调模型,又希望数据留在原处的人。做完之后,基座模型和微调后的模型都已注册,并在同一张记分板上对比。如果驱动 Agent 的也是本地模型(见第三步),你的数据就始终不会离开你的环境。
-下文中归给 Agent 的每一项行为,都是已发布技能里真实写明的规则。这些技能就是普通的 Markdown,你可以自己去 `packages/skills/skills/` 下读。哪里是技能的边界、需要你接手,本文照实说明,不粉饰。
+文中 Agent 的每一种行为,都写在 PenguinHarness 自带的某个 Skill 里。Skill 就是普通的 Markdown 文件,0.1.1 里放在 `packages/skills/skills/` 下,发请求之前,你就能先读到 Agent 会怎么做。Skill 管不到、需要你接手的地方,教程会明确指出。
-## 一、「在这台机器上跑一个本地模型,数据不要出去」
+你即将跑通的闭环如下:
-这句话就是全部输入。以下是它另一端发生的事。
+```text
+ ┌───────────────────────────────────────────────┐
+ │ │
+ 部署模型 → 跑评测 → 读失败的 Trace
+ (vllm/ollama) (benchmark-design + (记分板里的 session id)
+ agent-evaluation)
+ ↑ │
+ │ ↓
+ 重新部署 ← 合并并导出 ← 针对失分微调
+ (vllm) (llamafactory) (llamafactory)
+```
-**Agent 加载 `ollama` 技能,并在动手之前先问两个问题。** 这不是客气:技能明确规定目标不清楚之前不许执行任何命令。它问你要跑哪个模型——你没有偏好时,它会推荐一个小默认值 Qwen3.5-0.8B,并提醒模型必须装得进机器的内存或显存。它还问你偏好哪个引擎,因为这个选择确实属于你:Ollama 是简单默认项,也是 macOS 与纯 CPU 机器上的唯一选择;vLLM 面向高吞吐的 GPU 部署。
+## 准备工作
-**然后它先看、再动。** 技能的第一条规则就是先确认当前状态——Ollama 装了没有、是不是已经在提供服务;如果 11434 端口上已经有实例,就复用它,绝不杀掉。这也正是 0.1.1 写进默认系统提示词的那条:绝不杀死不是自己启动的进程,端口被占就另选一个。
+- PenguinHarness。本教程对应 0.1.1,也就是新增 `ollama`、`vllm` 和 `llamafactory` 三个 Skill 的版本。之后的版本把 Skill 挪进了插件,也改过一些名称和参数取值,所以新版本在细节上会有出入;Agent 始终按你所装版本自带的 Skill 行事。
+- 一个供 Agent 自身运行的模型。托管 API 或本地模型都可以,两者的区别见第三步。
+- 一台用来部署模型的机器。Ollama 是简单的默认选择,也是 macOS 或纯 CPU 机器上的唯一选项;vLLM 适合在 GPU 上做高吞吐部署。
+- 一块用于 LlamaFactory 微调的 GPU。LoRA 需要的显存远少于全量微调。
+- 网络连接,用来下载安装包和模型权重。部署、训练和评估都不会上传你的数据,唯一的例外是驱动 Agent 的模型,见第三步。
-**然后它把你多半会做错的那几步做对。** 缺了就装 Ollama,拉取模型,并调大上下文窗口——这一步最常被跳过,然后花一个下午排查,因为 Ollama 默认的窗口很小,而 Agent 会话不小。技能给了它两条路:在服务环境里设 `OLLAMA_CONTEXT_LENGTH`,或者用 Modelfile 把 `num_ctx` 固化成一个模型变体。
+## 第一步:安装 PenguinHarness 并打开 Web App
-**然后它先验证,再注册。** 拉下来的模型在被添加之前,对 PenguinHarness 是不可见的,而模型配置是 CLI 的职责:
+安装 PenguinHarness 并启动 Web App:
```bash
-# 这是 Agent 执行过的命令,不是给你照做的清单
-curl http://localhost:11434/v1/models
-
-penguin config model add --provider custom --client-type openai \
- --base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollama
-penguin config model list
+curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
+penguin web
```
-这条命令里的每个细节都是判断,不是模板,而 Agent 是从 `penguin-cli` 技能里学到它们的。PenguinHarness 里的模型由 `(provider, model_id)` 二元组确定,分组**永远不**从模型 ID 推断——网关会用上游 ID 转售厂商模型,猜错就可能把你的 Key 发到别人的端点上;`custom` 是内置分组之外任何端点所属的分组。`--client-type openai --base-url <endpoint>` 是所有 OpenAI chat-completion 兼容服务的写法。而 `--api-key ollama` 不是装饰:Ollama 接受任何 Key,但这个字段必须非空。
+`penguin web` 会在浏览器里打开 Web App。第一次使用时,以内置管理员身份登录:0.1.1 的登录页上写着初始密码,之后的版本则改为在终端里打印一个一次性登录链接。如果还没有配置供 Agent 运行的模型,先在模型页添加,并把它设为默认模型。
-如果本地模型的上下文窗口很小,Agent 还有理由顺手限制输出——`--max-tokens` 是 0.1.1 新增的模型级上限,优先级高于 Agent 默认的 32,000;而这个默认值本身就塞不进 32k 窗口,更别提再加上提示词。
+点击**新对话**,再把这个对话的审批模式设为**总是询问**。新对话默认会自动放行所有工具调用;设为**总是询问**之后,每个工具调用都要等你点**允许**或**拒绝**,你在这篇教程里就是这样参与闭环的。下一步的请求就在这个对话里发送。
-以上没有一条是你跑的。你做的是逐条批准工具调用。这是人仍然实实在在留在环里的第一处,而且是有意为之。
+## 第二步:让 Agent 部署本地模型
-## 二、为什么这套 Harness 能把这三个工具用好
+发送这条消息:
-任何一个有 Shell 的能干 Agent,原则上都跑得动 `vllm serve`。真正的问题是:从「原则上可以」到「这一次会话第一遍就跑通」,中间要补多少东西,而其中又有多少得由你来补。下面六条回答,每一条对应仓库里的一个文件,而不是一个形容词。
+> 在这台机器上跑一个本地模型,数据不要出去
-**其一:这些知识是开箱就有的。** `packages/skills/skills/vllm/SKILL.md`、`.../ollama/SKILL.md`、`.../llamafactory/SKILL.md` 本身就属于技能库,而一个项目的 `default_agent` 在创建时会把整个技能库装上——不用去拉取、不用去配置,也不用你粘贴进去。所以在一台全新安装的机器上,Agent 已经知道:vLLM 必须带上 `--enable-auto-tool-choice` 和与模型家族匹配的 `--tool-call-parser` 启动,否则每一次工具调用都会返回 `400`;Ollama 的默认上下文窗口撑不住 Agent 会话,以及两种调大它的办法;LoRA 适配器绝不能合并到量化过的基座上。这些都不算冷门知识——它们恰好就是那种「搭进去一个下午才会知道」的知识。
+这句话就是全部输入。Agent 加载 `ollama` Skill,接下来的事由它完成:
-<details>
-<summary><strong>展开:三个技能里已经写着的一部分坑</strong></summary>
+1. 动手之前先问两个问题,因为 Skill 规定目标不清楚时不许执行任何命令。第一个问题是跑哪个模型:如果你没有偏好,它会推荐一个小的默认模型 Qwen3.5-0.8B,并提醒你模型必须装得进机器的内存或显存。第二个问题是用哪个引擎:Ollama 是简单的默认选择,也是 macOS 或纯 CPU 机器上的唯一选项;vLLM 面向 GPU 上的高吞吐部署。这个选择由你来定。
+2. 检查当前状态。Ollama 装了没有?是不是已经有服务在运行?如果 11434 端口上已经有实例,Agent 会复用它,绝不杀掉。0.1.1 的默认系统提示词里也写着同样的规则:绝不杀死不是自己启动的进程,端口被占用就换一个。
+3. 缺 Ollama 就安装,然后拉取模型、调大上下文窗口。调大窗口这一步最常被跳过,结果往往要花一个下午排查:Ollama 的默认窗口很小,而 Agent 会话需要的上下文很大。Skill 给了两种调大的办法:在服务的环境变量里设置 `OLLAMA_CONTEXT_LENGTH`,或者用 Modelfile 把 `num_ctx` 固化成一个模型变体。
+4. 先验证端点,再注册模型。拉取下来的模型要添加之后,PenguinHarness 才看得到,而模型配置归 CLI 管:
-以下直接来自已发布的 `SKILL.md`——这就是在你开口之前,Agent 就已经能够拿到的细节:
+ ```bash
+ # 这是 Agent 执行过的命令,不是给你照做的清单
+ curl http://localhost:11434/v1/models
-- **vLLM 的工具调用。** `vllm serve <model> --enable-auto-tool-choice --tool-call-parser hermes`,parser 按模型家族选(Qwen 用 `hermes`,Llama 用 `llama3_json`)。不带它,每一次 Agent 请求都会得到 `400 "auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set`。
-- **vLLM 启动时显存不足。** 调低 `--gpu-memory-utilization` 或 `--max-model-len`,或者改部署量化模型。
-- **Ollama 的上下文。** `OLLAMA_CONTEXT_LENGTH=32768 ollama serve`,或在 Modelfile 里写 `PARAMETER num_ctx 32768` 再 `ollama create`。
-- **Ollama 已经在跑。** 11434 端口被占就复用——绝不杀死一个不是自己启动的服务进程。
-- **LlamaFactory 的合并。** 为了能独立部署要把适配器合并进基座权重,但绝不合并到量化过的基座上。
-- **把结果注册回去。** `--provider custom --client-type openai --base-url <endpoint>`;模型部署起来之后,不添加就对 Penguin 不可见。
+ penguin config model add --provider custom --client-type openai \
+ --base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollama
+ penguin config model list
+ ```
-</details>
+这些命令一条都不用你来跑。你只需回答那两个问题,并在每个工具调用出现时点**允许**或**拒绝**;调用之所以会停下来等你,靠的正是第一步设置的审批模式。在 SDK 里,这道审批关卡是一个回调函数,应用如果不提供它,所有工具调用都会被拒绝。
-**其二:会用很多工具,几乎不增加每次请求的开销。** 技能没有专门的工具,也不会被整段拼进提示词。系统提示词模板里只有一个 `{{SKILL_METADATA}}` 占位符,装配时把它替换成每个已安装技能一行的元数据——形如 `` - `vllm` — Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint… ``——而技能正文要等任务真的对上了,才由模型用 Shell 命令从磁盘读进来。在 0.1.1 里,这是十五个技能、元数据合计约 2.5 KB,而它们的正文合计超过 100 KB,在被需要之前一个字都不进上下文窗口。对一个这一轮用不上的工具了解得很深,并不需要你每次请求都为它付费。
+### 注册命令各部分的含义
-**其三:它操作的就是真正的 CLI,因为它手里只有这个。** 一次会话的内置工具是 `exec_command`、`input_command`、`run_subagent`、`input_subagent`,外加一个图像工具。没有读文件工具,没有写文件工具,也没有任何按厂商定制的集成:`exec_command` 自己的描述就是让模型用 Shell 去读写编辑文件、运行程序。这个约束在这里恰恰是优点。`vllm serve`、`ollama pull`、`llamafactory-cli train` 不需要谁去写一层适配,技能里写的参数就是工具真正的参数,而不是某层封装挑出来的子集;等 vLLM 下个月加了新参数,要改的是一份 Markdown,而不是发一个 Harness 的新版本。
+这条命令里的每个细节都有讲究,Agent 是从 `penguin-cli` Skill 里学到的:
-**其四:闭环合得上,是因为「注册」本身就是工作的一部分。** 把模型部署起来,和**能用上**这个模型,是两件事;而大多数「Agent 帮我搭好了」的演示,正是在这条缝上悄悄结束的。`penguin-cli` 技能把它补上了:它告诉 Agent,端点在 `penguin config model add` 注册之前是不可见的;更关键的是,要注册到**哪个**数据根目录里。Agent 在开发一个应用时,`--root` 必须指向该应用项目内自己的数据目录(`--root ./penguin_data`,也就是应用传给 `createAgent({ root })` 的那个路径),而默认根目录是留给 Penguin 自身的模型的。于是它刚刚部署好的模型,就成了它接下来可以运行其上的模型——有意为之,且落在正确的位置。演示和闭环的差别就在这里。
+- PenguinHarness 里的模型由 `(provider, model_id)` 二元组确定,分组绝不从模型 id 推断。网关会用上游 id 转售厂商的模型,一旦猜错,你的 API Key 可能被发到别人的端点上。内置分组之外的任何端点,都归入 `custom` 分组。
+- 任何兼容 OpenAI chat completion 接口的服务,都用 `--client-type openai --base-url <endpoint>` 这种写法。
+- `--api-key ollama` 不是摆设:Ollama 接受任意 Key,但这个字段不能为空。
-**其五:「能衡量」是随包发布的能力,不是留给读者的练习。** `benchmark-design`、`agent-evaluation`、`agent-optimization` 在同一个技能库里,用同样的方式安装。执行不等于改进;「微调到能过」这句话,得先有个东西能说出「过了」。第三部分讲的就是这三个技能做了什么。
+这个 Skill 还讲了两个这条命令没有用到的参数:
-**其六:这两个故事其实是同一个故事。** Agent 之所以能驱动这些工具,正是因为它是在持有数据的那台机器上直接执行命令。中间没有一个托管的控制面,需要先看到你的数据集才能编排这次运行。「本地」不是给这套设计外挂上去的特性,它和「它能用真正的 CLI」是同一件事。
+- `--max-tokens` 是 0.1.1 新增的单模型输出上限,会覆盖 Agent 默认的 32,000。这个默认值再加上任何提示词,都放不进 32k 的窗口,所以本地模型的上下文窗口较小时,Agent 有理由设置它。
+- `--root` 决定注册到哪个数据根目录。Agent 在开发应用时,`--root` 必须指向应用自己的数据目录(`--root ./penguin_data`,也就是应用传给 `createAgent({ root })` 的那个路径)。默认根目录留给 PenguinHarness 自身运行所用的模型,本教程注册的也正是这里。注册到正确的位置,闭环才能合上:Agent 刚部署好的模型,成了它自己接下来就能用的模型。
-**以及这六条的诚实版本。** 以上没有一条是在说别的 Agent 做不到。把同样的说明喂给任何一个会用 Shell 的强 Agent,它也能把模型部署起来。差别比一句「最强」小得多,也更可核查:在 PenguinHarness 上,这些说明是已经装好的,代价是约 2.5 KB 的提示词,而且其中包含了那一步让模型在部署之后真正可用的注册。换到别处,得由你来知道这些——并且下一次会话还得再知道一遍。
+## 第三步(可选):让整个闭环留在本地
-## 三、「把这个模型微调到能过我的评测」
+从下一步开始,Agent 就要接触你的数据了:它会读评估题目、Trace 和你的训练数据。这些内容会不会离开你的机器,取决于一个选择:驱动 Agent 的模型。如果 Agent 跑在托管 API 上,那么即使它微调的模型完全在本地,对话本身也会发到那家供应商,包括你的指令、Agent 读到的文件内容和它转述的工具输出。
-正是这句话让闭环合上,而关键在「评测」两个字。没有数字就没有自我改进,而跑一次不算数字。
+要让一切都留在本机,就把 Agent 刚部署好的端点也设为 PenguinHarness 自身的默认模型:还是那条 `penguin config model add ...` 命令,加上 `--set-default`。可以让 Agent 来执行,也可以自己执行。在 0.1.1 里,一个对话会一直使用它开始时的模型,所以第四步的请求要在新对话里发送,并写明你部署的是哪个模型,因为新对话不知道第二步里发生了什么。这样整个闭环从头到尾都没有第三方参与。
-```text
- ┌───────────────────────────────────────────────┐
- │ │
- 部署模型 → 跑评测 → 读失败的 Trace
- (vllm/ollama) (benchmark-design + (记分板里的 session id)
- agent-evaluation)
- ↑ │
- │ ↓
- 重新部署 ← 合并并导出 ← 针对失分微调
- (vllm) (llamafactory) (llamafactory)
-```
+这是一个实实在在的取舍:由小型本地模型驱动整个闭环,和由前沿模型来驱动,完全是两回事。要不要这样做,应该是你想清楚之后的决定,而不是默认如此。
-**Agent 先把量具造出来。** `benchmark-design` 让它铺开一个 Benchmark:一组 Case,每个 Case 都有被测 Agent 能看到的公开 Statement 和它绝不能看到的私有 Rubric,以及结果落地的记分板。每个 Case 默认不止跑一次——对一个不确定的本地模型采样一次,算不上一次测量。`agent-evaluation` 负责隔离地执行每一次 Case 运行,且只返回协议元数据:分数、成本、耗时、session id。正是这份沉默让 Rubric 不进入被测 Agent 的上下文。
+## 第四步:让 Agent 微调模型,直到通过评估
-**于是 Agent 拿到的不只是一个数字。** 每次评估都记录产生它的 `(provider, model_id)` 二元组,基座模型与调优后的后继者因此落在同一张记分板上,可以直接比。而每一次 run 都带着自己的 session id,Agent 可以打开那次 Trace,看清是哪一步丢的分。「针对失分微调」这句话之所以有确切的所指,全靠这一点。
+发送第二条消息:
-**然后它开始微调。** `llamafactory` 技能要求它在训练前确认四件事:可用显存(LoRA 的需求远低于全参微调)、基座模型、数据集及其格式、以及目标——常规起点是 LoRA SFT。它把数据集按 alpaca 或 sharegpt 格式登记进 `data/dataset_info.json`,从随附的 `examples/train_lora/qwen3_lora_sft.yaml` 派生出训练配置,执行 `llamafactory-cli train`,并在信任结果之前先交互试一下。
+> 把这个模型微调到能过我的评估
-**然后它重新部署,再测一次。** 适配器被合并进基座权重并导出。vLLM 可以直接部署导出目录,Ollama 则需要先导入。部署时,`vllm` 技能早就告诉过它那个所有人都会忘的参数——就是第二部分里那对工具调用开关。调优后的端点被注册成**独立**的模型 ID,而不是覆盖基座——正是为了让两者都留在记分板上——然后同一个 Benchmark 再跑一遍。
+这句话让闭环合上,关键在「评估」两个字:没有数字就谈不上改进,而只跑一次也算不上数字。所以 Agent 先用 `benchmark-design` Skill 把测量搭起来:
-这就是闭环,而从「部署」到「再测一次」之间的每一步,都不需要你说出任何一条命令。
+- 它规划出一个 Benchmark:一组题目,每道题都有被测 Agent 能看到的公开题干,以及它绝不能看到的私有评分细则,外加记录结果的记分板。
+- 它需要知道被测 Agent 和要测量的能力,缺哪一项就向你询问哪一项。
+- 每道题默认运行不止一次,因为对不确定的本地模型只采样一次,算不上测量。
+- `agent-evaluation` Skill 隔离执行每道题的每次运行,只返回协议元数据:分数、成本、耗时和 Session id。评分细则正是这样被挡在被测 Agent 的上下文之外。
-**有一道缝,明说。** 把失败的 Trace 变成训练样本,是技能**没有**规定的一步。`llamafactory` 只问你数据集在哪、是什么格式,它并不教 Agent 如何从 Trace 里挖出一份 SFT 数据。Agent 能读 Trace,你让它写转换脚本它也能写——但那是你在指挥它,不是技能在驱动它。谁要是告诉你这一段已经全自动了,那多半是在卖东西。
+这样 Agent 拿到的就不只是一个数字。每次评估都记录产生它的 `(provider, model_id)` 二元组,基座模型和微调后的模型因此落在同一张记分板上,可以直接对比。每次运行都带着 Session id,Agent 可以打开对应的 Trace,看清是哪一步丢了分。「针对做错的地方微调」这句话,因此有了具体的所指。
-## 四、人还站在哪里
+## 第五步:提供训练数据,用 LlamaFactory 微调
-三个位置,都不是疏漏:
+训练开始前,`llamafactory` Skill 要求 Agent 跟你确认四件事:
-- **批准工具调用。** 每一次工具调用都要过闸。在 SDK 里这个闸就是一个回调函数,不提供它等于全部拒绝——默认是拒绝,而不是放行。
-- **只能由你做的判断。** 用哪个基座模型、用哪个引擎、多好才算「够好」。三个部署与调优技能都写成**先问**而不是替你假设;`benchmark-design` 也要求你先指明被测 Agent 与要衡量的能力才肯开始。如果你想改进的是 Agent 本身而不是权重,`agent-optimization` 基于同一张记分板工作——而且在存在可回滚的快照之前,它拒绝改动 Agent State。
-- **数据集那道缝**,见第三部分结尾。
+- 可用显存(LoRA 需要的显存远少于全量微调);
+- 基座模型;
+- 数据集及其格式;
+- 训练目标,通常从 LoRA SFT 起步。
-除此之外的一切——用哪些参数、哪个端口、哪个 parser、要不要复用已在运行的服务、遇到 `400 … tools must not be an empty array` 怎么办(升级到 0.1.1,它不再发送空工具列表)、vLLM 启动显存不足怎么办——都写在技能里,也就意味着都在 Agent 身上。
+数据集要由你来提供。把失败的 Trace 变成训练样本,是唯一一个没有 Skill 规定做法的环节:`llamafactory` Skill 只问你数据集放在哪、是什么格式,并不教 Agent 怎样从 Trace 里整理出 SFT 数据。把数据集的位置告诉 Agent。如果想把失败的 Trace 变成训练数据,可以让 Agent 写转换脚本:它能读 Trace,也能写脚本,但这是你在指挥它,不是 Skill 在驱动它。
-## 五、数据安全不出域
+随后,Agent 把数据集按 alpaca 或 sharegpt 格式登记到 `data/dataset_info.json`,参照 LlamaFactory 随附的 `examples/train_lora/qwen3_lora_sft.yaml` 写出训练配置,执行 `llamafactory-cli train`,并先交互试用训练结果,确认可信再使用。
-这才是整套安排值得折腾的理由,所以它需要的是精确,而不是口号。
+## 第六步:重新部署,再测一次
-**这套配置下留在本地的部分:**
+Agent 把适配器合并进基座权重并导出。vLLM 可以直接部署导出目录,Ollama 则需要先导入。用 vLLM 部署导出结果时,`vllm` Skill 早就告诉过 Agent 那对人人都会忘的参数:`--enable-auto-tool-choice`,以及与模型系列匹配的 `--tool-call-parser`。
-- **被部署的模型。** Ollama 在 `http://localhost:11434/v1` 暴露 OpenAI 兼容 API,vLLM 在 `http://localhost:8000/v1`。两者都在本机。对它们发起的 Agent 会话里,每一条提示词、工具 Schema、工具结果与补全,都留在本地回环接口上。
-- **训练。** LlamaFactory 跑在你自己的 GPU 上。数据集放在 `data/` 下、与 `data/dataset_info.json` 相邻;适配器与合并后的导出落在 `saves/`。`llamafactory-cli train` 的任何阶段都不会把你的样本发出去。
-- **评测。** Case、Statement 与 Rubric 都是你项目里的文件——一份 Rubric 的路径形如 `~/.penguin/data/default_project/agents/tool-router/benchmarks/tool-routing-v1/CASE-003-pick-the-cheaper-endpoint/rubric/README.md`——评估者从磁盘读取它们,记分板是与之相邻的一份 YAML。
-- **配置。** `penguin config model add` 写入一份隐藏的项目配置文件。它只由 CLI 管理、从不手工编辑,而且你指到哪它就待在哪。
+Agent 把微调后的端点注册成独立的模型 id,不覆盖基座模型,这样两者都留在记分板上。然后同一个 Benchmark 再跑一遍,你在记分板上对比两次的结果。从部署到再测一次,没有哪一步需要你说出一条命令。
-**确实会经过网络的部分:** 安装包与权重,方向是**进来**。`ollama pull`、`pip install vllm`、克隆 LlamaFactory、解析一个 Hugging Face 基座模型 ID——这些都是下载,没有一项在上传你的数据。方向值得说清楚,因为「本地」这个词经常被悄悄安在会回传的方案上。
+如果想改进的是 Agent 本身而不是模型权重,可以用 `agent-optimization` Skill,它基于同一张记分板工作。在有可供回滚的快照之前,它不会改动 Agent State。
-**以及决定其余一切的那一项:** 驱动 Agent 的模型本身。如果 Agent 跑在托管 API 上,那么无论它调优的模型多本地,对话本身——你的指令、它读到的文件内容、它转述的工具输出——都会到达那家厂商。完全本地是你主动做的选择:用同样的 `penguin config model add ... --set-default`,把 Harness 自身的默认模型也指向本地端点,整个闭环就没有第三方参与。这是一个真实的取舍——让一个小的本地模型驱动整个闭环,和让一个前沿模型驱动它,不是同一件事——它应该是一个决定,而不是一个默认假设。
+## 各环节如何衔接
-## 真正改变的是什么
+Agent 能跑通这个闭环,靠的是下面三点,每一点背后都有一个你能打开查看的文件。
-在这个版本之前,PenguinHarness 可以对接任何 OpenAI 兼容端点,但对这个端点从哪来只字不提。把模型部署起来、衡量它能做到什么、修补它做不到的地方,是三套工具、三套约定,中间夹着一个人做翻译。
+### 知识已经装在 Agent 里
-现在它们是同一套系统,而人的位置变了。你描述你要的结果。Agent 自己部署模型、自己跑评测、自己读失败原因、自己微调、自己重新部署、自己再测一次——每一步都由上一步的结果决定。你负责批准调用、做判断、看记分板。
+在 0.1.1 里,`packages/skills/skills/vllm/SKILL.md`、`.../ollama/SKILL.md` 和 `.../llamafactory/SKILL.md` 都属于 Skill 库,而 Project 的 `default_agent` 在创建时就装好了整个库。下载、配置、粘贴,这些都不用你做。负责测量和改进的 `benchmark-design`、`agent-evaluation` 和 `agent-optimization` 也在同一个库里,安装方式相同。全新安装之后,Agent 就已经知道:启动 vLLM 必须带上 `--enable-auto-tool-choice` 和与模型系列匹配的 `--tool-call-parser`,否则每次工具调用都会返回 `400`;Ollama 默认的上下文窗口装不下 Agent 会话,以及调大窗口的两种办法;LoRA 适配器绝不能合并进量化过的基座。这些细节,往往要搭进去一个下午才会弄明白。
-跑在你自己的硬件上。用你自己的权重。数据留在你放它的地方。
+### 会用的工具再多,每次请求也几乎不增加开销
-```bash
-curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
-penguin web
-```
+Skill 没有专用工具,也不会整篇塞进提示词。系统提示词模板里有一个 `{{SKILL_METADATA}}` 占位符,组装时会替换成每个已安装 Skill 各一行的元数据,例如 `` - `vllm` — Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint… ``。只有任务对得上时,Agent 才用 shell 命令从磁盘读取 Skill 正文。在 0.1.1 里,15 个 Skill 的元数据行合计约 2.5 KB,正文合计超过 100 KB,用到之前一个字都不进上下文窗口。
+
+### Agent 操作的是真正的 CLI
+
+在 0.1.1 里,会话的内置工具是 `exec_command`、`input_command`、`run_subagent`、`input_subagent` 和一个图像工具。没有读文件工具,没有写文件工具,也没有针对某家厂商的集成:`exec_command` 自己的描述就告诉模型,用 shell 读写、编辑文件和运行程序。所以 `vllm serve`、`ollama pull` 和 `llamafactory-cli train` 都不需要适配层,Skill 里写的参数就是这些工具真正的参数;vLLM 哪天加了新参数,改一份 Markdown 就行,不必等 Harness 发新版。闭环能留在本地也是这个原因:Agent 直接在存放数据的机器上执行命令,中间没有一个需要先看到你数据集的托管控制面。
+
+换成别的有 shell 可用、能力足够的 Agent,给它同样的指令,也能做到这些。区别在于,PenguinHarness 已经装好了这些指令,只占约 2.5 KB 的提示词,其中还包括注册这一步,有了它,部署好的模型才真正用得上。换作别处,这些都得你自己知道,而且每个会话都要再来一遍。
+
+## 故障排查
+
+下面这些故障的处理办法已经写进 Skill,Agent 知道怎么应对。列在这里,是为了让你在会话中遇到时能认出来:
+
+- vLLM 拒绝所有工具调用:启动服务时没有带工具调用参数。用 `vllm serve <model> --enable-auto-tool-choice --tool-call-parser hermes` 重新启动,并按模型系列选择 parser(Qwen 用 `hermes`,Llama 用 `llama3_json`)。不带这对参数,Agent 的每个请求都会报 `400 "auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set`。
+- vLLM 启动时显存不足:调低 `--gpu-memory-utilization` 或 `--max-model-len`,或者改为部署量化模型。
+- Ollama 的上下文窗口太小:用 `OLLAMA_CONTEXT_LENGTH=32768 ollama serve` 启动服务,或者在 Modelfile 里写上 `PARAMETER num_ctx 32768`,再执行 `ollama create`。
+- Ollama 已经在运行:11434 端口被占用,说明应该复用现有实例,绝不能杀掉不是自己启动的服务进程。
+- 合并 LoRA 适配器:为了独立部署,要把适配器合并进基座权重,但绝不能合并到量化过的基座上。
+- 部署好的模型在 PenguinHarness 里看不到:模型添加之前一直不可见,用 `--provider custom --client-type openai --base-url <endpoint>` 注册即可。
+
+还有一个错误出在 Harness 本身,而不在 Skill 里。0.1.1 之前,不带工具的请求也会发送一个空的工具列表,vLLM 会以 `400 … tools must not be an empty array` 拒绝;0.1.1 不再发送空列表,升级即可解决。
+
+## 哪些东西留在本机
+
+在这套配置下,以下内容都留在本地:
+
+- 部署的模型。Ollama 在 `http://localhost:11434/v1` 提供 OpenAI 兼容 API,vLLM 在 `http://localhost:8000/v1`。Agent 会话里发给它们的每条提示词、工具 Schema、工具结果和补全,都只经过本机回环接口。
+- 训练。LlamaFactory 跑在你的 GPU 上。数据集放在 `data/` 下,与 `data/dataset_info.json` 相邻;适配器和合并后的导出结果落在 `saves/` 下。`llamafactory-cli train` 的任何阶段都不会把你的样本发出去。
+- 评估。题目、题干和评分细则都是你 Project 里的文件,评估者从磁盘读取它们。一份评分细则的路径形如 `~/.penguin/data/default_project/agents/tool_router/benchmarks/tool-routing-v1/CASE-003-pick-the-cheaper-endpoint/rubric/README.md`,记分板是它们旁边的一个 YAML 文件。
+- 配置。`penguin config model add` 写入一个隐藏的 Project 配置文件。它只由 CLI 管理,不应手工编辑,你指定放在哪里,它就留在哪里。
+
+如果驱动 Agent 的是本地模型,经过网络的就只有安装包和模型权重,而且都是下载进来。`ollama pull`、`pip install vllm`、克隆 LlamaFactory、解析 Hugging Face 基座模型 id,这些都是下载,没有一项会上传你的数据。如果驱动 Agent 的是托管模型,对话本身也会发到那家供应商,见第三步。
+
+## 结语
+
+在 0.1.1 之前,PenguinHarness 能对接任何 OpenAI 兼容端点,却不管这个端点从哪里来。把端点搭起来、测出它能做什么、补上它做不到的,要用三套工具、守三套约定,中间还得有个人来回转述。
+
+在这篇教程里,你只描述了两个目标。Agent 自己部署模型、跑 Benchmark、读失败原因、微调、重新部署、再测一次,每一步都由上一步的结果决定。你留在闭环里的位置有三处:审批工具调用;做判断(选哪个基座模型、用哪个引擎、多好才算够好);提供训练数据。其余的一切,从参数、端口、parser,到要不要复用正在运行的服务,都写在 Skill 里,也就是都装在 Agent 身上。
+
+接下来可以:
+
+- 到 [`packages/skills/skills/`](https://github.com/Prism-Shadow/penguin-harness/tree/v0.1.1/packages/skills/skills) 读一读 0.1.1 随附的 Skill,看看 Agent 手里都有哪些知识。
+- 如果这次驱动 Agent 的是托管模型,可以按第三步的做法,换成本地模型再跑一遍闭环。
diff --git a/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.en.md b/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.en.md
index 1fe8b733..153ab652 100644
--- a/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.en.md
+++ b/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.en.md
@@ -1,37 +1,48 @@
---
-title: "Implementing Agent Self-Improvement with PenguinHarness on an AMD GPU"
+title: "Run an agent self-improvement loop with PenguinHarness on an AMD GPU"
date: 2026-07-22
category: practice
author: Yuyang Gao (AMD), Ning Zhang (AMD), Yaowei Zheng (PrismShadow)
-excerpt: "A complete PenguinHarness self-improvement loop—from baseline evaluation and Trace analysis to Agent optimization and rollback—using a local Qwen3:8B model alongside the Fireworks API."
+excerpt: "Run a complete PenguinHarness self-improvement loop, from baseline evaluation and Trace analysis to agent optimization and rollback, with a local Qwen3:8B model on an AMD GPU and a model on the Fireworks API."
description: "Learn how PenguinHarness combines Benchmarks, Traces, editable Agent State, Snapshots, and rollback in a dual-model experiment with local Qwen3:8B and the Fireworks API."
---
-
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
*AMD × PrismShadow — Yuyang Gao and Ning Zhang (AMD), Yaowei Zheng (PrismShadow).*
-[PenguinHarness](https://github.com/Prism-Shadow/penguin-harness) is an open-source Agent Harness that brings model integrations, Agent configuration, workspace tools, Sessions, Traces, Skills, and Benchmarks into one runtime, with both a CLI and a Web UI. It can use hosted models as well as local models exposed through an OpenAI-compatible endpoint.
+In this tutorial you run a complete self-improvement loop with [PenguinHarness](https://github.com/Prism-Shadow/penguin-harness). You create a small agent, measure it with a Benchmark, let an Optimizer improve it using evidence from real Traces, and keep the new version only if it scores higher. The agent under test runs on Qwen3:8B on an AMD GPU; the agent that creates, measures and optimizes it runs on a model from the Fireworks API.
+
+The model is never retrained, and no weights change. The tutorial is for developers who want to make an agent more reliable without preparing training data, especially when the agent runs a local model. The task is intentionally small, because the subject is the loop itself, not a comparison of models on a leaderboard.
+
+## Prerequisites
+
+- An AMD GPU on which Ollama can already run Qwen3:8B. Installing the AMD driver, ROCm and Ollama is outside the scope of this tutorial; for setup instructions, see the [Ollama Linux documentation](https://docs.ollama.com/linux) and the [GPU support documentation](https://docs.ollama.com/gpu).
+- Fireworks API access. Through the AMD AI Developer Program, AMD and Fireworks AI offer eligible developers USD 50 in complimentary Fireworks credits, and Fireworks provides open-weight models through an OpenAI-compatible endpoint. [Getting Fireworks API Access](https://penguin.ooo/blog/fireworks-credits-amd) explains how to redeem the credits and generate an API key.
+
+## How self-improvement works in PenguinHarness
+
+PenguinHarness is an open-source agent harness. It brings model integrations, agent configuration, Workspace tools, Sessions, Traces, Skills and Benchmarks into one runtime, with both a CLI and a Web App, and it can use hosted models as well as local models exposed through an OpenAI-compatible endpoint.
-What makes the project especially interesting is that it represents Agent behavior as a set of readable, editable, and versioned state files rather than as a fixed prompt that only a developer can maintain manually. Role definitions, operating procedures, reusable Skills, and runtime settings all belong to the Agent State, while each task produces a complete Session and Trace. This allows one Agent to evaluate another, update its State using evidence from real executions, and then verify the change against the same evaluation.
+PenguinHarness represents an agent's behavior as a set of readable, editable and versioned state files, rather than as a fixed prompt that only a developer can maintain by hand. Role definitions, operating procedures, reusable Skills and runtime settings all belong to the Agent State, and each task produces a complete Session and Trace. So one agent can evaluate another, update its State using evidence from real executions, and then verify the change against the same evaluation.
-This is what PenguinHarness calls “self-improvement.” It does not retrain the model or update its weights. Instead, it improves the Agent Harness around the model and uses repeatable measurements to decide whether a new version should be retained.
+That is what PenguinHarness calls self-improvement. It does not retrain the model or update its weights. It improves the agent harness around the model, and uses repeatable measurements to decide whether a new version is kept.
-## How PenguinHarness Implements Agent Self-Improvement
+### The editable Agent State
-The main editable parts of an Agent State include:
+The main editable parts of an Agent State are:
-- `AGENTS.md`: role, boundaries, and operating procedures;
+- `AGENTS.md`: role, boundaries and operating procedures;
- `skills/`: reusable capabilities;
- `system_config.yaml`: version and runtime configuration.
-PenguinHarness organizes the self-improvement process around three roles:
+### Three roles
-- **Target Agent**: the Agent that performs tasks and is evaluated and improved;
-- **Evaluator**: runs one Benchmark Case in an isolated workspace and scores it against a private Rubric;
+- **Target Agent**: the agent that performs tasks, and is evaluated and improved;
+- **Evaluator**: runs one Benchmark Case in an isolated Workspace and scores it against a private Rubric;
- **Optimizer**: reads baseline scores and their linked Traces, forms an improvement hypothesis, and modifies the Target Agent State.
-The complete loop works as follows:
+### The loop
1. Create a multi-Case Benchmark for the target capability.
2. Run the Target Agent repeatedly to establish a traceable baseline.
@@ -40,20 +51,29 @@ The complete loop works as follows:
5. Evaluate the candidate version with the same Benchmark and the same model.
6. Keep the new version only if its total score is strictly higher; otherwise, restore the previous State.
-The loop is orchestrated by built-in Skills:
+Built-in Skills orchestrate the loop:
-- `agent-creation`: creates the initial Agent from a set of requirements;
+- `agent-creation`: creates the initial agent from a set of requirements;
- `benchmark-design`: designs a multi-Case Benchmark and establishes a complete baseline;
- `agent-evaluation`: runs and scores one isolated Case execution;
-- `agent-optimization`: analyzes the baseline and Traces, edits Agent State, evaluates the candidate, and handles rollback.
+- `agent-optimization`: analyzes the baseline and Traces, edits the Agent State, evaluates the candidate and handles rollback.
-The important point is not simply that “one model rewrites another model’s prompt.” Every change is re-evaluated under the same conditions. The Benchmark provides the measurement, the Trace provides the evidence, the Snapshot provides a recovery point, and the State version ties each score to the Agent State that actually produced it. If an optimization does not yield a strict improvement, the candidate change is not treated as a successful evolution.
+The point is not simply that one model rewrites another model's prompt. Every change is re-evaluated under the same conditions. The Benchmark provides the measurement, the Trace provides the evidence, the Snapshot provides a recovery point, and the State version ties each score to the Agent State that actually produced it. If an optimization does not yield a strict improvement, the candidate change does not count as a successful evolution.
+
+### Two models, two jobs
+
+This tutorial splits the work between two models:
+
+| Purpose | Agent | Model |
+|---|---|---|
+| Create the agent, design the Benchmark, and perform optimization | `default_agent` | Fireworks API model |
+| Undergo evaluation and improvement | `meeting_summary_agent` | Qwen3:8B on an AMD GPU |
-To demonstrate the full mechanism, this article uses a dual-model setup. Qwen3:8B runs through Ollama on an AMD GPU and serves as the Target Agent model. A model accessed through the Fireworks API runs `default_agent` and is responsible for creating the Agent, designing the Benchmark, and performing optimization. We first establish a v1 baseline, let the Optimizer improve the Agent using evidence from real Traces, and then use the same Benchmark to decide whether to accept the new version or roll it back. The focus is the self-improvement loop itself, not a model leaderboard comparison.
+Qwen3:8B runs through Ollama on the AMD GPU and serves as the Target Agent model. A model on the Fireworks API runs `default_agent`, which creates the agent, designs the Benchmark and performs the optimization. You first establish a v1 baseline, let the Optimizer improve the agent using evidence from real Traces, and then use the same Benchmark to decide whether to accept the new version or roll it back.
-## What We Will Build
+## What you will build
-We will create a `meeting-summary-agent`. It reads a small collection of text files and generates the following file in its workspace:
+You create `meeting_summary_agent`. It reads a small collection of text files and writes the following file in its Workspace:
```markdown
# Summary
@@ -65,7 +85,7 @@ We will create a `meeting-summary-agent`. It reads a small collection of text fi
## Unresolved
```
-The Benchmark contains two Cases:
+You measure it with a Benchmark of two Cases:
| Case | Task |
|---|---|
@@ -74,37 +94,20 @@ The Benchmark contains two Cases:
Each Case runs independently three times, so one complete evaluation contains six Target Agent runs.
-The overall workflow is:
+The steps below follow this workflow:
1. Configure local Qwen3:8B and the Fireworks API model.
-2. Create the v1 Agent.
+2. Create the v1 agent.
3. Export the v1 Snapshot.
4. Create and run the Benchmark.
5. Inspect the baseline and Traces.
-6. Optimize the Agent.
+6. Optimize the agent.
7. Evaluate the candidate with the same Benchmark.
8. Accept the new version or roll it back.
----
-
-## Step 1: Configure Qwen3:8B on an AMD GPU and the Fireworks API
-
-This experiment uses two models:
-
-| Purpose | Agent | Model |
-|---|---|---|
-| Create the Agent, design the Benchmark, and perform optimization | `default_agent` | Fireworks API model |
-| Undergo evaluation and improvement | `meeting-summary-agent` | Qwen3:8B on an AMD GPU |
-
-### Prepare Local Qwen3:8B
-
-The local model runs through Ollama. Installing the AMD driver, ROCm, and Ollama is outside the scope of this article; you only need to confirm that Ollama can already run Qwen3:8B successfully. For setup instructions, see the [Ollama Linux documentation](https://docs.ollama.com/linux) and [GPU support documentation](https://docs.ollama.com/gpu).
-
-### Get Fireworks API Access
-
-Through the AMD AI Developer Program, AMD and Fireworks AI offer eligible developers USD 50 in complimentary Fireworks credits. Fireworks provides open-weight models through an OpenAI-compatible endpoint. See [Getting Fireworks API Access](https://penguin.ooo/blog/fireworks-credits-amd) for instructions on redeeming the credits and generating an API key.
+## Step 1: Install PenguinHarness and register the models
-### Register the Models in the Web UI
+In this step you install PenguinHarness and register both models the experiment uses.
Install and start PenguinHarness:
@@ -113,17 +116,15 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Open the **Models** page in the Web UI and add the local Qwen3:8B model:
+Open the **Models** page in the Web App and add the local Qwen3:8B model:
<img width="491" height="481" alt="PenguinHarness local Qwen3:8B model configuration" src="https://github.com/user-attachments/assets/a0d866e9-21e6-4b89-8ec1-b50710aed0db" />
-
Next, configure the Fireworks API key and set DeepSeek V4 Flash as the default model:
<img width="498" height="479" alt="PenguinHarness Fireworks API model configuration" src="https://github.com/user-attachments/assets/3b392317-615d-46d3-95c9-f9e3b4ad61a5" />
-
-New top-level `default_agent` Chats can now use the Project Default—the Fireworks model. When the Benchmark runs `meeting-summary-agent`, it explicitly selects the following local model pair:
+New top-level `default_agent` chats now use the Project default, which is the Fireworks model. When the Benchmark runs `meeting_summary_agent`, it explicitly selects this local model pair:
```text
provider: custom
@@ -132,19 +133,21 @@ model_id: qwen3:8b
The baseline and every candidate must use this same `(provider, model_id)` pair. Otherwise, their scores are not directly comparable.
----
+## Step 2: Create the v1 agent
-## Step 2: Create the v1 Agent
+In this step you create the first version of the Target Agent and save a Snapshot of it as a recovery point.
-In the PenguinHarness Web UI, create a new Agent named **meeting-summary-agent**.
+1. In the Web App, create a new agent with the id `meeting_summary_agent`. An agent id takes only lowercase letters, digits and underscores, so a hyphenated id is rejected.
+2. Start a new top-level chat with `default_agent`, and select the Fireworks model you just set as the Project default.
+3. Invoke the `agent-creation` Skill (renamed `agent-initialization` in PenguinHarness 0.2.4) and submit the prompt below.
-Start a new top-level Chat with `default_agent`, select the Fireworks model that was just configured as the Project Default, invoke the `agent-creation` Skill, and submit the prompt below. It creates the v1 version of **meeting-summary-agent**. Version 1 defines only the basic responsibilities and safety boundaries; it does not preload a complete summarization workflow. This allows the Benchmark to expose missing operating habits through actual runs.
+The prompt creates v1 of `meeting_summary_agent`. Version 1 defines only the basic responsibilities and safety boundaries. It does not preload a complete summarization workflow, so the Benchmark can expose the operating habits the agent lacks through actual runs.
<details>
-<summary><strong>Expand: Complete Prompt for Creating the v1 Agent</strong></summary>
+<summary><strong>Expand: complete prompt for creating the v1 agent</strong></summary>
```text
-Use the agent-creation Skill to configure the Agent `meeting-summary-agent`.
+Use the agent-creation Skill to configure the Agent `meeting_summary_agent`.
Goal:
This is a simple local-file summarization Agent. It reads the task instructions
@@ -180,40 +183,35 @@ State version.
</details>
-
-After the operation completes, the new Agent appears in the Agents list:
+When the operation completes, the new agent appears in the Agents list. The screenshot comes from the original run, in which the agent's id was `meeting-summary-agent`:
<img width="1376" height="464" alt="Meeting Summary Agent in the Agents list" src="https://github.com/user-attachments/assets/7e3f70d2-2164-4f90-8507-6c2d1cd9085c" />
-
-Open the Agent settings and export the v1 Snapshot. This Snapshot provides the recovery point if a later candidate fails:
+Open the agent's settings and, on the **Overview** tab, click **Export snapshot** to export the v1 Snapshot. The Snapshot is the recovery point if a later candidate fails, and the `agent-optimization` Skill will not change the Agent State until it exists:
<img width="790" height="407" alt="Exporting the v1 Agent State Snapshot" src="https://github.com/user-attachments/assets/6f0c4745-3fd5-4c66-b302-bd58e42ce646" />
+## Step 3: Create the Benchmark and measure the baseline
----
-
-## Step 3: Create the Benchmark
-
-Still in the top-level `default_agent` Chat that uses the Fireworks model, invoke the `benchmark-design` Skill and submit the following prompt to create and calibrate the v1 Benchmark.
+In this step you create and calibrate the Benchmark, and run the complete baseline for v1.
-Use this Benchmark ID:
+In the same top-level `default_agent` chat on the Fireworks model, invoke the `benchmark-design` Skill and submit the prompt below. It creates and calibrates the v1 Benchmark, with this Benchmark ID:
```text
simple-file-summary-2case-v1
```
-The maximum scores of the two Cases total 100 points, and each Case runs three times. The Target Agent can see only the public Statement, never the private Rubric.
+The maximum scores of the two Cases total 100 points, and each Case runs three times. The Target Agent sees only the public Statement, never the private Rubric.
<details>
-<summary><strong>Expand: Complete Prompt for Creating and Calibrating the Benchmark</strong></summary>
+<summary><strong>Expand: complete prompt for creating and calibrating the Benchmark</strong></summary>
```text
Use the benchmark-design Skill to create and calibrate a Benchmark for the
following Test Agent.
Test Agent:
-meeting-summary-agent
+meeting_summary_agent
Benchmark ID:
simple-file-summary-2case-v1
@@ -304,34 +302,31 @@ Finally, report:
</details>
-After completion, the Benchmark structure looks like this:
+When it completes, the Benchmark has this structure:
<img width="635" height="350" alt="Generated Benchmark structure" src="https://github.com/user-attachments/assets/f44b9bbd-4b38-4c14-aa3a-2d95f44165cf" />
-
-Inspect the output in the Web UI and open the Benchmark page to review the total score, each Case mean, and the corresponding Sessions and Traces:
+Check the run's output in the Web App, then open **Evaluation Center** to review the total score, the mean of each Case, and the Sessions and Traces behind them:
<img width="550" height="235" alt="Baseline Benchmark score" src="https://github.com/user-attachments/assets/5dbfb515-198d-4d29-9ff3-01eccd61d630" />
+The baseline total is 84. The task is intentionally small, so the baseline already exceeds 80, but there is still room for improvement. This score is the reference the candidate must beat.
-The overall baseline score is 84. Because the task is intentionally small, the baseline already exceeds 80, but there is still room for improvement. In the next step, we optimize the Agent to demonstrate the self-improvement process.
-
+## Step 4: Optimize the agent
----
-
-## Step 4: Optimize the Agent
+In this step the Optimizer analyzes all six runs and their linked Traces, then makes one small, evidence-based change to the Agent State.
-After the baseline has been established, use the top-level `default_agent` Chat running the Fireworks model to invoke the `agent-optimization` Skill. The prompt instructs the Optimizer to analyze all six runs and their linked Traces, form a generalizable behavioral hypothesis, and then update `AGENTS.md` or create a narrowly scoped Skill.
+In the top-level `default_agent` chat on the Fireworks model, invoke the `agent-optimization` Skill and submit the prompt below. It instructs the Optimizer to form one generalizable behavioral hypothesis, and then to update `AGENTS.md` or create a narrowly scoped Skill.
<details>
-<summary><strong>Expand: Complete Prompt for Optimizing the Agent</strong></summary>
+<summary><strong>Expand: complete prompt for optimizing the agent</strong></summary>
```text
Use the agent-optimization Skill in Benchmark optimization mode to improve
the target Agent.
Test Agent:
-meeting-summary-agent
+meeting_summary_agent
Benchmark:
simple-file-summary-2case-v1
@@ -372,17 +367,13 @@ Finally, report:
</details>
-A likely optimization direction is to add a concise operating procedure or a small set of workflow constraints.
-
-The exact change should be driven by evidence in the real Traces, rather than by embedding the Benchmark answers in the Agent State.
-
----
+A likely direction is a concise operating procedure or a small set of workflow constraints. The exact change should come from evidence in the real Traces, not from embedding the Benchmark answers in the Agent State.
-## Step 5: Compare Results and Retain the New Version
+## Step 5: Compare the results and keep the new version
-The Optimizer evaluates the candidate with the same two Cases, the same Qwen3:8B model, and the same three repeated runs.
+In this step the Optimizer evaluates the candidate under identical conditions and applies the acceptance rule.
-The acceptance rule is simple:
+The candidate runs with the same two Cases, the same Qwen3:8B model and the same three repeated runs. The acceptance rule is simple:
```text
candidate total > reference total
@@ -392,27 +383,23 @@ candidate total <= reference total
→ roll back to v1
```
-The optimized Agent updates `AGENTS.md`, adds an operating procedure, reruns the Cases, and produces the new score:
+In this run, the Optimizer adds an operating procedure to `AGENTS.md`, reruns the Cases and reports the new score:
<img width="857" height="413" alt="Optimization result and updated Agent State" src="https://github.com/user-attachments/assets/f046ca42-e7ef-4063-8c10-babce816eba4" />
+If v2 is accepted, export a v2 Snapshot from the agent's **Overview** tab. To keep improving the agent, repeat the same process from the accepted version.
-If v2 is accepted, export a v2 Snapshot from the Agent Overview page. To continue improving the Agent, repeat the same process from the accepted version.
-
-Open the Benchmark page and select **MEETING SUMMARY AGENT** to see both evaluation rounds in the improvement history:
+Open **Evaluation Center** and select **MEETING SUMMARY AGENT** to see both evaluation rounds in the improvement history:
<img width="628" height="515" alt="Two rounds in the Benchmark history" src="https://github.com/user-attachments/assets/58be7385-8746-4931-92e6-f563dc26e804" />
+Because the task is relatively simple, a single optimization round brings the score close to the maximum. On more complex real-world tasks, the value of the self-improvement loop becomes more apparent.
+## What the experiment shows
+You measured a baseline of 84, let the Optimizer change the Agent State based on Trace evidence, and applied a rule that keeps a new version only when it scores strictly higher under the same Benchmark, model and run count.
-> Because this example uses a relatively simple task, a single optimization round can bring the score close to the maximum. On more complex real-world tasks, the value of the self-improvement loop becomes more apparent.
-
----
-
-## Conclusion
-
-This experiment does not show Qwen3:8B retraining itself during execution. Instead, it shows how PenguinHarness places the Agent’s operating procedure inside a verifiable loop:
+This experiment does not show Qwen3:8B retraining itself during execution. It shows how PenguinHarness places the agent's operating procedure inside a verifiable loop:
```text
Behavior is measured by a Benchmark
@@ -422,7 +409,7 @@ Behavior is measured by a Benchmark
→ only measured improvements are retained
```
-This approach is especially useful for local models. Without preparing training data or fine-tuning model weights, clearer operating procedures can still improve the reliability with which an Agent completes its tasks.
+This approach is especially useful for local models. Without preparing training data or fine-tuning model weights, clearer operating procedures can still make an agent complete its tasks more reliably.
## References
diff --git a/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.zh.md b/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.zh.md
index c6f5b1ea..0ec1fb75 100644
--- a/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.zh.md
+++ b/packages/landing/content/blog/penguin-harness-self-improvement-with-amd-gpu.zh.md
@@ -1,56 +1,79 @@
---
-title: "在 AMD GPU 上用 PenguinHarness 实现 Agent 自我进化"
+title: "在 AMD GPU 上用 PenguinHarness 跑通 Agent 自我进化闭环"
date: 2026-07-22
category: practice
author: 高钰洋(AMD)、张宁(AMD)、郑耀威(PrismShadow)
-excerpt: "通过本地 Qwen3:8B 与 Fireworks API 的双模型分工,完整演示 PenguinHarness 从基线评测、Trace 分析到 Agent 优化与回滚的自我进化闭环。"
+excerpt: "用 AMD GPU 上的本地 Qwen3:8B 和 Fireworks API 上的模型,跑通一个完整的 PenguinHarness 自我进化闭环:从基线评估、Trace 分析,到 Agent 优化与回滚。"
description: "介绍 PenguinHarness 如何通过 Benchmark、Trace、可编辑的 Agent State 与 Snapshot 回滚构建自我进化闭环,并用本地 Qwen3:8B 与 Fireworks API 完成一次双模型实验。"
---
-*AMD × PrismShadow——高钰洋、张宁(AMD),郑耀威(PrismShadow)。*
-[PenguinHarness](https://github.com/Prism-Shadow/penguin-harness) 是一个开源的 Agent Harness。它把模型接入、Agent 配置、工作区工具、Session、Trace、Skill 和 Benchmark 放在同一套运行环境中,并同时提供 CLI 与 Web UI。在线模型和通过 OpenAI 兼容接口暴露的本地模型,都可以作为其中的推理后端。
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-这个项目比较特别的一点,是它把 Agent 的行为定义为一组可以读取、修改和版本化的状态文件,而不是一段只能由开发者手工维护的固定提示词。角色说明、工作方式、可复用 Skill 和运行参数都属于 Agent State;一次任务又会留下完整的 Session 与 Trace。因此,另一个 Agent 可以先评测目标 Agent,再根据真实运行记录修改它的状态,最后用同一套评测验证修改是否有效。
+AMD × PrismShadow——高钰洋、张宁(AMD),郑耀威(PrismShadow)。
-这就是 PenguinHarness 所说的“自我进化”:它不重新训练模型,也不更新模型权重,而是持续改进模型外部的 Agent Harness,并用可重复的结果决定新版本能否被保留。
+在本教程中,你会用 [PenguinHarness](https://github.com/Prism-Shadow/penguin-harness) 跑通一个完整的自我进化闭环:创建一个小 Agent,用 Benchmark 评估它,让 Optimizer 根据真实 Trace 中的证据改进它,分数更高才保留新版本。被测 Agent 使用 AMD GPU 上的 Qwen3:8B;负责创建、评估和优化的 Agent 则使用 Fireworks API 上的模型。
+
+全程不重新训练模型,也不改动任何权重。本教程面向想让 Agent 更可靠、又不想准备训练数据的开发者,尤其适合 Agent 使用本地模型的场景。任务刻意选得很小,因为这里关注的是闭环本身,而不是比较模型在排行榜上的高低。
+
+## 准备工作
+
+- 一块 AMD GPU,并且 Ollama 已经能在上面正常运行 Qwen3:8B。AMD 驱动、ROCm 和 Ollama 的安装不在本教程范围内,具体方法可以参考 [Ollama Linux 文档](https://docs.ollama.com/linux)和 [GPU 支持文档](https://docs.ollama.com/gpu)。
+- Fireworks API 访问权限。通过 AMD AI Developer Program,AMD 与 Fireworks AI 合作,为符合条件的开发者提供价值 50 美元的免费 Fireworks 额度;Fireworks 通过 OpenAI 兼容端点提供开源权重模型。额度兑换和 API Key 获取步骤,见 [Fireworks API 获取指南](https://penguin.ooo/blog/fireworks-credits-amd)。
## PenguinHarness 如何实现自我进化
-一个 Agent 的主要可编辑状态包括:
+PenguinHarness 是一个开源的 Agent Harness。它把模型接入、Agent 配置、Workspace 工具、Session、Trace、Skill 和 Benchmark 放在同一套运行环境中,同时提供 CLI 与 Web App;在线模型和通过 OpenAI 兼容端点暴露的本地模型,都可以用作推理后端。
+
+PenguinHarness 把 Agent 的行为定义为一组可读、可编辑、带版本的状态文件,而不是一段只能由开发者手工维护的固定提示词。角色说明、工作流程、可复用的 Skill 和运行参数都属于 Agent State,每次任务也都会留下完整的 Session 与 Trace。因此,一个 Agent 可以先评估另一个 Agent,再根据真实运行记录修改它的 State,最后用同一套评估验证修改是否有效。
+
+这就是 PenguinHarness 所说的自我进化:它不重新训练模型,也不更新模型权重,而是改进模型外围的 Agent Harness,并用可重复的测量结果决定新版本能否保留。
+
+### 可编辑的 Agent State
+
+Agent State 中主要的可编辑部分包括:
- `AGENTS.md`:角色、边界和工作流程;
-- `skills/`:可复用能力;
+- `skills/`:可复用的能力;
- `system_config.yaml`:版本和运行配置。
-围绕这些状态,PenguinHarness 把自我进化组织成三个角色:
+### 三个角色
-- **Target Agent**:真正执行任务、接受评测和改进的目标 Agent;
-- **Evaluator**:在隔离工作区中运行一个 Benchmark Case,并根据私有 Rubric 评分;
-- **Optimizer**:读取基线分数及其关联 Trace,提出改进假设并修改 Target Agent State。
+- **Target Agent**:执行任务、接受评估和改进的目标 Agent;
+- **Evaluator**:在隔离的 Workspace 中运行一道 Benchmark 题目,并按私有评分细则打分;
+- **Optimizer**:读取基线分数及其关联的 Trace,提出改进假设,并修改 Target Agent 的 State。
-完整闭环如下:
+### 自我进化闭环
-1. 为目标能力建立多 Case Benchmark。
-2. 对 Target Agent 重复运行,得到可追溯的基线。
-3. 从分数和对应 Trace 中定位稳定的失败模式。
-4. 保存 Snapshot,并修改 Agent State。
-5. 使用相同 Benchmark 和相同模型重新评测候选版本。
-6. 总分严格提高则保留新版本,否则恢复原状态。
+1. 为目标能力创建包含多道题目的 Benchmark。
+2. 多次运行 Target Agent,得到可追溯的基线。
+3. 根据分数和关联的 Trace,定位稳定的失败模式。
+4. 保存快照,然后修改 Agent State。
+5. 用同一个 Benchmark 和同一个模型评估候选版本。
+6. 总分严格提高才保留新版本,否则恢复之前的 State。
-这个流程主要由内置 Skill 编排:
+这个闭环由内置 Skill 编排:
- `agent-creation`:根据需求创建初始 Agent;
-- `benchmark-design`:设计多 Case Benchmark,并建立完整基线;
-- `agent-evaluation`:隔离执行并评分一次 Case 运行;
-- `agent-optimization`:分析基线和 Trace,修改 Agent State,并完成候选版本评测与回滚。
+- `benchmark-design`:设计包含多道题目的 Benchmark,并建立完整基线;
+- `agent-evaluation`:隔离执行一道题目的一次运行并打分;
+- `agent-optimization`:分析基线和 Trace,修改 Agent State,评估候选版本并处理回滚。
+
+关键不只是让一个模型改写另一个模型的提示词,而是让每次修改都在相同条件下重新评估。Benchmark 提供测量,Trace 提供证据,快照提供恢复点,State 版本号则把每个分数对应到实际产生它的 Agent State。优化没有带来严格提升时,候选修改就不算一次成功的进化。
-这里的关键不只是“让另一个模型改写提示词”,而是让每次修改都经过同条件复测。Benchmark 提供度量,Trace 提供证据,Snapshot 提供恢复点,版本号则把分数与实际 Agent State 对应起来。优化没有带来严格提升时,候选修改不会被当成进化成果。
+### 两个模型,各司其职
-为了把这套机制完整跑一遍,本文采用双模型分工:AMD GPU 上通过 Ollama 运行的 Qwen3:8B 作为 Target Agent 的模型;通过 Fireworks API 调用的模型则用于运行 `default_agent`,负责创建 Agent、设计 Benchmark 和执行优化。我们先测出 v1 的基线,再让 Optimizer 根据真实 Trace 改进它,最后由同一 Benchmark 决定接受新版本还是回滚。这个例子关注的是自我进化闭环本身,而不是比较模型排行榜上的能力高低。
+本教程把工作分给两个模型:
+
+| 用途 | Agent | 模型 |
+|---|---|---|
+| 创建 Agent、设计 Benchmark 和执行优化 | `default_agent` | Fireworks API 模型 |
+| 接受评估和改进 | `meeting_summary_agent` | AMD GPU 上的 Qwen3:8B |
+
+Qwen3:8B 通过 Ollama 在 AMD GPU 上运行,作为 Target Agent 的模型;通过 Fireworks API 调用的模型运行 `default_agent`,负责创建 Agent、设计 Benchmark 和执行优化。你会先测出 v1 的基线,再让 Optimizer 根据真实 Trace 改进 Agent,最后由同一个 Benchmark 决定接受新版本还是回滚。
## 本文要完成的实验
-我们创建一个 `meeting-summary-agent`。它读取少量文本文件,并在工作区中生成:
+你要创建的是 `meeting_summary_agent`。它读取少量文本文件,并在 Workspace 中生成下面这个文件:
```markdown
# 摘要
@@ -62,46 +85,29 @@ description: "介绍 PenguinHarness 如何通过 Benchmark、Trace、可编辑
## 未确定
```
-Benchmark 包含两个 Case:
+再用一个包含两道题目的 Benchmark 评估它:
-| Case | 任务 |
+| 题目 | 任务 |
|---|---|
| 单份会议纪要 | 提取已确认事项、两个待办和一个未确定项 |
| 草案与正式决定 | 同时读取草案和正式决定,并以正式决定为准 |
-每个 Case 独立运行 3 次,因此一次完整评测共有 6 次 Target Agent 运行。
+每道题目独立运行三次,因此一次完整评估共有六次 Target Agent 运行。
-完整流程如下:
+下面的步骤按这个流程展开:
1. 配置本地 Qwen3:8B 与 Fireworks API 模型。
2. 创建 v1 Agent。
-3. 导出 v1 Snapshot。
+3. 导出 v1 快照。
4. 创建并运行 Benchmark。
5. 查看基线和 Trace。
6. 优化 Agent。
-7. 使用相同 Benchmark 重新评测候选版本。
+7. 用同一个 Benchmark 评估候选版本。
8. 接受新版本或回滚。
----
-
-## 第一步:配置 AMD GPU 上的 Qwen3:8B 与 Fireworks API
-
-本实验使用两类模型:
-
-| 用途 | Agent | 模型 |
-|---|---|---|
-| 创建 Agent、设计 Benchmark 和执行优化 | `default_agent` | Fireworks API 模型 |
-| 接受评测与进化 | `meeting-summary-agent` | AMD GPU 上的 Qwen3:8B |
-
-### 准备本地 Qwen3:8B
-
-本地模型通过 Ollama 运行。AMD 驱动、ROCm 和 Ollama 的安装不是本文重点,这里不做详细介绍;只需提前确认 Qwen3:8B 已经能够被 Ollama 正常调用。具体安装方式可以参考 [Ollama Linux 文档](https://docs.ollama.com/linux) 和 [GPU 支持文档](https://docs.ollama.com/gpu)。
-
-### 获取 Fireworks API
-
-通过 AMD AI Developer Program,AMD 与 Fireworks AI 合作,为符合条件的开发者提供价值 50 美元的免费 Fireworks 额度。Fireworks 通过 OpenAI 兼容端点提供开源权重模型。可参阅 [Fireworks API 获取指南](https://penguin.ooo/blog/fireworks-credits-amd),了解额度兑换和 API Key 获取步骤。
+## 第一步:安装 PenguinHarness 并注册模型
-### 在 Web UI 中注册模型
+这一步安装 PenguinHarness,并注册实验要用到的两个模型。
安装并启动 PenguinHarness:
@@ -110,36 +116,38 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-打开 Web UI 的 **Models** 页面,添加本地 Qwen3:8B:
+在 Web App 中打开**模型仓库**页面,添加本地 Qwen3:8B:
<img width="491" height="481" alt="PenguinHarness 本地 Qwen3:8B 模型配置" src="https://github.com/user-attachments/assets/a0d866e9-21e6-4b89-8ec1-b50710aed0db" />
-然后配置 Fireworks API Key,并将 DeepSeek V4 Flash 设置为默认模型:
+然后配置 Fireworks API Key,并将 DeepSeek V4 Flash 设为默认模型:
<img width="498" height="479" alt="PenguinHarness Fireworks API 模型配置" src="https://github.com/user-attachments/assets/3b392317-615d-46d3-95c9-f9e3b4ad61a5" />
-这样,新建 `default_agent` 顶层 Chat 时可以直接使用 Project Default,也就是 Fireworks 模型;Benchmark 在运行 `meeting-summary-agent` 时,则显式指定下面这组本地模型配置:
+这样,新建的 `default_agent` 顶层对话会使用 Project 默认模型,也就是 Fireworks 模型;Benchmark 运行 `meeting_summary_agent` 时,则显式指定下面这组本地模型配置:
```text
provider: custom
model_id: qwen3:8b
```
-后续的 baseline 和 candidate 都必须沿用这组 `(provider, model_id)`,否则分数不能直接比较。
-
----
+基线和每个候选版本都必须使用同一组 `(provider, model_id)`,否则分数无法直接比较。
## 第二步:创建 v1 Agent
-在 PenguinHarness Web UI 中创建一个新的 Agent:`meeting-summary-agent`。
+这一步创建 Target Agent 的第一个版本,并保存一份快照作为恢复点。
+
+1. 在 Web App 中创建一个新 Agent,Agent id 填 `meeting_summary_agent`。Agent id 只能包含小写字母、数字和下划线,带短横线的 id 会被拒绝。
+2. 与 `default_agent` 新建一个顶层对话,模型选择刚刚设为 Project 默认模型的 Fireworks 模型。
+3. 调用 `agent-creation` Skill(0.2.4 起更名为 `agent-initialization`),并提交下面的提示词。
-使用 `default_agent` 新建一个顶层 Chat,模型选择刚刚设为 Project Default 的 Fireworks 模型。然后调用 `agent-creation` Skill,并输入下面的 Prompt,生成 `meeting-summary-agent` 的 v1 版本。v1 只定义基本职责和安全边界,不提前写入完整总结流程,这样 Benchmark 才能真实暴露它缺少的工作习惯。
+这段提示词会生成 `meeting_summary_agent` 的 v1 版本。v1 只定义基本职责和安全边界,不提前写入完整的总结流程,这样 Benchmark 才能在真实运行中暴露它缺少的工作习惯。
<details>
-<summary><strong>展开:创建 v1 Agent 的完整 Prompt</strong></summary>
+<summary><strong>展开:创建 v1 Agent 的完整提示词</strong></summary>
```text
-请使用 agent-creation Skill 配置 Agent `meeting-summary-agent`。
+请使用 agent-creation Skill 配置 Agent `meeting_summary_agent`。
目标:
这是一个简单的本地文件总结 Agent。它读取当前工作区中的任务说明和文本文件,并创建题目要求的总结文件。
@@ -171,37 +179,34 @@ model_id: qwen3:8b
</details>
+创建完成后,可以在 Agent 列表中看到新 Agent。下图来自最初的那次运行,当时的 Agent id 是 `meeting-summary-agent`:
-创建完成后,可以在 Agent 列表中看到新增的 `meeting-summary-agent`:
+<img width="1376" height="464" alt="Agent 列表中的 Meeting Summary Agent" src="https://github.com/user-attachments/assets/7e3f70d2-2164-4f90-8507-6c2d1cd9085c" />
-<img width="1376" height="464" alt="Agent 列表中的 meeting-summary-agent" src="https://github.com/user-attachments/assets/7e3f70d2-2164-4f90-8507-6c2d1cd9085c" />
-
-然后进入 Agent 设置页面并导出 v1 Snapshot。它是后续 Candidate 失败时的回滚基础。
+打开这个 Agent 的设置页面,在**概览**标签页点击**导出快照**,导出 v1 快照。后续候选版本失败时,这份快照就是恢复点;在它存在之前,`agent-optimization` Skill 不会改动 Agent State:
<img width="790" height="407" alt="导出 v1 Agent State Snapshot" src="https://github.com/user-attachments/assets/6f0c4745-3fd5-4c66-b302-bd58e42ce646" />
----
+## 第三步:创建 Benchmark 并测量基线
-## 第三步:创建 Benchmark
+这一步创建并校准 Benchmark,然后跑完 v1 的完整基线。
-仍然在使用 Fireworks 模型的 `default_agent` 顶层 Chat 中调用 `benchmark-design` Skill,并输入下面的 Prompt 来创建并校准 v1 版本的 Benchmark。
-
-Benchmark ID 使用:
+仍然在使用 Fireworks 模型的 `default_agent` 顶层对话中调用 `benchmark-design` Skill,并提交下面的提示词。它会创建并校准 v1 版本的 Benchmark,Benchmark ID 为:
```text
simple-file-summary-2case-v1
```
-两个 Case 的总分为 100 分,每个 Case 运行 3 次。Target Agent 只能看到公开题面,不能看到私有 Rubric。
+两道题目的满分合计 100 分,每道题目运行三次。Target Agent 只能看到公开的题干,看不到私有评分细则。
<details>
-<summary><strong>展开:创建并校准 Benchmark 的完整 Prompt</strong></summary>
+<summary><strong>展开:创建并校准 Benchmark 的完整提示词</strong></summary>
```text
请使用 benchmark-design Skill,为下面的 Test Agent 创建并校准 Benchmark。
Test Agent:
-meeting-summary-agent
+meeting_summary_agent
Benchmark ID:
simple-file-summary-2case-v1
@@ -290,31 +295,30 @@ Rubric 应检查:
</details>
-完成后,会得到如下图所示的 Benchmark 结构:
+完成后,Benchmark 的结构如下:
<img width="635" height="350" alt="生成后的 Benchmark 结构" src="https://github.com/user-attachments/assets/f44b9bbd-4b38-4c14-aa3a-2d95f44165cf" />
-在 Web UI 中查看运行输出,并在 Benchmark 页面检查总分、每个 Case 的均分,以及对应的 Session 和 Trace。
+在 Web App 中查看运行输出,然后打开**评估中心**,查看总分、每道题目的平均分,以及对应的 Session 和 Trace:
<img width="550" height="235" alt="Benchmark 基线评分" src="https://github.com/user-attachments/assets/5dbfb515-198d-4d29-9ff3-01eccd61d630" />
-可以看到,整体评分为 84 分。由于任务较为简单,baseline 已经进入 80 分区间,但仍有优化空间。后续我们会继续优化 Agent,以展示完整的自我进化过程。
-
-
----
+基线总分为 84 分。由于任务较为简单,基线已经超过 80 分,但仍有提升空间。候选版本必须超过这个分数。
## 第四步:优化 Agent
-基线建立后,在使用 Fireworks 模型的 `default_agent` 顶层 Chat 中调用 `agent-optimization` Skill,并输入下面的 Prompt。Optimizer 会分析全部 6 次运行及其 Trace,提出一个可泛化的行为假设,再修改 `AGENTS.md` 或创建一个职责明确、范围有限的 Skill。
+这一步由 Optimizer 分析全部六次运行及其关联的 Trace,再根据证据对 Agent State 做一处小的修改。
+
+在使用 Fireworks 模型的 `default_agent` 顶层对话中调用 `agent-optimization` Skill,并提交下面的提示词。它要求 Optimizer 提出一个可泛化的行为假设,再修改 `AGENTS.md`,或者创建一个职责明确、范围有限的 Skill。
<details>
-<summary><strong>展开:优化 Agent 的完整 Prompt</strong></summary>
+<summary><strong>展开:优化 Agent 的完整提示词</strong></summary>
```text
请使用 agent-optimization Skill,以 Benchmark optimization mode 优化目标 Agent。
Test Agent:
-meeting-summary-agent
+meeting_summary_agent
Benchmark:
simple-file-summary-2case-v1
@@ -349,17 +353,13 @@ simple-file-summary-2case-v1
</details>
-一种可能的优化方向,是加入简洁的工作流程或执行约束。
+一种可能的优化方向,是加入简洁的工作流程或一小组执行约束。具体修改应由真实 Trace 中的证据决定,而不是把 Benchmark 的答案直接写进 Agent State。
-具体修改内容应由真实 Trace 决定,而不能把 Benchmark 的答案直接写入 Agent State。
+## 第五步:比较结果并保留新版本
----
-
-## 第五步:比较并保留新版本
+这一步由 Optimizer 在完全相同的条件下评估候选版本,并执行接受规则。
-Optimizer 会使用同样的两个 Case、同样的 Qwen3:8B 和同样的 3 次重复运行评测 Candidate。
-
-接受规则很简单:
+候选版本使用同样的两道题目、同样的 Qwen3:8B 和同样的三次重复运行。接受规则很简单:
```text
candidate 总分 > reference 总分
@@ -369,23 +369,23 @@ candidate 总分 <= reference 总分
→ 回滚到 v1
```
-优化完成后可以看到,Agent 修改了 `AGENTS.md`,新增了工作流程,并重新运行全部 Case,得到新的评测分数:
+这次运行中,Optimizer 在 `AGENTS.md` 里新增了工作流程,重新运行全部题目,并报告了新的分数:
<img width="857" height="413" alt="Agent 优化结果与更新后的 Agent State" src="https://github.com/user-attachments/assets/f046ca42-e7ef-4063-8c10-babce816eba4" />
-如果 v2 被接受,再从 Agent Overview 导出 v2 Snapshot。如果还需要继续优化,可以基于已接受的版本重复上述流程。
+如果 v2 被接受,就在 Agent 的**概览**标签页导出 v2 快照。如果还要继续优化,就从已接受的版本出发,重复上述流程。
-打开 Benchmark 页面,选择 **MEETING SUMMARY AGENT**,可以查看两轮评测形成的进化记录:
+打开**评估中心**,选择 **MEETING SUMMARY AGENT**,就能看到两轮评估形成的进化记录:
<img width="628" height="515" alt="Benchmark 页面中的两轮进化记录" src="https://github.com/user-attachments/assets/58be7385-8746-4931-92e6-f563dc26e804" />
-> 由于示例任务较为简单,一轮优化后分数便接近满分。在更复杂的真实场景中,自我进化能力的价值会体现得更加明显。
+由于示例任务较为简单,一轮优化就把分数推到接近满分。在更复杂的真实任务中,自我进化闭环的价值会体现得更加明显。
----
+## 实验说明了什么
-## 结语
+你测出了 84 分的基线,让 Optimizer 根据 Trace 中的证据修改 Agent State,并执行了这样一条规则:只有在同一个 Benchmark、同一个模型、同样的运行次数下总分严格更高,新版本才会被保留。
-这个实验展示的并不是 Qwen3:8B 在运行中重新训练了自己,而是 PenguinHarness 让 Agent 的工作方式进入了一个可验证闭环:
+这个实验展示的并不是 Qwen3:8B 在运行中重新训练了自己,而是 PenguinHarness 如何让 Agent 的工作流程进入一个可验证的闭环:
```text
行为被 Benchmark 测量
@@ -395,7 +395,7 @@ candidate 总分 <= reference 总分
→ 只有真实提升才被保留
```
-对于本地模型来说,这种方式尤其有价值:不需要准备训练数据或微调权重,也能通过更清晰的工作流程,提高 Agent 完成任务的稳定性。
+对于本地模型来说,这种方式尤其有价值:不需要准备训练数据,也不需要微调模型权重,更清晰的工作流程同样能提高 Agent 完成任务的稳定性。
## 参考资料
diff --git a/packages/landing/content/blog/penguinharness-0-1-4.en.md b/packages/landing/content/blog/penguinharness-0-1-4.en.md
index 06bc6200..571e1f74 100644
--- a/packages/landing/content/blog/penguinharness-0-1-4.en.md
+++ b/packages/landing/content/blog/penguinharness-0-1-4.en.md
@@ -2,48 +2,75 @@
title: "PenguinHarness 0.1.4: Windows support, goal mode, and the agents panel"
date: 2026-07-27
category: news
-excerpt: 0.1.4 has one theme — the harness meets you where you work and keeps working when you step away. It now installs and runs on Windows with its own one-liner and CI; a new goal mode keeps driving a Session until the objective is actually done rather than merely replied to; and a new agents panel turns subagent fan-outs into a live call graph. Here is what shipped.
+excerpt: 0.1.4 brings PenguinHarness to Windows with a one-line installer, adds goal mode to keep a Session working until an objective is done, and moves subagents into an agents panel with a live call graph.
---
-PenguinHarness 0.1.4 is out, and the release has one theme: the harness meets you where you work and keeps working when you step away. It now installs and runs on Windows; a new **goal mode** keeps driving a Session until an objective is actually done rather than merely replied to; and a new **agents panel** turns subagent fan-outs from nested cards into a live call graph you can watch and steer. Feature by feature:
+PenguinHarness 0.1.4 is out, and it now installs and runs on Windows. A new **goal mode** keeps a Session working until an objective is actually done, not merely replied to. A new **agents panel** turns subagent runs from nested cards into a live call graph you can watch and steer.
-## Windows is now a first-class install
+## Windows support
-One line in PowerShell:
+Install PenguinHarness on Windows with one line in PowerShell:
```powershell
irm https://penguin.ooo/install.ps1 | iex
```
-That fetches `penguin-win32-x64.zip` — the official Windows Node runtime bundled, so nothing needs to be preinstalled — verifies its SHA256, unpacks with a staged swap that never touches your `data\` directory, and puts `penguin` on your user PATH (reading and writing the registry value with its kind preserved, so an existing `%USERPROFILE%`-style entry survives the edit). The stable URL is a forwarder that downloads fully before executing, so a truncated stream cannot half-install. Prefer npm? `npm install -g @prismshadow/penguin-cli` works anywhere Node ≥ 24 does.
+The script downloads `penguin-win32-x64.zip`, which bundles the official Windows Node runtime, so you do not need to install anything first. It verifies the archive's SHA256 checksum, installs through a staged swap that never touches your `data\` directory, and adds `penguin` to your user PATH. Existing PATH entries that use variables, such as `%USERPROFILE%`, stay intact. The script at the stable URL is a small forwarder that downloads the full installer before running it, so a truncated download cannot leave a half-finished install. If you prefer npm, `npm install -g @prismshadow/penguin-cli` works anywhere Node ≥ 24 runs.
-The interesting part was not packaging but the agent itself. Every `exec_command` used to die on Windows with `spawn bash ENOENT`, because the command session hardcoded bash. Command sessions now resolve their shell per platform: Git-Bash first when present (best compatibility with the POSIX-oriented skill ecosystem — and a `bash` that resolves into the Windows system directory is rejected, because that is the WSL launcher, a different filesystem view entirely), then `pwsh`, then `powershell`, with `PENGUIN_SHELL` as the override. The chosen shell is announced to the model through a `Shell:` line in the session environment, so it writes PowerShell syntax when PowerShell is what it has, instead of emitting bash into the void.
+The harder part was the agent itself. Every `exec_command` used to fail on Windows with `spawn bash ENOENT`, because command sessions always started bash. Command sessions now choose their shell per platform. On Windows they try Git-Bash first, since it works best with Skills written for POSIX shells, then `pwsh`, then `powershell`. Set `PENGUIN_SHELL` to override the choice. A `bash` that resolves into the Windows system directory is skipped, because that is the WSL launcher, which sees a different filesystem.
-All of it is kept true by CI: a `ci-windows` job — full build, typecheck and tests, plus a PowerShell parse gate — now runs beside the required Ubuntu job, and getting it green surfaced and fixed real Windows findings, including a workspace-upload symlink guard that POSIX's `O_NOFOLLOW` had been providing silently. The remaining limits are documented rather than pretended away: the package is x64-only for now (ARM64 runs via emulation), Ctrl-C in `input_command` hard-kills the whole command tree instead of interrupting the foreground command, and upgrading means re-running the installer — in-place `penguin update` still refuses on Windows.
+The model learns which shell it has from a `Shell:` line in the Session environment. When it gets PowerShell, it writes PowerShell syntax instead of bash.
-## Goal mode: loop until it is done
+CI keeps all of this working. A `ci-windows` job now runs the full build, typecheck and tests, plus a PowerShell syntax check, beside the required Ubuntu job. Getting it green surfaced and fixed real Windows bugs, including a symlink guard on Workspace uploads that POSIX's `O_NOFOLLOW` had been providing silently and that Windows lacked.
-A normal Task ends when the model stops calling tools and replies. That is right for a request and wrong for an objective — "make the check suite green" is not done just because the model went quiet. Goal mode inverts the contract: you state an objective, and the system keeps driving Tasks on the same Session, re-injecting the objective every round, until the goal reaches a terminal state.
+A few limits remain, and the docs state them:
+
+- The package is x64 only for now. ARM64 machines run it through emulation.
+- Ctrl-C in `input_command` kills the whole command tree instead of interrupting only the foreground command.
+- To upgrade, re-run the installer. In-place `penguin update` still refuses to run on Windows.
+
+## Goal mode
+
+A normal Task ends when the model stops calling tools and replies. That suits a request, but not an objective: "make the check suite green" is not done just because the model went quiet. Goal mode changes the contract. You state an objective, and the system keeps running Tasks on the same Session, re-injecting the objective every round, until the goal reaches a final state.
+
+The model has to claim completion through a protocol; silence does not count. Each goal run creates a `GOAL.yaml` file next to the Session's `PLAN.md`. The model may change only one field, `status`, and only to `complete` or `blocked`. The rules injected every round tell the model to:
+
+- Check a completion claim against evidence, such as files, command output and test results, before writing it.
+- Never shrink the objective to an easier subset.
+- Claim `blocked` only after the same blocker has held for three consecutive rounds, so a temporary obstacle does not end the goal.
+
+You can set an optional Token budget, such as `500k` or `2m`, which is checked between rounds. When the budget runs out, the model gets one wrap-up round to summarize its progress and the remaining work. The goal then ends as budget-limited instead of pretending to succeed.
+
+In the Web App, the composer's new **+** menu adds a goal chip with an inline budget field; `/goal` in the slash menu does the same. Each round appears as a regular user message with a "Goal · round N" notice below it, and a live banner above the composer tracks the objective, the round count and tokens against the budget. The screenshot below shows round 3 of a real loop, in the middle of verification.
<img class="dark:hidden" src="/blog-assets/goal-mode-en-light.webp" alt="Goal mode mid-loop: round 3 of a check-suite objective, with the goal banner above the composer tracking the objective, the round count and tokens against the budget" width="1920" height="1350" />
<img class="hidden dark:block" src="/blog-assets/goal-mode-en-dark.webp" alt="Goal mode mid-loop in dark theme: round 3 of a check-suite objective, with the goal banner above the composer tracking the objective, the round count and tokens against the budget" width="1920" height="1350" />
-Completion is claimed through a protocol, not inferred from silence. Each goal run creates a `GOAL.yaml` next to the session's `PLAN.md`; the model may change exactly one field, `status`, and only to `complete` or `blocked`. The rules injected with every round tell it to audit a completion claim against evidence — files, command output, test results — before writing it, never to shrink the objective to an easier subset, and to claim `blocked` only after the same blocker has held for three consecutive rounds, so a transient obstacle does not end the goal. An optional token budget (`500k`, `2m`) is checked between rounds; when it runs out, the model gets one wrap-up round to summarize progress and remaining work, and the goal ends as budget-limited instead of pretending success.
+The CLI offers the same loop: `/goal[:<budget>] <objective>` in chat, and `--goal` on `penguin run`, where only a completed goal exits 0. That makes an objective something you can put in a script. The SDK keeps its single entry point: `session.run(input, { goal: { budget } })`.
-In the Web App, the composer's new "+" menu engages a goal chip with an inline budget field (`/goal` in the slash menu does the same). Every round renders as a regular user bubble with a "Goal · round N" notice beneath it, and a live banner above the composer tracks the objective, the round count and tokens against budget — the screenshot above is round 3 of a real loop, mid-verification. The CLI has the same power as `/goal[:<budget>] <objective>` in chat and `--goal` on `penguin run`, where only a completed goal exits 0 — an objective you can put in a script. The SDK keeps its one entry point: `session.run(input, { goal: { budget } })`.
+## The agents panel
-## The agents panel: see the whole tree
+`run_subagent` used to inline each child's entire conversation into the parent's message flow. Cards nested inside cards became unreadable after the second child. 0.1.4 moves child conversations into a dedicated agents panel that docks on the right, just like the Workspace files panel: toggle it from the toolbar and drag to resize it. On phones it opens as a bottom sheet.
-`run_subagent` used to inline the child's entire conversation into the parent's message flow — cards nested inside cards, unreadable past the second child. 0.1.4 moves child conversations into a dedicated **agents panel** that docks on the right exactly like the Workspace files panel: toolbar toggle, drag to resize, a bottom sheet on phones. In the message flow, each child leaves a single bar row — avatar, resolved agent name, a spinner while it runs, and an amber dot whenever an approval is pending anywhere in its subtree, so a nested approval stays discoverable even with the panel closed.
+In the message flow, each child leaves a single row: its avatar, its agent name, a spinner while it runs, and an amber dot whenever an approval is pending anywhere in its subtree. A nested approval stays easy to find even with the panel closed.
<img class="dark:hidden" src="/blog-assets/agents-panel-en-light.webp" alt="The agents panel: a call graph with the main session as root and two named subagents with live elapsed times, above the selected child's streaming conversation" width="1920" height="1350" />
<img class="hidden dark:block" src="/blog-assets/agents-panel-en-dark.webp" alt="The agents panel in dark theme: a call graph with the main session as root and two named subagents with live elapsed times, above the selected child's streaming conversation" width="1920" height="1350" />
-The top of the panel is a **call graph**: one node per participating agent — avatar, name, run-state dot and elapsed time, ticking while the child runs and frozen at the settled span once it is done, so a reloaded page shows the same durations as a live one. The main session is the root, and edges show who spawned whom. Click a node and the conversation below switches to that child, rendered by the same machinery as the main stream: its own user prompt is there, tool cards stream live, and approval buttons work from inside the panel. Visibility is task-scoped — every new Task starts with the panel closed, it auto-opens once when the task first spawns a subagent, and your manual open or close wins for the rest of the task. The graph follows the latest Task by default; click a bar row from an older turn and it pins that turn's historical spawn tree instead.
+The top of the panel is the **Call graph**, with one node per participating agent: avatar, name, run-state dot and elapsed time. The time ticks while a child runs and freezes at its final duration once it is done, so a reloaded page shows the same durations as a live one. The main Session is the root, and edges show which agent spawned which.
+
+Click a node to switch the conversation below to that child. It renders the same way as the main stream: the child's own user prompt is there, tool cards stream live, and approval buttons work from inside the panel.
+
+The panel's visibility follows the Task. Each new Task starts with the panel closed, and the panel opens once, automatically, when the Task first spawns a subagent. If you open or close it yourself, your choice holds for the rest of the Task. The graph follows the latest Task by default; click a child's row from an earlier turn to pin that turn's spawn tree instead.
## Also in 0.1.4
-The same release makes an in-progress reply survive a page refresh — the server keeps a live tail per running session, so after a reload the already-streamed prefix is back immediately and keeps growing. The chat header's cost and elapsed chips now tick live while a Task runs, joining the token count that already did. Trace files gained export and import, so a trajectory can move across deployments. And the app finally knows its own version: a "Check for updates" row with the running version inline, plus a one-click in-place update for admins. The full list is in the [v0.1.4 release notes](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.4).
+- An in-progress reply now survives a page refresh. After a reload, the part that has already streamed is back at once and keeps growing.
+- The cost and elapsed-time chips in the chat header tick live while a Task runs, as the Token count already did.
+- Trace files can be exported and imported, so a trajectory can move between deployments.
+- The app knows its own version. A **Check for updates** row in the user menu shows the running version, and admins can update in place with one click.
+
+The full list is in the [v0.1.4 release notes](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.4).
## Get it
@@ -57,4 +84,6 @@ curl -fsSL https://penguin.ooo/install.sh | sh
irm https://penguin.ooo/install.ps1 | iex
```
-Or `npm install -g @prismshadow/penguin-cli` with Node ≥ 24 — 0.1.4 is the version to install, since 0.1.3 carries the same feature set but never reached npm. Then run `penguin web`, add a model key on the Models page — and state an objective.
+You can also install with `npm install -g @prismshadow/penguin-cli` on Node ≥ 24. On npm, 0.1.4 is the version to install: 0.1.3 has the same features but never reached npm.
+
+Then run `penguin web`, add a model key on the **Models** page, and state an objective.
diff --git a/packages/landing/content/blog/penguinharness-0-1-4.zh.md b/packages/landing/content/blog/penguinharness-0-1-4.zh.md
index fdb68419..8aa7bb25 100644
--- a/packages/landing/content/blog/penguinharness-0-1-4.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-1-4.zh.md
@@ -2,48 +2,75 @@
title: "PenguinHarness 0.1.4:Windows 支持、目标模式与智能体面板"
date: 2026-07-27
category: news
-excerpt: 0.1.4 只有一个主题——harness 来到你工作的地方,并在你离开后继续工作。Windows 有了自己的一行安装命令与完整 CI;新的目标模式让 Session 循环推进,直到目标真正完成而不是「回复完了」;新的智能体面板把子智能体的并发执行变成一张实时调用图。逐项说明如下。
+excerpt: 0.1.4 让 PenguinHarness 登陆 Windows,一行命令即可安装;新增目标模式,让会话一直推进到目标真正完成;子 Agent 移进智能体面板,以实时调用图呈现。
---
-PenguinHarness 0.1.4 发布了。这个版本只有一个主题:harness 来到你工作的地方,并在你离开后继续工作。它现在可以在 Windows 上安装运行;新的**目标模式**让 Session 循环推进,直到目标真正完成而不是「回复完了」;新的**智能体面板**把子智能体从层层嵌套的卡片变成一张可观察、可操作的实时调用图。逐项来看:
+PenguinHarness 0.1.4 发布了,现在可以在 Windows 上安装和运行。新增的**目标模式**让会话持续推进,直到目标真正完成,而不是模型回复一句就算结束。新增的**智能体面板**把子 Agent 的运行从层层嵌套的卡片变成一张实时调用图,可观察,也可操作。
-## Windows 成为一等公民
+## Windows 支持
-PowerShell 里一行命令:
+在 PowerShell 里用一行命令即可在 Windows 上安装 PenguinHarness:
```powershell
irm https://penguin.ooo/install.ps1 | iex
```
-它会下载 `penguin-win32-x64.zip`——内置官方 Windows Node 运行时,无需预装任何东西——校验 SHA256,用「先落地再替换」的方式解压安装(绝不触碰你的 `data\` 目录),并把 `penguin` 加入用户 PATH:注册表值按原始类型读写,已有的 `%USERPROFILE%` 风格条目不会被展开破坏。稳定地址是一个「完整下载后才执行」的转发脚本,截断的流不可能装出半个产品。偏好 npm 的话,`npm install -g @prismshadow/penguin-cli` 在任何 Node ≥ 24 的环境同样可用。
+脚本会下载 `penguin-win32-x64.zip`,包内自带官方 Windows 版 Node 运行时,无需预装任何东西。它会校验压缩包的 SHA256,用「先落地再替换」的方式安装,全程不碰你的 `data\` 目录,并把 `penguin` 加入用户 PATH。PATH 里已有的带变量条目(例如 `%USERPROFILE%`)会原样保留。稳定地址上的脚本只是一个转发器,它会先把完整的安装脚本下载下来再执行,即使下载中途断掉,也不会留下装到一半的程序。偏好 npm 的话,`npm install -g @prismshadow/penguin-cli` 在任何 Node ≥ 24 的环境都能用。
-有意思的部分不在打包,而在智能体本身。过去每一次 `exec_command` 在 Windows 上都死于 `spawn bash ENOENT`——命令会话把 bash 写死了。现在命令会话按平台解析 shell:优先 Git-Bash(与 POSIX 取向的技能生态兼容性最好;解析到 Windows 系统目录的 `bash` 会被拒绝——那是 WSL 启动器,完全是另一个文件系统视图),其次 `pwsh`,再次 `powershell`,`PENGUIN_SHELL` 可随时覆盖。选定的 shell 会通过会话环境里新增的 `Shell:` 一行告知模型,让它在拿到 PowerShell 时写 PowerShell 语法,而不是对着空气输出 bash。
+真正难的部分在 Agent 本身。以前在 Windows 上,每次 `exec_command` 都会报 `spawn bash ENOENT`,因为命令会话写死了 bash。现在命令会话按平台选择 shell:Windows 上优先尝试 Git-Bash,它和面向 POSIX shell 编写的 Skill 最兼容;其次是 `pwsh`,再次是 `powershell`。设置 `PENGUIN_SHELL` 可以覆盖这个选择。如果 `bash` 解析到 Windows 系统目录,就会跳过它,因为那是 WSL 启动器,看到的是另一套文件系统。
-这一切由 CI 保真:新增的 `ci-windows` 任务(完整构建、类型检查、测试,外加 PowerShell 语法门禁)与必需的 Ubuntu 任务并排运行;把它跑绿的过程本身就发现并修复了数个真实的 Windows 问题,包括一个此前由 POSIX 的 `O_NOFOLLOW` 默默兜底的工作区上传符号链接漏洞。剩余的限制如实写进文档而非假装不存在:安装包目前仅有 x64(ARM64 经转译运行),`input_command` 里的 Ctrl-C 会整树杀掉命令进程而非中断前台命令,升级方式是重跑安装器——`penguin update` 在 Windows 上仍拒绝原地更新。
+模型通过会话环境里的 `Shell:` 一行得知自己用的是哪种 shell。拿到 PowerShell 时,它就写 PowerShell 语法,而不是 bash。
-## 目标模式:循环到完成为止
+这些都由 CI 守住。除了必需的 Ubuntu 任务,现在还有一个 `ci-windows` 任务,运行完整的构建、类型检查和测试,外加 PowerShell 语法检查。把它跑绿的过程中发现并修复了几个真实的 Windows 问题,其中包括 Workspace 上传的符号链接防护:在 POSIX 系统上,这层防护一直由 `O_NOFOLLOW` 默默提供,Windows 上却没有。
-普通 Task 在模型停止调用工具并给出回复时结束。这对「一个请求」是对的,对「一个目标」是错的——「让检查套件全绿」不会因为模型不说话了就算完成。目标模式把契约倒了过来:你给出目标,系统在同一个 Session 上持续驱动 Task,每一轮重新注入目标,直到目标进入终态。
+目前仍有几项限制,文档里都写明了:
+
+- 安装包暂时只有 x64,ARM64 机器通过转译运行。
+- `input_command` 里的 Ctrl-C 会结束整棵命令进程树,而不是只中断前台命令。
+- 升级需要重新运行安装脚本。在 Windows 上,`penguin update` 仍然拒绝原地升级。
+
+## 目标模式
+
+普通 Task 在模型停止调用工具、给出回复时结束。这对「一个请求」是对的,对「一个目标」却不对:「让检查套件全绿」不会因为模型不说话了就算完成。目标模式改变了这个约定:你给出目标,系统在同一个会话上持续运行 Task,每一轮重新注入目标,直到目标进入终态。
+
+完成必须通过协议声明,沉默不算数。每次目标运行都会在会话的 `PLAN.md` 旁边创建一个 `GOAL.yaml` 文件。模型只能改其中一个字段 `status`,而且只能改成 `complete` 或 `blocked`。每轮注入的规则要求模型:
+
+- 声明完成之前,先对照证据自查,例如文件、命令输出和测试结果。
+- 不得把目标缩水成更容易的子集。
+- 同一个障碍连续存在三轮之后,才能声明 `blocked`,这样一时的阻碍不会让目标就此结束。
+
+还可以给目标设一个 Token 预算,例如 `500k` 或 `2m`,系统在每两轮之间检查一次。预算耗尽时,模型还有最后一个收尾轮,用来总结进展和剩余工作。随后目标以「预算耗尽」结束,而不是假装成功。
+
+在 Web App 里,输入框新增的 **+** 菜单可以挂上目标条,并直接在里面填写预算;斜杠菜单里的 `/goal` 效果相同。每一轮都显示为一条普通的用户消息,下方带「目标 · 第 N 轮」的标注;输入框上方的实时横幅显示目标、轮次,以及 Token 用量与预算的对比。下面的截图就是一次真实循环的第 3 轮,正在验证中。
<img class="dark:hidden" src="/blog-assets/goal-mode-zh-light.webp" alt="目标模式进行中:检查套件目标的第 3 轮,输入框上方的目标横幅实时显示目标、轮次与 token 用量对预算" width="1920" height="1350" />
<img class="hidden dark:block" src="/blog-assets/goal-mode-zh-dark.webp" alt="深色主题下的目标模式:检查套件目标的第 3 轮,输入框上方的目标横幅实时显示目标、轮次与 token 用量对预算" width="1920" height="1350" />
-完成必须通过协议声明,而不是从沉默里推断。每次目标运行都会在会话的 `PLAN.md` 旁创建一个 `GOAL.yaml`;模型只允许改动其中一个字段 `status`,且只能改成 `complete` 或 `blocked`。每轮注入的工作规则要求它:声明完成前先对照证据(文件、命令输出、测试结果)逐项自查;不得把目标缩水成更容易的子集;只有同一障碍连续三轮存在才可声明 `blocked`,一次性的阻碍不会终结目标。可选的 token 预算(`500k`、`2m`)在轮与轮之间检查;预算耗尽时模型获得最后一个收尾轮——总结进展、列出剩余工作——然后目标以「预算受限」结束,而不是伪装成功。
+CLI 提供同样的循环:聊天里用 `/goal[:<预算>] <目标>`,`penguin run` 则加上 `--goal`,此时只有目标真正完成,命令才以 0 退出,所以可以把目标直接写进脚本。SDK 仍然只有一个入口:`session.run(input, { goal: { budget } })`。
-在 Web App 里,输入框新增的「+」菜单可挂上目标条并内联填写预算(斜杠菜单里的 `/goal` 等价)。每一轮都渲染成一条普通的用户气泡,下方带「目标 · 第 N 轮」的标注;输入框上方的实时横幅跟踪目标、轮次与 token 用量对预算——上面的截图正是一次真实循环的第 3 轮验证现场。CLI 侧同样齐备:聊天里的 `/goal[:<预算>] <目标>`,以及 `penguin run` 的 `--goal`——只有真正完成的目标才以 0 退出,一个可以写进脚本的目标。SDK 保持唯一入口:`session.run(input, { goal: { budget } })`。
+## 智能体面板
-## 智能体面板:看清整棵树
+以前,`run_subagent` 会把每个子 Agent 的完整对话内联进父会话的消息流。卡片套卡片,超过两个子 Agent 就没法读了。0.1.4 把子 Agent 的对话移进专门的智能体面板。它和 Workspace 文件面板一样停靠在右侧:在工具栏里开关,拖拽调整宽度;在手机上则以底部抽屉的形式打开。
-`run_subagent` 过去把子会话的完整对话内联进父消息流——卡片套卡片,两个子智能体之后就没法读了。0.1.4 把子会话对话移进专门的**智能体面板**,像工作区文件面板一样停靠在右侧:工具栏开关、拖拽调宽、窄屏变成底部抽屉。消息流里每个子智能体只留下一条横条:头像、解析出的智能体名称、运行中的旋转指示,以及子树中任何位置有待审批时的琥珀色圆点——面板关着也不会错过嵌套审批。
+消息流里,每个子 Agent 只留下一行:头像、Agent 名称、运行中的旋转指示,以及一个琥珀色圆点,子树中任何位置有待审批时就会出现。即使面板关着,也不会错过嵌套的审批。
<img class="dark:hidden" src="/blog-assets/agents-panel-zh-light.webp" alt="智能体面板:调用图以主会话为根、两个具名子智能体带实时用时,下方是选中子会话的流式对话" width="1920" height="1350" />
<img class="hidden dark:block" src="/blog-assets/agents-panel-zh-dark.webp" alt="深色主题下的智能体面板:调用图以主会话为根、两个具名子智能体带实时用时,下方是选中子会话的流式对话" width="1920" height="1350" />
-面板顶部是一张**调用图**:每个参与的智能体一个节点——头像、名称、运行状态点与用时,运行中按墙钟实时走秒,结束后定格为实际耗时,刷新后的页面与实时页面显示同样的数字。主会话是根节点,边表示谁派生了谁。点击节点,下方对话切换到对应子会话,由与主消息流完全相同的机制渲染:它自己的用户提示词就在那里,工具卡片实时流式输出,审批按钮在面板里直接可用。可见性按任务划定作用域——每个新 Task 开始时面板关闭,任务第一次派生子智能体时自动打开一次,此后你的手动开合在该任务内始终优先。调用图默认跟随最新 Task;点击更早轮次的横条,则钉住那一轮的历史派生树。
+面板顶部是**调用关系**图,每个参与的 Agent 对应一个节点,显示头像、名称、运行状态圆点和用时。子 Agent 运行时,用时实时走秒;结束后定格为实际耗时,所以刷新后的页面和实时页面显示的数字一致。主会话是根节点,连线表示哪个 Agent 派生了哪个。
+
+点击节点,下方的对话就切换到这个子 Agent。它的渲染方式和主消息流相同:子 Agent 自己收到的用户消息也显示在其中,工具卡片实时流式输出,审批按钮在面板里直接可用。
+
+面板的显隐以 Task 为单位。每个新 Task 开始时面板关闭;Task 第一次派生子 Agent 时,面板自动打开一次。之后你手动打开或关闭面板,这个选择会一直保持到这个 Task 结束。调用图默认跟随最新的 Task;点击更早轮次里的子 Agent 行,则钉住那一轮的派生树。
-## 0.1.4 还有
+## 0.1.4 还有这些
-同一个版本里:进行中的回复现在能挺过页面刷新——服务端为每个运行中的会话维护实时尾部,刷新后已流出的前缀立即回来并继续增长;聊天页头部的费用与用时统计在 Task 运行期间实时走动,与此前就随请求推进的 token 计数并列;Trace 文件支持导出与导入,一条轨迹可以跨部署迁移;应用终于知道自己的版本——「检查更新」一行内联显示当前版本号,管理员可一键原地更新。完整清单见 [v0.1.4 发布说明](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.4)。
+- 正在生成的回复不会再因为刷新页面而丢失。刷新后,已经输出的部分立刻恢复,并接着往下生成。
+- Task 运行期间,对话页头部的费用和用时统计会实时更新,和此前就已实时更新的 Token 计数一样。
+- Trace 文件支持导出和导入,一条轨迹可以在不同部署之间迁移。
+- 应用现在能显示自己的版本号:用户菜单里的**检查更新**一行会显示当前运行的版本,管理员还能一键原地更新。
+
+完整清单见 [v0.1.4 发布说明](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.4)。
## 获取
@@ -57,4 +84,6 @@ curl -fsSL https://penguin.ooo/install.sh | sh
irm https://penguin.ooo/install.ps1 | iex
```
-或 `npm install -g @prismshadow/penguin-cli`(Node ≥ 24)——请安装 0.1.4:0.1.3 的功能集与之相同,但未能发布到 npm。然后 `penguin web`,在模型页配好密钥——给它一个目标。
+也可以在 Node ≥ 24 的环境里用 `npm install -g @prismshadow/penguin-cli` 安装。通过 npm 安装请选 0.1.4:0.1.3 的功能与之相同,但没能发布到 npm。
+
+然后运行 `penguin web`,在**模型仓库**页面添加模型密钥,再给它一个目标。
diff --git a/packages/landing/content/blog/penguinharness-0-1-5.en.md b/packages/landing/content/blog/penguinharness-0-1-5.en.md
index a4f97df4..304b8e2c 100644
--- a/packages/landing/content/blog/penguinharness-0-1-5.en.md
+++ b/packages/landing/content/blog/penguinharness-0-1-5.en.md
@@ -1,15 +1,17 @@
---
-title: "PenguinHarness 0.1.5: offline installs, richer input, and runs that recover"
+title: "PenguinHarness 0.1.5: offline installs, file attachments, and runs that recover"
date: 2026-07-30
category: news
-excerpt: 0.1.5 widens where PenguinHarness runs and what it can take in. Five self-contained offline bundles install it on machines with no network at all; the composer attaches any file and images now reach steering and goal objectives; nearly every LLM failure recovers inside the run instead of killing the turn; and the built-in skills learned a second visual language plus the thinking and image message kinds. Here is what shipped.
+excerpt: 0.1.5 adds five self-contained offline install bundles, lets the composer attach any file and send images with steering and goals, and retries nearly every LLM failure inside the run. The web-design Skill gains a second visual theme, and penguin-sdk documents thinking and image messages.
---
-PenguinHarness 0.1.5 is out. The release widens both ends of the pipe: where the harness can be installed — including machines that never touch the internet — and what you can hand it once it is running. In between, runs got sturdier: almost every LLM failure now recovers inside the run, and a mid-request Stop can no longer strand a Session. Feature by feature:
+PenguinHarness 0.1.5 is out. You can now install it on machines with no network at all, attach any type of file in the Web composer, and send images with steering messages and goal objectives. Runs are sturdier too: almost every LLM failure now recovers inside the run, and pressing Stop mid-request can no longer leave a Session stuck.
-## Install with no network at all
+## Install without a network
-Every GitHub Release now attaches **five self-contained offline bundles** — Linux and macOS in x64 and arm64, Windows in x64. Each bundle carries the program archive, its SHA256 checksum and the platform's own installer, so the whole flow is: download on any networked machine, copy to the target, run one command.
+The 0.1.5 GitHub Release attaches five self-contained offline bundles: Linux and macOS, each for x64 and arm64, and Windows for x64. Each bundle carries the program archive, its SHA256 checksum and the platform's own installer. Download a bundle on any machine with network access, copy it to the target machine, and run one command.
+
+On Linux or macOS, extract the bundle and run its installer. For the Linux x64 bundle:
```bash
mkdir penguin-offline
@@ -17,44 +19,61 @@ tar -xzf penguin-linux-x64-offline.tar.gz -C penguin-offline
./penguin-offline/install.sh
```
-On Windows, unzip `penguin-win32-x64-offline.zip` and double-click `install.cmd` — or run `.\install.ps1` in PowerShell. Offline installs verify the SHA256 unconditionally (there is no network to re-download from, so a corrupted archive must be caught, not tolerated), the POSIX bundles pass their payload to the installer explicitly rather than letting a script scan its directory, and a renamed archive still installs because platform packages now carry a target manifest inside.
+On Windows, unzip `penguin-win32-x64-offline.zip` and double-click `install.cmd`, or run `.\install.ps1` in PowerShell.
+
+Offline installs always verify the SHA256 checksum. With no network to download the archive again, a corrupted archive has to stop the install. A renamed archive still installs, because each package now records its target platform inside.
+
+The Windows package also bundles MinGit under `git/`, so `exec_command` has a real bash even on a machine without Git for Windows. If you have Git for Windows installed, it still takes precedence, because its MSYS userland is more complete. MinGit's GPLv2 obligations are recorded in a new `THIRD-PARTY-NOTICES.md` at the repository root.
+
+The install instructions were rewritten to match. The README now gives every method as a complete block you can copy and paste: Linux, macOS, Windows, npm and the offline bundles. The landing page's install section switches by operating system and method instead of listing everything at once.
+
+## Attach any file, steer with images
+
+The Web composer now attaches files of any type, not just images. Attachments are written to the Session scratchpad and passed to the model as `[attached file: <path>]` lines, with non-ASCII file names preserved, so the model reads them with its usual file tools.
+
+Images now reach every kind of input. A steering message sent mid-run can carry images, and an image with no caption is a complete steering message on its own. Steering does not carry files; an attached file waits for your next regular message. A goal objective accepts images as scratchpad paths. The paths are re-injected as text every round, so they work with every model, with or without vision.
+
+The composer's `@` mention is now an `/agent` command. Both switch commands, `/agent` and `/model`, are available inside an existing Session, not on a new-chat draft, and each places your pick as a chip above the text. The chip is saved with the draft and takes effect only when you press Enter to send: an agent chip hands the conversation off to a new chat with that agent, and a model chip forks the conversation onto the chosen model.
-The Windows package also grew a floor to stand on: it bundles MinGit under `git/`, so `exec_command` has a real bash even on a machine with no Git for Windows installed. Your own Git for Windows still wins when present — its MSYS userland is the fuller one — and the GPLv2 obligations are recorded in the new root `THIRD-PARTY-NOTICES.md`.
+## Runs that recover instead of failing
-The install story around the bundles is redone to match: the README now spells out every method — Linux, macOS, Windows, npm, and the offline packages — each as a complete copy-paste block, and the landing page's install sections switch by OS and method instead of listing everything at once.
+The classifier that separates transient LLM failures from permanent ones used to work from a list of known errors, so a gateway that described a transient fault in its own words ended the turn. 0.1.5 turns this around: every failure except a rejected credential now retries inside the run. The Web App shows the retry as a live countdown, and the CLI prints a `[retry]` line. Compaction retries under its own shorter budget, and a failure that recovers is no longer reported to the operator as an incident.
-## Attach anything, steer with images
+Two related fixes:
-The Web composer can now attach **files of any type**, not just images. Attachments are written into the Session scratchpad and handed to the model as `[attached file: <path>]` lines — non-ASCII filenames preserved — so the model reads them with its normal file tools, and the same attachment flow works mid-run.
+- Pressing **Stop** mid-request no longer leaves a Session running forever when a provider's stream neither returns data nor fails after the abort.
+- In the **Cost Center**, the error table pages back through the whole history, no longer records an ordinary non-zero exit (such as `grep` finding nothing) as an error, and marks entries that come from the environment with `[env]`.
-Images, meanwhile, now reach **every** input. Mid-run steering carries them (an image with no caption is a complete steering message by itself), and a goal objective accepts images as scratchpad paths — re-injected as text every round, they work on every model, vision or not.
+## Skills that design and build better apps
-The composer's `@` mention grew up into an `/agent` command, and both switch commands (`/agent`, `/model`) now stage their pick as a chip beside the text — cached with the draft, applied only when Enter sends, and session-only.
+Two built-in Skills took large steps in this release.
-## Runs that recover instead of dying
+### web-design
-The classifier separating transient from permanent LLM failures used to be an allowlist: a gateway that worded a transient fault its own way killed the turn. 0.1.5 inverts it — **every failure except a rejected credential now retries inside the run**, with the retry visible in both frontends as a live countdown, compaction retrying under its own shorter budget, and a recovered failure no longer reported to the operator as an incident.
+`web-design` now carries a second complete visual language next to its default GitHub-style simplicity: an opt-in *paper editorial* theme with warm paper tones, system serif display headings and small monospace labels.
-Two companions to that: pressing Stop mid-request can no longer leave a Session running forever when a provider's stream neither yields nor rejects after the abort; and the Cost center's error table now pages back through the whole history, stops recording an ordinary non-zero exit (`grep` finding nothing) as an error, and labels environment-sourced entries `[env]`.
+It also follows a "ship complete" contract. A one-line request is the whole spec, and every page it delivers includes dark mode, loading/empty/error states, a working keyboard path and zero external requests, without being asked. For chat interfaces, it adds recipes for a collapsible reasoning block and image attachments in the composer.
-## Skills that design — and build — better apps
+### penguin-sdk
-The built-in skill library took two big steps this release:
+`penguin-sdk` now documents the thinking and image message kinds that current models emit and accept, along with patterns for building on them:
-- **web-design** now carries a second complete visual language — an opt-in *paper editorial* theme with warm paper tones, system-serif display headings and mono micro-labels — next to the default GitHub-style simplicity, plus a "ship complete" contract: a one-line request is the whole spec, and every delivered page includes dark mode, loading/empty/error states, a working keyboard path and zero external requests, unasked. Chat interfaces gained recipes for a collapsible reasoning block and composer image attachments.
-- **penguin-sdk** documents the message kinds modern models actually emit and accept: stream `partial_thinking` into its own collapsed channel, build image input with `imageUrlMessage` (with the config `vision` flag degrading gracefully through the project's `vision_model`), fix the output format in the persona instead of shipping a Markdown renderer, and bridge cross-language BM25 retrieval with an ingest-time bilingual keyword map.
+- Stream `partial_thinking` into its own collapsed channel.
+- Build image input with `imageUrlMessage`. When the model config's `vision` flag is off, the image is passed as a file path that the built-in image tools read through the Project's `vision_model`, so the app still works.
+- Fix the output format in the persona instead of shipping a Markdown renderer.
+- Bridge cross-language BM25 retrieval with a bilingual keyword map built at ingest time.
-On top of both, the Web App's draft page gained an end-to-end **agent tuning example** — create, benchmark and optimize an Agent through isolated CLI sessions — and its example prompts got shorter, because the skills now carry the knowledge the prompts used to spell out.
+Because these two Skills now carry the knowledge the draft page's example prompts used to spell out, those prompts are shorter. The draft page also adds an end-to-end example of tuning an agent, built on the agent creation, Benchmark design, evaluation and optimization Skills: it creates, benchmarks and optimizes an agent through isolated CLI sessions.
## Also in 0.1.5
-- The default system prompt is about a tenth shorter (1087 → 969 words), pins replies to the user's language, and directs shared tooling into a per-Agent `shared_env/` directory. Existing Agents keep their own prompt.
-- Navigation entries settle on one name each; the Workspace and Agents panels share one width and one open/closed lifetime; Project display names are editable; the draft page's examples became a fixed-height folder shelf.
-- The chat header's elapsed chip survives reloads and counts in-flight events — anchored to the server's clock, so live and replayed views agree.
-- Pasting CJK or emoji into `penguin chat` no longer corrupts characters torn across stdin chunks.
-- Duration and byte formatting carry into the next unit instead of printing `1m60s` or `1024KB`.
-- `PORT` / `HOST` no longer leak into commands the Agent runs, and the development backend moved to port 7368, out of the installed `penguin web`'s way.
-- Docs catch up in three reference blocks: `run_subagent`'s `provider` argument, the gateway credential table, and the Project model entry's `max_tokens`.
+- The default system prompt is about a tenth shorter (1087 → 969 words). It tells the model to reply in the user's language and to install shared tooling into a per-agent `shared_env/` directory. Existing agents keep their own prompt.
+- Each navigation entry now has a single name. The Workspace and Agents panels share one width and the same open/closed behavior, Project display names are editable, and the draft page's examples become a fixed-height folder shelf.
+- The elapsed-time chip in the chat header survives reloads and counts in-flight events. It follows the server's clock, so live and replayed views agree.
+- Pasting CJK text or emoji into `penguin chat` no longer corrupts characters that arrive split across stdin chunks.
+- Durations and byte sizes roll over into the next unit instead of printing `1m60s` or `1024KB`.
+- `PORT` and `HOST` no longer leak into the commands an agent runs, and the development backend moved to port 7368, out of the way of an installed `penguin web`.
+- Three reference blocks in the docs caught up with the code: `run_subagent`'s `provider` argument, the gateway credential table and the Project model entry's `max_tokens`.
## Install or upgrade
@@ -70,4 +89,4 @@ irm https://penguin.ooo/install.ps1 | iex
penguin web
```
-Or `npm install -g @prismshadow/penguin-cli` with Node >= 24 — and from this release, fully offline from the [Release assets](https://github.com/Prism-Shadow/penguin-harness/releases). Full detail per change: [changelog/0.1.5](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.5).
+You can also install from npm with Node >= 24: `npm install -g @prismshadow/penguin-cli`. From this release, you can also install fully offline with the bundles attached to the [v0.1.5 Release](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.5); the steps are under "Install without a network" above. Every change is described in detail in [changelog/0.1.5](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.5).
diff --git a/packages/landing/content/blog/penguinharness-0-1-5.zh.md b/packages/landing/content/blog/penguinharness-0-1-5.zh.md
index b0bc352a..4b95009f 100644
--- a/packages/landing/content/blog/penguinharness-0-1-5.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-1-5.zh.md
@@ -1,15 +1,17 @@
---
-title: "PenguinHarness 0.1.5:离线安装、更丰富的输入与更稳的运行"
+title: "PenguinHarness 0.1.5:离线安装、文件附件与能自动恢复的运行"
date: 2026-07-30
category: news
-excerpt: 0.1.5 同时拓宽了 PenguinHarness 的两端:五个自包含离线安装包让它装进完全没有网络的机器;composer 可以附加任意类型的文件,图像也进入了中途引导与目标模式;几乎所有 LLM 故障都在运行内自动恢复而不再终止任务;内置技能学会了第二套视觉语言,并写清了 thinking 与图像这两类消息的用法。逐项说明如下。
+excerpt: 0.1.5 新增五个自包含的离线安装包;输入框可以附加任意文件,插话和目标也能带上图片;几乎所有 LLM 故障都会在运行内重试。web-design Skill 新增第二套视觉主题,penguin-sdk 补上了思考消息和图片消息的用法。
---
-PenguinHarness 0.1.5 发布了。这个版本把管道的两端同时拓宽:harness 能装在哪里——包括从不联网的机器;装好之后你能递给它什么。中间那段也更结实了:几乎所有 LLM 故障都在运行内自动恢复,请求中途按下 Stop 也不再可能让 Session 悬死。逐项来看:
+PenguinHarness 0.1.5 发布了。现在可以在完全没有网络的机器上安装,在 Web 输入框里附加任意类型的文件,还能随插话和目标一起发送图片。运行也更稳了:几乎所有 LLM 故障都能在运行内恢复,请求中途按下「停止」也不会再让会话卡住。
-## 完全离线也能安装
+## 离线安装
-每个 GitHub Release 现在附带**五个自包含离线安装包**——Linux 与 macOS 各有 x64、arm64 两种架构,Windows 为 x64。包内自带程序压缩包、SHA256 校验文件与对应平台的安装器,完整流程就是:在任意有网机器下载、拷贝到目标机器、跑一条命令。
+0.1.5 的 GitHub Release 附带五个自包含的离线安装包:Linux 和 macOS 各有 x64 和 arm64 两种,Windows 为 x64。每个安装包里有程序压缩包、它的 SHA256 校验文件和对应平台的安装器。在任意一台能联网的机器上下载安装包,拷到目标机器,运行一条命令即可。
+
+在 Linux 或 macOS 上,解压安装包并运行里面的安装器。以 Linux x64 安装包为例:
```bash
mkdir penguin-offline
@@ -17,44 +19,61 @@ tar -xzf penguin-linux-x64-offline.tar.gz -C penguin-offline
./penguin-offline/install.sh
```
-Windows 上解压 `penguin-win32-x64-offline.zip` 后双击 `install.cmd` 即可——或在 PowerShell 里运行 `.\install.ps1`。离线安装无条件校验 SHA256(没有网络可以重新下载,损坏的包必须被拦下而不是被容忍);POSIX 离线包把安装载荷显式传给安装器,而不是让脚本扫描所在目录;平台包内置目标清单,改过名的压缩包也能正常安装。
+在 Windows 上,解压 `penguin-win32-x64-offline.zip` 后双击 `install.cmd`,或者在 PowerShell 中运行 `.\install.ps1`。
+
+离线安装一律校验 SHA256。离线环境没法重新下载,压缩包一旦损坏,就只能中止安装。改过名的压缩包仍然可以安装,因为每个安装包内部都记录了自己的目标平台。
+
+Windows 安装包还在 `git/` 下内置了 MinGit,所以即使机器上没装 Git for Windows,`exec_command` 也有真正的 bash 可用。如果你装了 Git for Windows,仍然优先使用它,因为它的 MSYS 用户层更完整。MinGit 的 GPLv2 义务记录在仓库根目录新增的 `THIRD-PARTY-NOTICES.md` 中。
+
+安装说明也随之重写。README 现在把每种安装方式都写成可以整段复制的完整代码块:Linux、macOS、Windows、npm 和离线安装包。官网落地页的安装区按操作系统和安装方式切换,不再一次列出全部内容。
+
+## 附加任意文件,用图片插话
+
+Web 输入框现在可以附加任意类型的文件,不再只限图片。附件写入会话的 scratchpad,以 `[attached file: <path>]` 行的形式交给模型,非 ASCII 文件名原样保留,模型用常规的文件工具就能读取。
+
+现在所有输入都能带上图片。运行中途发送的插话可以携带图片,不带文字说明的图片本身就是一条完整的插话。文件则不随插话发出,会留到你的下一条普通消息里再发送。目标也可以通过 scratchpad 路径包含图片,这些路径每轮都会以文本形式重新注入,所以无论模型是否支持视觉都能用。
+
+输入框的 `@` 提及改成了 `/agent` 命令。`/agent` 和 `/model` 这两个切换命令只在已有会话里可用,新对话的草稿里没有;它们会把你选中的项以标签形式放在文字上方。标签随草稿一起保存,按 Enter 发送时才生效:Agent 标签会新开一个与该 Agent 的对话来接手,模型标签则把当前对话分叉到选中的模型上继续。
-Windows 安装包还多了一块「地板」:内置 MinGit(位于 `git/`),即使机器上没装 Git for Windows,`exec_command` 也有真正的 bash 可用。装了 Git for Windows 时仍然优先用你自己的——它的 MSYS 用户层更完整;GPLv2 义务记录在新增的根目录 `THIRD-PARTY-NOTICES.md` 中。
+## 运行出错也能自动恢复
-围绕离线包,安装文档也整体重做:README 把每种方式——Linux、macOS、Windows、npm、离线安装包——都写成可整段复制的完整代码块;官网落地页的安装区改为按系统与方式切换展示,不再全部平铺。
+过去,区分 LLM 暂时性故障和永久性故障的分类器依据的是一份已知错误清单,网关只要换个说法描述暂时性故障,这一轮就直接结束。0.1.5 把逻辑反了过来:除了凭证验证失败,所有故障都会在运行内重试。Web App 会以实时倒计时显示重试,CLI 则打印一行 `[retry]`。压缩请求在自己更短的预算内重试,恢复成功的故障也不再当成事故报告给管理员。
-## 附加任意文件,用图像引导
+两个相关修复:
-Web composer 现在可以附加**任意类型的文件**,不再局限于图像。附件写入 Session 暂存目录,以 `[attached file: <path>]` 行交给模型——非 ASCII 文件名原样保留——模型用常规文件工具读取,运行中途同样可以附加。
+- 请求中途按下**停止**时,即使供应商的流在中止后既不返回数据也不报错,会话也不会再一直处于运行状态。
+- **成本中心**的错误表可以往前翻页查看全部历史;普通的非零退出(例如 `grep` 没搜到结果)不再记为错误;来自环境的条目会标上 `[env]`。
-图像则进入了**所有**输入通道:中途引导可以携带图像(不带文字说明的图像本身就是一条完整的引导消息);目标模式的 objective 以暂存目录路径的形式接受图像——每轮以文本重新注入,因此无论模型是否具备视觉能力都可用。
+## 会设计也会构建应用的 Skill
-composer 的 `@` 提及升级为 `/agent` 命令,两个切换命令(`/agent`、`/model`)的选择都以纸片形式暂存在输入框旁——与草稿一同缓存,按下 Enter 发送时才生效,且仅作用于当前会话。
+这个版本里,两个内置 Skill 都有了大幅改进。
-## 运行不再死于一次故障
+### web-design
-区分暂时性与永久性 LLM 故障的分类器过去是一张允许名单:网关用自己的措辞描述一次暂时故障,任务就被判死。0.1.5 把它反了过来——**除凭证被拒外的所有故障都在运行内重试**,重试在两个前端都以倒计时可见,压缩请求在自己更短的预算内重试,恢复成功的故障也不再作为事故报给管理员。
+`web-design` 在默认的 GitHub 式简洁风格之外,新增了第二套完整的视觉语言:可选的 *paper editorial*(纸质编辑风)主题,采用暖纸色调、系统衬线体标题和等宽小标签。
-两项配套:请求中途按 Stop,即使供应商的流在中止后既不产出也不报错,Session 也不再可能永远悬着;成本中心的错误表可以翻页回看全部历史,普通的非零退出(`grep` 没搜到)不再被记为错误,环境来源的条目标注为 `[env]`。
+它还遵循「交付即完整」的约定:一句话需求就是完整规格,交付的每个页面都会主动包含暗色模式、加载/空/错误状态、可用的键盘操作路径,而且不发出任何外部请求。对于聊天界面,它新增了可折叠推理块和输入框图片附件两种做法。
-## 会设计、也会构建的技能库
+### penguin-sdk
-内置技能库这个版本迈了两大步:
+`penguin-sdk` 现在写清了当前模型发出和接收的思考消息与图片消息,以及基于它们构建应用的做法:
-- **web-design** 在默认的 GitHub 风格简洁语言之外,新增第二套完整视觉语言——可选的「纸质编辑风」主题:暖纸色调、系统衬线大标题、等宽小标签;并立下「交付即成品」的约定:一句话请求就是完整规格,交付页面默认包含暗色模式、加载/空态/错误状态、完整键盘路径与零外部请求。聊天界面新增了可折叠思考块与 composer 图像附件的配方。
-- **penguin-sdk** 写清了现代模型真正收发的消息类型:把 `partial_thinking` 流入独立的折叠通道,用 `imageUrlMessage` 构造图像输入(配置的 `vision` 标志经项目 `vision_model` 平滑降级),在 persona 里约定输出格式而不是在 UI 里搭 Markdown 渲染管线,并用 ingest 时生成的双语关键词映射弥合跨语言 BM25 检索。
+- 把 `partial_thinking` 流式输出到独立的可折叠区域。
+- 用 `imageUrlMessage` 构造图片输入。模型配置的 `vision` 标志关闭时,图片会以文件路径的形式传入,由内置图片工具通过 Project 的 `vision_model` 读取,应用照样能用。
+- 在 persona 里固定输出格式,而不是附带一个 Markdown 渲染器。
+- 用入库时生成的双语关键词映射,打通跨语言的 BM25 检索。
-在这之上,Web 应用的草稿页新增了端到端的 **Agent 调优示例**——通过相互隔离的 CLI 会话创建、评测并优化一个 Agent;示例提示词也变短了,因为过去要在提示词里写明的知识,现在由技能承载。
+草稿页示例提示词过去要写明的知识,现在由这两个 Skill 承载,所以这些提示词都变短了。草稿页还新增了一个端到端的 Agent 调优示例,它基于 Agent 创建、Benchmark 设计、评估和优化这几个 Skill:通过相互隔离的 CLI 会话创建 Agent、用 Benchmark 评估,再做优化。
## 0.1.5 还有这些
-- 默认系统提示词缩短约十分之一(1087 → 969 词),回复语言锁定用户语言,共享工具装入 Agent 级 `shared_env/` 目录。已有 Agent 保持自己的提示词不变。
-- 导航条目名称统一;Workspace 与 Agents 面板共用宽度与开合状态;Project 显示名可编辑;草稿页示例改为定高折叠书架。
-- 会话头部的耗时纸片在刷新后不再归零,并统计在途事件——锚定服务器时钟,直播与回放一致。
-- 向 `penguin chat` 粘贴中文或 emoji 不再因 stdin 分块撕裂字符而出现乱码。
-- 时长与字节的缩写会正确进位,不再出现 `1m60s` 或 `1024KB`。
-- `PORT` / `HOST` 不再泄漏进 Agent 运行的命令;开发后端移至 7368 端口,与已安装的 `penguin web` 互不干扰。
-- 文档补齐三处参考:`run_subagent` 的 `provider` 参数、网关凭证表、Project 模型条目的 `max_tokens`。
+- 默认系统提示词缩短了约十分之一(1087 → 969 词)。它要求模型用用户的语言回复,并把共享工具安装到每个 Agent 专属的 `shared_env/` 目录。已有 Agent 保留各自的提示词。
+- 导航项的名称统一了,每一项在各处只用一个名字。Workspace 面板和智能体面板共用同一个宽度,开合规则也相同;Project 的显示名称可以编辑;草稿页的示例改成固定高度的文件夹式书架。
+- 对话页头部的用时标签刷新后依然保留,并会计入尚未结束的事件。它以服务器时钟为准,所以实时视图和回放视图显示一致。
+- 向 `penguin chat` 粘贴 CJK 文本或 emoji 时,分散在多个 stdin 块中的字符不再出现乱码。
+- 时长和字节大小会正确进位,不再显示 `1m60s` 或 `1024KB`。
+- `PORT` 和 `HOST` 不再泄漏到 Agent 执行的命令中;开发后端改用 7368 端口,与已安装的 `penguin web` 互不干扰。
+- 文档里三处落后于代码的参考内容已经补齐:`run_subagent` 的 `provider` 参数、网关凭证表,以及 Project 模型条目的 `max_tokens`。
## 安装或升级
@@ -70,4 +89,4 @@ irm https://penguin.ooo/install.ps1 | iex
penguin web
```
-也可以在 Node >= 24 环境 `npm install -g @prismshadow/penguin-cli`——从这个版本起,还可以用 [Release 附件](https://github.com/Prism-Shadow/penguin-harness/releases)完全离线安装。每项改动的完整细节见 [changelog/0.1.5](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.5)。
+也可以在 Node >= 24 的环境下从 npm 安装:`npm install -g @prismshadow/penguin-cli`。从这个版本起,还可以用 [v0.1.5 Release](https://github.com/Prism-Shadow/penguin-harness/releases/tag/v0.1.5) 附带的安装包完全离线安装,步骤见上文「离线安装」一节。每项改动的详细说明见 [changelog/0.1.5](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.1.5)。
diff --git a/packages/landing/content/blog/penguinharness-0-2-0.en.md b/packages/landing/content/blog/penguinharness-0-2-0.en.md
index c46bd1a6..ebf10eea 100644
--- a/packages/landing/content/blog/penguinharness-0-2-0.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-0.en.md
@@ -1,41 +1,66 @@
---
-title: "PenguinHarness 0.2.0: navigable chats, recoverable output, installs from anywhere"
+title: "PenguinHarness 0.2.0: chat navigation, recoverable tool output, mirrored installers"
date: 2026-08-03
category: news
-excerpt: 0.2.0 makes long agent runs livable. The chat gains shell-style input recall, stacked sticky run headers and a minimap tick rail; tool output that blows past the cap is saved and recoverable instead of gone; steering survives reloads and carries files; the session list scales to many agents; each Release ships one sealed installer bundle per platform, now mirrored to Alibaba Cloud OSS; and the model catalog moves to the current qianwenai lineup. Here is what shipped.
+excerpt: 0.2.0 makes long agent runs easier to work with: input recall, sticky run headers and a minimap in the chat, recoverable tool output, and steering that survives reloads. Installers now prefer an Alibaba Cloud OSS mirror.
---
-PenguinHarness 0.2.0 is out. The theme is long-running work: conversations you can move through instead of scrolling past, tool output that cannot be lost to a cap, and a distribution pipe that reaches machines GitHub does not. Feature by feature:
+PenguinHarness 0.2.0 is out, and this release is about long-running work. Long conversations get three navigation aids, tool output that exceeds the cap can be recovered, and steering messages survive a reload. Each Release now ships one installer bundle per platform, mirrored to Alibaba Cloud OSS, and the model catalog moves to the current lineup.
## Navigate long conversations
-Three navigation aids land on the chat page together.
+The chat page gains three ways to move through a long Session.
-**↑ recalls your previous inputs, shell-style.** With an empty composer, ↑ steps back through everything you typed into this session, newest first; ↓ walks forward again and restores whatever draft you had. Editing a recalled entry hands the arrows back to the caret, multi-line entries move the caret line by line first, and IME candidate navigation is untouched.
+### Recall earlier inputs
-**Sticky run headers, stacked by level.** The "Reasoning & Tools" header pins to the top of the stream while its run is in view, and the thinking or tool row you are actually scrolled inside pins right below it — the bar above the content is always the section being read, never a skipped level. A twenty-screen tool dump collapses from anywhere inside it, per section or as a whole, and collapsing lands you back on the section instead of somewhere unrelated.
+When the composer is empty, press ↑ to step back through what you typed in this Session, newest first, as in a shell. Press ↓ to step forward again; past the newest entry, your draft comes back. Editing a recalled entry hands the arrow keys back to the caret. In a multi-line entry, the arrows move the caret line by line first, and IME candidate navigation is unaffected.
-**A minimap for the whole conversation.** A zero-width tick rail overlays the left gutter — one tick per exchange, the reading position emphasized. Hovering a tick pops a preview card (your question in bold over a truncated reply), clicking jumps straight to the turn. On phones, or whenever a docked panel eats the gutter, the same index moves to a top-right toolbar dropdown, so navigation stays reachable in every layout.
+### Sticky run headers
-## Tool output that survives truncation
+While a group of reasoning and tool calls is in view, its header stays pinned to the top of the stream. The thinking or tool row you are scrolled into pins directly below it, so the bar above the text is always the section you are reading. You can collapse a long tool output from anywhere inside it, one section or the whole group, and the view lands back on that section.
-Output exceeding the per-call cap in an Agent Session is written to the Session scratchpad, and the recovery path is appended to the same truncated result the model and both frontends see. The model reads the rest by path when it matters — no new tool, no protocol change, and the visible cap stays. Alongside it, every model-visible path core composes now shares one forward-slash spelling on Windows.
+### A minimap for the conversation
-## Steering and a session list built for scale
+A tick rail sits over the chat's left margin without taking any width: one tick per exchange, with your reading position highlighted. Hover over a tick to see a preview card with your question in bold above a shortened reply, and click to jump to that turn. On phones, or when a docked panel covers the margin, the same index moves to a dropdown in the top-right toolbar.
-Mid-run steering messages now survive reloads with their content visible and land exactly once — and file attachments steer just like images do. Tool-card subtitles render once fully formed instead of jittering while arguments stream. The sidebar session list is served straight from the database by default (CLI sessions become an opt-in toggle), and both the per-group lists and the groups themselves page, so a Project with many agents and workspaces stays fast and scannable.
+## Recover truncated tool output
-## One installer artifact per platform — mirrored
+In a Session run by an agent, output that exceeds the per-call cap is now saved to the Session scratchpad. The truncated result that the model, the Web App and the CLI see ends with the path to that file, and the model reads the rest from there when it needs to. No new tool or protocol change is involved, and the visible cap stays the same.
-Each Release attaches exactly one file per target: a flat installer bundle sealing the native installer, the program payload and its checksum. The same file serves online and offline installs, with checksums verified unconditionally at both layers. New in the pipe: the exact same bytes are mirrored to Alibaba Cloud OSS, and the installers prefer the mirror with an automatic same-version GitHub fallback (`PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`). In-place upgrades also survive filesystems that pin in-use directories, and the Windows payload drops its policy-blocked `penguin.ps1` launcher — typing `penguin` is unaffected.
+On Windows, every path the harness shows the model now uses forward slashes.
+
+## Steering that survives reloads, and a faster session list
+
+A steering message you send during a run now survives a page reload with its content still visible, and reaches the agent exactly once. File attachments can steer a run, just as images can.
+
+The sidebar session list now comes straight from the database, and both the sessions in each group and the groups themselves are shown a page at a time. A Project with many agents and Workspaces stays fast and easy to scan. CLI sessions no longer appear in the list by default; the **Show CLI sessions** switch in the user menu brings them back.
+
+## One installer per platform, mirrored to Alibaba Cloud OSS
+
+Each Release now attaches exactly one file per platform: an installer bundle that contains the native installer, the program payload and its checksum. The same file serves online and offline installs, and checksums are always verified.
+
+The installers now prefer a mirror on Alibaba Cloud OSS that carries the exact same bytes, and fall back to the same version on GitHub automatically. Set `PENGUIN_DOWNLOAD_SOURCE=auto|oss|github` to choose the source.
+
+Two install fixes ship with it:
+
+- In-place upgrades no longer fail on filesystems that lock directories in use, such as overlayfs in Docker.
+- The Windows package drops its `penguin.ps1` launcher, which PowerShell's execution policy blocked. Typing `penguin` still works.
## A current model catalog
-The qianwenai groups move to the current lineup — qwen3.8-max and deepseek-v4-flash-0731 in, the retired previews out — OpenRouter gains deepseek/deepseek-v4-flash-0731 and openai/gpt-5.6-luna, every gateway row's prices are re-read from the models API, and new Projects default to deepseek-v4-flash. Existing Projects keep their stored models and default.
+The qianwenai groups move to the current lineup: `qwen3.8-max` and `deepseek-v4-flash-0731` are added, and retired entries such as `qwen3.8-max-preview` are removed. OpenRouter adds `deepseek/deepseek-v4-flash-0731` and `openai/gpt-5.6-luna`, and every OpenRouter price has been re-read from its models API.
+
+New Projects default to `deepseek-v4-flash`. Existing Projects keep the models and the default they already have.
-## And the rest
+## Other changes
-`read_file` / `edit_file` diagnose a missing path (deepest existing ancestor, first missing segment, nearest names) instead of a bare "File not found". The manual update check reports every outcome — busy, up to date, update found, failed. Evaluation Center case details separate the target agent's task materials from reviewer-facing rubrics. File summaries move to the Task boundary, one card per completed Task. The full list, entry by entry: [changelog/0.2.0](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.0).
+- `read_file` and `edit_file` diagnose a missing path instead of returning a bare "File not found". They report the deepest existing ancestor, the first missing segment and the nearest matching names.
+- The manual update check reports every outcome: checking, up to date, update found, or failed.
+- Tool-card subtitles appear once they are complete, instead of jittering while the arguments stream in.
+- In the Evaluation Center, case details show the task materials the target agent receives separately from the scoring rubrics, which stay hidden from that agent.
+- The file summary in the main conversation now waits for the Task to finish: one card per completed Task.
+
+The full list, entry by entry, is in [changelog/0.2.0](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.0).
## Install or upgrade
@@ -44,4 +69,6 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows (PowerShell): `irm https://penguin.ooo/install.ps1 | iex` — or `npm install -g @prismshadow/penguin-cli` with Node >= 24. Upgrading is re-running the installer, or `penguin update` from 0.1.3+.
+On Windows, run `irm https://penguin.ooo/install.ps1 | iex` in PowerShell. With Node >= 24, you can also install from npm: `npm install -g @prismshadow/penguin-cli`.
+
+To upgrade, re-run the installer. On Linux and macOS, `penguin update` works too, from 0.1.3 or later.
diff --git a/packages/landing/content/blog/penguinharness-0-2-0.zh.md b/packages/landing/content/blog/penguinharness-0-2-0.zh.md
index 5e4c8985..86c4104b 100644
--- a/packages/landing/content/blog/penguinharness-0-2-0.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-0.zh.md
@@ -1,41 +1,66 @@
---
-title: "PenguinHarness 0.2.0:长对话导航、可找回的工具输出、随处可装"
+title: "PenguinHarness 0.2.0:对话导航、可找回的工具输出、镜像安装包"
date: 2026-08-03
category: news
-excerpt: 0.2.0 让长时间运行的 Agent 用起来更顺手:对话页新增命令行式输入回填、分层吸顶的运行标题栏和迷你刻度导航;超长工具输出落盘可找回而不再丢失;插话在刷新后仍在、还能带文件附件;会话列表按数据库直出、支撑大量 Agent;每个 Release 只发一个平台安装包,并镜像到阿里云 OSS;模型目录换到 qianwenai 当前阵容。逐项看看。
+excerpt: 0.2.0 让长时间运行的 Agent 更好用:对话页新增历史输入回填、吸顶的运行标题和迷你地图,超出上限的工具输出可以找回,插话刷新后依然保留。安装包现在优先从阿里云 OSS 镜像下载。
---
-PenguinHarness 0.2.0 发布了。这一版围绕"长时间运行的工作":对话可以导航而不是一路滚动、工具输出不会被截断上限吞掉、分发管道能到达 GitHub 不可达的机器。逐项说明:
+PenguinHarness 0.2.0 发布了,这一版的重点是长时间运行的任务。长对话多了三种导航方式,超出上限的工具输出可以找回,插话在刷新页面后也不会丢。每个 Release 现在为每个平台只提供一个安装包,并镜像到阿里云 OSS;模型目录也换成了当前的阵容。
-## 长对话导航
+## 浏览长对话
-对话页一次落地三件导航能力。
+对话页新增三种方式,方便在长会话里来回浏览。
-**↑ 命令行式回填历史输入。** 输入框为空时按 ↑,从最新一条开始逐条回填本会话输入过的内容;↓ 反向走回并恢复原来的草稿。编辑过的回填立即把方向键还给光标,多行条目先逐行移动光标,输入法候选导航不受影响。
+### 回填历史输入
-**运行标题栏分层吸顶。**「Reasoning & Tools」组头钉在消息流顶部,你正滚动阅读的思考 / 工具行紧贴其下再钉一层——内容正上方的横条永远是它所属的段落,不跨层级。二十屏长的工具输出滚到任何位置都能一键收起所在段或整组,收起后视图落回该段本身。
+输入框为空时按 ↑,会像 shell 一样从最新一条开始,逐条回填你在本会话中输入过的内容;按 ↓ 往回走,越过最新一条后,原来的草稿会恢复。编辑回填的内容后,方向键重新用于移动光标。多行内容里,方向键先逐行移动光标,输入法的候选词切换不受影响。
-**整场对话的迷你地图。** 一列零宽度的刻度线覆在消息流左侧留白上,每轮问答一条、当前所读加长加深;悬停弹出预览卡(问题加粗 + 截断的回答),点击直达该轮。手机上或侧面板挤占留白时,同一份索引移到右上角工具栏下拉菜单——任何布局下导航都可达。
+### 运行标题吸顶
-## 截断的工具输出可找回
+一组推理和工具调用还在视野内时,它的标题会吸附在消息流顶部;你正在阅读的思考行或工具行,则吸附在组标题正下方。这样,正文上方的横条始终是你正在读的那一节。很长的工具输出滚到任何位置都能直接折叠,可以只折叠一节,也可以折叠整组,折叠后视图会回到这一节。
-Agent 会话中超过单次上限的工具输出会写入会话 scratchpad,找回路径附在模型与两个前端看到的同一条截断结果末尾;需要时模型按路径读取其余部分——没有新工具、协议不变、可见上限不变。同批改动里,core 组装的所有模型可见路径在 Windows 上统一为正斜杠拼写。
+### 对话迷你地图
-## 插话与会话列表的规模化
+对话左侧的留白处叠加了一列刻度,不占任何宽度:每轮问答一个刻度,当前阅读位置会高亮。鼠标悬停在刻度上会弹出预览卡片,上方是加粗的问题,下方是截断的回复;点击刻度即可跳到那一轮。在手机上,或者停靠的面板占掉左侧留白时,这份索引会移到右上角工具栏的下拉菜单里。
-运行中的插话现在刷新后仍在、内容可见、恰好送达一次——文件附件也能随插话送出,与图片同规。工具卡副标题不再随参数流式渲染而抖动。侧栏会话列表默认由数据库直出(CLI 会话变为可选开关),分组内列表与分组本身都分页,大量 Agent 与 Workspace 的 Project 依然快而可扫。
+## 找回截断的工具输出
-## 每平台一个安装包,且有镜像
+在由 Agent 运行的会话里,单次调用超出上限的输出现在会保存到会话的 scratchpad 中。模型、Web App 和 CLI 看到的截断结果末尾会附上这个文件的路径,模型需要时可以按路径读取其余内容。这不需要新工具,协议不变,可见的上限也不变。
-每个 Release 每个平台只附一个文件:一个扁平安装包,内封原生安装器、程序负载与校验和。同一个文件同时服务在线与离线安装,两层校验无条件执行。管道新增:完全相同的字节镜像到阿里云 OSS,安装器优先走镜像、自动回退同版本 GitHub(`PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`)。原地升级也能在钉住占用目录的文件系统上完成,Windows 包移除了会被执行策略拦下的 `penguin.ps1` 启动器——直接敲 `penguin` 不受影响。
+在 Windows 上,Harness 交给模型的所有路径现在都统一使用正斜杠。
-## 跟上时代的模型目录
+## 刷新不丢的插话,以及更快的会话列表
-qianwenai 分组换到当前阵容——qwen3.8-max 与 deepseek-v4-flash-0731 上架,退役的 preview 下架——OpenRouter 新增 deepseek/deepseek-v4-flash-0731 与 openai/gpt-5.6-luna,各网关行价格按模型 API 重新读取,新 Project 默认 deepseek-v4-flash。已有 Project 保持原有模型与默认值不变。
+运行中发送的插话,现在刷新页面后仍会保留、内容可见,并且只会送达 Agent 一次。和图片一样,文件附件现在也可以随插话发送。
-## 其余改进
+侧栏的会话列表现在直接从数据库读取,分组内的会话和分组本身都分页显示,Agent 和 Workspace 再多的 Project 也能保持流畅、便于浏览。CLI 会话默认不再显示在列表里,打开用户菜单中的**显示 CLI 会话**开关,就能让它们重新出现。
-`read_file` / `edit_file` 对缺失路径给出诊断(最深存在的祖先、第一个缺失段、邻近同名项)而不是一句 "File not found"。手动检查更新汇报每种结果——检查中、已最新、发现新版、失败。评估中心的 Case 详情把目标 Agent 的任务材料与评审侧评分标准分开。文件摘要移到任务边界,每个完成的任务一张卡。完整清单逐条见 [changelog/0.2.0](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.0)。
+## 每个平台一个安装包,镜像到阿里云 OSS
+
+每个 Release 现在为每个平台只附带一个文件:一个安装包,内含原生安装器、程序负载和负载的校验和。在线安装和离线安装共用这一个文件,而且每次都会做校验。
+
+安装器现在优先从阿里云 OSS 镜像下载,镜像里的文件与 GitHub 上的逐字节一致,必要时自动回退到 GitHub 上的同一版本。设置 `PENGUIN_DOWNLOAD_SOURCE=auto|oss|github` 可以指定下载源。
+
+同时修复了两个安装问题:
+
+- 在会锁住使用中目录的文件系统上(例如 Docker 的 overlayfs),原地升级不再失败。
+- Windows 安装包去掉了 PowerShell 执行策略会拦下的 `penguin.ps1` 启动器,直接输入 `penguin` 仍然可用。
+
+## 模型目录换到当前阵容
+
+qianwenai 分组换到当前阵容:新增 `qwen3.8-max` 和 `deepseek-v4-flash-0731`,移除 `qwen3.8-max-preview` 等已下线的条目。OpenRouter 新增 `deepseek/deepseek-v4-flash-0731` 和 `openai/gpt-5.6-luna`,OpenRouter 的全部价格也按它的 models API 重新核对了一遍。
+
+新建的 Project 默认使用 `deepseek-v4-flash`。已有 Project 保留原来的模型和默认模型。
+
+## 其他改进
+
+- `read_file` 和 `edit_file` 遇到不存在的路径时会给出诊断,不再只返回一句「File not found」:它们会指出最深一级仍然存在的上级路径、第一个缺失的路径段,以及名称最接近的条目。
+- 手动检查更新会反馈每一种结果:检查中、已是最新、发现新版本或检查失败。
+- 工具卡片的副标题等内容完整后才显示,不再随参数流式传入而抖动。
+- 评估中心的题目详情把目标 Agent 拿到的任务材料和评分标准分开展示,评分标准对目标 Agent 始终不可见。
+- 主对话里的文件摘要现在等 Task 结束后才出现:每个完成的 Task 一张卡片。
+
+完整清单逐条见 [changelog/0.2.0](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.0)。
## 安装或升级
@@ -44,4 +69,6 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows(PowerShell):`irm https://penguin.ooo/install.ps1 | iex`;或在 Node >= 24 下 `npm install -g @prismshadow/penguin-cli`。升级即重跑安装器,0.1.3+ 也可直接 `penguin update`。
+Windows 上请在 PowerShell 中运行 `irm https://penguin.ooo/install.ps1 | iex`。Node >= 24 的环境也可以从 npm 安装:`npm install -g @prismshadow/penguin-cli`。
+
+升级只需重新运行安装器;在 Linux 和 macOS 上,0.1.3 及以上版本也可以直接运行 `penguin update`。
diff --git a/packages/landing/content/blog/penguinharness-0-2-1.en.md b/packages/landing/content/blog/penguinharness-0-2-1.en.md
index 5f841045..e12ede50 100644
--- a/packages/landing/content/blog/penguinharness-0-2-1.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-1.en.md
@@ -1,47 +1,82 @@
---
-title: "PenguinHarness 0.2.1: the desktop app arrives"
+title: "PenguinHarness 0.2.1: the desktop app and a download page"
date: 2026-08-04
category: news
-excerpt: 0.2.1 packs the full Web experience into a double-click desktop app — installers for macOS / Windows / Linux, signed in on open, sharing one data root with CLI installs. Around it, a software download page goes live with the installers mirrored to Alibaba Cloud OSS, standalone install scripts and penguin update learn to pick their download source, compaction failures stop trapping sessions with their retry costs finally visible, and the seeded admin password goes random with login throttling. Here is what shipped.
+excerpt: 0.2.1 adds a desktop app for macOS, Windows and Linux that opens already signed in and shares its data with the CLI. It also brings a download page backed by an OSS mirror, download-source control for installs and updates, and a hardened login.
---
-PenguinHarness 0.2.1 is out. The headline is the desktop app: no terminal, no login page — double-click an icon and you are in the full PenguinHarness. Around it, the distribution pipeline and download experience level up too. Feature by feature:
+PenguinHarness 0.2.1 is out, and the headline is the desktop app: no terminal and no login page, just double-click an icon to open the full PenguinHarness. Around it, distribution improves too: a new download page serves installers from an Alibaba Cloud OSS mirror, and install scripts and `penguin update` can choose their download source. Compaction failures no longer trap Sessions, and the first-start admin password is now random.
## The desktop app
-A deliberately thin Electron shell: it forks the existing server as a child process and points its window at `http://localhost` — no private IPC, no preload, no node integration; every capability still flows through the same HTTP API. It opens already signed in: a one-shot token lands an admin session, so there is no login page and no initial password to copy down.
+The desktop app is a deliberately thin Electron shell. It starts the existing server as a child process and points its window at `http://localhost`. There is no private IPC, preload script or Node integration, so everything still goes through the same HTTP API. It opens already signed in as the admin through a one-time token, so there is no login page and no initial password to copy down.
-Data is **fully shared** with CLI installs under `~/.penguin/data`: the desktop app and `penguin web` can be used interchangeably, and a data root only ever runs one server (a new `server.lock` single-instance guard that the CLI and the shell both honor) — if a CLI-started instance is already up, the app simply attaches to it. UI preferences (language, theme) survive restarts: the shell remembers the port the server last bound and reuses it while still free, keeping the window origin — and the origin-scoped browser storage behind your preferences — stable.
+Data is fully shared with CLI installs under `~/.penguin/data`, so you can use the desktop app and `penguin web` interchangeably. A data root only ever runs one server: a new `server.lock` guard, which the CLI and the app both honor, makes sure of that. If a server started from the CLI is already running, the app simply attaches to it.
-Installers cover macOS (dmg, Apple silicon / Intel), Windows (NSIS) and Linux (AppImage / deb). Current builds are unsigned: on first launch use right-click → Open on macOS, and "More info → Run anyway" past Windows SmartScreen.
+UI preferences such as language and theme survive restarts. The app remembers the port the server last used and reuses it while it is still free, which keeps the window's origin stable, and with it the browser storage that holds your preferences.
-## A download page, and desktop installers on the OSS mirror
+Installers are available for:
-[penguin.ooo/download](https://penguin.ooo/download) is a classic software download page: one card per platform, your detected system badged, click to download. Buttons default to GitHub's static `releases/latest/download` links — made possible by the installers moving to version-less names — while the page resolves the OSS mirror's `latest.json` in the background and, on success, switches to the mirror's immutable per-version directory, showing the resolved version with a manual source toggle. Desktop installers are mirrored byte-for-byte to Alibaba Cloud OSS, just like the CLI bundles.
+- macOS: dmg, for Apple silicon and Intel
+- Windows: NSIS
+- Linux: AppImage and deb
-## Install scripts and penguin update pick their download source
+The 0.2.1 builds are unsigned. On first launch on macOS, right-click the app and choose "Open". On Windows, get past SmartScreen with "More info → Run anyway".
-An `install.sh` / `install.ps1` saved from a Release page now follows the same policy as the penguin.ooo forwarding layer: `PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`, with `auto` preferring OSS and falling back to the same version on GitHub. Newly published installers embed their own Release tag, so however long you keep one around it downloads the matching version instead of silently following a future latest. `penguin update` adopts the same contract: upgrades no longer start at GitHub — version discovery prefers the OSS `latest.json`, forced modes are strict, and failures are reported localized.
+## A download page, with desktop installers on the OSS mirror
-## Compaction failures stop trapping sessions
+0.2.1 adds [penguin.ooo/download](https://penguin.ooo/download), a classic software download page: one card per platform, with your system detected and marked, and a click to download.
-Some models write `[summary]` as a title and put the body after the closing tag — the old logic extracted an empty summary, and every retry showed the model its own bad output to copy again, locking the session in a failing loop. In 0.2.1 summary extraction applies a tolerance ladder, unusable responses retry on the standard budget and backoff ladder with a corrective note, and the burned attempts and tokens finally land in stats and the cost center, with retry detail (`error_message` / `attempt` / `retry_in_ms`) visible in both the CLI and the Web.
+Installers now have version-less file names, which let the page's buttons start on GitHub's static `releases/latest/download` links. At launch, the page read the OSS mirror's `latest.json` in the background. If that succeeded, the buttons switched to the mirror's fixed per-version directory, and the page showed the resolved version with a toggle to switch the source by hand. Desktop installers are mirrored byte for byte to Alibaba Cloud OSS, just like the CLI bundles.
-## Login hardened
+## Install scripts and penguin update choose their download source
-The fixed seed password `penguin-2026` retires: first start generates a random password, printed exactly once; the login endpoint throttles per username with exponential delays (5 free failures, 1s doubling to 60s), so the 4-digit space cannot be enumerated.
+An `install.sh` or `install.ps1` saved from a Release page now follows the same policy as the penguin.ooo install scripts: `PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`, where `auto` prefers OSS and falls back to the same version on GitHub. Newly published install scripts also embed their own Release tag. However long you keep one, it downloads the matching version instead of silently following a later release.
+
+`penguin update` follows the same rules. Upgrades no longer start at GitHub: version discovery prefers the OSS `latest.json`, the `oss` and `github` modes never fall back, and failures are reported in your language.
+
+## Compaction failures no longer trap Sessions
+
+Some models write `[summary]` as a title and put the body after the closing tag. The old logic extracted an empty summary, and every retry showed the model its own bad output to copy again, locking the Session in a failing loop.
+
+In 0.2.1, summary extraction tolerates these malformed formats. A response that is still unusable is retried on the standard retry budget and backoff, with a corrective note to the model. The attempts and Tokens that retries burn now show up in the stats and the **Cost Center**, and the retry details (`error_message` / `attempt` / `retry_in_ms`) are visible in both the CLI and the Web App.
+
+## A hardened login
+
+The fixed seed password `penguin-2026` is retired. The first start now generates a random password, `penguin-` followed by four digits, and prints it exactly once. The login endpoint also throttles failed attempts per username: after 5 failures, attempts wait for a delay that starts at 1 second and doubles up to 60 seconds, which makes guessing through the four-digit space impractical.
## Web App improvements
-Skills become manageable in the interface: Agent settings gains a Skills tab listing the installed set from disk, with uninstall, zip import/export and chat-driven install; the new `skill-porting` library skill normalizes skills from other ecosystems in. Project settings gains "New chat defaults" — default agent, working directory, approval mode, thinking level and model, seeded into every new draft. The Traces page shares the session sidebar's grouping components, sessions page server-side, and trace discovery moves onto a SQLite index instead of per-request filesystem walks. On the chat page: the outline tick rail windows to ±20 turns and stops overlapping the composer, the cost stat no longer blinks out across task boundaries, uploaded file attachments render as user content (right-aligned with the same timestamp treatment as images, and visible inside steering chips), and ANSI color codes are kept out of tool output for good.
+### Skills in the app
+
+**Agent settings** gains a **Skills** tab that lists the Skills installed on disk, with uninstall, zip import and export, and installing through chat. The new `skill-porting` library Skill brings in Skills from other ecosystems and normalizes them.
+
+### New chat defaults
+
+**Project settings** gains **New chat defaults**: the default agent, working directory, approval mode, thinking level and model that every new draft starts with.
+
+### A faster Trajectories page
+
+The **Trajectories** page shares the sidebar's grouping components, pages its sessions on the server, and finds Trace files through a SQLite index instead of walking the filesystem on every request.
+
+### Chat page
+
+- The outline tick rail shows a window of 20 turns on either side of your position and no longer overlaps the composer.
+- The cost stat no longer disappears between Tasks.
+- Uploaded file attachments render as part of your message, right-aligned with the same timestamp treatment as images, and also show inside steering chips.
+- ANSI color codes no longer leak into tool output.
## Everything else
-The server's last two IO hotspots close: the 30-second scheduler tick and the schedules routes serve from mtime-gated caches, and `GET /messages` gains cursor pagination with tail-first web loading. `hono` moves past the CORS-preflight ReDoS advisory, and the OpenRouter catalog gains `qwen/qwen3.8-max`. The full list, item by item: [changelog/0.2.1](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.1).
+- The server's last two disk-IO hotspots are gone. The 30-second scheduler tick and the schedules routes read from caches that refresh only when files change, and `GET /messages` supports cursor pagination, so the Web App loads a conversation from its newest messages first.
+- `hono` moves past the CORS-preflight ReDoS advisory.
+- The OpenRouter catalog adds `qwen/qwen3.8-max`.
+
+The full list, item by item, is in [changelog/0.2.1](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.1).
## Install or upgrade
-Desktop app: grab your platform's installer at [penguin.ooo/download](https://penguin.ooo/download).
+Desktop app: download the installer for your platform at [penguin.ooo/download](https://penguin.ooo/download).
CLI / server:
@@ -50,4 +85,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows (PowerShell): `irm https://penguin.ooo/install.ps1 | iex`; or `npm install -g @prismshadow/penguin-cli` with Node >= 24. Existing installs: just `penguin update` — which, as of this release, rides the mirror too.
+On Windows, run `irm https://penguin.ooo/install.ps1 | iex` in PowerShell. With Node >= 24, you can also install with `npm install -g @prismshadow/penguin-cli`. On Linux and macOS, upgrade an existing install with `penguin update`, which now downloads through the mirror as well.
diff --git a/packages/landing/content/blog/penguinharness-0-2-1.zh.md b/packages/landing/content/blog/penguinharness-0-2-1.zh.md
index 17b87e43..718fee74 100644
--- a/packages/landing/content/blog/penguinharness-0-2-1.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-1.zh.md
@@ -1,47 +1,82 @@
---
-title: "PenguinHarness 0.2.1:桌面端应用来了"
+title: "PenguinHarness 0.2.1:桌面应用与下载页"
date: 2026-08-04
category: news
-excerpt: 0.2.1 把完整的 Web 体验装进一个双击即用的桌面应用——macOS / Windows / Linux 三平台安装包、打开即已登录、与 CLI 安装共用同一份数据;配套上线软件下载页,安装包同步镜像到阿里云 OSS;独立安装脚本与 penguin update 学会自选下载源;压缩失败不再拖垮会话、烧掉的重试成本终于可见;管理员初始密码随机化并加登录限流。逐项看看。
+excerpt: 0.2.1 为 macOS、Windows 和 Linux 带来桌面应用,打开即已登录,数据与 CLI 共享。同时上线由 OSS 镜像提供安装包的下载页,安装和更新可以选择下载源,登录也做了加固。
---
-PenguinHarness 0.2.1 发布了。主角是桌面端:不打开终端、不看登录页,双击图标就是完整的 PenguinHarness。围绕它,分发管道与下载体验也一并升级。逐项说明:
+PenguinHarness 0.2.1 发布了,主角是桌面应用:不用终端,没有登录页,双击图标就能打开完整的 PenguinHarness。分发体验也一并改进:新的下载页从阿里云 OSS 镜像提供安装包,安装脚本和 `penguin update` 可以选择下载源。此外,压缩失败不再卡死会话,首次启动的管理员密码也改为随机生成。
-## 桌面端应用
+## 桌面应用
-一个刻意做薄的 Electron 壳:它把现有服务端作为子进程拉起,窗口指向 `http://localhost`——没有私有 IPC、没有 preload、没有 node integration,一切能力仍然走同一套 HTTP API。打开即已登录:一次性 token 落地管理员会话,没有登录页,也没有要抄写的初始密码。
+桌面应用是一个刻意做薄的 Electron 壳。它以子进程启动现有的服务端,并把窗口指向 `http://localhost`。没有私有 IPC,没有 preload 脚本,也没有 Node 集成,一切仍走同一套 HTTP API。应用通过一次性 token 直接以管理员身份登录,因此没有登录页,也不用抄写初始密码。
-数据与 CLI 安装**完全共用** `~/.penguin/data`:桌面端与 `penguin web` 可以混用,同一数据目录同一时刻只运行一个服务端(新增的 `server.lock` 单实例锁,CLI 与壳都遵守)——CLI 已启动实例时,应用直接接入它。UI 偏好(语言、主题)在重启后保持:壳会记住上次绑定的端口并在仍空闲时复用,窗口 origin 稳定,浏览器按 origin 存放的偏好随之稳定。
+数据与 CLI 安装完全共用,都放在 `~/.penguin/data` 下,桌面应用和 `penguin web` 可以混着用。一个数据根目录同一时刻只运行一个服务端,这由新增的 `server.lock` 单实例锁保证,CLI 和应用都遵守它。如果 CLI 启动的服务端已经在运行,应用会直接接入。
-安装包覆盖 macOS(dmg,Apple 芯片 / Intel)、Windows(NSIS)与 Linux(AppImage / deb)。当前构建暂未签名:macOS 首次启动右键 →「打开」,Windows 在 SmartScreen 中选「更多信息 → 仍要运行」。
+语言、主题等界面偏好在重启后依然保留。应用会记住服务端上次使用的端口,只要端口仍然空闲就继续沿用。这样窗口的 origin 保持不变,保存偏好的浏览器存储也随之稳定。
+
+提供以下平台的安装包:
+
+- macOS:dmg,支持 Apple 芯片和 Intel
+- Windows:NSIS
+- Linux:AppImage 和 deb
+
+0.2.1 的构建尚未签名。在 macOS 上首次启动时,右键点击应用并选择「打开」。在 Windows 上,遇到 SmartScreen 提示时选「更多信息 → 仍要运行」。
## 下载页,以及镜像到 OSS 的桌面安装包
-[penguin.ooo/download](https://penguin.ooo/download) 是一张经典的软件下载页:每个平台一张卡片、检测到的系统打上标记、点击即下载。按钮默认指向 GitHub 的 `releases/latest/download` 静态直链——安装包改为无版本号命名,这类链接才成为可能——页面同时在后台解析 OSS 镜像的 `latest.json`,解析成功即切到镜像的不可变版本目录,并显示当前版本号,可手动切换来源。桌面安装包与 CLI 包一样逐字节镜像到阿里云 OSS。
+0.2.1 新增了 [penguin.ooo/download](https://penguin.ooo/download),这是一个经典的软件下载页:每个平台一张卡片,自动识别并标出你的系统,点一下即可下载。
+
+安装包的文件名不再带版本号,所以页面上的按钮可以先指向 GitHub 的静态 `releases/latest/download` 链接。页面刚上线时,会在后台读取 OSS 镜像的 `latest.json`,读取成功后,按钮切换到镜像上这个版本的固定目录,页面显示解析出的版本号,并提供开关让你手动切换下载源。桌面安装包和 CLI 包一样,逐字节镜像到阿里云 OSS。
-## 安装脚本与 penguin update 自选下载源
+## 安装脚本和 penguin update 自选下载源
-从 Release 页保存的 `install.sh` / `install.ps1` 现在与 penguin.ooo 转发层同口径:`PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`,`auto` 优先 OSS、同版本回退 GitHub;新发布的安装脚本内嵌自己的 Release tag,保存多久都下载与之匹配的版本,不再悄悄跟随未来的 latest。`penguin update` 采用同一契约:升级不再从 GitHub 起步,版本发现优先走 OSS 的 `latest.json`,强制模式严格生效,失败信息本地化。
+从 Release 页面保存的 `install.sh` 或 `install.ps1`,现在遵循与 penguin.ooo 安装脚本相同的策略:`PENGUIN_DOWNLOAD_SOURCE=auto|oss|github`,`auto` 优先使用 OSS,并回退到 GitHub 上的同一版本。新发布的安装脚本还会内嵌自己的 Release tag,无论保存多久,下载的都是与之匹配的版本,不会悄悄跟着后来的新版本走。
-## 压缩失败不再拖垮会话
+`penguin update` 遵循同样的规则。升级时不再先访问 GitHub:查询最新版本时优先读取 OSS 的 `latest.json`,`oss` 和 `github` 两种模式绝不回退,失败信息也会用你的语言显示。
-某些模型会把 `[summary]` 写成标题、正文放在闭合标签之后——旧逻辑取到空摘要,每次重试还把模型自己的错误输出回显给它,会话就此陷入失败循环。0.2.1 的摘要提取带容错阶梯,不可用的响应按标准重试预算与退避阶梯重来并附纠正提示;烧掉的尝试次数与 token 终于计入统计与成本中心,重试详情(`error_message` / `attempt` / `retry_in_ms`)在 CLI 与 Web 上直接可见。
+## 压缩失败不再卡死会话
+
+有些模型把 `[summary]` 写成标题,正文却放在闭合标签之后。旧逻辑会取到空摘要,而且每次重试都把模型自己写坏的输出再给它看一遍,它就照抄下去,会话由此卡在失败循环里。
+
+0.2.1 的摘要提取能容忍这类不规范的格式。响应仍然不可用时,按标准的重试预算和退避重试,并给模型附上一条纠正说明。重试消耗的尝试次数和 Token 现在会计入统计和**成本中心**,重试详情(`error_message` / `attempt` / `retry_in_ms`)在 CLI 和 Web App 里都能看到。
## 登录加固
-固定的初始密码 `penguin-2026` 退役:首次启动生成随机密码、只打印一次;登录端点按用户名做指数限流(5 次免罚,1 秒起倍增至 60 秒),4 位数字空间不再可枚举。
+固定的初始密码 `penguin-2026` 退役了。首次启动时会生成随机密码,格式是 `penguin-` 加四位数字,并且只打印一次。登录接口还会按用户名限制失败尝试:失败 5 次后,每次尝试都要等待,延迟从 1 秒起步,逐次翻倍,最长 60 秒。想靠穷举四位数字来猜密码,就不现实了。
+
+## Web App 改进
-## Web 应用改进
+### 在应用里管理 Skill
-技能可以在界面里管理了:Agent 设置新增 Skills 标签页,列出磁盘上已装技能,支持卸载、zip 导入导出与对话驱动安装;新的 `skill-porting` 库技能把外部生态的技能规范化迁入。Project 设置新增「新对话默认值」——默认 Agent、工作目录、审批模式、思考等级与模型,落进每个新草稿。Traces 页与会话侧栏共享同一套分组组件,会话分页、轨迹索引落到 SQLite,不再逐请求扫文件系统。对话页:大纲刻度轨按 ±20 轮开窗不再压住输入区,成本统计跨任务边界不再闪没,上传的文件附件按用户内容渲染(右对齐、随图片同款时间戳,插话 chip 里也能看到),工具输出的 ANSI 颜色码被彻底拦下。
+**Agent 设置**新增**技能**标签页,列出磁盘上已安装的 Skill,支持卸载、zip 导入导出,以及通过对话安装。技能库新增的 `skill-porting` 可以把其他生态的 Skill 引入进来并规范化。
+
+### 新对话默认值
+
+**Project 设置**新增**新对话默认值**:每个新对话草稿默认使用的 Agent、工作目录、审批模式、思考等级和模型。
+
+### 更快的轨迹观测页
+
+**轨迹观测**页复用侧栏的分组组件,会话改在服务端分页,并通过 SQLite 索引查找 Trace 文件,不再每次请求都遍历文件系统。
+
+### 对话页
+
+- 对话索引的刻度条只显示当前位置前后各 20 轮,也不再与输入框重叠。
+- 成本统计不再在 Task 之间消失。
+- 上传的文件附件显示为你消息的一部分,靠右对齐,时间戳样式与图片一致,插话标签里也能看到。
+- ANSI 颜色代码不再混进工具输出。
## 其余改进
-服务端最后两个 IO 热点关闭:调度器每 30 秒的 tick 与 schedules 路由改为 mtime 门控缓存,`GET /messages` 支持游标分页与 Web 端尾部优先加载。`hono` 升级越过 CORS 预检 ReDoS 通告;OpenRouter 目录新增 `qwen/qwen3.8-max`。完整清单逐条见 [changelog/0.2.1](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.1)。
+- 服务端最后两个磁盘 IO 热点已经消除。每 30 秒一次的调度器 tick 和 schedules 路由改为读取缓存,缓存只在文件变化时刷新;`GET /messages` 支持游标分页,Web App 加载对话时因此先取最新的消息。
+- `hono` 升级到不受 CORS 预检 ReDoS 安全通告影响的版本。
+- OpenRouter 模型目录新增 `qwen/qwen3.8-max`。
+
+完整清单逐条见 [changelog/0.2.1](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.1)。
## 安装或升级
-桌面端:前往 [penguin.ooo/download](https://penguin.ooo/download) 下载对应平台安装包。
+桌面应用:到 [penguin.ooo/download](https://penguin.ooo/download) 下载对应平台的安装包。
CLI / 服务端:
@@ -50,4 +85,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows(PowerShell):`irm https://penguin.ooo/install.ps1 | iex`;或在 Node >= 24 下 `npm install -g @prismshadow/penguin-cli`。已有安装直接 `penguin update`——这一版起,它也走镜像了。
+Windows 上请在 PowerShell 中运行 `irm https://penguin.ooo/install.ps1 | iex`。Node >= 24 的环境也可以用 `npm install -g @prismshadow/penguin-cli` 安装。在 Linux 和 macOS 上升级已有安装,运行 `penguin update` 即可,它现在同样通过镜像下载。
diff --git a/packages/landing/content/blog/penguinharness-0-2-11.en.md b/packages/landing/content/blog/penguinharness-0-2-11.en.md
index 578d9835..e66bd8f2 100644
--- a/packages/landing/content/blog/penguinharness-0-2-11.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-11.en.md
@@ -1,120 +1,137 @@
---
-title: "PenguinHarness 0.2.11: an upgraded file browser, adjustable compaction timing, hooks, and a Docker image"
+title: "PenguinHarness 0.2.11: editable files, a draggable compaction threshold, hooks, and a Docker image"
date: 2026-09-10
category: news
-excerpt: The conversation grew a workbench. The Files panel became a two-pane browser with in-place editing and version-checked saves, the context ring now measures against the point compaction actually fires and its threshold is a cutter you drag, a shortcuts ball fans the dock open from the edge of the chat, and scheduled tasks moved in beside it. Hooks became a capability of the loop itself, with goal mode and continual learning shipping as installable plugins. An official Docker image makes a server one `docker run`, and DeepSeek V4.1 Flash is the model a new Project starts on.
+excerpt: The Files panel becomes a two-pane browser with in-place editing, the context ring measures against a compaction threshold you can drag, and scheduled tasks move into the dock. Hooks become part of the agent loop, and an official Docker image ships.
---
-PenguinHarness 0.2.11 turns the dock into a workbench: editable files, a movable compaction trigger, scheduled tasks, and an edge shortcut ball. Hooks become an agent-loop capability, an official container image simplifies server deployment, and the model catalog expands.
+PenguinHarness 0.2.11 is out, and most of its changes are inside the conversation. You can edit Workspace files in a two-pane Files panel, the context ring measures against the point where compaction fires, scheduled tasks move into the dock, and a shortcuts ball on the conversation's edge opens the dock's panels. Hooks are now part of the agent loop, with goal mode and continual learning available as installable plugins. An official Docker image turns a server deployment into one `docker run`, and new Projects start on DeepSeek V4.1 Flash.
-## The Files panel is a browser you can type into
+## The Files panel is a two-pane browser you can type into
-- Workspace files panel is now two panes: lazy directory tree on the left, selected file on the right, draggable divider.
-- Text files gain an **Edit** action with a monospace editor, **Wrap** toggle, and Ctrl+S save.
-- Saves are version-checked via `ETag` / `ifVersion`. If the Agent changed the file, the server returns `409` without writing; the UI offers **Overwrite** and preserves your draft.
-- Dropping OS files into the panel uploads them into the directory under the pointer.
-- Unsaved changes prompt before switching files or removing the panel, but collapsing the dock keeps the draft mounted.
+The Files panel now shows a directory tree on the left and the selected file on the right, with a divider you can drag. The tree loads each directory's contents as you expand it.
+
+- Text files gain an **Edit** action: a monospace editor with a **Wrap** toggle, and Ctrl+S to save.
+- Saves are version-checked with `ETag` / `ifVersion`. If the agent changed the file after you opened it, the server returns `409` and writes nothing. The panel then offers **Overwrite** and keeps your draft.
+- Dropping files from your operating system onto the panel uploads them into the directory under the pointer.
+- If you have unsaved changes, the panel asks before you switch files or remove the panel. Collapsing the dock keeps your draft.
![The Files panel: a directory tree on the left beside an open file in the plain-text editor on the right](/blog-assets/penguinharness-0-2-10-files-panel-en.png)
## The context ring measures against compaction
-- The composer ring now fills against the compaction trigger, not the model context window, so a 64k/128k threshold reads 50%.
-- The panel bar remains scaled to the model window and shows the dashed compaction cutter.
-- Dragging the cutter opens a confirmation with the proposed value prefilled and still editable.
-- Context is assembled whole from Agent State under three tiers; compaction settings are re-read at each checkpoint, so running conversations honor changes.
-- Added a second Top 5 view showing files with the most file-tool traffic in the current context.
+The ring in the composer now fills up against the compaction threshold instead of the model's context window. With 64k used against a 128k threshold, it reads 50%.
+
+The bar in the context panel still uses the model's window as its scale, and marks the compaction threshold with a dashed cutter. Drag the cutter to change the threshold: a confirmation opens with the new value filled in, and you can still edit it. Compaction settings are re-read at every compaction checkpoint, so a change also applies to conversations that are already running.
+
+The panel also gains a second Top 5 view that lists the files with the most file-tool traffic in the current context.
![The context panel: a bar scaled to the model window with a draggable compaction cutter, and the Top 5 files view](/blog-assets/penguinharness-0-2-10-context-panel-en.png)
## A shortcuts ball on the edge of the conversation
-- When no dock panel is open, a translucent round button floats on the right edge with a “Shortcuts” caption.
-- Clicking it fans out a semicircular ring of dock panels plus terminal; names appear through the caption, not pills around the ball.
-- Selecting an entry opens that panel and hides the ball.
-- The ball drags along the edge, remembers position, carries the pending-approval dot, and can be dismissed; an Appearance setting brings it back.
+When no dock panel is open, a translucent round button floats inside the right edge of the conversation, captioned **Shortcuts**. Click it, and the dock panels plus a terminal fan out around it in a semicircle. The entries are icons only; the caption shows the name of the one you point at. Picking an entry opens that panel and hides the ball.
+
+You can drag the ball along the edge, and it remembers where you left it. It shows the pending-approval dot. The last entry on its ring dismisses the ball for good, and a setting under **Appearance** brings it back.
![The shortcuts ball on the conversation's right edge, fanned open into a semicircular ring of panel entries](/blog-assets/penguinharness-0-2-10-shortcuts-launcher-en.png)
## Scheduled tasks, in the conversation
-- New dock **Scheduled tasks** panel lists tasks for the current Session with search, state filters, enable switches, and plain-language schedule lines.
-- Header offers **Create with AI**, which prefills this conversation’s composer without posting, and **Create manually**, which opens the form pinned to this Session.
-- Sidebar rows show an alarm clock for Sessions with a bound upcoming task.
-- Saving no longer claims tasks take effect in a new conversation; toasts reflect scheduler behavior.
+A new **Scheduled tasks** panel in the dock lists the scheduled tasks bound to the current Session. It has search, state filters and enable switches, and it describes each schedule in plain language.
+
+- The panel header offers **Create with AI**, which fills in this conversation's composer without sending anything, and **Create manually**, which opens the form already set to this Session.
+- In the sidebar, a Session with a scheduled task still to fire shows an alarm clock.
+- Saving a scheduled task no longer claims that it takes effect in a new conversation. The notifications now describe what the scheduler actually does.
![The scheduled-tasks panel in the dock with its Create with AI and Create manually buttons, and a sidebar session row wearing an alarm clock](/blog-assets/penguinharness-0-2-10-schedule-panel-en.png)
-## Hooks are a capability, goal mode is a plugin
+## Hooks are part of the loop, and goal mode is a plugin
-- Sessions gain hook points: **stop**, **pre_tool_use**, and **user_prompt**.
-- Hooks are plain Node scripts installed into `agent_state/hooks/`, run as subprocesses, and may answer `continue`, `stop`, a `subagent` request, or nothing.
-- Goal mode is now the `goal` plugin’s stop hook; `continual-learning` sends long-task findings to a background subagent that updates relevant `SKILL.md` files.
-- Skill library becomes a **plugin library**: npm packages, dated versions, detail modal with file browser.
-- Agent settings gain a **Hooks** tab with one `hooks.enabled` switch per Agent. Disabled Agents assemble no hooks while installed packages remain on disk.
-- Per-package rows show hook-point chips, zip export/import, and chat import.
+Sessions now have three hook points: `stop`, `pre_tool_use` and `user_prompt`. A hook is a plain Node script installed into `agent_state/hooks/`. It runs as a subprocess, and a stop hook can answer `continue`, `stop`, a `subagent` request, or nothing.
+
+- Goal mode is now the `goal` plugin's stop hook.
+- The `continual-learning` plugin sends the findings of a long task to a background subagent, which updates the relevant `SKILL.md` files.
+- The Skill library is now the **Plugin library**. Plugins are npm packages with dated versions, and each has a detail dialog with a file browser.
+- Agent settings gain a **Hooks** tab with a `hooks.enabled` switch for each agent. When it is off, the agent loads no hooks, and installed packages stay on disk. Each package row shows its hook points as chips, and the tab offers zip export and import, plus import through a chat.
![The Agent settings Hooks tab: the enable-switch card, a package row with hook-point chips, and the import dialog entry](/blog-assets/penguinharness-0-2-10-hooks-tab-en.png)
## Create with AI, as a kit
-- Every object created from a form is gaining an AI creation path. This release ships the kit: button pair, prompt panel with examples and folded full-prompt preview, and dialog sending the prompt to the Project’s default agent.
-- Separate buttons: accented **Create with AI** with a wand, plain **Create manually** with a hand.
-- The dialog only offers **Edit in a new conversation**; nothing is auto-sent. The prompt lands as a prefilled draft, and Send remains your action.
-- Only kit and schedule surfaces ship this release; other creation forms follow later.
+Every object the Web App creates from a form is getting a second path: describe it to an agent. This release ships the kit behind that path. It includes the button pair, a prompt panel with examples and a folded preview of the full prompt, and a dialog that hands the prompt to the Project's default agent.
+
+- The two buttons are separate. **Create with AI** is accented and shows a wand; **Create manually** is plain and shows a hand.
+- The dialog's only action is **Edit in a new conversation**, and nothing is ever sent automatically. The prompt arrives as a draft in the composer, and pressing Send is up to you.
+- Besides the scheduled-tasks panel, the Skills tab's import through a chat and the Memory tab's add and edit already use the kit. Other creation forms follow in later releases.
![A page header's Create with AI and Create manually button pair, with the Create with AI dialog open over it](/blog-assets/penguinharness-0-2-10-create-with-ai-en.png)
## A server on another machine
-- Official container image: Docker Hub `hiyouga/penguinharness`, built from source for `linux/amd64` and `linux/arm64`.
-- Runs `penguin server` on `0.0.0.0:7364` with `/data` volume. Tags: `latest` follows `main`; `X.Y.Z` follows release tags. Documented `docker run` publishes on host loopback.
-- **Machines** records now live in `web.db`, belong to a Project, and each machine mints a 16-character id.
-- Machine identity uses `penguin server status` over ssh. All traffic rides one held `ssh -T -D` session per machine; connected-machine API answers same-origin at `/server/<machineId>/api/…`.
+There is now an official container image on Docker Hub, `hiyouga/penguinharness`, built from source for `linux/amd64` and `linux/arm64`. It runs `penguin server` on `0.0.0.0:7364` with a `/data` volume. The `latest` tag follows `main`, and `X.Y.Z` tags are built from releases. The documented `docker run` command publishes the port on the host's loopback address, so a new deployment answers only on the machine running Docker.
+
+The **Machines** page, which installs PenguinHarness on another machine over ssh, changed too:
+
+- Machine records moved from a JSON file into `web.db` and now belong to a Project. Each machine mints its own 16-character id.
+- PenguinHarness runs `penguin server status` over ssh to learn a machine's id and whether its server is up.
+- All traffic to a machine goes through one long-lived `ssh -T -D` session per machine. A connected machine's API answers on the same origin, at `/server/<machineId>/api/…`.
## The model catalog
-- **DeepSeek V4.1 Flash** ships as bare id `deepseek-flash`, new Project default; 1,000,000-token context, image input, Flash pricing with off-peak halving. Direct-vendor row pins a client and base URL.
-- **Gemini 3.8 Flash** joins directly and on OpenRouter; 1,048,576-token window, image input. Launch-discount pricing is declared and derived; two incorrect rows corrected.
-- **GPT-6 Astra** joins direct and OpenRouter; 1,050,000-token window, images, $1 / $12.5 / $50 per million tokens for cache read / cache write / output.
-- Three **Doubao Seed** rows join TokenDance with 50% off.
-- New **vLLM** group covers eight self-hosted models: zero price, no base URL, group-pinned protocol.
-- Existing Projects pick this up via **sync presets**.
+- **DeepSeek V4.1 Flash** ships under the bare id `deepseek-flash` and is the default model for new Projects. It has a 1,000,000-token context window, image input, and Flash pricing that halves off-peak. Its direct-vendor row pins a client and a base URL.
+- **Gemini 3.8 Flash** joins directly and on OpenRouter, with a 1,048,576-token window and image input. Gemini 3.x Flash rows now store the list price and declare the launch discount instead of building it into the numbers, and two rows that billed the wrong price are corrected.
+- **GPT-6 Astra** joins directly and on OpenRouter, with a 1,050,000-token window and image input, at $1 / $12.5 / $50 per million tokens for cache read / cache write / output.
+- Three **Doubao Seed** rows join the TokenDance group at 50% off.
+- A new **vLLM** group covers eight self-hosted models. The rows have a price of zero and no base URL, and the group pins their protocol.
+
+Existing Projects pick up these rows with **Sync presets** on the models page.
## Also in this release
-- `exec_command` accepts `command` as well as `cmd`; tool rejections answer with the fault, parameters, and correct call shape. `read_image` and `describe_image` fold into `read_file`.
-- Slow turns show `Elapsed 10.3s (API 5s, tools 5.3s)`, excluding approval wait.
-- Sidebar marks Sessions with dev servers or background subagents; chat header gets a matching pill.
-- Compaction shows status and wall time; thinking and summary stream into separate disclosure rows.
-- `model.timeoutMs` is now an idle budget between upstream events, default 300000; retry ladder resets after received content.
-- Updating runs through one dialog: check, release notes, download with progress, then **Restart and update**.
-- Conversations open on the latest 50 turns; earlier turns load as you scroll up.
-- Sidebar lists every Workspace from server-side counts.
-- Terminals behave like terminals: link positioning after redraw, OSC 52 copy reaches the system clipboard.
-- Plugin versions read `2026.09.10.1`; old dash spelling reads as the same version, so no false update badge.
+- `exec_command` accepts `command` as well as `cmd`. When a tool rejects a call, it now replies with the fault, the parameters and the correct call shape. `read_image` and `describe_image` fold into `read_file`.
+- Slow turns show where the time went, such as `Elapsed 10.3s (API 5s, tools 5.3s)`. Neither part counts time spent waiting for approval.
+- The sidebar marks Sessions that have dev servers or background subagents running, and the chat header shows a matching pill.
+- The compaction row shows its status and how long it took, and the thinking and the summary stream into separate rows you can expand.
+- `model.timeoutMs` is now an idle budget between upstream events, with its default raised to 300000, so a request times out on silence rather than on length. The retry ladder starts over once content has been received.
+- Updating runs through one dialog: check, read the release notes, download with a progress bar, then **Restart and update**.
+- A conversation opens on its latest 50 turns, and earlier turns load as you scroll up.
+- Grouped by Workspace, the sidebar lists every Workspace, not only those its loaded conversations belong to.
+- Terminals behave like terminals: a link still opens correctly after the screen redraws, and OSC 52 copy reaches the system clipboard.
+- Plugin versions are now written like `2026.09.10.1`. A copy installed under the old spelling with dashes counts as the same version, so no false update badge appears.
+
+## About 0.2.10
+
+0.2.11 is 0.2.10 rebuilt with electron-builder 26.16.1, which makes signed macOS installer builds work again. 0.2.10 was tagged, and its npm packages and Docker image were published, but its signed macOS build failed, so it never got installers or a Release page. The per-change entries stay in [`changelog/0.2.10/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.10).
## Upgrading
-- First restart-only schema migration (`drop-goal-state`): hot push onto a running runtime is refused before touching the database. Normal install restarts and applies it. Downgrading to 0.2.9 still works.
-- Install the `goal` plugin on pre-0.2.10 Agents, or goal mode returns `409 goal_plugin_not_installed`. One click per Agent.
-- Update the kernel to `2026-09-10` for `read_file` images. Until then image tools get unknown-tool replies and image reads use the stored 30s timeout. Rename `skills` / `--skills` to `plugins` / `--plugins` in scripts.
-- `POST /api/version/update` now returns job status instead of blocking. Machines routes moved under a Project, so 0.2.9 machine lists start empty; re-install from the owning Project to recover.
+- **One restart.** This release has the first restart-only schema migration, `drop-goal-state`. A hot push onto a running runtime is refused before it touches the database, while a normal install restarts and applies the migration. Downgrading to 0.2.9 still works.
+- **Install the `goal` plugin on agents created before 0.2.10.** Without it, goal mode returns `409 goal_plugin_not_installed`. It takes one click per agent.
+- **Update the kernel to `2026-09-10`** so that agents read images with `read_file`. Until then, calls to the old image tools get unknown-tool replies, and image reads use the stored 30s timeout.
+- **Rename `skills` / `--skills` to `plugins` / `--plugins`** in scripts that create agents.
+- **API changes.** `POST /api/version/update` now returns a job status instead of blocking until the update ends. Machines routes moved under a Project, so machine lists from 0.2.9 start empty; install again from the Project that owns the machine to get it back.
+
+## Install
-Desktop installers are at [penguin.ooo/download](https://penguin.ooo/download); the CLI and server install with:
+Desktop installers are at [penguin.ooo/download](https://penguin.ooo/download).
+
+On Linux and macOS, install the CLI and server with:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
+On Windows, use PowerShell:
+
```powershell
irm https://penguin.ooo/install.ps1 | iex
penguin web
```
+To run the server in Docker:
+
```sh
docker run -d --name penguin -p 127.0.0.1:7364:7364 -v penguin-data:/data hiyouga/penguinharness:latest
```
-
-0.2.11 is a rebuild of 0.2.10 with electron-builder 26.16.1, restoring signed macOS installer builds; 0.2.10 itself never received installers or a Release page. Full details for every change are in [`changelog/0.2.10/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.10).
diff --git a/packages/landing/content/blog/penguinharness-0-2-11.zh.md b/packages/landing/content/blog/penguinharness-0-2-11.zh.md
index 2ffa3f62..ed47bff6 100644
--- a/packages/landing/content/blog/penguinharness-0-2-11.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-11.zh.md
@@ -1,96 +1,137 @@
---
-title: "PenguinHarness 0.2.11:文件浏览升级、压缩时机动态调整、Hook 能力、Docker 镜像"
+title: "PenguinHarness 0.2.11:可编辑的文件、可拖动的压缩阈值、钩子与 Docker 镜像"
date: 2026-09-10
category: news
-excerpt: 对话长出了一张工作台。文件面板变成可就地编辑、带版本校验保存的双栏浏览器;上下文环改为对着压缩真正触发的那个点计量,阈值本身成了一把可拖动的刻刀;对话右缘多了一颗快捷球,可以把整个面板栏扇开;定时任务也搬进了面板栏。钩子成为智能体循环自身的能力,目标模式与持续学习则作为可安装插件发布。官方 Docker 镜像让一台服务端只需一条 `docker run`,而新建 Project 的默认模型换成了 DeepSeek V4.1 Flash。
+excerpt: 文件面板变成可以直接编辑的双栏浏览器,上下文环按压缩阈值计量且阈值可以拖动,定时任务搬进了右侧栏。钩子成为 Agent 循环的一部分,官方 Docker 镜像也随这一版发布。
---
-PenguinHarness 0.2.11 发布。本版大部分变化在对话内部:文件面板可编辑、上下文环按压缩点计量、快捷球与定时任务进入面板栏;钩子成为智能体循环能力,官方容器镜像让服务端一条命令部署,模型库同步更新。
+PenguinHarness 0.2.11 发布了,这一版的大部分改动都在对话里面。你可以在双栏的文件面板里编辑 Workspace 文件,上下文环改为按压缩触发点计量,定时任务搬进了右侧栏,对话边缘还多了一个打开各个面板的悬浮球。钩子成为 Agent 循环的一部分,目标模式和持续学习以可安装插件的形式提供。有了官方 Docker 镜像,部署服务端只需一条 `docker run`;新建的 Project 默认使用 DeepSeek V4.1 Flash。
-## 可以直接敲字的文件面板
+## 可以直接编辑的双栏文件面板
-文件面板改为两栏:左侧目录树,右侧选中文件,中间可拖动分隔条。文本文件新增**编辑**操作,提供等宽输入框、**自动换行**和 Ctrl+S 保存。保存带版本校验:文件变化时返回 `409` 并提示覆盖,同时保留草稿。未保存改动在切换文件或移除前会确认,折叠面板不会丢失草稿。
+文件面板现在左边是目录树,右边是选中的文件,中间的分隔条可以拖动。目录树在你展开某个目录时才加载其中的内容。
+
+- 文本文件新增**编辑**操作:打开等宽字体的编辑器,带**自动换行**开关,按 Ctrl+S 保存。
+- 保存时会用 `ETag` / `ifVersion` 做版本校验。如果你打开文件之后 Agent 改过它,服务端会返回 `409`,不写入任何内容。面板随后提供**仍然覆盖**,你的草稿也会保留。
+- 把操作系统里的文件拖到面板上,就会上传到鼠标指针所在的目录。
+- 有未保存的修改时,切换文件或移除面板前会先确认。收起右侧栏不会丢失草稿。
![文件面板:左侧目录树,右侧是在纯文本编辑器里打开的文件](/blog-assets/penguinharness-0-2-10-files-panel-zh.png)
-## 上下文环对着压缩计量
+## 上下文环按压缩阈值计量
+
+输入框旁的上下文环现在以压缩阈值为满格,不再以模型的上下文窗口为满格。阈值是 128k 时,用掉 64k 显示为 50%。
+
+上下文面板里的长条仍以模型窗口为刻度,并用一条虚线标出压缩阈值。拖动这条虚线就能修改阈值:确认框弹出时已经填好新值,你还可以再改。每到一个压缩检查点,都会重新读取压缩设置,所以修改对正在运行的对话同样生效。
+
+面板还新增了第二个 Top 5 视图,列出当前上下文里文件工具读写最多的文件。
-输入框上下文环改为按压缩触发点计量:128k 阈值下用掉 64k 显示为 50%。长条仍以模型窗口为刻度,触发点用虚线刻刀表示,拖动刻刀即可调整,确认框预填建议值。压缩设置会在每个压缩检查点重新读取,对运行中的对话同样生效。面板新增 Top 5 文件视图。
+![上下文面板:以模型窗口为刻度的长条、可拖动的压缩阈值虚线,以及 Top 5 文件视图](/blog-assets/penguinharness-0-2-10-context-panel-zh.png)
-![上下文面板:以模型窗口为刻度的长条、可拖动的压缩刻刀,以及 Top 5 文件视图](/blog-assets/penguinharness-0-2-10-context-panel-zh.png)
+## 对话边缘的悬浮球
-## 对话边缘的一颗快捷球
+没有打开任何面板时,对话区域右缘内侧会浮着一个半透明的圆形按钮,下方写着**快捷方式**。点击它,各个面板和一个终端的入口会围着它展开成半圆。这些入口只显示图标,鼠标指向哪一个,下方的文字就显示哪一个的名称。选中一个入口,就会打开对应的面板,悬浮球随之隐藏。
-无面板打开时,对话右缘内侧出现半透明快捷球。点击后沿半圆弧展开面板入口(每个面板一个,外加终端),选中即打开对应面板。球可沿边缘拖动并记住位置,带待审批小圆点;弧上最后一个入口会永久收起,可在外观设置中恢复。
+悬浮球可以沿着边缘拖动,并记住你放下的位置。有待审批的请求时,它会显示提示小圆点。半圆上的最后一个入口会永久收起悬浮球,想找回来,可以在**外观**设置里重新打开。
-![对话右缘的快捷球,展开成一圈半圆形的面板入口](/blog-assets/penguinharness-0-2-10-shortcuts-launcher-zh.png)
+![对话右缘的悬浮球,展开成一圈半圆形的面板入口](/blog-assets/penguinharness-0-2-10-shortcuts-launcher-zh.png)
## 定时任务进入对话
-面板栏新增**定时任务**面板,列出当前 Session 的任务,带搜索、状态过滤和启用开关。头部提供**AI 创建**(把请求写进当前对话输入框,不发送)和**手动创建**(打开锁定 Session 的表单)。侧栏为有未触发任务的 Session 显示闹钟;保存提示不再说“在新对话中生效”。
+右侧栏新增了**定时任务**面板,列出绑定到当前会话的定时任务。面板带搜索、状态过滤和启用开关,每个任务的执行时间都用通俗的话写出来。
-![面板栏里的定时任务面板,带 AI 创建与手动创建两个按钮,以及侧栏中带闹钟标记的会话行](/blog-assets/penguinharness-0-2-10-schedule-panel-zh.png)
+- 面板顶部有**用 AI 创建**和**手动创建**两个按钮。前者把请求填进当前对话的输入框,但不会发送;后者打开的表单已经选好当前会话。
+- 在侧栏里,还有定时任务没触发的会话会显示一个闹钟。
+- 保存定时任务时,提示不再说「在新对话中生效」,而是如实说明调度器会怎么执行。
-## 钩子成为一项能力,目标模式成为插件
+![右侧栏里的定时任务面板,带「用 AI 创建」和「手动创建」两个按钮,以及侧栏中带闹钟标记的会话行](/blog-assets/penguinharness-0-2-10-schedule-panel-zh.png)
-Session 获得通用钩子机制:core 只定义触发点(**stop**、**pre_tool_use**、**user_prompt**),钩子以 Node 脚本包安装在 `agent_state/hooks/`,子进程运行并返回 `continue`、`stop`、`subagent` 或空。目标模式移出 core,成为 `goal` 插件的 stop 钩子;技能库改为**插件库**,新增 `continual-learning` 包。Agent 设置新增**钩子**标签页,含 `hooks.enabled` 总开关和每包管理(触发点标签、zip 导入导出、对话导入)。
+## 钩子成为循环的一部分,目标模式变成插件
-![Agent 设置的钩子标签页:启用开关卡片、带触发点标签的包条目,以及导入对话框入口](/blog-assets/penguinharness-0-2-10-hooks-tab-zh.png)
+会话现在有三个钩子触发点:`stop`、`pre_tool_use` 和 `user_prompt`。钩子就是一个普通的 Node 脚本,安装在 `agent_state/hooks/` 下,以子进程方式运行。stop 钩子可以返回 `continue`、`stop`、一个 `subagent` 请求,也可以什么都不返回。
-## AI 创建,作为一套套件
+- 目标模式现在就是 `goal` 插件的 stop 钩子。
+- `continual-learning` 插件会把长任务中的发现交给一个后台子 Agent,由它更新相关的 `SKILL.md` 文件。
+- 技能库改名为**插件库**。插件以 npm 包的形式发布,版本号是日期,每个插件都有带文件浏览器的详情弹窗。
+- Agent 设置新增**钩子**标签页,每个 Agent 有一个 `hooks.enabled` 开关。关闭后,这个 Agent 不加载任何钩子,已安装的钩子包仍然留在磁盘上。每个钩子包的那一行用小标签列出它的触发点,标签页还支持 zip 导出、导入,以及通过对话导入。
-Web App 中每个由表单创建的对象将获得第二种方式:描述给智能体。本版发布机件:按钮对、带示例与可折叠完整提示词预览的提示面板,以及把提示词交给 Project 默认智能体的对话框。**AI 创建**与**手动创建**为两个独立按钮;对话框唯一出口是**在新对话中编辑**,永不自动发送。本版仅定时任务两处入口启用。
+![Agent 设置的钩子标签页:启用开关卡片、带触发点标签的钩子包,以及导入对话框入口](/blog-assets/penguinharness-0-2-10-hooks-tab-zh.png)
-![页面头部的 AI 创建与手动创建按钮对,其上打开着 AI 创建对话框](/blog-assets/penguinharness-0-2-10-create-with-ai-zh.png)
+## 「用 AI 创建」做成通用套件
+
+Web App 里凡是用表单创建的对象,都会多一条创建途径:把它描述给 Agent。这一版发布的是支撑这条途径的套件,包括一对按钮、一个带示例和完整提示词折叠预览的提示词面板,以及一个把提示词交给 Project 默认 Agent 的对话框。
+
+- 两个按钮彼此独立。**用 AI 创建**是强调样式,图标是魔杖;**手动创建**是普通样式,图标是一只手。
+- 对话框唯一的出口是**在新对话中编辑**,任何内容都不会自动发送。提示词作为草稿进入输入框,发不发由你决定。
+- 除了定时任务面板,技能标签页里通过对话导入技能、记忆标签页里新增和编辑记忆,也已经接入了这个套件。其他创建表单会在后续版本陆续接入。
+
+![页面顶部的用 AI 创建和手动创建按钮,上面打开着用 AI 创建对话框](/blog-assets/penguinharness-0-2-10-create-with-ai-zh.png)
## 把服务端放到另一台机器上
-官方容器镜像 `hiyouga/penguinharness` 发布在 Docker Hub,支持 `linux/amd64` 与 `linux/arm64`,以 `0.0.0.0:7364` 运行 `penguin server`,数据挂 `/data`。标签 `latest` 跟随 `main`,`X.Y.Z` 由发布 tag 构建。机器记录从 JSON 文件迁入 `web.db` 并归属 Project;每台机器自行签发 16 位 id,通过 ssh 应答,流量走常驻 `ssh -T -D` 会话。
+Docker Hub 上现在有官方容器镜像 `hiyouga/penguinharness`,从源码构建,支持 `linux/amd64` 和 `linux/arm64`。镜像在 `0.0.0.0:7364` 上运行 `penguin server`,数据放在 `/data` 卷里。`latest` 标签跟随 `main` 分支,`X.Y.Z` 标签由各个发布版本构建。文档里的 `docker run` 命令把端口发布在宿主机的回环地址上,所以新部署的实例只有运行 Docker 的那台机器能访问。
+
+用来通过 ssh 在其他机器上安装 PenguinHarness 的**机器**页面,也有几处变化:
-## 模型库
+- 机器记录从 JSON 文件迁入了 `web.db`,并归属于某个 Project。每台机器会自己生成一个 16 字符的 id。
+- PenguinHarness 通过 ssh 运行 `penguin server status`,获取机器的 id,并确认上面的服务端有没有在运行。
+- 每台机器只保持一条常驻的 `ssh -T -D` 会话,发往这台机器的所有流量都走这条会话。已连接机器的 API 在同源路径 `/server/<machineId>/api/…` 下应答。
-- **DeepSeek V4.1 Flash** 以 `deepseek-flash` 发布并成为默认模型:1,000,000 Token 窗口,支持图片。
-- **Gemini 3.8 Flash** 进入直连与 OpenRouter,1,048,576 Token 窗口,支持图片;Google Gemini 3.x Flash 记录现在存官方标价并声明折扣。
-- **GPT-6 Astra** 进入直连与 OpenRouter(1,050,000 Token 窗口,支持图片)。
-- 三条 **Doubao Seed** 进入 TokenDance 分组,享五折促销。
-- 新增 **vLLM** 分组,收录八个自建部署模型:价格为零,不带 base URL,协议由分组统一锁定。
+## 模型目录
-已有 Project 需在模型页执行**同步预置**获取。
+- **DeepSeek V4.1 Flash** 以不带版本号的 id `deepseek-flash` 上架,并成为新建 Project 的默认模型。它有 1,000,000 Token 的上下文窗口,支持图片输入,按 Flash 系列定价,非高峰时段价格减半。它的直连条目固定了客户端和 base URL。
+- **Gemini 3.8 Flash** 加入直连分组和 OpenRouter,上下文窗口 1,048,576 Token,支持图片输入。Gemini 3.x Flash 的条目现在保存官方标价,并单独声明上线折扣,不再把折扣直接算进价格;两条计费价格有误的条目也已更正。
+- **GPT-6 Astra** 加入直连分组和 OpenRouter,上下文窗口 1,050,000 Token,支持图片输入,每百万 Token 的价格为 $1 / $12.5 / $50(缓存读取 / 缓存写入 / 输出)。
+- 三个 **Doubao Seed** 模型加入 TokenDance 分组,按五折计费。
+- 新增 **vLLM** 分组,收录八个自建部署的模型。这些条目价格为零,不带 base URL,协议由分组统一固定。
+
+已有的 Project 需要在模型页点击**同步预置**,才能拿到这些条目。
## 这一版还有
-- 被拒绝的工具调用会说明错误、参数表和正确形状;`exec_command` 同时接受 `command`/`cmd`,`read_image`/`describe_image` 并入 `read_file`。
-- 慢轮显示耗时分解,如 `Elapsed 10.3s (API 5s, tools 5.3s)`,不含等待审批。
-- 侧栏为有开发服务器或后台子智能体的 Session 显示活动标记和胶囊标签。
-- 压缩展示状态与耗时,思考与摘要分别流进折叠行。
-- LLM 请求按沉默超时,`model.timeoutMs` 是事件间空闲预算,默认提升到 300000,收到内容后重试阶梯重置。
-- 更新只走一个对话框:检查、发布说明、下载、重启并更新。
-- 对话默认只打开最近 50 轮,向上滚动按需加载更早内容。
-- 侧栏列出每个 Workspace,依据服务端计数。
-- 终端链接按目标打开,重绘后按位置判定点击,OSC 52 复制可到系统剪贴板。
-- 插件版本写作 `2026.09.10.1`,旧写法被读作同一版本。
+- `exec_command` 除了 `cmd`,也接受 `command`。工具拒绝一次调用时,现在会说明错在哪里、有哪些参数,以及正确的调用形式。`read_image` 和 `describe_image` 并入了 `read_file`。
+- 耗时较长的轮次会显示时间花在了哪里,例如 `Elapsed 10.3s (API 5s, tools 5.3s)`。两部分都不计入等待审批的时间。
+- 有开发服务器或后台子 Agent 正在运行的会话,会在侧栏里带上标记,对话顶部也会显示对应的胶囊标签。
+- 压缩行会显示状态和耗时,思考内容和摘要分别流式写进各自可以展开的行里。
+- `model.timeoutMs` 现在是上游两次事件之间的空闲时限,默认值提高到 300000,所以请求只会因为长时间没有响应而超时,不会因为生成时间长而超时。收到内容之后,重试阶梯会从头开始。
+- 更新全部在一个对话框里完成:检查更新、查看发布说明、下载时显示进度条,最后点击**重启并更新**。
+- 打开对话时只加载最近 50 轮,向上滚动时再加载更早的内容。
+- 按 Workspace 分组时,侧栏会列出所有 Workspace,不再只列出已加载会话所属的那些。
+- 终端更像终端了:屏幕重绘之后,链接仍能正确打开;通过 OSC 52 复制的内容也能进入系统剪贴板。
+- 插件版本号现在写作 `2026.09.10.1` 这样的形式。用旧写法(短横线分隔)安装的副本仍算作同一个版本,不会误报有更新。
+
+## 关于 0.2.10
+
+0.2.11 是用 electron-builder 26.16.1 重新构建的 0.2.10,签名的 macOS 安装包又能正常构建了。0.2.10 已经打了 tag,npm 包和 Docker 镜像也已发布,但签名的 macOS 构建失败,所以 0.2.10 始终没有安装包,也没有 Release 页面。各项改动的记录仍在 [`changelog/0.2.10/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.10)。
## 升级须知
-- **热推送需重启一次**:本版包含首个“仅限重启”迁移 `drop-goal-state`,热推送会在触及数据库前被拒绝;正常安装会重启并执行迁移,回退 0.2.9 可行。
-- 给旧 Agent 安装 `goal` 插件,否则启动目标模式会返回 `409 goal_plugin_not_installed`。
-- 内核需更新到 `2026-09-10` 才能用 `read_file` 读图;脚本中 `skills`/`--skills` 改为 `plugins`/`--plugins`。
-- API 变化:`POST /api/version/update` 返回任务状态而非阻塞到结束;机器路由移至 Project 下,0.2.9 装机机器列表会为空,从对应 Project 重装恢复。
+- **需要重启一次。** 这一版包含第一个只能在重启时执行的数据库迁移 `drop-goal-state`。热推送到运行中的实例时,系统会在改动数据库之前就拒绝;正常安装则会重启并执行迁移。回退到 0.2.9 仍然可行。
+- **给 0.2.10 之前创建的 Agent 安装 `goal` 插件。** 不装的话,目标模式会返回 `409 goal_plugin_not_installed`。每个 Agent 点一下就能装好。
+- **把内核更新到 `2026-09-10`**,Agent 才会用 `read_file` 读图。在此之前,调用旧图片工具会得到「未知工具」的回复,读图也仍按已保存的 30 秒超时执行。
+- **把创建 Agent 的脚本里的 `skills` / `--skills` 改成 `plugins` / `--plugins`。**
+- **API 变化。** `POST /api/version/update` 现在返回任务状态,不再阻塞到更新结束。机器相关的路由移到了 Project 下面,所以 0.2.9 里的机器列表升级后会是空的;从这台机器所属的 Project 重新安装一次即可恢复。
+
+## 安装
-桌面端安装包在 [penguin.ooo/download](https://penguin.ooo/download);CLI 与服务端的安装方式:
+桌面应用的安装包在 [penguin.ooo/download](https://penguin.ooo/download)。
+
+Linux 和 macOS 上,用下面的命令安装 CLI 和服务端:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
+Windows 上用 PowerShell:
+
```powershell
irm https://penguin.ooo/install.ps1 | iex
penguin web
```
+用 Docker 运行服务端:
+
```sh
docker run -d --name penguin -p 127.0.0.1:7364:7364 -v penguin-data:/data hiyouga/penguinharness:latest
```
-
-0.2.11 是 0.2.10 的重新构建版:electron-builder 升至 26.16.1,签名的 macOS 安装包得以重新构建;0.2.10 本身没有安装包也没有 Release 页面。完整细节见 [`changelog/0.2.10/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.10)。
diff --git a/packages/landing/content/blog/penguinharness-0-2-13.en.md b/packages/landing/content/blog/penguinharness-0-2-13.en.md
index 0aa952ce..f04678bf 100644
--- a/packages/landing/content/blog/penguinharness-0-2-13.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-13.en.md
@@ -1,126 +1,162 @@
---
-title: "PenguinHarness 0.2.13: a rebuilt Evaluation Center, a working file manager, a tray icon, and a company-mode beta"
+title: "PenguinHarness 0.2.13: a rebuilt Evaluation Center, a file manager, and a company-mode beta"
date: 2026-09-15
category: news
-excerpt: The Evaluation Center was rebuilt around a Benchmark that became a peer of an agent rather than something an agent owns. The Workspace browser grew a context menu and lost its size ceilings, the desktop app keeps working from the system tray after you close its window, and a running tool call can be handed to the background. Three gateway bugs that used to end a task mid-run are gone. Last, a Project can become an organization: company mode — a beta, off until an admin turns it on — gives a Project's Agents a CEO, a reporting tree, a calendar, a five-column ticket board and channels, each of them a file on disk.
+excerpt: "The Evaluation Center is rebuilt so one Benchmark can evaluate several agents. The Files panel becomes a working file manager, the desktop app keeps running in the system tray, and company mode arrives as a beta that an admin turns on."
---
-PenguinHarness 0.2.13 is a release about the workbench: the Evaluation Center rebuilt around the loop it exists to serve, the Files panel turned into something you can actually manage a Workspace with, a tray icon for the desktop app, and three provider-gateway bugs that used to stop a Task where it stood. Behind an admin switch it also opens a beta — a Project can become an organization, with a CEO that proposes, a human who decides, and the whole company living as files under the Project.
+PenguinHarness 0.2.13 rebuilds the Evaluation Center so that one Benchmark can evaluate several agents, and turns the Files panel into a working file manager. The desktop app now keeps running in the system tray after you close its window, a running tool call can be sent to the background, and three gateway bugs that used to end a Task mid-run are fixed. We are also shipping company mode as a beta: an admin turns it on, and then you can create an organization of agents inside a Project.
-## The Evaluation Center, rebuilt around the loop
+## A rebuilt Evaluation Center
-- A Benchmark moved from `agents/<agent>/benchmarks/<id>/` to the Project's own `benchmarks/<id>/`: one Benchmark can now evaluate several agents, and the agent under test is recorded on each evaluation.
-- An evaluation's label is `<agent_id> · <model_id> · <thinking_level>`, and the chart draws one series per label. Only comparable scores share a line, so successive versions of one agent on one runtime finally form one connected trend.
-- Opening a Benchmark now enters it, at `/benchmark/:benchmarkId`. A table row opens an evaluation dialog.
-- Both detail dialogs end in an **Ask AI** button that hands what is on screen — Benchmark id, series label, version, provider, model, thinking level, per-case scores and every run's Session id — to a prefilled conversation.
-- A Benchmark carries a `status`. A `draft` is masked while `benchmark-design` calibrates it, and the publish gate is a fixed 85 on the 0–100 scale.
-- Evaluation Sessions are filed into their own **Evaluations** folder instead of pouring into the tested agent's active list.
+A Benchmark no longer lives inside the agent it tests. It moved from `agents/<agent>/benchmarks/<id>/` to the Project's own `benchmarks/<id>/`, so one Benchmark can evaluate several agents, and each evaluation records which agent it tested.
-![A Benchmark's page: the score chart drawing one labelled series per agent, model and thinking level, above the evaluation table](/blog-assets/penguinharness-0-2-13-benchmark-detail-en.png)
+- An evaluation is labeled `<agent_id> · <model_id> · <thinking_level>`, and the chart draws one series per label. Only comparable scores share a line, so successive versions of one agent on one runtime now form one connected trend.
+- Opening a Benchmark now takes you to its own page at `/benchmark/:benchmarkId`. A row in the evaluation table opens an evaluation dialog, and a case opens a case dialog.
+- Both dialogs end in an **Ask AI** button that hands what is on screen to a prefilled conversation. From an evaluation, that is the Benchmark id, series label, version, provider, model, thinking level, per-case scores and every run's Session id. From a case, it is the paths to the case's statement and rubric, and how the latest evaluation's runs scored it.
+- A Benchmark carries a `status`. A `draft` stays masked while the `benchmark-design` Skill calibrates it, and the Skill publishes it once the tested agent's baseline scores below 85 on the 0–100 scale.
+- Evaluation Sessions go into their own **Evaluations** folder instead of filling up the tested agent's active list.
-## The Workspace browser became a working file manager
+![A Benchmark's page: the score chart drawing one labeled series per agent, model and thinking level, above the evaluation table](/blog-assets/penguinharness-0-2-13-benchmark-detail-en.png)
-- Renamed to Files, it gained a context menu on any tree row or the preview body — copy path, add to conversation, upload, download, rename, move, delete — reached by right-click, Shift+F10 or a long press.
-- Renames and deletes carry the same precondition the editor's save does, so one is refused if the Agent rewrote the file while the dialog was open.
-- Highlighting moved to a worker, which is what removed the size ceilings: it costs about four milliseconds per kilobyte of TypeScript, which is why the source view gave up above 64KB and the editor above 32KB. Both ceilings are gone.
-- A text preview now reads up to 1MB, and over a 400KB file the page holds a full 60 frames a second for the whole pass.
-- The search box searches the whole Workspace on the server, rather than filtering the rows the tree happened to have loaded. Soft wrap now defaults to on.
+## The Files panel is now a file manager
+
+The Workspace browser is renamed **Files**, and you can now manage a Workspace with it, not only browse it.
+
+- Any tree row and the preview body have a context menu, which you open with a right-click, Shift+F10 or a long press. It offers copy path, add to conversation, upload, download, rename, move and delete.
+- Renames and deletes carry the same check as the editor's save: if the agent rewrote the file while the dialog was open, the action is refused.
+- Syntax highlighting moved to a background worker, which removed the size limits. Highlighting costs about four milliseconds per kilobyte of TypeScript, which is why the source view used to give up above 64KB and the editor above 32KB. Both limits are gone.
+- A text preview now reads up to 1MB. On a 400KB file, the page holds a steady 60 frames per second while it highlights.
+- The search box searches the whole Workspace on the server, rather than filtering only the rows the tree happened to have loaded.
+- Soft wrap is now on by default.
![The Files panel with its context menu open over a tree row](/blog-assets/penguinharness-0-2-13-files-panel-en.png)
-## The desktop app stays running when you close the window
+## The desktop app keeps running when you close the window
+
+The desktop app now has a system tray icon on Windows, macOS and Linux. By default, closing the main window hides the app in the tray, and the embedded server and its background tasks keep running.
-- It takes a place in the system tray on Windows, macOS and Linux, and closing the main window hides it there by default, leaving the embedded server and its background tasks running.
-- Left click brings the window back; right click offers Open, New Session, Models, a **Keep running in the tray when the window closes** checkbox, and Quit. A **Tray icon** switch in Settings › Appearance turns it off with no restart.
-- **Show in folder** joins the Files panel's preview header, drawn only in the desktop app's own window and enforced server-side — a browser signed into the same server does not get it, even when it is running on that very machine. macOS and Windows select the file; Linux opens the directory.
+- Left-click the tray icon to bring the window back. Right-click it for **Open PenguinHarness**, **New Session**, **Models**, a **Keep running in the tray when the window closes** checkbox, and **Quit**.
+- The **Tray icon** switch in **System settings** › **Appearance** turns the tray icon off, without a restart.
+- **Show in folder** joins the header of the Files panel's preview. It appears only in the desktop app's own window, and the server enforces that: a browser signed in to the same server does not get it, even when the browser runs on that very machine. On macOS and Windows it selects the file; on Linux it opens the folder.
## Send a running tool call to the background
-- While an `exec_command` or `run_subagent` is executing, its row offers **Send to background**: the call closes with a `process_id` or `subagent_id`, nothing is killed, and the turn continues instead of waiting out the command.
-- A detached subagent keeps running and streaming after the turn that started it has ended.
-- The action appears once the call has been running for ten seconds, so a command that returns in a few seconds no longer flashes it and takes it away again.
+While an `exec_command` or `run_subagent` call is executing, its row offers **Send to background**. The call returns with a `process_id` or `subagent_id`, nothing is killed, and the turn continues instead of waiting for the command to finish.
+
+- A subagent sent to the background keeps running and streaming after the turn that started it has ended.
+- **Send to background** appears only after the call has been running for ten seconds, so it no longer flashes up and disappears on a command that returns within a few seconds.
![A running exec_command row offering Send to background](/blog-assets/penguinharness-0-2-13-send-to-background-en.png)
-## Three gateway bugs that used to end a task mid-run
+## Three gateway bugs that ended Tasks mid-run
+
+Each of these bugs caused a provider to return a 4xx error that the engine treated as fatal, so the Task stopped where it stood. All three are fixed in AgentHub.
-- Each of these produced a provider 4xx the engine classified as fatal, so the Task stopped where it stood.
-- AgentHub 0.4.12 moves an image read by `read_file` or returned by an MCP tool out of the `tool` message and onto the user message that follows the turn, the one placement Chat Completions documents. A schema-validating gateway used to reject the whole request.
-- 0.4.14 ends two DeepSeek failures: `400 invalid_json` on the request after the first tool call behind a strict Responses relay, and `400 The reasoning_content in the thinking mode must be passed back to the API` part-way through a long tool chain.
-- 0.4.15 fixes a turn that calls two tools in parallel through a gateway that opens every call before closing any, which used to lose the whole turn one request later with `No function call found for function_call_output`.
+- AgentHub 0.4.12 moves an image read by `read_file`, or returned by an MCP tool, out of the `tool` message and onto the user message that follows the turn. That is the only placement Chat Completions documents, and a schema-validating gateway used to reject the whole request.
+- AgentHub 0.4.14 fixes two DeepSeek failures: `400 invalid_json` on the request after the first tool call behind a strict Responses relay, and `400 The reasoning_content in the thinking mode must be passed back to the API` part-way through a long tool chain.
+- AgentHub 0.4.15 fixes turns that call two tools in parallel through a gateway that opens every call before closing any. The whole turn used to be lost one request later, with `No function call found for function_call_output`.
## Shell commands can be confined
-- The harness gained a sandbox interface naming three dimensions — `fs-write`, `network`, `mask-paths` — with argv rewriting, honest enforcement reporting and fail-closed routing: a requirement no backend covers aborts the spawn rather than running the command unconfined.
-- No backend is part of the harness. Four ship as plugin packages a deployment installs and names in `plugins.json`: `sandbox-dsh` (portable), `-bwrap` (Linux), `-seatbelt` (macOS) and `-mxc` (Windows).
-- A default deployment names none and confines nothing.
+The harness gained a sandbox interface that confines shell commands along three dimensions: `fs-write`, `network` and `mask-paths`. Backends rewrite the command's argv and report honestly what they enforce. Routing fails closed: if no backend covers a requirement, the command is not started, rather than running unconfined.
+
+No backend is built into the harness. Four ship as plugin packages named `@prismshadow/penguin-plugin-<backend>`, which a deployment installs and names in `plugins.json`:
+
+| Backend | Platform |
+| --- | --- |
+| `sandbox-dsh` | Portable |
+| `sandbox-bwrap` | Linux |
+| `sandbox-seatbelt` | macOS |
+| `sandbox-mxc` | Windows |
+
+A default deployment names none of them and confines nothing.
## The model catalog
-- All 43 OpenRouter presets now speak the Responses API — only the ten `openai/*` rows did — and the group itself pins the protocol, so a hand-added OpenRouter model gets it too.
-- **Atria-Dawn-Preview** joins the custom group: Anthropic Messages, 256K context, text only.
-- The free **dots-3-note-preview** joins the TokenDance group: 512K context, vision.
-- Protocol detection stopped taking a typed URL literally. An extra `/v1`, a missing one, or a whole endpoint path copied out of a provider's docs all detect correctly now, and the Models page writes the corrected URL back into the field.
+- All 43 OpenRouter presets now use the Responses API; before, only the ten `openai/*` rows did. The OpenRouter group itself pins the protocol, so a model you add to it by hand uses Responses too.
+- `Atria-Dawn-Preview` joins the Custom group, with Anthropic Messages, a 256K context window and text only.
+- The free `dots-3-note-preview` joins the TokenDance group, with a 512K context window and vision.
+- Protocol detection no longer takes a typed URL literally. An extra `/v1`, a missing one, or a whole endpoint path copied from a provider's docs are all detected correctly, and the **Models** page writes the corrected URL back into the field.
+
+## A Project can hold a company of agents
-## A Project's Agents can become a company
+Company mode is a beta, and it is off until an admin turns it on under **System settings** › **Server** › **Company mode**. The switch takes effect the moment it is flipped. Company mode is marked **Beta** in the mode switch and under the master switch: it is new, and you may run into problems.
-- Company mode is a **beta, and off until an admin turns it on** in System settings › Server › Company mode. It takes effect the moment it is flipped, and it is marked Beta both in the mode switch and under the master switch — it is new, and you will find things.
-- An organization has a CEO at the root of a reporting tree, one standing desk session per employee, a calendar, a ticket board, channels, and a monthly budget per employee that warns at 80% and pauses that employee's calendar at 100%.
-- Every one of those is a file under `<project>/organizations/<org_id>/`. SQLite holds only caches, rebuilt from those files on every pass.
-- Creating an organization takes one sentence — the mission — and produces only the CEO, with a default budget of 100 USD/month compared on the cumulative line, so that one number caps the whole company from the first minute.
-- Six pages — overview, org chart, calendar, tickets, finance, handbook — sit behind a Development | Company switch above the Project switcher, and `penguin org` covers the whole API from the command line, with `--json` everywhere.
+With company mode on, you can create an organization inside a Project, and a Project can hold more than one. Creating an organization takes one sentence, the mission, and produces only the CEO. A manager's budget covers everyone under it, so the CEO's default budget of 100 USD a month caps the whole organization from the first minute.
+
+An organization has:
+
+- a CEO at the root of a reporting tree, and one standing desk Session per employee
+- a calendar
+- a ticket board
+- channels
+- a monthly budget per employee, which warns at 80% and, at 100%, pauses the calendar of that employee and everyone under it
+
+All of this is stored as files under `<project>/organizations/<org_id>/`. SQLite holds only caches, rebuilt from those files on every pass.
+
+Six pages, **Overview**, **Org Chart**, **Calendar**, **Tickets**, **Finance** and **Handbook**, sit behind a **Development | Company** switch above the Project switcher. On the command line, `penguin org` covers the whole API, and every command takes `--json`.
![Company mode's overview page: the inbox, today's schedule and the budget alerts](/blog-assets/penguinharness-0-2-13-company-overview-en.png)
## The board, the calendar, and who decides
-- The ticket board has five columns: `proposed`, `in_progress`, `review`, `done`, `rejected`.
-- The CEO proposes — how it reads the mission, the first tickets, who to hire with what budget and model, how to split the workspace — and you decide. Hiring, budgets, and closing a P0 or P1 ticket all wait for your confirmation in the all-hands channel.
-- A server-side scheduler reconciles every organization every 30 seconds and immediately after an API write: it fires due calendar events at desks, delivers channel mentions, and recomputes budgets. An event that came due while the organization was paused is not backfilled when it resumes.
-- Ticket changes never start a run. They queue and arrive in the employee's next calendar sweep, under `## Since your last sweep`.
-- In a channel, only an `@` mention reaches anyone.
-- A desk or ticket conversation is an ordinary conversation — the same message list, tool cards, approvals and composer as development mode. Company mode has no chat view of its own.
+- The ticket board has five columns: `proposed`, `in_progress`, `review`, `done` and `rejected`.
+- The CEO is meant to propose while you decide, but this is guidance, not a rule the server enforces. The CEO's Skill and the organization's handbook tell the CEO to post one proposal in the all-hands channel and wait for your answer before it hires (roles, budgets, models), sets or raises a budget, rejects someone else's ticket, closes a P0 or P1 ticket without review, or does anything outside the organization.
+- A server-side scheduler reconciles every organization every 30 seconds, and again right after each API write. It fires due calendar events at desks, delivers channel mentions and recomputes budgets. An event that came due while the organization was paused is not run later when it resumes.
+- Ticket changes never start a run. They queue up and reach the employee at its next calendar sweep, under `## Since your last sweep`.
+- In a channel, a message reaches someone only through an `@` mention.
+- A desk or ticket conversation is an ordinary conversation, with the same message list, tool cards and composer as development mode. Company mode has no chat view of its own.
+- Desk and ticket sessions run unattended and never stop to ask a person for tool approval. An organization's approval mode is **Allow all** by default, and there is no always-ask option.
![The five-column ticket board: proposed, in progress, review, done and rejected](/blog-assets/penguinharness-0-2-13-company-tickets-en.png)
## Also in this release
-- The default system prompt grew guardrails: fourteen edits against four failure modes the old prompt permitted. "Cannot resolve" now has an observable trigger — the same error still there after three different fixes — independent tool calls go out together, commands run non-interactively, a library counts as available only once the manifest shows it, and a new `# Output` section kills filler openers, tool-name narration and closing recaps.
-- Two concurrent edits of one file no longer lose one silently. `edit_file` and `write_file` hold a per-file lock across the whole read-modify-write, keyed on the file's real path, so a symlink and its target fold onto one lock.
-- Every account gets a profile: an avatar (128×128, re-encoded, refused over 128 KiB) and a 1–32 character nickname replace the raw user id in the sidebar, the rail and the admin list.
-- The proxy options page can test reachability over six targets — OpenAI, Anthropic, Gemini, DeepSeek and GLM's two hosts — measured from the server, no credential sent, five seconds each. Any HTTP answer counts as reachable, 401 and 403 included.
-- A long Trace finally loads. Later rounds, the compaction round included, used to show an empty message list because only the first 1000 events were ever fetched; the view now pages through the whole file and renders progressively.
-- Tool cards can use short names — `read_file` → read, `exec_command` → exec, `run_subagent` → subagent — with an Appearance switch, on by default. The real name stays in the tooltip.
-- A compaction request runs at the thinking level the Session pinned, like every other request. It used to take the context's base level, which on DeepSeek could get the request rejected outright.
-- Sidebar folders reveal ten conversations at a time, with a Show less that folds them back.
-- The context panel's compaction cutter is readable while you drag it, the room the model has but compaction will not let the Session use is hatched, and clicking a bar segment or a legend row pins its highlight.
-- Task-completion notifications actually work. Nothing ever called `Notification.requestPermission()`, and Electron reports `granted` without asking anyone, so on macOS a bundle that never requested authorization had its notifications dropped. There is now a switch in System settings › General, off by default, which asks at the moment it is flipped; a browser is eligible for the first time.
-- A used-up or expired one-time sign-in link lands on `/login` with a dialog explaining what happened, instead of a page of raw JSON.
-- Signing out asks first, naming what happens: this session ends, running conversations keep going on the server.
-- The Code of Conduct moves to Contributor Covenant 3.0 in both languages. Each rung of the ladder now names the repair expected, not only the consequence; the reporting route is unchanged.
+- **The default system prompt has new guardrails.** Fourteen edits address four failure modes the old prompt allowed. "Cannot resolve" now has an observable trigger: the same error is still there after three different fixes. Independent tool calls go out together, commands run non-interactively, and a library counts as available only once the manifest lists it. A new `# Output` section rules out filler openers, narrating tool names and closing recaps.
+- **Two concurrent edits of one file no longer lose one silently.** `edit_file` and `write_file` hold a per-file lock across the whole read-modify-write. The lock is keyed on the file's real path, so a symlink and its target share one lock.
+- **Every account has a profile.** An avatar (128×128, re-encoded, refused over 128 KiB) and a nickname of 1–32 characters replace the raw user id in the sidebar, the rail and the admin list.
+- **Proxy options can test reachability** for six targets: OpenAI, Anthropic, Gemini, DeepSeek and GLM's two hosts. The test runs from the server, sends no credential, allows five seconds per target, and fills in each row as its answer arrives. Any HTTP answer counts as reachable, 401 and 403 included, because a rejected credential still proves that the name resolved, TCP connected, TLS completed and the host replied.
+- **A long Trace now loads.** Later rounds, including the compaction round, used to show an empty message list because only the first 1000 events were ever fetched. The view now pages through the whole file and renders as it goes.
+- **Tool cards can use short names:** `read_file` shows as read, `exec_command` as exec and `run_subagent` as subagent. A switch in **Appearance** controls this, on by default, and the tooltip keeps the real name.
+- **A compaction request uses the thinking level the Session pinned,** like every other request. It used to take the context's base level, which on DeepSeek could get the request rejected outright.
+- **Sidebar folders reveal ten conversations at a time,** and **Show less** folds them back.
+- **The context panel is easier to read.** The compaction cutter stays readable while you drag it, the room the model has but compaction will not let the Session use is hatched, and clicking a bar segment or a legend row pins its highlight.
+- **Task-completion notifications actually work.** Nothing ever called `Notification.requestPermission()`, and Electron reports `granted` without asking anyone, so on macOS an app bundle that never requested authorization had its notifications dropped. A new switch in **System settings** › **General**, off by default, asks for permission when you turn it on. Browsers can now show these notifications too.
+- **A used or expired one-time sign-in link** now lands on `/login` with a dialog explaining what happened, instead of a page of raw JSON.
+- **Signing out asks first** and says what happens: this session ends, and running conversations keep going on the server.
+- **The Code of Conduct moves to Contributor Covenant 3.0** in both languages. Each rung of the enforcement ladder now names the repair expected, not only the consequence. The reporting route is unchanged.
## Upgrading
-- **Rename `extensions.json` to `plugins.json`, and its `"extensions"` key to `"plugins"`.** The old name is not read and not migrated, so a deployment that configured plugins under it keeps running with none of them loaded and their capability silently unavailable.
-- **Port plugins to the new contract.** Imports point at `@prismshadow/penguin-core/plugin` rather than `/extension`, and `activate(ctx)` is replaced by `Plugin { modules }` — an installed plugin written against the old one fails to load with "the default export is not a Plugin". `@prismshadow/penguin-server` no longer exports `AppDeps`, `buildAppDeps` or `createApp`. Nothing about the wire format, the database or any on-disk document changes with the rename.
-- **Click sync presets on the models page.** Stored rows keep the protocol, display name and vision flag they were written with, so the OpenRouter move to Responses, the `deepseek-v4-flash` text-only correction and the two new presets reach an existing Project only through a sync — though a display name you deliberately cleared is filled in again by it.
-- **Turn company mode on if you want it**, in System settings › Server › Company mode. It is off by default and takes effect on the flip.
-- **Two defaults changed:** task-completion notifications are off until you turn them on, and the file editor's soft wrap is on for anyone who has never touched its Wrap toggle.
+- **Rename `extensions.json` to `plugins.json`, and its `"extensions"` key to `"plugins"`.** The old name is not read and not migrated. A deployment that configured plugins under it keeps running, but with none of them loaded and their capabilities silently unavailable.
+- **Port plugins to the new contract.** Imports point at `@prismshadow/penguin-core/plugin` rather than `/extension`, and `activate(ctx)` is replaced by `Plugin { modules }`. An installed plugin written against the old contract fails to load with "the default export is not a Plugin". `@prismshadow/penguin-server` no longer exports `AppDeps`, `buildAppDeps` or `createApp`. The rename changes nothing about the wire format, the database or any document on disk.
+- **Click Sync presets on the Models page.** Stored rows keep the protocol, display name and vision flag they were written with. The OpenRouter move to Responses, the `deepseek-v4-flash` text-only correction and the two new presets reach an existing Project only through a sync. A sync also fills in again any display name you deliberately cleared.
+- **Turn on company mode if you want it,** under **System settings** › **Server** › **Company mode**. It is off by default and takes effect as soon as you flip it.
+- **Two defaults changed.** Task-completion notifications are off until you turn them on, and the file editor's soft wrap is on for anyone who has never touched its **Wrap** toggle.
- **Move any Benchmark left under `agents/<agent>/benchmarks/` into the Project's `benchmarks/` by hand.** This version does not read the old location, and nothing migrates or deletes it.
-- **Migrations 5, 6, 7 and 8** — the profile page brings 5, company mode brings 6, 7 and 8 — are additive and applied at open.
+- **Migrations 5, 6, 7 and 8** are additive and applied when the database opens. The profile page brings 5, and company mode brings 6, 7 and 8.
-Desktop installers are at [penguin.ooo/download](https://penguin.ooo/download); the CLI and server install with:
+## Install
+
+Desktop installers are at [penguin.ooo/download](https://penguin.ooo/download).
+
+On Linux and macOS, install the CLI and server with:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
+On Windows, use PowerShell:
+
```powershell
irm https://penguin.ooo/install.ps1 | iex
penguin web
```
+To run the server in Docker:
+
```sh
docker run -d --name penguin -p 127.0.0.1:7364:7364 -v penguin-data:/data hiyouga/penguinharness:latest
```
diff --git a/packages/landing/content/blog/penguinharness-0-2-13.zh.md b/packages/landing/content/blog/penguinharness-0-2-13.zh.md
index fb55e7b0..d6ae0ef2 100644
--- a/packages/landing/content/blog/penguinharness-0-2-13.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-13.zh.md
@@ -1,101 +1,164 @@
---
-title: "PenguinHarness 0.2.13:新版评估中心、文件浏览器升级、托盘图标,以及 Agent 公司内测"
+title: "PenguinHarness 0.2.13:重建的评估中心、文件管理器,以及公司模式内测"
date: 2026-09-15
category: news
-excerpt: 评估中心重做了一遍,Benchmark 从 Agent 的附属品变成与 Agent 平级的对象。文件浏览长出右键菜单并去掉了体积上限,桌面端关掉窗口后继续在托盘里干活,运行中的工具调用可以转入后台,三个会让任务中途终止的网关问题也一并修掉。最后是仍在内测的公司模式:缺省关闭,需管理员开启,一个 Project 可以变成一家公司,把里面的 Agent 组织起来——一位 CEO、一棵汇报树、一张日历、一块五列工单板和若干频道,每一样都是磁盘上的文件。
+excerpt: "评估中心重建之后,一个 Benchmark 可以评估多个 Agent。文件面板成了真正能用的文件管理器,桌面应用可以留在系统托盘里继续运行,公司模式也以内测形式推出,由管理员开启。"
---
-PenguinHarness 0.2.13 改的主要是工作台:评估中心按它服务的那条闭环重建,文件浏览变成真的能管理 Workspace 的面板,桌面端进了系统托盘,以及三个曾经让 Task 停在原地的网关问题。这一版还开了一项内测,需管理员开启——「Project 可以变成组织」:CEO 提议、人拍板,整家公司以文件的形式存在 Project 下。
+PenguinHarness 0.2.13 重建了评估中心,一个 Benchmark 现在可以评估多个 Agent;文件面板也成了真正能用的文件管理器。关掉窗口之后,桌面应用会留在系统托盘里继续运行;运行中的工具调用可以转入后台;三个曾让 Task 中途终止的网关问题也修好了。我们还以内测形式推出了公司模式:由管理员开启之后,你就可以在 Project 里建立一个由 Agent 组成的组织。
-## 评估中心围着闭环重建
+## 重建的评估中心
-Benchmark 从 `agents/<agent>/benchmarks/<id>/` 移到了 Project 自己的 `benchmarks/<id>/`:一个 Benchmark 可以评测多个 Agent,被测 Agent 记录在每条评测记录上。评测记录的标签是 `<agent_id> · <model_id> · <thinking_level>`,图表按标签画序列,只有可比的分数才落在同一条线上——同一个 Agent 在同一运行时上的历次版本,终于连成一条趋势线。打开一个 Benchmark 现在是**进入**它,地址是 `/benchmark/:benchmarkId`;表格中的一行点开评测详情对话框。两个详情对话框末尾都有**问 AI**:把屏幕上的事实——Benchmark id、序列标签、版本、供应商、模型、思考等级、逐题分数和每次 Run 的 Session id——交给一个预填好的对话。Benchmark 带上了 `status`,`benchmark-design` 校准期间的 `draft` 会被遮住,发布门槛固定为 0–100 分制下的 85 分。评测产生的 Session 归进独立的「评估任务」分组,不再涌入被测 Agent 的活跃列表。
+Benchmark 不再放在被测 Agent 的目录里。它从 `agents/<agent>/benchmarks/<id>/` 移到了 Project 自己的 `benchmarks/<id>/`,所以一个 Benchmark 可以评估多个 Agent,每条评估记录也会写明被测的是哪个 Agent。
-![Benchmark 页面:按 Agent、模型与思考等级分序列的分数图,下面是评测表格](/blog-assets/penguinharness-0-2-13-benchmark-detail-zh.png)
+- 每条评估记录的标签是 `<agent_id> · <model_id> · <thinking_level>`,图表按标签各画一条序列。只有可比的分数才会落在同一条线上,所以同一个 Agent 在同一运行时上的历次版本,现在能连成一条完整的趋势线。
+- 打开一个 Benchmark,会进入它自己的页面 `/benchmark/:benchmarkId`。点击评估表格里的一行,会打开评估详情对话框;点击一道题目,会打开题目对话框。
+- 两个对话框的末尾都有**问 AI** 按钮,把屏幕上的信息交给一个预填好的对话。从评估详情发起时,交过去的是 Benchmark id、序列标签、版本、供应商、模型、思考等级、各题分数,以及每次运行的 Session id;从题目发起时,交过去的是这道题的任务材料和评分标准的路径,以及最近一次评估中各次运行在这道题上的得分。
+- Benchmark 有了 `status` 字段。`benchmark-design` Skill 校准期间,处于 `draft` 状态的 Benchmark 会以遮罩显示;被测 Agent 的基线分在 0–100 分制下低于 85 时,Skill 就会发布它。
+- 评估产生的会话会归进单独的**评估任务**文件夹,不再挤进被测 Agent 的活跃列表。
-## 文件浏览成了真正的文件管理器
+![Benchmark 页面:按 Agent、模型与思考等级分序列的分数图,下面是评估明细表格](/blog-assets/penguinharness-0-2-13-benchmark-detail-zh.png)
-面板改名为文件浏览,目录树的任意一行和预览区本身都有了右键菜单:复制路径、加入对话、上传、下载、重命名、移动、删除,右键、Shift+F10 和长按都能唤出。重命名和删除带着与编辑器保存相同的前置条件——对话框开着的时候 Agent 改写了文件,这一次操作会被拒绝。高亮移进了 Worker,体积上限也就此消失:TypeScript 每千字节约耗四毫秒,这正是源码视图卡在 64KB、编辑器卡在 32KB 的原因,现在两道上限都没有了。文本预览可读到 1MB,400KB 的文件整个过程稳在每秒 60 帧。搜索框改为在服务端搜索整个 Workspace,而不是过滤目录树恰好加载过的那些行;自动换行改为缺省开启。
+## 文件面板成了文件管理器
+
+Workspace 浏览器改名为**文件浏览**,现在不只能浏览 Workspace,还能用它来管理 Workspace。
+
+- 目录树的任意一行和预览区都有右键菜单,右键点击、按 Shift+F10 或长按都能打开。菜单里有复制路径、添加到对话、上传、下载、重命名、移动和删除。
+- 重命名和删除沿用编辑器保存时的同一项检查:如果对话框开着的时候 Agent 改写了这个文件,这次操作就会遭到拒绝。
+- 语法高亮移到了后台 Worker 里,体积上限也随之取消。高亮 TypeScript 每千字节大约要花四毫秒,这正是过去源码视图超过 64KB、编辑器超过 32KB 就不再处理的原因。现在这两道上限都没有了。
+- 文本预览现在最多可以读取 1MB。打开一个 400KB 的文件时,高亮的整个过程中页面都能稳定保持每秒 60 帧。
+- 搜索框现在在服务端搜索整个 Workspace,而不是只过滤目录树碰巧已经加载的那些行。
+- 自动换行现在默认开启。
![文件浏览面板,目录树上的一行打开着右键菜单](/blog-assets/penguinharness-0-2-13-files-panel-zh.png)
-## 关掉窗口,桌面端继续运行
+## 关掉窗口,桌面应用继续运行
+
+桌面应用现在在 Windows、macOS 和 Linux 上都有系统托盘图标。默认情况下,关闭主窗口只会把应用收进托盘,内嵌的服务端和它的后台任务照常运行。
-桌面应用在 Windows、macOS 和 Linux 的系统托盘里常驻一个图标,关闭主窗口缺省只是把它收进托盘,内嵌的服务端和后台任务照常运行。左键点击把窗口叫回来;右键提供打开、新建会话、模型、**关闭窗口后继续在托盘中运行**复选项和退出。设置 › 外观里的**托盘图标**开关可以关掉它,无需重启。文件浏览的预览头部还多了**在文件夹中显示**:只在桌面应用自己的窗口里绘制,并由服务端把关——用浏览器登录同一台服务端拿不到它,哪怕浏览器就跑在那台机器上。macOS 与 Windows 选中文件,Linux 打开所在目录。
+- 左键点击托盘图标可以把窗口叫回来。右键点击会看到**打开 PenguinHarness**、**新建会话**、**模型**、**关闭窗口后继续在托盘中运行**复选框,以及**退出**。
+- **系统设置** › **外观**里的**托盘图标**开关可以关掉托盘图标,不需要重启。
+- 文件浏览面板的预览头部新增了**在文件夹中显示**。它只在桌面应用自己的窗口里出现,并由服务端把关:登录同一个服务端的浏览器拿不到它,哪怕浏览器就运行在那台机器上。macOS 和 Windows 上会选中这个文件,Linux 上则会打开所在的文件夹。
## 把运行中的工具调用转入后台
-`exec_command` 或 `run_subagent` 执行期间,它在对话里的那一行提供**转入后台执行**:调用带着 `process_id` 或 `subagent_id` 结束,什么都不会被杀掉,这一轮继续往下走,不必等命令跑完。转入后台的子智能体在启动它的那一轮结束之后仍然在跑、仍然在流式输出。这个操作在调用运行满十秒后才出现——几秒就返回的命令不会再闪一下又消失。
+`exec_command` 或 `run_subagent` 执行期间,它在对话里的那一行会出现**转入后台执行**按钮。点击后,这次调用会带着 `process_id` 或 `subagent_id` 返回,不会终止任何东西,这一轮也继续往下走,不必等命令跑完。
+
+- 转入后台的子 Agent,在启动它的那一轮结束之后,仍然会继续运行、继续流式输出。
+- **转入后台执行**要等调用运行满十秒才会出现,几秒就能返回的命令不会再让它闪一下又消失。
![运行中的 exec_command 行上出现的转入后台执行](/blog-assets/penguinharness-0-2-13-send-to-background-zh.png)
-## 三个会让任务中途终止的网关问题
+## 三个曾让 Task 中途终止的网关问题
+
+这三个问题都会让供应商返回 4xx 错误,引擎把它当作致命错误处理,Task 就停在了原地。三个问题都已在 AgentHub 里修复。
+
+- AgentHub 0.4.12 把 `read_file` 读到的图片,或者 MCP 工具返回的图片,从 `tool` 消息挪到这一轮之后的那条 user 消息上。这是 Chat Completions 文档里唯一给出的放置方式;以前,按 schema 校验请求的网关会把整个请求打回。
+- AgentHub 0.4.14 修复了 DeepSeek 上的两个错误:一个是在严格的 Responses 中继后面,第一次工具调用之后的那条请求报 `400 invalid_json`;另一个是长工具链跑到一半时报 `400 The reasoning_content in the thinking mode must be passed back to the API`。
+- AgentHub 0.4.15 修复的是一轮里并行调用两个工具、而网关先打开所有调用再逐个关闭的情况。以前到了下一个请求,这一整轮都会丢失,并报 `No function call found for function_call_output`。
+
+## Shell 命令可以受约束运行
+
+Harness 新增了一个沙箱接口,从三个维度约束 shell 命令:`fs-write`、`network` 和 `mask-paths`。后端负责改写命令的 argv,并如实报告自己实际强制执行了哪些约束。路由宁可拒绝也不放行:如果没有任何后端能覆盖某项要求,命令就不会启动,而不是不受约束地运行。
+
+Harness 本身不带任何后端。四个后端以插件包形式提供,包名是 `@prismshadow/penguin-plugin-<backend>`,由部署方自行安装,并写进 `plugins.json`:
-这三个问题都表现为供应商返回 4xx,被引擎判为致命错误,于是 Task 停在原地。AgentHub 0.4.12 把 `read_file` 读到的、或 MCP 工具返回的图片,从 `tool` 消息挪到该轮之后的 user 消息上——这是 Chat Completions 文档给出的唯一放置方式,此前按 schema 校验的网关会整条请求打回。0.4.14 解决两个 DeepSeek 上的失败:严格的 Responses 中继后面,第一次工具调用之后的那条请求报 `400 invalid_json`;以及长工具链中途报 `400 The reasoning_content in the thinking mode must be passed back to the API`。0.4.15 修的是一轮里并行调用两个工具、而网关先把所有调用打开再逐个关闭的情况——此前会在一条请求之后整轮丢失,报 `No function call found for function_call_output`。
+| 后端 | 平台 |
+| --- | --- |
+| `sandbox-dsh` | 跨平台 |
+| `sandbox-bwrap` | Linux |
+| `sandbox-seatbelt` | macOS |
+| `sandbox-mxc` | Windows |
-## Shell 命令可以被约束
+默认部署一个后端都不写,也就什么都不约束。
-harness 有了自己的沙箱接口,标明三个维度——`fs-write`、`network`、`mask-paths`——具备 argv 改写、如实上报实际强制力,以及失败即关闭的路由:没有后端能覆盖的要求会中止 spawn,而不是让命令不受约束地跑起来。后端不属于 harness 本体,四个以插件包发布,由部署方自行安装并写进 `plugins.json`:`sandbox-dsh`(跨平台)、`-bwrap`(Linux)、`-seatbelt`(macOS)与 `-mxc`(Windows)。缺省部署一个都不写,也就什么都不约束。
+## 模型目录
-## 模型库
+- OpenRouter 的全部 43 条预置现在都使用 Responses API,此前只有十条 `openai/*` 是这样。协议由 OpenRouter 分组本身固定,所以你手动加进这个分组的模型也会使用 Responses。
+- `Atria-Dawn-Preview` 加入 Custom 分组:Anthropic Messages 协议,256K 上下文窗口,仅支持文本。
+- 免费的 `dots-3-note-preview` 加入 TokenDance 分组:512K 上下文窗口,支持图片。
+- 协议识别不再照字面读取你填入的 URL。多一个 `/v1`、少一个 `/v1`,或者从供应商文档里整段复制来的端点路径,现在都能正确识别,**模型库**页面还会把修正后的 URL 写回输入框。
-- OpenRouter 分组全部 43 条预置改用 Responses API,此前只有十条 `openai/*` 是;协议由分组本身锁定,手工添加的 OpenRouter 模型也一并获得。
-- **Atria-Dawn-Preview** 进入自定义分组:Anthropic Messages 协议,256K 上下文,仅文本。
-- 免费的 **dots-3-note-preview** 进入 TokenDance 分组:512K 上下文,支持图片。
-- 协议识别不再照字面读取填入的 URL:多一个 `/v1`、少一个 `/v1`、或者从供应商文档里整段复制来的 endpoint 路径,现在都能正确识别,模型页还会把修正后的 URL 写回输入框。
+## 一个 Project 里可以有一家 Agent 公司
-## 一个 Project 可以变成一家公司
+公司模式是内测功能,默认关闭,需要管理员在**系统设置** › **服务器** › **公司模式**里打开。开关一拨,立即生效。模式切换处和总开关下方都标着**内测版**:这项功能还很新,你可能会遇到问题。
-公司模式是**内测功能,缺省关闭**,要管理员在「系统设置 › 服务器 › 启用公司模式」里打开,开关一拨即刻生效;模式切换处和总开关下方都标着内测版——它很新,你会撞上问题。一个组织以 CEO 为汇报树的根,每位员工有一条常驻的工位会话,另有日历、工单板、频道,以及每位员工的月度预算:用到 80% 告警,100% 暂停该员工的日历。这些全都是 `<project>/organizations/<org_id>/` 下的文件,SQLite 只存每轮从这些文件重建的缓存。新建一个组织只要一句话——使命——建成后只有 CEO,缺省预算每月 100 USD,按累计额比较,所以从第一分钟起就有一个数字封住整家公司。概览、组织图、日历、工单、财务、手册六个页面挂在 Project 切换器上方的「开发 | 公司」开关后面;命令行一侧,`penguin org` 覆盖了全部 API,每条命令都带 `--json`。
+打开公司模式后,你可以在 Project 里创建组织,一个 Project 里可以有多个组织。创建组织只需要一句话,也就是组织的使命;刚创建时,组织里只有 CEO。管理者的预算涵盖其所有下属,所以 CEO 默认每月 100 USD 的预算,从一开始就封住了整个组织的开销。
+
+一个组织包括:
+
+- 一位 CEO,位于汇报树的根部;每位员工各有一条常驻的工位会话
+- 一份日历
+- 一块工单板
+- 若干频道
+- 每位员工的月度预算:用到 80% 时告警,用到 100% 时暂停这位员工及其所有下属的日历
+
+这些全都以文件形式存放在 `<project>/organizations/<org_id>/` 下。SQLite 只保存缓存,每一轮都从这些文件重建。
+
+**概览**、**组织图**、**日历**、**工单**、**财务**和**手册**六个页面,挂在 Project 切换器上方的**开发 | 公司**开关后面。命令行一侧,`penguin org` 覆盖了全部 API,每条命令都支持 `--json`。
![公司模式的概览页:收件箱、今日日程与预算告警](/blog-assets/penguinharness-0-2-13-company-overview-zh.png)
-## 看板、日历,以及谁来拍板
+## 工单板、日历,以及谁来拍板
-工单板分五列:提议、进行中、审核中、已完成、已拒绝。CEO 负责提议——它如何理解使命、第一批工单、招谁、给多少预算和什么模型、工作区怎么划分——由你拍板:招聘、预算,以及关闭 P0 或 P1 工单,都要等你在全员频道里确认。服务端调度器每 30 秒对每个组织对账一次,API 写入之后也立刻再对一次:把到点的日程投给工位、投递频道里的提及、重算预算;组织暂停期间到点的日程,恢复后不会补发。工单变更本身从不启动运行,它们排队等待,在该员工下一次日历扫描时落在 `## Since your last sweep` 之下。频道里只有 `@` 提及才会送达。工位会话与工单会话都是普通对话——同一套消息列表、工具卡片、审批与输入框——公司模式没有自己的聊天页。
+- 工单板分五列:`proposed`、`in_progress`、`review`、`done` 和 `rejected`。
+- 按照设计,CEO 负责提议,由你拍板,但这只是写给 Agent 的指引,服务端并不强制执行。CEO 的 Skill 和组织手册要求它:在招聘(岗位、预算、模型)、设定或提高预算、驳回别人提的工单、不经审核就关闭 P0 或 P1 工单,以及做任何超出组织范围的事情之前,先在全员频道里发一条提案,等你答复。
+- 服务端调度器每 30 秒对每个组织对账一次,每次 API 写入之后也会马上再对一次。它把到期的日程投递给工位,送达频道里的提及,并重新计算预算。组织暂停期间到期的日程,恢复之后不会补发。
+- 工单变更从不启动运行。变更先排队,等到这位员工下一次日历巡检时才送达,列在 `## Since your last sweep` 标题下。
+- 在频道里,只有 `@` 提及才能把消息送到某个人那里。
+- 工位会话和工单会话都是普通对话,消息列表、工具卡片和输入框都和开发模式一样。公司模式没有自己的聊天页。
+- 工位会话和工单会话无人值守运行,从不停下来请人审批工具调用。组织的审批模式默认是**全部放行**,也没有「总是询问」这个选项。
![五列工单板:提议、进行中、审核中、已完成、已拒绝](/blog-assets/penguinharness-0-2-13-company-tickets-zh.png)
## 这一版还有
-- 缺省系统提示词加了护栏:针对旧提示词容许的四种失败模式改了十四处。「无法解决」现在有了可观测的触发条件——换过三种修法之后同一个错误仍在——相互独立的工具调用一次发出,命令以非交互方式运行,一个库只有在清单里出现才算可用,新增的 `# Output` 一节则掐掉了开场废话、复述工具名和结尾总结。
-- 同一个文件上的两处并发编辑不会再悄悄丢掉一处:`edit_file` 与 `write_file` 在整个读-改-写期间持有按文件的锁,以文件的真实路径为键,因此软链接与目标折叠到同一把锁上。
-- 每个账号都有了个人资料:头像(128×128,重新编码,超过 128 KiB 拒绝)与 1–32 字符的昵称,取代侧栏、导航栏和管理员列表里的原始用户 id。
-- 代理设置页可以测连通性,六个目标——OpenAI、Anthropic、Gemini、DeepSeek 和 GLM 的两个域名——由服务端发起,不带任何凭据,每个五秒,各行分别出结果。任何 HTTP 应答都算连通,401 和 403 也算:凭据被拒同样证明了域名解析、TCP 连接、TLS 握手和主机应答都成立。
-- 长 Trace 终于能打开了。此前只取前 1000 条事件,导致靠后的轮次(包括压缩那一轮)消息列表是空的;现在会翻完整个文件并渐进渲染。
-- 工具卡片可以用短名:`read_file` → 读取、`exec_command` → 执行命令、`run_subagent` → 子智能体,由外观里的开关控制,缺省开启,真实名字仍在悬停提示里。
-- 压缩请求按 Session 锁定的思考等级发出,和其他请求一样。此前它取的是上下文的基础等级,在 DeepSeek 上会导致请求直接被拒。
-- 侧栏文件夹每次展开十条对话,并提供「收起」折回去。
-- 上下文面板的压缩刻刀在拖动时可读,模型有、但压缩不允许 Session 用掉的那段空间以斜纹标出,点击长条的一段或图例的一行会把高亮钉住。
-- 任务完成通知这次是真的能用了。此前从来没有人调用过 `Notification.requestPermission()`,而 Electron 不问任何人就报告 `granted`,于是在 macOS 上,一个从未申请过授权的应用包,通知被直接丢弃。现在系统设置 › 通用里有一个开关,缺省关闭,拨动的那一刻才去申请;浏览器也第一次具备了资格。
-- 用过或过期的一次性登录链接会落到 `/login` 并弹出对话框说明原因,而不是一页原始 JSON。
-- 退出登录会先问一句,并说明后果:本次会话结束,运行中的对话在服务端继续。
-- 行为准则升级到 Contributor Covenant 3.0,中英文同步。阶梯的每一级现在写明了期待的修复动作,而不只是后果;举报渠道不变。
+- **默认系统提示词加了护栏。** 一共改了十四处,针对旧提示词放任的四种失败模式。「无法解决」现在有了可观测的触发条件:换了三种不同的修法之后,同一个错误依然存在。相互独立的工具调用会一次发出,命令以非交互方式运行,一个库要在清单文件里出现才算可用。新增的 `# Output` 一节去掉了空洞的开场白、复述工具名和结尾总结。
+- **同一个文件上的两处并发编辑,不会再悄悄丢掉一处。** `edit_file` 和 `write_file` 在读取、修改、写回的整个过程中都持有按文件加的锁。锁以文件的真实路径为键,所以软链接和它指向的文件共用同一把锁。
+- **每个账号都有了个人资料。** 头像(128×128,会重新编码,超过 128 KiB 拒收)和 1–32 个字符的昵称,取代了侧栏、导航栏和管理员列表里的原始用户 id。
+- **代理选项可以测试连通性**,目标共六个:OpenAI、Anthropic、Gemini、DeepSeek,以及 GLM 的两个域名。测试由服务端发起,不带任何凭据,每个目标限时五秒,哪个目标有了结果,就填进对应的那一行。任何 HTTP 应答都算连通,401 和 403 也算,因为即使凭据遭到拒绝,也说明域名解析、TCP 连接和 TLS 握手都已成功,主机也作出了应答。
+- **长 Trace 现在能打开了。** 以前只取前 1000 条事件,靠后的轮次(包括压缩那一轮)显示的都是空的消息列表。现在查看器会分页读完整个文件,边读边渲染。
+- **工具卡片可以显示短名。** `read_file` 显示为「读取」,`exec_command` 显示为「执行命令」,`run_subagent` 显示为「子智能体」。**外观**里有一个开关控制这项功能,默认开启,悬停提示里仍是真实名字。
+- **压缩请求使用会话锁定的思考等级**,和其他请求一样。以前它用的是上下文的基础等级,在 DeepSeek 上可能导致请求直接遭到拒绝。
+- **侧栏文件夹每次展开十条对话**,点击**收起**可以折叠回去。
+- **上下文面板更好读了。** 拖动压缩阈值的虚线时,数值始终看得清;模型本身有、但压缩不允许会话用到的那部分空间,会以斜纹标出;点击长条上的一段或图例里的一行,可以把高亮固定住。
+- **任务完成通知这次真的能用了。** 以前没有任何代码调用过 `Notification.requestPermission()`,而 Electron 不问任何人就报告 `granted`,所以在 macOS 上,从没申请过授权的应用包发出的通知会直接丢失。现在**系统设置** › **通用**里新增了一个开关,默认关闭,打开的那一刻才去申请权限。浏览器现在也能显示这类通知了。
+- **用过或已过期的一次性登录链接**,现在会跳到 `/login`,并弹出对话框说明原因,而不是显示一页原始 JSON。
+- **退出登录前会先确认**,并说明后果:当前的登录会话结束,运行中的对话在服务端继续。
+- **行为准则升级到 Contributor Covenant 3.0**,中英文同步。执行阶梯的每一级现在都写明了期望的补救措施,而不只是后果。举报渠道不变。
## 升级须知
-- **把 `extensions.json` 改名为 `plugins.json`,其中的 `"extensions"` 键改为 `"plugins"`。** 旧名不再被读取,也不迁移:按旧名配置插件的部署会照常运行,但一个插件都不加载,对应能力静悄悄地消失。
-- **插件按新契约改写。** import 指向 `@prismshadow/penguin-core/plugin` 而非 `/extension`,`activate(ctx)` 换成 `Plugin { modules }`——按旧契约写的插件加载时报「the default export is not a Plugin」。`@prismshadow/penguin-server` 不再导出 `AppDeps`、`buildAppDeps` 和 `createApp`。改名不触及任何线上格式、数据库或磁盘文档。
-- **到模型页点一次「同步预置」。** 已存的模型行保留写入时的协议、显示名和图片能力,因此 OpenRouter 转 Responses、`deepseek-v4-flash` 更正为仅文本,以及两条新预置,都只能通过同步到达既有 Project——代价是被你特意清空的显示名会被重新填上。
-- **想用公司模式要自己打开**:系统设置 › 服务器 › 启用公司模式,缺省关闭,拨动即生效。
-- **两处缺省值变了**:任务完成通知改为默认关闭,需要自己打开;文件编辑器的自动换行对从未动过 Wrap 开关的人默认开启。
-- **旧位置 `agents/<agent>/benchmarks/` 下的 Benchmark 需要手工搬到 Project 的 `benchmarks/`。** 本版不读旧位置,也不迁移、不删除它们。
-- **迁移 5、6、7、8**(个人资料页带来 5,公司模式带来 6、7、8)都是增量式的,打开时自动应用。
+- **把 `extensions.json` 改名为 `plugins.json`,其中的 `"extensions"` 键改为 `"plugins"`。** 旧文件名不再读取,也不做迁移。按旧名称配置插件的部署会照常运行,但一个插件都不会加载,这些插件提供的能力就这样悄无声息地没了。
+- **按新契约改写插件。** import 路径改为 `@prismshadow/penguin-core/plugin`,不再是 `/extension`;`activate(ctx)` 换成了 `Plugin { modules }`。按旧契约编写的已安装插件会加载失败,报「the default export is not a Plugin」。`@prismshadow/penguin-server` 不再导出 `AppDeps`、`buildAppDeps` 和 `createApp`。这次改名不影响线上传输格式、数据库,也不影响磁盘上的任何文档。
+- **到模型库页面点一次同步预置。** 已存的模型条目会保留写入时的协议、显示名和视觉标记。OpenRouter 改用 Responses、`deepseek-v4-flash` 更正为仅支持文本,以及两条新预置,都只能通过同步进入已有的 Project。同步还会把你特意清空的显示名重新填上。
+- **想用公司模式,就自己打开**:位置在**系统设置** › **服务器** › **公司模式**。它默认关闭,开关一拨就生效。
+- **两个默认值变了。** 任务完成通知默认关闭,需要你自己打开;对于从没动过**自动换行**开关的人,文件编辑器的自动换行默认开启。
+- **把还留在 `agents/<agent>/benchmarks/` 下的 Benchmark 手动移到 Project 的 `benchmarks/`。** 这个版本不读取旧位置,也不会迁移或删除那里的内容。
+- **迁移 5、6、7、8** 都是只做新增的迁移,在打开数据库时自动执行。个人资料页带来迁移 5,公司模式带来迁移 6、7、8。
-桌面端安装包在 [penguin.ooo/download](https://penguin.ooo/download);CLI 与服务端的安装方式:
+## 安装
+
+桌面应用的安装包在 [penguin.ooo/download](https://penguin.ooo/download)。
+
+Linux 和 macOS 上,用下面的命令安装 CLI 和服务端:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
+Windows 上用 PowerShell:
+
```powershell
irm https://penguin.ooo/install.ps1 | iex
penguin web
```
+用 Docker 运行服务端:
+
```sh
docker run -d --name penguin -p 127.0.0.1:7364:7364 -v penguin-data:/data hiyouga/penguinharness:latest
```
-完整细节见 [`changelog/0.2.13/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.13)。
+每一项改动的完整细节见 [`changelog/0.2.13/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.13)。
diff --git a/packages/landing/content/blog/penguinharness-0-2-2.en.md b/packages/landing/content/blog/penguinharness-0-2-2.en.md
index 79288dcd..89fed104 100644
--- a/packages/landing/content/blog/penguinharness-0-2-2.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-2.en.md
@@ -1,59 +1,99 @@
---
-title: "PenguinHarness 0.2.2: Agents That Remember"
+title: "PenguinHarness 0.2.2: long-term memory and MCP Server support"
date: 2026-08-11
category: news
-excerpt: 0.2.2 gives an agent long-term memory across sessions — a user scope and a per-workspace scope, indexes injected into context, bodies read on demand, a Memory tab to manage it all — plus MCP Server support over three transports. Skills, Vault and Schedules move behind Memory-style editable prompts with enable switches, agent configs gain a dated kernel version whose Update merges new defaults without losing customizations, the core runtime fixes a trace-corruption bug, and the dependency audit comes back clean. The details, item by item.
+excerpt: 0.2.2 gives agents long-term memory across Sessions, with a Memory tab to manage it, and adds MCP Server support over three transports. Prompt sections become editable and switchable, agent configs gain a kernel version, and a Trace corruption bug is fixed.
---
-PenguinHarness 0.2.2 is out. Earlier releases gave the agent hands — file tools, subagents, skills, scheduled tasks. This one gives it a memory: what an agent learns in one session is finally there for the next. Alongside it come MCP Server support, switchable prompt injection, and a versioning scheme for the configuration itself.
+PenguinHarness 0.2.2 is out. Earlier releases gave agents their working tools: file tools, subagents, Skills and scheduled tasks. This release gives them a memory, so what an agent learns in one Session is there for the next. It also adds MCP Server support, prompt sections you can edit and switch off, and a version stamp for the agent configuration itself.
## Memory
-Each agent keeps long-term notes under `agent_state/memory/`, in two scopes. The user scope is read by every session. Workspace scopes are keyed to the directory the agent works in, so notes about one project never leak into another; a temporary workspace gets no scope of its own, since no later session would ever return to read it.
+Each agent keeps long-term notes under `agent_state/memory/`, in two scopes. The user scope is read by every Session. Workspace scopes are tied to the directory the agent works in, so notes about one project never leak into another. A temporary Workspace gets no scope of its own, because no later Session would ever come back to read it.
-Only the `MEMORY.md` indexes enter the context, capped at 200 lines and 25,000 characters per scope with an explicit truncation note past the cap. Topic bodies stay on disk until the model opens them with the ordinary file tools. Writing works the same way: the model saves and merges its own notes through file edits, and the Harness confines those writes to the memory directories. No new tool was added for any of this.
+Only the `MEMORY.md` indexes enter the context, capped at 200 lines and 25,000 characters per scope, with an explicit truncation note past the cap. Topic files stay on disk until the model opens them with its ordinary file tools.
-Agent settings gain a Memory tab: every memory grouped by scope, with viewing, deletion (the index line is pruned in the same stroke) and editing through a prefilled chat with the agent itself. The two memory prompts are editable at the bottom of the tab. Agents created before Memory existed are untouched: a template without the `{{MEMORY}}` placeholder injects nothing, and the tab says so, offering a one-click insert.
+Writing works the same way. The model saves and merges its own notes by editing files, and the harness keeps those writes inside the memory directories. No new tool was added for any of this.
+
+Agent settings gain a **Memory** tab that lists every memory grouped by scope. You can view a memory, delete it (its index line is removed at the same time), or edit it through a prefilled chat with the agent itself. The two memory prompts are editable at the bottom of the tab.
+
+Agents created before Memory existed are unaffected: a template without the `{{MEMORY}}` placeholder injects nothing. The tab points this out and offers a one-click insert.
## MCP Servers
-Model Context Protocol support lands on the official TypeScript SDK v2, covering stdio, Streamable HTTP and legacy SSE transports. Server tools appear as `mcp__<server>__<tool>` under the existing execution and approval contract, with `readOnlyHint` mapping to read-only permission. Vault values never reach an MCP server process. An unreachable server is skipped with a warning rather than stalling session creation, and the connection wait streams into the chat as step rows instead of freezing the "new session" button.
+Agents can now use tools from MCP (Model Context Protocol) servers. Support is built on the official TypeScript SDK v2 and covers three transports: stdio, Streamable HTTP and legacy SSE.
+
+Server tools appear as `mcp__<server>__<tool>` and follow the existing execution and approval rules. A tool that the server marks with `readOnlyHint` gets read-only permission. Vault values never reach an MCP server process.
+
+The **MCP Servers** section of the agent's **Tools** tab, which used to show the configuration as read-only JSON, now manages servers with forms: add, edit and delete them, and test a connection on the spot. An unreachable server is skipped with a warning instead of stalling Session creation. While servers connect, the chat shows the progress as step rows instead of silently hanging on your first message.
+
+This is the release's one breaking change: the toolset record moves from `session_meta.tools` to a new `tool_list_ready` event. Traces written before the change no longer display their embedded tool record.
+
+## Prompt sections you can edit and switch off
+
+Memory's way of injecting its prompt now covers the three other subsystems that add text to the system prompt: Vault, Skills and Schedules. For these sections, the system-prompt template now holds only the placeholders `{{VAULT}}`, `{{SKILLS}}` and `{{SCHEDULES}}`. Each one expands to a prompt stored with the agent, which you can edit at the bottom of the matching tab, behind an enable switch at the top.
-Management is form-based: the agent settings page adds an MCP Server section with create, edit, delete and an on-the-spot connectivity test. The toolset record moves from `session_meta.tools` to a new `tool_list_ready` event — the one breaking change in this release. Traces written before the split no longer display their embedded tool record.
+The switch only controls what the model sees. Turning a section off removes it from the system prompt, but the feature keeps working: Vault values still reach shell subprocesses as environment variables, installed Skills can still be invoked explicitly, and scheduled tasks still fire on time.
-## Prompt injection: placeholders, switches, editable text
+### Schedule tasks from chat
-Memory's injection pattern now covers the other three prompt-borne subsystems. The system-prompt template carries only `{{VAULT}}`, `{{SKILLS}}` and `{{SCHEDULES}}` placeholders; each expands to a prompt stored with the agent, editable at the bottom of its tab, behind an enable switch at the top. The switch governs only what the model sees: turning a section off removes it from the system prompt while everything underneath keeps running, so Vault values reach shell subprocesses as environment variables and scheduled tasks fire on time whether or not the model is told about them.
+The default Schedules prompt is new. It teaches the model to manage the TOML files under `agent_state/schedule/` with its file tools. The prompt spells out the field rules, the five-minute minimum period, and that the server picks up changes within about thirty seconds, and it comes with the list of existing tasks. You can now ask for something like "run the test suite every morning at nine" in chat, and the model writes the file itself.
-The default Schedules prompt is new. It teaches the model to manage the TOML files under `agent_state/schedule/` with its file tools, spelling out the field rules, the five-minute floor on periods and the server's reconciliation within about thirty seconds, with the roster of existing tasks injected alongside. A request like "run the test suite every morning at nine" can now be made in chat, and the model writes the file itself.
+### Existing agents
-Existing agents baked the old template sections at creation, and those templates keep working as they are. Where the stock wording is intact, the tab offers a one-click migration to the placeholder form; hand-edited sections are left alone.
+Existing agents baked the old template sections in when they were created, and those templates keep working as they are. Where the stock wording is intact, the tab offers a one-click migration to the placeholder form. Hand-edited sections are left alone.
-## A kernel version for the config
+## A kernel version for agent configs
-`system_config.yaml` is frozen at agent creation and never upgraded behind the user's back. The behavior is predictable; the cost, until now, was that newer defaults only ever reached new agents. 0.2.2 stamps each config with a kernel version: a date recording which generation of built-in defaults it came from, written at creation and restore, untouched by ordinary edits.
+An agent's `system_config.yaml` is fixed when the agent is created and never upgraded behind your back. That keeps behavior predictable, but until now it also meant newer defaults only reached new agents.
-Bumping that date on any substantive defaults change is not left to discipline. A guard test pins the hash of every leaf default to the latest entry of a version history table, so a defaults change without a registered bump fails CI. On the overview, an Update control sits beside "restore defaults" and merges field by field: values still matching any recorded generation advance to the new default, customized values are kept and reported by readable names, and values of unknown origin are conservatively kept. Restore remains the full-refresh escape hatch.
+0.2.2 stamps each config with a kernel version: a date that records which generation of built-in defaults the config came from. Creating or restoring the config writes the stamp, and ordinary edits leave it alone. A guard test in CI fails whenever the defaults change without a new date, so the stamp cannot fall behind.
+
+On the agent overview, **Update kernel** now sits beside **Restore default configuration**. It merges field by field:
+
+- Values that still match any recorded generation move to the new default.
+- Customized values are kept and listed by readable names.
+- Values of unknown origin are kept, to be safe.
+
+**Restore default configuration** is still there when you want a full reset.
## Core runtime
-The default `max_turns` becomes -1, request caps and the compaction threshold now derive from the model's context window, and small-window vLLM-class deployments no longer need hand tuning. The LLM retry ladder starts at two seconds, and every failure short of a rejected credential is retried.
+The default `max_turns` is now -1, which means no turn limit. Request caps and the compaction threshold now derive from the model's context window, so small-window vLLM-class deployments no longer need hand tuning.
+
+The LLM retry ladder now starts at two seconds, and every failure except a rejected credential is retried.
-Trace appends are serialized, one `write(2)` per record, and resumption heals crash-torn tails, so a large record can no longer be split at the 512 KiB chunk boundary. The occasional trace corruption some users hit came from exactly that seam, and this release closes it.
+Trace appends are now serialized, with one `write(2)` per record, and resuming a Session repairs a tail torn by a crash. A large record can no longer be split at the 512 KiB chunk boundary, which is where the occasional Trace corruption some users saw came from.
-## Desktop and Web App
+## Desktop app and Web App
-The desktop app picks up penguin brand icons on every platform, system notifications on task completion, an explicit single-user mode, and a bundled `penguin` CLI on PATH. Administrators get a proxy options dialog: separate switches for the application and the agent environment sharing one proxy address, an empty address following the system proxy, loopback always exempt.
+The desktop app gets penguin brand icons on every platform, system notifications when a Task finishes, an explicit single-user mode, and a bundled `penguin` CLI on PATH.
-The Web App accumulated a month of fixes; the ones worth naming: header statistics fold into a details card with a click-to-copy session id and a background-process list whose Stop button works; typed-but-unsent text parks as sidebar drafts; the initial-password banner can be dismissed for good; the locked-model chip now just says "type /model to switch models"; detail tabs settle into Overview, System Prompt, Runtime, Tools, Skills, Memory, Vault, Schedules, with the list's stat icons in the same order; the overview becomes ruled sections with a copyable state path; the shared toggle switch loses the gray halo it kept after every click; and leaving a running conversation no longer flickers the whole app.
+Administrators get a **Proxy options** dialog. The application and the agent environment each have their own switch, and both use one shared proxy address. An empty address follows the system proxy, and loopback traffic always bypasses the proxy.
+
+The Web App collected a month of fixes. The ones worth naming:
+
+- Header statistics fold into a details card, with a click-to-copy Session id and a list of background processes whose **Stop** button works.
+- Starting a new chat with unsent text in the composer keeps that text as a draft in the sidebar.
+- The initial-password banner can be dismissed for good.
+- Clicking the locked-model chip now simply says **Type /model to switch models**.
+- Agent detail tabs settle into **Overview**, **System Prompt**, **Runtime**, **Tools**, **Skills**, **Memory**, **Vault** and **Schedules**, and the stat icons in the agent list follow the same order.
+- The agent overview is laid out as ruled sections, with a copyable state path.
+- The shared toggle switch no longer keeps a gray halo after a click.
+- Leaving a running conversation no longer makes the whole app flicker.
## Everything else
-The model catalog adds Thinking Machines Lab's Inkling on OpenRouter and Fireworks AI, and DeepSeek V4 Flash 0731 on Fireworks; GLM-5.1 gateway listings are delisted while Z.AI direct remains; OpenRouter prices are refreshed from the official API. The skill library gains `humanizer`, a manual-install skill that strips machine-writing tells from prose in any language — this post was drafted by its method. Workspace overrides force `@hono/node-server` to 2.0.5 or later (a path-traversal advisory in `serve-static` on Windows; the vulnerable copy came transitively from the MCP SDK) and `nanoid` to 3.3.17 or later, leaving `pnpm audit` with nothing to report. The release workflow now refuses a tag whose version disagrees with the repository. The full list is in [changelog/0.2.2](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.2).
+- The model catalog adds Thinking Machines Lab's Inkling on OpenRouter and Fireworks AI, and DeepSeek V4 Flash 0731 on Fireworks AI. The GLM-5.1 gateway listings are removed, while the Z.AI direct entry stays. OpenRouter prices are refreshed from its models API.
+- The Skill library adds `humanizer`, a Skill you install manually that strips machine-writing tells from prose in any language.
+- Dependency overrides force `@hono/node-server` to 2.0.5 or later, fixing a path-traversal advisory in `serve-static` on Windows that came in through the MCP SDK, and `nanoid` to 3.3.17 or later. `pnpm audit` now has nothing to report.
+- The release workflow refuses a tag whose version does not match the repository.
+
+The full list is in [changelog/0.2.2](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.2).
## Install or upgrade
-Desktop: grab your platform's installer at [penguin.ooo/download](https://penguin.ooo/download). As of this release the macOS builds are signed and notarized, so Gatekeeper opens them directly; Windows builds remain unsigned ("More info → Run anyway" past SmartScreen).
+Desktop app: download the installer for your platform at [penguin.ooo/download](https://penguin.ooo/download). Starting with this release, the macOS builds are signed and notarized, so Gatekeeper opens them directly. In this release, Windows builds are still unsigned: in SmartScreen, choose "More info → Run anyway".
CLI / server:
@@ -62,4 +102,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows (PowerShell): `irm https://penguin.ooo/install.ps1 | iex`; or with Node >= 24, `npm install -g @prismshadow/penguin-cli`. Existing installs: `penguin update`.
+On Windows, run `irm https://penguin.ooo/install.ps1 | iex` in PowerShell. With Node >= 24, you can also install with `npm install -g @prismshadow/penguin-cli`. On Linux and macOS, upgrade an existing install with `penguin update`.
diff --git a/packages/landing/content/blog/penguinharness-0-2-2.zh.md b/packages/landing/content/blog/penguinharness-0-2-2.zh.md
index f4b31c54..1399adc9 100644
--- a/packages/landing/content/blog/penguinharness-0-2-2.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-2.zh.md
@@ -1,59 +1,99 @@
---
-title: "PenguinHarness 0.2.2:Agent 有了记忆"
+title: "PenguinHarness 0.2.2:长期记忆与 MCP Server 支持"
date: 2026-08-11
category: news
-excerpt: 0.2.2 给 Agent 两样新能力:跨会话的长期记忆(用户与工作区两个作用域,索引进上下文、正文按需读取,设置页新增记忆标签页),以及三种传输方式的 MCP Server 支持。技能、密钥保险柜、定时任务改成与记忆同款的可编辑注入提示词加开关;agent 配置有了按日期记录的内核版本,「更新内核」能在保留自定义的前提下跟进新默认值。核心运行时修掉了轨迹写入被截断的老毛病,依赖审计清零。逐项看看。
+excerpt: 0.2.2 让 Agent 拥有跨会话的长期记忆,可以在「记忆」标签页里管理;同时支持通过三种传输方式接入 MCP Server。提示词区块可以编辑和关闭,Agent 配置有了内核版本,Trace 损坏的问题也已修复。
---
-PenguinHarness 0.2.2 发布了。前几版把 Agent 的手脚补齐——文件工具、子代理、技能、定时任务——这一版补的是记性:会话结束后,Agent 终于能把学到的东西留给下一次。配套的还有 MCP Server 支持、可开关的提示词注入,以及给配置本身加的版本机制。
+PenguinHarness 0.2.2 发布了。之前的版本为 Agent 配齐了干活的工具:文件工具、子 Agent、Skill 和定时任务。这个版本给它们加上了记忆:Agent 在一个会话里学到的东西,下一个会话还能接着用。这一版还加入了 MCP Server 支持、可编辑也可关闭的提示词区块,以及给 Agent 配置本身的版本标记。
## 记忆
-每个 Agent 在 `agent_state/memory/` 下维护自己的长期笔记,分两个作用域:用户作用域每个会话都读,工作区作用域跟着目录走——同一个 Agent 在不同项目里各记各的,临时工作区则只拿用户作用域,因为不会有下一个会话回来读它。
+每个 Agent 把长期笔记存在 `agent_state/memory/` 下,分两种作用域。用户作用域的内容,每个会话都会读取;Workspace 作用域绑定 Agent 工作的目录,关于某个项目的笔记不会混进另一个项目。临时 Workspace 没有自己的作用域,因为之后不会有会话回来读它。
-进入上下文的只有各作用域的 `MEMORY.md` 索引(每个作用域至多 200 行、25,000 字符,超出部分注明截断),正文文件由模型在需要时用普通文件工具打开。写入、去重、合并同样全靠文件工具完成:Harness 决定记忆放在哪里、把写入圈在里面,其余是模型自己的事,没有为此新增任何工具。
+只有 `MEMORY.md` 索引会进入上下文,每个作用域最多 200 行、25,000 字符,超出上限时会附上明确的截断说明。主题文件留在磁盘上,模型需要时再用普通的文件工具打开。
-设置页新增记忆标签页:按作用域分组列出全部记忆,可查看、删除(索引行同步清掉)、或经由一段预填的对话让 Agent 自己改写;两段记忆提示词也在这页直接编辑。记忆机制此前的 Agent 不受影响——模板里没有 `{{MEMORY}}` 占位符就什么都不注入,标签页会指出这一点,并提供一键插入。
+写入也是同样的方式。模型通过编辑文件来保存、合并自己的笔记,Harness 则把这些写入限制在记忆目录里。为此没有新增任何工具。
-## MCP Server 支持
+Agent 设置里多了一个**记忆**标签页,按作用域分组列出所有记忆。你可以查看某条记忆、删除它(对应的索引行会一并移除),也可以通过一段预填好的对话,让 Agent 自己来改。标签页底部还可以编辑两段记忆提示词。
-Model Context Protocol 落在官方 TypeScript SDK v2 上,stdio、Streamable HTTP、legacy SSE 三种传输都支持。服务器工具以 `mcp__<服务器>__<工具>` 的名字进入既有的执行与审批契约,`readOnlyHint` 映射为只读权限;密钥保险柜的值不会进入任何 MCP 服务器进程;连不上的服务器跳过并告警,不拖垮会话创建——连接过程以步骤行的形式流进对话,而不是让「新建会话」卡住等它。
+记忆功能推出之前创建的 Agent 不受影响:模板里没有 `{{MEMORY}}` 占位符,就不会注入任何内容。标签页会指出这一点,并提供一键插入。
-管理界面是表单式的:Agent 设置页新增 MCP Server 一节,可增删改配置并当场做连通性测试。工具清单从 `session_meta.tools` 移到了新的 `tool_list_ready` 事件——这是本版唯一的破坏性变更:拆分之前写下的轨迹文件不再显示其内嵌的工具记录。
+## MCP Server
-## 提示词注入:占位符、开关、可编辑文本
+Agent 现在可以使用 MCP(Model Context Protocol)服务器提供的工具。这项支持基于官方 TypeScript SDK v2,覆盖三种传输方式:stdio、Streamable HTTP 和旧式 SSE。
-记忆的注入模式被推广到了其余三个子系统。系统提示词模板里现在只放 `{{VAULT}}`、`{{SKILLS}}`、`{{SCHEDULES}}` 占位符,各自展开成一段随 Agent 保存、可在对应标签页下方直接编辑的提示词,页顶一个开关决定注入与否。关掉开关只影响模型看到什么——保险柜的值仍以环境变量注入子进程,已排期的任务、已装的技能也都照常工作,只是模型的系统提示词里不再出现那一段。
+服务器的工具以 `mcp__<server>__<tool>` 的名字出现,沿用现有的执行和审批规则。服务器用 `readOnlyHint` 标记的工具获得只读权限。密钥保险柜里的值永远不会传给 MCP 服务器进程。
-定时任务的默认提示词是新写的,它教模型用文件工具直接管理 `agent_state/schedule/` 下的 TOML——字段规则、五分钟的周期下限、服务端约三十秒内自动生效,都写在里面,当前任务清单也随提示词注入。也就是说,「每天早上九点跑一遍测试」这类要求,现在可以直接在对话里提,模型自己落文件。
+Agent 设置的**工具**标签页里,**MCP Server** 分区过去只以只读 JSON 展示配置,现在可以用表单管理服务器:添加、编辑、删除,还能当场测试连接。连不上的服务器会直接跳过并给出警告,不会卡住会话创建。服务器连接期间,对话里会以步骤行显示进度,你的第一条消息不会再无声无息地卡住。
-存量 Agent 的模板在创建时就物化了旧段落,这些模板原样可用;旧默认文字没被改过的,标签页提供一键迁移到占位符写法,改过的不动。
+这是本版唯一的破坏性变更:工具集记录从 `session_meta.tools` 移到了新的 `tool_list_ready` 事件。变更之前写下的 Trace 不再显示其中内嵌的工具记录。
-## 配置内核版本
+## 可编辑、可关闭的提示词区块
-`system_config.yaml` 在 Agent 创建时定格,从不自动升级——好处是行为可预期,代价是新默认值只属于新 Agent。0.2.2 给配置加了内核版本:一个日期,记录这份配置基于哪一代内置默认值,创建与还原时盖章,日常编辑不动它。
+记忆注入提示词的方式,现在也用到了另外三个会往系统提示词里加内容的子系统上:密钥保险柜、技能和定时任务。这三部分在系统提示词模板里只保留 `{{VAULT}}`、`{{SKILLS}}` 和 `{{SCHEDULES}}` 三个占位符。每个占位符展开为一段随 Agent 保存的提示词,可以在对应标签页的底部编辑,标签页顶部则有一个启用开关。
-日期的升级由一条守卫测试强制执行:它把全部默认值的哈希钉在版本历史表的最新条目上,改了默认值而不登记新条目,CI 直接变红。概览页在「还原为默认配置」旁边多了「更新内核」:逐字段比对历代默认值做合并——没改过的字段跟进新默认,改过的保留并按可读名称列出,认不出来历的一律保守保留。想全量刷新,旁边的还原按钮仍是兜底。
+开关只决定模型能看到什么。关掉某个区块,它就从系统提示词里消失,但功能照常运转:密钥保险柜的值仍以环境变量的形式传给 shell 子进程,已安装的 Skill 仍可显式调用,定时任务也照样准时触发。
+
+### 在对话里安排定时任务
+
+定时任务的默认提示词是新写的。它教模型用文件工具管理 `agent_state/schedule/` 下的 TOML 文件。提示词写明了字段规则、最短五分钟的周期、服务端大约三十秒内就会载入改动,还附上了现有任务的列表。现在你可以在对话里说一句「每天早上九点跑一遍测试套件」,模型会自己把文件写好。
+
+### 已有 Agent
+
+已有 Agent 在创建时就把旧模板的各个区块固化了进去,这些模板照旧可用。原版措辞没有改动过的,标签页提供一键迁移到占位符写法;手动改过的区块保持不动。
+
+## Agent 配置的内核版本
+
+Agent 的 `system_config.yaml` 在创建时就固定下来,绝不会在背后悄悄升级。这让行为可以预期,但在此之前,新的默认值也只有新 Agent 才用得上。
+
+0.2.2 给每份配置打上内核版本:一个日期,记录这份配置出自哪一代内置默认值。创建或还原配置时写入这个标记,日常编辑不会动它。CI 里有一个守卫测试,只要默认值变了而日期没有更新,测试就会失败,所以这个标记不会落后。
+
+Agent 概览页上,**更新内核**现在就在**还原为默认配置**旁边。它会逐个字段合并:
+
+- 仍与某一代已记录的默认值一致的字段,更新为新的默认值。
+- 自定义过的字段保留,并以可读的名称列出。
+- 来源不明的值稳妥起见也保留。
+
+想彻底重置时,**还原为默认配置**仍然可用。
## 核心运行时
-`max_turns` 默认值改为 -1(不限轮次),请求上限与压缩阈值改由模型的上下文窗口推导,小窗口的 vLLM 类部署不再需要手工调参。LLM 重试阶梯放缓到 2 秒起步,除凭证被拒外的失败全部纳入重试。
+`max_turns` 的默认值现在是 -1,即不限轮次。请求上限和压缩阈值改为根据模型的上下文窗口推算,小窗口的 vLLM 类部署不再需要手工调参。
+
+LLM 重试阶梯现在从 2 秒起步,除凭证验证失败外,所有失败都会重试。
-轨迹文件的写入串行化了,每条记录一次 `write(2)` 落盘,恢复会话时自动修复崩溃留下的残尾。此前偶发的轨迹损坏,来源正是大记录在 512 KiB 边界被劈开的那道缝,这一版把它补上了。
+Trace 的追加写入现在串行执行,每条记录一次 `write(2)`;恢复会话时,会修复崩溃时写坏的文件末尾。大记录不会再在 512 KiB 的分块边界处断成两截。部分用户偶尔遇到的 Trace 损坏,根源就在这里。
-## 桌面端与 Web 应用
+## 桌面应用与 Web App
-桌面端补上了各平台的品牌图标、任务完成的系统通知、显式的单用户模式,并随包携带 `penguin` CLI。管理员多了一个代理选项对话框:应用本身与 Agent 环境两个开关共用一个代理地址,留空跟随系统代理,回环地址始终豁免。
+桌面应用在各个平台都换上了企鹅品牌图标,Task 结束时会发出系统通知,有了明确的单用户模式,还自带可以在 PATH 中直接调用的 `penguin` CLI。
-Web 应用这一个月的积累不少,拣要紧的说。对话头部的统计并入详情卡,会话 id 点击即复制,后台进程列表带可用的停止按钮;输入未发的文字存为侧栏草稿。设置侧:初始密码横幅可以永久关闭,锁定模型的提示精简为「输入 /model 切换模型」,详情页标签定序为概览、系统提示词、运行参数、工具、技能、记忆、密钥保险柜、定时任务(列表统计图标同序),概览页改为横线分节、State 路径可复制,共享滑动开关也修掉了点击后残留的灰色光环。离开运行中的对话不再引发全应用闪烁。
+管理员多了一个**代理选项**对话框:应用和 Agent 环境各有自己的开关,共用同一个代理地址;地址留空时跟随系统代理,回环流量始终不走代理。
+
+Web App 积累了一个月的修复,值得一提的有:
+
+- 对话头部的统计收进一张详情卡片,会话 id 点击即可复制,卡片里还列出后台进程,每个进程的**停止**按钮都能正常使用。
+- 输入框里有没发出去的文字时新建对话,这段文字会以草稿的形式留在侧栏。
+- 初始密码横幅可以永久关闭。
+- 点击已锁定的模型标签,现在只提示**输入 /model 切换模型**。
+- Agent 详情页的标签顺序定为**概览**、**系统提示词**、**运行参数**、**工具**、**技能**、**记忆**、**密钥保险柜**和**定时任务**,Agent 列表里的统计图标也按同样的顺序排列。
+- Agent 概览页改为用分隔线分节的排版,Agent State 路径可以直接复制。
+- 共用的开关组件点击后不再残留灰色光晕。
+- 离开正在运行的对话时,整个应用不会再闪烁。
## 其余改进
-模型目录:Thinking Machines Lab 的 Inkling 上架 OpenRouter 与 Fireworks AI,Fireworks 新增 DeepSeek V4 Flash 0731,GLM-5.1 的网关条目下架(Z.AI 直连保留),OpenRouter 价格按官方 API 刷新。技能库新增 `humanizer`——中英等多语言通用的去 AI 味改写技能,手动安装;这篇发布文就是按它的方法写的。依赖侧以 workspace override 强制 `@hono/node-server` ≥ 2.0.5(Windows 下 serve-static 的路径穿越通告,旧副本来自 MCP SDK 的传递依赖)与 `nanoid` ≥ 3.3.17,`pnpm audit` 归零。发布工作流拒绝版本号与仓库不一致的 tag。完整清单见 [changelog/0.2.2](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.2)。
+- 模型目录新增 Thinking Machines Lab 的 Inkling(上架 OpenRouter 和 Fireworks AI),以及 Fireworks AI 上的 DeepSeek V4 Flash 0731。GLM-5.1 的网关条目已移除,Z.AI 直连条目保留。OpenRouter 的价格按它的 models API 重新刷新。
+- 技能库新增 `humanizer`:一个需要手动安装的 Skill,用来去除各种语言文字里的机器写作痕迹。
+- 依赖覆盖把 `@hono/node-server` 强制升到 2.0.5 或更高,以修复一则路径穿越安全通告:问题出在 Windows 上的 `serve-static`,有漏洞的版本经由 MCP SDK 间接引入。`nanoid` 也强制升到 3.3.17 或更高。现在 `pnpm audit` 没有任何需要报告的问题。
+- 发布工作流会拒绝版本号与仓库不一致的 tag。
+
+完整清单见 [changelog/0.2.2](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.2)。
## 安装或升级
-桌面端:前往 [penguin.ooo/download](https://penguin.ooo/download) 下载对应平台安装包。本版起 macOS 安装包已签名并公证,Gatekeeper 直接放行;Windows 构建仍未签名,SmartScreen 里选「更多信息 → 仍要运行」。
+桌面应用:到 [penguin.ooo/download](https://penguin.ooo/download) 下载对应平台的安装包。从这个版本起,macOS 安装包已签名并完成公证,Gatekeeper 会直接放行。这一版的 Windows 安装包仍未签名:在 SmartScreen 里选「更多信息 → 仍要运行」。
CLI / 服务端:
@@ -62,4 +102,4 @@ curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows(PowerShell):`irm https://penguin.ooo/install.ps1 | iex`;或在 Node >= 24 下 `npm install -g @prismshadow/penguin-cli`。已有安装直接 `penguin update`。
+Windows 上请在 PowerShell 中运行 `irm https://penguin.ooo/install.ps1 | iex`。Node >= 24 的环境也可以用 `npm install -g @prismshadow/penguin-cli` 安装。在 Linux 和 macOS 上升级已有安装,运行 `penguin update` 即可。
diff --git a/packages/landing/content/blog/penguinharness-0-2-3.en.md b/packages/landing/content/blog/penguinharness-0-2-3.en.md
index e7aa421f..d0b42d12 100644
--- a/packages/landing/content/blog/penguinharness-0-2-3.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-3.en.md
@@ -1,98 +1,95 @@
---
-title: "PenguinHarness 0.2.3: a better experience, and an agent you can watch work"
+title: "PenguinHarness 0.2.3: live Session status and a readable compaction record"
date: 2026-08-19
category: news
-excerpt: This release does two things — it makes what the agent is doing visible, and it files down the parts that were awkward to use. The sidebar now shows which conversation is running, context compaction went from a silent gap to a record you can open and read, any completed reply can fork into a new Session, and a queued message can be pulled back into the composer and edited before it goes out.
+excerpt: "Every sidebar row now shows live Session status, context compaction is a record you can open and read, any completed reply can fork into a new Session, and a queued message can be pulled back and edited."
---
-PenguinHarness 0.2.3 is out. It does two things. It makes what the agent is doing visible, and it files down the parts that were awkward to use.
+PenguinHarness 0.2.3 is out. This release makes an agent's work easier to follow and removes several points of friction. Session status in the sidebar is now live, context compaction is a record you can open and read, any completed reply can fork into a new Session, and a queued message can be pulled back into the composer and edited before it goes out.
-## The sidebar shows which conversation is running
+## The sidebar shows which Session is running
-Until now exactly one row in the sidebar was telling the truth, and that was the conversation you had open. Every other row showed whatever the last list fetch returned. Leave a running conversation and it kept claiming to run; start one in the background and its row never changed at all.
+Until now, only the conversation you had open showed its real status. Every other row showed whatever the last list fetch returned. A Session you left while it was running kept showing as running, and a Session started in the background never changed at all.
-Session status now rides the user-level event stream, so every row is live. A turning hourglass means running. A green dot means it finished and you have not looked at it since. Nothing at all means you have.
+Session status is now live in every row. A turning hourglass means the Session is running. A green dot means it finished and you have not looked at it yet. No marker means you have.
-![Three sidebar rows showing an unread green dot, no marker, and a running hourglass](/blog-assets/penguinharness-0-2-3-sidebar-status-en.png)
+![Sidebar with three Session rows: a green unread dot, no marker, and a running hourglass](/blog-assets/penguinharness-0-2-3-sidebar-status-en.png)
-There was a trap hiding under that. Whether a Session has ever run is a field on the server's list row, and the event only updated the status, not that field. So a Session running its very first task went blank the moment the hourglass stopped. The field now travels with the status, and a first run settles onto the dot like any other.
+First runs are covered too. When a Session's first Task finishes, its row settles on the green dot like any other, instead of going blank.
-## Compaction is no longer a gap
+## Compaction is a record you can open
-Context compaction used to be a blank stretch in the conversation. You knew it had happened. Now it is a row you can open, collapsed by default, the same way thinking is collapsed inside a task group.
+Context compaction used to be a blank stretch in the conversation. You could tell it had happened, but not what it kept. It is now a row you can open, collapsed by default, the same way thinking is collapsed inside a Task group.
-![A settled compaction row, collapsed](/blog-assets/penguinharness-0-2-3-compaction-collapsed-en.png)
+![A compaction row in the conversation, collapsed by default](/blog-assets/penguinharness-0-2-3-compaction-collapsed-en.png)
-The summary streams in as it is written, so you can expand it and read exactly what the agent decided to keep.
+The summary streams in as it is written, so you can expand the row and read exactly what the agent decided to keep.
![The expanded compaction summary, with task, confirmed findings, next steps and caveats](/blog-assets/penguinharness-0-2-3-compaction-expanded-en.png)
-The timing changed too. When compaction triggers after the model has produced a tool call, it now waits for the tools to finish and compacts with their results in hand, instead of folding an unfinished exchange into the request. Quit the client mid-compaction and that round is marked failed, with its half-written content discarded on load. A round that clears the context rather than summarizing it no longer calls itself compaction; it says Clear.
+The timing changed as well. When compaction triggers after the model has produced a tool call, it now waits for the tools to finish and compacts with their results in hand, instead of folding an unfinished exchange into the request. If you quit the client mid-compaction, that round is marked failed, and its half-written content is discarded on load. A round that clears the context instead of summarizing it is no longer called compaction. It is labeled Clear.
-One recurring complaint is fixed as well. After restarting the client, a conversation full of history would still refuse to compact, reporting that there was nothing to compact. The engine object is built lazily, and while resumption did replay the turn count into the initial state, that value only takes effect in the engine's constructor, which had not run yet. The server's three different 409 reasons also became three distinct error codes, so a Chinese UI now shows a Chinese message instead of falling back to the English prose.
+One recurring complaint is fixed. After a client restart, a conversation full of history used to refuse to compact, reporting that there was nothing to compact. It now compacts as expected. The server's three reasons for refusing a compaction also have their own error codes now, so the Chinese UI shows a Chinese message instead of English text.
## Any reply can fork into a new Session
-When a conversation goes sideways you used to have two options, live with it or start over. Every completed reply now carries a fork control, sitting next to copy.
+When a conversation went sideways, you used to have two options: live with it or start over. Every completed reply now carries a fork control, next to copy.
-![The reply action row, with fork beside copy](/blog-assets/penguinharness-0-2-3-session-fork-actions-en.png)
+![A completed reply's action row, with the fork control next to copy](/blog-assets/penguinharness-0-2-3-session-fork-actions-en.png)
-It asks first. On confirm it copies the conversation up to that reply into a new Session and leaves the original alone.
+Forking asks first. When you confirm, the conversation up to that reply is copied into a new Session, and the original is left alone.
![The confirmation dialog shown before forking](/blog-assets/penguinharness-0-2-3-session-fork-confirm-en.png)
## A queued message can be pulled back
-Steering typed mid-run, and follow-ups waiting their turn, used to be gone the moment you sent them. Each now carries a curved-back arrow. Click it and the message returns to the composer, where you can edit it and send it again.
+Steering you typed mid-run and follow-ups waiting their turn used to be out of reach the moment you sent them. Each now carries a curved-back arrow. Click it, and the message returns to the composer, where you can edit it and send it again.
-Recall and the engine's own dequeue are mutually exclusive, so a message is never both delivered and withdrawn. If the engine takes it in the same instant you click, you get a clear message saying so rather than a silent disappearance or a double send.
+A message is never both delivered and recalled. If the engine takes it in the same instant you click, you get a clear message saying so, rather than a silent disappearance or a double send.
## Thinking levels
-AgentHub 0.4.4 added a `max` tier, so the ladder is now low, medium, high, xhigh, max.
+AgentHub 0.4.4 added a `max` tier, so the ladder is now low, medium, high, xhigh, max. In the Chinese UI, the button shows only the Chinese name, and the menu adds the English value.
![The thinking-level dropdown](/blog-assets/penguinharness-0-2-3-thinking-level-menu-en.png)
-Changing the level mid-conversation now asks first. Some providers implement thinking levels by injecting a different prompt prefix at the very front of the request, so switching part-way through invalidates the prefix cache over the whole history and the next request re-bills all of it at the uncached rate. The dialog offers three ways out: compact first and then switch, switch anyway, or cancel.
+Changing the level mid-conversation now asks first. Some providers implement thinking levels by putting a different prompt prefix at the very front of the request. Switching part-way through then invalidates the prefix cache for the whole history, and the next request bills all of it again at the uncached rate. The dialog offers three ways out: compact first and then switch, switch anyway, or cancel.
-![The confirmation shown when switching thinking level mid-conversation](/blog-assets/penguinharness-0-2-3-thinking-level-switch-guard-en.png)
+![The confirmation shown when switching the thinking level mid-conversation](/blog-assets/penguinharness-0-2-3-thinking-level-switch-guard-en.png)
The level you pick is stored on the Session, so it survives a refresh and shows up in a second tab.
## Adding a custom model no longer means guessing the protocol
-Since 0.4.2 AgentHub has carried three generic protocol clients — OpenAI Responses, Anthropic Messages, and OpenAI Chat Completions. You no longer have to work out which one your endpoint speaks. The detect action probes them in that order and takes the first that answers in its shape, then fills the protocol picker in for you. With no key typed it falls back to the environment variable, and when nothing matches you get one short message telling you to check the API key and the base URL.
+Since 0.4.2, AgentHub has carried three generic protocol clients: OpenAI Responses, Anthropic Messages and OpenAI Chat Completions. You no longer have to work out which one your endpoint speaks. The detect action probes them in that order, takes the first that answers in its expected shape, and fills in the protocol picker for you. With no key typed, it falls back to the environment variable. When nothing matches, you get one short message asking you to check the API key and the base URL.
![The detect action at the top right of the base URL field, and the in-field picker listing the three protocols with the path each appends](/blog-assets/penguinharness-0-2-3-model-add-protocol-en.png)
-Vision support can be detected the same way. It sends a 1×1 image; a normal answer turns the setting on, an explicit image-related rejection turns it off, and anything else leaves your setting alone. That probe costs a real API call, so it only runs when you ask for it and never on save.
+Vision support can be detected the same way. The probe sends a 1×1 image. A normal answer turns the setting on, an explicit image-related rejection turns it off, and anything else leaves your setting alone. The probe costs a real API call, so it runs only when you ask for it, never on save.
-Models that can serve fast mode gained a toggle, default off. Models that cannot do not show the toggle at all, so you cannot arm a switch that would fail every turn. Turning it on says plainly that fast mode bills at premium rates.
+Models that can serve fast mode gained a toggle, off by default. Models that cannot do not show the toggle at all, so you cannot turn on a switch that would fail every turn. Turning it on tells you plainly that fast mode bills at premium rates.
## Also in this release
-The sidebar row's hover actions went back to archive and delete, with the full set moved to the right-click menu. Attachments and images can be dragged onto the chat area to upload, and a file attachment can now be 100MB rather than 10MB, with an admin able to change that from the user menu. Inline images keep a separate 20MB cap, because their bytes enter the conversation and the Trace, which is re-read whole on every history page; a file attachment is opened by path, so its size never reaches the context. The CLI gained `/thinking` and `--thinking`, and long tool output now collapses to its first and last lines with `/verbose` to see all of it — the model and the Trace always received the full text either way.
-
-The model catalog was refreshed: Gemini 3.7, GLM-5.3 and the GPT-5.6 family, plus their OpenRouter counterparts, with the nine `openai/*` rows pinned to the Responses protocol. DeepSeek pricing follows the current official rates, and the delisted `ling-3.0-flash` row is gone.
-
-One fix underneath is worth calling out. Gateways such as one-api and OpenRouter inject heartbeat events into a streaming response during a long generation. Those events used to reach the unknown-event guard and kill the stream, the harness classified that as a retryable failure, and the retry hit the next heartbeat — a long generation through such a gateway reconnected until it gave up. Every streaming client in AgentHub 0.4.3 and later skips them.
-
-## From running to legible
-
-These changes land on the same point. While an agent works you should be able to see what it is doing, what it chose to remember, and what the next step will cost. Session status, the compaction record, and the warning before a level switch all move something out of the logs and onto the screen.
+- The hover actions on a sidebar row are back to archive and delete. The full set is in the right-click menu.
+- You can drag attachments and images onto the chat area to upload them. A file attachment can now be 100MB instead of 10MB, and an admin can change that limit from the user menu.
+- Inline images have their own 20MB cap. Their bytes enter the conversation and the Trace, which is re-read whole on every history page. A file attachment is opened by path, so its size never reaches the context.
+- The CLI gained `/thinking` and `--thinking`. Long tool output now collapses to its first and last lines, and `/verbose` shows all of it. The model and the Trace always receive the full text either way.
+- The model catalog was refreshed with Gemini 3.7, GLM-5.3 and the GPT-5.6 family, plus their OpenRouter counterparts. The nine `openai/*` rows are pinned to the Responses protocol. DeepSeek pricing follows the current official rates, and the delisted `ling-3.0-flash` row is gone.
+- A long generation through a gateway such as one-api or OpenRouter no longer reconnects until it gives up. These gateways inject heartbeat events into a streaming response. The events used to kill the stream, the harness retried, and the retry hit the next heartbeat. Every streaming client in AgentHub 0.4.3 and later skips them.
## Install and upgrade
-Desktop builds are on the site for every platform. Windows builds are signed as of this release; macOS has been signed and notarized since 0.2.2.
+Desktop builds for every platform are on the site. Windows builds are signed as of this release, and macOS builds have been signed and notarized since 0.2.2.
-Linux and macOS install from the command line.
+On Linux and macOS, install from the command line:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows uses PowerShell.
+On Windows, use PowerShell:
```powershell
irm https://penguin.ooo/install.ps1 | iex
diff --git a/packages/landing/content/blog/penguinharness-0-2-3.zh.md b/packages/landing/content/blog/penguinharness-0-2-3.zh.md
index 0e04ef91..e21f8c58 100644
--- a/packages/landing/content/blog/penguinharness-0-2-3.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-3.zh.md
@@ -1,102 +1,99 @@
---
-title: "PenguinHarness 0.2.3:更好的用户体验,更透明的 Agent 运行"
+title: "PenguinHarness 0.2.3:实时的会话状态,可以展开阅读的压缩记录"
date: 2026-08-19
category: news
-excerpt: 这一版集中在两件事上,一是让 Agent 正在做什么变得看得见,二是把用起来别扭的地方磨掉。侧栏能实时看出哪个会话在跑,上下文压缩从一段空白变成可以展开读的记录,任何一条回复都能分叉出新会话,排队的消息可以撤回来改了再发。
+excerpt: "侧栏的每一行都能实时显示会话状态,上下文压缩变成一条可以展开阅读的记录,任何一条已完成的回复都能分叉出新会话,排队中的消息也可以撤回来改了再发。"
---
-我们发布了 PenguinHarness 0.2.3。这一版集中在两件事上,一是让 Agent 正在做什么变得看得见,二是把用起来别扭的地方磨掉。
+PenguinHarness 0.2.3 发布了。这一版让 Agent 的工作过程更容易看清,也磨掉了几处用着别扭的地方。侧栏的会话状态现在是实时的,上下文压缩变成一条可以展开阅读的记录,任何一条已完成的回复都能分叉出新会话,排队中的消息也可以撤回输入框,改完再发。
-## 侧栏能看出哪个会话在跑
+## 侧栏能看出哪个会话在运行
-以前侧栏里只有一行的状态是准的,就是你当前打开的那个会话。其余每一行显示的都是上次拉取列表时的快照。你离开一个正在跑的会话,它会一直显示成在跑;而在后台开始跑的会话,那一行根本不会变。
+以前,只有你当前打开的那个会话显示的是真实状态,其余各行显示的都是上次拉取列表时的结果。你离开时还在运行的会话,会一直显示为运行中;在后台启动的会话,那一行则始终不变。
-现在会话状态走用户级的事件流推送,每一行都是实时的。运行中是一个转动的沙漏,跑完了而你还没看过是一个绿点,看过之后就什么都不显示。
+现在每一行的状态都是实时的。转动的沙漏表示正在运行,绿点表示已经结束而你还没看过,什么标记都没有就是你已经看过了。
-![侧栏的三个会话,分别显示未读绿点、无标记和运行中的沙漏](/blog-assets/penguinharness-0-2-3-sidebar-status-zh.png)
+![侧栏里的三个会话,分别显示未读绿点、无标记和运行中的沙漏](/blog-assets/penguinharness-0-2-3-sidebar-status-zh.png)
-这里有个不显眼的坑。会话是否"跑过"是服务端列表行上的一个字段,而事件只更新状态,不更新它。所以一个第一次跑任务的新会话,沙漏一停就会什么都不显示。现在这个字段跟着状态一起推送,第一次跑完也能正常落到绿点上。
+第一次运行的情况也顾及到了。会话的第一个 Task 结束后,这一行和其他情况一样停在绿点上,不会变成空白。
-## 压缩不再是一段空白
+## 压缩变成一条可以展开的记录
-上下文压缩以前是会话里的一段空白,你只知道它发生过。现在它是一行可以展开的记录,默认折叠,和任务组里的思考一样。
+上下文压缩以前是对话里的一段空白,你能看出它发生过,却不知道它保留了什么。现在它是一行可以展开的记录,默认折叠,和 Task 分组里的思考内容一样。
-![折叠状态的压缩行](/blog-assets/penguinharness-0-2-3-compaction-collapsed-zh.png)
+![对话中的压缩行,默认折叠](/blog-assets/penguinharness-0-2-3-compaction-collapsed-zh.png)
-摘要在生成的时候就流式写进去,展开就能看到 Agent 到底保留了什么。
+摘要边生成边显示。展开这一行,就能看到 Agent 究竟决定保留哪些内容。
![展开后的压缩摘要,包含任务、已确认的结论、下一步和注意事项](/blog-assets/penguinharness-0-2-3-compaction-expanded-zh.png)
-压缩的时机也改了。模型产生工具调用之后触发的压缩,现在会等工具执行完,带着工具返回一起压,而不是把一次没结束的交换塞进去。压缩到一半你退出程序,那一次会被标记为失败,重新加载时直接丢掉写了半截的内容。清空上下文这种模式不再顶着"压缩"两个字,它现在就叫清空。
+压缩的时机也变了。如果压缩在模型发出工具调用之后触发,现在会等工具执行完,带着工具结果一起压缩,不再把一次没有结束的交互塞进请求。压缩进行到一半时退出客户端,这一轮会标记为失败,写了一半的内容在下次加载时丢弃。如果这一轮是清空上下文而不是生成摘要,它不再叫压缩,而是标为「清空」。
-还修掉一个反复有人碰到的问题。客户端重启之后,明明满屏都是历史,压缩却报"当前上下文没有可压缩的内容"。原因是引擎对象是惰性构造的,会话从磁盘恢复时轮次数确实回填进了初始状态,但那个值只在引擎的构造函数里才会生效,而这时候引擎还没被造出来。顺带把服务端这类 409 拆成了三个错误码,中文界面下报错也是中文了。
+还修复了一个反复有人反馈的问题。以前重启客户端之后,会话里明明有大量历史,压缩却报没有可压缩的内容;现在可以正常压缩。服务端拒绝压缩的三种原因也各自有了错误码,中文界面会显示中文提示,不再是英文。
## 任何一条回复都能分叉出新会话
-对话跑歪了,以前要么继续将就,要么从头开一个。现在每条已完成的回复右边都有一个分叉按钮,就在复制旁边。
+对话跑偏了,以前只有两个选择:将就着继续,或者从头再来。现在每条已完成的回复都带一个分叉按钮,就在复制按钮旁边。
-![回复下方的操作行,分叉按钮在复制右边](/blog-assets/penguinharness-0-2-3-session-fork-actions-zh.png)
+![已完成回复下方的操作行,分叉按钮在复制按钮旁边](/blog-assets/penguinharness-0-2-3-session-fork-actions-zh.png)
-点它会先问一句,确认之后把这条回复之前的对话原样复制成一个新会话,原来那个不动。
+分叉前会先确认。确认后,到这条回复为止的对话会复制成一个新会话,原会话保持不动。
-![分叉前的确认弹窗](/blog-assets/penguinharness-0-2-3-session-fork-confirm-zh.png)
+![分叉前弹出的确认框](/blog-assets/penguinharness-0-2-3-session-fork-confirm-zh.png)
-## 排队的消息可以撤回来改
+## 排队中的消息可以撤回
-任务跑着的时候插的话、排在后面的追问,以前发出去就收不回来了。现在它们旁边有一个回弯的箭头,点一下消息回到输入框,改完再发。
+运行中途发出的插话,以及排队等待的跟进消息,以前一发出去就收不回来。现在它们旁边都有一个回弯箭头。点一下,消息就回到输入框,改完可以重新发送。
-撤回和引擎取用之间是互斥的,同一条消息不会既被送出去又被撤回来。如果引擎刚好在那一瞬间把它取走了,你会看到一条明确的提示,而不是消息悄悄消失或者发两遍。
+一条消息不会既送达、又撤回。如果引擎恰好在你点击的那一刻取走了这条消息,你会看到一条明确的提示,不会出现消息悄悄消失或者重复发送。
## 思考等级
-AgentHub 升到 0.4.4 之后多了一档 max,梯度现在是低、中、高、极高、最高。按钮上只写中文,下拉里带上英文的原始值。
+AgentHub 0.4.4 新增了 `max` 一档,梯度现在是低、中、高、极高、最高(low、medium、high、xhigh、max)。中文界面的按钮上只显示中文,下拉菜单里还会附上英文原值。
![思考等级的下拉菜单](/blog-assets/penguinharness-0-2-3-thinking-level-menu-zh.png)
-会话中途换等级会先弹一个框。有些模型服务商是靠在提示词最前面注入不同前缀来实现思考等级的,中途一换,整段历史的前缀缓存就失效了,下一次请求要按未缓存的价格重新计一遍。所以这个框给三个选择,先压缩再切换、直接切换、取消。
+在对话中途切换等级,现在会先弹出确认框。有些供应商实现思考等级的方式,是在请求的最前面放一段不同的提示词前缀。中途一换,整段历史的前缀缓存就会失效,下一次请求要把全部历史按未缓存的价格重新计费。确认框提供三个选择:「压缩后切换」「仍要切换」和「取消」。
-![中途切换思考等级时的确认框](/blog-assets/penguinharness-0-2-3-thinking-level-switch-guard-zh.png)
+![对话中途切换思考等级时的确认框](/blog-assets/penguinharness-0-2-3-thinking-level-switch-guard-zh.png)
-换完的等级会存在会话上,刷新页面、换个标签页都还在。
+选好的等级保存在会话上,刷新页面后仍然有效,在另一个标签页里也能看到。
-## 加自定义模型不用再猜接口
+## 添加自定义模型,不用再猜协议
-AgentHub 0.4.2 之后有三种通用协议客户端,OpenAI Responses、Anthropic Messages 和 OpenAI Chat Completions。填自定义 base URL 的时候,你现在不用自己判断对方是哪一种。检测按钮会按 Responses、Messages、Chat Completions 的顺序去探,第一个能对上的就是它,结果直接填进协议选择器里。没填 key 的时候会回退到环境变量,探不出来就弹一句提示让你查 key 和地址。
+从 0.4.2 起,AgentHub 就带有三个通用协议客户端:OpenAI Responses、Anthropic Messages 和 OpenAI Chat Completions。你的端点用的是哪一种,现在不用自己判断了。「检测协议」按钮会按这个顺序逐个探测,第一个按预期格式应答的就是结果,并自动填进协议选择器。没有填 key 时,会改用环境变量里的 key;一个都对不上时,会弹出一句简短的提示,请你检查 API key 和 base URL。
-![base URL 输入框右上角的检测协议按钮,以及框内列出三种协议和各自端点路径的选择器](/blog-assets/penguinharness-0-2-3-model-add-protocol-zh.png)
+![base URL 输入框右上角的检测按钮,以及框内的选择器,列出三种协议和各自追加的路径](/blog-assets/penguinharness-0-2-3-model-add-protocol-zh.png)
-视觉能力也能探。它会发一张 1x1 的图过去,正常应答就打开,模型明确拒绝图片就关掉,其他情况一律不动你的设置。这个探测会真实产生一次调用费用,所以只在你点的时候跑,保存模型的时候不会偷偷跑。
+视觉能力也能用同样的方式检测。探测会发送一张 1×1 的图片:正常应答就打开视觉设置,明确拒绝图片就关闭,其他情况一律保持你原来的设置。每次探测都是一次真实的 API 调用,所以只在你手动点击时运行,保存模型时不会运行。
-支持 fast mode 的模型多了一个开关,默认关。不支持的模型上根本不显示这个开关,免得你打开之后每一轮都报错。打开的时候会提示一句,fast mode 是溢价计费的。
+支持快速模式的模型多了一个开关,默认关闭。不支持的模型不会显示这个开关,免得你打开一个每一轮都会失败的选项。打开时会明确提示:快速模式按溢价费率计费。
-## 还有一些
+## 这一版还有
-会话列表的悬停操作改回了归档和删除,右键菜单里是完整的那一套。附件和图片可以直接拖到聊天区域上传,单个文件的上限从 10MB 放宽到 100MB,管理员可以在用户菜单里改这个数。内联图片是例外,单独限在 20MB,因为图片的字节会进对话正文和轨迹文件,而轨迹每次翻历史都要整个读一遍;文件附件不受这个约束,模型是按路径去打开它的。CLI 加了 `/thinking` 和 `--thinking`,长工具输出默认折叠成首尾几行,`/verbose` 展开,模型和轨迹拿到的一直是完整内容。
-
-模型目录这一版也刷了一遍。新增 Gemini 3.7、GLM-5.3、GPT-5.6 系列,以及它们在 OpenRouter 上的对应条目,其中 OpenAI 那九行走 Responses 协议。DeepSeek 的价格按官网最新的改过了,下架的 ling-3.0-flash 移除。
-
-底层还有一个值得说的修复。经过 one-api、OpenRouter 这类网关的长时间生成,网关会往流里塞心跳事件,而这些事件以前会被当成未知输出直接让整条流失败,harness 又把它判成可重试,重试再撞上下一个心跳,表现出来就是没完没了的"正在重连"。AgentHub 0.4.3 起所有流式客户端都会跳过这些心跳。
-
-## 从跑得动到看得懂
-
-前面这些改动落在同一件事上。Agent 干活的时候,你应该知道它在干什么、它把什么记住了、它下一步要花多少钱。会话状态、压缩记录、切换等级前的提示,都是把原本只有日志里才有的东西搬到界面上。
+- 侧栏会话行的悬停操作改回了归档和删除,完整的操作都在右键菜单里。
+- 附件和图片可以直接拖到聊天区域上传。单个文件附件的上限从 10MB 提高到 100MB,管理员可以在用户菜单里修改这个上限。
+- 内联图片另有 20MB 的上限。内联图片的字节会进入对话和 Trace,而每翻一页历史,都要把 Trace 整个重读一遍。文件附件按路径打开,大小不会影响上下文。
+- CLI 新增了 `/thinking` 和 `--thinking`。较长的工具输出现在只显示开头和结尾几行,用 `/verbose` 可以看到全部。无论是否折叠,模型和 Trace 拿到的始终是完整内容。
+- 模型目录更新了一轮,新增 Gemini 3.7、GLM-5.3 和 GPT-5.6 系列,以及它们在 OpenRouter 上的对应条目。九个 `openai/*` 条目固定使用 Responses 协议。DeepSeek 的价格按当前官方价格更新,已下架的 `ling-3.0-flash` 已移除。
+- 经过 one-api、OpenRouter 这类网关的长时间生成,不会再反复重连直到放弃。这类网关会往流式响应里插入心跳事件,这些事件以前会让整条流中断,Harness 随即重试,重试又撞上下一个心跳。AgentHub 0.4.3 及之后版本的所有流式客户端都会跳过这些事件。
## 安装与升级
-桌面端到官网下载对应平台的安装包。这一版开始 Windows 构建也带签名了,macOS 从 0.2.2 起就已经签名并公证。
+各平台的桌面安装包都可以在官网下载。从这一版开始,Windows 安装包带有签名;macOS 安装包从 0.2.2 起就已经签名并通过公证。
-Linux 和 macOS 用命令行装。
+Linux 和 macOS 用命令行安装:
```sh
curl -fsSL https://penguin.ooo/install.sh | sh
penguin web
```
-Windows 用 PowerShell。
+Windows 用 PowerShell 安装:
```powershell
irm https://penguin.ooo/install.ps1 | iex
penguin web
```
-完整的改动记录在 [changelog/0.2.3/](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.3)。
+完整的改动记录见 [changelog/0.2.3/](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.3)。
diff --git a/packages/landing/content/blog/penguinharness-0-2-4.en.md b/packages/landing/content/blog/penguinharness-0-2-4.en.md
index 79c0301c..461ba3e9 100644
--- a/packages/landing/content/blog/penguinharness-0-2-4.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-4.en.md
@@ -1,86 +1,90 @@
---
-title: "PenguinHarness 0.2.4: a DeepSeek vision model, a more flexible workspace, and a clearer cost center"
+title: "PenguinHarness 0.2.4: a DeepSeek vision model, dockable panels, and a rebuilt cost center"
date: 2026-08-21
category: news
-excerpt: DeepSeek gained a vision model and moved onto the Responses protocol. The chat page's side panels and terminals became tabs in two docks you arrange yourself. Long-running commands go to the background and report back when they finish. And the cost center was rebuilt around one time axis, so every chart on the page answers the same question about the same window.
+excerpt: DeepSeek gains a vision model and moves to the Responses protocol. The chat page's panels and terminals are now tabs in two docks, long commands run in the background, and the cost center is rebuilt around a single time range.
---
-PenguinHarness 0.2.4 is out. Three things carry this release: a DeepSeek model that reads images, a workspace whose panels you arrange instead of putting up with, and a cost center that finally reads as one page rather than four unrelated widgets.
+PenguinHarness 0.2.4 is out. It adds a DeepSeek model that reads images, turns the chat page's side panels and terminals into tabs in two docks you arrange, moves long-running commands to the background, and rebuilds the cost center around a single time range. Five changes need a decision from you when you upgrade; they are listed under Upgrading at the end of this post.
-## A DeepSeek model that can see
+## DeepSeek gains a vision model
AgentHub 0.4.6 brings `deepseek-v4-flash-vision-exp` into the catalog. It adds image input on top of V4 Flash's text capabilities, keeps the 1M context window, and bills at V4 Flash's own price.
![The DeepSeek model group, with the Vision badge on deepseek-v4-flash-vision-exp](/blog-assets/penguinharness-0-2-4-deepseek-vision-model-en.png)
-It is the only vision-capable model in that group, and that changes how a session handles an image. A text-only model routes pictures through the `vision_model` proxy, which describes them with `describe_image` and hands the agent a paragraph of text. A session running the vision model reads the image itself — no proxy, no description in between.
+It is the only vision-capable model in the DeepSeek group, and that changes how a Session handles an image. A text-only model routes pictures through the `vision_model` proxy, which describes each one with `describe_image` and hands the agent a paragraph of text. A Session running the vision model reads the image itself, with no proxy and no description in between.
-The model is also on OpenRouter at that gateway's published rates. Both rows record DeepSeek's **off-peak** tier, the same convention the existing rows follow: Beijing 9:00–12:00 and 14:00–18:00 bill exactly double, and the cost center uses one rate, so peak usage is under-counted by half.
+The model is also on OpenRouter at that gateway's published rates. Both rows record DeepSeek's off-peak tier, the same convention the existing rows follow. Usage between 9:00–12:00 and 14:00–18:00 Beijing time bills at exactly double, and the cost center applies one rate, so it under-counts peak usage by half.
-The same release moves the first-party DeepSeek client from Chat Completions to the OpenAI Responses API, which the base-URL hint now reflects.
+The same release moves the first-party DeepSeek client from Chat Completions to the OpenAI Responses API, and the base URL hint in the model dialog now shows it.
![The model dialog's base URL field, its protocol hint reading /responses](/blog-assets/penguinharness-0-2-4-model-protocol-hint-en.png)
-That is a breaking change if you point a `deepseek-v4*` entry at something other than DeepSeek's own endpoint — see [Upgrading](#upgrading) below.
+This is a breaking change if a `deepseek-v4*` entry points at anything other than DeepSeek's own endpoint. See Upgrading at the end of this post for what to do.
-Elsewhere in the catalog: `claude-opus-5` joined the direct Anthropic group, the add-group dialog can import an endpoint's whole model listing instead of making you type ids one at a time, and a model whose key comes from an environment variable is finally counted as configured — it no longer hides behind the "show models without key" filter, and the credential guide stops nagging about it.
+Elsewhere in the catalog:
-## The workspace is something you arrange
+- `claude-opus-5` joined the direct Anthropic group.
+- The add-group dialog can import an endpoint's whole model listing, so you no longer type ids one at a time.
+- A model whose key comes from an environment variable now counts as configured. It no longer hides behind the **Show models without a key** filter, and the credential guide stops flagging it.
-The chat page used to have drawer-style side panels and a separate terminal pane system, each with its own rules. Both are gone. Every side element — the subagents panel, the Workspace files panel, Memory, the new Trace panel, and any number of terminals — is now a closable tab in one of two docks, one on the right and one along the bottom.
+## Side panels and terminals are now dock tabs
+
+The chat page's drawer-style side panels and its separate terminal pane system are gone. Every side element is now a closable tab in one of two docks, one on the right and one along the bottom. That covers the subagents panel, the Workspace files panel, Memory, the new Trace panel and any number of terminals.
![The chat page with the right dock showing Agents, Memory and Workspace tabs, and a terminal in the bottom dock](/blog-assets/penguinharness-0-2-4-dock-tabs-en.png)
-Anything can go in either dock. Drag a tab across, split your attention how the task actually needs it, and the arrangement stays with the conversation.
+Any tab can go in either dock. Drag tabs where the task needs them, and the arrangement stays with the conversation.
Terminals are real server-side shells, and they live in the same tab strip as everything else.
![A live terminal in the bottom dock, showing git log output](/blog-assets/penguinharness-0-2-4-dock-terminal-en.png)
-## Long commands stop blocking the conversation
+## Long commands no longer block the conversation
-A command that takes minutes no longer holds the turn. It goes to the background, the agent carries on, and the harness injects a completion report when it finishes — so the model learns the outcome without polling for it. There are kill tools for stopping one, and a process that opens a port gets a link straight to it.
+A command that takes minutes no longer holds up the turn. It goes to the background and the agent carries on. When the command finishes, the harness injects a completion report, so the model learns the outcome without polling for it. The agent has kill tools to stop a background command, and a process that opens a port gets a link straight to it.
![A background process row, with its command, pid, a localhost link and a Stop control](/blog-assets/penguinharness-0-2-4-background-process-en.png)
-Alongside it, a Project-level **sandbox command policy**: regex rules that refuse a shell command before it runs, checked against both shell entry points, and applied whatever the approval mode would otherwise allow. It is a guardrail against accidents rather than a security boundary — a command assembled at run time can still slip past a pattern.
+## A command policy for shell commands
+
+Each Project now has a sandbox command policy: regex rules that refuse a shell command before it runs. The rules are checked at both shell entry points and apply whatever the approval mode would otherwise allow. New and existing Projects start with a small default set that refuses destructive commands such as `rm -rf`, even in allow-all mode. You can edit or disable a rule, or the whole policy, under **Project settings** › **Security policy**.
-## The cost center reads as one page
+The policy is a guardrail against accidents, not a security boundary. A command assembled at run time can still slip past a pattern.
-The usage page was four widgets answering four different questions over four different windows. It is now one time axis that every chart draws over.
+## The cost center is built around one time range
+
+The usage page used to be four widgets answering four different questions over four different windows. Every chart on it now draws over one time axis.
![The cost center: range preset, and the Token chart with its cache hit rate line](/blog-assets/penguinharness-0-2-4-usage-range-en.png)
-You pick a range — trailing last hour or last 24 hours, calendar 7 / 30 / 90 days, or a custom pair of dates — and the range alone decides the precision: per minute, hourly, daily, weekly or monthly. There is no second control to keep in step with the first.
+You pick a range: the trailing hour or 24 hours, the last 7, 30 or 90 calendar days, or a custom pair of dates. The range alone decides the precision, which is per minute, hourly, daily, weekly or monthly. There is no second control to keep in step with the first.
-The share pie and the per-model progress bars are replaced by two charts, side by side, one broken down by Agent and one by Model. Each bucket's requests are a stacked bar against the left axis; each entity's success rate is a dashed line against the right-hand percentage axis, in the same hue.
+Two charts, side by side, replace the share pie and the per-model progress bars. One breaks usage down by agent and the other by model. In each chart, a bucket's requests are a stacked bar against the left axis, and each entity's success rate is a dashed line in the same hue against the percentage axis on the right.
![Requests and success rate, by agent and by model, side by side with legends](/blog-assets/penguinharness-0-2-4-usage-agent-model-en.png)
-Both breakdowns are on screen at once — no dimension toggle to flip, and neither chart opens on an aggregate total that tells you nothing. The top four entities are named with one colorblind-checked hue each, and the rest fold into a neutral series whose label says how many it folded. Hovering a bar segment, a rate line or a legend item singles that entity out and fades the others.
+Both breakdowns are on screen at once. There is no dimension toggle to flip, and neither chart opens on an aggregate total that tells you nothing. The top four entities are named, each with its own colorblind-checked hue, and the rest fold into a neutral series whose label says how many it holds. Hovering a bar segment, a rate line or a legend item singles that entity out and fades the others.
-The Token chart keeps its three-segment bars and gains the cache hit rate as a dashed line on its own percentage axis, which is usually the fastest way to see why a day cost what it did.
+The Token chart keeps its three-segment bars and gains the cache hit rate as a dashed line on its own percentage axis. That line is usually the fastest way to see why a day cost what it did.
## Also in this release
-- **Memory** gained a change list under each file summary with a peer side panel, groups that export and import whole, and a prompt that now says *when* a fact is worth saving — a request repeated, a correction that outlives the task, a habit stated more than once — and to ask when it cannot tell.
-- **Settings** were consolidated into one System settings dialog, explanations moved behind a circled "?" instead of sitting on screen every visit, and required fields got one consistent marker.
-- **The new-chat screen** gained a rhythm-game example, a conversational investment Copilot, and a folder of scheduled-task examples. Clicking an example now fills the composer instead of sending it, so you read and edit before it goes out — and you can save your own prompts as shortcuts, stored per user on the server so they follow you to another machine.
+- **Memory** changes now show as a list below the file summary, and Memory has its own side panel beside the others. Memory groups export and import whole. The memory prompt now says when a fact is worth saving: a request repeated, a correction that outlives the Task, a habit stated more than once. When the agent cannot tell, it asks.
+- **Settings** were consolidated into one **System settings** dialog. Explanations moved behind a circled "?" instead of sitting on screen on every visit, and required fields got one consistent marker.
+- **The new-chat screen** gained a rhythm-game example, a conversational investment Copilot and a folder of scheduled-task examples. Clicking an example now fills the composer instead of sending it, so you can read and edit it first. You can also save your own prompts as shortcuts. They are stored per user on the server, so they follow you to another machine.
- **MCP Servers** take per-server permission settings.
-- **Desktop** installers are built from bundles rather than an assembled dependency tree, GUI launches import the login shell's environment, terminals ship their native module again, and the client updates from the account menu.
+- **Desktop** installers are built from bundles rather than an assembled dependency tree. Launching from the GUI imports the login shell's environment, terminals ship their native module again, and the client updates from the account menu.
## Upgrading
-Five changes in this release need a decision from you rather than just an update.
-
-**DeepSeek on the Responses protocol.** An entry whose id contains `deepseek-v4` and which carries no `client_type` is routed by its id to the DeepSeek client, which now posts to `{base_url}/responses`. Entries aimed at `https://api.deepseek.com` are fine — DeepSeek serves both protocols. An entry aimed at an endpoint that serves Chat Completions only — a self-hosted server, a relay, a third-party DeepSeek-compatible gateway — starts failing after the upgrade. Set `client_type = "openai-chat"` on it, in `.project_config.toml` or through the models page's protocol selector.
-
-**New catalog rows are not automatic.** Presets are copied into `.project_config.toml` when a Project is created, and nothing rewrites them afterwards. Use **sync presets** on the models page to pick up the new models; it appends and updates catalog-owned fields and never touches your stored default.
-
-**`GET /usage` changed shape.** `trend`, `byAgent` and `success` are gone, replaced by `series`, `byAgentSeries` and `byModelSeries`. The per-status failure breakdown `success` carried has no replacement.
-
-**Saved terminal dock arrangements are not carried over.** The docks start closed once; running shells are still reachable from any dock's "+" menu.
+Five changes in this release need a decision from you, not just an update.
-**The `agent-creation` skill is now `agent-initialization`.** The name says what it does — it initializes an Agent's settings rather than creating an Agent. An already-installed copy keeps working but no longer matches a library skill, so it will not be updated again. Install `agent-initialization`, delete `agent-creation` from the Agent's Skills tab, and update anything that pins the old name by hand: a stale pin resolves to nothing rather than failing loudly.
+- **DeepSeek on the Responses protocol.** An entry whose id contains `deepseek-v4` and that carries no `client_type` is routed by its id to the DeepSeek client, which now posts to `{base_url}/responses`. Entries aimed at `https://api.deepseek.com` are fine, because DeepSeek serves both protocols. An entry aimed at an endpoint that serves only Chat Completions, such as a self-hosted server, a relay or a third-party DeepSeek-compatible gateway, starts failing after the upgrade. Set `client_type = "openai-chat"` on it, in `.project_config.toml` or with the protocol selector on the models page.
+- **New catalog rows are not automatic.** Presets are copied into `.project_config.toml` when a Project is created, and nothing rewrites them afterwards. Click **Sync presets** on the models page to pick up the new models. It appends missing rows and updates catalog-owned fields, and it never touches your stored default model.
+- **`GET /usage` changed shape.** `trend`, `byAgent` and `success` are gone, replaced by `series`, `byAgentSeries` and `byModelSeries`. The per-status failure breakdown that `success` carried has no replacement.
+- **Saved terminal dock arrangements are not carried over.** The docks start closed once. Running shells are still reachable from any dock's "+" menu.
+- **The `agent-creation` Skill is now `agent-initialization`.** The new name says what it does: it initializes an agent's settings rather than creating an agent. An already-installed copy keeps working but no longer matches a library Skill, so it will not be updated again. Install `agent-initialization`, delete `agent-creation` from the agent's **Skills** tab, and update anything that pins the old name by hand. A stale pin resolves to nothing instead of failing loudly.
Full detail for every change is in [`changelog/0.2.4/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.4).
diff --git a/packages/landing/content/blog/penguinharness-0-2-4.zh.md b/packages/landing/content/blog/penguinharness-0-2-4.zh.md
index f2a16f48..36c54cdd 100644
--- a/packages/landing/content/blog/penguinharness-0-2-4.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-4.zh.md
@@ -1,86 +1,90 @@
---
-title: "PenguinHarness 0.2.4:DeepSeek 视觉模型、更灵活的工作区,以及成本中心优化"
+title: "PenguinHarness 0.2.4:DeepSeek 视觉模型、可自由停靠的面板,以及重建的成本中心"
date: 2026-08-21
category: news
-excerpt: DeepSeek 多了一个视觉模型,并切换到 Responses 协议。对话页的侧边面板与终端都变成两个 Dock 里的标签页,由你自行编排。耗时命令转入后台执行,跑完再回报结果。成本中心则围绕同一条时间轴重建——页面上每张图回答的都是同一个时间窗里的同一个问题。
+excerpt: "DeepSeek 新增视觉模型,并改用 Responses 协议。对话页的面板和终端变成右侧栏和下侧栏里的标签页,耗时命令转入后台运行,成本中心围绕同一个时间范围重建。"
---
-PenguinHarness 0.2.4 发布。这一版由三件事撑起来:一个能读图的 DeepSeek 模型,一个可以自己编排而不必将就的工作区,以及一个终于像一整页、而不是四个互不相干小部件的成本中心。
+PenguinHarness 0.2.4 发布了。这一版加入了一个能读图的 DeepSeek 模型,把对话页的侧边面板和终端变成右侧栏和下侧栏里的标签页,由你自行摆放;耗时的命令转入后台运行,成本中心也围绕同一个时间范围重建。升级时有五处改动需要你做判断,列在文末的「升级须知」里。
-## 一个会看图的 DeepSeek 模型
+## DeepSeek 新增视觉模型
-AgentHub 0.4.6 把 `deepseek-v4-flash-vision-exp` 带进了模型库。它在 V4 Flash 的文本能力之上增加图像输入,保留 1M 上下文窗口,价格与 V4 Flash 相同。
+AgentHub 0.4.6 把 `deepseek-v4-flash-vision-exp` 带进了模型目录。它在 V4 Flash 文本能力的基础上增加了图片输入,保留 1M 上下文窗口,价格与 V4 Flash 相同。
![DeepSeek 模型分组,视觉模型上带有「视觉」标记](/blog-assets/penguinharness-0-2-4-deepseek-vision-model-zh.png)
-它是该分组里唯一具备视觉能力的模型,这会改变一次会话处理图片的方式。纯文本模型要把图片交给 `vision_model` 代理,由 `describe_image` 转述成一段文字再递给 agent;而运行视觉模型的会话直接读图——中间既没有代理,也没有那段转述。
+它是 DeepSeek 分组里唯一支持视觉的模型,这会改变会话处理图片的方式。纯文本模型要把图片交给 `vision_model` 代理,由代理用 `describe_image` 逐张描述,再把一段文字交给 Agent。使用视觉模型的会话则直接读图,中间既没有代理,也没有转述这一步。
-该模型同时上架 OpenRouter,按该网关的公开价格计费。两条记录都采用 DeepSeek 的**非高峰**档,与既有记录同一口径:北京时间 9:00–12:00 与 14:00–18:00 的计费正好翻倍,而成本中心只按一个费率计算,因此高峰时段的用量会被低估一半。
+这个模型同时上架了 OpenRouter,按该网关公布的价格计费。两条记录都采用 DeepSeek 的非高峰档价格,与已有记录的口径一致。北京时间 9:00–12:00 和 14:00–18:00 的用量价格正好翻倍,而成本中心只按一个费率计算,所以高峰时段的用量会少算一半。
-同一版本还把第一方 DeepSeek 客户端从 Chat Completions 切到 OpenAI Responses API,base URL 的协议提示也随之改变。
+同一版本还把第一方 DeepSeek 客户端从 Chat Completions 切换到了 OpenAI Responses API,模型弹窗里 base URL 的协议提示也随之改变。
-![模型弹窗的 base URL 字段,协议提示显示 /responses](/blog-assets/penguinharness-0-2-4-model-protocol-hint-zh.png)
+![模型弹窗的 base URL 输入框,协议提示显示 /responses](/blog-assets/penguinharness-0-2-4-model-protocol-hint-zh.png)
-如果你把 `deepseek-v4*` 条目指向的不是 DeepSeek 官方端点,这是一处破坏性变更——见下方[升级须知](#升级须知)。
+如果你的 `deepseek-v4*` 条目指向的不是 DeepSeek 官方端点,这就是一处破坏性变更,处理方法见文末的「升级须知」。
-模型库的其他变化:`claude-opus-5` 进入 Anthropic 直连分组;新增分组弹窗可以直接导入某个端点的完整模型列表,不必一个个手敲 id;由环境变量提供 key 的模型终于被算作「已配置」——不再被「显示未配置 key 的模型」过滤器藏起来,凭据引导也不再反复提醒。
+模型目录的其他变化:
-## 工作区变成可以自己编排的
+- `claude-opus-5` 加入 Anthropic 直连分组。
+- 新增分组的弹窗可以一次导入某个端点的完整模型列表,不必再逐个输入 id。
+- 密钥来自环境变量的模型,现在也算作已配置。它不会再被**显示未配置 key 的模型**这个过滤器藏起来,凭据引导也不再提示它。
-对话页原先是抽屉式侧边面板加一套独立的终端窗格系统,两者各有各的规则。现在两者都没了。所有侧边元素——子智能体面板、工作区文件面板、记忆、新增的轨迹面板,以及任意多个终端——都成了两个 Dock(一个在右侧、一个在底部)里的可关闭标签页。
+## 侧边面板和终端都变成了标签页
-![对话页:右侧 Dock 显示智能体、记忆与工作区标签,底部 Dock 里是一个终端](/blog-assets/penguinharness-0-2-4-dock-tabs-zh.png)
+对话页原来的抽屉式侧边面板,以及那套独立的终端窗格,都已经移除。现在每个侧边元素都是一个可以关闭的标签页,放在右侧栏或下侧栏里。子 Agent 面板、Workspace 文件面板、记忆、新增的 Trace 面板,以及任意多个终端,都是这样的标签页。
-任何一项都可以放进任一 Dock。把标签拖过去,按这项任务真正需要的方式分配注意力,这套编排会跟着对话保留下来。
+![对话页:右侧栏里有智能体面板、记忆和工作区标签页,下侧栏里是一个终端](/blog-assets/penguinharness-0-2-4-dock-tabs-zh.png)
-终端是真正的服务端 shell,和其他所有内容共用同一条标签栏。
+标签页放在右侧栏还是下侧栏都可以。按任务的需要把标签页拖过去,这套布局会跟着会话保存下来。
-![底部 Dock 中的实时终端,显示 git log 输出](/blog-assets/penguinharness-0-2-4-dock-terminal-zh.png)
+终端是真正在服务端运行的 shell,和其他标签页共用同一条标签栏。
-## 耗时命令不再堵住对话
+![下侧栏里的实时终端,显示 git log 输出](/blog-assets/penguinharness-0-2-4-dock-terminal-zh.png)
-耗时数分钟的命令不再占住这一轮。它转入后台,agent 继续往下走,命令结束时由 Harness 注入一份完成回报——模型不必轮询就能知道结果。配套提供了终止工具;开了端口的进程还会直接给出访问链接。
+## 耗时命令不再卡住对话
-![后台进程行:命令、pid、localhost 链接与停止按钮](/blog-assets/penguinharness-0-2-4-background-process-zh.png)
+要跑好几分钟的命令,不会再占住当前这一轮。它转入后台运行,Agent 继续往下做。命令结束时,Harness 会注入一份完成报告,模型不用轮询就能知道结果。Agent 可以用终止工具停掉后台命令;开了端口的进程还会附上一个直达链接。
-与之配套的是 Project 级的**沙箱命令策略**:用正则规则在 shell 命令执行前拦下它,两个 shell 入口都会检查,且无论审批模式本来允许什么都一律拒绝。它是防误操作的护栏,不是安全边界——运行时拼装出来的命令仍可能绕过某条模式。
+![后台进程行:命令、pid、localhost 链接和停止按钮](/blog-assets/penguinharness-0-2-4-background-process-zh.png)
-## 成本中心读起来是一整页
+## Shell 命令策略
-原先的用量页是四个小部件,在四个不同的时间窗里回答四个不同的问题。现在只有一条时间轴,页面上每张图都画在它上面。
+每个 Project 现在都有一套沙箱命令策略:用正则规则在 shell 命令执行前把它拦下。两个 shell 入口都会检查这些规则,而且不管审批模式原本是否放行,命中规则的命令一律拒绝。新建的和已有的 Project 都自带一小套默认规则,会拒绝 `rm -rf` 这类破坏性命令,全部放行模式下也不例外。你可以在 **Project 设置** › **安全策略**里编辑或停用某条规则,也可以关掉整套策略。
+
+这套策略是防止误操作的护栏,不是安全边界。运行时才拼出来的命令,仍然可能绕过规则。
+
+## 成本中心围绕同一个时间范围重建
+
+用量页原先是四个小部件,在四个不同的时间窗里回答四个不同的问题。现在页面上的每张图都画在同一条时间轴上。
![成本中心:时间范围预设,以及带缓存命中率曲线的 Token 图](/blog-assets/penguinharness-0-2-4-usage-range-zh.png)
-你选一个范围——最近一小时、最近 24 小时这样的滚动窗口,最近 7 / 30 / 90 天这样的自然日预设,或者一对自定义日期——精度完全由范围决定:按分钟、按小时、按天、按周或按月。不存在第二个需要与第一个保持同步的控件。
+先选一个时间范围:最近 1 小时或 24 小时、最近 7 天、30 天或 90 天(按自然日计),或者一对自定义日期。精度完全由范围决定,分为按分钟、按小时、按天、按周和按月。不存在第二个需要和它保持同步的控件。
-占比饼图与按模型的进度条被两张并排的图取代,一张按 Agent 拆分,一张按模型拆分。每个时间桶的请求数是一根对着左轴的堆叠柱;每个实体的成功率是一条对着右侧百分比轴的虚线,颜色与它的柱段相同。
+占比饼图和按模型的进度条,换成了两张并排的图:一张按 Agent 拆分,一张按模型拆分。每张图里,每个时间桶的请求数画成一根堆叠柱,对应左侧坐标轴;每个实体的成功率画成一条同色虚线,对应右侧的百分比轴。
-![按 Agent 与按模型的「请求数与成功率」两张图并排,各自带图例](/blog-assets/penguinharness-0-2-4-usage-agent-model-zh.png)
+![按 Agent 与按模型拆分的请求数和成功率,两张图并排,各带图例](/blog-assets/penguinharness-0-2-4-usage-agent-model-zh.png)
-两种拆分同时在屏幕上——没有需要来回切换的维度开关,也没有一上来就给你一个说明不了任何问题的汇总总量。用量前四的实体各占一种通过色觉校验的色相,其余折叠成一条中性序列,标签里写明折叠了多少个。悬停某个柱段、某条成功率曲线或某个图例项,都会把该实体单独提出来、其余淡化。
+两种拆分同时显示在屏幕上,不需要来回切换维度,两张图也都不会一打开就给你一个说明不了问题的汇总数。用量前四的实体会单独列出名字,各用一种经过色盲友好校验的颜色;其余实体合并成一条中性色的序列,标签上写明合并了几个。鼠标悬停在某个柱段、某条成功率曲线或某个图例项上,这个实体就会突出显示,其余的变淡。
-Token 图保留三段式堆叠柱,并新增缓存命中率作为一条画在自己百分比轴上的虚线——想知道某一天的花费为什么是那个数,通常看它最快。
+Token 图保留三段式柱状图,并新增一条缓存命中率虚线,画在它自己的百分比轴上。想弄清某一天为什么花了那么多钱,通常看这条线最快。
## 这一版还有
-- **记忆**:文件摘要下方新增变更列表与并列的记忆侧栏;记忆分组可以整组导出导入;提示词也明确了**何时**值得记——同一诉求被再次提出、能超出本次任务的纠正、反复讲到的习惯——拿不准时就直接问。
-- **设置**:合并为一个系统设置弹窗;解释性文字收进带圈问号,不再每次进来都占着屏幕;必填字段统一了标记方式。
-- **新对话页**:新增音乐节奏游戏、对话式投资 Copilot,以及一整个定时任务示例分类。点击示例现在是填入输入框而不是直接发送,你可以先读、先改再发出;也可以把自己常用的提示词存成快捷指令,按用户存在服务端,换台机器依然还在。
+- **记忆**的变更现在列在文件摘要下方,记忆也有了自己的侧边面板,和其他面板并列。记忆分组可以整组导出、导入。记忆提示词现在写明了哪些信息值得记下来:重复提出的请求、在 Task 结束后仍然成立的纠正、不止一次提到的习惯。拿不准时,Agent 会直接问你。
+- **设置**合并成了一个**系统设置**弹窗。说明文字收进了带圈的「?」里,不再每次打开都占着屏幕;必填字段也统一了标记方式。
+- **新对话页**新增了节奏游戏示例、对话式投资 Copilot,以及一个定时任务示例分类。现在点击示例只会把内容填进输入框,不会直接发送,你可以先看、先改。你还可以把自己常用的提示词存成快捷指令。快捷指令按用户保存在服务端,换一台机器也还在。
- **MCP Server** 支持按服务器单独设置权限。
-- **桌面端**:安装包改由 bundle 构建而非组装依赖树;GUI 启动会导入登录 shell 的环境变量;终端所需的原生模块重新随包发布;客户端更新入口移到账号菜单。
+- **桌面应用**的安装包改为基于 bundle 构建,不再组装依赖树。从图形界面启动时会导入登录 shell 的环境变量,终端所需的原生模块重新随安装包提供,客户端也可以从账号菜单里更新。
## 升级须知
-这一版有五处需要你做一次判断,而不是升级完就没事了。
-
-**DeepSeek 切到 Responses 协议。** id 含 `deepseek-v4` 且未设置 `client_type` 的条目,会仅凭 id 被路由到 DeepSeek 客户端,而该客户端现在请求 `{base_url}/responses`。指向 `https://api.deepseek.com` 的条目不受影响——DeepSeek 两种协议都提供。指向只提供 Chat Completions 的端点(自建服务、中转、第三方 DeepSeek 兼容网关)的条目升级后会开始失败:在 `.project_config.toml` 里或通过模型页的协议选择器,把它设为 `client_type = "openai-chat"` 即可。
-
-**模型库的新条目不会自动出现。** 预置模型是在创建 Project 时复制进 `.project_config.toml` 的,此后不再被改写。在模型页点**同步预置**即可补入新模型:它只做追加与更新 catalog 所属字段,绝不会动你保存的默认模型。
-
-**`GET /usage` 的返回结构变了。** `trend`、`byAgent`、`success` 已移除,改为 `series`、`byAgentSeries` 与 `byModelSeries`。原先 `success` 携带的按状态失败明细没有替代项。
-
-**已保存的终端 Dock 布局不会迁移。** Dock 会有一次以关闭状态启动;正在运行的 shell 仍可从任一 Dock 的「+」菜单找回。
+这一版有五处改动需要你做判断,不是升级完就没事了。
-**`agent-creation` 技能更名为 `agent-initialization`。** 新名字说的是它实际做的事——初始化一个 Agent 的设置,而不是「创建 Agent」。已安装的旧副本仍可使用,但不再对应技能库里的任何 Skill,因此不会再收到更新。请安装 `agent-initialization`,在该 Agent 的技能标签页删除 `agent-creation`,并把手工点名旧名字的地方一并改掉:旧名字不会报错,只会静默地什么都匹配不到。
+- **DeepSeek 改用 Responses 协议。** id 中含有 `deepseek-v4`、且没有设置 `client_type` 的条目,会按 id 路由到 DeepSeek 客户端,而这个客户端现在请求的是 `{base_url}/responses`。指向 `https://api.deepseek.com` 的条目不受影响,因为 DeepSeek 两种协议都支持。如果条目指向只支持 Chat Completions 的端点,比如自建服务、中转服务或第三方 DeepSeek 兼容网关,升级后就会开始报错。给它设置 `client_type = "openai-chat"` 即可,可以写在 `.project_config.toml` 里,也可以用模型页的协议选择器。
+- **模型目录的新条目不会自动出现。** 预置模型只在创建 Project 时复制进 `.project_config.toml`,之后不会再被改写。要用上新模型,请在模型页点击**同步预置**。它会补入缺少的条目,更新由模型目录管理的字段,并且不会改动你保存的默认模型。
+- **`GET /usage` 的返回结构变了。** `trend`、`byAgent` 和 `success` 已移除,改为 `series`、`byAgentSeries` 和 `byModelSeries`。原先 `success` 里按状态拆分的失败统计,没有替代项。
+- **已保存的终端侧栏布局不会保留。** 升级后侧栏会先以关闭状态启动一次。正在运行的 shell 仍然可以从任一侧栏的「+」菜单里找回。
+- **`agent-creation` Skill 更名为 `agent-initialization`。** 新名字说的是它实际做的事:初始化一个 Agent 的设置,而不是创建 Agent。已经安装的旧副本仍然可以用,但它不再对应技能库里的任何 Skill,所以不会再收到更新。请安装 `agent-initialization`,在该 Agent 的**技能**标签页里删除 `agent-creation`,并手动修改所有写死了旧名字的地方:旧名字不会报错,只会什么都匹配不到。
每一项改动的完整细节见 [`changelog/0.2.4/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.4)。
diff --git a/packages/landing/content/blog/penguinharness-0-2-6.en.md b/packages/landing/content/blog/penguinharness-0-2-6.en.md
index e67014bc..0c42e6df 100644
--- a/packages/landing/content/blog/penguinharness-0-2-6.en.md
+++ b/packages/landing/content/blog/penguinharness-0-2-6.en.md
@@ -1,109 +1,129 @@
---
-title: "PenguinHarness 0.2.6: two Flash models, a TokenDance gateway, and subagents you can talk to"
+title: "PenguinHarness 0.2.6: two Flash models, a TokenDance gateway, and subagents you can steer"
date: 2026-08-27
category: news
-excerpt: GLM-5.3 Flash and Qwen 3.8 Flash joined the built-in catalog, and GLM-5.3 Flash is listed three times over — once per route that sells it, at three different prices. A TokenDance gateway group arrived with an authorization flow that mints its own key. And an agent's reach grew three ways: a subagent can be steered mid-run, by the model and by you; the `penguin` CLI became a client of the running server, so an agent can drive the install hosting it; and a Session can be bound to a Feishu app or a Telegram bot and answered from the chat.
+excerpt: "GLM-5.3 Flash and Qwen 3.8 Flash joined the built-in catalog, and a new TokenDance gateway group can obtain its API key for you. Subagents can be steered mid-run, the `penguin` CLI works through the server, and a Session can be answered from Feishu or Telegram."
---
-PenguinHarness 0.2.6 is out. The model catalog gained two low-cost Flash models and a whole new gateway, and an agent's reach grew in three directions: the subagents panel turned from a place you watch a child agent into a place you talk to one, the `penguin` CLI became a client of the running server so an agent can drive the harness hosting it, and a Session can be bound to a Feishu app or a Telegram bot and answered from there.
+PenguinHarness 0.2.6 is out. The model catalog gains two low-cost Flash models and a TokenDance gateway group whose **Authorize key** action mints a key for you. An agent's reach also grows in three directions: you and the model can steer a subagent mid-run, the `penguin` CLI works through the server so an agent can drive the harness it runs in, and a Session can be answered from Feishu or Telegram. Five changes need a decision from you when you upgrade; they are listed under Upgrading at the end of this post.
-## Two Flash models, one of them three times over
+## Two Flash models in the catalog
-`glm-5.3-flash` and `qwen3.8-flash` joined the built-in catalog. Both carry a million-token context window, both read images, and both price roughly an order of magnitude under their non-Flash siblings.
+The built-in catalog now includes `glm-5.3-flash` and `qwen3.8-flash`. Both have a million-token context window, both read images, and both cost roughly an order of magnitude less than their non-Flash siblings.
-GLM-5.3 Flash is in the catalog three times, because three routes sell it — Z.AI directly, OpenRouter, and the new TokenDance group — and each row records what that route charges.
+GLM-5.3 Flash appears three times, once for each route that sells it: Z.AI directly, OpenRouter, and the new TokenDance group. Each row carries that route's own prices.
![GLM-5.3 Flash listed under OpenRouter, TokenDance and Z.AI (GLM), each with a Vision badge and its own three prices](/blog-assets/penguinharness-0-2-5-glm-flash-rows-en.png)
-The three prices disagree for two different reasons, and one of them is a convention worth knowing. TokenDance simply charges its own rate. But Z.AI is running a 50% promotion on this model through 2026-09-09, and the two rows treat it differently on purpose: a **direct-vendor row records the vendor's list price**, so the Z.AI row reads $0.03 / $0.15 / $0.50 per million tokens, while a **gateway row records what the gateway actually bills**, so the OpenRouter row reads half that. Until the promotion lapses, the direct row over-states what Z.AI charges you by a factor of two.
+The three prices differ for two reasons, and one of them is a convention worth knowing. TokenDance simply charges its own rate. Z.AI, however, is running a 50% promotion on this model through 2026-09-09, and the Z.AI row and the OpenRouter row treat it differently on purpose:
-The Vision badge on the direct row is newer than it looks. AgentHub 0.4.8 taught the GLM client to forward `image_url` parts — in a prompt and in a tool result alike — and it does so for `glm-5.3-flash` and nothing else. Every other GLM id answers an image with `"GLM <id> does not support image inputs."` rather than quietly dropping it, which is why the rest of that group is still marked vision-off.
+- A direct-vendor row records the vendor's list price, so the Z.AI row reads $0.03 / $0.15 / $0.50 per million tokens.
+- The OpenRouter row records what OpenRouter actually bills, so it reads half that.
-Qwen 3.8 Flash sits in the Qwen Pay-As-You-Go group, a million-token input window against a 131K output cap, images included.
+Until the promotion ends, the direct row overstates what Z.AI charges you by a factor of two.
+
+The Vision badge on the direct row is newer than it looks. AgentHub 0.4.8 taught the GLM client to forward `image_url` parts, in a prompt and in a tool result alike, and it does so for `glm-5.3-flash` only. Every other GLM model answers an image with `"GLM <id> does not support image inputs."` instead of quietly dropping it, which is why the rest of that group is still marked as having no vision.
+
+Qwen 3.8 Flash sits in the Qwen Pay-As-You-Go group, with a million-token input window, a 131K output cap and image input.
![Qwen 3.8 Flash and Qwen 3.8 Max side by side in the Qwen Pay-As-You-Go group](/blog-assets/penguinharness-0-2-5-qwen-flash-row-en.png)
-## A TokenDance gateway, and a key you do not have to copy
+## A TokenDance gateway, with a key you do not have to copy
-TokenDance is now a provider group of its own, reaching `https://tokendance.space/gateway/v1` over Chat Completions, with seven presets.
+TokenDance is now a provider group of its own, with seven presets that reach `https://tokendance.space/gateway/v1` over Chat Completions.
![The TokenDance group: seven presets under a header carrying Add model, Authorize key, Set key, Speed test and Manage keys](/blog-assets/penguinharness-0-2-5-tokendance-group-en.png)
-**Authorize key** is the part worth pointing at. It sends you to TokenDance's own authorization page, mints a key on your account there, and writes it into every model in the group — so a first run no longer starts with a trip to a console and a copy-paste. The PKCE verifier is generated on the server and never sent to a browser, and the minted key goes straight into the group's models without passing through one either; it appears in no response, log line, URL or error message. Where a redirect cannot reach you — the desktop shell, an odd deployment — a manual mode shows a one-time code to paste instead.
+**Authorize key** saves you the usual first-run errand. It opens TokenDance's own authorization page, mints a key on your account there, and writes it into every model in the group, so you no longer start with a trip to a console and a copy-paste. Where a redirect cannot reach you, such as in the desktop app or an unusual deployment, a manual mode shows a one-time code to paste instead.
+
+The key exchange stays on the server. The PKCE verifier is generated there and never sent to a browser, and the minted key goes straight into the group's models without passing through one either. The key appears in no response, log line, URL or error message.
-The group's prices are **official list prices**, the same convention the two Qwen groups follow, and two of its rows are on live promotions: `glm-5.3-flash` at 50% off and `qwen3.8-max` at 20% off. So for those two, the catalog currently costs you more than the gateway does. Both promotions are tagged in TokenDance's public catalog API, which needs no credential, so whether one still runs is checkable rather than guessable.
+Unlike OpenRouter, this group records official list prices, the same convention the two Qwen groups follow. Two of its rows are on live promotions: `glm-5.3-flash` at 50% off and `qwen3.8-max` at 20% off. For those two models, the catalog currently shows a higher price than TokenDance bills. Both promotions are tagged in TokenDance's public catalog API, which needs no credential, so you can check whether a promotion is still running instead of guessing.
-Alongside the group, model requests now name PenguinHarness to the gateways that read an app-attribution header — `HTTP-Referer` and `X-OpenRouter-Title` for OpenRouter, `X-App-URL` for TokenDance. The header is chosen by the endpoint's host, not by the provider group, so a model filed under **custom** that points at one of those gateways is attributed the same way.
+Model requests now also identify PenguinHarness to gateways that read an app-attribution header: `HTTP-Referer` and `X-OpenRouter-Title` for OpenRouter, and `X-App-URL` for TokenDance. The header is chosen by the endpoint's host, not by the provider group, so a model in the Custom group that points at one of those gateways is attributed the same way.
-None of this reaches a Project you already have on its own. Presets are copied into `.project_config.toml` when a Project is created and nothing rewrites them afterwards; **sync presets** on the models page is the one path. It appends what is missing and updates catalog-owned fields on what is there, deletes nothing, and does not touch your stored default model or any credential.
+None of this reaches an existing Project on its own. Presets are copied into `.project_config.toml` when a Project is created, and nothing rewrites them afterwards. **Sync presets** on the models page is the only way in. It appends what is missing and updates catalog-owned fields on what is already there. It deletes nothing, and it does not touch your stored default model or any credential.
## Subagents you can talk to
-A subagent used to be fire-and-observe. `input_subagent` refused a prompt while the child was still running, the panel offered no way to correct or stop one at all, and stopping the main agent left its children running. All of that is gone, replaced by one mechanism: the steering channel you already have into the main session, pointed at the child session, and reachable by the model and by you.
+A subagent used to be something you launched and then watched. `input_subagent` refused a prompt while the child was still running, the panel offered no way to correct or stop a child, and stopping the main agent left its children running. All of that is gone. In its place is one mechanism, available to both the model and you: the steering channel you already had into the main Session, now pointed at the child Session.
![The subagents panel: the call graph above, the child conversation below with a steering message and the child's follow-up reply, and the child's own composer at the bottom](/blog-assets/penguinharness-0-2-5-subagent-steering-en.png)
-For the model, `input_subagent` gained a lot. A prompt sent to a running child is injected mid-run as a steering message at the child's next step. A new `abort` argument stops the child's current run only — the session survives for follow-ups — and combining `abort` with a prompt interrupts and redirects in one call. Its output is now the child's most recent complete reply, an idempotent snapshot on every access rather than a delta drain. And a released `subagent_id` revives automatically when the model messages it again.
+For the model, `input_subagent` changed in four ways:
-For you, the selected child is driven by the **same composer as the main conversation**: text, skills and slash commands, a per-turn thinking level, the context ring showing the child's own usage, and the approval-mode selector. A message is a user input on the child whatever state it is in — steering while it runs, a new round while it is idle, and a revival when the session had already ended. "This subagent has ended" is no longer a dead end.
+- A prompt sent to a running child is injected as a steering message at the child's next step.
+- A new `abort` argument stops only the child's current run, and the Session stays available for follow-ups. Combining `abort` with a prompt interrupts and redirects the child in one call.
+- The output is now the child's most recent complete reply. Repeated calls return that same reply until the child completes a newer one, instead of only what is new since the last call.
+- A released `subagent_id` comes back to life automatically when the model messages it again.
-The last gap was approvals. A background child that hit a tool approval used to be auto-denied, because the parent task's end converged every pending approval and a child with no active poll window had nowhere to ask. Now a child approval with nowhere else to go escalates to you as an ordinary approval card, and a parent task ending converges only the main session's approvals — the child's card stays rendered until you decide.
+For you, the selected child is driven by the same composer as the main conversation. It offers text, Skills and slash commands, a per-turn thinking level, the context ring showing the child's own usage, and the approval-mode selector. Whatever state the child is in, your message is user input to it: steering while it runs, a new round while it is idle, and a revival when its Session has already ended. An ended subagent is no longer a dead end.
-One trade-off comes with it, and it is a real one. Since a subagent session is always resumable and never destroyed, the kill notion for subagents is gone: `kill_subagent` is **removed**, and `kill_command` is folded into `input_command` as `kill: true`. No compatibility is kept for the two removed names — a model calling one gets an unknown-tool failure. See [Upgrading](#upgrading).
+The last gap was approvals. A background child that hit a tool approval used to be denied automatically, for two reasons: the parent Task's end closed every pending approval, and a child running in the background, with no parent call waiting on it, had nowhere to ask. Now a child's approval with nowhere else to go comes to you as an ordinary approval card. When the parent Task ends, only the main Session's pending approvals are closed, so the child's card stays on screen until you decide.
+
+This comes with a real trade-off. A subagent Session is now always resumable and never destroyed, so killing a subagent no longer exists as a concept. `kill_subagent` is removed, and `kill_command` is folded into `input_command` as `kill: true`. Neither removed name is kept for compatibility: a model that calls one gets an unknown-tool failure. See Upgrading below.
## An agent that can drive the harness
-`penguin run` and `penguin chat` used to execute a Task in-process against core: no server involved, and nothing the Web App could see. They are HTTP/SSE clients now — the CLI parses arguments and renders the stream, the server runs the Task — so a conversation started from a terminal shows up in the sidebar, and one started in the browser can be picked up from a terminal.
+`penguin run` and `penguin chat` used to execute a Task in-process against core, with no server involved and nothing the Web App could see. They are now HTTP/SSE clients: the CLI parses arguments and renders the stream, and the server runs the Task. A conversation started from a terminal shows up in the sidebar, and one started in the browser can be picked up from a terminal.
+
+Everything else in this section builds on that. Beside `run` and `chat` there is now a family of commands for inspecting and operating an install: `ls`, `input`, `logs`, `agent`, `project`, `cost` and `schedule`. Every command an agent runs gets what it needs to use them. `PENGUIN_API_URL`, `PENGUIN_API_TOKEN`, `PENGUIN_PROJECT_ID`, `PENGUIN_AGENT_ID` and `PENGUIN_SESSION_ID` are set in every tool subprocess. Inside a Session, a bare `penguin agent ls` reaches the very server running that Session, with that Project and that agent already the defaults. There is no login step anywhere on that path.
+
+![An agent inside its own conversation running penguin agent create and penguin run --background, then penguin ls showing the session it just started](/blog-assets/penguinharness-0-2-5-orchestration-en.png)
-That rebuild is what the rest of this rests on. Beside `run` and `chat` there is now a family for reading and moving an install — `ls`, `input`, `logs`, `agent`, `project`, `cost` and `schedule` — and every command an Agent runs is handed the coordinates to use them. `PENGUIN_API_URL`, `PENGUIN_API_TOKEN`, `PENGUIN_PROJECT_ID`, `PENGUIN_AGENT_ID` and `PENGUIN_SESSION_ID` go into every tool subprocess, so from inside a session a bare `penguin agent ls` reaches the very server running that session, with that Project and that Agent already the defaults. There is no login step anywhere on that path.
+`penguin input` is subagent steering one level out:
-![An Agent inside its own conversation running penguin agent create and penguin run --background, then penguin ls showing the session it just started](/blog-assets/penguinharness-0-2-5-orchestration-en.png)
+- Sent to a running Session, the message is taken in as a course correction at the next step, exactly like a steering message to a subagent.
+- Sent to an idle Session, it starts a new turn.
+- Without `-m`, it polls instead and prints the Session's most recent complete assistant reply. That is the same snapshot `input_subagent` returns for an empty prompt.
+- `--timeout` bounds any wait. When it expires, the command yields softly: it exits with code 0 and prints a line naming the follow-up command, while the Task keeps running on the server.
-`penguin input` is where this meets the section above: the same verb, one level out. Sent at a **running** session it is absorbed as a course correction at the next step, exactly as a steering message is on a subagent; sent at an idle one it starts a new turn. Without `-m` it polls instead, printing that session's most recent complete assistant reply — an idempotent snapshot, the same semantics `input_subagent` has with an empty prompt. `--timeout` bounds any wait and expires as a soft yield: exit 0, a line naming the follow-up command, and the Task still running on the server.
+A Session started from inside an agent inherits the settings of the Session it was started from. For each field you leave unspecified, `run` takes the calling Session's current value: Workspace, the model pair, approval mode and thinking level. This is the same inheritance `run_subagent` applies to children. From inside an agent, `penguin run -m "…"` on its own usually does the right thing, and flags are only for changing something.
-A session an Agent starts inherits the Agent's own. `run` fills each field left unspecified from the calling session's live values — Workspace, the model pair, approval mode, thinking level — field by field, the same inheritance `run_subagent` applies to children. So from inside an Agent, `penguin run -m "…"` on its own usually does the right thing, and flags are for diverging from it.
+Authorization is deliberately simple. At every start, the server mints an API token into `<data-root>/api-token` with mode 0600, and a CLI on the same machine reads it. That token is admin-equivalent, because filesystem access to the data root already amounts to admin authority. A remote `--server` gets no such shortcut: without an explicit `PENGUIN_API_TOKEN`, it is refused.
-Authorization is deliberately plain. The server mints an API token at every boot into `<data-root>/api-token`, mode 0600, and a CLI on the same machine reads it; that token is admin-equivalent, on the grounds that filesystem access to the data root already is admin authority. A remote `--server` gets no such shortcut and is refused without an explicit `PENGUIN_API_TOKEN`.
+The recipes ship as a Skill. `penguin-orchestration` joined the library's AI App Development group as part of the preinstalled set, so a new `default_agent` gets it along with the rest of the library, and any other agent can install it from the library. It sets out the conventions: look around with the read-only listings before changing anything, and hand bulk material to a new Session through a Workspace file rather than through `-m`. It also spells out the cautions, which are the real limits:
-The recipes ship as a Skill. **`penguin-orchestration`** joined the library's AI App Development group, with no preinstall marker, so a newly created Agent picks it up like the rest of the library. It carries the conventions — orient with the read-only listings before mutating anything, hand bulk material to a new session through a Workspace file rather than through `-m` — and the cautions, which are the real edges: one active Task per session, so a message at a busy session steers it rather than queueing a second; a spawned session inherits your approval mode, so an unattended `always-ask` run just hangs waiting for a human who is not watching; an Agent that can message Agents can build a loop that never terminates; and everything it starts bills the same Project.
+- A Session runs one active Task at a time, so a message to a busy Session steers it instead of queueing a second Task.
+- A spawned Session inherits your approval mode, so an unattended `always-ask` run just hangs, waiting for a person who is not watching.
+- An agent that can message agents can build a loop that never ends.
+- Everything it starts bills the same Project.
## A Session you can reach from Feishu or Telegram
-A conversation no longer has to be read in a browser tab. A Session can be bound to a self-built Feishu app or a Telegram bot: messages sent to the bot land in that Session as ordinary user input, and the assistant's replies come back into the chat.
+You no longer have to read a conversation in a browser tab. A Session can be bound to a self-built Feishu app or a Telegram bot. Messages sent to the bot land in that Session as ordinary user input, and the assistant's replies come back into the chat.
![The Messaging panel on Telegram: the channel selector, then the enable switch with its live status and the two probes, and only below them the Bot Token field with its stored-secret mask and clear checkbox](/blog-assets/penguinharness-0-2-5-messaging-en.png)
-Both channels sit behind one connector seam, and a Session keeps a saved config for each — Feishu takes an App ID, an App Secret and an API domain, Telegram a single Bot Token — but **at most one of them is enabled**, and the enabled one holds the live connection. Turning the second on is gated with the reason on screen, and refused by the server as well.
+A Session keeps a saved configuration for each channel. Feishu takes an **App ID**, an **App Secret** and an **API domain**, and Telegram takes a single **Bot Token**. At most one channel is enabled at a time, and the enabled one holds the live connection. Turning on the second is blocked, with the reason on screen, and the server refuses it too.
-Neither channel needs a public URL. Feishu's inbound events arrive over the SDK's WebSocket long connection, Telegram's over an offset-based `getUpdates` long poll — Telegram pushes nothing without a public webhook, so the connector pulls instead. A laptop behind NAT is enough: no tunnel, no webhook endpoint. On connect the poller discards whatever accumulated while nothing was listening rather than replaying a dark period as a flood of Tasks, which is also how Feishu behaves — missed events are simply gone.
+Neither channel needs a public URL. Feishu delivers inbound events over the SDK's WebSocket long connection. Telegram pushes nothing without a public webhook, so the connector pulls updates with an offset-based `getUpdates` long poll instead. A laptop behind NAT is enough: no tunnel, no webhook endpoint. When the Telegram connector connects, it skips whatever piled up while nothing was listening, rather than replaying that stretch as a flood of Tasks. Feishu behaves the same way, so missed events are simply gone.
-Replies arrive as they finish rather than in one block at the end. Each completed assistant message is relayed on its own the moment it completes, so a run that writes working notes between tool calls reaches the chat as that same sequence; the sends of one Session are serialised so they arrive in the order they completed, and chunked under the channels' text limits (Telegram's 4096-character cap is the tightest). In a group chat, the first thing a run sends is threaded onto the message that triggered it and everything after it — including that message's own continuation chunks — is a plain send, so a long answer does not bury the thread in quote blocks.
+Replies arrive as they finish, not in one block at the end. Each assistant message is relayed the moment it completes, so a run that writes working notes between tool calls reaches the chat as the same sequence of messages. Messages from one Session arrive in the order they completed, split to fit each channel's text limit; Telegram's 4096-character cap is the tightest. In a group chat, a run's first message replies to the message that triggered it, and everything after that, including the rest of a split message, is sent plainly, so a long answer does not bury the thread in quote blocks.
-Credentials follow the models page's interaction: the field always starts empty, a stored secret shows only as its mask, and a "clear stored …" checkbox drops it on save — refused while that channel's connection is enabled, so a live connection can never outrun the credential its store still has. Saving and enabling stay separate concerns, Save writing credentials and the switch connecting or terminating with what is stored. The controls lead the form and the credential fields trail them, which is deliberate: the two channels' field lists differ in length, so controls placed underneath would sit at a different height in each channel and jump on every switch.
+Credentials work the way they do on the models page. The field always starts empty, a stored secret shows only as a mask, and a **Clear stored App Secret** or **Clear stored Bot Token** checkbox removes it when you save. Clearing is refused while that channel's connection is enabled, so a live connection never outlasts its stored credential. Saving and enabling are separate: **Save** writes credentials, and the switch connects or disconnects with what is stored. The form puts the connection controls, meaning the switch, its live status and the two probes, above the credential fields on purpose: the two channels have different numbers of fields, so controls placed below the fields would sit at a different height in each channel and jump every time you switch channels.
-One form, two hosts — the session row's menu, and a **Messaging** panel in the conversation's dock beside the Trace panel. A Session holding a live connection carries a small paper plane on its sidebar row, the same mark for every channel, with the channel named in the tooltip and the screen-reader text rather than in the shape. What the model sees is nothing special: inbound text starts a Task as plain composer input, with no marker and no special sender, so it never learns the message came from a chat app. A pending tool approval sends a one-line notice pointing at the web UI, since approving is not something a chat message can do.
+The same form opens from two places: the Session row's menu, and the **Messaging** panel in the conversation's dock, beside the Trace panel. In later versions this panel is called **Remote control**. A Session with a live connection shows a small paper plane on its sidebar row. The mark is the same for every channel, and the tooltip and screen-reader text name the channel.
+
+The model sees nothing special. Inbound text starts a Task as plain composer input, with no marker and no special sender, so the model never learns the message came from a chat app. A pending tool approval sends a one-line notice pointing to the Web App, because a chat message cannot approve anything.
## Also in this release
-- **The context ring is a button now.** Clicking it breaks the current context into six parts — system prompt, tool definitions, user messages, model messages, tool requests, tool results — as one bar across the whole window, with a dashed mark where compaction will fire and a ranking of the five tools eating the most of it.
-- **A red dot leads to the update.** Whenever a software release or an Agent kernel update is available, the chrome carries a phone-style dot, and every dot leads down an unbroken path to the control that performs that update rather than stopping at a notice.
-- **Groups go in the order you put them.** Both the chat sidebar's conversation groups and the models page's provider groups can be dragged into a manual order, stored per Project; the chat model picker follows the models page.
-- **The sidebar counts by group.** Each group pages its own server stream, so its reveal row names that group's own hidden count and a **Show less** folds it back, and the group list itself paginates ten at a time.
-- **The standalone Trace page is gone.** A Trace is read in its conversation's Trace panel, and Trace import moved into System settings with an explicit Project and Agent destination — an imported Trace becomes a listed conversation instead of hiding behind a filter.
-- **Agents are easier to start.** The create dialog installs library skills and the skills a chosen project directory already carries, and it can initialize an Agent straight from an exported snapshot package instead of making you create an empty one and import into it.
+- **The context ring is now a button.** Clicking it breaks the current context into six parts: system prompt, tool definitions, user messages, model messages, tool requests and tool results. They appear as one bar across the whole context window, with a dashed mark where compaction will fire and a ranking of the five tools that take up the most of it.
+- **A red dot leads to the update.** When a software release or an agent kernel update is available, the interface shows a phone-style red dot. Every dot leads along an unbroken path to the control that performs the update, rather than stopping at a notice.
+- **Groups stay in the order you set.** You can drag both the chat sidebar's conversation groups and the models page's provider groups into a manual order, stored per Project. The chat model picker follows the models page's order.
+- **The sidebar counts by group.** Each group loads its own pages, so its reveal row shows that group's own hidden count, and **Show less** folds it back. The group list itself pages ten groups at a time.
+- **The standalone Trace page is gone.** You read a Trace in its conversation's Trace panel. Trace import moved into **System settings** and now asks for a Project and an agent, so an imported Trace becomes a listed conversation instead of hiding behind a filter.
+- **Agents are easier to start.** The create dialog installs library Skills and the Skills a chosen project directory already carries. It can also initialize an agent straight from an exported snapshot package, instead of making you create an empty agent and import into it.
## Upgrading
-Five changes in this release need a decision from you rather than just an update.
-
-**`kill_subagent` and `kill_command` are gone.** Stopping a subagent run is `input_subagent`'s `abort`; terminating a command is `input_command` with `kill: true`. Nothing translates the old names: an Agent whose stored tool configuration names them simply stops assembling those entries, and a model that calls one gets the standard unknown-tool failure. Update anything that pins either name by hand.
-
-**Editing one field of a settings tab freezes that whole tab.** The kernel update's unit is now a settings tab rather than a single config leaf. The upside is that a tab you have customized is never overwritten; the cost is that an Agent with one customized built-in tool stops receiving new built-in tools entirely. "Restore the default configuration" on that tab puts it back under kernel updates.
-
-**An Agent's commands no longer inherit the server's `PENGUIN_*` environment.** No `PENGUIN_*` variable — nor `PORT` or `HOST` — reaches a command an Agent runs, so a harness an Agent starts takes the default data root rather than the serving install's. Outbound proxy variables are the deliberate exception. If a command needs one of those variables, set it in that Agent's vault, which is applied after the host environment is stripped.
-
-**The CLI no longer runs a Task without a server.** `penguin run` and `penguin chat` go through the server API; where none is running they start one locally, and fully offline core-direct execution is no longer a CLI mode — the SDK keeps that capability for embedders. In the same rework the per-user "show CLI sessions" filter was retired and every session is always listed, so Sessions an older CLI left behind now appear in the sidebar on their own. Nothing on disk has to be migrated, and old binaries keep working against their own cores until they are updated.
+Five changes in this release need a decision from you, not just an update.
-**New catalog rows are not automatic.** Presets are copied into `.project_config.toml` at Project creation and nothing rewrites them. Use **sync presets** on the models page to pick up GLM-5.3 Flash, Qwen 3.8 Flash and the TokenDance group. A Project older than that group has to sync once before the group — and its **Authorize key** action — appears at all.
+- **`kill_subagent` and `kill_command` are gone.** To stop a subagent run, use `input_subagent` with `abort`. To terminate a command, use `input_command` with `kill: true`. Nothing translates the old names: an agent whose stored tool configuration names them simply stops loading those entries, and a model that calls one gets the standard unknown-tool failure. Update anything that pins either name by hand.
+- **Editing one field of a settings tab freezes that whole tab.** Kernel updates now apply to a settings tab as a unit rather than to single config values. A tab you have customized is never overwritten. The cost is that an agent with one customized built-in tool stops receiving new built-in tools entirely. **Restore default configuration** on that tab puts it back under kernel updates.
+- **An agent's commands no longer inherit the server's `PENGUIN_*` environment.** A command an agent runs no longer receives any of the server's own `PENGUIN_*` variables, nor `PORT` or `HOST`. Of the `PENGUIN_*` family, the harness sets only the five control variables described earlier. A harness that an agent starts therefore uses the default data root rather than that of the install serving it. Outbound proxy variables are the deliberate exception. If a command needs one of these variables, set it in that agent's vault, which is applied after the host environment is stripped.
+- **The CLI no longer runs a Task without a server.** `penguin run` and `penguin chat` go through the server API. Where no server is running, they start one locally. Fully offline execution directly against core is no longer a CLI mode; the SDK keeps that capability for embedders. The same rework retired the per-user "show CLI sessions" filter, so every Session is always listed, and Sessions left behind by an older CLI now appear in the sidebar. Nothing on disk needs migrating, and old binaries keep working against their own cores until you update them.
+- **New catalog rows are not automatic.** Presets are copied into `.project_config.toml` when a Project is created, and nothing rewrites them. Use **Sync presets** on the models page to pick up GLM-5.3 Flash, Qwen 3.8 Flash and the TokenDance group. A Project older than that group has to sync once before the group, and its **Authorize key** action, appear at all.
Full detail for every change is in [`changelog/0.2.6/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.6).
diff --git a/packages/landing/content/blog/penguinharness-0-2-6.zh.md b/packages/landing/content/blog/penguinharness-0-2-6.zh.md
index d4ec320e..bfc7e4d5 100644
--- a/packages/landing/content/blog/penguinharness-0-2-6.zh.md
+++ b/packages/landing/content/blog/penguinharness-0-2-6.zh.md
@@ -1,109 +1,129 @@
---
-title: "PenguinHarness 0.2.6:两个 Flash 模型、TokenDance 网关,以及可以对话的子智能体"
+title: "PenguinHarness 0.2.6:两款 Flash 模型、TokenDance 网关,以及你能中途插话的子 Agent"
date: 2026-08-27
category: news
-excerpt: GLM-5.3 Flash 与 Qwen 3.8 Flash 进入预置模型库,其中 GLM-5.3 Flash 被列了三次——每条售卖它的通路各一条记录,价格各不相同。新增 TokenDance 网关分组,并带一套能直接签发密钥的授权流程。智能体的触达范围也向三个方向长了一截:子智能体可以在运行途中被纠偏,模型能做,你也能做;`penguin` CLI 变成了服务端的客户端,智能体由此能操作运行着自己的那套 PenguinHarness;Session 还能绑定飞书应用或 Telegram 机器人,直接在聊天里对话。
+excerpt: "GLM-5.3 Flash 和 Qwen 3.8 Flash 加入内置模型目录,新增的 TokenDance 网关分组支持自动获取密钥。现在可以向运行中的子 Agent 插话,`penguin` CLI 改为经由服务端运行,你还能在飞书或 Telegram 里直接和会话对话。"
---
-PenguinHarness 0.2.6 发布。预置模型库多了两个低价 Flash 模型和一整个新网关;智能体的触达范围则向三个方向各长了一截:子智能体面板从「看着子智能体跑」变成了「和它对话」,`penguin` CLI 变成了服务端的客户端——这正是智能体得以驱动运行着自己的那套 Harness 的前提,而 Session 可以绑定飞书应用或 Telegram 机器人,从聊天里对话。
+PenguinHarness 0.2.6 发布了。模型目录新增两款低价的 Flash 模型,以及一个支持自动获取密钥的 TokenDance 网关分组。Agent 能触及的范围也向三个方向扩展:你和模型都可以在子 Agent 运行中途向它插话;`penguin` CLI 改为经由服务端运行,Agent 因此可以操作运行着它自己的 Harness;你还可以在飞书或 Telegram 里直接和会话对话。升级时有五处改动需要你做判断,都列在文末的「升级须知」里。
-## 两个 Flash 模型,其中一个出现了三次
+## 模型目录新增两款 Flash 模型
-`glm-5.3-flash` 与 `qwen3.8-flash` 进入预置模型库。两者都是百万 Token 上下文窗口,都能读图,价格也都比各自的非 Flash 版本低一个数量级左右。
+内置模型目录新增了 `glm-5.3-flash` 和 `qwen3.8-flash`。两者都有百万 Token 的上下文窗口,都能读图,价格也都比各自的非 Flash 版本低一个数量级左右。
-GLM-5.3 Flash 在模型库里出现了三次,因为有三条通路在卖它——Z.AI 直连、OpenRouter,以及新增的 TokenDance——每条记录写的都是这条通路的收费。
+GLM-5.3 Flash 在目录里出现了三次,因为有三条渠道在卖它:Z.AI 直连、OpenRouter,以及新增的 TokenDance 分组。每条记录列的都是这条渠道自己的价格。
![OpenRouter、TokenDance 与 Z.AI (GLM) 下各有一条 GLM-5.3 Flash,都带视觉标记,价格各不相同](/blog-assets/penguinharness-0-2-5-glm-flash-rows-zh.png)
-三个价格不一致有两个原因,其中一个是值得知道的口径差异。TokenDance 只是按自己的费率收费;而 Z.AI 正在对这个模型做 50% 促销,有效期至 2026-09-09——两条记录对这次促销的处理是**有意不同**的:**直连厂商的记录写厂商的官方标价**,所以 Z.AI 那条是每百万 Token $0.03 / $0.15 / $0.50;**网关的记录写网关实际计费的价格**,所以 OpenRouter 那条是它的一半。促销结束之前,直连那条记录把 Z.AI 的实际收费高估了一倍。
+三个价格不一致有两个原因,其中一个是值得了解的记录口径。TokenDance 只是按自己的费率收费。Z.AI 则正在对这款模型做五折促销,有效期到 2026-09-09,而 Z.AI 和 OpenRouter 的两条记录有意采用了不同的处理方式:
-直连那条上的「视觉」标记比看上去要新。AgentHub 0.4.8 让 GLM 客户端开始转发 `image_url` 部件——提示词里和工具结果里都转发——而且只对 `glm-5.3-flash` 一个 id 生效。其他每个 GLM id 面对图片都会直接报 `"GLM <id> does not support image inputs."`,而不是悄悄丢掉,这也是该分组其余模型仍标为不支持视觉的原因。
+- 直连厂商的记录写厂商的官方标价,所以 Z.AI 那条是每百万 Token $0.03 / $0.15 / $0.50。
+- OpenRouter 的记录写 OpenRouter 实际收取的价格,所以是它的一半。
-Qwen 3.8 Flash 位于 Qwen Pay-As-You-Go 分组,百万 Token 输入窗口、131K 输出上限,同样支持图片输入。
+促销结束之前,直连那条记录把 Z.AI 的实际收费高估了一倍。
+
+直连那条上的视觉标记,其实是最近才加上的。AgentHub 0.4.8 让 GLM 客户端开始转发 `image_url` 部件,提示词和工具结果里的都会转发,但只对 `glm-5.3-flash` 生效。其他 GLM 模型收到图片时,会直接报 `"GLM <id> does not support image inputs."`,而不是悄悄丢掉图片,所以这个分组的其余模型仍然标为不支持视觉。
+
+Qwen 3.8 Flash 位于 Qwen Pay-As-You-Go 分组,输入窗口百万 Token,输出上限 131K,同样支持图片输入。
![Qwen Pay-As-You-Go 分组里并排的 Qwen 3.8 Flash 与 Qwen 3.8 Max](/blog-assets/penguinharness-0-2-5-qwen-flash-row-zh.png)
-## TokenDance 网关,以及一把不用手抄的密钥
+## TokenDance 网关,以及不用手动复制的密钥
-TokenDance 现在是独立的供应商分组,通过 Chat Completions 协议访问 `https://tokendance.space/gateway/v1`,随分组提供七个预置模型。
+TokenDance 现在是一个独立的供应商分组,带七个预置模型,通过 Chat Completions 协议访问 `https://tokendance.space/gateway/v1`。
![TokenDance 分组:七个预置模型,分组头部有添加模型、自动获取密钥、手动设置密钥、测速与前往密钥管理](/blog-assets/penguinharness-0-2-5-tokendance-group-zh.png)
-值得单独点出来的是**自动获取密钥**。它把你送到 TokenDance 自己的授权页,在你的账号下签发一把新密钥,并写入该分组的每一个模型——第一次使用不必再跑一趟控制台手工复制。PKCE 校验串在服务端生成、从不下发给浏览器,签发出的密钥也不经过浏览器直接进入分组的模型配置,不出现在任何响应、日志、URL 或错误信息里。回调到不了你这里的场景(桌面端,或某些部署形态)另有一种手动模式:授权页改为显示一次性验证码,粘贴即可。
+**自动获取密钥**省掉了第一次使用时的例行步骤。它会打开 TokenDance 自己的授权页,在你的账号下签发一个密钥,并写进分组里的每一个模型,你不必先去控制台复制粘贴。如果授权后的回调到不了你这里,比如在桌面应用里或某些特殊的部署环境中,可以改用手动模式:页面会显示一个一次性验证码,把它粘贴回来即可。
-该分组的价格记录的是**官方标价**,与下方两个 Qwen 分组同一口径;而其中两条正在促销:`glm-5.3-flash` 打五折、`qwen3.8-max` 打八折。也就是说这两条目前把实际花费算高了。两个促销都在 TokenDance 的公开模型接口里带标记,且该接口无需凭据,所以促销是否还在跑是可以查的,不用猜。
+整个密钥交换都在服务端完成。PKCE 校验串在服务端生成,从不发给浏览器;签发的密钥直接写进分组里的模型,同样不经过浏览器。任何响应、日志、URL 或错误信息里都不会出现这个密钥。
-与该分组一同上线的还有应用归属:模型请求现在会向读取该类头部的网关表明自己是 PenguinHarness——OpenRouter 用 `HTTP-Referer` 与 `X-OpenRouter-Title`,TokenDance 用 `X-App-URL`。头部按端点的 host 选择,而非按供应商分组,因此一个归在 **custom** 下、却指向这两个网关的模型,会得到同样的归属标记。
+和 OpenRouter 不同,这个分组记录的是官方标价,与两个 Qwen 分组口径相同。其中两个模型正在促销:`glm-5.3-flash` 打五折,`qwen3.8-max` 打八折。所以对这两个模型,目录里的价格目前高于 TokenDance 的实际收费。两个促销在 TokenDance 的公开模型目录 API 里都有标记,这个 API 不需要凭据,促销还在不在,可以直接查到,不用猜。
-以上这些都不会自动出现在你已有的 Project 里。预置模型是在创建 Project 时复制进 `.project_config.toml` 的,此后不再被改写;模型页的**同步预置**是唯一入口。它只补入缺失项、更新 catalog 所属字段,不删除任何东西,也不会动你保存的默认模型和任何凭据。
+模型请求现在还会向会读取应用归属请求头的网关表明自己来自 PenguinHarness:OpenRouter 用 `HTTP-Referer` 和 `X-OpenRouter-Title`,TokenDance 用 `X-App-URL`。用哪个请求头由端点的主机名决定,与供应商分组无关,所以放在 Custom 分组里、却指向这两个网关的模型,也会带上同样的归属信息。
-## 可以对话的子智能体
+以上这些都不会自动出现在已有的 Project 里。预置模型只在创建 Project 时复制进 `.project_config.toml`,之后不会再改写。模型页的**同步预置**是唯一的入口。它会补上缺少的条目,更新已有条目中由模型目录管理的字段;它不删除任何东西,也不会改动你保存的默认模型和任何凭据。
-子智能体过去是「发出去,然后只能看着」。子会话还在运行时 `input_subagent` 会拒绝新的提示词;面板里既不能纠偏也不能停止;停掉主智能体,它的子会话还在跑。这些现在都没有了,取而代之的是同一套机制:把你本来就有的、对主会话的纠偏通道指向子会话,模型和你都能用。
+## 可以对话的子 Agent
-![子智能体面板:上方是调用关系图,下方是子会话对话——一条纠偏消息与子会话的后续回复,底部是子会话自己的输入框](/blog-assets/penguinharness-0-2-5-subagent-steering-zh.png)
+以前,子 Agent 启动之后你就只能看着。子 Agent 还在运行时,`input_subagent` 会拒绝新的提示词;面板上既不能纠正它,也不能停止它;停掉主 Agent,它的子 Agent 还会继续运行。这些现在都改了。取而代之的是一套模型和你都能用的机制:你原本用来向主会话插话的通道,现在也能指向子会话。
-对模型来说,`input_subagent` 增强了不少。发给运行中子会话的提示词会作为纠偏消息在它下一步注入。新增的 `abort` 参数只停掉子会话**当前这一轮**——会话本身保留,还能继续对话——`abort` 与提示词一起给出,就是一次调用完成「打断并改道」。它的返回值现在是子会话**最近一条完整回复**,每次访问都是幂等快照,而不是增量抽取。已释放的 `subagent_id` 在模型再次给它发消息时会自动复活。
+![子 Agent 面板:上方是调用关系图,下方是子会话的对话,包括一条插话消息和子 Agent 随后的回复,底部是子会话自己的输入框](/blog-assets/penguinharness-0-2-5-subagent-steering-zh.png)
-对你来说,选中的子会话由**与主对话完全相同的输入框**驱动:正文、技能与斜杠指令、按轮设置的思考档位、显示子会话自身用量的上下文环,以及审批模式选择器。无论子会话处于什么状态,你发的都是一条对它的用户输入——运行中是纠偏,空闲时是新一轮,已经结束的则被复活。「该子智能体已结束」不再是死路。
+对模型来说,`input_subagent` 有四处变化:
-最后一处缺口是审批。后台子会话碰到工具审批过去会被自动拒绝:父任务结束时会把所有待审批一并收敛,而没有活动轮询窗口的子会话根本没地方发问。现在,无处可去的子会话审批会以普通审批卡片的形式升级给你;父任务结束时也只收敛主会话的审批——子会话的卡片会一直留在那里,等你决定。
+- 发给运行中子 Agent 的提示词,会在它的下一步作为插话消息注入。
+- 新增的 `abort` 参数只停止子 Agent 当前这一轮运行,会话本身保留,之后还能继续对话。`abort` 和提示词一起给出,一次调用就能打断子 Agent 并给它新的方向。
+- 返回值改为子 Agent 最近一条完整的回复。在子 Agent 完成新的回复之前,重复调用返回的都是这同一条,而不是上次调用之后新增的内容。
+- 已释放的 `subagent_id`,在模型再次给它发消息时会自动恢复。
-随之而来的是一处取舍,而且是实打实的。既然子会话始终可恢复、从不销毁,「kill」这个概念对子智能体就不再成立:`kill_subagent` 已**移除**,`kill_command` 并入 `input_command`,改为 `kill: true`。这两个旧名字没有保留任何兼容——模型调用它们会得到标准的「未知工具」失败。详见下方[升级须知](#升级须知)。
+对你来说,选中的子 Agent 由和主对话相同的输入框驱动。文字、Skill 和斜杠命令、按轮设置的思考等级、显示子 Agent 自身用量的上下文环,以及审批模式选择器,一样不少。不管子 Agent 处于什么状态,你发的消息都是给它的用户输入:运行中是插话,空闲时是新的一轮,会话已经结束时则会让它恢复。已经结束的子 Agent 不再是死路。
-## 能驱动 Harness 自己的智能体
+最后一处缺口是审批。后台子 Agent 碰到工具审批时,以前会被自动拒绝,原因有两个:父 Task 一结束,所有待处理的审批都会随之关闭;而在后台运行、没有父调用在等它的子 Agent,也没有地方发问。现在,子 Agent 没有别处可以处理的审批,会以普通审批卡片的形式交给你。父 Task 结束时,只会关闭主会话里待处理的审批,子 Agent 的卡片会一直留在界面上,等你决定。
-`penguin run` 与 `penguin chat` 过去是在进程内直接调用 core 执行任务的:不经过服务端,Web App 也看不见。现在它们是 HTTP/SSE 客户端——CLI 负责解析参数与渲染流式输出,任务本身在服务端执行——因此终端里发起的对话会出现在侧边栏里,浏览器里发起的对话也能从终端接着聊。
+这带来一个实实在在的取舍。子 Agent 的会话现在始终可以恢复、从不销毁,所以「终止子 Agent」这个概念不复存在。`kill_subagent` 已移除,`kill_command` 并入 `input_command`,改为 `kill: true`。两个移除的名字都没有保留兼容:模型调用其中任何一个,都会得到「未知工具」错误。详见下文的「升级须知」。
-这次重建是后面这些的前提。除 `run` 与 `chat` 外,现在还有一组用于查看和操作一套部署的命令——`ls`、`input`、`logs`、`agent`、`project`、`cost` 与 `schedule`——而 Agent 运行的每一条命令都会被交给使用它们所需的坐标。`PENGUIN_API_URL`、`PENGUIN_API_TOKEN`、`PENGUIN_PROJECT_ID`、`PENGUIN_AGENT_ID` 与 `PENGUIN_SESSION_ID` 会注入每一个工具子进程,因此在会话内部,一句不带任何参数的 `penguin agent ls` 访问的正是承载该会话的那个服务端,并且已经以该 Project 与该 Agent 为默认值。这条路径上没有任何登录步骤。
+## 能操作 Harness 的 Agent
-![智能体在自己的对话里执行 penguin agent create 与 penguin run --background,随后用 penguin ls 看到刚刚启动的会话](/blog-assets/penguinharness-0-2-5-orchestration-zh.png)
+以前,`penguin run` 和 `penguin chat` 在进程内直接调用 core 执行 Task,不经过服务端,Web App 也看不到。现在它们是 HTTP/SSE 客户端:CLI 负责解析参数和渲染流式输出,Task 由服务端执行。从终端发起的对话会出现在侧栏里,浏览器里发起的对话也能在终端里接着聊。
-`penguin input` 正是它与上一节交汇的地方:同一个动作,只是往外挪了一层。发给**运行中**会话时,它会在下一步作为纠偏被吸收,与对子智能体发送纠偏消息完全一致;发给空闲会话则开启新一轮。不带 `-m` 时它转为轮询,打印该会话最近一条完整的助手回复——一份幂等快照,与 `input_subagent` 传空提示词时的语义相同。`--timeout` 为任何等待设定上限,到期是一次软让出:退出码 0、一行点名后续命令的提示,而任务仍在服务端继续跑。
+这一节后面的内容都建立在这个基础上。除了 `run` 和 `chat`,现在还有一组用来查看和操作 PenguinHarness 实例的命令:`ls`、`input`、`logs`、`agent`、`project`、`cost` 和 `schedule`。Agent 运行的每一条命令,都能拿到使用这些命令所需的信息:每个工具子进程里都设置了 `PENGUIN_API_URL`、`PENGUIN_API_TOKEN`、`PENGUIN_PROJECT_ID`、`PENGUIN_AGENT_ID` 和 `PENGUIN_SESSION_ID`。在会话内部,一条不带参数的 `penguin agent ls` 访问的正是运行这个会话的服务端,而且已经以当前 Project 和当前 Agent 为默认值。这条路径上没有任何登录步骤。
-智能体启动的会话会继承它自己的配置。`run` 会把你没有指定的每个字段,逐个从调用方会话的实时取值里补齐——工作区、模型对、审批模式、思考档位——与 `run_subagent` 对子会话的继承是同一套。因此在 Agent 内部,单独一句 `penguin run -m "…"` 通常就是对的,参数是用来偏离它的。
+![Agent 在自己的对话里运行 penguin agent create 和 penguin run --background,随后用 penguin ls 看到刚刚启动的会话](/blog-assets/penguinharness-0-2-5-orchestration-zh.png)
-授权模型有意保持朴素。服务端每次启动都会签发一把 API 令牌,写入 `<data-root>/api-token`(权限 0600),同机的 CLI 直接读取它;这把令牌等同管理员权限,理由是能读写数据根的文件系统访问权本来就等同管理员权限。指向远程的 `--server` 没有这层便利,未显式提供 `PENGUIN_API_TOKEN` 时会被拒绝。
+`penguin input` 相当于把给子 Agent 插话的做法往外挪了一层:
-这些用法以 Skill 的形式随产品发布。**`penguin-orchestration`** 进入技能库的「AI 应用开发」分组,且没有预装标记,因此新建的 Agent 会像装其余技能一样装上它。它写明了惯例——动手改动之前先用只读列表命令摸清现状,大段材料通过工作区文件交给新会话,而不是塞进 `-m`——也写明了注意事项,那才是真正的边界:每个会话同时只有一个活动任务,因此发给繁忙会话的消息是纠偏而非排入第二个任务;派生的会话继承你的审批模式,因此无人值守的 `always-ask` 会话只会一直挂着,等一个并没有在看的人;能给智能体发消息的智能体,也能搭出一个永不终止的循环;以及它启动的一切都算在同一个 Project 的账上。
+- 发给运行中的会话,消息会在下一步当作纠偏来处理,和发给子 Agent 的插话消息完全一样。
+- 发给空闲的会话,会开始新的一轮。
+- 不带 `-m` 时,它改为轮询,打印这个会话最近一条完整的助手回复。这和 `input_subagent` 收到空提示词时返回的快照相同。
+- `--timeout` 为任何等待设定上限。到时间后命令会平稳退出:退出码为 0,打印一行提示写明后续可以运行的命令,Task 则继续在服务端运行。
-## 可以从飞书或 Telegram 联系的 Session
+在 Agent 内部启动的会话,会继承发起调用的那个会话的设置。你没有指定的字段,`run` 都会取那个会话的当前值:Workspace、模型对、审批模式和思考等级。这和 `run_subagent` 对子 Agent 的继承规则相同。所以在 Agent 内部,单独一句 `penguin run -m "…"` 通常就是对的,参数只在需要改动某一项时才加。
-对话不再只能在浏览器标签页里读。Session 可以绑定到一个自建的飞书应用或一个 Telegram 机器人:发给机器人的消息会作为普通用户输入进入该 Session,助手的回复也会回到聊天里。
+授权的设计有意保持简单。服务端每次启动都会签发一个 API Token,写入 `<data-root>/api-token`,权限为 0600,同一台机器上的 CLI 直接读取它。这个 Token 等同管理员权限,理由是能访问数据根目录的文件系统权限,本来就相当于管理员权限。远程的 `--server` 没有这种便利:没有显式提供 `PENGUIN_API_TOKEN` 时,CLI 会直接拒绝连接。
-![Telegram 下的消息软件面板:先是渠道选择器,随后是带实时状态的启用开关与两个探测按钮,再往下才是 Bot Token 字段及其已存密钥掩码与清除勾选框](/blog-assets/penguinharness-0-2-5-messaging-zh.png)
+这些用法以 Skill 的形式提供。`penguin-orchestration` 加入了技能库的「AI 应用开发」分组,属于预装的那一批,所以新建的 `default_agent` 会和技能库里的其他 Skill 一起装上它,其他 Agent 也可以从技能库里安装。它写明了惯例:改动任何东西之前,先用只读的列表命令了解现状;大段材料通过 Workspace 文件交给新会话,而不是塞进 `-m`。它也写明了注意事项,这些才是真正的边界:
-两个渠道位于同一层连接器抽象之后,Session 为每个渠道各保存一份配置——飞书需要 App ID、App Secret 与 API 域名,Telegram 只需要一个 Bot Token——但**同时至多只有一个处于启用状态**,持有实时连接的就是它。想启用第二个时,开关会带着原因被拦住,服务端也会拒绝。
+- 一个会话同一时间只运行一个活动 Task,所以发给忙碌会话的消息会作为插话送达,而不是排进第二个 Task。
+- 派生出的会话会继承你的审批模式,所以无人值守的 `always-ask` 运行只会一直卡住,等一个并没有在看的人。
+- 能给 Agent 发消息的 Agent,可能搭出一个永远不会结束的循环。
+- 它启动的一切,都记在同一个 Project 的账上。
-两个渠道都不需要公网 URL。飞书的入站事件走 SDK 的 WebSocket 长连接;Telegram 没有公网 webhook 就不会推送,因此连接器改为主动拉取,走基于 offset 的 `getUpdates` 长轮询。一台位于 NAT 之后的笔记本就够了——不必打隧道,也不必准备 webhook 端点。连接时,轮询会把无人连接期间积压的更新直接跳过,而不是把这段空窗期重放成一堆任务;飞书同理——错过的事件就是错过了。
+## 可以从飞书或 Telegram 联系的会话
-回复是完成一条发一条,而不是在整轮结束时发一大块。每条完整的助手消息在完成的那一刻单独转发出去,因此一轮里在工具调用之间写下的工作笔记,到了聊天里也是同样的一串消息;同一个 Session 的发送被串行化,到达顺序与完成顺序一致,并按各渠道的文本长度上限分块(其中 Telegram 的 4096 字符上限最紧)。在群聊里,一轮中发出的第一段内容会挂在触发它的那条消息下形成话题回复,其后的一切——包括这条消息自身的后续分块——都是普通发送,这样长回答不会把话题埋进一堆引用块里。
+对话不再只能在浏览器标签页里看。会话可以绑定一个自建的飞书应用或一个 Telegram 机器人:发给机器人的消息会以普通用户输入的形式进入这个会话,助手的回复也会发回聊天里。
-凭据沿用模型页的那套交互:输入框永远从空开始,已保存的密钥只以掩码形式显示,旁边的「清除已保存的……」勾选框在保存时将其丢弃——而该渠道的连接处于启用状态时,清除会被拒绝,这样实时连接永远不会跑在它的凭据存量之前。保存与启用是两件独立的事:保存只写凭据,开关则用已存的凭据去连接或断开。表单把控件放在前面、凭据字段排在后面,这是有意为之:两个渠道的字段数量不同,控件若放在字段下方,在两个渠道里的高度就不一致,每次切换都会跳动。
+![Telegram 下的消息软件面板:先是渠道选择器,然后是带实时状态和两个探测按钮的启用开关,再往下才是 Bot Token 字段,以及已存密钥的掩码和清除勾选框](/blog-assets/penguinharness-0-2-5-messaging-zh.png)
-一套表单,两个宿主——会话行的菜单,以及对话面板栏里紧邻 Trace 面板的**消息软件**面板。持有实时连接的 Session 会在侧栏行上带一个小小的纸飞机,所有渠道共用同一个标记,渠道本身由提示气泡与无障碍文本点名,而不是由图形区分。而模型看到的一切并无特别:入站文本以普通输入框内容的形式启动任务,没有任何标记、也没有特殊发送者,因此它不会知道这条消息来自聊天软件。遇到待审批的工具调用时,会发出一行提示指向 Web 界面——审批不是一条聊天消息能完成的事。
+会话为每个渠道各保存一份配置。飞书需要 **App ID**、**App Secret** 和 **API 域名**,Telegram 只需要一个 **Bot Token**。同一时间最多只能启用一个渠道,启用的那个持有实时连接。要启用第二个时,界面会阻止你并说明原因,服务端也会拒绝。
-## 这一版还有
+两个渠道都不需要公网 URL。飞书的入站事件通过 SDK 的 WebSocket 长连接送达。Telegram 没有公网 webhook 就不会主动推送,所以连接器改为用基于 offset 的 `getUpdates` 长轮询主动拉取。一台在 NAT 后面的笔记本就够了,不用打隧道,也不用准备 webhook 端点。Telegram 连接器连上时,会跳过无人监听期间积压的消息,而不是把这段空窗期重放成一大堆 Task。飞书也是这样,错过的事件就是错过了。
-- **上下文环现在是个按钮。** 点开它,当前上下文被拆成六部分——系统提示词、工具定义、用户消息、模型消息、工具请求、工具结果——画成横跨整个窗口的一条,虚线标出压缩将在何处触发,并列出占用最多的五个工具。
-- **一个红点带你走到更新本身。** 只要有可用的软件更新或 Agent 内核更新,界面上就会出现手机式的小红点;每个红点都沿着一条不断的路径通向真正执行更新的那个控件,而不是停在一句通知上。
-- **分组按你排的顺序来。** 对话侧栏的会话分组与模型页的供应商分组都可以拖成手动顺序,按 Project 保存;对话的模型选择器跟随模型页的顺序。
-- **侧栏按分组各算各的。** 每个分组分页读取自己的服务端流,展开行写的是该分组自己的隐藏数量,并配有**收起**;分组列表本身也按每页十个分页。
-- **独立的轨迹页面已移除。** 轨迹在其所属对话的轨迹面板里查看;轨迹导入移入系统设置,并需明确指定目标 Project 与 Agent——导入的轨迹会成为一条正常列出的对话,而不是藏在过滤器后面。
-- **新建 Agent 更省事。** 创建弹窗可以一次装好技能库里的多个技能,以及所选项目目录本来就带的技能;也可以直接用导出的快照包初始化一个 Agent,不必先建空 Agent 再导入。
+回复是完成一条发一条,而不是整轮结束后一次发出一大段。每条助手消息一完成就转发出去,所以一次运行中在工具调用之间写下的工作笔记,到了聊天里也是同样的一串消息。同一个会话的消息按完成的先后到达,并按各渠道的文本长度上限拆分,其中 Telegram 的 4096 字符上限最紧。在群聊里,一次运行发出的第一条消息会回复触发它的那条消息,之后的消息(包括拆分出来的后续部分)都直接发送,这样长回答就不会把话题埋进一堆引用块里。
-## 升级须知
+凭据的交互方式和模型页一样。输入框总是从空白开始,已保存的密钥只显示掩码;勾选**清除已存 App Secret** 或**清除已存 Bot Token**,保存时就会删掉它。渠道连接处于启用状态时不能清除,这样实时连接就不会在它的凭据删掉之后继续存在。保存和启用是两件独立的事:**保存**只写入凭据,开关则用已保存的凭据去连接或断开。表单有意把连接控件(开关、实时状态和两个探测按钮)放在凭据字段上方:两个渠道的字段数量不同,控件如果放在字段下面,在两个渠道里的高度就不一样,每次切换渠道都会跳动。
-这一版有五处需要你做一次判断,而不是升级完就没事了。
+同一套表单有两个入口:会话行的菜单,以及对话右侧栏里紧挨 Trace 面板的**消息软件**面板。在之后的版本里,这个面板改名为**远程控制**。持有实时连接的会话,会在侧栏那一行上显示一个小纸飞机。所有渠道用的都是这个标记,具体是哪个渠道,写在提示气泡和读屏文本里。
-**`kill_subagent` 与 `kill_command` 已移除。** 停止子会话当前这一轮用 `input_subagent` 的 `abort`;终止命令用 `input_command` 加 `kill: true`。旧名字没有任何转换:Agent 存量工具配置里若点名了它们,这些条目会直接装配不出来;模型调用它们则得到标准的「未知工具」失败。请把手工点名旧名字的地方一并改掉。
+模型看到的东西没有任何特别之处。入站文本就像在输入框里输入的一样启动 Task,没有标记,也没有特殊的发送者,所以模型不会知道消息来自聊天软件。遇到待审批的工具调用时,会发出一行提示,引导你去 Web App 处理,因为聊天消息没法完成审批。
-**改动设置标签页里的任何一个字段,会冻结整个标签页。** 内核更新的粒度从单个配置叶子改成了一个设置标签页。好处是你自定义过的标签页永远不会被覆盖;代价是只要一个内置工具被改过,该 Agent 就完全收不到新增的内置工具了。在该标签页上「恢复默认配置」,即可让它重新接受内核更新。
+## 这一版还有
+
+- **上下文环现在是个按钮。** 点击它,会把当前上下文拆成六部分:系统提示词、工具定义、用户消息、模型消息、工具请求和工具结果。它们画成一条横跨整个上下文窗口的长条,用虚线标出压缩会在哪里触发,并列出占用最多的五个工具。
+- **红点会一路带你找到更新。** 有软件更新或 Agent 内核更新时,界面上会出现手机上那样的小红点。顺着任何一个红点一路点下去,都能走到真正执行更新的那个控件,不会停在一条通知上。
+- **分组按你排好的顺序显示。** 对话侧栏里的会话分组和模型页的供应商分组,都可以拖成自己想要的顺序,按 Project 保存。对话里的模型选择器沿用模型页的顺序。
+- **侧栏按分组计数。** 每个分组各自分页加载,所以展开行显示的是这个分组自己的隐藏数量,点击**收起**即可折叠回去。分组列表本身每次显示十个分组。
+- **独立的 Trace 页面已移除。** Trace 在所属对话的 Trace 面板里查看。Trace 导入移到了**系统设置**里,并且需要指定一个 Project 和一个 Agent,导入的 Trace 会成为列表里的一条对话,而不是藏在过滤器后面。
+- **新建 Agent 更省事。** 创建弹窗可以安装技能库里的 Skill,以及所选项目目录里已有的 Skill。它还能直接用导出的快照包初始化 Agent,不必先建一个空 Agent 再导入。
-**Agent 运行的命令不再继承服务端的 `PENGUIN_*` 环境变量。** 任何 `PENGUIN_*` 变量(以及 `PORT`、`HOST`)都不会传到 Agent 运行的命令里,因此由 Agent 启动的 Harness 会使用默认数据根,而不是当前服务实例的数据根。出网代理相关的变量是有意保留的例外。命令确实需要某个变量时,请写进该 Agent 的 vault——它在剥离宿主环境之后再叠加。
+## 升级须知
-**CLI 不再脱离服务端执行任务。** `penguin run` 与 `penguin chat` 都经由服务端 API;本机没有服务端在跑时,它们会自行拉起一个,而「完全离线、直连 core」不再是 CLI 的一种运行方式——这项能力仍由 SDK 为嵌入方保留。同一次重建中,按用户保存的「显示 CLI 会话」过滤开关被取消,所有会话一律列出,因此旧版 CLI 留下的 Session 现在会自行出现在侧边栏里。磁盘上没有任何数据需要迁移,旧版二进制在更新之前也仍能用它自带的 core 正常工作。
+这一版有五处改动需要你做判断,不是升级完就没事了。
-**模型库的新条目不会自动出现。** 预置模型是在创建 Project 时复制进 `.project_config.toml` 的,此后不再被改写。在模型页点**同步预置**即可补入 GLM-5.3 Flash、Qwen 3.8 Flash 与 TokenDance 分组。比该分组更早创建的 Project,需要先同步一次,这个分组——以及它的**自动获取密钥**——才会出现。
+- **`kill_subagent` 和 `kill_command` 已移除。** 要停止子 Agent 的运行,用 `input_subagent` 加 `abort`;要终止一条命令,用 `input_command` 加 `kill: true`。旧名字不会自动转换:Agent 已保存的工具配置里如果写了它们,这些条目就不再加载;模型调用旧名字,会得到标准的「未知工具」错误。手动写死了这两个名字的地方,都需要改掉。
+- **改动设置标签页里的任何一个字段,整个标签页都会冻结。** 内核更新现在以设置标签页为单位,而不是以单个配置值为单位。好处是更新永远不会覆盖你改过的标签页;代价是,只要改过一个内置工具,这个 Agent 就再也收不到新增的内置工具。在该标签页点击**还原为默认配置**,它就会重新接受内核更新。
+- **Agent 运行的命令不再继承服务端的 `PENGUIN_*` 环境变量。** 服务端自己的 `PENGUIN_*` 变量都不会传给 Agent 运行的命令,`PORT` 和 `HOST` 也不会。`PENGUIN_*` 变量里,Harness 只会设置前面提到的五个控制变量。所以 Agent 启动的 Harness 会使用默认的数据根目录,而不是当前服务实例的数据根目录。出站代理相关的变量是有意保留的例外。如果某条命令确实需要这些变量,请写进该 Agent 的密钥保险柜,保险柜里的变量会在剥离宿主环境变量之后注入。
+- **CLI 不再脱离服务端执行 Task。** `penguin run` 和 `penguin chat` 都经由服务端 API;本机没有服务端在运行时,它们会在本地启动一个。完全离线、直接调用 core 的执行方式不再是 CLI 的一种模式,这项能力保留在 SDK 里,供嵌入方使用。在这次重构中,按用户保存的「显示 CLI 会话」过滤开关也取消了,所有会话一律列出,旧版 CLI 留下的会话现在会出现在侧栏里。磁盘上没有任何数据需要迁移,旧版二进制在你更新之前,也仍能用它们自带的 core 正常工作。
+- **模型目录的新条目不会自动出现。** 预置模型只在创建 Project 时复制进 `.project_config.toml`,之后不会再改写。请在模型页点击**同步预置**,补入 GLM-5.3 Flash、Qwen 3.8 Flash 和 TokenDance 分组。比这个分组更早创建的 Project 需要先同步一次,这个分组和它的**自动获取密钥**才会出现。
每一项改动的完整细节见 [`changelog/0.2.6/`](https://github.com/Prism-Shadow/penguin-harness/tree/main/changelog/0.2.6)。
diff --git a/packages/landing/content/blog/simple-harness-is-all-you-need.en.md b/packages/landing/content/blog/simple-harness-is-all-you-need.en.md
index d1e6b3e2..05689aa4 100644
--- a/packages/landing/content/blog/simple-harness-is-all-you-need.en.md
+++ b/packages/landing/content/blog/simple-harness-is-all-you-need.en.md
@@ -2,54 +2,68 @@
title: "Simple Harness Is All You Need"
date: 2026-07-22
category: perspectives
-excerpt: Databricks benchmarked coding agents against real pull requests from its own multi-million-line codebase. The best score on the entire board did not belong to the most capable harness — it belonged to the simplest one, at roughly half the cost. Here is why context discipline beats feature count, and how PenguinHarness is built around that bet.
+excerpt: Databricks benchmarked coding agents on roughly a hundred real pull requests, and the highest pass rate went to the simplest harness at about half the cost. This essay argues that a harness is an information budget, and shows how PenguinHarness is built around that idea.
---
-You would expect a feature-rich agent harness to beat a minimal one. More tools, more context, more scaffolding, better decisions. That is the intuition the entire category was built on.
+> Written for PenguinHarness 0.1.1. Later releases may differ in some details.
-Databricks tested it against real work — roughly a hundred pull requests pulled from their own multi-million-line production monorepo, graded by restoring the held-out tests and running them. Here is the result:
+An **agent harness** is the software around a language model that decides what goes into each request: the system prompt, the tool definitions, and the message history. The common intuition is that a bigger harness makes a better agent. More tools, more context, and more scaffolding should lead to better decisions, and the whole category was built on that belief.
-![Databricks' Pareto chart: pass-rate against cost per task. The frontier is dominated by the minimal Pi harness, and the highest score on the chart is Opus 4.8 on Pi](/blog-assets/databricks-pareto.png)
+This essay argues the opposite. In a Databricks benchmark on real pull requests, the simplest harness produced the highest score at about half the cost, and Databricks attributes the result to sending less context per turn.
+
+## The evidence: a benchmark on real pull requests
+
+Databricks tested the intuition against real work. It took roughly a hundred pull requests from its own multi-million-line production monorepo, and graded each run by restoring the held-out tests and running them. Here is the result:
+
+![Scatter plot from the Databricks benchmark: pass rate against cost per task for coding agents. Red points mark the Pareto frontier, which is dominated by the minimal Pi harness, and the highest point is Opus 4.8 on Pi](/blog-assets/databricks-pareto.png)
_Pass-rate against cost per task. Red points form the Pareto frontier. Source: [Databricks](https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase)._
-Read the top of that chart carefully, because it is the opposite of what the intuition predicts. **The single highest pass-rate — about 90% — belongs to Opus 4.8 running on [Pi](https://github.com/earendil-works/pi), a harness whose entire core is read, write, edit, and a shell.** The same model on Claude Code at maximum effort scores slightly lower, at roughly twice the cost per task. And of the points on the Pareto frontier, most are Pi.
+The top of the chart inverts the intuition. The single highest pass rate, about 90%, belongs to Opus 4.8 running on [Pi](https://github.com/earendil-works/pi), a harness whose entire core is read, write, edit, and a shell. The same model on Claude Code at maximum effort scores slightly lower, at roughly twice the cost per task. Most of the points on the Pareto frontier, the runs that no other run beats on both cost and pass rate, are Pi.
-The minimal harness did not merely hold its own on price. **At the top of the board, it won.**
+The minimal harness did not merely hold its own on price. At the top of the board, it won.
-Databricks were careful not to overclaim, and so are we: their stated lesson is not that one harness is always cheaper or that vendor harnesses are worse. The chart backs that caution up — Opus on Pi at `max` effort lands around 81%, well below Claude Code at comparable spend. Simplicity is not a guarantee. But the direction is unmistakable, and their explanation of the mechanism is a single sentence:
+Databricks is careful not to overclaim, and so are we. Its stated lesson is not that one harness is always cheaper, or that vendor harnesses are worse. The chart supports that caution: Opus on Pi at `max` effort lands around 81%, well below Claude Code at comparable spend. Simplicity is not a guarantee. The direction is still clear, and Databricks explains the mechanism in two sentences:
> "Pi sent about 3x less context per turn. It managed context better, keeping a tighter working set and finishing the tasks in fewer runs."
-One more detail worth noting, since it is rarer than it should be: they refused to grade with a model, on the grounds that doing so "rewards sounding right over being right."
+One choice in the method deserves mention, because few benchmarks make it: Databricks refused to grade with a model, on the grounds that doing so "rewards sounding right over being right."
+
+## A harness is an information budget
-## 1. A harness is an information budget
+A model is a function behind an API. It receives a system prompt, tool definitions, and a message history, and it returns text and tool calls. That contract is fixed and public, so a harness makes exactly one kind of decision: what occupies the model's context window on each turn.
-A model is a function behind an API. It receives a system prompt, tool definitions, and a message history; it returns text and tool calls. That contract is fixed and public. **Everything else — every piece of software deciding what goes into that request — is the harness.**
+The context window, the text a model can attend to in one request, is finite. Everything a harness does is therefore allocation: it spends a budget on the model's behalf, on every turn. Two harnesses that call the same model are not running different intelligence. They are running different budgets, and in the Databricks data, the one that spent less scored higher.
-Which means a harness only ever makes one kind of decision: what occupies the finite context window. It is not a feature list. It is a budget, spent on the model's behalf, on every single turn.
+## Where context weight accumulates
-That reframing explains the chart immediately. Two harnesses calling the same model are not running different intelligence. They are running different budgets — and the one that spent less scored higher.
+Context bloat is never one bad decision. It is four defensible ones, compounding on every turn.
-## 2. Where the weight accumulates
+### The tool surface
-Context bloat is never one bad decision. It is four defensible ones, compounding every turn.
+Every tool costs its name, description, and full JSON Schema in *every* request. Thirty tools are not thirty conveniences. They are a permanent tax, plus a wider decision space for the model to get lost in. The marginal tools usually re-implement something a shell already does.
-**The tool surface.** Every tool costs its name, description, and full JSON Schema in *every* request. Thirty tools is not thirty conveniences — it is a permanent tax plus a wider decision space to get lost in. And the marginal ones usually re-implement something a shell already does.
+### Tool output
-**Tool output.** A dependency install dumps thousands of lines. That output is not billed once; it becomes history and gets resent every subsequent turn. Uncapped output is the fastest way to turn a cheap task into an expensive one.
+A dependency install prints thousands of lines. That output is not billed once: it becomes history and is resent on every later turn. Uncapped output is the fastest way to turn a cheap task into an expensive one.
-**The system prompt.** Long behavioral rulebooks encode judgment the model already has. Telling a frontier model not to hardcode credentials spends tokens restating its training. Worse, over-specification implies the model is not trusted to reason — which makes it hesitant precisely in the cases the rules failed to anticipate.
+### The system prompt
-**Per-turn injections.** Environment snapshots, status blocks, re-sent config files, stapled onto every message. Individually tiny, structurally permanent.
+Long behavioral rulebooks encode judgment the model already has. Telling a frontier model not to hardcode credentials spends Tokens restating its training. Worse, over-specification implies that the model is not trusted to reason, which makes it hesitant in exactly the cases the rules failed to anticipate.
-None of these are wrong ideas. They are unpriced ones.
+### Per-turn injections
-## 3. How PenguinHarness is built
+Environment snapshots, status blocks, and re-sent config files get stapled onto every message. Each one is tiny, but structurally it is permanent.
-We made this bet before the benchmark existed, and it is visible in the source rather than the marketing. Every number below is checkable in the repo.
+None of these is a wrong idea. The problem is that nobody puts a price on them.
-**Six tools, and no file tools at all.** PenguinHarness ships [six built-in tools](https://penguin.ooo/docs/tools); any session sees five, since the two image tools are mutually exclusive by model class.
+## How PenguinHarness is built
+
+We made this bet before the benchmark existed, and it shows in the source code rather than in marketing copy. Each detail in this section can be checked in the repository at the `v0.1.1` tag.
+
+### Six tools, and no file tools
+
+PenguinHarness 0.1.1 ships [six built-in tools](https://github.com/Prism-Shadow/penguin-harness/blob/v0.1.1/packages/docs/content/tools.en.md). Any one Session sees five of them, because the two image tools are mutually exclusive by model class.
| Tool | Purpose |
| --- | --- |
@@ -58,51 +72,71 @@ We made this bet before the benchmark existed, and it is visible in the source r
| `run_subagent` / `input_subagent` | Delegate a subtask to a child agent, then poll or follow up |
| `read_image` / `describe_image` | Return an image, or have a vision model describe it in text |
-There is no read tool, no write tool, no edit tool, no glob, no grep. Reading, writing, editing and searching all go through the shell, because the shell already does them and the model already knows how. Where a four-tool minimal core spends read, write and edit on the filesystem, **we spend one**. We are not claiming the smallest absolute tool count — Pi's core is tighter by one — but the smallest schema surface for what agents actually do all day.
+In 0.1.1 there is no read tool, write tool, edit tool, glob, or grep. Reading, writing, editing, and searching all go through the shell, because the shell already does them and the model already knows how. A four-tool minimal core spends three tools (read, write, and edit) on the filesystem; PenguinHarness spends one. We do not claim the smallest absolute tool count, since Pi's core has one tool fewer. We claim the smallest schema surface for what agents actually do all day.
+
+### A 72-line system prompt
+
+The 0.1.1 default template is 72 lines, about 6,500 characters before placeholder substitution ([source](https://github.com/Prism-Shadow/penguin-harness/blob/v0.1.1/packages/core/src/state/default-config.ts)). It covers the role, success criteria, constraints, stop rules, the filesystem layout, and a short list of suggested workflows. Then it stops.
+
+### Output capped by default
+
+The Environment truncates the output of every tool call at 16,000 characters, in one central place. Exit codes are appended *outside* the truncation window, so the line that tells the model whether the command succeeded survives even when long output is cut.
+
+### Skills that cost one line until used
+
+There is no skill tool. The prompt carries only each Skill's name and one-line description, and the agent reads the body on demand with an ordinary shell command. A Skill that goes unused costs a single line.
+
+### Compaction into a clean context
+
+Past 128,000 Tokens, the engine summarizes the conversation into a `<context_summary>` and continues in a *fresh* context, instead of appending to a swollen history. As a result, one Trace file always holds exactly one model context.
-**A 72-line system prompt.** The default template is 72 lines, about 6,600 characters before substitution ([source](https://github.com/Prism-Shadow/penguin-harness/blob/main/packages/core/src/state/default-config.ts)). Role, success criteria, constraints, stop rules, filesystem layout, a short list of suggested workflows — then it stops.
+### A clean message protocol
-**Output capped by default.** Every tool call truncates at 16,000 characters, enforced centrally by the Environment. Exit codes are appended *outside* the truncation window, so the line telling the model whether the command succeeded survives even when the middle is cut.
+No environment metadata is stapled to user messages. The model receives the conversation itself: user turns, assistant turns, and tool results.
-**Skills that cost nothing until used.** There is no skill tool. The prompt carries only each skill's name and one-line description; the body is read on demand with an ordinary shell command. A skill you do not use costs you a single line.
+## Why less context wins
-**Compaction into a clean context.** Past 128,000 tokens, the engine summarizes into a `<context_summary>` and continues in a *fresh* context rather than appending to a swollen history — so one trace file is always exactly one model context.
+The intuition that more context improves decisions is reasonable. It is wrong at the margin for two reasons, and a third, practical reason also favors a lean harness.
-**A clean message protocol.** No environment metadata stapled to user messages. The model receives the conversation: user turns, assistant turns, tool results.
+The first reason is mechanical: attention is a fixed budget that gets divided. Self-attention weighs every Token against every other. When a request grows from 20K to 60K Tokens, the decisive parts, such as the actual error and the actual constraint, hold a smaller share. Five rules that are followed beat fifty that compete, and five tools chosen correctly beat thirty that widen the search.
-## 4. Why less wins
+The second reason is that redundant instructions cost more than Tokens. Rules that restate training data add no capability; they add the suggestion that judgment is unwanted. The resulting failure is not rule-breaking. It is freezing on a case the rules did not cover.
-The intuition that more context means better decisions is not stupid. It is wrong at the margin, for two reasons.
+The third reason is practical: portability. Post-training binds a model to the *protocol*, not to a harness, and every serious model trains on the same function-calling contract. From the model's side, a lean harness is just a standard request that happens to be short. That is why models from several vendors, plus the open-weight GLM, all did well through the same minimal wrapper, and why lean designs keep working when you switch models. For a project that offers 1000+ models behind one interface, portability is the foundation.
-**Attention is a fixed budget that gets divided.** Self-attention weighs every token against every other. Grow a request from 20K to 60K tokens and the decisive parts — the actual error, the actual constraint — hold a smaller share. Five rules that are followed beat fifty that compete; five tools chosen correctly beat thirty that widen the search.
+The same reasoning explains where our own benchmark numbers land. In those runs, each harness used the model it is normally paired with: DeepSeek V4 Pro on PenguinHarness, Claude Opus 4.8 on Claude Code, and GPT-5.5 on Codex.
-**Redundant instruction costs more than tokens.** Rules restating training data do not add capability, they add the suggestion that judgment is unwanted. The failure mode is not rule-breaking — it is freezing on the case the rules did not cover.
+- **Complex data analysis.** PenguinHarness had the highest accuracy of the three harnesses we tested, 66.67% against 53.33% for both others. It cost $0.55 against Claude Code's $38.48, roughly 1/70 of the bill.
+- **Coding.** PenguinHarness ties Codex at 71.25% and trails Claude Code's 86.25%. The suite cost $3.81, against $220.08 for Codex and $146.97 for Claude Code.
-There is a third, practical reason: **portability**. Post-training binds models to the *protocol*, not to a harness. Every serious model trains on the same function-calling contract. From the model's side, a lean harness is just a standard request that happens to be short — which is why several vendors' models plus open-weight GLM all did well through the same minimal wrapper, and why lean designs keep working when you switch models. For a project whose proposition is 1000+ models behind one interface, that is the foundation.
+We do not claim to beat a frontier model on every axis. We claim that the quality gap is one to two orders of magnitude smaller than the price gap.
-It is also why our own numbers land where they do. On complex data analysis, PenguinHarness on DeepSeek V4 Pro took the highest accuracy of the three harnesses we tested (66.67% against 53.33% for both) at **$0.55** against Claude Code's **$38.48** — roughly 1/70 the bill. On coding we tie Codex at 71.25% and trail Claude Code's 86.25%, but the suite cost **$3.81** against **$220.08** and **$146.97**. We do not claim to beat a frontier model on every axis. We claim the quality gap is one to two orders of magnitude smaller than the price gap.
+## What minimalism must not cost
-## 5. What minimalism must not cost
+This is where we part company with minimalism as a philosophy. A lean context must not come at the cost of what makes an autonomous process safe on a real machine.
-Here is where we part company with minimalism as a philosophy.
+Stripping a harness down is easy if you strip out those safeguards too. Pi's own README says plainly that it "does not include a built-in permission system", and suggests containers instead. That is a reasonable trade for a personal CLI. It is not a trade an enterprise can make.
-Stripping a harness down is easy if you also strip out what makes an autonomous process safe on a real machine. Pi's own README is upfront that it *"does not include a built-in permission system"* and suggests containers instead. Reasonable for a personal CLI. Not a trade an enterprise can make.
+PenguinHarness treats safety and observability as load-bearing. They are cheap in context because they live in the runtime rather than in the prompt:
-We treat safety and observability as load-bearing, and they are cheap in context precisely because they live in the runtime rather than the prompt:
+- Every tool call gets exactly one approval decision, in one of four approval modes: `allow-all`, `deny-all`, `read-only`, or `always-ask`. The SDK denies by default when no approver is supplied, so nothing runs unattended by accident.
+- Every decision is audited in the Trace as an `approval_decision` event.
+- Tools never throw into the engine. Failures become tool output that the model reads and reacts to. This is also why a lean prompt is safe: the environment reports its own errors clearly enough that the prompt does not have to anticipate them.
-- **Every tool call gets exactly one approval decision**, in one of four modes — allow-all, deny-all, read-only, always-ask. The SDK denies by default when no approver is supplied, so nothing runs unattended by accident.
-- **Every decision is audited** to the Trace as an `approval_decision` event.
-- **Tools never throw into the engine.** Failures become tool output the model reads and reacts to — which is also why a lean prompt is safe: the environment reports its own errors clearly enough that the prompt does not have to anticipate them.
+None of this adds Tokens to a turn, and every decision stays auditable.
-Zero extra tokens per turn, fully auditable. Discipline in the context window; rigor in the runtime.
+## Conclusion
-## 6. The takeaway
+The result worth internalizing is not that simple harnesses are cheaper. It is that at the top of a real benchmark, on real pull requests, the simplest harness produced the best result, and did so by sending less.
-The result worth internalizing is not that simple harnesses are cheaper. It is that at the top of a real benchmark, on real pull requests, **the simplest harness produced the best result** — and did it by sending less.
+If you build agents, the audit is short:
-If you are building agents, the audit is short. How many tools does your model see, and how many re-implement a shell? What is your hard cap on tool output? How many lines of your system prompt teach the model things it learned in pre-training? What gets injected into every message?
+- How many tools does your model see, and how many of them re-implement a shell?
+- What is your hard cap on tool output?
+- How many lines of your system prompt teach the model things it learned in pre-training?
+- What gets injected into every message?
-Every answer is a line item, charged on every turn, for the life of the task.
+Each answer is a line item, charged on every turn, for the life of the task. To try PenguinHarness, install it and start the Web App:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
@@ -111,7 +145,7 @@ penguin web
---
-- **Read the internals**: [Tools & Approval](https://penguin.ooo/docs/tools) · [The Agent Loop](https://penguin.ooo/docs/agent-loop) · [Skills](https://penguin.ooo/docs/skills)
+- **Read the internals**: [Tools & Approval](https://penguin.ooo/docs/tools) · [The Agent Loop](https://penguin.ooo/docs/agent-loop) · [Skills & Plugins](https://penguin.ooo/docs/skills)
- **Come argue with us**: [GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**Sources**: [Databricks — Benchmarking Coding Agents on Databricks' Multi-Million Line Codebase](https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase) · [Pi (earendil-works/pi)](https://github.com/earendil-works/pi) · [SaladDay, "Less is More"](https://x.com/Salad95238547/status/2079508549382644194)
diff --git a/packages/landing/content/blog/simple-harness-is-all-you-need.zh.md b/packages/landing/content/blog/simple-harness-is-all-you-need.zh.md
index 79c91ff8..8f071fc5 100644
--- a/packages/landing/content/blog/simple-harness-is-all-you-need.zh.md
+++ b/packages/landing/content/blog/simple-harness-is-all-you-need.zh.md
@@ -2,112 +2,141 @@
title: "精简的 Harness 就够了"
date: 2026-07-22
category: perspectives
-excerpt: Databricks 拿自家百万行代码库里的真实 PR,评测了多个 coding agent harness。全场最高分不属于功能最全的那个 harness,而属于最简单的那个,成本还只有一半左右。本文讲清楚上下文纪律为什么胜过功能数量,以及 PenguinHarness 怎么把这个判断写进了代码。
+excerpt: Databricks 拿约一百个真实 Pull Request 评测编程 Agent,通过率最高的是最简单的 Harness,成本还只有一半左右。本文认为 Harness 本质上是一份上下文预算,并介绍 PenguinHarness 如何围绕这个判断构建。
---
-按直觉想,功能丰富的 Agent harness 应该赢过精简的那个:工具更多、上下文更全、脚手架更厚,决策自然更好。整个品类就是建立在这个直觉上的。
+> 本文基于 PenguinHarness 0.1.1 撰写,之后的版本在部分细节上可能有所不同。
-Databricks 拿真实工作检验了它——从自家百万行的生产级 monorepo 里挑出约一百个 Pull Request,把此前抽走的测试恢复回去跑一遍来判分。结果是这样的:
+**Agent Harness** 是包在语言模型外面的那层软件,决定每次请求里放什么:系统提示词、工具定义和消息历史。按常见的直觉,Harness 越大,Agent 越强。工具更多、上下文更全、脚手架更厚,决策理应更好,整个品类就是建立在这个信念上的。
-![Databricks 的 Pareto 图:任务通过率对单任务成本。前沿几乎被精简的 Pi harness 占满,全图最高分是跑在 Pi 上的 Opus 4.8](/blog-assets/databricks-pareto.png)
+本文的观点正好相反。Databricks 用真实 Pull Request 做了一次评测,最简单的 Harness 拿到最高分,成本还只有一半左右;Databricks 把原因归结为它每轮发送的上下文更少。
-_横轴是单任务成本,纵轴是整体通过率,红点构成 Pareto 前沿。图片来源:[Databricks](https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase)。_
+## 证据:一次基于真实 Pull Request 的评测
-请仔细看这张图的顶部,因为那里的结论和直觉完全相反。**全场最高的通过率,约 90%,属于跑在 [Pi](https://github.com/earendil-works/pi) 上的 Opus 4.8**——而 Pi 的整个内核只有读、写、编辑,加一个 shell。同一个模型跑在 Claude Code 上、开到最高档,分数略低,单任务成本却是它的两倍左右。而 Pareto 前沿上的点,大部分都是 Pi。
+Databricks 拿真实工作检验了这个直觉:从自家数百万行代码的生产 monorepo 里挑出约一百个 Pull Request,把事先抽走的测试恢复回去再运行,以此给每次运行判分。结果如下:
-精简的那个 harness 不只是在价格上守住了阵地。**在榜首,它赢了。**
+![Databricks 评测的散点图:编程 Agent 的通过率对单任务成本。红点标出 Pareto 前沿,前沿上大部分是精简的 Pi Harness,全图最高点是跑在 Pi 上的 Opus 4.8](/blog-assets/databricks-pareto.png)
-Databricks 自己很谨慎,我们也该同样谨慎:他们明确说过,这里的教训**不是**某个 harness 永远更便宜,也**不是**厂商自家的 harness 更差。这张图本身就佐证了这份谨慎——Opus 跑在 Pi 上开 `max` 档时只有 81% 左右,明显低于同等花费下的 Claude Code。**精简不是保票。** 但方向不会看错,而他们对机制的解释只有一句话:
+_横轴是单任务成本,纵轴是通过率,红点构成 Pareto 前沿。图片来源:[Databricks](https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase)。_
-> Pi 每轮发送的上下文大约少三倍。它把工作集管得更紧,用更少的轮次完成了任务。
+图的顶部和直觉正好相反。全场最高的通过率约 90%,属于跑在 [Pi](https://github.com/earendil-works/pi) 上的 Opus 4.8,而 Pi 的全部内核只有读、写、编辑加一个 shell。同一个模型跑在 Claude Code 上、开到最高档,得分略低,单任务成本却是它的两倍左右。Pareto 前沿指的是没有其他运行能在成本和通过率上同时胜过的那些运行,前沿上的点大部分是 Pi。
-还有一个细节值得一提,因为这么做的人比应该有的少得多:他们拒绝用模型来判分,理由是那样会奖励"听起来对",而不是"真的对"。
+精简的 Harness 不只是价格上不吃亏。在榜首,它赢了。
-## 一、Harness 的本质是一份上下文预算
+Databricks 很谨慎,没有过度引申,我们也一样。他们明确说过,这里的教训不是某个 Harness 永远更便宜,也不是厂商自家的 Harness 更差。图本身也佐证了这份谨慎:Opus 跑在 Pi 上开 `max` 档时只有 81% 左右,明显低于同等花费下的 Claude Code。精简不是保票。但方向依然清楚,Databricks 用两句话解释了背后的机制:
-模型是 API 背后的一个函数。它接收 system prompt、工具定义、消息历史,返回文本和工具调用。这份契约是固定的,也是公开的。**除此之外的一切——所有决定"这个请求里放什么"的软件——就是 harness。**
+> 「Pi 每轮发送的上下文少了大约三分之二。它对上下文管理得更好,工作集更紧凑,完成任务所需的运行次数也更少。」
-也就是说,harness 从头到尾只做一类决策:**有限的上下文窗口,究竟被什么占着**。它不是一张功能清单,而是一份替模型花出去的预算,每一轮都要重花一次。
+方法上还有一个选择值得一提,因为肯这样做的评测并不多:Databricks 拒绝用模型来判分,理由是那样会「奖励听起来对,而不是真的对」。
-换了这个视角,那张图立刻就讲得通了:两个 harness 调的是同一个模型,跑的不是不同的智能,而是不同的预算——**而花得更少的那个,分数更高。**
+## Harness 是一份上下文预算
-## 二、重量到底堆在哪里
+模型是 API 背后的一个函数:接收系统提示词、工具定义和消息历史,返回文本和工具调用。这份契约是固定的,也是公开的,所以 Harness 只做一种决策:每一轮,模型的上下文窗口里放什么。
-上下文膨胀从来不是一个糟糕的决定,而是四个各自都说得通的决定,在每一轮里复利叠加。
+上下文窗口是模型在一次请求里能关注到的全部文本,长度有限。所以 Harness 做的每件事都是分配:每一轮都在替模型花一笔预算。两个 Harness 调用同一个模型,跑的不是不同的智能,而是不同的预算。在 Databricks 的数据里,花得少的那个得分更高。
-**工具面。** 每个工具在**每一次**请求里都要付出名字、描述和完整 JSON Schema 的代价。三十个工具不等于三十份便利,而是一笔常驻的税,外加一个更大的、够模型迷路的决策空间。而那些边际工具,往往正是在重新实现 shell 早就有的能力。
+## 上下文负担堆在哪里
-**工具输出。** 一次依赖安装吐出几千行。这些输出不是只计费一次,它们会变成历史,在之后的每一轮里被重新发送。**不设上限的工具输出,是把便宜任务变贵最快的途径。**
+上下文膨胀从来不是某一个糟糕决定的结果,而是四个各自说得通的决定在每一轮里不断叠加的结果。
-**System prompt。** 冗长的行为守则,编码的是模型本来就有的判断力。告诉一个前沿模型别硬编码密钥,等于花 token 复述它的训练数据。更微妙的是,规定得太细本身就在暗示模型的判断不被信任,于是碰上规则没覆盖的情形,它反而更容易犹豫——而那恰恰是最需要它自己拿主意的时候。
+### 工具面
-**每轮注入。** 环境快照、状态块、被反复重发的配置文件,统统钉在每条消息上。单看微不足道,结构上却是永久的。
+每个工具的名字、描述和完整 JSON Schema,在**每一次**请求里都要付一遍。三十个工具不等于三十份便利,而是一笔常驻的税,外加一个更大的决策空间,模型容易在里面迷路。那些边际工具,通常只是在重新实现 shell 已经能做的事。
-这些都不是错的想法,只是**没被定价**的想法。
+### 工具输出
-## 三、PenguinHarness 是怎么做的
+装一次依赖就能吐出几千行。这些输出不是只计费一次:它们会变成历史,在之后的每一轮里重新发送。不设上限的工具输出,是把便宜任务变贵最快的途径。
-在这份评测出现之前,我们就下了这个赌注,而且它写在源码里,不在宣传页上。下面每个数字都能在仓库里核对。
+### 系统提示词
-**六个工具,而且完全没有文件工具。** PenguinHarness 内置[六个工具](https://penguin.ooo/docs/tools),任一会话实际只看到五个——两个图像工具按模型类别互斥。
+冗长的行为守则,写下的是模型本来就有的判断力。告诉一个前沿模型别硬编码凭据,等于花 Token 复述它的训练数据。更糟的是,规定得太细,等于暗示你不信任模型自己推理,结果恰恰在规则没料到的情形里,模型反而犹豫。
+
+### 每轮注入
+
+环境快照、状态块、反复重发的配置文件,都钉在每条消息上。单个很小,却每一轮都甩不掉。
+
+这些都不是错的想法,问题在于没人给它们标价。
+
+## PenguinHarness 是怎么做的
+
+这个赌注我们在那份评测出现之前就下了,它写在源码里,不在宣传页上。本节每个细节都能在仓库的 `v0.1.1` 标签下核对。
+
+### 六个工具,没有文件工具
+
+PenguinHarness 0.1.1 内置[六个工具](https://github.com/Prism-Shadow/penguin-harness/blob/v0.1.1/packages/docs/content/tools.zh.md),任一会话实际只看到五个,因为两个图像工具按模型类别互斥。
| 工具 | 作用 |
| --- | --- |
| `exec_command` | 通过 `bash -lc` 执行 shell 命令,流式返回 stdout/stderr |
-| `input_command` | 驱动运行中的命令:写 stdin、发送 Ctrl-C、轮询输出 |
+| `input_command` | 驱动运行中的命令:写入 stdin、发送 Ctrl-C、轮询输出 |
| `run_subagent` / `input_subagent` | 把子任务委派给子 Agent,之后轮询或追加指令 |
| `read_image` / `describe_image` | 返回图像,或交给视觉模型转成文字描述 |
-没有 read 工具,没有 write 工具,没有 edit 工具,没有 glob,也没有 grep。读、写、编辑、搜索全部走 shell,因为 shell 本来就能做这些,模型本来就会用它。当一个四工具的最小内核把 read、write、edit 三个名额花在文件系统上时,**我们只花一个**。我们不宣称绝对工具数最少(论内核,Pi 比我们还紧一个),我们宣称的是:**在"Agent 每天真正在做的事"上,我们的 schema 面积最小。**
+0.1.1 里没有 read 工具、write 工具、edit 工具,也没有 glob 和 grep。读、写、编辑、搜索全部走 shell,因为 shell 本来就能做这些事,模型也本来就会用。一个四工具的极简内核要把三个名额(read、write 和 edit)花在文件系统上,PenguinHarness 只花一个。我们不宣称工具的绝对数量最少,Pi 的内核比我们还少一个。我们宣称的是,在 Agent 每天真正在做的事上,我们的 schema 面积最小。
+
+### 72 行的系统提示词
+
+0.1.1 的默认模板在替换占位符之前是 72 行、约 6,500 字符([源码](https://github.com/Prism-Shadow/penguin-harness/blob/v0.1.1/packages/core/src/state/default-config.ts))。内容包括角色、成功标准、约束、停止规则、文件系统布局,外加一小段建议工作流,然后就结束了。
+
+### 输出默认设上限
+
+每次工具调用的输出都截断在 16,000 字符,由 Environment 在一处统一执行。退出码追加在**截断窗口之外**,哪怕长输出截掉了一部分,告诉模型命令成没成功的那一行也还在。
+
+### Skill 在用到之前只占一行
+
+系统里没有 Skill 工具。提示词里只带每个 Skill 的名字和一行描述,需要时 Agent 再用一条普通的 shell 命令读取正文。用不到的 Skill,只占一行。
+
+### 压缩进干净的上下文
-**72 行的 System Prompt。** 默认模板在变量替换前是 72 行、约 6,600 字符([源码](https://github.com/Prism-Shadow/penguin-harness/blob/main/packages/core/src/state/default-config.ts))。角色、成功标准、约束、停止规则、文件系统布局,外加一小段建议工作流,然后就结束了。
+超过 128,000 Token 后,引擎把对话摘要成一段 `<context_summary>`,然后在**全新的**上下文里继续,而不是接在一段已经臃肿的历史后面。这样一来,一个 Trace 文件恰好对应一个模型上下文。
-**输出上限是默认行为。** 每次工具调用截断在 16,000 字符,由 Environment 统一执行。退出码被追加在**截断窗口之外**,所以哪怕输出中段被砍掉,那条告诉模型"命令到底成没成"的信息依然还在。
+### 干净的消息协议
-**用不到就不花钱的 Skills。** 系统里没有 skill 工具。Prompt 只带上每个 skill 的名字和一行描述,正文等到需要时用一条普通 shell 命令读进来。这次用不到的 skill,只花你一行的代价。
+用户消息上不钉任何环境元数据。模型收到的就是对话本身:用户轮、助手轮和工具结果。
-**压缩之后是干净的上下文。** 超过 128,000 tokens 后,引擎把历史摘要成 `<context_summary>`,在一个**全新的**上下文里继续,而不是接在一段已经臃肿的历史后面——于是一个 trace 文件恰好对应一个模型上下文。
+## 为什么更少的上下文反而赢
-**干净的消息协议。** 不把环境元信息钉在用户消息上。模型收到的就是对话本身:用户轮、助手轮、工具结果。
+「上下文越多,决策越好」这个直觉并不离谱,只是在边际上不成立,原因有两个;另外还有一个实际的理由,同样支持精简的 Harness。
-## 四、为什么"更少"反而赢
+第一个原因在机制上:注意力是一份固定的预算,要分给所有 Token。Self-attention 让每个 Token 都和其余所有 Token 计算权重。请求从 20K Token 涨到 60K Token,真正起决定作用的部分,比如那条实际的报错、那条实际的约束,占的份额就变小了。五条真正执行到位的规则,胜过五十条互相争抢注意力的规则;五个选对的工具,胜过三十个把搜索范围撑大的工具。
-"上下文越多,决策越好"这个直觉并不蠢,只是在边际上不成立,原因有两个。
+第二个原因是,冗余指令的代价不止是 Token。复述训练数据的规则不会增加能力,只会暗示模型「这里不需要你判断」。由此带来的失败不是违反规则,而是在规则没覆盖的情形里卡住。
-**注意力是固定预算,而且会被摊薄。** Self-attention 让每个 token 都要和其余所有 token 算权重。当请求从 20K tokens 涨到 60K,真正起决定作用的那部分——那条实际的报错、用户实际的约束——占的份额就变小了。**五条被执行到位的规则,胜过五十条互相抢注意力的规则;五个被正确选中的工具,胜过三十个把搜索空间撑大的工具。**
+第三个原因更实际:可移植性。后训练绑定的是**协议**,不是 Harness,所有像样的模型都在同一套 function calling 契约上训练。从模型的角度看,精简的 Harness 不过是一个恰好比较短的标准请求。这就是为什么多家厂商的模型加上开放权重的 GLM,在同一个精简封装下都表现不错,也是为什么精简的设计在你换模型之后照样好用。对一个用同一套接口接入 1000+ 模型的项目来说,可移植性是地基。
-**冗余指令的代价不止是 token。** 复述训练数据的规则不增加能力,只增加"这里不需要你判断"的暗示。它的失效模式不是模型违反规则,而是**模型在规则没覆盖的场景下卡住**。
+我们自己的评测结果也能用同一个道理解释。这组评测里,每个 Harness 都搭配它平时常用的模型:PenguinHarness 配 DeepSeek V4 Pro,Claude Code 配 Claude Opus 4.8,Codex 配 GPT-5.5。
-还有第三个更实际的理由:**可移植性**。后训练绑定的是**协议**,不是 harness。所有严肃的模型都在同一套 function calling 契约上训练。从模型的角度看,一个精简的 harness 不过是一个恰好比较短的标准请求——这就解释了为什么多家厂商的模型、加上开放权重的 GLM,在同一个精简 harness 下都表现不错,也说明精简的设计最有可能在你换模型之后依然好用。对于一个价值主张是"一套接口接 1000+ 模型"的项目,这是地基。
+- **复杂数据分析**:在我们测试的三个 Harness 里,PenguinHarness 准确率最高,为 66.67%,另外两个都是 53.33%。花费 $0.55,Claude Code 是 $38.48,账单约为后者的 1/70。
+- **编程**:PenguinHarness 与 Codex 同为 71.25%,落后于 Claude Code 的 86.25%。整套题我们花了 $3.81,Codex 是 $220.08,Claude Code 是 $146.97。
-我们自己的数字落在那个位置,也是同一个道理。复杂数据分析上,PenguinHarness 搭配 DeepSeek V4 Pro 拿到了三者中最高的准确率(66.67%,两个对手各 53.33%),花费 **$0.55**,Claude Code 是 **$38.48**,账单约为其 1/70。编程题上,我们和 Codex 以 71.25% 打平,落后于 Claude Code 的 86.25%,但整套题我们花了 **$3.81**,它们分别是 **$220.08** 和 **$146.97**。我们不宣称在每个维度上都赢过前沿模型,我们宣称的是:**效果的差距,比价格的差距小一到两个数量级。**
+我们不宣称在每个维度上都赢过前沿模型。我们宣称的是,效果的差距比价格的差距小一到两个数量级。
-## 五、精简不该牺牲什么
+## 精简不该牺牲什么
-这里是我们和"极简主义"分道扬镳的地方。
+这里是我们和「极简主义」分道扬镳的地方。上下文可以精简,但不能因此丢掉让一个自主进程能在真机上安全运行的那些东西。
-要把 harness 削薄其实很容易,前提是你连"让一个自主进程敢在真机上跑"的那部分也一并砍掉。Pi 的 README 就坦率写明它**不包含内置权限系统**,并建议改用容器隔离。对个人 CLI 来说这是合理取舍,对企业不是。
+如果连这些保障也一并砍掉,把 Harness 削薄就很容易。Pi 自己的 README 坦率写明它「不包含内置权限系统」,并建议改用容器。对个人 CLI 来说这是合理的取舍,企业却做不了这种取舍。
-我们把安全和可观测当成承重结构,而它们在上下文里几乎不花钱,恰恰因为**它们活在运行时,不活在 prompt 里**:
+PenguinHarness 把安全和可观测性当作承重结构。它们在上下文里几乎不占开销,因为它们在运行时里实现,而不是写在提示词里:
-- **每次工具调用恰好触发一次审批决策**,四种模式:全部允许、全部拒绝、只读放行、每次询问。SDK 在没有注入审批回调时**默认拒绝**,不会有东西在无人值守时意外跑起来;
-- **每个决策都以 `approval_decision` 事件写入 Trace**,形成完整审计记录;
-- **工具永远不向引擎抛异常**。失败会收敛成模型读得懂、也能据此反应的工具输出——这也正是精简 prompt 依然安全的原因:**环境把自己的错误讲清楚了,prompt 就不必去替它预判。**
+- 每次工具调用恰好触发一次审批决策,审批模式有四种:`allow-all`、`deny-all`、`read-only` 和 `always-ask`。没有注入审批回调时,SDK 默认拒绝,不会有东西在无人值守时意外跑起来。
+- 每个决策都以 `approval_decision` 事件写入 Trace,留作审计。
+- 工具永远不向引擎抛异常。失败会变成工具输出,模型读到后据此应对。这也是精简的提示词依然安全的原因:环境把自己的错误讲得足够清楚,提示词就不必替它预判。
-每轮零额外 token,同时完全可审计。**上下文窗口里讲纪律,运行时里讲严谨。**
+这些机制不给任何一轮增加 Token,每个决策也始终可以审计。
-## 六、结论
+## 结论
-值得记住的结论不是"精简的 harness 更便宜",而是:在一套基于真实 Pull Request 的评测里,**最简单的那个 harness 拿到了最好的成绩**——靠的是发得更少。
+值得记住的结论不是「简单的 Harness 更便宜」,而是在一套基于真实 Pull Request 的评测里,榜首属于最简单的 Harness,它靠的是发得更少。
-如果你在构建 Agent,自检清单很短:
+如果你在构建 Agent,自查清单很短:
-- 你的模型看到多少个工具?其中多少个在重新实现 shell?
-- 你的工具输出硬上限是多少?
-- 你的 system prompt 里,有多少行在教模型它预训练时就学会的事?
-- 每条消息里到底被注入了什么?
+- 你的模型能看到多少个工具?其中多少个在重新实现 shell?
+- 工具输出的硬上限是多少?
+- 你的系统提示词里,有多少行在教模型预训练时就学会的事?
+- 每条消息里都注入了什么?
-每一个答案,都是一个**按轮计费、贯穿整个任务生命周期**的成本项。
+每个答案都是一个成本项,按轮计费,贯穿整个任务。想试试 PenguinHarness,就安装它并启动 Web App:
```bash
curl -fsSL https://penguin.ooo/install.sh | sh
@@ -116,7 +145,7 @@ penguin web
---
-- **读实现**:[工具与审批](https://penguin.ooo/docs/tools) · [Agent Loop](https://penguin.ooo/docs/agent-loop) · [Skills](https://penguin.ooo/docs/skills)
-- **来讨论**:[GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
+- **读实现**:[工具与审批](https://penguin.ooo/docs/tools) · [Agent 运行循环](https://penguin.ooo/docs/agent-loop) · [技能与插件](https://penguin.ooo/docs/skills)
+- **来找我们讨论**:[GitHub](https://github.com/Prism-Shadow/penguin-harness) · [Discord](https://discord.gg/eFHKqqcU3D)
**参考来源**:[Databricks — Benchmarking Coding Agents on Databricks' Multi-Million Line Codebase](https://www.databricks.com/blog/benchmarking-coding-agents-databricks-multi-million-line-codebase) · [Pi (earendil-works/pi)](https://github.com/earendil-works/pi) · [SaladDay《Less is More》](https://x.com/Salad95238547/status/2079508549382644194)
diff --git a/packages/landing/test/blog-content.test.ts b/packages/landing/test/blog-content.test.ts
new file mode 100644
index 00000000..968d7201
--- /dev/null
+++ b/packages/landing/test/blog-content.test.ts
@@ -0,0 +1,112 @@
+/**
+ * Blog content integrity, the counterpart of packages/docs/test/content.test.ts for the blog:
+ * content/blog is read from disk (no Vite glob), so the checks run under plain node. Three
+ * things a post can get wrong today without anything failing:
+ *
+ * - A missing translation. src/lib/blog.ts documents a deliberate fallback ("a post missing the
+ * active language falls back to the other one"), so deleting a .zh.md serves the English text
+ * on the Chinese site and no test notices.
+ * - Frontmatter that disagrees across the pair. `date`, `category` and `pinned` feed comparePosts,
+ * so a one-character divergence orders one language's list differently — and only that one's.
+ * - A link to a docs page that does not exist. Posts send readers to
+ * https://penguin.ooo/docs/<slug>, and a renamed or dropped page leaves a 404 behind.
+ * packages/docs/src/lib/nav.ts is deliberately kept import.meta-free so a test can import
+ * DOC_SLUGS under plain node, which is what this one does.
+ *
+ * Deliberately not checked here: /blog-assets/<name>. Those bytes live in the separate
+ * Prism-Shadow/penguin-harness-community repository, so this repository holds nothing to resolve
+ * an asset name against; a typo'd name can only be caught where the files are.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { DOC_SLUGS } from "../../docs/src/lib/nav";
+import { parseFrontmatter } from "../src/lib/frontmatter";
+
+const contentDir = join(__dirname, "..", "content", "blog");
+const LANGS = ["en", "zh"] as const;
+
+/** The categories src/lib/blog.ts maps; anything else silently becomes "news". */
+const CATEGORIES = new Set(["news", "practice", "perspectives", "changelog"]);
+
+const files = readdirSync(contentDir).filter((f) => f.endsWith(".md"));
+
+/** Post slugs in the directory, from the `<slug>.<lang>.md` file names. */
+const slugs = [
+ ...new Set(
+ files
+ .map((file) => /^(.+)\.(zh|en)\.md$/.exec(file)?.[1])
+ .filter((slug): slug is string => slug !== undefined),
+ ),
+].sort();
+
+const read = (slug: string, lang: string) =>
+ parseFrontmatter(readFileSync(join(contentDir, `${slug}.${lang}.md`), "utf8"));
+
+/**
+ * Docs pages a post links to: every `https://penguin.ooo/docs/<slug>` occurrence, whether it sits
+ * in a Markdown link, an autolink or bare prose. A trailing slash, an anchor and a query string
+ * are all stripped — the router only ever sees the slug.
+ */
+function docsLinks(body: string): string[] {
+ const slugs = [...body.matchAll(/https:\/\/penguin\.ooo\/docs\/([^)\s"'<>]*)/g)].map((match) =>
+ match[1]!.split(/[#?]/)[0]!.replace(/\/+$/, ""),
+ );
+ // The bare docs root names no page, so it is always valid.
+ return slugs.filter((slug) => slug !== "");
+}
+
+describe("blog content integrity", () => {
+ it("names every content file <slug>.<zh|en>.md", () => {
+ expect(files.length).toBeGreaterThan(0);
+ for (const file of files) {
+ expect(/^(.+)\.(zh|en)\.md$/.test(file), `unparsable content file name ${file}`).toBe(true);
+ }
+ });
+
+ it("provides zh and en files with a title, an excerpt and a body for every post", () => {
+ expect(slugs.length).toBeGreaterThan(0);
+ for (const slug of slugs) {
+ for (const lang of LANGS) {
+ const name = `${slug}.${lang}.md`;
+ // A missing file is served by the other language's text, so presence is the whole check.
+ expect(files, `missing content file ${name}`).toContain(name);
+ const { meta, body } = read(slug, lang);
+ expect(meta.title, `missing title in ${name}`).toBeTruthy();
+ expect(meta.excerpt, `missing excerpt in ${name}`).toBeTruthy();
+ expect(body.length, `empty body in ${name}`).toBeGreaterThan(0);
+ }
+ }
+ });
+
+ it("gives both languages of a post the same date, category and pinned flag", () => {
+ for (const slug of slugs) {
+ const en = read(slug, "en").meta;
+ const zh = read(slug, "zh").meta;
+ expect(zh.date, `${slug}: date differs between en and zh`).toBe(en.date);
+ expect(zh.category, `${slug}: category differs between en and zh`).toBe(en.category);
+ // `pinned` is absent on an unpinned post, so the flag is compared, not the raw text.
+ expect(zh.pinned === "true", `${slug}: pinned differs between en and zh`).toBe(
+ en.pinned === "true",
+ );
+ }
+ });
+
+ it("gives every post a date and a known category", () => {
+ for (const slug of slugs) {
+ for (const lang of LANGS) {
+ const { meta } = read(slug, lang);
+ expect(meta.date, `malformed date in ${slug}.${lang}.md`).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+ expect([...CATEGORIES], `unknown category in ${slug}.${lang}.md`).toContain(meta.category);
+ }
+ }
+ });
+
+ it("links only to docs pages the docs site navigates", () => {
+ for (const file of files) {
+ const { body } = parseFrontmatter(readFileSync(join(contentDir, file), "utf8"));
+ const dangling = docsLinks(body).filter((slug) => !DOC_SLUGS.includes(slug));
+ expect(dangling, `links to non-existent docs pages in ${file}`).toEqual([]);
+ }
+ });
+});