菜单
Run `harbor validate` + `make preflight` + the per-phase smoke gates before shipping an agent. Use when packaging an agent for a non-dev environment — production deploy, share with a teammate, hand off to CI, or ship a release tag.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Attach Harbor's native terminal Runtime test/control client with authenticated REST/SSE. Use when testing sessions, tasks, tools, artifacts, events, posture, interventions, controls, reconnect, or transcript export without opening the Console.
Use the Console's Playground page to chat against your agent, attach files (images / PDFs / audio), and steer or queue input during a run. Use when validating the agent end-to-end interactively, the foreground/background task posture, image-vs-PDF MIME dispatch, and the playground's steering UI.
Tour the Console's observability pages — Overview, Live Runtime, Sessions, Tasks, Agents, Tools, Events, Background Jobs, Playground, Flows, Memory, MCP Connections, Artifacts, Settings. Use when debugging an agent's behavior, hunting a regression, or building intuition for what the runtime is actually doing under the hood.
Build a chat UI (or any other client) against the Harbor Protocol directly — auth headers, the typed wire surface, events.subscribe SSE, the topology_snapshot capability, artifact upload. Use when shipping a frontend that talks to the runtime WITHOUT the bundled Console — a custom chatbot, a Slack bot, a TUI, an IDE plugin.
Get a real, verifiable JWT into a client and attach it to a production `harbor serve` — OIDC app registration, the (tenant, user, session) + scopes claim shape, the iss/aud exact-match contract, and the no-IdP `harbor token` self-issuing on-ramp. Use when moving off `harbor dev`'s ephemeral token to a production deployment, wiring an IdP (Auth0 / Okta / Keycloak / Cognito), or standing up your own issuer.
Use `harbor dev` + `harbor console` to run an agent locally with the Console attached. Use when iterating on a Harbor project — single-process or multi-process attach posture, the `HARBOR_DEV_TOKEN` handshake, hot reload on yaml changes, and which posture to pick when.
| name | validate-and-package |
| description | Run `harbor validate` + `make preflight` + the per-phase smoke gates before shipping an agent. Use when packaging an agent for a non-dev environment — production deploy, share with a teammate, hand off to CI, or ship a release tag. |
| license | Apache-2.0 |
| metadata | {"framework":"harbor","surface":"cli","verbs":"validate"} |
Before an agent leaves your dev workstation — to staging, to production, to a teammate's laptop, to a release tag — it goes through three gates: yaml validation, the preflight gate (the same one Harbor's pre-commit hook + CI both enforce), and one or more smoke checks against the running build. This skill is the canonical ordering and what to look for at each step.
harbor validate — yaml firstharbor validate ./harbor.yaml
This is the cheapest gate. It runs the config loader against your yaml and reports every issue with file:line precision:
llm.driver, llm.provider, identity.issuer, etc.).memory.budget_tokens: "8000" instead of int).memory.strategy: "summary" not in none|truncation|rolling_summary).governance.identity_tiers.free.budget_ceiling_usd: -1).memory.driver: sqlite without memory.dsn).llm.provider: nim without a matching custom_providers: entry).Run after every yaml edit. Failure modes are usually obvious from the message.
Expected output on success:
./harbor.yaml: ok
make preflight — the live gatemake preflight
This is the same gate the pre-commit hook and CI both enforce. It:
./bin/harbor (CGO_ENABLED=0, single static binary)../bin/harbor dev on 127.0.0.1:18080 with a temp data dir./healthz to return 200.scripts/smoke/phase-NN.sh in parallel batches (per the PREFLIGHT_REQUIRES: header — live-server smokes against the running build, static-only smokes locally, unit-tests invokes go test).What "preflight passes" means: every phase's surface that exists in your build works end-to-end against a live server.
If a surface doesn't yet exist in your build (e.g. a future phase), the smoke script auto-skips (404/405/501 → SKIP). The gate counts SKIP separately from FAIL — SKIPs are fine on master.
Run a single phase's smoke in isolation:
HARBOR_BASE_URL=http://127.0.0.1:18080 \
HARBOR_DEV_TOKEN="$(cat /tmp/harbor-dev-token)" \
scripts/smoke/phase-72b.sh
Useful when you've narrowed a failing surface and want a fast iteration loop without re-running the full preflight (which takes ~2 minutes).
The smoke scripts use scripts/smoke/common.sh's vocabulary:
assert_status <expected> <method> <path> — HTTP status check.skip_if_404 <method> <path> — graceful degradation when a phase isn't built yet.assert_json_path <jq-expr> <expected> — JSON body assertion.assert_json_truthy <jq-expr> — non-empty body assertion.protocol_call <method> <body> — JSON-RPC call against the Protocol surface.api_url <path> — base-URL composition.Don't roll new curl wrappers; reuse these. Forces consistency across phases.
Beyond the gates above, before deploying to a non-dev environment:
identity.issuer + jwks_url + audience — the placeholder values in the scaffold won't accept production tokens.env.NAME).state.driver: sqlite or postgres — NOT inmem (runs vanish on restart).memory.driver: sqlite or postgres — same logic.artifacts.driver: fs / sqlite / postgres — inmem artifacts vanish on restart.events.driver: sqlite or postgres — for durable event replay.governance.identity_tiers declared with real budget ceilings — declared tiers are enforced at the LLM edge (cost ceiling, rate limit, per-call MaxTokens; each rejection emits a governance.* event you can alert on).server.allowed_origins lists every Console host that will attach.server.bind_addr set (default 127.0.0.1:8080 only listens loopback).telemetry.log_format: json (default) — for log aggregator ingestion.telemetry.log_level: info (NOT debug — debug leaks prompt/completion content).The scaffold drops AGENTS.md and CLAUDE.md as verbatim mirrors. Edit one, copy to the other:
cp AGENTS.md CLAUDE.md # or vice versa
diff -q AGENTS.md CLAUDE.md # expected: no output
If your project has the equivalent of Harbor's make check-mirror, run it. CI will fail if they drift.
When you're ready to tag a release:
git tag -a v1.0.0 -m "v1.0.0: <one-line summary>"
git push --tags
If you have a release workflow (Harbor's repo does — .github/workflows/release.yaml), the annotated tag triggers a build of the static binary + a checksum + a GitHub Release with the binary attached.
The release notes should reference the agent's CHANGELOG (the user-facing one, not internal phase numbering — see Harbor's scripts/smoke/phase-82.sh rule).
make preflight fails on a phase you didn't touch. Almost always either (a) stale build (make clean && make build), (b) a port conflict on :18080 (kill the stray harbor dev), or (c) a SQLite WAL trap from a memory/state DSN inside the project dir.harbor validate passes but harbor dev exits at boot. The validator catches yaml-shape errors; it does NOT catch runtime errors like missing env vars (ErrMissingAPIKey) or unreachable JWKS URLs. Boot once after validating.skip_if_404 is firing because the endpoint returned 404. The endpoint is registered wrong, OR the build is stale.curl <jwks_url> from the deployment host.scaffold-a-harbor-agent — the start of the flow.define-the-agent-yaml — every field validated by harbor validate.run-the-dev-loop — the dev posture; preflight uses the same boot path..github/workflows/ci.yml — the CI gates a real PR runs through.