Contributing

AgentHub is moving quickly, so contributions need to preserve product boundaries as much as code quality. This page explains how to choose work, what evidence to attach, and how to avoid turning in-development product ideas into public launch claims.

Choose The Right Workstream

Workstream	Good first scope	Read first
Docs and public site	Fix stale wording, add route evidence, improve screenshots, update `llms.txt`	Product Status, Release Checklist, Deployment
Desktop UI	Tighten layout, states, icons, theme/language behavior, visual QA	Desktop Guide, Desktop UI Reference, Design System
Runtime adapter	Normalize events, failure states, approval gates, and artifact metadata	Agent Profiles, Run Lifecycle, Adapter Contract
Hub/Web	Improve Hub-backed review surfaces, session state, project routing, audit views	Hub And Edge, Web Workbench, Collaboration
Feishu/Lark	Cards, event ingress, async queue, TokenDance ID binding	Feishu/Lark Integration, Security
Security/privacy	Remove secret drift, clarify credentials, redact evidence	Security, Data And Privacy

If a feature touches multiple products, check the TokenDance workspace governance docs before opening a broad change. Product pages should stay aligned with the cross-repo design, identity, i18n, and public-surface rules.

Local Development Loop

For AgentHub Home:

powershell

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm visual:qa

For the AgentHub product repository, follow that repository's README and AGENTS instructions. Use the mock runtime before testing a real Claude Code, Codex, or OpenCode runtime.

Documentation Changes

Every new docs route needs:

English and Chinese MDX pages with matching slugs.
Navigation registration in src/lib/docs-data.ts.
docMetadata entries in src/app/[lang]/docs/[slug]/page.tsx.
Search index body text in src/lib/search-index.ts.
public/sitemap.xml entries for both languages.
public/llms.txt links and current-status notes.
README route inventory and changelog notes.
Tests or visual QA route coverage when the page is important to public claims.

Use "in development", "preview", or "contract shaped" when the implementation is not generally available. Do not rewrite roadmap work as completed product behavior.

UI Changes

UI work should follow the shared TokenDance design contract:

Use TokenDance Blue #0071BC as the primary accent.
Keep surfaces light-first, compact, and tool-like.
Avoid old purple gradients, unrelated color bars, heavy hover shadows, and hard black footers.
Use lucide icons for generic UI and LobeHub icons for AI/runtime marks when available.
Verify Desktop mock theme, language, hover, selected states, and reduced-motion behavior.
Capture desktop and mobile screenshots through pnpm visual:qa when visible UI changes.

Runtime And API Changes

Runtime and API work should preserve event and approval semantics:

Emit versionable events with stable ids and no secrets.
Use relative paths for artifacts and diffs.
Distinguish between runtime unavailable, permission denied, timeout, schema validation, approval rejection, and target offline.
Keep Web Hub-backed; do not route Web directly to Local Edge or local files.
Keep TokenDance ID sessions separate from TokenDance API keys and provider credentials.

Pull Request Evidence

Attach the smallest complete evidence set:

Change	Evidence
Docs route	`pnpm test`, `pnpm build`, rendered route, sitemap/llms check
Public UI	`pnpm lint`, `pnpm test`, `pnpm build`, `pnpm visual:qa`, desktop/mobile screenshots
Runtime adapter	Focused unit/integration output, event samples with redacted payloads, failure-state proof
Hub/Web	Auth/session proof, route permission proof, degraded-state proof
Feishu/Lark	Challenge/signature handling, 3-second card acknowledgement, async queue proof, binding failure UX

Review Checklist

Before asking for review:

The changed files match one clear workstream.
Product status language is conservative and matches Product Status.
Public docs contain no private paths, secrets, provider keys, raw logs, or real user data.
zh/en public claims are semantically aligned.
New routes are present in navigation, search, sitemap, llms.txt, and README inventory.
Visual changes have artifact paths from pnpm visual:qa.
In-development features are labeled honestly.