Usage Cookbook
This cookbook turns the higher-level AgentHub docs into task recipes. Use it when you know what you want to do and need the shortest safe path through Desktop, Local Edge, Hub, Web, runtime adapters, or public release work.
Current scope
The recipes below are public-safe operating patterns. Local Desktop + Local Edge + mock runtime is preview-ready. Hub-backed Web, Feishu/Lark, Remote/Cloud Edge, and stable third-party adapter packaging remain in progress or in development unless the owning repository has newer release evidence.
Recipe Map
| Goal | Start here | Required surfaces | Status |
|---|---|---|---|
| Verify a workstation | Installation | Git, Go, Node.js, pnpm, mock runtime | Current |
| Run a read-only agent task | Quickstart | Desktop, Local Edge, mock or real runtime | Preview-ready |
| Produce a reviewable diff | Desktop Guide | Desktop, Local Edge, diff/artifact panel, approval policy | Preview-ready |
| Compare runtime adapters | Agent Profiles | Mock, Claude Code, Codex, OpenCode profiles | Contract shaped |
| Triage a failed run | Troubleshooting | Edge health, run events, runtime status, error code | Current |
| Prepare a team-visible task | Hub And Edge | Hub session, project, target Edge, audit | In progress |
| Plan Feishu/Lark entry | Feishu/Lark Integration | Integration Gateway, TokenDance ID binding, Hub task | In development |
| Publish docs/site changes | Release Checklist | build, test, lint, sitemap, llms, visual QA | Current |
Local Read-Only Review
Use this recipe for the first successful task on a new machine or with a new runtime profile.
- Start Local Edge with the mock runtime on loopback.
- Start Desktop and connect it to the same Local Edge URL.
- Select an allowlisted workspace.
- Ask for a read-only review, for example:
Review the README and suggest the smallest documentation improvement.
Expected evidence:
| Evidence | Healthy shape |
|---|---|
| Edge health | process is reachable and runtime inventory includes the mock runtime |
| Desktop connection | Local Edge appears online and the selected workspace is allowed |
| Event stream | run.started, run.message.delta, run.artifact.ready, run.completed appear in order |
| Transcript | user prompt and agent output render without overflow |
| Safety | no file write happens without explicit approval |
Public screenshots should replace private absolute paths with short placeholders such as workspace/app.
Reviewable Diff
Use this recipe when an agent should propose changes but a human should decide whether they are applied.
- Start from a clean or intentionally reviewed Git state.
- Run a focused task that names the target files or behavior.
- Keep writes in proposal mode until the diff panel has rendered.
- Review the changed files, generated artifacts, and event timeline.
- Approve apply, commit, or publish only as separate actions.
The UI should make the boundary visible:
| Step | Owner | UI expectation |
|---|---|---|
| Runtime output | Runtime adapter | normalized message, tool, and file events |
| File change detection | Edge | relative paths and diff metadata |
| Review | Desktop/Web | read-only diff until approved |
| Apply | Edge + user approval | explicit approval id and final result event |
| Audit | Hub when routed through Hub | actor, project, run id, action, result, request id |
Do not treat a completed model response as an applied change. Completion means the run reached a terminal state; the repository is still governed by diff review, approvals, commits, and CI.
Runtime Adapter Comparison
Use this recipe when comparing Claude Code, Codex, OpenCode, or a custom adapter.
Keep the task, workspace, approval policy, and expected output the same:
Inspect the docs navigation and report one missing consistency check. Do not edit files.
Compare:
| Dimension | What to compare |
|---|---|
| Availability | installed or authenticated, ready, unavailable, or timeout |
| Event quality | message deltas, tool calls, file reads, errors, terminal state |
| Diff discipline | whether proposed changes are surfaced as reviewable diffs |
| Cancellation | whether canceling leaves a clear terminal event |
| Privacy | whether paths, prompts, and provider output can be redacted for public evidence |
Adapter examples in these docs are contract previews. Do not copy placeholder import paths into production code until the owning SDK or package is published and versioned.
Failed Run Triage
Use this recipe when a task fails or stalls.
- Record the run id and the last event type.
- Check Local Edge health and runtime inventory.
- Reproduce with the mock runtime.
- If the mock runtime passes, check the real runtime CLI install, login, quota, and adapter profile.
- If Hub/Web is involved, check Hub authorization and target Edge presence before changing the UI.
- If Feishu/Lark is involved, check gateway verification, idempotency, queue handoff, TokenDance ID binding, and Hub task creation.
First useful error codes:
| Code | First owner to inspect |
|---|---|
runtime_unavailable | runtime CLI and Edge adapter profile |
workspace_outside_allowlist | Edge workspace policy |
permission_denied | Hub permission or Edge approval policy |
unauthorized_target | Hub project or device target authorization |
target_offline | Hub target presence and Edge heartbeat |
schema_validation_failed | API or event schema and adapter normalization |
Public issues should include the route class, error code, request id or run id placeholder, and the last safe event type. Private logs, raw prompts, real file content, provider keys, and callback payloads belong in private operator evidence.
Team Task Preparation
Use this recipe before moving a local-only run into a team-visible workflow.
Minimum readiness checklist:
- TokenDance ID login and Hub product session are distinct and both understood.
- Project membership and target Edge authorization are checked before queueing work.
- The task references a project or workspace target by id, not by private absolute path.
- Reviewable diffs and artifacts are available before apply or publish.
- Audit records denied actions as well as successful actions.
- Web renders Hub-owned state and does not directly access Local Edge or local files.
If any item is missing, keep the task in local preview or controlled integration testing rather than calling it generally available.
Feishu/Lark Task Preparation
Use this recipe for bot messages, card actions, and H5/workbench entry planning.
The durable shape is:
- Integration Gateway verifies and decrypts the provider event.
- Gateway acknowledges quickly.
- Slow work moves to an async queue.
- TokenDance ID binding maps the Feishu/Lark actor to a product identity.
- Hub creates or updates an AgentHub task under product authorization.
- Progress returns through card, message, H5, or Web without leaking full workspace context.
Do not put verification tokens, app secrets, tenant tokens, full prompts, raw provider payloads, or absolute local paths into cards, frontend code, or public docs.
Docs And Site Release
Use this recipe when adding or changing public documentation.
Every new docs route needs:
| Surface | Required update |
|---|---|
| MDX | English and Chinese page under the same slug |
| Navigation | docs sidebar labels and prev/next order |
| TOC | English and Chinese headings |
| Metadata | localized title and description |
| Search | body text for English and Chinese search |
| Discovery | sitemap.xml and llms.txt |
| Reader map | README docs inventory and docs landing page |
| Verification | tests, build, lint, public-surface and i18n checks |
Public release notes should say what changed and how readers verify it. They should not include production web-root paths, SSH aliases, rollback commands, logs, or secrets.
Evidence Template
Use this template for a private PR, internal issue, or handoff note:
goal:
route_or_surface:
language:
theme:
viewport:
edge:
runtime:
run_id:
last_event:
artifact_or_diff:
checks:
result:
private_evidence_location:
Public docs should keep only redacted status and stable boundaries. The actual local path, raw logs, provider output, and deployment path should remain private.