Workflows

This page maps AgentHub concepts to the work people actually perform: local runs, team-visible reviews, Hub-backed collaboration, Feishu/Lark entry points, runtime adapter development, and release evidence.

Workflow Map

Workflow	Primary user	Required surfaces	Status
Local solo run	Individual developer	Desktop, Local Edge, one runtime adapter	Preview-ready
Reviewable diff	Developer and reviewer	Desktop, Local Edge, artifact/diff panel, approval state	Preview-ready
Team collaboration	Team member	Hub Server, Web, project/session/device state	In development
Remote routing	Team/operator	Hub Server, authorized Edge target, audit	In development
Feishu/Lark task	Team chat participant	Integration Gateway, Hub task, TokenDance ID binding	In development
Adapter development	Runtime integrator	Edge adapter contract, events, validation	Contract shaped
Public release	Maintainer	docs, sitemap, llms.txt, visual QA, governance checks	Current

Local Solo Run

Use this when a developer wants AgentHub Desktop to run a local coding agent against a local workspace.

1. Start Local Edge on loopback with the mock runtime.
2. Start Desktop and connect it to the Local Edge URL.
3. Select an allowlisted workspace.
4. Run a read-only task before testing writes.
5. Confirm transcript, events, diff/artifact, and final state render correctly.

Expected evidence:

Evidence	What to record
Edge health	loopback URL, health result, runtime preset
Desktop connection	UI URL, selected Edge URL, connected state
Workspace	allowlist status, not the private path in public screenshots
Run	run id, agent id, terminal status, artifact presence
Safety	writes blocked or approval shown before mutation

If the mock runtime works but Claude Code, Codex, or OpenCode fails, debug the local CLI first. Do not move provider credentials into frontend code, public docs, screenshots, or browser storage.

Reviewable Diff

Use this when the output must be inspected before it changes a repository or when another person needs to review the result.

The user-visible sequence should be:

1. User starts a run with an explicit workspace and task.
2. Runtime adapter streams progress events.
3. Edge extracts file changes and produces a diff artifact.
4. Desktop/Web shows the diff as reviewable state, not as a completed fact.
5. A write, apply, commit, or publish step requires explicit approval.

The important product boundary is that AgentHub should make the work observable and reviewable. The runtime still performs the actual agent work, and the repository remains the source of truth for code history.

Team Collaboration

Use this when a run should be visible to a team or across multiple devices.

Hub Server becomes required when you need:

• TokenDance ID authenticated users;
• project and member visibility;
• session and message history;
• device or Edge routing targets;
• audit events for approvals, failures, and sensitive actions.

Web is Hub-backed. It should not directly call Local Edge, read local files, or start local CLI processes. Desktop can connect to Local Edge for local execution; Web should go through Hub and authorized targets.

Remote Routing

Remote/Cloud Edge is still in development. Public docs should describe the intended boundary without claiming general availability.

Before a remote run can be considered release-ready, the implementation needs evidence for:

Requirement	Why it matters
Target authorization	Hub must decide whether the user/session may use that Edge
Device identity	Hub must know which Edge is online and trusted enough for the task
Workspace policy	Edge must enforce allowlists and local policy before file access
Audit trail	approvals, denials, routing decisions, and failures must be traceable
Degraded states	offline Edge, stale device, denied workspace, and runtime unavailable need stable errors

Feishu/Lark Task

Feishu/Lark is a collaboration entry, not AgentHub login.

The expected flow is:

1. A message or card action reaches the Integration Gateway.
2. The Gateway verifies the Feishu/Lark event and acknowledges quickly.
3. Slow AgentHub work is queued asynchronously.
4. The Gateway resolves the Feishu user to a TokenDance ID binding.
5. Hub Server creates or updates an AgentHub task under product-local authorization.
6. Progress is reflected back through a card, message, H5/workbench view, or Web session.

Keep verification tokens, app secrets, encrypt keys, tenant tokens, and OAuth refresh tokens server-side or inside TokenDance ID. Do not store them in Desktop/Web clients.

Adapter Development

Use this when integrating a new runtime or improving Claude Code, Codex, OpenCode, or a custom agent adapter.

An adapter should produce stable AgentHub events for:

• run started, completed, failed, cancelled;
• model text and message deltas;
• tool calls and tool results;
• file changes, diffs, artifacts, and previews;
• permission or user-input requests;
• runtime unavailable, timeout, and schema validation failure.

The adapter contract is shaped, but public SDK package names and import paths should remain conservative until they are published and versioned.

Public Release

Use this when changing the product site, docs, SEO files, public screenshots, or release claims.

Minimum release evidence:

Gate	Required evidence
Docs parity	zh/en pages and navigation cover the same claims
Discovery	robots.txt, sitemap.xml, and llms.txt include changed routes
Search	docs search index includes new pages and important terms
Security	no secrets, private paths, rollback commands, or real tokens in public files
Visual QA	desktop and mobile pages show no overflow or obsolete visual language
Governance	workspace root public surface, i18n, design, freshness, and governance checks pass or warn only on accepted debt

Status Language

Use these words consistently:

Status	Meaning
Live	public page or endpoint is deployed and smoke-tested
Preview-ready	local or public preview path exists and can be verified
Contract shaped	interface direction is documented, but public SDK stability is not promised
In progress	implementation exists but is not release-ready
In development	planned or actively being built; do not present as generally available

Edit this page on GitHub