Yaowei Zheng
d4faee3a1e
Branch-length batch covering tooling, the model layer, the Web App and the public surfaces. Highlights: - Changelog: a per-release `changelog/<version>/` tree, grouped by the surface each change touches, with a root CHANGELOG.md holding one line per release. - Dev startup: `scripts/dev-prebuild.mjs` serializes the skills+core prebuild behind a lock and keeps `pnpm install` current; `pnpm dev` runs server+web together. - AgentHub 0.3.3 -> 0.4.0: OmniMessage complete payloads carry one opaque `fidelity` object in place of item-level `signature`/`phase`, threaded verbatim through Trace, replay and resume; malformed classification adapted to the new error types. - Model layer: a model is always referenced by an explicit `(provider, model_id)` pair. The provider is never inferred, guessed or defaulted -- both the catalog inference and the unique-match config resolution are gone, and CLI, SDK, server routes and run_subagent all require the complete pair. Catalog gains the Qwen Token Plan, Qwen Pay-As-You-Go and Fireworks AI gateways, plus an expanded OpenRouter group. - Web App: catalog preset sync and per-group speed test on the Models page, positional slash commands, a markdown renderer, skill-library update reminders, and a vertically centred draft page whose upward menus size themselves to the room available. - Public surfaces: restructured READMEs, the penguin.ooo landing site and blog, refreshed benchmark results for both suites, and the demo videos playing on the landing page. Includes the fixes from a full review of the branch: 23 confirmed findings, among them a provider-inference bug that could send one vendor's API key to another vendor's endpoint, and an Escape handler that destroyed the composer's contents unrecoverably. Verified on the branch head: pnpm test (1127 passing, 7 packages), pnpm typecheck and pnpm format:check clean, Playwright e2e 14/14.
5.6 KiB
Contributing to PenguinHarness
Thanks for helping build PenguinHarness! This guide covers the workspace setup, daily commands, quality gates, and the repo's working rules.
Prerequisites
- Node >= 24
- pnpm 10 (
corepack enableornpm install -g pnpm)
Setup and daily commands
pnpm install
pnpm build # build first: core's exports point at dist/
pnpm dev # backend + web app together (prefixed logs, deps built once)
pnpm dev:server # backend at 127.0.0.1:7364
pnpm dev:web # web app (Vite) at 127.0.0.1:7365, /api proxied
pnpm dev:docs # docs site (Vite) at 127.0.0.1:7367
pnpm dev:landing # landing page (Vite) at 127.0.0.1:7366
BASE_PATH=/ pnpm build:site # assemble landing + docs exactly like the Pages deploy
Every dev command runs scripts/dev-prebuild.mjs first, which (behind a lock that
serializes concurrent invocations) keeps pnpm install current automatically — a
fresh clone or a pulled lockfile change installs before starting, and an up-to-date tree
pays nothing (the lockfile hash is stamped) — then prebuilds the workspace deps (skills,
core) with back-to-back builds deduped: starting dev:server and dev:web at the same
time (or just pnpm dev) installs and builds exactly once. dev:docs / dev:landing
run the install check only (--install-only).
Copy .env.example to .env for model credentials in development.
Repo layout
A pnpm monorepo (TypeScript, Node >= 24). One install ships four layers that share a
single data directory (~/.penguin/data) and a single message protocol (OmniMessage):
| Package | Name | Role |
|---|---|---|
packages/core |
@prismshadow/penguin-core |
SDK & engine: ReAct loop, OmniMessage protocol, LLM/Environment interface contracts, Agent State, Trace |
packages/cli |
@prismshadow/penguin-cli |
The penguin command: REPL, one-shot runs, model & vault config, service launcher |
packages/server |
@prismshadow/penguin-server |
Web backend: HTTP API + SSE streaming, multi-user auth, Project authorization, usage stats |
packages/web |
@prismshadow/penguin-web |
Web App: multi-session chat, Agent/skill/model management, Trace observability, evaluation center |
packages/skills |
@prismshadow/penguin-skills |
Built-in skill library (agent creation, benchmarking, evaluation, optimization, …) |
packages/landing |
— | Product landing page (this repo's website) |
packages/docs |
— | Documentation site (bilingual, deployed under /docs/) |
Responsibilities split by source of truth: the SDK owns protocol and execution
(message parsing, the agent loop, tools), the Server owns the multi-user runtime
(auth, SSE streaming, scheduled tasks), and the file layer under ~/.penguin/data
owns everything editable and recorded (prompts, Skills, secrets, Traces). The full map
is in Architecture → Division of responsibilities.
Quality gates
CI runs all of these on every PR — run them locally before pushing:
pnpm format:check # prettier
pnpm typecheck
pnpm test # unit suites for every package
End-to-end suites (optional locally, slower):
npx playwright install chromium # once
pnpm --filter @prismshadow/penguin-web test:e2e # browser e2e against a mock LLM
pnpm test:e2e # core live-model e2e, needs DEEPSEEK_API_KEY
Working rules
- English is the repository's working language — code, comments, error/log messages,
test names and fixtures, package metadata, and developer docs. Chinese appears only
where it is the content itself: zh i18n catalogs and fields (
strings.tsdictionaries, CLIi18n.ts,titleZh,short_description_zh),*.zh.mddocuments, and test literals that assert zh i18n output or exercise CJK-specific behavior. - Every change ships with a changelog entry: add
changelog/<version>/YYYY-MM-DD-<semantic-id>.mdunder the next unreleased version (released versions' folders are frozen) — an H1 title, a one-sentence summary paragraph, then details — and add a one-line link for it to that version's index,changelog/<version>/README.md. The layout is documented inchangelog/README.md. Related changes may share one entry file (extending its details) instead of opening a new file per small change. - README assets under
assets/readme/are generated — the benchmark charts from the landing benchmark data, and the demo screenshots vianode packages/landing/scripts/capture-readme-demo.mjs(build first; needs Playwright chromium). Regenerate rather than hand-editing.
Pull requests
- Branch from
main; keep PRs focused on one topic. - Make sure CI is green (build, format, typecheck, tests) and describe user-visible changes in the PR body.
- New user-facing behavior should come with tests, and with docs updates when it changes documented behavior (README, docs site).