# PenguinHarness

> 在 NeuroSquad 卡片中运行 PenguinHarness——如何安装、卡片如何工作，以及有哪些须知。

Source: https://docs.neurosquad.ai/zh/agents/penguin

**PenguinHarness** 是 PrismShadow AI 团队推出的开源（Apache-2.0）、本地优先的智能体平台：一个带 Web 应用的服务器，
以及运行在其上的 `penguin chat` 命令。在 NeuroSquad 中，每张 Penguin 卡片都在自己的终端里运行真正的 `penguin chat`。

基于 PenguinHarness 0.2.13 及其 main 分支实测。

## 安装

**1. 安装 penguin 命令**

```bash
npm install -g @prismshadow/penguin-cli
```

需要 Node 24 或更新版本。也可以使用 [penguin.ooo](https://penguin.ooo) 提供的安装脚本。NeuroSquad 的
**Settings → Setup** 可以替你执行 npm 安装。

**2. 添加你的模型**

像平常一样在 Penguin 中设置提供方和模型——卡片会使用它们。卡片也可以改用 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter)
或[你自己的服务器](https://docs.neurosquad.ai/zh/providers/your-servers)。

**3. 添加 PenguinHarness 卡片**

添加一张智能体卡片并选择 **PenguinHarness**。

## 卡片如何工作

NeuroSquad 为自己的数据目录运行**自己的 Penguin 服务器**，在第一张 Penguin 卡片启动时开启，在你退出时停止。
**每张卡片都是一个独立的 Penguin 智能体**（`ns_<卡片>`），拥有自己的钩子、MCP 服务器和说明。你的 Penguin
项目配置——你的模型和密钥——每次启动时都会复制进来；你自己的 `~/.penguin` 从不被改写。

## 可用功能

- **准确的状态。** 卡片跟随服务器为其会话提供的状态流——工作中和已完成——由 NeuroSquad 钩子决定哪些调用需要你。
NeuroSquad 自己的工具、`read_file` 和子智能体无需询问即可运行；其他调用会等待 Penguin 自己的
`? Approve this tool call? [Y/n]`，通知会写明这次调用（`PenguinHarness needs your permission: write_file: a.txt`）。
- **箭头。** NeuroSquad 的 MCP 服务器写在卡片的智能体里。Penguin 会为工具拍快照，所以 NeuroSquad 的全部工具一开始就提供，
由箭头在调用时决定；技能或已安装的 MCP 服务器需要卡片下次启动后生效。已安装的服务器每次调用前都会询问。
- **卡片模式。** 钩子拒绝 `exec_command` 和 `input_command`——Penguin 的 shell，也是它上网的唯一途径——危险模式下也一样。
参见[卡片模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)。
- **危险模式无需重启。** 开关打开时，钩子放行每次调用。参见[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)。
- **停止。** 停止按钮、预算刹车和手机上的停止都使用 Penguin 自己的中止 API；聊天保持打开。
- **会话。** 重启后卡片继续同一段对话（`--resume`）；被删除的会话会换成新会话。
- **长时间会话。** 上下文仪表、**Compact**（`/compact`）、速率限制提示、提示词队列、日志和交接。
- **用量。** 每次请求都从 Penguin 的 Trace 文件读取，子智能体单独标记，显示在[用量与费用](https://docs.neurosquad.ai/zh/usage)、
[Run Stats](https://docs.neurosquad.ai/zh/cards/run-stats) 和 [Agent Pulse](https://docs.neurosquad.ai/zh/cards/agent-pulse) 中。
- **模型。** 主智能体可以通过 `agent_set_model` 更换模型，或把对话迁到 Claude Code 再迁回来。OpenRouter 和你自己的服务器
经由 NeuroSquad 的本地中继——磁盘上没有密钥。

## 须知

- **对话保存在 NeuroSquad 的 Penguin 目录中。** 你自己运行 `penguin chat --resume` 不会列出它们；把 `PENGUIN_HOME`
指向该目录并加上 `--agent-id ns_<卡片>` 后就能看到。
- **在卡片里添加的模型**只保留到卡片下次启动——请在你自己的 Penguin 中添加。
- **插件。** [Caveman](https://docs.neurosquad.ai/zh/plugins/caveman)、[记忆](https://docs.neurosquad.ai/zh/plugins/mem0-memory)、[Context7](https://docs.neurosquad.ai/zh/plugins/context7-docs) 和
[Graphify](https://docs.neurosquad.ai/zh/plugins/graphify) 通过一个钩子为每一轮添加文字，而 Penguin 只在 0.2.13 之后的版本才会在每条提示词上运行它；
在 0.2.13 上，它们的工具仍可通过箭头使用。[省令牌](https://docs.neurosquad.ai/zh/plugins/rtk-ai-token-saver)无法工作：Penguin 的钩子不能改写命令。
- **用量栏位。** Penguin 把缓存创建并入输入、把推理并入输出，所以这两栏显示“未报告”；在 Claude 模型上价格因此略微偏低。
- **卡片的 MCP 令牌**保存在其智能体的配置中（Penguin 在那里无法从环境变量读取）。它只用于本机回环、每张卡片各不相同，
并在应用每次运行时更换。

> PenguinHarness 卡片只在本机运行——不支持 WSL 或 SSH 工作区。