AgentHub
文档

贡献指南

AgentHub 迭代很快，所以贡献不仅要看代码质量，也要守住产品边界。本页说明如何选择工作、提交什么证据，以及如何避免把开发中的产品想法写成公开上线承诺。

选择合适的工作流

工作流适合的第一步先读
Docs 和公开站点修正过期口径、补路由证据、完善截图、更新 llms.txt产品状态、发布检查、部署
Desktop UI调整布局、状态、图标、主题/语言行为、视觉 QADesktop 使用手册、Desktop UI 参考、设计系统
Runtime adapter规范 event、失败态、approval gate 与 artifact metadataAgent Profile、Run 生命周期、适配器契约
Hub/Web完善 Hub-backed review surface、session state、project routing、audit viewHub 与 Edge、Web 工作台、团队协作
飞书/Lark卡片、事件入口、异步队列、TokenDance ID 绑定飞书/Lark 集成、安全边界
安全/隐私清理 secret 漂移、澄清凭据、脱敏证据安全边界、数据与隐私

如果功能跨多个产品，先查 TokenDance workspace 治理文档，再开大范围改动。产品页面要和跨仓库设计、身份、i18n、公开入口规则保持一致。

本地开发循环

AgentHub Home：

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

AgentHub 产品仓库按该仓库 README 和 AGENTS 指令执行。测试真实 Claude Code、Codex 或 OpenCode runtime 前，先用 mock runtime 跑通。

文档改动

每个新增 docs route 都需要：

  • 英文和中文 MDX 页面，slug 保持一致。
  • 在 src/lib/docs-data.ts 注册导航。
  • 在 src/app/[lang]/docs/[slug]/page.tsx 添加 docMetadata。
  • 在 src/lib/search-index.ts 添加搜索正文。
  • 在 public/sitemap.xml 添加双语 URL。
  • 在 public/llms.txt 添加链接和当前状态说明。
  • 更新 README route inventory 和 changelog。
  • 重要公开承诺页面需要测试或 visual QA route 覆盖。

实现尚未通用可用时，使用“开发中”、“可预览”或“契约已定”。不要把 roadmap 工作改写成已完成产品行为。

UI 改动

UI 工作遵守共享 TokenDance 设计契约：

  • 主品牌色使用 TokenDance Blue #0071BC。
  • 保持 light-first、紧凑、工具型界面。
  • 避免旧紫色渐变、无关彩色条、过重 hover 阴影和死黑 footer。
  • 通用 UI 用 lucide 图标；AI/runtime 品牌图标优先用 LobeHub icons。
  • 校验 Desktop mock 的主题、语言、hover、selected state 和 reduced-motion 行为。
  • 可见 UI 改动通过 pnpm visual:qa 留存桌面和移动截图。

Runtime 和 API 改动

Runtime 和 API 工作应保持 event 与 approval 语义：

  • 发送可版本化的 event，包含稳定 id 且不含 secret。
  • Artifact 和 diff 使用相对路径。
  • 区分 runtime unavailable、permission denied、timeout、schema validation、approval rejection 与 target offline。
  • Web 保持 Hub-backed，不能直接访问 Local Edge 或本地文件。
  • 保持 TokenDance ID session、TokenDance API key 与 provider credential 相互独立。

PR 证据

提交最小但完整的证据：

改动证据
Docs routepnpm test、pnpm build、渲染路由、sitemap/llms 检查
公开 UIpnpm lint、pnpm test、pnpm build、pnpm visual:qa、桌面/移动截图
Runtime adapterfocused unit/integration 输出、脱敏 event sample、失败态证据
Hub/Webauth/session 证据、route permission 证据、degraded-state 证据
飞书/Larkchallenge/signature 处理、3 秒卡片响应、异步队列证据、绑定失败 UX

Review Checklist

请求 review 前：

  • 改动文件对应一个清晰工作流。
  • 产品状态口径保守，并与产品状态页一致。
  • 公开文档不含私有路径、secret、provider key、原始日志或真实用户数据。
  • zh/en 公开承诺语义一致。
  • 新路由进入 navigation、search、sitemap、llms.txt 和 README inventory。
  • 视觉改动有 pnpm visual:qa artifact 路径。
  • 开发中能力如实标注。

相关页面