Initialize repository with harness code and assets

Initial import of all source code, config, and README assets: the packages workspace (cli, core, server, web, docs, landing, skills), build scripts, tooling config, and CI workflows. Includes the data-layout revision made on this branch: the local data root defaults to ~/.penguin/data (PENGUIN_HOME still overrides; the installer keeps its binaries in ~/.penguin), and every Agent lives under <project>/agents/<agent>/ — path helpers, the three agent-enumeration scans, the system prompt, built-in Skills, tests and docs all follow the new layout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ihk8iQuo3kv2aPjAYEPuR
2026-07-19 14:06:53 +08:00
parent 056bed7aeb
commit 45bfae6e94
543 changed files with 92949 additions and 0 deletions
@@ -0,0 +1,76 @@
+---
+title: Quickstart
+description: Install PenguinHarness, configure a model, and run your first Task.
+---
+
+## Install
+
+One-liner for Linux / macOS:
+
+```bash
+curl -fsSL https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.sh | sh
+```
+
+For other options (npm, from source), see [Installation](/installation).
+
+## Configure a model
+
+PenguinHarness ships with no built-in model credentials, so configure a model first. Use the Models page in the Web UI, or the CLI:
+
+```bash
+penguin config model add --model-id deepseek-v4-pro --api-key sk-... --set-default
+```
+
+- When `--provider` is omitted, the Provider is inferred from the built-in catalog.
+- The API key can also come from environment variables: when a model entry has no inline api_key, AgentHub (the LLM gateway library) reads variables such as `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. A `.env` file in the working directory is loaded automatically.
+
+## Start the Web App
+
+```bash
+penguin web
+```
+
+The service runs at http://127.0.0.1:7364 and opens your browser (`--no-open` to skip). First login is `admin` / `admin123` — change it right away. `penguin server` starts the same process headless.
+
+## One-shot run
+
+```bash
+penguin run -m "Create hello.txt containing Hello, Penguin"
+```
+
+The Workspace defaults to the current directory; pass `--workspace /path` to change it. The target directory must already exist.
+
+## Interactive chat
+
+```bash
+penguin chat
+```
+
+- Each input line starts a Task.
+- `/compact` compacts the context; `/exit` or `/quit` quits; Ctrl-C interrupts the running Task.
+- On exit it prints a `penguin chat --resume <sessionId>` hint for resuming this Session; `--resume` without an id resumes the Agent's latest Session.
+
+## SDK hello
+
+After installing `@prismshadow/penguin-core`:
+
+```ts
+import { createAgent, isCompleteModelMessage, userText } from "@prismshadow/penguin-core";
+
+const agent = await createAgent({ agentId: "default_agent" });
+const session = await agent.createSession({ workspaceDir: process.cwd() });
+
+for await (const output of session.run([userText("Create hello.txt containing hi")], {
+  approve: async () => "allow",
+})) {
+  if (isCompleteModelMessage(output) && output.payload.type === "text") {
+    console.log(output.payload.text);
+  }
+}
+```
+
+## Next steps
+
+- [Web App Guide](/web-app): use PenguinHarness from the browser.
+- [CLI Reference](/cli): the full list of commands and options.
+- [Architecture Overview](/architecture): how the pieces fit together.