内容
<p align="center">
<img src="img/logo.png" alt="PET 项目徽标" width="360">
</p>
# PET 项目
[](LICENSE)
PET 项目是一套工具、技能和 MCP，旨在通过 VICE 模拟器启用智能 Commodore PET 编码和调试。
> Python 包作为 `petlib` 导入，作为 `pet-tools` 安装，并由命令行工具 `pet` 驱动。
## 安装
需要 **Python 3.11+**、**VICE 3.5+**（提供 `xpet` 和 `petcat`）和 **cc65** 套件（`ca65`/`ld65`，用于组装 6502 程序）。然后安装此包。
macOS（Homebrew）：
brew install vice cc65
pip install -e .
Debian / Ubuntu：
sudo apt install vice cc65
pip install -e .
## 快速入门
pip install -e .
pet session start --model pet4032 # 启动模拟的 PET 4032
pet run tests/programs/hello-basic/program.bas # 标记 + 加载 + 运行
pet run tests/programs/hello-asm/program.s # 组装 + 加载 + 运行（需要 cc65）
pet screen # 读取屏幕文本
pet basic type prog.bas --run # 通过键盘输入程序
pet mem read '$8000' 64 # 屏幕 RAM 的十六进制转储
pet break add start # 符号断点（使用 .lbl 符号）
pet wait --break # 阻塞直到触发
pet step 5 && pet reg # 单步调试，检查（PC 注释）
pet continue # 继续
pet disk create work.d64 && pet disk put work.d64 game.prg game
pet session start --disk work.d64 # 启动时附加磁盘
pet disk boot work.d64 # 或在会话中附加和运行
pet rom info # 确定加载的 ROM 集
pet rom disasm CHROUT 16 # 注释的实时反汇编
pet session stop
pet test run mytest.yaml # 声明性 YAML 测试（docs/cli.md 中的格式）
pet test programs # 运行每个示例程序作为测试
每个命令都带有 `--json` 参数，用于机器可读的输出 — 这是 AI 代理的预期接口。
## 支持的机器
每个会话都启动特定的 PET（ `--model`，默认为 `pet4032`）。根据目标选择模型 — 并告诉 AI 代理类似 *"使其适应 4K PET"* 或 *"使用 pet8032 的 80 列屏幕"*：
| 型号 | RAM | 启动时空闲 | BASIC | 屏幕 | 备注 |
|-------|-----|--------------|-------|--------|-------|
| `pet2001-4k` | 4 KB | 3071 字节 | 1.0 | 40×25 | 1977 配置的入门级（PET 2001-4）— 最紧凑的目标。 |
| `pet2001` | 8 KB | 7167 字节 | 1.0 | 40×25 | 8 KB 原始版（2001-8）。不同的零页（jiffy 时钟在 $0200），BASIC 中没有磁盘命令。 |
| `pet3032` | 32 KB | 31743 字节 | 2.0 | 40×25 | 大多数 6502 书籍针对的 BASIC。 |
| `pet4032` | 32 KB | 31743 字节 | 4.0 | 40×25 | **默认**。BASIC 中的磁盘命令（`DLOAD` 等）；演示使用。 |
| `pet8032` | 32 KB | 31743 字节 | 4.0 | 80×25 | 80 列商务机器。屏幕数学更改：一行是 80 字节。 |
| `pet8296` | 128 KB | 31743 字节 | 4.0 | 80×25 | 银行 RAM — BASIC 仍然看到 32 KB；其余部分需要银行切换。 |
每个型号的屏幕都在 `$8000` 处映射到内存；"启动时空闲" 是 BASIC 报告的内容，是 BASIC 程序（或 `SYS` 存根汇编程序）实际可用的预算。
## 与 AI 编码代理一起使用
该工具集旨在由 AI 代理驱动。调试状态在命令之间持续：当代理在断点处停止机器时，它会保持停止状态，同时代理在单独的工具调用中检查内存、寄存器和屏幕。有两种方法可以让代理使用它 — 选择其中一种或两种：
- **CLI** — 每个 `pet` 命令都带有 `--json` 参数。可与 *任何* 可以运行 shell 命令的代理一起使用；无需配置。
- **MCP 服务器** — `pet-tools-mcp` 通过 stdio 公开与 MCP 工具相同的操作。CLI 和 MCP 共享相同的会话，因此它们可以互换。
无论哪种方式，代理都应该在启动前阅读 [`skills/pet-development/SKILL.md`](skills/pet-development/SKILL.md)（PET 工作流程和陷阱）— 以下特定于代理的步骤会自动实现这一点。
用于多个代理的 MCP 配置为以下块：
```json
{
"mcpServers": {
"pet-tools": { "command": "pet-tools-mcp" }
}
}
```
在 **2026 年 7 月**验证了设置符合每个代理的文档；如果某些内容已更改，请检查代理的当前 MCP 文档。
### 任何具有 shell 的代理（最简单 — 在任何地方都有效）
1. 安装（参见上文）— 就是整个设置。
2. 以以下内容开始任务提示： *"阅读 docs/cli.md 和 skills/pet-development/SKILL.md，然后 …"*
### Claude Code
1. 从仓库根目录安装技能，以便 Claude 自动发现它们：
```
mkdir -p .claude/skills && cp -R skills/* .claude/skills/
```
2. （可选）添加 MCP 服务器：`claude mcp add pet-tools -- pet-tools-mcp`
3. 请求您想要的内容 — 例如粘贴 [`demos/`](demos/) 中的提示。
无需编辑 `CLAUDE.md`：安装的技能按需加载，MCP 工具会自我描述。
### OpenAI Codex
1. 添加 MCP 服务器：`codex mcp add pet-tools -- pet-tools-mcp`
（或将 `[mcp_servers.pet_tools]` 添加到 `~/.codex/config.toml`）。
2. Codex 没有技能机制，因此告诉它文档的位置：在仓库的 `AGENTS.md` 中添加一行 — *"对于 Commodore PET 工作，首先阅读 skills/pet-development/SKILL.md 和 docs/cli.md。"*
3. 粘贴 [`demos/`](demos/) 中的提示。
### Cursor
1. 在仓库中创建 `.cursor/mcp.json`（或全局的 `~/.cursor/mcp.json`），
包含上面的 JSON 块。
2. 创建规则（`.cursor/rules/pet.mdc`）或纯文本 `AGENTS.md` — 包含相同的单行： *"对于 Commodore PET 工作，首先阅读 skills/pet-development/SKILL.md 和 docs/cli.md。"*
3. 粘贴 [`demos/`](demos/) 中的提示。
### Gemini CLI
1. 将上面的 JSON 块添加到仓库中的 `.gemini/settings.json`（或全局的 `~/.gemini/settings.json`）。
2. 在 `GEMINI.md` 中添加相同的阅读技能单行。
3. 粘贴 [`demos/`](demos/) 中的提示。
### Google Antigravity
1. 打开 MCP 商店 → **管理 MCP 服务器** → **查看原始配置** 并添加
上面的 JSON 块（文件是 `~/.gemini/config/mcp_config.json`）。
2. 在 `AGENTS.md` 中添加阅读技能的单行。
3. 粘贴 [`demos/`](demos/) 中的提示。
## 演示 — 使用您的 AI 代理试用
[`demos/`](demos/) 是一组现成的提示，从基本程序到机器级调试和完整的 6502 汇编 Snake（标题屏幕、关卡、高分）到旗舰：具有声音、波浪和打包磁盘镜像的街机保真入侵者。用法：
1. 设置您的代理（上一节 — 或使用任何 shell 代理，无需设置）。
2. 打开演示文件并复制其提示。
3. 将其粘贴到您的代理中，观看它编写、运行和调试真正的 PET 软件。
参考示例程序（带有预期屏幕输出，可作为回归测试运行 via `pet test programs`）位于
[`tests/programs/`](tests/programs/)。
## 分享您的作品
`pet package` 将源文件转换为任何 VICE 用户都可以运行的内容 — 无需在他们那边安装 pet-tools：
pet package snake.s -o snake.d64 --title SNAKE
这会组装程序并将其写入新磁盘镜像中的第一个文件，以便自动启动。接收者只需安装 VICE：
xpet -model 4032 snake.d64 # 启动测试的 PET 模型，运行 SNAKE
（`pet package` 打印此确切命令；`-model` 参数很重要，因为库存 xpet 启动其自己的默认模型，并且 ROM 行为在 BASIC 版本之间有所不同 — 读取按键的游戏在错误的一个上会无声。）裸 `.prg`（也生成）同样有效，VICE 的文件 → 智能附加也有效。磁盘镜像旅行效果更好：它们携带真正的 CBM 目录，因此 `LOAD"SNAKE",8` 然后 `RUN` 正常工作。
两个工件都不包含 ROM 或此工具集的任何内容。
## 状态
稳定 — 当前版本 **v1.1.0**。完整历史：[CHANGELOG.md](CHANGELOG.md)。
## AI 公告
PET 项目主要由 AI 开发 — Anthropic 的 Claude，通过 Claude Code — 在人类指导下工作：人类设定目标，审查设计和计划，并批准工作；AI 编写规格、计划、代码、测试和文档。每个更改都通过自动化测试套件验证，包括在真实 VICE 模拟器上运行的集成测试，然后再进行。 该项目也 *为* AI 使用而存在 —
这些工具的构建是为了让 AI 代理能够编写和调试 Commodore PET 软件 — 使其成为 AI 构建的开发者工具的示例。
## 许可证
MIT 许可证。注意 VICE 是一个单独的 GPLv2+ 程序，作为子进程调用；它不捆绑在一起，必须单独安装。
ROM 工具读取运行模拟器中的 ROM 字节，并仅提供原始标签注释 — 没有 Commodore 版权代码存在于此仓库中。
