内容
# gizza 工具
一个小型、单一用途的计算工具库 — 计算器、转换器、文本/数据实用程序、加密、图像和视频（ffmpeg 支持）等 — 每个工具都作为一个 [WAFER](https://github.com/wafer-run/wafer-run) WASM 模块实现，并通过三个接口以相同的方式暴露：无头 CLI、用于代理的 MCP 服务器和静态、支持 SEO 的网页。每个工具都有一个单一的真实来源（模块的 `info()`/schema）；不需要为不同的接口重新实现工具。
这些工具的托管、基于浏览器的版本 — 聊天界面、模型选择器等 — 位于 **[gizza.ai](https://gizza.ai)**。本仓库是支持它的公共、MIT 许可的工具包：工具实现（`blocks/`）、`gizza` CLI（`cli/`）和静态工具页面生成器（`tools/generator`）。
## 布局
- `blocks/<slug>/` — 每个工具一个 WASM 模块（`core/` 纯逻辑，`web/` 浏览器绑定，`page/` SEO 文本 + 表单元数据，`manifest.json` schema）。
- `block-utils/` — 跨模块共享的 Rust 帮助程序。
- `cli/` — `gizza` 二进制文件：通过 wasmi 运行时无头运行任意模块。
- `tools/generator/` — 将每个模块的 `page/` 渲染为静态、独立的 HTML 页面（`pkg/tools/<slug>/`）。
- `js/` — 生成的工具页面共享的运行时 JS/CSS。
- `tests/` — 生成的工具页面的 Playwright 端到端测试，以及一些 `node --test` 单元测试套件（`js/*.test.js`）。
- `scripts/` — 工具链引导、工具卫生检查和新建工具脚手架脚本。
## 构建
引导工具链（Rust + wasm 目标、 `wasm-pack` 、Node、ffmpeg）：
```bash
scripts/bootstrap-toolchain.sh
```
构建一个模块的 WASM（重复每个工具，或遍历 `blocks/*`）：
```bash
cd blocks/<slug>
cargo build --target wasm32-wasip1 --release
mkdir -p target
cp target/wasm32-wasip1/release/*.wasm target/block.wasm
```
构建 CLI：
```bash
cargo build --manifest-path cli/Cargo.toml --release # → cli/target/release/gizza
```
从每个模块的 `page/` 元数据中渲染通用（未品牌化）静态工具页面：
```bash
cargo run --manifest-path tools/generator/Cargo.toml -- . # → pkg/tools/<slug>/
```
在本地提供服务：
```bash
python3 -m http.server --directory pkg 8001
```
## CLI：从终端或代理运行工具
`gizza` CLI 启动 wasmi 运行时，加载模块的 `blocks/<slug>/target/block.wasm` 工件，并调度一个工具调用 — 因此每个工具都有一个单一的真实来源（没有单独的 CLI 重新实现）。工具模式来自每个模块的 `info()`。
```bash
# 运行工具 — 位置参数，键=值，或完整 JSON
gizza tool calculator "2*2" # → 4
gizza tool web-fetch url=https://example.com
gizza tool image-resize url=https://…/cat.png width=640 --out thumb.png
gizza tool calculator --json '{"expr":"sqrt(16)"}'
# 发现工具
gizza list # 每个工具的名称 + 描述
gizza describe calculator # 工具的 JSON-Schema 参数
# 机器可读输出，用于脚本/代理
gizza tool calculator "2*2" --json-out # 完整的 {_for_llm,_for_ui} 信封
```
退出代码：`0` ok · `1` 工具错误 · `2` 用法/错误参数 · `3` CLI 不支持。图像/视频工具使用系统的 `ffmpeg`（安装它来使用它们）；仅 GPU 工具（例如 `imagine`）需要浏览器 GPU，因此在此处返回 `unsupported_in_cli` 错误。`gizza list`/`gizza tool` 仅涵盖具有已提交 `target/block.wasm` 工件的模块 — 目前是 `blocks/` 的子集；没有已提交 wasm 的模块仍然会提供页面，但不能从 CLI 运行。
### MCP 服务器
`gizza mcp` 通过模型上下文协议（stdio，换行符分隔的 JSON-RPC）提供相同的工具集 — 使用 MCP 客户端注册它，而不是使用 shell，例如 `claude mcp add gizza -- /path/to/gizza mcp`.
### 适用于代理的 — `SKILL.md`
`SKILL.md`（仓库根目录）是一个关于 `gizza tool …` 协议的小型静态文档，它指向代理到 `gizza list`（实时工具集）和 `gizza describe <name>`（工具的模式）。它故意不枚举工具，因此保持体积小，并且在添加工具时不会漂移。
### 嵌入到另一个程序中
`gizza-cli` 包还为 Rust 程序提供了一个小型库 API — `run_tool(name, json)`、`list_tools()`、`describe_tool(name)` — 无需使用 shell。完整参考： [`cli/README.md`](cli/README.md).
## 测试
```bash
npm install --no-audit --no-fund && npm test # js/*.test.js 单元测试套件
cargo test --manifest-path cli/Cargo.toml
cargo test --manifest-path block-utils/Cargo.toml
cargo test --manifest-path tools/generator/Cargo.toml
# 生成的工具页面 Playwright 测试（在构建页面和模块的 web/pkg 之后）
cd tests && npm install && npx playwright test
```
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何添加或改进工具。所有贡献都在 MIT 许可下进行（参见 [LICENSE](LICENSE)）。
