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

Local Solo Run

Use this workflow 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 that transcript, events, diff/artifact, and final state render correctly.

Expected evidence:

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 workflow 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. A user starts a run with an explicit workspace and task.
2. The 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 workflow 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:

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 or Web clients.

Adapter Development

Use this workflow 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 workflow when changing the product site, docs, SEO files, public screenshots, or release claims.

Minimum release evidence:

Status Language

Use these words consistently: